# U.S. Web Design System: brand book and build spec

The federal government's own design system: a flag-and-banner frame, a regularized token palette led by primary blue #005ea2 and secondary red #d83933, Public Sans in light and bold, flat 4px-radius buttons, and rules written for accessibility first.

From unfairly.ai/brand-guidelines/uswds, checked 2026-10-30. Unofficial study; not affiliated with U.S. Web Design System.

Every value is labelled with where it came from: **published** (the brand says it), **observed** (measured or seen on its live site, with the date), **our reading** (inferred from the evidence) or **our recipe** (how we apply the system). Files beside this one: tokens.css, tokens.json (DTCG 2025.10), kit.json.

**Thesis (our reading):** Trust through sameness. USWDS makes every government site look and behave alike on purpose (official banner on top, identifier at the bottom, token-only color that passes contrast by arithmetic) so a citizen recognizes an official, accessible site before reading a word. Based on: Earn trust and Promote continuity principles; key benefits say consistency "increases trust in government"; banner and identifier rules require unaltered text on every page; color grades guarantee contrast.

## Purpose

Mission: Shaping the future of government digital services. (published; https://designsystem.digital.gov/about/)

Story: Created in 2015 by 18F and the U.S. Digital Service, guided by staff from CFPB, FDA, VA, SSA, Education, IRS and GSA. Now maintained by GSA TTS's Digital Services Division. (published)

| Value | What it means in the work | Source |
|---|---|---|
| Start with real user needs | Research and test with real people from the start of every decision. | published: https://designsystem.digital.gov/design-principles/ |
| Earn trust | Be reliable, consistent and honest; identify as government; protect data. | published: https://designsystem.digital.gov/design-principles/ |
| Embrace accessibility | Build accessibility into every decision, beyond the legal minimum. | published: https://designsystem.digital.gov/design-principles/ |
| Promote continuity | Start from shared solutions so experiences stay consistent across agencies and devices. | published: https://designsystem.digital.gov/design-principles/ |
| Listen | Measure, collect feedback and keep improving. | published: https://designsystem.digital.gov/design-principles/ |
| Be consistent, not static | Product value: specific enough to be practical, general enough to extend. | published: https://designsystem.digital.gov/about/product-values/ |

## Fixed and flexible

Never changes:
- Official banner on top and identifier at the bottom of every page, text unaltered
- Only USWDS tokens for color, type, spacing; contrast by grade difference
- Plain, flush-left, sentence-case copy; buttons start with a verb
- Visible 4px blue-40v focus outline and WCAG 2.1 AA components

The one thing that varies: Which token families fill the theme roles: agencies swap primary/secondary/accent families and typefaces in settings (the docs site itself uses Public Sans where the default theme uses Source Sans Pro and Merriweather).

## Positioning

- **Statement**: The design system for the federal government. (observed)
- **Category**: A government design system: principles, guidance and code (a toolkit), maintained as open source by GSA. (published)
- **Audience**: Federal digital service teams: content managers, designers and developers, plus the agencies and contractors who build government sites. (published)
- **Problem**: Federal requirements (Section 508, 21st Century IDEA) are confusing, and every team rebuilding basic components wastes public money. (published)
- **Promise**: Accessible, mobile-friendly, compliant sites from the start, improving as the system improves. (published)
- **Differentiators**: Built by government, for government, with government.; Compliance (508, 21st Century IDEA) designed in from the start.; Color grades regularized so a "magic number" guarantees contrast.; Type normalized so each size token looks the same in any supported face.; Adopt incrementally: principles, then guidance, then code (maturity model).
- **Alternatives**: Building components and patterns from scratch for each site (the "redesign treadmill").

## Messaging

Boilerplate (published): USWDS gives government teams principles, guidance and code for building accessible, mobile-friendly websites. It was created in 2015 by 18F and the U.S. Digital Service and is a product of GSA's Technology Transformation Services.

Taglines:
- The design system for the federal government. (Homepage hero h1)
- We make it easier to build accessible, mobile-friendly government websites. (Homepage hero lead)
- Focus on your mission, not your markup. (Key benefits: Mission focus)

| Pillar | Claim | Proof | Label |
|---|---|---|---|
| Compliance from the start | Principles, guidance and code meet Section 508 and 21st Century IDEA requirements out of the box. | Over 40 accessible, mobile-friendly components out of the box (47 listed on the components page).; Components are tested against WCAG 2.1 AA, above the 2.0 AA legal baseline. | published |
| Proven design solutions users expect | Don't reinvent buttons and forms; consistent experiences across government build trust. | Contributors support dozens of agencies and nearly 200 sites.; Sites using USWDS topped 1.4 billion pageviews in Q2 2018. | published |
| Team alignment | Five design principles give any team a shared starting agreement. | Five design principles: start with real user needs, earn trust, embrace accessibility, promote continuity, listen. | published |
| Mission focus | Spend less time building from scratch; every system improvement reaches every site. | 243 icons in the icon component.; 24 color families in the system palette, each graded 5-90 for predictable contrast. | published |
| A cross-government community | Content managers, designers and developers share solutions in the open. | Open source on GitHub with public GitHub Discussions. | published |
| Stewardship of public resources | Any team's improvement is shared, multiplied and compounded across government. | Created in 2015 by 18F and the U.S. Digital Service with an advisory board from seven agencies. | published |

They never claim:
- Never claim 100% accessibility: USWDS says nothing can ever be fully accessible, and teams must test their own work.
- Use the banner and identifier only on real official government sites, never on test or non-official sites.

Real lines, as they wrote them:
| Line | Channel | Source |
|---|---|---|
| "The design system for the federal government." | homepage hero | https://designsystem.digital.gov/ |
| "Sites built with USWDS" | homepage section | https://designsystem.digital.gov/ |
| "Become part of the community" | homepage section | https://designsystem.digital.gov/ |

## Voice

Tone words: reliable, consistent, honest, plain.

Traits:
- Reliable, but not Flashy (published)
- Consistent, but not Static (published)
- Continuous, but not Conformist (published)
- Accessible, but not An afterthought (published)
- Open, but not Closed (published)
- Practical, but not Emotional first (published)

- Plain language is a trust practice: the Earn trust principle asks whether content is clear and easy to follow (paraphrase).
- Write for the web: expect readers to skim and scan (Earn trust practical actions).
- The site speaks as "we" (the USWDS team) to "you" (government teams), e.g. "We make it easier to build..." (observed on the homepage).
- Headings and button labels are sentence case on the docs site; button guidance makes it a rule.
- Explain, then list: guidance pages pair a bold imperative lead ("Lead with a verb.") with one or two plain sentences.
- USWDS publishes no separate voice and tone guide; these notes come from the design principles, product values, and component guidance.

Rules a copy check enforces:
- Use sentence case for button labels
- Lead button labels with a verb ("File a complaint", not "Complaint filing")
- Keep button text as short as possible, with action words like Download, View, Sign up
- Sentence case headlines
- Write as "we", to "you"
- Write in plain language; label headings, images and links accurately
- No uppercase text longer than a few words unless the law requires it
- Avoid long stretches of bold or italic text; use a callout or heading instead
- Set type flush left; no justified text
- Pair icons with text; only home, print and search are widely understood alone
- Use the official banner text unaltered ("An official website of the United States government")
- Identify the site as a federal government site on every page
- Link between pages with links; reserve buttons for important actions
- Never use color alone to convey meaning

Their words: accessible, mobile-friendly, user needs, trust, continuity, plain language.

## Color

| Name | Hex | Role | Use |
|---|---|---|---|
| White | #ffffff | paper | Page ground; text on primary, secondary and dark grounds |
| Base lightest (gray-5) | #f0f0f0 | surface | Default banner ground; homepage hero and showcase bands |
| Ink (gray-90) | #1b1b1b | ink | Body text color (base-darkest / ink) |
| Base dark (gray-cool-60) | #565c65 | ink_muted | Secondary text (our reading) |
| Base (gray-cool-50) | #71767a | base | Neutral mid gray; grade 50 passes AA on white and black |
| Base lighter (gray-cool-10) | #dfe1e2 | rule | Borders and dividers |
| Primary (blue-60v) | #005ea2 | accent | About 60% of non-base color: default buttons, links |
| Primary vivid (blue-warm-60v) | #0050d8 | accent_vivid | Search button and the "Migrating" hero button |
| Primary dark (blue-warm-70v) | #1a4480 | accent_hover | Button hover |
| Primary darker (blue-warm-80v) | #162e51 | accent_active | Button active; dark grounds |
| Primary lighter (blue-10) | #d9e8f6 | tint | Light primary tint |
| Secondary (red-50) | #d83933 | accent_secondary | About 30% of non-base color; homepage icon circles and first hero button |
| Secondary dark (red-60v) | #b50909 | secondary_hover | Secondary button hover |
| Accent cool (cyan-30v) | #00bde3 | accent_cool | Part of the 10% accent share; community icon circles |
| Accent warm (orange-30v) | #fa9441 | accent_warm | Part of the 10% accent share |
| Docs header (blue-warm-80) | #252f3e | night | Dark header band on designsystem.digital.gov (observed) |
| Focus (blue-40v) | #2491ff | focus | 4px focus outline everywhere |
| Visited (violet-70v) | #54278f | visited | Visited links |
| Info (cyan-30v) | #00bde3 | state | Info alerts |
| Error (red-warm-50v) | #d54309 | state | Errors |
| Warning (gold-20v) | #ffbe2e | state | Warnings; also the docs site's "Read website standards" outline button |
| Success (green-cool-40v) | #00a91c | state | Success |
| Emergency (red-warm-60v) | #9c3d10 | state | Emergency alerts |
| Disabled (gray-50) | #757575 | state | Disabled |

## Typography

| Role | Their face | Licence | Open stand-in (Google Fonts) | Fallback |
|---|---|---|---|---|
| display | Public Sans Web | Open: SIL OFL 1.1 (Libre Franklin) with GSA changes dedicated CC0 | Public Sans | 'Public Sans Web', 'Public Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif |
| body | Public Sans Web | Open: SIL OFL 1.1 | Public Sans | 'Public Sans Web', 'Public Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif |
| mono | Roboto Mono Web | Open: Apache 2.0 | Roboto Mono | 'Roboto Mono Web', 'Roboto Mono', 'Bitstream Vera Sans Mono', Consolas, Courier, monospace |

| Role | Token | Face | Desktop | Phone | Line height | Tracking | Weight |
|---|---|---|---|---|---|---|---|
| Hero H1 | --text-hero-h1-* | Public Sans | 36px | 36px | 1.3 | 0px | 200 |
| Hero lead | --text-hero-lead-* | Public Sans | 24px | 24px | 1.4 | 0px | 200 |
| Section H2 (showcase) | --text-h2-xl-* | Public Sans | 28px | 28px | 1.2 | 0px | 700 |
| Footer H2 | --text-h2-footer-* | Public Sans | 20px | 20px | 1.2 | 0px | 700 |
| Site title (header) | --text-site-title-* | Public Sans | 20px | 15.04px | 1.2 | -0.2px | 700 |
| Graphic list head | --text-h2-md-* | Public Sans | 16.96px | 16.96px | 1.5 | 0px | 700 |
| Showcase caption link | --text-link-lg-* | Public Sans | 16.96px | 16.96px | 1.6 | 0px | 700 |
| Body (footer paragraph) | --text-body-* | Public Sans | 16px | 16px | 1.6 | 0px | 400 |
| Graphic list body / link | --text-body-sm-* | Public Sans | 15.04px | 15.04px | 1.5 | 0px | 400 |
| Primary nav link | --text-nav-* | Public Sans | 15.04px | 16px | 1 | 0px | 400 |
| Required links (identifier) | --text-identifier-link-* | Public Sans | 15.04px | 16px | 1.4 | 0px | 400 |
| Community item head / link | --text-body-xs-* | Public Sans | 14.08px | 14.08px | 1.4 | 0px | 400 |
| Button label | --text-button-* | Public Sans | 16px | 16px | 0.9 | 0px | 700 |
| Gov banner | --text-banner-* | Public Sans | 12px | 12px | 1.2 | 0px | 400 |

## Layout

Measured on https://designsystem.digital.gov/: Read from designsystem.digital.gov guidance pages (fetched 2026-10-30) and the site stylesheet /assets/css/styles.css.

| Measure | Desktop (1440) | Phone (390) |
|---|---|---|
| Page margin | 52px | 16px |
| Section padding | 64px | 32px |
| Container max width | 1400px | full |
| Hero text width | max 480px | full |
| Grid columns | 4 | 1 |
| Gutter | 32px | 16px |
| Card gap | 32px | 32px |
| Navigation height | 128px | 128px |

Breakpoints weren't measured. tokens.css switches to the phone values at 600px; that number is our default, not U.S. Web Design System's.

Homepage bands, top to bottom (observed):
1. Gov banner
   - Desktop: 1440x22, one line, 12px text from x 52
   - Phone: 390x48, two lines
   - Accordion; build collapsed
   - Text is fixed, never restyled
2. Header (row 1)
   - Desktop: 1440x80, y 22
   - Phone: 390x48 with star + "USWDS" and MENU
   - Outline buttons use 2px inset box-shadow rings, not borders
3. Primary nav (row 2)
   - Desktop: 1440x48, y 102, sticky, 2px rgba(0,0,0,0.1) bottom rule
   - Phone: in the 240px MENU drawer
   - 15.04px 400 #1b1b1b; hover #2672de with 4px bar
4. Hero
   - Desktop: 1440x351, text column 480px at x 52; illustration background at calc(50% + 240px) 12px, 400px tall, cropped
   - Phone: illustration on top (padding-top 265px), stacked full-width buttons
   - No frame or shadow around the illustration
5. Graphic list
   - Desktop: 4 columns, 64px top and bottom padding, icons stacked above text
   - Phone: icon left, text right, one item per row
   - No cards
6. Showcase
   - Desktop: 3x2 grid of 424x239 images, 32px gutter, 48px between rows
   - Phone: 1 column 358x201
   - Image shadow 0 1px 4px rgba(0,0,0,0.1), radius 0
7. Community footer
   - Desktop: 300px incl. v1 strip; 4 columns of 338px
   - Phone: stacked
   - Links #2f4668 underlined
8. v1 strip
   - Desktop: 36px, 15.04px text
   - Phone: 55px, wraps
   - Bold underlined ink link
9. Identifier
   - Desktop: 1440x220
   - Phone: 390x545
   - Required links never removed or restyled to stand out

## Page anatomy

How U.S. Web Design System's own landing pages are built, part by part (observed; https://designsystem.digital.gov/, 2026-10-30). A homepage pattern, not a brand law: follow it for landing pages.

**Announcement bar**
- summary: The official government banner (usa-banner): a thin #1b1b1b strip above the header on every page. Not marketing; text is fixed.
- text: An official website of the United States government
- link: "Here's how you know" (12px/14.4px Public Sans 400, #c9c9c9, underlined) followed by a 16px expand_more chevron in #2491ff (mask icon, absolutely placed 2px after the label)
- ground: #1b1b1b
- desktop: height 22px (padding-top 4px); 16x11 US flag at x 52, y 6; text 12px/14.4px 400 #FFFFFF at x 76; link at x 371 on the same line
- phone: height 48px (padding 8px 0); flag at x 16, y 8; text at x 40 on line 1 (y 8), link on line 2 (y 24) with the chevron
- resting state: Collapsed. Expanded (on click) it opens a 144px panel on the same #1b1b1b with two media blocks: icon-dot-gov.svg + "Official websites use .gov" / "A .gov website belongs to an official government organization in the United States." and icon-https.svg + "Secure .gov websites use HTTPS" / "A lock ( ) or https:// means you've safely connected to the .gov website. Share sensitive information only on official, secure websites." Build the collapsed state.

**Navigation**
- summary: Extended header in two rows. Row 1: dark #252f3e bar with the USWDS star and "U.S. Web Design System (USWDS)" at left, and search, two outlined buttons and a GitHub mark at right. Row 2: a white primary-nav bar with eight links. Phone: one 48px dark bar with star + "USWDS" and a blue MENU button.
- ground: row 1 #252f3e; row 2 #FFFFFF with a 2px solid rgba(0,0,0,0.1) bottom border
- height: row 1 80px (y 22-102), row 2 48px (y 102-150); phone 48px (y 48-96)
- border: none on row 1; 2px solid rgba(0,0,0,0.1) under row 2
- logo: variant USWDS star 4c-lg-on-black.svg (five-colour star: #81aefc, #4d52af, #ee601d, #f6bd9c, #e6e6e6) as a 24x24 ::before, then the wordmark set in type, not an image; px star 24x24; title "U.S. Web Design System (USWDS)" 20px Public Sans 700, tracking -0.2px, #FFFFFF; phone title "USWDS" 15.04px 700; position desktop star x 52 (margin-left -2px), title x 82, vertically centred in the 80px row (title y 48); phone star x 16, title x 45; file https://designsystem.digital.gov/assets/img/uswds-logo/4c-lg-on-black.svg
- links: count 8; labels How to use USWDS,Design principles,Components,Patterns,Design tokens,Utilities,Templates,About; hrefs /how-to-use-uswds/,/design-principles/,/components/,/patterns/,/design-tokens/,/utilities/,/templates/,/about/; size 15.04px/15.04px (text-sm), hit area 48px tall with 16px padding all round; weight 400; color #1b1b1b; hover #2672de text plus a 4px #2672de bar along the bottom inset 16px each side; alignment left aligned, first link box x 36 (text x 52, flush with the logo), boxes adjacent with no gap: x 36, 205, 357, 477, 568, 699, 785, 890; no dropdown chevrons on desktop
- actions:
  - Search: input 169x38 fill #13171f, no border, radius 0; submit button 48x38 fill #2672de, radius 0 4px 4px 0, white 24px search--white.svg icon; hover fill #0050d8. Group starts x 718, y 43
  - Read website standards: outline button 219x38 at x 951, transparent fill, text 16px Public Sans 700 #e5a000, 2px inset ring #e5a000 (box-shadow inset 0 0 0 2px), radius 4px, padding 12px 16px 12px 20px; hover text and ring #FFFFFF
  - Download v3.14.0: outline button 170x38 at x 1178, text 16px 700 rgba(255,255,255,0.7) with 2px inset ring rgba(255,255,255,0.7), radius 4px; hover text and ring #FFFFFF. Label verbatim "Download v3.14.0"
  - GitHub: 32x32 GitHub mark at x 1360 (link box 40x56 at x 1356), fill rgba(255,255,255,0.7) at rest, #FFFFFF on hover; screen-reader text "View on GitHub", href https://github.com/uswds/uswds
- sticky: row 2 (white primary nav) is position sticky; the dark row 1 and the banner scroll away
- phone: Banner 48px, then a 48px #252f3e bar: star x 16 + "USWDS" 15.04px 700 #FFFFFF; at right a 62x48 "MENU" button, fill #005ea2, 12.96px 400 #FFFFFF uppercase, radius 0. MENU opens a 240px white drawer from the right over a dimmed page: a 48x48 close X (#f0f0f0 square) at top right, then the eight links (16px 400 #5c5c5c, ~43px rows with 1px #dfe1e2 dividers, "+" toggles on all but Design principles), then the search field (#005ea2 button), "Read website standards" and "Download v3.14.0" as outline buttons with #005ea2 text and ring, and a solid #005ea2 "View on GitHub" button with the white GitHub mark.

**Hero**
- summary: Light-gray band. Left: a thin 2-line h1, a thin 2-line lead and two flat solid buttons side by side. Right: a large line illustration of UI screens, set as the section background and cropped by the band bottom.
- desktop: band y 150-501 (351px), padding 48px top, 64px bottom, ground #f0f0f0; columns single text column 480px wide (x 52-532); the illustration is a CSS background, not a column: background-position calc(50% + 240px) 12px, background-size auto 400px, no-repeat, so at 1440 the art spans roughly x 750-1170 (left edge about 30px right of the page centre) and is cut off at the band bottom (400px tall from y 162, band ends y 501); anchors y h1 y 198, lead y 312, buttons y 399; gaps h1 (94px, 2 lines) -> 20px -> lead (67px, 2 lines) -> 20px -> buttons; text max width 480; media frame no frame, no radius, no shadow; illustration sits on the #f0f0f0 ground; cta two 38px buttons, 12px apart: "Introducing USWDS 3.0" 215px at x 52, "Migrating to USWDS 3.0" 221px at x 279
- phone: order illustration first (feature-image-phone.webp, background-size 100% at background-position 0 16px, i.e. 390x228 from y 112), then h1, lead, buttons; band y 96-759, padding-top 265.2px (68% of width, reserving the illustration), 32px bottom; alignment left, 16px gutters, text 358px wide; sizes h1 36px/46.8px 200 (3 lines, y 362), lead 24px/33.6px 200 (3 lines, y 522), buttons full width 358x38 stacked 8px apart (y 643 and 689)
- at rest: Static. Nothing animates.
- media: desktop https://designsystem.digital.gov/assets/img/introducing-uswds-2-0/feature-image-homepage.svg; phone https://designsystem.digital.gov/assets/img/webp/introducing-uswds-2-0/feature-image.webp; note Line illustration of phone, tablet and desktop UI fragments in #171717 strokes on #f0f0f0 with flat accents (#ee601d orange, #252f3e navy, #ffbe2e yellow, #2672de/#0076d6 blues, a small US flag). viewBox 486x453.
- type: h1 36px/46.8px (line-height 1.3) Public Sans 200, rgba(0,0,0,0.8) (#303030 on the gray), sentence case ending with a full stop; lead 24px/33.6px Public Sans 200, same color
- cta: Primary pair: "Introducing USWDS 3.0" fill #d83933 (secondary), hover #b50909; "Migrating to USWDS 3.0" fill #0050d8 (primary-vivid), hover #162e51. Both 16px/14.4px Public Sans 400 #FFFFFF, padding 12px 20px, radius 4px, no border, no shadow; focus ring 4px solid #2491ff, offset 4px. Note weight 400 here, not the default 700.
- proof: none in the hero

**Graphic list (four entry points)**
- summary: Four equal columns, each a red 72px circle icon, a bold head, one sentence and an underlined link.
- ground: #fcfcfc (page ground)
- desktop: y 502-846; padding 64px top and bottom; 4 columns of 342px (x 36, 378, 720, 1062) with 16px inner padding, so content x 52, 394, 736, 1078, 310px wide. Icon 72x72 at y 566 stacked above the text; head at y 654 (16px below the icon), body at y 683, link 6px under the body.
- phone: y 760-1408; padding 32px 16px; one column; each item is a row: 72px icon at x 16, text block at x 108 (20px gap), 266px wide; items 151px apart (heads at y 792, 943, 1072, 1224).
- anatomy:
  - Icon: 70x70 SVG circle #d83933 with white line glyph and #e9695f inner fills, rendered 72x72; order Components (ui-component.svg), Patterns (page-templates.svg), Design tokens (design-tokens.svg), Utilities (utilities.svg)
  - Head (h2): 16.96px/25.44px Public Sans 700, rgba(0,0,0,0.8) (#323232 on #fcfcfc), labels "Components", "Patterns", "Design tokens", "Utilities"
  - Body: 15.04px/22.56px 400, rgba(0,0,0,0.8); 2-3 lines in 310px
  - Link: 15.04px 400 #005ea2 underlined, hover #1a4480; labels in order "Browse components" (/components/), "Explore pattern guidance" (/patterns/), "View design tokens" (/design-tokens/), "Build with utilities" (/utilities/)
  - No cards, borders, backgrounds or shadows: the columns sit straight on the ground
- components:
  - usa-graphic-list
  - usa-media-block
  - link

**Sites built with USWDS (showcase)**
- summary: Gray band with a bold h2 and a 3x2 grid of 16:9 site screenshots, each captioned by a bold underlined external link.
- ground: #f0f0f0
- desktop: y 845-1627; padding-top 64px, 64px below the last row. h2 "Sites built with USWDS" 28px/33.6px 700 at y 909, x 52. Row 1 images at y 967 (24px below the h2), row 2 at y 1289 (48px between rows). 3 columns at x 52, 508, 964 (456px stride, 32px gutter), each image 424x239 (16:9), no radius, box-shadow 0 1px 4px rgba(0,0,0,0.1). Caption link 10px below the image (y 1216 / 1538).
- phone: y 1408-2945; padding 32px 0; h2 at y 1440, x 16; one column, images 358x201 at x 16, 237px rhythm (image, 10px, link, ~5px, next image).
- anatomy:
  - Order, left to right then row 2: National Institutes of Health Library (https://www.nihlibrary.nih.gov/), U.S. Department of Veterans Affairs (https://www.va.gov/), NASA Glenn Research Center (https://www1.grc.nasa.gov/), PubMed | U.S. National Library of Medicine (https://pubmed.ncbi.nlm.nih.gov/), vote.gov (https://vote.gov/), America’s Seed Fund (https://seedfund.nsf.gov/)
  - Caption link: 16.96px/27.136px Public Sans 700 #005ea2 underlined, hover #1a4480, followed by a 15px launch (external-link) icon in #005ea2 with 2px left margin (mask of launch.svg, currentColor); hidden "External." text for screen readers
  - Screenshots are real site captures (webp), not illustrations; no frame beyond the 4px soft shadow
- components:
  - grid
  - external link

**Footer**
- summary: Three stacked parts: a light-gray community band with four contact media blocks, a mid-gray v1 strip, then the dark USWDS identifier with the GSA logo, required links and the USA.gov line.
- ground: #e6e6e6 community band; #adadad v1 strip; #1b1b1b identifier
- anatomy:
  - Community band (#e6e6e6), desktop y 1627-1892, padding-top 32px: h2 "Become part of the community" 20px/24px 700 #1b1b1b at y 1659; paragraph 16px/25.6px 400 #1b1b1b, 596px wide, 3 lines: "USWDS is an active open source community of government engineers, content specialists, and designers. Our contributors both in and out of government support dozens of agencies and nearly 200 sites."
  - Contact row at y 1808: 4 columns at x 52, 390, 728, 1066 (338px stride); each a 40px #00bde3 circle (accent-cool) holding a 24px white Material icon, 8px gap, then h3 14.08px/19.7px 400 #1b1b1b and a 14.08px underlined link in #2f4668
  - Contact items in order: "Have an idea or an issue?" / "Reach out in GitHub" (https://github.com/uswds/uswds/issues/new/choose, help icon); "Engage with the community" / "Find a channel that works for you" (/about/community/, people icon); "Subscribe to our newsletter" / "Sign up for USWDS updates" (govdelivery, mail icon); "Get support" / "Email the USWDS team" (mailto:uswds@gsa.gov, support icon). External ones carry the launch icon
  - v1 strip (#adadad, padding 8px 0, 36px tall): 15.04px #1b1b1b "Looking for USWDS v1 documentation?" then bold underlined #1b1b1b link "Visit v1.designsystem.digital.gov" (https://v1.designsystem.digital.gov)
  - Identifier (#1b1b1b, padding-bottom 16px), masthead padding-top 16px: 48x48 GSA logo (gsa-logo.svg, #00538e square, white letters) at x 52, then at x 116 the domain "designsystem.digital.gov" 16px/22.4px 400 #adadad and "An official website of the General Services Administration" 16px 700 #FFFFFF with "General Services Administration" a #e6e6e6 underlined link to https://gsa.gov plus launch icon
  - Required links (nav, padding-top 8px): 15.04px/21px 400 #adadad underlined, hover #e6e6e6, in a 4-column grid flowing down: column 1 "About GSA", "Accessibility statement"; column 2 "FOIA requests", "No FEAR Act data"; column 3 "Office of the Inspector General", "Performance reports"; column 4 "Privacy policy". Rows at y 2016 and 2046, columns x 52, 394, 736, 1078. Each carries the launch icon
  - USA.gov line (padding-top 16px): "Looking for U.S. government information and services?" 16px 400 #FFFFFF then "Visit USA.gov" 16px 700 #e6e6e6 underlined (https://www.usa.gov/) with launch icon
  - No copyright line, no postal address and no phone number appear on the page
- phone: Community band y 2944-3440 with 16px gutters: h2 y 2960, paragraph 128px tall, contact items stacked one per row (icon x 24, text x 64), 64px rhythm. v1 strip y 3440-3495 wraps to 2 lines. Identifier y 3496-4041: GSA logo above the identity text (logo y 3512, domain y 3576), required links one per row at 16px/22.4px with 35px rhythm, USA.gov line wraps to 2 lines.

**On dark grounds**
- secondary button: outline: transparent fill, 2px inset ring and 16px 700 text in rgba(255,255,255,0.7) (or #e5a000 for the standards CTA), radius 4px; hover ring and text #FFFFFF
- link: #e6e6e6 underlined (identifier); required links #adadad underlined, hover #e6e6e6
- muted text: #adadad
- hairline: none used on the dark grounds
- logo variant: USWDS star 4c-lg-on-black.svg on #252f3e; GSA logo (#00538e square) on #1b1b1b

## Components

- **button hero secondary** (observed): fill #d83933, text #FFFFFF, border none, radius 4, padding 12px 20px, height 38, example Introducing USWDS 3.0 (215x38), text style 16px/14.4px Public Sans 400, face body, font size 16, weight 400, padding x 20, weight note Labels are 400 (class text-normal), measured 2026-10-30; not bold.
  - hover (observed): fill #b50909
  - focus (observed): outline 4px solid #2491ff, outline-offset 4px
  - active (published): background-color #8b0a03
- **button hero primary** (observed): fill #0050d8, text #FFFFFF, border none, radius 4, padding 12px 20px, height 38, example Migrating to USWDS 3.0 (221x38), text style 16px/14.4px Public Sans 400, face body, font size 16, weight 400, padding x 20, weight note Labels are 400 (class text-normal), measured 2026-10-30; not bold.
  - hover (observed): fill #162e51
  - focus (observed): outline 4px solid #2491ff, outline-offset 4px
- **button outline on dark** (observed): fill transparent, text rgba(255,255,255,0.7), border none; ring is box-shadow inset 0 0 0 2px currentColor, ring px 2, ring rgba(255,255,255,0.7), radius 4, padding 12px 16px 12px 20px, height 38, example Download v3.14.0 (170x38), text style 16px Public Sans 700, face body, font size 16, weight 700, padding x 18, variant gold Read website standards: text and ring #e5a000 (warning-dark)
  - hover (observed): text #FFFFFF, ring #FFFFFF
- **button outline on light** (observed): fill transparent, text #005ea2, ring px 2, ring #005ea2, radius 4, height 38, example Phone drawer: Read website standards / Download v3.14.0, text style 16px Public Sans 700, face body, font size 16, weight 700, padding x 18
- **search small** (observed): input 169x38, fill #13171f on the dark header (white field with #005ea2 button in the phone drawer), radius 0, no border, Source Sans Pro Web 16.96px, button 48x38, fill #2672de, radius 0 4px 4px 0, 24px white magnifier (search--white.svg); hover #0050d8
- **link** (observed): color #005ea2, hover #1a4480, visited #54278f (published), decoration underline always, external launch icon after the text, same color as the link, ~0.9em, 2px gap
- **graphic list item** (observed): icon 72px red circle SVG, head 16.96px 700, body 15.04px 400, link 15.04px #005ea2 underlined, gap icon->head 16px (desktop, stacked); 20px icon->text (phone, side by side)
- **contact media block** (observed): icon 40px circle #00bde3 (accent-cool), 24px white Material icon, gap 8, head 14.08px 400 #1b1b1b, link 14.08px #2f4668 underlined
- **nav link** (observed): text 15.04px 400 #1b1b1b, padding 16, height 48, hover text #2672de plus a 4px #2672de bar at the bottom, inset 16px left and right

## Icon tokens

Grid not published (Material Icons-derived glyphs), stroke not published (filled glyphs) (published).
| Name | Size | Use |
|---|---|---|
| size-3 | 24px | .usa-icon--size-3 (3 units) |
| size-4 | 32px | .usa-icon--size-4 (4 units) |
| size-5 | 40px | .usa-icon--size-5 (5 units) |
| size-6 | 48px | .usa-icon--size-6 (6 units) |
| size-7 | 56px | .usa-icon--size-7 (7 units) |
| size-8 | 64px | .usa-icon--size-8 (8 units) |
| size-9 | 72px | .usa-icon--size-9 (9 units) |

## Signature moves

### Official government banner

Where: top of every page, directly after the skip link.
Do: thin strip on $theme-banner-background-color (default base-lightest #f0f0f0; the docs site runs it dark) with the small US flag, 12-13px text "An official website of the United States government" and a "Here's how you know" accordion that explains .gov and HTTPS (lock icon). Text used unaltered.
Don't: customize the banner text, use it on a non-.gov/.mil or non-HTTPS site, or style it to draw attention.
Example: "An official website of the United States government".

### Identifier footer

Where: the very bottom of every page, below the site footer.
Do: dark band (primary or base grade 80+, or black) with the parent agency logo, the domain, "An official website of the [agency]" and the federally required links (About, Accessibility statement, FOIA, No FEAR Act, OIG, Performance reports, Privacy policy), then the USA.gov line.
Don't: delete required links, add a product logo in place of the agency logo, or use colors that draw attention.
Example: "Looking for U.S. government information and services? Visit USA.gov".

### Token-only, grade-checked color

Where: every color on the page.
Do: pick only USWDS tokens; pair text and ground by grade difference ("magic number") of 50+ for AA body text (40+ for large text, 70+ for AAA); primary/secondary/accent in roughly 60/30/10 proportion of non-base color.
Don't: use custom hexes, or rely on color alone to carry meaning.

### Solid 4px-radius buttons in primary blue and secondary red

Where: primary actions; the homepage hero pairs secondary red #d83933 and primary-vivid #0050d8.
Do: flat fill, white bold sentence-case label that starts with a verb, 4px radius, 12px x 20px padding, darker shade on hover, visible 4px #2491ff focus outline.
Don't: use buttons for page-to-page links, or crowd a page with many buttons.
Example: "Download".

## Messaging: rules

The homepage leads with a category claim ("The design system for the federal government.") and a plain benefit line about accessible, mobile-friendly websites. Key benefits frame six pillars for making the case to management, from compliance to stewardship.

Why it works: Government buyers need a reason that survives procurement: compliance and reuse of public money are the arguments, so the pillars are those.

- Lead with the benefit to government teams, then the requirement it satisfies (508, 21st Century IDEA).
- Quote numbers only as published (40+ components, nearly 200 sites).
- Describe USWDS as principles, guidance and code.
- Never promise full accessibility; teams must test their own work.

Sources: https://designsystem.digital.gov/, https://designsystem.digital.gov/about/key-benefits/, https://designsystem.digital.gov/how-to-use-uswds/, https://designsystem.digital.gov/documentation/accessibility/

## Voice: rules

USWDS has no standalone voice guide. Its voice shows in the design principles and component guidance: bold imperative lead-ins ("Start early.", "Lead with a verb.") followed by one or two plain sentences, "we" speaking to "you", sentence case throughout.

Why it works: Plain, instructive language serves the broadest public and doubles as accessibility practice (the principles tie plain language to trust).

|  |  |
|---|---|
| Tone | reliable, consistent, honest (Earn trust) |
| Person | we to you (observed) |
| Case | sentence case |
| Buttons | verb first, short |

- Write in plain language; expect readers to skim.
- Lead with a short imperative, then explain.
- Sentence case for headings and buttons.
- Start button labels with a verb; keep them short.
- Speak as "we" to "you".
- Don't long uppercase passages
- Don't long bold or italic passages
- Don't icons without text for anything but home, print or search
- Don't altered banner text

Do and don't:
- Do: "File a complaint". Verb first, sentence case (button guidance).
- Don't: "COMPLAINT FILING". Noun first and in capitals.

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Design principles page: bold principle names with plain explanations: https://designsystem.digital.gov/design-principles/

Sources: https://designsystem.digital.gov/design-principles/, https://designsystem.digital.gov/about/product-values/, https://designsystem.digital.gov/components/button/, https://designsystem.digital.gov/components/typography/

## Logo: rules

The USWDS mark is a five-point star built from five separate triangles in light blue, indigo, orange, peach and charcoal, set at 24px before "U.S. Web Design System (USWDS)" in Public Sans Bold in the dark header. A dark-ground version swaps the charcoal point to light gray. The identifier at the foot carries the parent agency (GSA) logo, not the product logo.

Why it works: A star echoes the flag without copying it; the identifier rule keeps product logos from masquerading as agency identity.

|  |  |
|---|---|
| Header size | 24px star (1.5rem) before wordmark (observed) |
| Identifier logo | SVG or 120px+ tall image |
| Star colors | #81aefc, #4d52af, #ee601d, #f6bd9c, #2e2e2e |

- Use the four-color star on light grounds and the on-black version on dark grounds.
- In the identifier, show the parent agency logo, not a product logo (identifier guidance).
- Use an SVG logo, or an image at least 120px tall, in the identifier.
- Add alt text "[Agency shortname] logo" and role="img" to SVG logos.
- Don't put a product logo in the identifier
- Don't omit logo alt text

Not published: clear space; minimum size; misuse examples for the USWDS star.

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- USWDS star, light-ground version: https://designsystem.digital.gov/
- Logo in the dark docs header: https://designsystem.digital.gov/

Sources: https://designsystem.digital.gov/, https://designsystem.digital.gov/components/identifier/, https://designsystem.digital.gov/assets/css/styles.css

## Color: rules

A system palette of 24 hue families (plus vivid variants), each graded 5-90 on a regularized lightness scale, feeds role-based theme tokens (base, primary, secondary, accent-cool, accent-warm) and state tokens (info, error, warning, success, emergency, disabled). Defaults: primary blue-60v #005ea2, secondary red-50 #d83933, ink gray-90 #1b1b1b.

Why it works: Because grades share luminance ranges across families, the grade difference alone predicts contrast: teams pick accessible pairs without a checker.

|  |  |
|---|---|
| Primary | blue-60v #005ea2 |
| Secondary | red-50 #d83933 |
| Ink | gray-90 #1b1b1b |
| Proportion | 60 / 30 / 10 (non-base) |
| Contrast | magic number 50+ for AA |

- Use USWDS color tokens; avoid custom colors.
- Proportion non-base color about 60% primary, 30% secondary, 10% accents.
- Magic number 40+ = AA large text; 50+ = AA; 70+ = AAA.
- Grade 50 passes AA against both white and black.
- AA contrast: 4.5:1 text, 3:1 large text (19px+ bold or 24px+).
- Start in black and white; add color to support the message.
- Put functional color (states) before emotional color.
- Icons need 3:1 against their ground.
- Don't use color as the only signal
- Don't pure black text on white for long reading (guidance suggests avoiding it)

Do and don't:
- Do: "Download". Primary blue fill, white bold label: grade 60 on white clears AA.
- Don't: "Download". accent-cool-light (grade 20) text on white: magic number below 40 fails contrast.

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Using color: grades and magic number: https://designsystem.digital.gov/design-tokens/color/overview/
- System color tokens table: https://designsystem.digital.gov/design-tokens/color/system-tokens/

Sources: https://designsystem.digital.gov/design-tokens/color/overview/, https://designsystem.digital.gov/design-tokens/color/system-tokens/, https://designsystem.digital.gov/design-tokens/color/theme-tokens/, https://designsystem.digital.gov/design-tokens/color/state-tokens/

## Typography: rules

Four open faces ship with USWDS: Public Sans (its own), Source Sans Pro, Merriweather, Roboto Mono. The default theme sets headings in Merriweather and body/UI in Source Sans Pro; the docs site itself runs on Public Sans, with thin 200-weight hero type and bold 700 section heads. Size tokens are normalized so each step looks the same in any supported face.

Why it works: Normalization lets agencies swap typefaces without breaking layouts; neutral sans faces keep interfaces tool-like.

|  |  |
|---|---|
| Display (docs site) | Public Sans 200, 36px hero h1 |
| Body (docs site) | Public Sans 400, 16px / 1.6 |
| Default theme | Merriweather headings, Source Sans Pro body |
| Weights | light 300, normal 400, bold 700 |
| Line heights | 1, 1.15, 1.35, 1.5, 1.62, 1.75 |
| Measure | 44, 60, 64, 68, 72, 88ex |

- Body text at least 16px (font-size 5); most running text 16-20px.
- Line length 45-90 characters; target 66 (measure 2).
- Line height 1-1.35 for headings, at least 1.5 for longer text; 1.62 for most reading.
- Flush left; no justified text.
- At least 1em between paragraphs; 1.5x more space above a heading than below.
- Tighten large headings: -1 at size 9+, -2 at 12+, -3 at 17+.
- Loosen tracking for uppercase and micro text.
- Theme scale 12, 14, 16, 17, 18, 24, 32, 40, 56px.
- Don't indent paragraphs
- Don't set long passages in caps, bold or italic

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Font tokens and the theme type scale: https://designsystem.digital.gov/design-tokens/typesetting/font/

Sources: https://designsystem.digital.gov/components/typography/, https://designsystem.digital.gov/design-tokens/typesetting/font/, https://designsystem.digital.gov/design-tokens/typesetting/overview/, https://designsystem.digital.gov/design-tokens/typesetting/line-height/, https://designsystem.digital.gov/design-tokens/typesetting/font-weight/, https://designsystem.digital.gov/design-tokens/typesetting/letterspacing/, https://designsystem.digital.gov/design-tokens/typesetting/measure/, https://designsystem.digital.gov/documentation/settings/

## Graphic elements: rules

The recognizable furniture is functional: the official banner strip with the flag, a dark header band, 72px solid circles holding white line icons (red on the homepage graphic list, cyan in the community row), flat 4px-radius buttons, a gray showcase band, and the dark identifier. The homepage hero carries a flat outline illustration of browser windows with orange, navy, yellow and red blocks and a small star.

Why it works: Every element maps to a component in the system, so the brand is the system in use.

|  |  |
|---|---|
| Icon circle | 72px circle, white icon (graphic list, observed) |
| Radius | sm 2, md 4, lg 8, pill |
| Shadow 1 | 0 1px 4px rgba(0,0,0,.1) |

- Banner first, identifier last, on every page.
- Use components as published; contribute changes back.
- Shadows only from tokens 1-5 (rgba 0,0,0,0.1).
- Radius from tokens: 0, 2, 4, 8px or pill.
- Don't invent components that duplicate existing ones

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Homepage hero illustration: https://designsystem.digital.gov/
- Graphic list icon in a red circle: https://designsystem.digital.gov/

Sources: https://designsystem.digital.gov/, https://designsystem.digital.gov/components/banner/, https://designsystem.digital.gov/components/identifier/, https://designsystem.digital.gov/design-tokens/shadow/, https://designsystem.digital.gov/utilities/border/

## Iconography: rules

243 icons, mostly from Google Material Icons plus USWDS additions, delivered as an SVG sprite. Icons inherit currentColor and scale with font size, with size variants 3-9 units (24-72px).

|  |  |
|---|---|
| Sizes | 24-72px (size-3 to size-9) |
| Color | currentColor |
| Contrast | 3:1 |
| Set | Material Icons (Apache 2.0) + USWDS |

- Pair icons with text.
- One icon, one meaning, everywhere on a site.
- Hide decorative icons (aria-hidden); label meaningful ones.
- 3:1 contrast against the ground.
- Put icons inside their link.
- Change only color; never alter icons.
- Don't use icons as illustration
- Don't rely on icons to fix unclear hierarchy
- Don't customize or combine icons

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Homepage graphic list icon: https://designsystem.digital.gov/

Sources: https://designsystem.digital.gov/components/icon/

## Illustration: rules

The only illustration is the homepage hero: flat outlined browser frames and phones with blocks of orange, navy, yellow and red, dashed connector lines and a star. The icon guidance says to use illustration, not icons, for visual explanation.

- Use illustration, not icons, to explain a concept (icon guidance).

Not published: illustration style guidance.

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Homepage hero illustration: https://designsystem.digital.gov/

Sources: https://designsystem.digital.gov/, https://designsystem.digital.gov/components/icon/

## Photography: rules

The homepage uses screenshots of real government sites built with USWDS (NIH Library, VA, NASA Glenn, PubMed, vote.gov, America's Seed Fund) as proof, each with a light shadow. No photography guidance is published.

- Show real sites as proof (observed pattern).
- Avoid alarming images (accessibility guidance for sensory-sensitive users).

Not published: photography style guidance.

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Showcase: vote.gov: https://designsystem.digital.gov/
- Showcase: NASA Glenn Research Center: https://designsystem.digital.gov/

Sources: https://designsystem.digital.gov/, https://designsystem.digital.gov/documentation/accessibility/

## Motion: rules

No motion tokens or easing are published. Accessibility guidance asks teams to avoid flashing and repetitive animation, and USWDS disables nonessential header transitions under reduced-motion.

- Avoid flashing and repetitive animation.
- Respect prefers-reduced-motion.
- No autoplaying audio or video; let users pause content.

Not published: durations; easing curves.

Sources: https://designsystem.digital.gov/documentation/accessibility/, https://designsystem.digital.gov/components/header/

## Interface and layout: rules

A mobile-first 12-column flexbox grid in a container capped at 1024px (desktop), with 16px side padding on phones and 32px at desktop. Spacing comes from an 8px unit. Landing pages follow the published template: extended header, hero, graphic list, buttons, grid, medium footer.

|  |  |
|---|---|
| Container | 1024px max |
| Columns | 12 |
| Site margin | 16px mobile, 32px desktop |
| Unit | 8px |
| Breakpoints | mobile-lg 480, tablet 640, desktop 1024, widescreen 1400 |

- Use grid-container (max 1024px) and 12 columns.
- Gutters: grid-gap 16px, 32px at desktop; grid-gap-lg 32px.
- Spacing in 8px units (4, 12, 20px half steps).
- Keep landing pages simple: no forms or side navigation.
- Remove unneeded template parts instead of filling them.

Real examples, to look at on U.S. Web Design System's own pages (not for reuse):
- Spacing unit tokens: https://designsystem.digital.gov/design-tokens/spacing-units/

Sources: https://designsystem.digital.gov/utilities/layout-grid/, https://designsystem.digital.gov/design-tokens/spacing-units/, https://designsystem.digital.gov/templates/landing-page/, https://designsystem.digital.gov/documentation/settings/

## Rules: rules

- Follow the five design principles.
- Use tokens for every value.
- Show the official banner and identifier on every page.
- Meet WCAG 2.1 AA; test your own implementation.
- Use .gov and HTTPS before using the banner.
- Adopt incrementally: principles, guidance, code.
- Don't use custom colors when a token exists
- Don't convey meaning with color alone
- Don't alter banner text or icons
- Don't use the banner or identifier on test or unofficial sites
- Don't use buttons for navigation between pages

Sources: https://designsystem.digital.gov/design-principles/, https://designsystem.digital.gov/design-tokens/color/overview/, https://designsystem.digital.gov/components/banner/, https://designsystem.digital.gov/components/identifier/, https://designsystem.digital.gov/documentation/accessibility/, https://designsystem.digital.gov/maturity-model/

## Applications

| Format | What | Source |
|---|---|---|
| agency websites | NIH Library, VA, NASA Glenn, PubMed, vote.gov and America's Seed Fund are shown as sites built with USWDS. | https://designsystem.digital.gov/ |
| landing page template | Published template: extended header, hero, graphic list, buttons, grid, medium footer. | https://designsystem.digital.gov/templates/landing-page/ |

## By format

How our engine applies USWDS to each format: our recipe from their published tokens and components. Loudness runs 0 (nothing but the essentials) to 5 (the signature moves at full volume).

| Format | Loudness 0–5 | Must appear | What varies |
|---|---|---|---|
| Landing page | 2 | Follow kit.spec.page (the designsystem.digital.gov homepage, observed 2026-10-30): official #1b1b1b gov banner; #252f3e header with the USWDS star, "U.S. Web Design System (USWDS)" in Public Sans 700, search and two 2px-ring outline buttons; white 48px sticky nav of 8 links; #f0f0f0 hero with a Public Sans 200 36px h1, 200 24px lead and two flat 4px-radius buttons (#d83933, #0050d8) beside the line illustration; a 4-up graphic list of 72px red circle icons with bold heads and underlined #005ea2 links on #fcfcfc; a #f0f0f0 3x2 showcase of 16:9 screenshots with bold external links; a #e6e6e6 community band with #00bde3 icon circles; a #adadad v1 strip; the #1b1b1b GSA identifier with required links. 1400px container with 32px padding, 64px section padding, 8px unit. | theme families and typeface (the default theme uses Source Sans Pro/Merriweather and a 1024px container), number of graphic list items and showcase sites, hero illustration |
| Documentation page | 1 | Banner, header, side navigation, Public Sans prose at 16px/1.6 within measure 2-5, tokens tables, identifier | section depth |
| Form or transaction | 0 | Default components untouched, step indicator, plain labels, primary button with a verb | none beyond theme color |
| Slide deck | 1 | White or #f0f0f0 grounds, Public Sans, primary blue and secondary red used 60/30, sentence case | accent use |

## Checks before anything ships

- **Logo hidden**: Cover the star. It should still read as USWDS: the flag banner on top, blue and red flat buttons, Public Sans, and the dark identifier at the foot.
- **Contrast by grade**: Every text/ground pair differs by 50+ grades (40+ for large text); no meaning carried by color alone.

## Make it your own

Keep the system: color roles and proportions, type, layout, components, the signature moves, the voice traits and rules. Replace everything that is U.S. Web Design System's own: name and logo, positioning, pillars, proof, taglines, boilerplate and any real line quoted above. kit.json lists these under make_it_yours.

## Not published

- Logo usage rules for the USWDS star (clear space, minimum size, misuse): not published.
- Logo colors: the orange point #ee601d is not a system color token; the other four match tokens (observed in the SVG).
- Brand voice and tone guide: not published (voice taken from design principles, product values and component guidance).
- Banned words or terminology list: not published.
- Photography guidance: not published.
- Illustration style guidance: not published.
- Motion tokens, easing and durations: not published.
- A muted-text color role: not published (base-dark #565c65 is our reading).
- The docs site's own theme (Public Sans, thin hero type, #252f3e header) is observed from its CSS, not published as guidance.
- Proportions beyond the 60/30/10 non-base color split: not published.

Logos and reference images belong to U.S. Web Design System. Look at them on U.S. Web Design System's own pages; don't reuse them.