Styling

Background

• Styling is written in Sass using the SCSS syntax

  • There are two syntaxes available for Sass. The first, known as SCSS (Sassy CSS) and used throughout this reference, is an extension of the syntax of CSS. This means that every valid CSS stylesheet is a valid SCSS file with the same meaning. In addition, SCSS understands most CSS hacks and vendor specific syntax, such as Internet Explorer's old filter syntax. This syntax is enhanced with the Sass features described below. Files using this syntax have the .scss extension.

• Styles reside in src/platform/site-wide/sass

• Frameworks and libraries include:

  • VA Design System

    • GitHub

  • U.S. Web Design System (USWDS) - v1.6

    • GitHub - uswds/uswds

  • Font Awesome

• Compiled to CSS using Webpack

Directory structure

• vets-website/src/platform/site-wide/sass/

  • Site wide style is defined in style.scss

    • Includes global imports such as our frameworks and libraries

  • Temporary styles lives in shame.scss

  • Other files at the root-level are considered page-specific

  • modules/

    • Contains site-wide styles for individual components that are generally reusable across the website.

Webpack/Compilation

• Sass is configured and compiled into CSS via Webpack. The configuration file is at vets-website/config/webpack.config.js.

• The website is split into a series of entry files, one of which is style.scss, while the rest are entry points for applications defined as JSX files.

• Site-wide style is compiled into build/BUILD_TYPE/generated/style.css, which is linked to in the header of the website and therefore available on all pages.

• An import statement within an entry file is used to include styles for that specific application. All application entry points are retrieved in the getEntryPoints function of the Webpack configuration. This ensures that your application's code and styles are not included in every page. The key you use to define your application's entry point in the manifest.json file will also be used as the file name for the generated JavaScript and CSS. Files in the content directory can then define an entryName property to link to those files.

Example Application

src/applications/my-application/manifest.json

{
  "appName": "My Application",
  "entryFile": "./my-application-entry.jsx",
  "entryName": "my-application-entry",
  "rootUrl": "/my-application"
}

src/applications/my-application/my-application-entry.jsx

// Our Webpack configuration will use the file extension to determine how to handle that import, which in our case is to compile it into a CSS file.
import './sass/my-application.scss';

Static Assets

The src/site/assets/ directory is used for storing images, fonts, and other files you may want to have reside outside of the Webpack build system. During build time, the contents of that directory will be moved as is to the build output, so src/site/assets/img/something.png will be moved to build/BUILD_TYPE/img/something.png, which means it can be linked to in the website with /img/something.png.

Roadmap Ahead

• Keep up-to-date with USWDS

  • What's New

• Reduce the shame file

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.