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.
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
node_modules
directory to be used directly by our other packages. This means that the ds-healthcare-gov
package always uses the most up-to-date version of our local design-system
package, and so on.yarn build
yarn build:{core,cmsgov,healthcare,medicare}
yarn build:docs
yarn serve:docs
yarn build:storybook
./storybook-static
yarn serve:storybook
yarn storybook
yarn build:examples
./examples
yarn serve:examples
yarn start
start
run the build
commandyarn storybook
yarn storybook:react
starts Storybook with React instead of Preactyarn test
yarn test:unit
yarn test:unit
yarn test:unit -u
updates Jest snapshotsyarn test:unit:preact
runs the unit tests in Preact modeyarn test:unit:wc
runs the unit tests for the web components, which have to run in Preact modeyarn test:browser
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
yarn type-check
yarn deploy-demo
yarn release
yarn release:notes
yarn release:patch
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.
yarn test:browser
to begin comparing component images
yarn test:browser -u
, verify the changes, and then commit them.--no-docker
flag, like yarn test:browser:examples --no-docker
.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.--ignore-snapshots
if you want to just see that the tests execute properly.--headed
flag.--debug
flag is another helpful argument because it will pause and allow you to step through the tests.--grep
argument.--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.yarn test:browser:interaction --no-docker --no-build --headed --debug --ignore-snapshots --grep "Dropdown"
The CMS Design System provides a Figma file and library containing components, styles, and design tokens. These assets are regularly updated alongside the codebase, and updates are automatically synced for designers using the Figma Library, across all CMS brands.
We use Figma's multi-mode variable system to define theme variants for each of our theme-level tokens. These theme-level tokens can be used in our shared design library. Tokens can be edited by developers comfortable with JSON, and by designers using Figma's variable tables. Changes to tokens can be synced both ways: from the code repository to Figma, and from Figma to the code repository.
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.