# U.S. Web Design System

> `uswds@1.0.0`

The U.S. Web Design System (USWDS) is the official design system for U.S. federal government websites, maintained by the General Services Administration's Technology Transformation Services. Adoption is widespread across executive-branch domains. The default "uswds" theme uses Blue 60v (#005EA2) as primary, Red 50 (#D83933) as secondary, Cyan 30v (#00BDE3) as accent-cool, and Orange 30v (#FA9441) as accent-warm — all sourced from the 24-hue USWDS system color palette already present in this catalogue. Typography pairs Public Sans (the system's default open-source face commissioned by GSA) with Source Sans Pro and a Roboto Mono fallback for code. Accessibility (WCAG 2.1 AA) is non-negotiable.


**Tags:** `uswds`, `government`, `federal`, `public-domain`, `design-system`, `civic`, `light-first`

## Atoms

### Palette

**U.S. Web Design System** · `uswds@1.0.0` · CC0-1.0

> The system color palette of the U.S. Web Design System (USWDS) — the official design system for U.S. federal government websites. Ten hue families (red, orange, yellow, green, mint, cyan, blue, indigo, violet, magenta) plus three neutral families (gray, gray-cool, gray-warm). Each hue ships at grades 5/10/20/30/40/50/60/70/80/90, with a parallel "vivid" variant at the same grades (vivid-90 is intentionally absent in USWDS sources). Plain neutrals (gray) include grades 1–5 in addition to 10..90 plus a true black at grade 100. Light mode uses low-grade neutrals for the canvas; dark mode uses high-grade neutrals for the canvas. 

### Fonts

| Role | Font | License | Classification |
|------|------|---------|----------------|
| `heading` | **Public Sans** `(public-sans@1.0.0)` | OFL-1.1 | sans-serif |
| `body` | **Source Sans 3** `(source-sans-3@1.0.0)` | OFL-1.1 | sans-serif |
| `mono` | **Roboto Mono** `(roboto-mono@1.0.0)` | Apache-2.0 | monospace |

## Swatches

