Building a government site takes more than knowing HTML. You need to pick the right USWDS component, know when to use it, which variants exist, whether it meets Section 508 and WCAG 2.1 AA, and how to adapt it without breaking compliance. That's a lot of context that doesn't fit in a model's training data.

USWDS AI Components treats the whole design system as a searchable database. Every component is labeled, scored, and indexed so an agent can find and adapt the right one consistently.

What It Is

This isn't a UI library you install. It's a knowledge base with search indexes. When an agent needs to build a form, nav, or any compliant UI pattern, it queries the registry to find the right component, check when to use it, and pull production-ready markup with adaptation guidance baked in.

Each of the 146 components is described by:

  • Facets : section (forms, navigation, feedback, data display, layout, utilities), component type, JavaScript requirement, compliance flags
  • Use-when and avoid-when rules : explicit guidance on when the component is the right or wrong choice
  • Agent prompts : concrete instructions for how to adapt the component
  • Editable and preserved areas : what you can safely change and what you must keep unchanged for correctness
  • Known limitations : browser quirks, usage caveats, and edge cases
  • Related components : commonly used combinations

The Retrieval Flow

Retrieval is designed to stay lightweight. Three small files, not one big dump:

1. Load facets.json           → Learn what you can filter on
2. Load components.index.json  → Get the full list with discovery facets
3. Filter by facets            → Narrow down to candidates
4. Fetch component HTML        → Get the markup + embedded metadata
5. Follow agentPrompt          → Adapt the component correctly

The agent loads a small facets file once to understand the filter vocabulary, then loads a lean discovery index (all components without the heavy adaptation prose), filters in code, and fetches only the specific component tiles it needs. Each tile is a self-contained HTML file with production-ready USWDS markup and an embedded <script id="uswds-agent-meta"> block containing the adaptation guidance.

Real-World Example

Say the task is: Build a contact form with name, email, and message fields.

Step 1: Filter section=forms, requiresJs=no
Step 2: Candidates: text-input, form
Step 3: Fetch text-input/default.html
Step 4: Read embedded metadata:
  - useWhen: ["Text entry", "User input"]
  - agentPrompt: "Add usa-input class to input element"
  - editableAreas: ["Label text", "placeholder", "id/for attributes"]
  - preserveElements: ["label.usa-label", "input.usa-input",
                       "aria-describedby"]
Step 5: Adapt: Create three text-input instances
         for name, email, message

The agent never guesses. It retrieves, reads the guidance, and adapts within the constraints.

Compliance Metadata

Government sites have legal requirements that most AI agents do not know about. Every component in the registry carries compliance metadata:

  • Section 508 : federal accessibility law (36 CFR 1194)
  • WCAG 2.1 AA : Web Content Accessibility Guidelines
  • 21st Century IDEA : Integrated Digital Experience Act
  • NIST Guidelines : National Institute of Standards and Technology

Need Section 508 compliance? Filter for the flag, and you only get components that carry it. No reasoning required — the metadata tells you.

Do not generate custom UI if a suitable component exists in the registry. Custom UI lacks the government-compliance metadata that this registry provides.

USWDS AI Components, decision strategy

Patterns From Real Government Sites

Beyond the standard USWDS component set, the registry documents patterns we found by inspecting real government sites: usa.gov and pandemicoversight.gov. These aren't in USWDS docs; they're patterns found in production. We worked on both sites: USA.gov across multiple roles at CTAC and Mobomo (2013–present), and pandemicoversight.gov (PRAC) where we built the Azure architecture and created custom USWDS UI components that became three Drupal contrib modules.

  • hidden="until-found" — HTML5 pattern used on usa.gov for accordion and banner content. Content stays hidden but is searchable via browser find-in-page.
  • usa-sidenav — The actual sidenav class used on every usa.gov content page with sidebar navigation.
  • usa-footer__primary-content--collapsible — Footer sections that collapse on mobile, used in the big footer variant.
  • usa-media-block — Image-plus-text layout used inside the government banner.
  • Clickable card pattern from pandemicoversight.gov where the entire card container is wrapped in a link.
  • Feedback form pattern ("Was this page helpful?") with Yes/No submit buttons at the bottom of content pages.

These patterns close the gap between the USWDS documentation and what government sites actually ship.

The Spec Foundation

The registry extends the AI Component Registry Spec, a shared foundation any design system can build on. The spec provides the protocol, index generator, and templates. This project provides the content: 146 tiles, the facet schema, and the adaptation guidance. Think Drupal base theme: you don't use it directly, you inherit its structure.

Component Inventory

The registry covers 146 components across six sections:

  • Forms (16) : Text input, checkbox, radio, select, combo box, date picker, file input, range slider, character count, form validation
  • Navigation (13) : Header, side navigation, breadcrumb, pagination, step indicator, search, language selector, skip nav
  • Feedback (8) : Alert, site alert, modal, tooltip, banner, process list, summary box, tag
  • Data Display (6) : Table, card, collection, identifier, icon, data visualizations
  • Layout (6) : Footer, header, prose, typography, media block, layout docs
  • Utilities (4) : Button, button group, accordion, overlay

The project is MIT licensed. USWDS components are in the public domain. The full registry is available at github.com/ednark/uswds-ai-components. In the next post, we cover how this design registry connects to Drupal implementation through the companion Drupal USWDS AI Components registry.