---
version: alpha
name: USWDS Federal Service Interface
description: "A United States public-service interface derived from USWDS federal patterns. It uses tokenized blue action semantics, cool-gray civic surfaces, Public Sans-style typography, official-site trust rails, banner and identifier anchors, accessible forms, alerts, summary boxes, step indicators, modest cards, and responsive 8px rhythm for federal services, benefit portals, public data, compliance flows, and high-trust civic products."

colors:
  primary: "#005ea2"
  primary-vivid: "#0050d8"
  primary-dark: "#1a4480"
  primary-darker: "#162e51"
  on-primary: "#ffffff"
  secondary: "#d83933"
  secondary-dark: "#b50909"
  accent-cool: "#00bde3"
  accent-cool-dark: "#07648d"
  accent-warm: "#fa9441"
  accent-warm-dark: "#c05600"
  ink: "#1b1b1b"
  body: "#3d4551"
  muted: "#565c65"
  canvas: "#ffffff"
  surface-card: "#ffffff"
  surface-soft: "#f0f0f0"
  surface-tint: "#e1f3f8"
  hairline: "#dfe1e2"
  hairline-strong: "#a9aeb1"
  focus: "#face00"
  error: "#b50909"
  warning: "#ffbe2e"
  success: "#00a91c"
  info: "#005ea2"
  identifier: "#1a4480"
  inverse-canvas: "#111827"
  inverse-surface: "#1f2937"
  inverse-card: "#243447"
  inverse-ink: "#f8fafc"
  inverse-body: "#dfe1e2"
  inverse-hairline: "#4b5563"

typography:
  display-xl:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 56px
    fontWeight: 700
    lineHeight: 1.05
    letterSpacing: 0
  display-lg:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 40px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: 0
  heading-md:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 24px
    fontWeight: 700
    lineHeight: 1.25
    letterSpacing: 0
  heading-sm:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 18px
    fontWeight: 700
    lineHeight: 1.35
    letterSpacing: 0
  body-lg:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 22px
    fontWeight: 400
    lineHeight: 1.45
    letterSpacing: 0
  body:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.55
    letterSpacing: 0
  body-sm:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.45
    letterSpacing: 0
  label:
    fontFamily: "Public Sans, Source Sans Pro, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
    fontSize: 13px
    fontWeight: 700
    lineHeight: 1.35
    letterSpacing: 0
  mono:
    fontFamily: "Roboto Mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
    fontSize: 13px
    fontWeight: 500
    lineHeight: 1.5
    letterSpacing: 0

rounded:
  none: 0px
  xs: 2px
  sm: 4px
  md: 6px
  lg: 8px
  pill: 9999px

spacing:
  base: 8px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
  xxl: 48px
  section: 80px

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body}"
    rounded: "{rounded.sm}"
    padding: 12px 20px
  button-secondary:
    backgroundColor: "{colors.surface-card}"
    textColor: "{colors.primary}"
    typography: "{typography.body}"
    rounded: "{rounded.sm}"
    padding: 11px 18px
    borderColor: "{colors.primary}"
  banner:
    backgroundColor: "{colors.surface-soft}"
    textColor: "{colors.ink}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.none}"
    padding: 8px 16px
  identifier:
    backgroundColor: "{colors.identifier}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-sm}"
    rounded: "{rounded.none}"
    padding: 32px
  alert:
    backgroundColor: "{colors.surface-tint}"
    textColor: "{colors.body}"
    typography: "{typography.body}"
    rounded: "{rounded.sm}"
    padding: 16px 20px
    borderColor: "{colors.info}"
  text-input:
    backgroundColor: "{colors.canvas}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    rounded: "{rounded.sm}"
    padding: 10px 12px
    borderColor: "{colors.ink}"

layout:
  content-width: "64rem maximum service container, with task text often constrained to 40rem."
  grid: "12-column grid with 8px unit spacing; side navigation and process rails support complex services."
  rhythm: "Use multiples of 8px through tokenized spacing units. The unit scale is functional and should map to Sass tokens or CSS variables."
  surfaces: "White service canvas, cool-gray groups, blue trust/action rails, and dark identifier blocks."

guidance:
  do:
    - "Lead with the service task, eligibility, official-site trust, and next action."
    - "Use the banner and identifier only when they honestly represent official government context."
    - "Map color through theme tokens instead of arbitrary hex values in production USWDS builds."
    - "Keep form control order identical in DOM and visual layout."
    - "Use alerts, summary boxes, and step indicators to reduce recovery cost."
  dont:
    - "Do not use the official banner on non-government domains or marketing mockups."
    - "Do not copy agency seals, logos, flags, or federal marks without proper authority."
    - "Do not turn federal service pages into campaign-style hero layouts."
    - "Do not rearrange form controls with CSS or hide required context in accordions."
    - "Do not invent decorative uses for semantic red, warning, or trust blue."