| ID | Name | Value |
|----|------|-------|
| `gray-1` | Gray 1 | `#FCFCFC` |
| `gray-2` | Gray 2 | `#F9F9F9` |
| `gray-3` | Gray 3 | `#F6F6F6` |
| `gray-4` | Gray 4 | `#F3F3F3` |
| `gray-5` | Gray 5 | `#F0F0F0` |
| `gray-10` | Gray 10 | `#E6E6E6` |
| `gray-20` | Gray 20 | `#C9C9C9` |
| `gray-30` | Gray 30 | `#ADADAD` |
| `gray-40` | Gray 40 | `#919191` |
| `gray-50` | Gray 50 | `#757575` |
| `gray-60` | Gray 60 | `#5C5C5C` |
| `gray-70` | Gray 70 | `#454545` |
| `gray-80` | Gray 80 | `#2E2E2E` |
| `gray-90` | Gray 90 | `#1B1B1B` |
| `gray-100` | Gray 100 | `#000000` |
| `gray-cool-1` | Gray Cool 1 | `#FBFCFD` |
| `gray-cool-2` | Gray Cool 2 | `#F7F9FA` |
| `gray-cool-3` | Gray Cool 3 | `#F5F6F7` |
| `gray-cool-4` | Gray Cool 4 | `#F1F3F6` |
| `gray-cool-5` | Gray Cool 5 | `#EDEFF0` |
| `gray-cool-10` | Gray Cool 10 | `#DFE1E2` |
| `gray-cool-20` | Gray Cool 20 | `#C6CACE` |
| `gray-cool-30` | Gray Cool 30 | `#A9AEB1` |
| `gray-cool-40` | Gray Cool 40 | `#8D9297` |
| `gray-cool-50` | Gray Cool 50 | `#71767A` |
| `gray-cool-60` | Gray Cool 60 | `#565C65` |
| `gray-cool-70` | Gray Cool 70 | `#3D4551` |
| `gray-cool-80` | Gray Cool 80 | `#2D2E2F` |
| `gray-cool-90` | Gray Cool 90 | `#1C1D1F` |
| `gray-warm-1` | Gray Warm 1 | `#FCFCFB` |
| `gray-warm-2` | Gray Warm 2 | `#F9F9F7` |
| `gray-warm-3` | Gray Warm 3 | `#F6F6F2` |
| `gray-warm-4` | Gray Warm 4 | `#F5F5F0` |
| `gray-warm-5` | Gray Warm 5 | `#F0F0EC` |
| `gray-warm-10` | Gray Warm 10 | `#E6E6E2` |
| `gray-warm-20` | Gray Warm 20 | `#CAC9C0` |
| `gray-warm-30` | Gray Warm 30 | `#AFAEA2` |
| `gray-warm-40` | Gray Warm 40 | `#929285` |
| `gray-warm-50` | Gray Warm 50 | `#76766A` |
| `gray-warm-60` | Gray Warm 60 | `#5D5D52` |
| `gray-warm-70` | Gray Warm 70 | `#454540` |
| `gray-warm-80` | Gray Warm 80 | `#2E2E2A` |
| `gray-warm-90` | Gray Warm 90 | `#171716` |
| `red-5` | Red 5 | `#F9EEEE` |
| `red-10` | Red 10 | `#F8E1DE` |
| `red-20` | Red 20 | `#F7BBB1` |
| `red-30` | Red 30 | `#F2938C` |
| `red-40` | Red 40 | `#E9695F` |
| `red-50` | Red 50 | `#D83933` |
| `red-60` | Red 60 | `#A23737` |
| `red-70` | Red 70 | `#6F3331` |
| `red-80` | Red 80 | `#3E2927` |
| `red-90` | Red 90 | `#1B1616` |
| `red-vivid-5` | Red Vivid 5 | `#FFF3F2` |
| `red-vivid-10` | Red Vivid 10 | `#FDE0DB` |
| `red-vivid-20` | Red Vivid 20 | `#FDB8AE` |
| `red-vivid-30` | Red Vivid 30 | `#FF8D7B` |
| `red-vivid-40` | Red Vivid 40 | `#FB5A47` |
| `red-vivid-50` | Red Vivid 50 | `#E52207` |
| `red-vivid-60` | Red Vivid 60 | `#B50909` |
| `red-vivid-70` | Red Vivid 70 | `#8B0A03` |
| `red-vivid-80` | Red Vivid 80 | `#5C1111` |
| `orange-5` | Orange 5 | `#F6EFE9` |
| `orange-10` | Orange 10 | `#F2E4D4` |
| `orange-20` | Orange 20 | `#F3BF90` |
| `orange-30` | Orange 30 | `#F09860` |
| `orange-40` | Orange 40 | `#DD7533` |
| `orange-50` | Orange 50 | `#A86437` |
| `orange-60` | Orange 60 | `#775540` |
| `orange-70` | Orange 70 | `#524236` |
| `orange-80` | Orange 80 | `#332D27` |
| `orange-90` | Orange 90 | `#1B1614` |
| `orange-vivid-5` | Orange Vivid 5 | `#FEF2E4` |
| `orange-vivid-10` | Orange Vivid 10 | `#FCE2C5` |
| `orange-vivid-20` | Orange Vivid 20 | `#FFBC78` |
| `orange-vivid-30` | Orange Vivid 30 | `#FA9441` |
| `orange-vivid-40` | Orange Vivid 40 | `#E66F0E` |
| `orange-vivid-50` | Orange Vivid 50 | `#C05600` |
| `orange-vivid-60` | Orange Vivid 60 | `#8C471C` |
| `orange-vivid-70` | Orange Vivid 70 | `#5F3617` |
| `orange-vivid-80` | Orange Vivid 80 | `#352313` |
| `yellow-5` | Yellow 5 | `#FAF3D1` |
| `yellow-10` | Yellow 10 | `#F5E6AF` |
| `yellow-20` | Yellow 20 | `#E6C74C` |
| `yellow-30` | Yellow 30 | `#C9AB48` |
| `yellow-40` | Yellow 40 | `#A88F48` |
| `yellow-50` | Yellow 50 | `#8A7237` |
| `yellow-60` | Yellow 60 | `#6B5A39` |
| `yellow-70` | Yellow 70 | `#504332` |
| `yellow-80` | Yellow 80 | `#332D27` |
| `yellow-90` | Yellow 90 | `#1A1614` |
| `yellow-vivid-5` | Yellow Vivid 5 | `#FFF5C2` |
| `yellow-vivid-10` | Yellow Vivid 10 | `#FEE685` |
| `yellow-vivid-20` | Yellow Vivid 20 | `#FACE00` |
| `yellow-vivid-30` | Yellow Vivid 30 | `#DDAA01` |
| `yellow-vivid-40` | Yellow Vivid 40 | `#B38C00` |
| `yellow-vivid-50` | Yellow Vivid 50 | `#947100` |
| `yellow-vivid-60` | Yellow Vivid 60 | `#776017` |
| `yellow-vivid-70` | Yellow Vivid 70 | `#5C4809` |
| `yellow-vivid-80` | Yellow Vivid 80 | `#422D19` |
| `green-5` | Green 5 | `#EAF4DD` |
| `green-10` | Green 10 | `#DFEACD` |
| `green-20` | Green 20 | `#B8D293` |
| `green-30` | Green 30 | `#9BB672` |
| `green-40` | Green 40 | `#7D9B4E` |
| `green-50` | Green 50 | `#607F35` |
| `green-60` | Green 60 | `#4C6424` |
| `green-70` | Green 70 | `#3C4A29` |
| `green-80` | Green 80 | `#293021` |
| `green-90` | Green 90 | `#161814` |
| `green-vivid-5` | Green Vivid 5 | `#DDF9C7` |
| `green-vivid-10` | Green Vivid 10 | `#C5EE93` |
| `green-vivid-20` | Green Vivid 20 | `#98D035` |
| `green-vivid-30` | Green Vivid 30 | `#7FB135` |
| `green-vivid-40` | Green Vivid 40 | `#719F2A` |
| `green-vivid-50` | Green Vivid 50 | `#538200` |
| `green-vivid-60` | Green Vivid 60 | `#466C04` |
| `green-vivid-70` | Green Vivid 70 | `#2F4A0B` |
| `green-vivid-80` | Green Vivid 80 | `#243413` |
| `mint-5` | Mint 5 | `#DBF6ED` |
| `mint-10` | Mint 10 | `#C7EFE2` |
| `mint-20` | Mint 20 | `#92D9BB` |
| `mint-30` | Mint 30 | `#5ABF95` |
| `mint-40` | Mint 40 | `#34A37E` |
| `mint-50` | Mint 50 | `#2E8367` |
| `mint-60` | Mint 60 | `#286846` |
| `mint-70` | Mint 70 | `#204E34` |
| `mint-80` | Mint 80 | `#193324` |
| `mint-90` | Mint 90 | `#0D1A12` |
| `mint-vivid-5` | Mint Vivid 5 | `#C9FBEB` |
| `mint-vivid-10` | Mint Vivid 10 | `#83FCD4` |
| `mint-vivid-20` | Mint Vivid 20 | `#0CEDA6` |
| `mint-vivid-30` | Mint Vivid 30 | `#04C585` |
| `mint-vivid-40` | Mint Vivid 40 | `#00A871` |
| `mint-vivid-50` | Mint Vivid 50 | `#008659` |
| `mint-vivid-60` | Mint Vivid 60 | `#146947` |
| `mint-vivid-70` | Mint Vivid 70 | `#0C4E29` |
| `mint-vivid-80` | Mint Vivid 80 | `#0D351E` |
| `cyan-5` | Cyan 5 | `#E7F6F8` |
| `cyan-10` | Cyan 10 | `#CCECF2` |
| `cyan-20` | Cyan 20 | `#99DEEA` |
| `cyan-30` | Cyan 30 | `#5DC0D1` |
| `cyan-40` | Cyan 40 | `#449DAC` |
| `cyan-50` | Cyan 50 | `#168092` |
| `cyan-60` | Cyan 60 | `#2A646D` |
| `cyan-70` | Cyan 70 | `#2C4A4E` |
| `cyan-80` | Cyan 80 | `#203133` |
| `cyan-90` | Cyan 90 | `#111819` |
| `cyan-vivid-5` | Cyan Vivid 5 | `#E5FAFF` |
| `cyan-vivid-10` | Cyan Vivid 10 | `#A8F2FF` |
| `cyan-vivid-20` | Cyan Vivid 20 | `#52DAF2` |
| `cyan-vivid-30` | Cyan Vivid 30 | `#00BDE3` |
| `cyan-vivid-40` | Cyan Vivid 40 | `#009EC1` |
| `cyan-vivid-50` | Cyan Vivid 50 | `#0081A1` |
| `cyan-vivid-60` | Cyan Vivid 60 | `#00687D` |
| `cyan-vivid-70` | Cyan Vivid 70 | `#0E4F5C` |
| `cyan-vivid-80` | Cyan Vivid 80 | `#093B44` |
| `blue-5` | Blue 5 | `#EFF6FB` |
| `blue-10` | Blue 10 | `#D9E8F6` |
| `blue-20` | Blue 20 | `#AACDEC` |
| `blue-30` | Blue 30 | `#73B3E7` |
| `blue-40` | Blue 40 | `#4F97D1` |
| `blue-50` | Blue 50 | `#2378C3` |
| `blue-60` | Blue 60 | `#2C608A` |
| `blue-70` | Blue 70 | `#274863` |
| `blue-80` | Blue 80 | `#1F303E` |
| `blue-90` | Blue 90 | `#11181D` |
| `blue-vivid-5` | Blue Vivid 5 | `#E8F5FF` |
| `blue-vivid-10` | Blue Vivid 10 | `#CFE8FF` |
| `blue-vivid-20` | Blue Vivid 20 | `#A1D3FF` |
| `blue-vivid-30` | Blue Vivid 30 | `#58B4FF` |
| `blue-vivid-40` | Blue Vivid 40 | `#2491FF` |
| `blue-vivid-50` | Blue Vivid 50 | `#0076D6` |
| `blue-vivid-60` | Blue Vivid 60 | `#005EA2` |
| `blue-vivid-70` | Blue Vivid 70 | `#0B4778` |
| `blue-vivid-80` | Blue Vivid 80 | `#112F4E` |
| `indigo-5` | Indigo 5 | `#EFEFF8` |
| `indigo-10` | Indigo 10 | `#E5E4FA` |
| `indigo-20` | Indigo 20 | `#C5C5F3` |
| `indigo-30` | Indigo 30 | `#A5A8EB` |
| `indigo-40` | Indigo 40 | `#8889DB` |
| `indigo-50` | Indigo 50 | `#676CC8` |
| `indigo-60` | Indigo 60 | `#4D52AF` |
| `indigo-70` | Indigo 70 | `#3D4076` |
| `indigo-80` | Indigo 80 | `#2B2C40` |
| `indigo-90` | Indigo 90 | `#16171F` |
| `indigo-vivid-5` | Indigo Vivid 5 | `#F0F0FF` |
| `indigo-vivid-10` | Indigo Vivid 10 | `#E0E0FF` |
| `indigo-vivid-20` | Indigo Vivid 20 | `#CCCEFF` |
| `indigo-vivid-30` | Indigo Vivid 30 | `#A3A7FA` |
| `indigo-vivid-40` | Indigo Vivid 40 | `#8289FF` |
| `indigo-vivid-50` | Indigo Vivid 50 | `#656BD7` |
| `indigo-vivid-60` | Indigo Vivid 60 | `#4A50C4` |
| `indigo-vivid-70` | Indigo Vivid 70 | `#3333A3` |
| `indigo-vivid-80` | Indigo Vivid 80 | `#212463` |
| `violet-5` | Violet 5 | `#F4F1F9` |
| `violet-10` | Violet 10 | `#EBE3F9` |
| `violet-20` | Violet 20 | `#D0C3E9` |
| `violet-30` | Violet 30 | `#B8A2E3` |
| `violet-40` | Violet 40 | `#9D84D2` |
| `violet-50` | Violet 50 | `#8168B3` |
| `violet-60` | Violet 60 | `#665190` |
| `violet-70` | Violet 70 | `#4C3D69` |
| `violet-80` | Violet 80 | `#312B3F` |
| `violet-90` | Violet 90 | `#18161D` |
| `violet-vivid-5` | Violet Vivid 5 | `#F7F2FF` |
| `violet-vivid-10` | Violet Vivid 10 | `#EDE3FF` |
| `violet-vivid-20` | Violet Vivid 20 | `#D5BFFF` |
| `violet-vivid-30` | Violet Vivid 30 | `#C39DEB` |
| `violet-vivid-40` | Violet Vivid 40 | `#AD79E9` |
| `violet-vivid-50` | Violet Vivid 50 | `#9355DC` |
| `violet-vivid-60` | Violet Vivid 60 | `#783CB9` |
| `violet-vivid-70` | Violet Vivid 70 | `#54278F` |
| `violet-vivid-80` | Violet Vivid 80 | `#39215E` |
| `magenta-5` | Magenta 5 | `#F9F0F2` |
| `magenta-10` | Magenta 10 | `#F6E1E8` |
| `magenta-20` | Magenta 20 | `#F0BBCC` |
| `magenta-30` | Magenta 30 | `#E895B3` |
| `magenta-40` | Magenta 40 | `#E0699F` |
| `magenta-50` | Magenta 50 | `#C84281` |
| `magenta-60` | Magenta 60 | `#8B4566` |
| `magenta-70` | Magenta 70 | `#66364B` |
| `magenta-80` | Magenta 80 | `#402731` |
| `magenta-90` | Magenta 90 | `#1B1617` |
| `magenta-vivid-5` | Magenta Vivid 5 | `#FFF2F5` |
| `magenta-vivid-10` | Magenta Vivid 10 | `#FFDDEA` |
| `magenta-vivid-20` | Magenta Vivid 20 | `#FFB4CF` |
| `magenta-vivid-30` | Magenta Vivid 30 | `#FF87B2` |
| `magenta-vivid-40` | Magenta Vivid 40 | `#FD4496` |
| `magenta-vivid-50` | Magenta Vivid 50 | `#D72D79` |
| `magenta-vivid-60` | Magenta Vivid 60 | `#AB2165` |
| `magenta-vivid-70` | Magenta Vivid 70 | `#731F44` |
| `magenta-vivid-80` | Magenta Vivid 80 | `#4F172E` |

