U.S. Web Design System

---
name: uswds
description: Apply the U.S. Web Design System visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" U.S. Web Design System, mentions USWDS, US Web Design System, designsystem.digital.gov, or describes color grades with contrast 'magic numbers', Public Sans / Source Sans / Merriweather trio, official government banner component — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# U.S. Web Design System Design System

The US federal government's design system: Public Sans typography, a token architecture of color 'grades' where the numeric distance between grades guarantees WCAG contrast, a #005ea2 primary blue, the #2491ff vivid focus ring, and sturdy, benefit-of-the-doubt components (banners, identifiers, step indicators) built for gov.gov trust.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as U.S. Web Design System.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (USWDS, US Web Design System, designsystem.digital.gov, federal design system), or describes its traits: color grades with contrast 'magic numbers'; Public Sans / Source Sans / Merriweather trio; official government banner component; #2491ff focus ring; sturdy bordered forms; flag-blue and flag-red accents.

## Design tokens

### Color palette

- default page background: `#ffffff` (--color-bg)
- base-lightest (gray-5) — banner and section backgrounds: `#f0f0f0` (--color-surface)
- ink / base-darkest — body text: `#1b1b1b` (--color-text)
- base-dark (gray-cool-60) — hint and meta text: `#565c65` (--color-text-muted)
- primary (blue-60v) — links, primary buttons: `#005ea2` (--color-accent)
- primary-dark (blue-warm-70v) — link hover, button hover: `#1a4480` (--color-accent-dark)
- accent-cool (cyan-30v) — highlights and info: `#00bde3` (--color-accent-cool)
- accent-warm (orange-30v) — attention accents: `#fa9441` (--color-accent-warm)
- focus (blue-40v) — the 4px outline on every focused element: `#2491ff` (--color-focus)
- visited link (violet-70v): `#54278f` (--color-link-visited)
- error (red-warm-50v); error-dark is #b50909: `#d54309` (--color-error)
- success (green-cool-40v): `#00a91c` (--color-success)

### Typography

- Display / headings: Public Sans (fallback: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif)
- Body: Public Sans (fallback: -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif)
- Mono / data: Source Code Pro (fallback: Menlo, Consolas, monospace)
- Type scale: 1.25 ratio, base 17px — computed steps: 17px / 21px / 27px / 33px / 42px / 52px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 700, line-height 1.2, letter-spacing 0
- Body: line-height 1.62, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 12, 16, 24, 32, 40, 48, 64 — Units token system in multiples of 8px (with 4px halves); reading measures are generous — body line height is a roomy 1.62 — while forms use 8/16/24px rhythm to stay scannable.
- Border radius: sm 2px, md 4px, lg 8px — Default component radius is a modest 4px (buttons, inputs, cards via $theme-button-border-radius etc.); nothing is pill-shaped by default.
- Border treatment: 1px solid #dfe1e2 — base-lighter #dfe1e2 for card and table borders; form inputs use a heavier 1px #565c65 border, and alerts carry an 8px colored left bar.

### Shadows

- shadow-1: `0 1px 4px 0 rgba(0, 0, 0, 0.1)` — Cards and raised elements (USWDS box-shadow token 1)
- shadow-2: `0 4px 8px 0 rgba(0, 0, 0, 0.1)` — Dropdowns and date pickers (token 2)
- shadow-3: `0 8px 16px 0 rgba(0, 0, 0, 0.1)` — Modals and overlays (token 3)

### Layout

- Max content width: 1024px
- 12-column grid in a desktop container (max 1024px default, widescreen optional); 2rem gutters
- Every site opens with the official 'An official website of the United States government' banner above the header
- Reading columns capped via measure tokens (~66ch); identifier footer with agency links closes the page
- Forms are single-column with labels above fields and 8px label gaps

### Effects

- Flat surfaces with occasional 8px colored left bars on alerts and summary boxes
- The .gov banner's tiny flag icon is the system's one moment of ornament

### Motion

- Easing: ease-in-out; durations 150ms / 250ms / 400ms
- Motion is sparse and functional: accordion expands, modal fades, banner slide — nothing decorative
- All animation must respect prefers-reduced-motion

## CSS variables (drop-in)

