CONTRIBUTING.md

July 23, 2026 ยท View on GitHub

All contributions to this project will be released under the CC0 public domain dedication. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest. Details can be found in our TERMS and LICENSE.

There are two primary ways to help:

  • Using the issue tracker, and
  • Changing the codebase.

Using the issue tracker

Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution.

Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the Changing the codebase guidance below.

Changing the codebase

We work off feature branches from the main branch. After you've edited a component, open a Pull Request to merge your feature branch back into main.

For example, if you wanted to change some button code in @cfpb/cfpb-design-system and use it in consumerfinance.gov, here's what you'd do:

  1. git clone git@github.com:cfpb/design-system.git, if you haven't already.
  2. cd design-system
  3. git checkout main && git pull to ensure you're on the latest changes (this step is not necessary when cloning for the first time).
  4. yarn install to install dependencies and set up workspaces
  5. yarn after-install to copy assets and configure Ruby dependencies.
  6. git checkout -b button-fix to create a new branch for your changes.
  7. Edit file(s) in /packages/cfpb-design-system/src/components/cfpb-buttons however you want.
  8. Copy /packages/cfpb-design-system/ into node_modules/@cfpb/cfpb-design-system/ in your consumerfinance.gov or other repo.
  9. cd ~/wherever/consumerfinance.gov/ to navigate to another project where you'd like to test your buttons changes (in this case, consumerfinance.gov).
  10. yarn build in consumerfinance.gov to compile your stylesheets.
  11. Start consumerfinance.gov and navigate to a page with buttons to view your @cfpb/cfpb-design-system changes.
  12. When you're pleased with your changes, cd back to your design-system repo and commit your changes: git commit -am "Fix button border radius"
  13. git push origin button-fix to push your branch up to GitHub.
  14. Go to https://github.com/cfpb/design-system and open a pull request to merge button-fix into main.

If you are not a current contributor to this repository, use forks by first clicking the fork button on top of the repository and cloning your fork in step 1. In the final step, go to https://github.com/cfpb/design-system and file a pull request by clicking the link to compare changes across forks.

Updating Documentation

The Design System's website lives in this repository's docs/ directory and is powered by Decap CMS and Jekyll. To edit any page of the website, click the edit button at the bottom right of the page. You'll need to be added as a contributor to this repository in order to authenticate with Decap CMS.

Testing components locally

Automated tests

Automated tests can be run with the command yarn test:browser.

Browser support

Per the best practices published by browserslist, we use a 0.2% cutoff with this config for the browsers that get fed into our build systems.

What this means to the end-user is we've added a level of backward compatability for modern features as much as possible. This doesn't necessarily mean feature parity. Where it's impossible or impractical to implement a modern feature, we fallback to standard practices for that browser. For example, we do not deliver interactive scripting for Internet Explorer 8, but we do ensure that default browser features continue to work so users that can't or don't want to upgrade continue to have access to the site and our content.

Autoprefixer

Autoprefixer parses our CSS and adds vendor prefixes to rules where necessary using reported feature support by Can I Use. For more information visit the [Autoprefixer documentation site] (https://autoprefixer.github.io/).

Release management

Ready to publish changes to npm?

First, set some credentials:

  1. Create and export a personal access token called GITHUB_TOKEN.
  2. Confirm your environment has the above token properly defined and is not blank: echo $GITHUB_TOKEN.
  3. Create an npm account if you don't already have one and ensure you're listed as a "collaborator" on all our npm packages (e.g. cfpb-buttons).
  4. Check that you are logged in with npm whoami. If you aren't shown your username, run npm login.

Note: If you run into issues with your npm account not approving your MFA code, try resetting your npm password at npmjs.com.

Then, do a release:

  1. Ensure you're on the main branch with git checkout main and pull latest with git pull.
  2. Run yarn release
  3. Follow the prompts to decide what version (major, minor, or patch) you will be releasing.

Note: You can preview the generated changelog with yarn changelog.

Adhere to any linting errors or warnings

The yarn lint command can be used to lint the CSS and JS. Linting tasks that are set up within the pre-release processes are there to promote consistency.

Follow our CSS naming conventions

We are using the getBEM format:

.block-name
.block-name__element-name
.block-name--block-modifier

/* Modifiers on elements is discouraged, but they would look like */
.block-name__element-name--element-modifier

Avoid creating elements of modifiers

Appending an element name to a modifier class can result in a confusing class name like .list--space__item. Avoid this in favor of using a descendant, like this: .list--spaced .list__item.

Shoot for mobile first declarations

In most cases styles should be declared mobile first, then enhanced with media queries. By doing this we create a base experience that all devices can use and one that does not require media query support.

Adding and updating icons

Instructions for developers who've received a new or updated icon from a designer:

  1. Place SVG file (named with its canonical name, i.e., canonical.svg) in packages/cfpb-design-system/src/components/cfpb-icons/icons.

  2. If it has a -round or -square version, ensure those are in place as well.

  3. Run yarn process-icon-svgs from the root of the repository.

    • This script compresses and standardizes the SVG code for all of our icons.
    • It should be a no-op for icons that have not changed.

  4. From the repo root, copy the icons into the docs site with yarn copy-assets.

  5. If adding a new icon or updating any names, update the tables on both packages/cfpb-design-system/src/components/cfpb-icons/usage.md and docs/pages/iconography.md accordingly

  6. If any icons were deleted, be sure to delete them from both packages/cfpb-design-system/src/components/cfpb-icons/icons/ and docs/_includes/icons/

Adding and updating web component JSON design tokens

The web components in the design system use JSON format design tokens that get transformed by Style Dicitonary into css. These tokens are exported from Figma and then saved to the tokens directory in subfolders organized by their usage. Meaning, global tokens are in the packages/cfpb-design-system/src/tokens/abstracts directory and any component specific tokens are located in their own sub directories inside tokens (e.g. packages/cfpb-design-system/src/tokens/cfpb-button or similar).

Style dicitonary transforms any JSON token it finds in the tokens directory into css files and places them in a directory mirroring the structure it found in tokens to the src/elements directory as sub directories.

  1. To add or update a color token's value, find the relevant JSON token file and change the value or create a JSON token file in the appropriate location.
    • For example,if you wanted to change the value of "pacific" you would go to tokens/abstracts/custom-props.json find the "pacific" token and then change its $value: #newval.
    • If you wanted to add a color token file for cfpb-newcomponent, you would create tokens/cfpb-newcomponent directory and then add the JSON token file using the approriate JSON token form.
  2. Then either use yarn start to build the cobebase and view it in a browser or yarn tokens if you would like to simply create the .css.
  3. Then the rest of the steps outlined for changing the codebase apply.
    • Open a feature branch for your change
    • Commit the changes
    • yarn start to verify your changes in a browser (for developers or designers who can bulid the project)
    • Open a pull request and ask for a review

Our tokens have the following form

Example of a valid JSON token file structure for our project.

"beige": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [
        0.7450980544090271,
        0.6627451181411743,
        0.43529412150382996
      ],
      "alpha": 1,
      "hex": "#BEA96F"
    },
    "$extensions": {
      "com.figma.variableId": "VariableID:296:293",
      "com.figma.scopes": [
        "ALL_SCOPES"
      ],
      "com.figma.isOverride": true
    }
  },

Figma emits JSON color that adears to the w3c design token spec. Editors can supply only hex values, srgb int or srgb float while ignoring the Figma specifc metadata.

Storybook for Web Components

For detailed information about how this project uses Storybook for it's Web Components and advice on contributing new stories for our Web Components please see this document: STORYBOOK.md