DOCSEARCHbyAlgolia
Submit Docs

React USWDS Component Library

repository·main·Indexed 42 days ago

https://github.com/trussworks/react-uswds

A TypeScript-based React component library implementing the United States Web Design System (USWDS) 3.0 design patterns. Version 12.0.0 provides accessible, semantic UI components to reduce development overhead for projects following the USWDS standard.

Tokens
9.5K
Snippets
16
Records
40
Agent score
53%

What's inside React USWDS

  1. Version alignment between ReactUSWDS and USWDS

    main

    To avoid unexpected markup and CSS combinations, the version of uswds used in your application must align with the version of @trussworks/react-uswds you are using.

    ReactUSWDS tracks USWDS versioning types. When ReactUSWDS updates its underlying USWDS dependency, it follows the same release type (major, minor, or patch) as the USWDS release. This ensures that users can determine which version of ReactUSWDS includes specific USWDS features by looking at the USWDS release history.

  3. Release Automation Tools Overview

    main

    The React USWDS release pipeline relies on several integrated tools:

    • conventional-commits: Used to parse commit messages into a structured changelog. Merged Pull Requests are squashed into single commits to facilitate this.
    • release-please: Automates the creation of Release PRs. These PRs update the package.json version and the changelog. Merging a Release PR triggers the creation of a GitHub tag and release.
    • GitHub Actions:
      • release-please.yml: Manages the release-please workflow.
      • package-release.yml: Generates a clean, publishable .tgz build artifact for each release.
    • npm: The registry used to host and distribute the versioned build artifacts.

  4. Understand Happo visual regression testing

    main

    Happo is a visual regression testing platform integrated into the project. It automatically detects visual changes in components and design system elements by comparing screenshots of the current PR against the main branch in Storybook.

    Key Concepts:

    • Automatic Reports: When an engineer creates a PR, Happo generates a report integrated with GitHub.
    • Spurious Diffs: Occasionally, Happo may flag "spurious diffs"—false positives caused by minor rendering differences (like slight spacing shifts) that are not related to the actual code changes. If the before and after images look identical to the human eye, these can typically be ignored.

  5. How ReactUSWDS versioning relates to USWDS versioning

    main

    ReactUSWDS uses the release type of the underlying USWDS dependency to determine its own version increment. This provides a predictable mapping for developers:

    • Patch updates: USWDS 2.10.0 $\rightarrow$ 2.10.1 results in ReactUSWDS 1.0.0 $\rightarrow$ 1.0.1.
    • Minor updates: USWDS 2.10.1 $\rightarrow$ 2.11.0 results in ReactUSWDS 1.0.0 $\rightarrow$ 1.1.0.
    • Major updates: USWDS 2.11.0 $\rightarrow$ 3.0.0 results in ReactUSWDS 1.0.0 $\rightarrow$ 2.0.0.

  6. Design patterns for writing flexible components in react-uswds

    main

    To maintain consistency and flexibility in react-uswds, follow these guiding patterns:

    Props

    • Fundamental Props: Require props essential to the element (like id or name for inputs), but make all other props optional.
    • Avoid Boolean Traps: Do not use conflicting boolean props. If props are mutually exclusive, use an enum prop instead (e.g., see <Button />).
    • Extend HTML Attributes: Use spread attributes to allow consumers to pass standard HTML attributes, aria- values, and custom event handlers while maintaining TypeScript safety.
    interface FormProps {
  children: React.ReactNode;
  big: boolean;
}

export const Form = (
  props: FormProps & JSX.IntrinsicElements['form']
): React.ReactElement => {
  // implementation
}

    State

    • Organization: Group state declarations and hooks at the top of the component function.
    • Functional Updates: When using useState, prefer functional updates (e.g., using object spread syntax).
    • State vs. Props: Avoid putting business logic or implementation details in component state. If a piece of state is heavily used, consider if it should be managed by the consumer and passed in via props instead.

    Children

    • Use the children prop whenever main content is not highly structured or ordered.

    Subcomponents

    • Break large components into smaller concerns using subcomponents to leverage React composition.
    • Group subcomponents in a folder.
    • Use subcomponents when it becomes difficult to pass conditional props down a deep tree, or when a piece of the UI is generalizable enough to be reused independently.

  7. Node.js compatibility

    main
    The library is developed using the Node.js version specified in .node-version. It is tested against major released LTS (Long Term Support) versions of Node.js. Using pre-release or development versions of Node.js may result in unexpected issues.

  8. How to implement subcomponents in react-uswds

    main

    react-uswds components do not always map one-to-one to USWDS design system components. Instead, we use subcomponents to break down complex components (often referred to as 'organisms' in atomic design) into smaller, manageable pieces.

    When to use subcomponents:

    • When passing conditional props (like styles) through multiple levels of the HTML tree becomes difficult.
    • When a specific piece of the UI is general enough to be exported and used on its own.
    • When the USWDS component is highly complex.

    Implementation Pattern:

    • Group subcomponents together in a single folder.
    • Generally, do not write Storybook stories for subcomponents unless they are useful as standalone UI elements.
    • Examples of components that use this pattern include Header, Footer, and Card.

  10. Review a design PR for react-uswds

    main

    When reviewing Pull Requests (PRs) for react-uswds, follow these steps to ensure UI consistency and adherence to USWDS patterns:

    1. Understand the Context

    • Read the PR description to understand the changes and their expected impact on the UI.
    • Review the acceptance criteria in the associated Shortcut ticket.
    • Compare the changes against Figma designs (check provided links or find relevant screens manually).
    • Consider pairing with the engineer to discuss the implementation if needed.

    2. Review the Happo Report

    • Use the Happo report to verify that changes match expectations and that no unexpected visual regressions occurred.
    • If unsure about visual changes in Happo, consult the engineer.
    • Action Required: Click Accept in the dropdown in the left sidebar of the Happo report. Ideally, a designer should perform this action.

    3. Apply the Design Review Checklist

    • Use the design review checklist located in the PR description. Use your judgment to determine which steps are necessary for the specific change.

    4. Finalize the Review

    If the changes are correct:

    1. Ensure the Happo test is passing and approve the Happo report.
    2. Approve the PR in GitHub.

    If changes are required:

    1. Leave a comment on the GitHub PR explaining the necessary changes.
    2. To block the merge: Select the Request Changes option. The engineer must address the changes and re-request your review.
    3. To provide non-blocking feedback: Use the Comment option if the feedback is out of scope or you do not wish to block the branch.
    4. Reach out to the engineer directly to discuss the feedback.
    5. Repeat the process until the changes are satisfactory.

  11. Import USWDS styles into your React application

    main

    To ensure the USWDS components render correctly, you must import the necessary CSS files in the root of your React application.

    • If you do NOT have uswds as a dependency: Import both the USWDS base CSS and the library's index CSS.
    • If you ALREADY have uswds as a dependency: You only need to import the library's index CSS.
    // If you DON'T have 'uswds' installed:
import '@trussworks/react-uswds/lib/uswds.css';
import '@trussworks/react-uswds/lib/index.css';

// If you ALREADY have 'uswds' installed:
import '@trussworks/react-uswds/lib/index.css';