Start by using existing Design System components and patterns. If a component or pattern does not meet your needs, follow the contribution process below.

If a required component or example does not exist in production, contact the Design System team. We will review the request together and determine next steps.

Book a design system drop-in hours session.

Be prepared to:

• Describe the component or pattern and its purpose
• Explain your user needs and service goals
• Share iterations explored with and without the Design System

A proposed component or pattern must meet the following criteria.

Useful

Evidence shows it supports multiple teams or services. Provide screenshots or links to demonstrate usage.

Unique

It does not duplicate an existing component or pattern. If replacing an existing component, provide evidence that the new approach improves usability or accessibility.

To be published, the solution must be:

Usable

Improves clarity, usability, and accessibility for users. Is informed by research and addresses a validated user need.

Universal

Inclusive and accessible. Meets or exceeds accessibility standards. WCAG 2.2 AA is the minimum requirement.

If approved, the item is added to the Design System's backlog.

When development begins, the Design System team will collaborate with you to confirm detailed requirements.

The Design System supports multiple development frameworks through Web Components. Contributing full components can be complex. Smaller contributions are encouraged.

• Bug fixes
• Documentation updates
• Enhancements to existing components

Start by contacting the team in the #design-system-support Slack channel.

Select an issue tagged ready-for-contribution from the backlog. Confirm which issue you will work on.

1. Clone the ui-components repository.
2. Open the repository in your IDE.
3. Create a branch named: contributions/story-number
4. Run the following commands:

   npm i
   npm run build

5. The playgrounds for local testing are located in:

   /apps/dev/angular
   /apps/dev/react

Angular

npm run dev:watch
npm run serve:dev:angular

React

npm run dev:watch
npm run serve:dev:react

React wrappers

/libs/react-components/src/lib

Each folder represents a single component with its associated unit tests and wrapper code.

Angular wrappers

/libs/angular-components/src/lib/components

Each folder represents a single component with its associated unit tests and wrapper code.

Web Components

/libs/web-components/src/components

• Unit tests as *.spec.ts
• Component code as *.ts

• Write all unit tests in Svelte.
• If updating React or Angular wrappers, write unit tests in those respective frameworks.
• Add browser testing using Jest for React wrappers and Svelte components when appropriate. These can be found in: libs/react-components/specs
• Manually test components in both React and Angular.
• Create test files that others can use to manually test the PR. These can be created in:

  /apps/prs/angular
  /apps/prs/react

• Follow the conventions already used in those files to create your test files.

A Design System developer will also manually test the pull request.

Use the following commit message format:

Bug fix

fix(#storyNumber): short description (7 words max)

Feature request

feat(#storyNumber): short description (7 words max)

• Create a pull request from your branch to the dev branch.
• Notify the design system team of the PR.