CMS Design System

The design system is a set of open source design and front-end development resources for creating Section 508 compliant, responsive, and consistent websites. It builds on the U.S. Web Design System and extends it to support additional CSS and React components, utility classes, and a grid framework to allow teams to quickly prototype and build accessible, responsive, production-ready websites.

Contents

• Packages
• Running locally
  • Getting started
  • Scripts
  • Visual regression testing
• Design assets
• Examples
• Contributing
• Contact

Packages

You're currently at the root of a monorepo containing multiple NPM packages located in the packages directory. Unless you're a contributor or a child design system maintainer, you can ignore the @cmsgov/design-system-scripts package, as it is contains tools for developers of the CMSDS. View the README.md in each of these for additional details.

Name	Description
CMS Design System	The core CSS, JS, and React components for the design system.
Design System Scripts	Scripts for compiling, testing, and linting design system assets. Also contains scripts for building and serving the documentation site. This is used internally by the core CMS design system team, but is made public for child design systems.
Healthcare.gov Design System	Design system used by application teams at healthcare.gov
Medicare.gov Design System	Design system used by application teams at medicare.gov
CMSDS Documentation	Gatsby based CMSDS Documentation site.

Running locally

This project uses Yarn for package management. Yarn helps to ensure everyone is using the same package versions. Install Yarn, if you don't have it yet.

Getting started

1. yarn install
   • This will also run Lerna bootstrap which allows us to have multiple packages within the same repo (a monorepo). Lerna installs all our dependencies and symlinks any cross-dependencies.
2. yarn start

Note: When you create a Git commit, any staged scripts will be automatically ran through ESLint and Prettier. If the linter catches an error, your commit will fail. This is a feature, not a bug :)

Scripts

These scripts can all be run from the root level of the repo:

• yarn start
  • Starts local server running the documentation site
  • Regenerates documentation when files change
• yarn build
  • Compile/transpile/uglify everything and makes things release-ready.
  • yarn build:healthcare to build the Healthcare.gov Design System
  • yarn build:medicare to build the Medicare.gov Design System
• yarn build-storybook:gatsby && yarn build:docs
  • Builds the docs site statically
• yarn storybook
  • Starts storybook for easier local development for the core package
  • yarn storybook:healthcare starts storybook for healthcare stories & styles
  • yarn storybook:medicare starts storybook for medicare stories & styles
• yarn test
  • Runs JS unit tests
  • Runs a11y accessibility tests against core storybook stories
• yarn test:unit
  • Runs JS unit tests for all packages
• yarn test:a11y
  • Runs accessibility tests for design-system package only
  • yarn test:a11y:healthcare to run the Healthcare.gov Design System's accessibility tests
  • yarn test:a11y:medicare to run the Medicare.gov Design System's accessibility tests
• yarn update-snapshots
  • Updates Jest snapshots
• yarn loki test
  • Runs visual regression tests using loki. See Visual regression testing section below for details.
  • yarn loki update updates reference screenshots used for visual regression testing. Update these only when we expect the visual changes
  • yarn loki:healthcare test to run the Healthcare.gov visual regression tests
  • yarn loki:medicare test to run the Medicare.gov visual regression tests
• yarn lint
  • Runs just the linting portion of the tests, eslint and stylelint
• yarn deploy-demo
  • Builds the doc site locally and deploys it to a branch-specific path on GitHub Pages. The terminal will display the URL where the demo was deployed to after it is done running.
• yarn release
  • Bumps package versions and tags a release commit. Read our Release Process guide for more info.

Visual regression testing

We use loki to test our components for visual regressions. It uses our existing Storybook stories, taking screenshots of them within a docker container and comparing those screenshots with ones previously taken and committed to version control.

Running loki tests locally requires that you be signed into Docker.

1. Open the Docker app, and make sure you're signed in (Docker Desktop requires a license now)
2. Run yarn loki test to begin comparing component images
   1. If differences are detected and unexpected, evaluate your changes - we only want to update and commit references when we expect the visual changes detected
   2. If differences are detected and expected, run yarn loki update

Visual regression troubleshooting

Error: ./loki.sh: line 70: kill: (74680) - No such process

If you run the visual regression command and receive ./loki.sh: line 70: kill: (74680) - No such process in your terminal, it may be related to your shell.

For MacOS users, run brew install bash to resolve this issue.

Design Assets

The CMS Design System provides a Sketch file and Sketch Library containing components, styles, and symbols. These are regularly updated alongside our code, and updates are automatically synced for designers using the Sketch Library.

Read more on using Sketch with the CMS Design System

Examples

Examples of the design system in use can be found in the examples directory.

Contributing

Please read the CONTRIBUTING.md document to learn about contributing to the design system, and our coding guidelines.

Contact

To contact the CMS Design System product owners, please email [email protected]

One of our goals is to ensure a welcoming environment for all contributors. Please take a look at our Code of Conduct to learn more.