Skip to main content

U.S. flagU.S. flag

An official website of the United States government

CMS Design System

CMS Design System v2 is released!  See our migration guide.


How you implement the design system depends on the needs of your project and your workstyle. We highly recommend implementing the design system with npm, as it allows you to easily update the design system version, but we also provide a direct download if npm will not work for you or your project.

Install using npm

Simply add the @cmsgov/design-system package to your package.json to install it as a dependency.

npm install --save @cmsgov/design-system@latest

yarn add @cmsgov/design-system@latest

The @cmsgov/design-system package includes:

  • Pre-compiled SCSS files
  • Compiled CSS files
  • Compiled React components (CommonJS and ES modules)
  • Typescript definition files
  • Fonts and image

Package file structure

The dist folder contains all the necessary files in the design system, your project should not be importing anything from src.

└── dist
    ├── components/
    │   └── index.js        Compiled JS entry point (CommmonJS)
    ├── css/
    │   └── index.css       Compiled CSS entry point
    ├── esnext/
    │   └── index.esm.js    Compiled JS entry point (ES Module)
    ├── fonts/
    ├── images/
    ├── scss/
    │   ├── base/           Base styles, HTML element selectors
    │   ├── components/     Component styles
    │   ├── settings/       Variables, mixins, and functions
    │   ├── utilities/      Utility classes for individual CSS properties
    │   └── index.scss      Precompiled SCSS entry point
    └── types/              Typescript definition files

Download zip

Download the zip file from the latest release and extract the zip file to see the following folder structure. Like the npm package, the contents of download/design-system/dist contain design system code and assets.

└── download
    ├── design-assets/      Design system assets (Sketch files, fonts, designer assets)
    └── design-system/      Design system package (code, fonts, images)
        └── dist/

Copy the files and folders from download/design-system/dist to a relevant place in your project’s code base. Here is an example structure for how this might look:

    ├── assets/
    │   ├── ds-2.0.0/       Renamed design system package
    │   ├── stylesheets/
    │   ├── images/
    │   └── javascript/
    └── index.html

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.