U.S. Web Design System

For Published

Federal digital service teams: content managers, designers and developers, plus the agencies and contractors who build government sites.

Problem Published

Federal requirements (Section 508, 21st Century IDEA) are confusing, and every team rebuilding basic components wastes public money.

Promise Published

Accessible, mobile-friendly, compliant sites from the start, improving as the system improves.

Mission Published

Shaping the future of government digital services.

Proof behind each pillar

• Compliance from the start. Over 40 accessible, mobile-friendly components out of the box (47 listed on the components page).
• Compliance from the start. Components are tested against WCAG 2.1 AA, above the 2.0 AA legal baseline.
• Proven design solutions users expect. Contributors support dozens of agencies and nearly 200 sites.
• Proven design solutions users expect. Sites using USWDS topped 1.4 billion pageviews in Q2 2018.
• Team alignment. Five design principles: start with real user needs, earn trust, embrace accessibility, promote continuity, listen.
• Mission focus. 243 icons in the icon component.
• Mission focus. 24 color families in the system palette, each graded 5-90 for predictable contrast.
• A cross-government community. Open source on GitHub with public GitHub Discussions.
• Stewardship of public resources. Created in 2015 by 18F and the U.S. Digital Service with an advisory board from seven agencies.

Story Published

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.

Values

Category. A government design system: principles, guidance and code (a toolkit), maintained as open source by GSA. Published

Why them

1. Built by government, for government, with government. Published
2. Compliance (508, 21st Century IDEA) designed in from the start. Published
3. Color grades regularized so a "magic number" guarantees contrast. Published
4. Type normalized so each size token looks the same in any supported face. Published
5. Adopt incrementally: principles, then guidance, then code (maturity model). Published

Instead of

Building components and patterns from scratch for each site (the "redesign treadmill").

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

They never claim

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

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.

Source: designsystem.digital.govdesignsystem.digital.gov/about/key-benefitsdesignsystem.digital.gov/how-to-use-uswdsdesignsystem.digital.gov/documentation/accessibility

• 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

reliableconsistenthonestplain

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.

• 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".

• 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.

Source: designsystem.digital.gov/design-principlesdesignsystem.digital.gov/about/product-values

Source: designsystem.digital.gov/design-principlesdesignsystem.digital.gov/about/product-valuesdesignsystem.digital.gov/components/buttondesignsystem.digital.gov/components/typography

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.

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

Source: designsystem.digital.govdesignsystem.digital.gov/components/identifierdesignsystem.digital.gov/assets/css/styles.css

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.

Source: designsystem.digital.gov/design-tokens/color/overviewdesignsystem.digital.gov/design-tokens/color/system-tokensdesignsystem.digital.gov/design-tokens/color/theme-tokensdesignsystem.digital.gov/design-tokens/color/state-tokens

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.

Source: designsystem.digital.gov/components/typographydesignsystem.digital.gov/design-tokens/typesetting/fontdesignsystem.digital.gov/design-tokens/typesetting/overviewdesignsystem.digital.gov/design-tokens/typesetting/line-heightdesignsystem.digital.gov/design-tokens/typesetting/font-weightdesignsystem.digital.gov/design-tokens/typesetting/letterspacingdesignsystem.digital.gov/design-tokens/typesetting/measuredesignsystem.digital.gov/documentation/settings

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.

Source: designsystem.digital.govdesignsystem.digital.gov/components/bannerdesignsystem.digital.gov/components/identifierdesignsystem.digital.gov/design-tokens/shadowdesignsystem.digital.gov/utilities/border

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).

Source: designsystem.digital.gov/components/icon

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.

Not published: illustration style guidance.

Source: designsystem.digital.govdesignsystem.digital.gov/components/icon

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.

Not published: photography style guidance.

Source: designsystem.digital.govdesignsystem.digital.gov/documentation/accessibility

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.

Not published: durations; easing curves.

Source: designsystem.digital.gov/documentation/accessibilitydesignsystem.digital.gov/components/header