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.

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

You're currently at the root of a monorepo containing multiple NPM packages located in the packages directory. 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.
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.

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.

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 :)

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

• 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.

• 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:docs && yarn build:docs

  • Builds the docs site statically

• yarn start

  • Starts local server running the documentation site
  • Regenerates documentation when files change
  • Before running start run the build command

• yarn storybook

  • Starts storybook for easier local development for the core package
  • yarn storybook:react starts Storybook with React instead of Preact

• yarn test

  • Alias of yarn test:unit

• yarn test:unit

  • Runs JS unit tests for all packages
  • yarn test:unit -u updates Jest snapshots

• yarn test:browser

  • Runs accessibility and visual-regression tests using Playwright. See Visual regression testing section below for details. This is the base command that defaults to the basic tests that cover Storybook stories, but we have several different kinds of browser tests under different sub-commands.
  • Note that this command will accept any arguments that Playwright accepts.
  • yarn test:browser -u updates reference screenshots used for visual regression testing. Update these only when we expect the visual changes. You can use this argument on any of the browser-test sub-commands to update snapshots for specific kinds of tests.
  • yarn test:browser --no-build will skip building the tests' pre-requisites. This is useful if you've already done it and haven't made any changes to the source.
  • yarn test:browser --grep "Alert" will only run tests with "Alert" in the name.
  • yarn test:browser:interaction runs VRT interaction tests to validate visual state of components after interaction.
  • yarn test:browser:examples runs VRT tests for our example projects.
  • yarn test:browser:storybook-docs checks for regressions in prop tables in storybook docs.
  • yarn test:browser:all runs all of our 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

  • Interactive script that bumps package versions, tags a release commit, drafts notes, and more. Read our release guide on Confluence for more info.

• yarn release:notes

  • Interactive script that generates draft release notes and associated ticket information from GitHub Milestones in the CMSDS public repository.

• yarn release:patch

  • Interactive script that collects the merge commits from pull requests associated with a given milestone and cherry-picks them onto the current branch (use with release branch)

We use Playwright to test our components for visual regressions. We have several suites of visual regression tests, but our main suite uses Storybook stories as references. These tests will load a story or other reference material, take a screenshot within a docker container (for consistency), and compare those screenshots with ones previously taken and committed to version control.

Tests can be run in a docker container or out, but we only check in VRT reference images taken inside the docker container, because taking them outside of a container will produce inconsistent results from machine to machine. The reason you might run them outside of docker is if you're working on the tests themselves and want to run in headful mode so you can see what's happening and troubleshoot Note that updating the visual regression test reference images locally requires that you be signed into Docker.

There are a lot of tests, so it can be helpful to constrain the tests you run locally by using Playwright's --grep argument.

1. Open the Docker app, and make sure you're signed in (Docker Desktop requires a license now).
2. Run yarn test:browser 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 test:browser -u, verify the changes, and then commit them.

• Run any of the browser-test sub-commands with the --no-docker flag, like yarn test:browser:examples --no-docker.
• If you've never installed Playwright, running the yarn test:browser command will prompt you to install it, which you will want to do. The reason we don't need it installed when running it in Docker is because the Docker image contains all of its own dependencies.
• Because snapshots will probably fail outside of the Docker container, pass --ignore-snapshots if you want to just see that the tests execute properly.
• You can turn off headless mode by using Playwright's --headed flag.
• Playwright's --debug flag is another helpful argument because it will pause and allow you to step through the tests.
• Don't forget that you can run a subset of tests by using Playwright's --grep argument.
• Remember that passing --no-build will skip re-building the source material like Storybook stories if you haven't made any changes to them and are only changing the tests themselves.
• Here's an example of a command you might run to debug the dropdown tests: yarn test:browser:interaction --no-docker --no-build --headed --debug --ignore-snapshots --grep "Dropdown"

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 of the design system in use can be found in the examples directory.

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

To get in touch with the CMS Design System team, please visit design.cms.gov/contact for a list of ways to contact us.

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.