USWDS Development Guide

Build accessible, mobile-friendly interfaces using USWDS v3 and @trussworks/react-uswds.

Quick Reference

• Components: See references/components.md for all 47 components with React imports and CSS classes
• Design Tokens: See references/design-tokens.md for colors, spacing, typography, and all token values
• Utilities: See references/utilities.md for all utility classes organized by category
• Grid & Layout: See references/grid-layout.md for the 12-column grid system
• Sass Theming: See references/sass-theming.md for customizing USWDS via settings variables

Core Architecture

USWDS has three layers:

1. Design Tokens — Named values for color, spacing, typography (never use raw hex/px)
2. Utilities — Single-property CSS classes (bg-primary, padding-2, font-sans-lg)
3. Components — Pre-built UI patterns (usa-alert, usa-card, usa-header)