caseStudy:
  source: "U.S. Web Design System official documentation, components, design tokens, and code guidelines"
  urls:
    - "https://designsystem.digital.gov/"
    - "https://designsystem.digital.gov/design-tokens/"
    - "https://designsystem.digital.gov/design-tokens/color/theme-tokens/"
    - "https://designsystem.digital.gov/design-tokens/typesetting/font/"
    - "https://designsystem.digital.gov/components/banner/"
    - "https://designsystem.digital.gov/components/identifier/"
    - "https://designsystem.digital.gov/components/form/"
    - "https://designsystem.digital.gov/components/button/"
    - "https://designsystem.digital.gov/documentation/code-guidelines/"
    - "https://github.com/uswds/uswds"
    - "https://github.com/uswds/uswds-for-designers"
  analysis: "USWDS frames federal interfaces as accessible, mobile-friendly government services built from components, patterns, tokens, and utilities. Its theme color system uses role families such as base, primary, secondary, accent-warm, and accent-cool; components such as banner and identifier communicate official site trust and required agency links; form guidance emphasizes DOM order, fieldsets, legends, and aligned validation; implementation guidance uses Sass settings and token functions. This Interface resource extracts those reusable rules without granting rights to copy federal agency marks."
---

# USWDS Federal Service Interface

Use this design system for U.S.-style public services, benefits applications, civic data portals, federal information pages, compliance workflows, emergency status pages, government-adjacent service portals, and regulated product flows where official identity, accessibility, mobile friendliness, legal links, and recoverable forms matter more than visual novelty.

The system is calm, modular, and explicit. Its signature is not a decorative brand moment; it is a chain of trust signals: official-site banner, task-first header, tokenized action colors, clear forms, alert language, progress guidance, and identifier footer.

## Overview

USWDS Federal Service turns government UX into a structured service contract. Each page should answer:

1. Is this an official or official-adjacent service?
2. Which agency or parent organization is responsible?
3. What task can the public complete here?
4. What information is required, optional, or sensitive?
5. How can the user recover from errors or find required legal links?

Use the resource as a civic service language, not as permission to impersonate an agency. The system works best when page copy, form structure, and official context are precise.

## Colors

### Brand & Accent

