U.S. Web Design System report
USWDS is mature in code, while its design kit remains the main readiness gap.
How well does U.S. Web Design System stay aligned from design through production?
68.75/ 100
USWDS is ready for agent-assisted work on the tested tokens, components, validated fields, governance process, and most complete-form attempts. Multi-step forms still benefit from human review of workflow labels and transitions. Design-to-code work needs a current compatibility statement or versioned mapping before teams can assume the Figma kit matches the released package.
Evidence boundary: This report distinguishes missing public evidence from a missing capability. When a current result was not found in public sources, U.S. General Services Administration may still have it internally and can share it for a re-run.
Foundations
75 / 100
Foundations scored 75%, a good result that shows mature tokens and delivery. The missing quarter reflects the absence of published cross-consumer validation and adoption measures.
Bindings
50 / 100
Bindings scored 50%, the most concerning readiness result. The official Figma kit targets 3.11.0 while the evaluated code is 3.14.0, and no public machine-readable mapping resolved the gap.
Components
68.75 / 100
Components scored 68.75%, a mixed result. Core, responsive, and accessibility behavior are strong, while complete normal and recovery state coverage is incomplete.
Structure
75 / 100
Structure scored 75%, a good readiness result, and the agent passed two of three complete-form runs. The remaining reliability gap was one incorrect workflow action label.
Governance
75 / 100
Governance scored 75%, a good result supported by clear public ownership, contribution, release, and quality practices. Public outcome trends were the main missing evidence.
FoundationsUSWDS provides a coherent token taxonomy, primitives, responsive settings, theme controls, and a versioned package. The study did not find a current published result comparing every supported output or measuring downstream use.A stable foundation reduces product-level variation, but release teams still need evidence that generated outputs and consumers remain compatible after changes.Publish a release report that compares source tokens with generated outputs and the current Figma variables, tests supported modes and breakpoints, and records migration impact. Retain the manifest, passing result, seeded-failure result, and owner approval for a re-run.BindingsComponents and tokens exist in both design and code, but the available evidence did not confirm current names, properties, variables, supported choices, and deprecations one to one.Designers, engineers, and agents must otherwise guess whether the Figma choice, documentation name, class, utility, or package export is authoritative.Publish a current Figma export and a versioned manifest linking design component, variant, and variable identifiers to USWDS packages, classes, utilities, supported choices, and deprecations. Retain compatibility and intentional-mismatch results for a re-run.ComponentsThe sampled components have detailed implementation and accessibility guidance. Loading, empty, permission, retry, review, corrected, and submitted states were not all demonstrated as owned, executable examples.Users experience services in validation, waiting, failure, correction, and completion states as often as they experience the default component state.Define which states apply to each component and pattern, implement representative recovery paths, and publish current type, interaction, responsive, keyboard, and accessibility results. Retain the matrix, tests, failures, exceptions, and fixes.StructureUSWDS layout grids, form patterns, validation, and multi-page guidance supported complete typed, accessible, responsive flows in two runs. The third used Continue instead of Review application at the Supporting documents transition.Complete journeys depend on stable labels and transitions as well as correct layout, state, validation, submission, and recovery behavior.Publish one downloadable three-step reference using stable workflow labels with USWDS grid and form utilities, injected submission, exact validation, state persistence, success, failure, retry, and 320-pixel behavior. Require three fresh agent runs to pass every check.GovernanceUSWDS documents how changes are proposed, reviewed, tested, released, and supported. The study did not find current public trends for review health, migrations, adoption, exceptions, or regressions, and the available accessibility conformance report covers 3.11.0 rather than 3.14.0.Leaders need results over time to know whether releases migrate safely, accessibility regressions close, contributors receive timely decisions, and the system reaches agencies.Publish baselines, targets, trends, owners, and follow-up decisions for review, migration, adoption, exceptions, regressions, and accessibility conformance. Retain the metrics pack and decisions it changed.Can an AI agent use U.S. Web Design System successfully?
14 of 15 runs met every benchmark requirement
5 framework areas. Open an area to see its tested tasks and 3 repeated runs per task.
Foundations1 task · 3 of 3 runs passed100%
Bindings1 task · 3 of 3 runs passed100%
Components1 task · 3 of 3 runs passed100%
Structure1 task · 2 of 3 runs passed66.7%
Governance1 task · 3 of 3 runs passed100%
1 Structure run failed. One run used the wrong second-step action label. The implementation labeled the Supporting documents action Continue instead of the required Review application. The interaction harness could not advance using the exact task contract.
A failed run missed at least one benchmark requirement. The composite result does not, by itself, show whether the cause was the design system, the documentation, the actor, or the evaluator.
How U.S. Web Design System can get better
Make one complete public-service form work every time.
- Problem
- Two of three controlled three-step forms passed every check; the third used Continue instead of the required Review application transition.
- Action
- Publish one canonical implementation that combines stable transition labels with USWDS grid utilities, exact validation, state persistence, injected submission, success, failure, retry, and 320-pixel behavior. Test it as a complete flow.
- Owner
- USWDS pattern, component, accessibility, documentation, and developer-experience teams
- Finish line
- The reference passes type, accessibility, interaction, and responsive checks, followed by three new controlled agent runs in a row.
- Save for the next evaluation
- Reference source, agent-facing guidance, screenshots, harness output, and three controlled run records
- Decision enabled
- Whether teams can use USWDS guidance for agent-assisted multi-step forms without routine correction.
Keep the design kit and released code on the same contract.
- Problem
- The official Figma kit targets USWDS 3.11.0 while the evaluated package is 3.14.0, and the public evidence did not include a machine-readable cross-surface mapping.
- Action
- Publish a versioned manifest connecting current Figma components, properties, and variables to package exports, classes, utilities, supported choices, and deprecations. Compare it during release.
- Owner
- USWDS design-kit, token, component, documentation, and release-infrastructure teams
- Finish line
- Every sampled mapping is current, and a seeded mismatch fails the release check with the affected design and code identifiers.
- Save for the next evaluation
- Figma export, cross-surface manifest, comparison implementation, release results, drift report, and approved exceptions
- Decision enabled
- Whether a design-kit or code change is safe to publish as compatible.
Test difficult states and complete patterns across the system.
- Problem
- The study did not find one current results view spanning component states, breakpoints, assistive technology, layout rules, and complete service patterns.
- Action
- Define the required conditions for supported components and patterns, turn critical composition rules into executable checks, and publish current results with owned exceptions.
- Owner
- USWDS component, pattern, accessibility, quality, and agency implementation teams
- Finish line
- Required states, viewports, keyboard paths, accessibility checks, and complete patterns pass with current evidence and expiring exceptions.
- Save for the next evaluation
- Quality matrix, CI output, accessibility evidence, viewport screenshots, flow results, and exception register
- Decision enabled
- Whether a supported component or public-service pattern is ready for release across its promised conditions.
Use operating evidence to direct USWDS investment.
- Problem
- The public evidence did not show current trends for ownership health, review outcomes, migrations, adoption, exceptions, or regressions. GSA may already track some of this internally.
- Action
- Publish the target, current result, trend, accountable owner, and next decision for each operating measure, including accessibility conformance for the current stable release.
- Owner
- USWDS governance, release, accessibility, program, and design-infrastructure leadership
- Finish line
- The team can show current trends and identify a staffing, release, migration, or process decision changed by those results.
- Save for the next evaluation
- Metrics pack, current accessibility conformance evidence, exception outcomes, and recorded follow-up decisions
- Decision enabled
- Where leadership should invest, change ownership, adjust a release, or strengthen migration support.
The bottom line
USWDS already provides strong code, components, accessibility guidance, patterns, and public governance. The highest-value readiness step is to keep the Figma kit and released package linked through a versioned mapping. A canonical three-step form with stable transition labels would address the one remaining agent failure, while broader executable quality and operating evidence would support continued improvement.
Access the evidence
Review the scoring method, criterion-level rationales, citations, and downloadable study files.