Skip to main content

Design System

Getting started


The design system is available as NPM packages or via a .zip download.

The design system consists of two packages which are installed separately.

The core package includes the bulk of the design system:

  • Base styles
  • Utility classes
  • Sass/CSS and React components
  • Sass mixins and variables
  • Fonts and images
npm install --save @cmsgov/design-system-core

The layout package includes:

  • Responsive flexbox grid framework
npm install --save @cmsgov/design-system-layout

Fonts and images

Once you've downloaded the core package, copy the design system's fonts and images directories into the same directory as your site's CSS directory.

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

├── Your site's public assets directory/
    ├── css/
    ├── images/
    └── fonts/

You can manually copy these directories, or you could integrate this step into your build process. Here's an example of how this step could be accomplished using a Gulp task.

You can change the default paths by overriding the following Sass variables:

  • $font-path
  • $image-path


We offer two versions of design system assets: a minified + compiled version (located in a dist directory), and an un-minified + non-compiled version (located in a src directory). Use the minified version in production environments. Use the un-minified version in a development environment to debug in the browser, or if you'd like to manage the un-compiled files with your own build system.

Below are examples of the various ways you can reference the design system's styles and components:


Minified CSS

The easiest way to add the design system's styles to your site is by referencing its minified CSS.

  1. Copy the design system's dist/css folder 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.
  2. Add a <link> to the stylesheet in your site's <head>

For example:

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

View an example


If you're already using Sass to style your site, another way to include the design system's styles is by importing its un-minified Sass file.

  1. First, make sure your build system is configured so that the node_modules directory is in the list of Sass includePaths.
  2. Add the following to your Sass file:
@import '@cmsgov/design-system-core/src/index';

Learn how to override and theme Sass variables.

View an example

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.

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

Learn about the naming conventions

React components

The examples below assume you've installed the design system using NPM and have already setup your build system.

Default imports

Individual components can be imported from their individual export file.

import Button from '@cmsgov/design-system-core/dist/components/Button/Button';

Named imports

Components can also be imported using the shorter syntax below.

Performance note

This approach may result in a much larger file than you intend. Depending on what module bundler you use, all of the design system's React components may be included in the bundled file even if you didn't specifically import them. This can be avoided by enabling features like tree shaking in Webpack.

import { Button } from '@cmsgov/design-system-core';

View an example


Additional examples of the design system in use can be viewed on GitHub. These projects demonstrate the various ways you can incorporate the design system into your development process and various use cases.

Browse example projects

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.