CMS Design System

Using SCSS

If your project is already using Sass/SCSS, you can include the design system's styles by importing precompiled SCSS files from NPM.

First, make sure your build system is configured so that the node_modules directory is in the list of Sass includePaths.
Add the following to your Sass file:

@import '@cmsgov/design-system/dist/scss/index';

Ensure fonts and images are rendered correctly.

Using CSS

If your project does not use Sass/SCSS, add the design system styles by referencing its minified CSS.

Copy the dist/css/index.css file into a relevant place in your code base — likely a directory where you keep third-party libraries. In the example below, our directory is css/vendor.
Add a <link> to the stylesheet in your site's <head>

For example:

<link rel="stylesheet" src="/css/vendor/design-system/index.css" />

Ensure fonts and images are rendered correctly.

Using fonts and images

By default, the design system expects a file structure like this:

└── Your site's build folder/
    ├── images/
    ├── fonts/
    └── css/
      └── index.css/

You can manually copy the image and font directories, or you could integrate this step into your build process.

Alternatively if your project uses Webpack or Create React App, you can configure the bundler to process the assets.

Overriding asset paths

If you are using Sass/SCSS, you can change the default asset paths by overriding the $font-path and $image-path Sass variables.

For example, if your project build directory file structure looked like this:

└── Your site's build folder/
    ├── images/
    ├── fonts/
    └── index.css

The asset paths would have to be redefined like so:

$font-path: './fonts';
$image-path: './image';

Without overriding these variables, it's possible that your fonts and images will not render correctly in your project.

Setting asset paths to node_modules

If your project uses Webpack or Create React App, you can set the asset paths directly to the fonts and image folders in your node_modules.

$font-path: '~@cmsgov/design-system/dist/fonts';
$image-path: '~@cmsgov/design-system/dist/images';

This approach is recommended, as you no longer have to copy assets into your project. It does however require some additional configuration.

For Create React App projects, simply add the following to your .env. This will allow Create React App's Webpack configuration to know to process the fonts and images in node_modules.

SASS_PATH="node_modules"

If you have your own custom Webpack configuration, you need to use file-loader and resolve-url-loader to copy assets into your build folder and inject the correct URLS to your build files.

Applying styles to your page

Once your page is loading the design system's CSS, you can then begin applying its styling to your pages. Below is an example of a project applying the base-level of styles and a utility class.

<html>
  <head>
    <link rel="stylesheet" src="/css/vendor/design-system/index.css" />
  </head>
  <body class="ds-base">
    <h1 class="ds-u-font-size--title">Hello world</h1>
  </body>
</html>

Learn about the naming conventions

Need help or ran into an issue?

If you're having trouble installing or setting up the design system, or if you think you've found a bug, feel free to open an issue on GitHub.