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_modulesdirectory is in the list of Sass
- Add the following to your Sass file:
If your project does not use Sass/SCSS, add the design system styles by referencing its minified CSS.
- Copy the
dist/css/index.cssfile into a relevant place in your code base — likely a directory where you keep third-party libraries. In the example below, our directory is
- Add a
<link>to the stylesheet in your site's
<link rel="stylesheet" src="/css/vendor/design-system/index.css" />
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
$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
$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
If you have your own custom Webpack configuration, you need to use
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.