CFPB Design System React

A React/Storybook implementation of CFPB's Design System.

Status

✨ Work in progress. Interfaces will change. Things will break.

Current components: https://cfpb.github.io/design-system-react

Installation

The @cfpb/design-system-react library is released as an NPM package.

To install the package and its peer dependencies:

yarn add @cfpb/design-system-react @cfpb/cfpb-design-system lit react react-dom react-router

lit is required because @cfpb/cfpb-design-system web components (for example <cfpb-tagline> in Banner) are built with Lit.

Usage

import { Alert, Button } from '@cfpb/design-system-react';
import type { ReactElement } from 'react';

export default function SomePage(): ReactElement {
  return (
    <main>
      <Alert message='2025-Q1 Quarterly filing period is open' type='success'>
        Submissions of 2025-Q1 SBL data will be accepted through May 2025.
      </Alert>
      <Button onClick={async () => login()} label='Log in' />
      <Button
        onClick={async () => register()}
        appearance='secondary'
        label='Register'
      />
    </main>
  );
}

Development

To edit components or add new ones, install dependencies and run Storybook:

1. Install Node v26+ (see .nvmrc).
2. Enable corepack: corepack enable.
3. yarn install
4. yarn start

This project uses Yarn 4 with the node-modules linker (see .yarnrc.yml).

Edit the files in src/components/ and your browser should hot reload your changes.

Add tests to files called <component-name>.test.tsx. See Buttons.test.tsx for an example.

Run yarn test to watch for changes and run tests automatically.

Github actions will build and deploy a preview of any pull requests you open.

Integrating changes to the CFPB Design System

After modifications made to the Design System have been released in the NPM package, we can integrate those changes by updating our dependencies.

1. Create a PR in DSR that updates the Design System library versions

git checkout main
git pull --rebase
git checkout -b update-cfpb-ds
yarn up @cfpb/cfpb-design-system
git add --all
git commit -m 'chore: Update CFPB DS to <new.version.number>'
git push

2. Review & merge the PR
3. Upon merge, updates will be auto-deployed to cfpb.github.io/design-system-react/

Open source licensing info

1. TERMS
2. LICENSE
3. CFPB Source Code Policy