## Mode role mappings

### Light mode

| Role | Swatch | Hex |
|------|--------|-----|
| `background` | `gray-1` | `#FCFCFC` |
| `surface` | `gray-3` | `#F6F6F6` |
| `surface-elevated` | `gray-1` | `#FCFCFC` |
| `text-primary` | `gray-90` | `#1B1B1B` |
| `text-secondary` | `gray-70` | `#454545` |
| `text-tertiary` | `gray-50` | `#757575` |
| `primary` | `blue-50` | `#2378C3` |
| `primary-hover` | `blue-70` | `#274863` |
| `accent` | `indigo-vivid-60` | `#4A50C4` |
| `accent-hover` | `indigo-vivid-70` | `#3333A3` |
| `warning` | `yellow-30` | `#C9AB48` |
| `warning-hover` | `yellow-50` | `#8A7237` |
| `error` | `red-50` | `#D83933` |
| `success` | `green-50` | `#607F35` |
| `border` | `gray-30` | `#ADADAD` |

### Dark mode

| Role | Swatch | Hex |
|------|--------|-----|
| `background` | `gray-90` | `#1B1B1B` |
| `surface` | `gray-80` | `#2E2E2E` |
| `surface-elevated` | `gray-70` | `#454545` |
| `text-primary` | `gray-1` | `#FCFCFC` |
| `text-secondary` | `gray-20` | `#C9C9C9` |
| `text-tertiary` | `gray-30` | `#ADADAD` |
| `primary` | `blue-vivid-30` | `#58B4FF` |
| `primary-hover` | `blue-vivid-20` | `#A1D3FF` |
| `accent` | `indigo-vivid-30` | `#A3A7FA` |
| `accent-hover` | `indigo-vivid-20` | `#CCCEFF` |
| `warning` | `yellow-vivid-20` | `#FACE00` |
| `warning-hover` | `yellow-vivid-10` | `#FEE685` |
| `error` | `red-vivid-30` | `#FF8D7B` |
| `success` | `green-vivid-30` | `#7FB135` |
| `border` | `gray-70` | `#454545` |

