Skip to main content
U.S. flag

An official website of the United States government

CMS Design System

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

Migrating to v2

The CMS Design System v2 release introduces several breaking changes, and this migration guide outlines high-level steps to upgrade. See the release notes for a detailed list of changes.

NPM packages

The core, support, layout npm packages have been deprecated and replaced with a new consolidated package @cmsgov/design-system. This is now the only dependency you need to use the design system and you can simply replace the old packages with @cmsgov/design-system in your package.json.

Old usage:

  "dependencies": {
    "@cmsgov/design-system-core": "^3.7.0",
    "@cmsgov/design-system-support": "^3.7.0",
    "@cmsgov/design-system-layout": "^3.7.0",
    ...
  }

New usage:

  "dependencies": {
    "@cmsgov/design-system": "^2.0.0",
    ...
  }

Child design system packages (formerly site packages)

Usage of child design system NPM packages have also been consolidated and simplified. Applications that use child design system packages only need one design system dependency going forward. The child design system packages will contain core styles, components, and assets in addition to child design system-specific customizations.

The 2 child design system packages are:

  • @cmsgov/ds-healthcare-gov
  • @cmsgov/medicare-site-package

Old usage:

  "dependencies": {
    "@cmsgov/design-system-core": "3.4.2",
    "@cmsgov/design-system-layout": "3.4.2",
    "@cmsgov/design-system-support": "3.4.2",
    "@cmsgov/ds-healthcare-gov": "3.0.1",
  }

New usage:

  "dependencies": {
    "@cmsgov/ds-healthcare-gov": "3.0.1",
    ...
  }

Folder structure

The dist folder structure has been updated for the @cmsgov/design-system npm package. We recommend only importing files from the dist directory moving forward.

└── @cmsgov/design-system/dist
    ├── components/
    │   └── index.js      Compiled JS (CommmonJS)
    ├── css/
    │   └── index.css     Compiled CSS
    ├── esnext/
    │   └── index.esm.js  Compiled JS (ES Module)
    ├── fonts/
    ├── images/
    └── scss/             Uncompiled CSS

Importing SCSS/CSS

If you were importing Sass directly from our packages’ src directories, we recommended updating your import paths to import from dist.

We previously did not distribute the Sass files in our packages’ dist directories, so you likely had an import path that looked like this:

@import "~@cmsgov/design-system-core/src/index";

In CMSDS v2, it will be changed to

@import "~@cmsgov/design-system/dist/scss/index";

Imports to @cmsgov/design-system-layout or @cmsgov/design-system-support are now included in the main scss entry point. If you would like to only import specific styles, see the @cmsgov/design-system README.md for more info on our SASS architecture.

See the theming page for more specific information on overriding the default Sass variables or CSS declarations.

Importing Javascript

V2 adds support for an ES module version of our JS, which can be found in the dist/esnext directory. Our package.json has been updated to use the modules property, which is used by bundlers like Webpack and Rollup to point to the ES module entry point when possible. For most users this won't require any change. See the documentation on importing React components for more information on importing Javascript and ES module support.

Your project also should not contain any src folder imports for React components. While JavaScript files were always available in the src directory before, it was never recommended to import the source version directly.

Fonts and Images

Fonts and images are now stored in @cmsgov/design-system/dist/fonts and @cmsgov/design-system/dist/images. Previously they were stored in @cmsgov/design-system/fonts and @cmsgov/design-system/images.

If you’re using a tool like webpack to collect the images and fonts during your app’s build process, you will need to update the appropriate path variables. A typical Sass import might have looked like this:

$font-path: "~@cmsgov/design-system-core/fonts";
$image-path: "~@cmsgov/design-system-core/images";

When migrating to v2, it will need to be changed to:

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

Focus styles

CMSDS focus styles will now be considered a draft feature, and will be turned off by default. Focus styles can be reenabled by setting the $ds-include-focus-styles build variable to true, but these styles will likely change in the future as we iterate on our design. See the theming page for more information on how to customize or enable focus styles.

Why the change?

When we first released focus styles in version 3.6.0, our goal was to provide a recommended focus style implementation that would incorporate accessibility and best practices, much of which was informed by UKgov's research and USWDS's focus state implementation. While we spent 4 months developing, iterating, and gathering feedback before the release, we made several mistakes in the process. Due to communication and process shortcomings, our team wasn't able to fully consider how our design would impact existing focus styles, or whether or not our design was too specific. Our team assumed that the SCSS variables we provided were sufficient to adapt the focus styles for different use cases and we neglected to add an easy way to opt-out of the new feature.

In this release, we worked to correct these mistakes by putting the new styles under a flag and turning them off by default. In the future, we plan on iterating on our default styles to be more generalized and more in line with existing focus styles on CMS products. We will also be adding additional mixins, variables, and documentation to make it easier for teams to customize focus styles.

A note on versioning

When we decided to publish our new NPM packages for this release, we chose to start at v2.0.0 even though our old NPM packages were at v3.7.0. The main reason for this is that our past v2 and v3 major releases didn't introduce breaking changes to our design system according to our SemVer guidelines. These releases were also not aligned with our product communication and marketing, and were limited to developer usage.

With this major release, we are correcting past inconsistencies and unifying our versioning across NPM packages, our Sketch library, and product communication. Because we still have the same Github repo and release notes, we will be adopting a new naming convention for our release tags going forward; the version number will be prefixed with core- (i.e. core-2.0.0).

This was a difficult decision to make, but we believe this will make things more consistent and simpler going forward.