OMB M-23-22 requires federal agencies to adopt the U.S. Web Design System (USWDS) to ensure a consistent, accessible, and trustworthy digital experience for the public. USWDS design tokens — spacing, color, and typography — encode Section 508 color contrast ratios and responsive scale decisions that would otherwise require individual agencies to re-solve. Without USWDS tokens, agencies typically build custom styles that fail color contrast (WCAG 1.4.3), use non-standard spacing that breaks on mobile, or adopt inconsistent typography that erodes the visual coherence citizens expect from .gov sites.
Medium because non-adoption of USWDS design tokens violates OMB M-23-22 guidance and typically introduces color contrast, spacing, or typography choices that breach WCAG 2.2 and Section 508, creating both compliance and accessibility failures across all pages.
Install @uswds/uswds and import its settings and component CSS in your global stylesheet. Do not import USWDS only in devDependencies.
npm install @uswds/uswds
In your main stylesheet (e.g., app/globals.css or styles/global.scss):
// Import USWDS settings and all tokens
@forward 'uswds-settings'; // your overrides go here
@forward '@uswds/uswds';
Or with a direct CSS import:
@import '@uswds/uswds/css/uswds.css';
Then verify token adoption by confirming at least spacing utilities, the USWDS color palette, and the Public Sans font family are actively applied in layout and typography styles.
ID: gov-web-standards.uswds-alignment.design-tokens
Severity: medium
What to look for: Check for USWDS packages in dependencies (e.g., @uswds/uswds). List all CSS/SCSS files that import USWDS tokens or variables (e.g., @import '~uswds/src/settings/settings-general'). Examine stylesheets for use of USWDS spacing units (2px, 4px, 8px increments), color palette (Gray, Blue, Gold, Red, Green), or typography scales. Count every USWDS token import found across all stylesheets.
Pass criteria: USWDS is installed as a dependency, and the project imports and uses USWDS design tokens in at least 2 categories (spacing, color, typography) in stylesheets or CSS-in-JS configuration. Report the count of USWDS token categories adopted even on pass.
Fail criteria: USWDS is not installed, or is installed but not imported or used in styling. Having USWDS in devDependencies only without any actual imports does not count as pass.
Skip (N/A) when: The project has a documented exemption from USWDS (some agencies use alternative design systems with approval).
Cross-reference: For comprehensive design system evaluation including component consistency and token coverage, the Design System Consistency audit covers cross-component alignment.
Detail on fail: "@uswds/uswds is not in package.json" or "USWDS is installed but no imports found in stylesheets — tokens are not being used"
Remediation: Install USWDS and import design tokens in your main stylesheet:
npm install @uswds/uswds
Then in your main CSS file:
@import '~@uswds/uswds/src/settings/settings-general';
@import '~@uswds/uswds/src/all';