```css
:root {
  --color-bg: #ffffff;
  --color-surface: #f0f0f0;
  --color-text: #1b1b1b;
  --color-text-muted: #565c65;
  --color-accent: #005ea2;
  --color-accent-dark: #1a4480;
  --color-accent-cool: #00bde3;
  --color-accent-warm: #fa9441;
  --color-focus: #2491ff;
  --color-link-visited: #54278f;
  --color-error: #d54309;
  --color-success: #00a91c;
  --radius-sm: 2px;
  --radius-md: 4px;
  --radius-lg: 8px;
  --shadow-shadow-1: 0 1px 4px 0 rgba(0, 0, 0, 0.1);
  --shadow-shadow-2: 0 4px 8px 0 rgba(0, 0, 0, 0.1);
  --shadow-shadow-3: 0 8px 16px 0 rgba(0, 0, 0, 0.1);
  --border-default: 1px solid #dfe1e2;
  --font-display: "Public Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
  --font-body: "Public Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
  --font-mono: "Source Code Pro", Menlo, Consolas, monospace;
  --text-base: 17px;
  --leading-heading: 1.2;
  --leading-body: 1.62;
  --tracking-heading: 0;
  --tracking-body: 0;
  --ease: ease-in-out;
  --duration-fast: 150ms;
  --duration-base: 250ms;
  --duration-slow: 400ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Public+Sans:wght@400;700&family=Source+Code+Pro:wght@400&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** White extended header with agency logo, right-aligned nav links in Public Sans, and a #005ea2 current-page underline; the thin gray .gov banner always sits above it
- **Hero:** USWDS hero: full-width photo or dark-blue #1a4480 band, white bold headline, one #005ea2 primary button; often followed by a tagline section on #f0f0f0
- **Card:** White card with 1px #dfe1e2 border, 2px radius, optional shadow-1, a bold heading, and a text link with right arrow; media variant puts a flush image on top
- **Button (primary):** #005ea2 fill, white 700-weight text, 4px radius, generous 12px/20px padding; hover #1a4480, active #162e51, focus shows the 4px #2491ff ring offset from the button
- **Button (secondary):** Outline variant: transparent fill, 2px inset #005ea2 box-shadow border and blue text; 'base' variant uses gray-50 for tertiary actions
- **Form fields:** Bold label, gray hint text, then a white input with 1px #565c65 border and 4px radius, 44px tall; error state adds a 4px #b50909 left border and bold red message

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The color-grade system itself: every color has a 0–90 grade, and a difference of 40+ between two grades mathematically guarantees WCAG AA contrast — designers pick grades, not hexes, and accessibility follows. Spend boldness here; keep everything else quiet.

## Do

- Pick colors by grade arithmetic — a 40+ grade gap guarantees AA, 50+ guarantees AA for small text, 70+ AAA
- Use the vivid #2491ff focus ring everywhere, offset outside the element
- Lead with the .gov banner and identifier components on federal properties — they are trust signals, not chrome
- Use Public Sans for UI and pair it with Merriweather for long-form reading if you want the full federal voice

## Don't

- Don't hand-pick hexes outside the token grades; you silently break the contrast guarantees
- Don't restyle the focus ring subtle — USWDS deliberately makes it loud
- Don't use secondary red #d83933 as a brand color; it is reserved for urgent/alert semantics
- Don't tighten the 1.62 body line height to make pages feel 'denser'

## Accessibility notes

- USWDS is engineered around Section 508 / WCAG 2.1 AA compliance: the grade system encodes contrast math directly into the tokens ('magic numbers' 40/50/70), so correct token use is provably accessible
- Focus indicators are a mandated 0.25rem (4px) #2491ff outline with 0 offset by default on every interactive element
- Note: USWDS core's out-of-the-box theme defaults are source-sans-pro body with merriweather headings; Public Sans is the USWDS-commissioned flagship face used by designsystem.digital.gov itself and configured via $theme-font-type-sans — this record uses Public Sans throughout

## Reference sites

- U.S. Web Design System: https://designsystem.digital.gov
- USWDS theme color tokens: https://designsystem.digital.gov/design-tokens/color/theme-tokens/
- USWDS on GitHub: https://github.com/uswds/uswds

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip uswds.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/uswds.json

Settings → Capabilities → Skills → Upload skill → uswds.zip