sbolel / CMSgov-design-system

Open source design and front-end development resources for creating Section 508 compliant, responsive, and consistent websites.

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

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.

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 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: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:unit:update updates Jest snapshots

• 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 test:browser

  • Runs visual regression tests using Playwright. See Visual regression testing section below for details.
  • Note that you need to build Storybook statically (yarn build:storybook) before you can run the tests
  • yarn test:browser:update updates reference screenshots used for visual regression testing. Update these only when we expect the visual changes
  • yarn test:browser --project <name> runs only one of the named projects found in playwright.config.ts
  • yarn test:browser:interaction runs VRT interaction tests to validate visual state of components after interaction.
  • yarn test:browser:all runs all VRT, static and interactive.

• 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 guide on Confluence for more info.

• yarn release:bump

  • Bumps package versions in a branch off of main and creates a pr for these bumps using gh. Read our release guide on Confluence for more info.

• yarn release:notes

  • Generates draft release notes and associated ticket information from GitHub Milestones in the CMSDS public repository.

Visual regression testing

We use Playwright 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. The tests assume that Storybook has been built to ./storybook-static using yarn build:storybook.

Running the browser tests locally requires that you be signed into Docker or have playwright installed locally.

If using Docker:

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

If running Locally:

Note that running without using the docker image will occasionally throw false positives, depending on your system configuration. It's recommended that you utilize Docker when running DS visual regression tests.

1. If you have run npx playwright install and installed the playwright dependencies locally you can run the tests using their yarn commands directly.
2. For example, to run the CMSDS VRT Tests for inteaction states: yarn playwright test --config tests/browser/interaction.config.ts
3. The -u flag can be added to the yarn playwright test command to update snapshots.

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