line47/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 Standards 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

You're currently at the root of a monorepo which contains multiple NPM packages located in packages directory. View the README.md in each of these for additional details.

Name	Description
Core	The core CSS and React components for the design system. Includes the Support package.
Layout	A responsive flexbox grid framework.
Support	Sass variables, mixins, and functions. Included in the Core package.

Internal packages

These packages are project dependencies, mostly focused around the design system's developer tooling and documentation.

Name	Description
Documentation site	This directory contains code related to the documentation website. Unless you're a contributor, this directory isn't that interesting to you.
ESLint config	The ESLint rules we use to lint the design system's JS and React components
Stylelint config	The Stylelint rules we use to lint the design system's Sass
Yeoman generator	A Yeoman generator used in the development process. Again, unless you're a contributor, this directory isn't that interesting to you.

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.

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 bump
  • Increments package versions. Read "Versioning" for more info.
• yarn generate
  • Generates the necessary files for a new core component
  • Alias: yarn g
• yarn test
  • Runs JS unit tests
  • Lints JS using ESLint
  • Lints Sass using stylelint
• yarn test:e2e
  • Runs end to end tests
• yarn test:e2e packages/core/Autocomplete
  • Runs a single end to end test, this example runs Autocomplete
• yarn test:watch
  • Runs JS unit tests and will continue to run tests as files change
• yarn update-snapshots
  • Updates Jest snapshots
• yarn lint
  • Runs just the linting portion of the tests

Theme scripts

You can also use the following scripts to build and preview a theme:

• yarn start:theme
• yarn build:theme

These scripts will also place the documentation into a docs subdirectory in your theme's directory.

If you have multiple directories inside of packages/themes, you can specify which theme to use by passing the scripts the name of the folder. For example: yarn start:theme my-theme-folder-name

If your documentation site will be uploaded to a subdirectory (ie. example.com/design-system), you can set its root path by passing the --root option. For example: yarn build:theme --root design-system

Visual regression testing

We're using backstopJS for visual regression testing. Here's how to run the tests.

• Install backstopJS yarn install
• Run the site locally yarn start
• In a new terminal window run the backstop tests backstop test
  • This will test the local CMSDS documentation site against the CMSDS production documentation site
• After the tests run an html report will open in your browser showing passed and failed tests

Note: Use backstop reference to create new reference files. This would need to be run when adding a new component.

Contact

To contact the CMS Design System product owners, please email WPMG_Web@cms.hhs.gov

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.