- `primary` (#005ea2) is the core link and action blue. Use it for primary buttons, important navigation, and service identity.
- `primary-vivid` (#0050d8) increases action salience, but it should remain token-governed and not become decorative.
- `secondary` (#d83933) is for destructive or high-salience secondary actions and selected warnings, not brand decoration.
- `accent-cool` (#00bde3) supports data, educational callouts, and non-critical category accents.
- `accent-warm` (#fa9441) supports attention and deadline emphasis; keep it short-lived and text-supported.

### Surface

- `canvas` (#ffffff) is the default reading surface.
- `surface-soft` (#f0f0f0) groups banner, metadata, low-emphasis cards, and service utility panels.
- `surface-tint` (#e1f3f8) supports informational alerts and highlighted guidance.
- `identifier` (#1a4480) anchors the bottom of official or agency-linked services.

### Text

- `ink` (#1b1b1b) is primary text and high-contrast UI chrome.
- `body` (#3d4551) supports long reading and structured body copy.
- `muted` (#565c65) is for hint text, timestamps, secondary labels, and utility descriptions.

### Semantic

- `error` (#b50909) is for validation errors and destructive risk.
- `warning` (#ffbe2e) flags deadline, attention, or potentially disruptive state.
- `success` (#00a91c) is for confirmation and completion.
- `focus` (#face00) must remain visible and high-contrast; do not soften it into a subtle brand outline.

## Typography

### Font Family

Use `Public Sans, Source Sans Pro, system-ui, sans-serif` for most UI. Public Sans is the recognizable federal-service voice, but a production implementation should load it intentionally and define CJK or local-language fallbacks when needed.

### Hierarchy

- `display-xl`: 56px/1.05 for service landing and major federal program pages.
- `display-lg`: 40px/1.1 for page titles and critical task headers.
- `heading-md`: 24px/1.25 for section headings, process steps, and card titles.
- `body`: 16px/1.55 for forms, explanations, and transactional content.
- `label`: 13px bold for field labels, tags, and compact metadata.
- `mono`: 13px for IDs, case numbers, status codes, and structured data.

### Principles

The type system is readable before expressive. Avoid ultra-large hero typography, negative tracking, decorative small caps, and thin display weights. Use bold sparingly to identify task names, field labels, and status headings.

### Note on Font Substitutes

If Public Sans is unavailable, Source Sans Pro or a strong system sans may substitute. Keep the same line-height, input sizes, and button padding so the service structure remains stable.

## Layout

### Spacing System

Use an 8px base unit. Most component padding maps to 8, 16, 24, 32, and 48px. Page sections should feel measured and inspectable, not airy like a marketing site.

### Grid & Container

The service container should max out near 64rem. Long-form tasks often use a 40rem text column with a supporting rail for help, status, or in-page navigation. Wide data pages may use full containers but should preserve the same token rhythm.

### Whitespace Philosophy

Whitespace should separate tasks, not create brand atmosphere. Dense legal or eligibility content needs summary boxes, side navigation, and step indicators instead of decorative section breaks.

## Elevation & Depth

USWDS Federal Service is mostly flat. Depth comes from hierarchy, borders, alert sidebars, and dark identifier blocks. Shadows are rare and should be reserved for overlays or drawers that truly interrupt context.

- Cards use 1px cool-gray borders and white surfaces.
- Alerts use colored left rails instead of heavy panels.
- Modals and dropdowns may use modest shadow only when needed for focus separation.
- Avoid glass, blurred layers, bokeh, and ambient gradients.

## Shapes

Corners are practical and restrained:

- Square or 2px corners for official rails, tables, and legal panels.
- 4px corners for buttons, inputs, alerts, and cards.
- 6-8px corners for larger grouped containers only.
- Pills only for tags, status chips, and language labels.

The system should not read as playful. Rounded geometry must never weaken input affordance or alert clarity.

## Components

### Buttons

Primary buttons use `primary` blue, sentence case, short verb-led labels, and minimum 44px tap height. Use buttons for actions, links for navigation, and avoid placing many equal-weight buttons on one page.

### Cards & Containers

Cards group related service objects: application status, document checklist, appointment details, program eligibility, or evidence requirements. They should have visible borders, clear headings, and direct actions.

### Inputs & Forms

Forms preserve DOM order, use visible labels, fieldsets, legends, hint text, aligned errors, and summary-level recovery for long forms. Never reorder form controls visually with CSS if the DOM order differs.

### Navigation

Use top navigation for service families and side navigation for deep documentation or multi-step program content. In-page navigation supports long policy or eligibility pages but should not hide the primary task.

### Signature Components

- Official banner: identifies `.gov` or `.mil` context and HTTPS trust. Do not use on non-government domains.
- Identifier: communicates parent agency responsibility and required legal links.
- Alert: communicates informative, warning, success, error, and emergency status.
- Summary box: makes complex eligibility or review information inspectable.
- Step indicator/process list: supports long service flows without turning them into marketing timelines.

## Do's and Don'ts

### Do

- Show official context, service owner, and task outcome early.
- Use token names and settings when implementing USWDS in production.
- Keep trust rails, legal links, privacy, accessibility, and FOIA paths consistent.
- Put validation messages near fields and preserve user input.
- Test components against keyboard, screen reader, mobile, and Section 508 expectations.

### Don't

- Do not use federal trust components to make a non-official product look official.
- Do not copy agency seals, marks, or product logos into generated previews.
- Do not use blue, red, orange, or green as decoration divorced from action or status.
- Do not hide required links in a custom footer if the identifier is used.
- Do not over-brand a service flow with hero imagery, gradients, or decorative motion.

## Responsive Behavior

### Breakpoints

Use mobile-first layouts. Single-column forms and service content come first; side navigation, agency rails, and supporting cards move below or into clear stacked sections on small screens.

### Touch Targets

Buttons, navigation controls, checkboxes, radio tiles, language selectors, and accordion triggers need comfortable tap targets. Avoid compact icon-only controls for public service tasks.

### Collapsing Strategy

Banner and identifier content must remain readable and honest on mobile. Large link lists can wrap or stack, but legal/agency links should not disappear behind vague menus.

### Image Behavior

Use images sparingly. Agency marks, seals, flags, and official imagery require separate authority. Prefer icons, summary boxes, and data tables for explanatory UI.

## Iteration Guide

1. Start with the service task, user eligibility, and official context.
2. Map required trust components: banner, agency ownership, identifier links, privacy, accessibility, and security language.
3. Define theme color tokens before styling components.
4. Build forms with semantic HTML before visual layout.
5. Add alerts, summary boxes, step indicators, and in-page navigation only where they reduce cognitive or recovery cost.
6. Validate keyboard order, focus style, mobile wrapping, and screen reader labels.
7. Replace placeholder agency text with real approved agency names and links before production.

## Known Gaps

- This resource abstracts USWDS patterns and does not grant rights to use U.S. agency logos, seals, flags, or official marks.
- The dark preview is an internal operations variant. Most public-facing USWDS services default to light surfaces with dark identifier rails.
- Production work should verify current USWDS package version, Sass settings, component accessibility tests, and legal link requirements.
- USWDS token values and components evolve; confirm the current official docs before implementation.