## Brand semantic roles

### Colors

| Role | Swatch | Hex |
|------|--------|-----|
| `identity` | `gray-1` | `#FCFCFC` |
| `on-identity` | `gray-90` | `#1B1B1B` |
| `primary` | `blue-vivid-60` | `#005EA2` |
| `primary-hover` | `blue-vivid-70` | `#0B4778` |
| `accent` | `cyan-vivid-30` | `#00BDE3` |
| `accent-hover` | `cyan-vivid-40` | `#009EC1` |
| `mark` | `blue-vivid-60` | `#005EA2` |
| `success` | `green-50` | `#607F35` |
| `warning` | `yellow-30` | `#C9AB48` |
| `error` | `red-50` | `#D83933` |
| `text-primary-light` | `gray-90` | `#1B1B1B` |
| `text-primary-dark` | `gray-1` | `#FCFCFC` |
| `background-light` | `gray-1` | `#FCFCFC` |
| `background-dark` | `gray-90` | `#1B1B1B` |
| `surface-light` | `gray-3` | `#F6F6F6` |
| `surface-dark` | `gray-80` | `#2E2E2E` |
| `text-secondary-light` | `gray-70` | `#454545` |
| `text-tertiary-light` | `gray-50` | `#757575` |
| `border-light` | `gray-30` | `#ADADAD` |

