U.S. Web Design System

# U.S. Web Design System — Design Style Reference

> **Unofficial, community-authored reference.** Compiled by [designsystems.one](https://www.designsystems.one). Not affiliated with, endorsed by, or sponsored by U.S. Government. "U.S. Web Design System" and related marks belong to their respective owners. This document describes publicly observable style attributes in original words — it contains no copied documentation, logos, icon artwork, or original token files. Always defer to the official source for canonical, current values.

**System:** U.S. Web Design System
**Owner:** U.S. Government
**Official documentation:** https://designsystem.digital.gov/
**Visual character:** Federal dependable: Public Sans plainness, flag-adjacent blue and red used sparingly, engineered for every American on every device.

---

## Summary

Public-service design system for U.S. federal websites.

_Confidence: high. Values are drawn from well-documented public token references._

## Color tokens

| Color | Value | CSS variable | Role |
| --- | --- | --- | --- |
| Primary Blue | `#005ea2` | `--usa-primary` | Primary actions and links |
| Primary Dark | `#1a4480` | `--usa-primary-dark` | Hover states |
| Ink | `#1b1b1b` | `--usa-ink` | Primary text |
| Base | `#71767a` | `--usa-base` | Secondary text |
| White | `#ffffff` | `--usa-white` | Page background |
| Base Lightest | `#f0f0f0` | `--usa-base-lightest` | Subtle background |
| Secondary Red | `#d83933` | `--usa-secondary` | Errors and secondary emphasis |
| Green Success | `#00a91c` | `--usa-success` | Success |
| Gold Warning | `#ffbe2e` | `--usa-warning` | Warnings |

## Typography

- **Body:** Public Sans — weights 400, 700 — `'Public Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif`
- **Display:** Merriweather (serif option) — weights 400, 700 — `Merriweather, Georgia, serif`
- **Mono:** Roboto Mono — weights 400 — `'Roboto Mono', monospace`

## Type scale

| Step | Size | Line height |
| --- | --- | --- |
| 3xl | `48px` | `58px` |
| 2xl | `40px` | `48px` |
| xl | `32px` | `39px` |
| lg | `22px` | `29px` |
| body (sm) | `17px` | `26px` |

## Spacing

Base unit: `8px (units)`

Scale: `4px` · `8px` · `16px` · `24px` · `32px` · `40px` · `48px`

## Corner radius

| Name | Value |
| --- | --- |
| sm | `2px` |
| md | `4px` |
| lg | `8px` |
| pill | `99rem` |

## Elevation / shadows

| Name | Value |
| --- | --- |
| shadow-2 | `0 4px 8px 0 rgba(0,0,0,0.1)` |

## Quick start (CSS)

```css
/* U.S. Web Design System — illustrative tokens, restated as CSS custom properties.
   Unofficial reference by designsystems.one; values are indicative, not
   canonical. Official reference: https://designsystem.digital.gov/ */

:root {
  /* Color */
  --usa-primary: #005ea2; /* Primary actions and links */
  --usa-primary-dark: #1a4480; /* Hover states */
  --usa-ink: #1b1b1b; /* Primary text */
  --usa-base: #71767a; /* Secondary text */
  --usa-white: #ffffff; /* Page background */
  --usa-base-lightest: #f0f0f0; /* Subtle background */
  --usa-secondary: #d83933; /* Errors and secondary emphasis */
  --usa-success: #00a91c; /* Success */
  --usa-warning: #ffbe2e; /* Warnings */

  /* Typography */
  --font-body: 'Public Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
  --font-display: Merriweather, Georgia, serif;
  --font-mono: 'Roboto Mono', monospace;

  /* Type scale */
  --text-3xl: 48px /* line-height 58px */;
  --text-2xl: 40px /* line-height 48px */;
  --text-xl: 32px /* line-height 39px */;
  --text-lg: 22px /* line-height 29px */;
  --text-body-sm-: 17px /* line-height 26px */;

  /* Spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 16px;
  --space-4: 24px;
  --space-5: 32px;
  --space-6: 40px;
  --space-7: 48px;

  /* Radius */
  --radius-sm: 2px;
  --radius-md: 4px;
  --radius-lg: 8px;
  --radius-pill: 99rem;

  /* Elevation */
  --shadow-shadow-2: 0 4px 8px 0 rgba(0,0,0,0.1);
}
```

## Origin

USWDS launched in 2015 (under 18F and the U.S. Digital Service) to bring consistency, accessibility, and modern web standards to federal websites. v3 (2022+) modernized the architecture around design tokens and Sass utilities; major federal agencies use it directly.

## Governance

Maintained by GSA's Technology Transformation Services (TTS). Open source on GitHub, MIT-style license. Public Slack and bi-weekly office hours; agencies contribute through public PRs.

## Known for

- Accessibility — USWDS components meet Section 508 and WCAG 2.1 AA requirements as a baseline.
- Plain language writing guidance integrated with the component library.
- Form patterns engineered for users completing high-stakes services (taxes, benefits, immigration).

## Underrated

- USWDS Identifier component — the standard 'official site of the U.S. government' header pattern is reused by hundreds of federal sites.
- The token system in v3 is well-considered and serves as a reference for any government or public-service design system.

## Watch out for

- Visual identity is intentionally functional and government-flavored. Lifting it directly into a commercial product means substantial retheming.
- Sass-first build — adopting in modern build tooling (Vite, Next) requires some configuration.

## Components worth studying

- **Banner / Identifier** — The official U.S. government banner pattern, reused across federal sites.
- **Form Group** — Label + input + hint + error pattern with full a11y wiring.
- **Step Indicator** — Multi-step progress for benefits/applications flows.

## When to choose U.S. Web Design System

Adopt directly if you're building a U.S. federal or state government site. For public-service work elsewhere, USWDS is a strong reference for plain-language patterns and accessibility-first defaults; cherry-pick the patterns rather than the visual identity.

## Apply this style with an AI tool

Paste this into your AI coding assistant as a direction, then iterate:

> Design in the spirit of U.S. Web Design System by U.S. Government — Public-service design system for U.S. federal websites. Character: Federal dependable: Public Sans plainness, flag-adjacent blue and red used sparingly, engineered for every American on every device. Use a primary colour near #005ea2, the typeface "Public Sans" (or a close equivalent), corner radius around 2px, a spacing rhythm on a 8px (units) base. Lean into what it's known for: Accessibility — USWDS components meet Section 508 and WCAG 2.1 AA requirements as a baseline. Match the intent, not the pixels; adapt it to my product rather than cloning it.

## Official references

- [USWDS docs](https://designsystem.digital.gov/)
- [USWDS on GitHub](https://github.com/uswds/uswds)
- [Plain language](https://www.plainlanguage.gov/)

---

_Generated by [designsystems.one](https://www.designsystems.one/design-systems/usds-design) — a catalogue of public design systems. Style facts are reported for reference and education; adapt them to your own product. Report issues or takedown requests via the site._