### Typography

| Role | Font role key |
|------|---------------|
| `display` | `heading` |
| `prose` | `body` |
| `code` | `mono` |

## Rules

### 🛑 error (7)

#### `colorChoice` → `roles.colors.primary`

- **allowed:** blue-vivid-60, blue-vivid-70
- **forbidden:** red-50, red-vivid-50, green-50, violet-50, magenta-50

> USWDS's default "uswds" theme resolves the `primary` token to blue-vivid-60 (#005EA2) and `primary-vivid` to blue-warm-60v (#0050D8), with blue-warm-70v (#1A4480) and blue-warm-80v (#162E51) as the dark variants. The secondary slot is red-50, but red MUST NOT stand in for the primary interactive role — doing so violates the documented theme contract that federal consumers rely on for affordance and link recognition. 

#### `colorChoice` → `roles.colors.error`

- **allowed:** red-50, red-vivid-50
- **forbidden:** orange-vivid-30, yellow-30, magenta-50

> USWDS Red 50 (#D83933) is the documented danger / error color across the system. Orange and yellow are reserved for accent-warm and warning roles respectively; conflating them with destructive error states undermines the WCAG-grounded affordance hierarchy USWDS encodes. 

#### `contrastRatio` → `text-primary`

- **against:** `background`
- **minRatio:** `4.5`
- **standard:** `WCAG-AA`

> USWDS's published accessibility commitment targets WCAG 2.1 Level AA across all components. Gray 90 (#1B1B1B) on Gray 1 (#FCFCFC) clears AA at ~17:1, satisfying the federal Section 508 accessibility baseline that USWDS exists to make routine. 

#### `accessibilityRequirement` → `*`

- **standard:** `WCAG-AA`
- **criterion:** `1.4.3`

> WCAG 2.1 Success Criterion 1.4.3 (Contrast Minimum) — Level AA. Federal websites are subject to Section 508 of the Rehabilitation Act and OMB M-23-22 implementing guidance; USWDS is the standardized path to compliance and all consumers of this brand atom MUST meet AA at minimum. 

#### `forbiddenTreatment` → `logo`

- **treatments:** stretched, rotated, recolored, drop-shadow, gradient-fill, outlined, on-busy-photo

> U.S. government insignia (agency seals, the great seal, department wordmarks) are subject to federal statute and agency-specific usage policy. The USWDS visual-identity guidance prohibits decorative treatment of official marks; consumers ship the official mark unaltered or substitute a site-specific identifier rendered in the system's theme colors only. 

#### `fontPairing` → `typography.display`

- **requires:** `prose`
- **minSizeRatio:** `1.5`

> USWDS's documented type scale maintains a clear hierarchy between display and body sizes (heading-xl through heading-3xs, with body anchored at the 16-pixel base). Display-at-body-size collapses the scannability USWDS's component patterns rely on for landing pages, alerts, and form-flow surfaces. 

#### `contextRestriction` → `roles.colors.success`

- **forbiddenContexts:** error-state, destructive-action
- **allowedContexts:** confirmation, completion, data-viz-positive

> USWDS Green 50 (#607F35) is the documented success color used by the Alert and Status components. Inverting its meaning (success for failure) conflicts with the role contract federal product teams and screen-reader users rely on for assistive-tech announcement parity. 

### ⚠️ warning (1)

#### `enumMembership` → `typography.heading.fontWeight`

- **allowed:** 300, 400, 500, 600, 700

> Public Sans, USWDS's commissioned default heading face, ships in Thin, ExtraLight, Light (300), Regular (400), Medium (500), SemiBold (600), Bold (700), ExtraBold, and Black. USWDS's documented type ramp anchors at Regular, Medium, SemiBold, and Bold for headings — Thin/ExtraLight and Black/ExtraBold cuts are not part of the documented scale and should not be used for primary heading roles. 

### 💡 recommendation (1)

#### `compositionConstraint` → `roles.colors.mark`

- **pairsWith:** gray-1, gray-3, gray-90
- **doesNotPairWith:** red-50, orange-vivid-30, yellow-30, magenta-50

> Blue 60v reads as institutional federal-identity blue against the white canvas or the near-black ink surface. Placing it adjacent to red-50 (secondary), orange-vivid-30 (accent-warm), yellow-30 (warning), or magenta-50 at equal weight produces chromatic competition that fights the restrained civic-government voice USWDS targets. 

## Provenance

- **Source:** <https://designsystem.digital.gov/design-tokens/color/theme-tokens/>
- **License:** `CC0-1.0`
- **Attribution:** U.S. Web Design System (USWDS), released by the U.S. General Services Administration to the public domain (CC0-1.0). Theme token defaults captured from the published theme-color-tokens reference; system color values mirrored from the uswds-core Sass partials. "U.S. Web Design System," "USWDS," the federal word marks, and U.S. government insignia are not implied to be licensed CC0 — only the design-system code and tokens are. 
- **Imported:** `2026-05-19`
- **Notes:** This brand atom REFERENCES the existing `uswds@1` palette atom rather than creating a duplicate. Theme-token defaults from the published reference resolve as follows: primary = blue-vivid-60 (#005EA2), secondary = red-50 (#D83933), accent-cool = cyan-vivid-30 (#00BDE3), accent-warm = orange-vivid-30 (#FA9441), base-darkest / base-ink = gray-90 (#1B1B1B). All referenced swatch IDs exist in palettes/uswds@1. 

---

*Generated by the brand-atoms converter. Source: `uswds@1.0.0` from the encyclopedia.*