Back to the field report

U.S. General Services Administration

Technical study of U.S. General Services Administration's U.S. Web Design System design system

U.S. General Services Administration's U.S. Web Design System design system was reviewed to answer two questions: How well does U.S. Web Design System stay aligned from design through production? Can an AI coding agent meet the recorded benchmark requirements?

USWDS is mature in code, while its design kit remains the main readiness gap.

USWDS earned 68.75% for system readiness, a mixed result. Its code, documentation, component behavior, layouts, and public governance are strong. Its weakest area was the connection between design and code, where the official Figma kit targets USWDS 3.11.0 while this study evaluated code release 3.14.0.

The agent finished all 15 controlled runs and 14 passed every required check. Two of three realistic three-step forms passed type, accessibility, interaction, and responsive checks; one run used the wrong second-step action label.

What U.S. Web Design System already does well

  • A mature token and utility foundation with a stable, versioned package
  • Detailed component guidance with responsive and accessibility requirements
  • Strong layout, form, validation, and public-service pattern documentation
  • Clear public contribution, release, and ownership practices
  • Public guidance strong enough for the agent to pass every token, button, validated-field, and governance run, plus two of three complete-form runs

What is still unclear

USWDS public guidance supported 14 of 15 controlled agent runs. Every token, button, validated-field, and governance run passed, as did two of three complete three-step forms. The remaining form run compiled, passed accessibility checks, and remained responsive, but used Continue where the task required Review application, so the interaction could not advance.

The larger readiness concern is cross-surface currency: the official Figma kit describes compatibility with USWDS 3.11.0, three minor releases behind the evaluated 3.14.0 code, and the public evidence did not include a machine-readable design-to-code map. GSA may already hold current Figma exports or operating results internally; sharing them would allow those capabilities to be assessed in a re-run.

A 93.33% agent success rate is strong, but one changed workflow label can still block a complete government-service journey. The older design kit creates a different risk: designers and engineers cannot verify that a design choice still maps to the released code without a current compatibility contract.

How well does U.S. Web Design System stay aligned from design through production?

The study reviewed 20 criteria across foundations, design-to-code bindings, components, product structure, and governance. The evidence included available design files, documentation, source code, tests, and operating guidance.

Result68.75 / 100
Scores across the five areas
Foundations75 Bindings50 Components68.75 Structure75 Governance75

Can an AI agent use U.S. Web Design System successfully?

The recorded model completed 5 controlled tasks, each task repeated 3 times. A run passed only when it met every applicable benchmark requirement.

Full contract passed93.3%
Required evidence100%
Passed every run4/5 tasks

Benchmark-contract compliance was high, with one important gap.

The agent met every structured-answer, executable-check, and evidence requirement in 14 of 15 runs. 4 of 5 tasks passed every run. Every required U.S. Web Design System source and reviewed citation region was satisfied.

The exact code, wording, and citations matched 46.7% of the time, while repeated runs reached the same pass-or-fail result 93.3% of the time. That gap means the composite contract result was more stable than the exact answer. Executable behavior, semantic selection, governance procedure, and evidence compliance must still be interpreted separately.

What this means: Use the failed dimensions to guide review and test coverage. Do not treat the composite score as proof of unattended implementation reliability.

Model and run details

Model: Claude Sonnet 5. Test suite: design-system-agent-tasks/1.0.0. Runs: 15 across 5 tasks. Human interventions: 0.

What was not scored: Calibration, debugging, and interrupted attempts were excluded from these results.

Benchmark-contract outcomes across repeated runs

FoundationsChoose a semantic token100%
BindingsButton to code100%
ComponentsBuild a resource name field100%
StructureBuild the application, and submit flow66.7%
GovernancePlan a system change100%

Passed Failed

One run used the wrong second-step action label

Test: uswds-application-submit-flow, run 3

Cause
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.
What happened
Type checking, axe accessibility checks, and responsive checks at 320 and 1024 pixels passed. The interaction path stopped at Supporting documents, so submission, success, failure, and retry could not be verified for this run.
What it means
Two of three complete-flow runs passed every executable check after the evidence packet and harness were corrected. The remaining failure is an actor consistency error against an explicit label, not evidence that USWDS lacks the required layout or component behavior.
What to change
Add an executable complete-form reference whose workflow actions use stable, task-specific labels and expose those transition labels in agent-facing pattern guidance. Retain the current interaction test so future examples and agent runs must preserve the Review application transition.

See the test evidence

What this result covers: These numbers apply to this model, the 5 recorded tasks, the 15 saved runs, the controlled operational profile, the frozen evidence, and the versioned evaluator. They do not establish representative implementation reliability or documentation causality.

Why each criterion received its score

Open any item to see the evidence, the scoring rule, and what kept it from receiving a higher score.

Foundations

Every score in this area completed review.

75
out of 100, continue, 100% reviewed
Token taxonomy and semanticscritical
Assessor scores: 3, 3, 3; human review: approve3 / 4

The evaluated 3.14.0 code shows a full-file, operational token pipeline: raw system color grades (e.g.

'blue-60v', 'gray-cool-50') are assigned to named semantic theme tokens (base, primary, secondary, accent-warm, accent-cool, error, warning, success, info, disabled) in _settings-color.scss, and those theme tokens are in turn referenced by component-level alias settings (e.g. $theme-alert-text-color: default, $theme-card-border-color: 'base-lighter', $theme-button-border-radius: 'md') in _settings-components.scss. _properties.scss operationalizes this by combining $tokens-color-theme, $tokens-color-state, and $tokens-color-global into $standard-colors/$extended-colors that feed every color-consuming utility.

The color token docs independently confirm 'each theme token is drawn from a system color token and we only use token-based colors in official components.' This satisfies anchor 3's requirement that semantic layers and aliases be comprehensive and operational, not just named.

Anchor 4 is not reached: the only automated token check surfaced in evidence ($test-system-color-tokens) is explicitly described as an internal setting that 'may result in false positives,' and there is no evidence of a validated, cross-consumer (code + design-kit) token graph.

Completeness
Complete
Sources
9 of 9
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Semantic layers and aliases are comprehensive and operational

What a higher score requires: The token graph is validated, measured, and maintained across consumers

What is still needed: No evidence of automated, cross-consumer validation or maintenance of the token graph: the sole surfaced automated check (luminosity/contrast testing) is flagged internal and false-positive-prone, and the Figma kit's variable inventory (claimed but not independently exported) targets an older release (3.11.0) with no confirmed live parity to the 3.14.0 code tokens.

Scope: foundation; system-wide.

Subjects: USWDS theme color tokens, USWDS component-level alias settings, USWDS Sass token pipeline (uswds-core).

Limitation: Covers the code-based Sass token system with full-file evidence; does not verify current parity with the Figma design-kit token/variable inventory, which is a historical, beta 0.3 artifact targeting the older USWDS 3.11.0 and was not independently exported via the Figma API.

What broke
No confirmed break in the semantic/alias layer itself; the gap is that the token graph's validation and code-to-design parity are not evidenced.
Impact
Teams can trust the documented semantic and component-alias token layers in the shipped Sass, but cannot assume the token graph is automatically validated or that the Figma kit's token inventory is currently synchronized with it.
Why
The design-kit README's 'all tokens as Figma variables' claim is scoped to a historical beta (0.3, USWDS 3.11.0) with no independent variable export, and the only in-repo automated color-token check is explicitly labeled internal and prone to false positives.
What to change
Publish a machine-readable diff/export comparing the code token Sass source to the current Figma kit variables, and broaden automated token validation beyond the internal luminosity check.
Supporting evidence, 5 citation(s)
Primitive completeness
Assessor scores: 3, 3, 3; human review: approve3 / 4

The full-file $system-properties map in _properties.scss enumerates a comprehensive set of low-level primitives: spacing, color, border/border-radius/border-width, box-shadow, opacity, typography scale/line-height, flex, z-index, and more: each with standard and extended value sets. The utilities documentation page independently confirms dozens of matching utility modules (background-color, border, margin, padding, font, line-height, etc.) each with documented class-base, function, and mixin access patterns, and the design-tokens page shows the same primitives exposed consistently through function/mixin/utility-class triads.

Component settings (_settings-components.scss) consume these same primitive scales (e.g. $theme-card-border-radius: 'lg', $theme-button-stroke-width: 2px), demonstrating consistent consumption across the catalog rather than isolated, ad hoc use. This meets anchor 3's 'comprehensive and consistently consumed' bar.

Completeness
Complete
Sources
9 of 9
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Primitives are comprehensive and consistently consumed

What a higher score requires: Primitive coverage and adoption are measured and governed

What is still needed: No public evidence that primitive coverage or adoption is measured or governed (for example, no audit data or usage telemetry showing what proportion of components consume tokenized primitives vs. hard-coded values), so anchor 4 is not supported.

Scope: foundation; system-wide.

Subjects: USWDS spacing/color/border/shadow/typography primitive maps, USWDS utility module system.

Limitation: Covers the documented low-level Sass primitive system with full-file evidence; does not establish per-component adoption rates or a formal governance process for primitive usage.

What broke
No confirmed break in the primitive set itself.
Impact
Authors have a comprehensive, consistently-referenced primitive palette to build from, but there is no public evidence of measurement or governance over how consistently primitives are actually adopted across the full component catalog.
Why
The primitive maps and their function/mixin/utility access patterns are fully documented and demonstrably consumed by sampled component settings, but no coverage or adoption metrics/governance artifacts appear in the collected evidence.
What to change
Publish primitive-adoption or utility-usage audits (for example, share of components using tokenized values vs. hard-coded values) as part of governance reporting.
Supporting evidence, 4 citation(s)
Modes and adaptationcritical
Assessor scores: 3, 3, 3; human review: approve3 / 4

Responsive adaptation is systematic and not manual: the layout grid page documents a mobile-first, 12-column, flexbox-based breakpoint system, and the render-utilities-in/these-utilities mixin in _utility-builder.scss shows every utility module looping over the full set of configured breakpoints ($theme-utility-breakpoints-complete) to generate responsive variants automatically, rather than requiring per-utility manual overrides.

Theming/brand adaptation is systematic: the settings page shows every component's colors, fonts, and dimensions are driven from the same uswds-core theme token set via a single @use...with() configuration surface.

Accessibility-oriented adaptation is built into the tokens themselves: rem-based sizing paired with an em-based media-query mixin respects user font-size settings, and the settings page documents a compile-time contrast check with fallback color specifically for disabled-state tokens. Together these span tokens and components systematically, meeting anchor 3.

Anchor 4 (continuous, cross-consumer-validated mode compatibility) is not evidenced: the only automated check found is the narrow disabled-color contrast fallback, not a broader CI validation of theme/breakpoint/accessibility mode combinations. Density and native-platform modes are not evidenced as applicable to this web-only system.

Completeness
Complete
Sources
9 of 9
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Modes are systematic across tokens and components

What a higher score requires: Mode compatibility is continuously validated across supported consumers

What is still needed: No evidence of continuous, cross-consumer validation of mode compatibility (for example, automated visual-regression or contrast testing across breakpoint/theme/accessibility combinations in CI); the only automated check surfaced is a narrow compile-time disabled-color contrast fallback. Density and native-platform modes are not evidenced as in-scope or supported.

Scope: foundation; system-wide.

Subjects: USWDS responsive breakpoint/utility-builder system, USWDS theme settings configuration system, USWDS accessibility-oriented token adaptations (font scaling, disabled-color contrast).

Limitation: The breakpoint-looping utility builder is a cited system-wide code mechanism; theming and accessibility adaptation claims are drawn from settings/accessibility documentation rather than a live cross-mode test suite. Density and native-platform modes are not evidenced.

What broke
No confirmed break in the systematic wiring of modes themselves; the gap is continuous validation of mode compatibility.
Impact
Teams can rely on documented, systematically-generated responsive and theming behavior across tokens and components, but cannot assume every mode combination (theme configuration x breakpoint x accessibility setting) is continuously tested before release.
Why
Evidence shows only one narrow automated mode-related check (a compile-time disabled-color contrast fallback introduced in 3.6.0); no broader CI validation of breakpoint/theme mode compatibility across the maintained consumer matrix is evidenced.
What to change
Add and publish continuous validation (for example, automated visual regression or contrast/token-graph checks across breakpoints and theme configurations) covering the documented supported consumer matrix.
Supporting evidence, 5 citation(s)
Consumable delivery and versioning
Assessor scores: 3, 3, 3; human review: approve3 / 4

USWDS foundations ship as a semantically-versioned npm package (@uswds/uswds 3.14.0) with a documented package.json exports map covering compiled CSS/JS, ESM component imports, Sass entry points, fonts, and images, plus a parallel direct-GitHub-release download path described in the README. The settings page's 'Latest updates' table shows a maintained, versioned changelog spanning many releases (through 3.14.0) with explicit Breaking/No-breaking labeling per change, and the README documents multiple consistent consumption channels (npm, GitHub release ZIP, uswds-compile) all resolving to the same versioned artifact set.

This satisfies anchor 3's requirement that multiple consumers receive consistent versioned artifacts.

Anchor 4 is not reached: there is no evidence of automated migration-impact measurement (for example, breaking-change impact analysis across downstream consumers or delivery-contract validation) beyond qualitative changelog prose.

Completeness
Complete
Sources
9 of 9
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Multiple consumers receive consistent versioned artifacts

What a higher score requires: Delivery contracts are validated and migration impact is measured

What is still needed: No evidence of measured migration impact (for example, automated breaking-change impact analysis across downstream consumers) or delivery-contract validation beyond qualitative changelog entries, so anchor 4 is not supported.

Scope: foundation; system-wide.

Subjects: @uswds/uswds npm package delivery, USWDS GitHub release delivery, USWDS versioned changelog process.

Limitation: Covers the code package's delivery mechanism with direct package.json/README evidence; does not establish measured migration impact, and does not evaluate delivery/versioning of the separate Figma design-kit artifact, which is distributed as an infrequently-updated beta ZIP/Figma-community file rather than through a package registry.

What broke
No confirmed break in the delivery mechanism itself.
Impact
Consumers can reliably pull a specific versioned release via npm or GitHub with consistent compiled and source artifacts across releases, but there is no public evidence that migration impact across downstream consumers is measured before or after a release.
Why
Release notes document breaking vs. non-breaking changes qualitatively (for example, the 3.14.0 Receptor-dependency removal marked Breaking) but no quantitative or automated migration-impact tooling is evidenced in the collected sources.
What to change
Publish automated migration-impact reporting (for example, breaking-change diffing tooling or downstream-consumer adoption telemetry) alongside the existing prose changelog.
Supporting evidence, 3 citation(s)

Bindings

Every score in this area completed review.

50
out of 100, partial, 100% reviewed
Naming parity
Assessor scores: 2, 2, 2; human review: approve2 / 4

Code package/class names (usa-alert, usa-button, usa-card, usa-checkbox, usa-form, usa-header, usa-modal, usa-step-indicator, usa-table) align systematically with documentation page titles (Alert, Button, Card, Checkbox, Form, Header, Modal, Step indicator, Table), and each doc page explicitly states its package via a 'Package usage: @forward ...' line, directly tying the documented name to the code artifact. The design kit's historical README changelog also lists component names (Modal, Card, Step indicator, Tables, Site Alert, Summary Box, Pagination) that match code/doc naming for several sampled components.

However, the current beta 0.3 Figma kit's actual internal component/variant naming was never directly inspected (only a binary .fig file plus non-component metadata files were collected), and layout-grid's code-side class prefix ('grid-') deliberately diverges from the 'usa-' convention used everywhere else, a divergence the catalog itself flags as part of a broader unmapped Figma-to-utility relationship. This is common-name documentation with a known, disclosed gap rather than confirmed systematic alignment across all three surfaces.

Completeness
Complete
Sources
21 of 21
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Common names are documented with known gaps

What a higher score requires: Names are systematically aligned across surfaces

What is still needed: Reaching 'systematically aligned across surfaces' (anchor 3) requires direct, current evidence of Figma component/variant naming for the beta 0.3 kit (e.g. a live Figma API export or textual component inventory) confirming 1:1 alignment for every sampled component, including layout-grid, whose code class prefix already diverges from the 'usa-' convention and whose Figma-to-utility naming mapping is explicitly flagged in catalog metadata as not machine-readable.

Scope: deep-component; sample-only.

Subjects: Button, Form, Text input, Checkbox, Header, Modal, Alert, Card, Step indicator, Layout grid, Table, uswds-design-kit (Figma beta 0.3).

Limitation: Cannot confirm actual Figma layer/component/variant names for the current beta 0.3 kit (only README/LICENSE/CONTRIBUTING/repository.json were collected, no live export); the historical changelog list is from an earlier point in the kit's life and may not reflect current naming after subsequent point releases.

What broke
The Figma design kit's internal component/layer naming cannot be confirmed to match code package and documentation names because the evidence packet contains only the binary .fig file plus README/LICENSE/CONTRIBUTING/repository.json, not a live component/variant export.
Impact
A team using this diagnostic can't verify that picking 'Card' or 'Modal' in the Figma kit reliably maps to code class 'usa-card'/'usa-modal' without a separate manual cross-check, especially for less-common variant names.
Why
uswds-design-kit evidence is limited to non-component metadata files (README, LICENSE, CONTRIBUTING, repository.json); no textual export of Figma layer, component, or variant names was collected, whereas code package/class names and documentation titles are directly observed and align systematically for the sampled set.
What to change
Collect a live Figma API export (component and variant names) for the current beta kit version to confirm 1:1 naming against code classes and doc titles, with particular attention to layout-grid, whose naming convention already diverges from other components.
Supporting evidence, 6 citation(s)
Design-to-code contract correspondencecritical
Assessor scores: 2, 2, 2; human review: approve2 / 4

Core consumer-controlled choices for the sampled components correspond through documented, public code mechanisms: variant classes (button color/size, alert status, modal size, table striping/border/compactness, step-indicator counters/no-labels/center) are enumerated in each component's 'variants' documentation table and implemented as BEM modifier classes; state choices (disabled, hover, active, focus) map to native pseudo-classes plus documented preview-only modifier classes; compound components (Form, Header) compose documented sub-packages coherently.

Runtime-only interaction wiring (Modal's data-open-modal/aria-controls attributes, Table's JS-driven sort behavior) and code-only accessibility semantics (Alert's role attribute choice) are properly excludable as justified surface-specific controls with no necessary design-property equivalent.

The evidence does not, however, let us directly confirm the design (Figma) half of most of these mappings: no Figma property/variant names were observed, only the catalog's asserted 'component'/'compound' disposition. layout-grid is the one component where this gap is made explicit in evidence: its own design metadata states the Figma-to-utility mapping 'is not available as a public machine-readable contract,' making it a genuine, disclosed gap rather than an assumed correspondence.

Completeness
Complete
Sources
21 of 21
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Core consumer choices correspond through documented APIs or runtime mechanisms, with justified surface-specific controls excluded

What a higher score requires: Supported choices, derived states, slots, and composition map coherently, and surface-specific controls are explicitly classified

What is still needed: Anchor 3 ('supported choices, derived states, slots, and composition map coherently, and surface-specific controls are explicitly classified') requires confirming the design-side half of each mapping directly (actual Figma variant/property names), which the evidence does not provide beyond catalog-level disposition metadata; layout-grid is the one component where this gap is explicitly acknowledged as a missing 'public machine-readable contract,' and no comparable confirmation exists for the other ten sampled components either.

Scope: deep-component; sample-only.

Subjects: Button, Form, Text input, Checkbox, Header, Modal, Alert, Card, Step indicator, Layout grid, Table.

Limitation: No direct inspection of Figma component properties or variants was possible; correspondence for the design half of each mapping rests on catalog-declared 'component'/'compound' disposition metadata rather than confirmed property names, except for layout-grid, where a gap is explicitly documented in the evidence.

What broke
layout-grid explicitly lacks a public machine-readable Figma-to-utility mapping, and no other deep component's Figma property definitions (variant names, boolean toggles) are directly observable in the evidence, so most design-side halves of the ledger are asserted by catalog metadata rather than confirmed.
Impact
A consumer configuring column widths/gaps in the Figma grid has no confirmed, documented path to the equivalent grid-col-N/grid-gap-* utility classes; for other components, matching design variants to code modifiers relies on the shared component name rather than a verified property-level contract.
Why
uswds-layout-grid-docs and the usa-layout-grid Sass source show a rich, code-only utility system (grid-container, grid-col-[1-12], grid-gap variants, an explicit utility-mixins table) with no cross-reference to any Figma smart-layout property naming scheme; the layout-grid deep_component's own design rationale states this mapping 'is not available as a public machine-readable contract.'
What to change
Publish an explicit mapping (e.g. a Code Connect file or documentation table) tying Figma grid smart-layout properties to grid-col-*/grid-gap-* utility classes, and extend a comparable explicit mapping to other components' variant and state properties.
Binding mappings
  • Button variant (primary/secondary/accent-cool/accent-warm/base/outline/outline-inverse/big): shared_contract; design: Figma Button component variant property (asserted by catalog disposition='component'; not directly inspected); code: .usa-button--secondary/--accent-cool/--accent-warm/--base/--outline/--big modifier classes. Both surfaces are documented as offering the same set of consumer-selectable color/size variants; the code side is fully evidenced via SCSS modifier classes and the doc's component preview/code samples, while the Figma side is only asserted through catalog metadata rather than direct inspection.
  • Button hover/active/focus pseudo-states: derived_mapping; design: Figma pseudo-state or interactive variant for hover/active/focus (not directly inspected); code: :hover/.usa-button--hover, :active/.usa-button--active, :focus/.usa-focus pseudo-classes and static preview modifier classes. The same interaction meaning is expressed through different mechanisms on each surface: real CSS pseudo-classes at runtime plus a documented static modifier class (--hover/--active) used to render the state in static doc-site screenshots: a derived mapping rather than a literal shared prop.
  • Button disabled state: shared_contract; design: Figma disabled variant/state (not directly inspected); code: :disabled and [aria-disabled="true"] selectors via the button-disabled mixin. Code explicitly supports both the native disabled attribute and aria-disabled='true' as documented alternatives (doc preview rows 'Disabled'/'aria-disabled'), giving consumers two supported runtime mechanisms for the same design-level disabled choice.
  • Alert status variant (info/warning/success/error/emergency): shared_contract; design: Figma Alert component status variant (asserted, not directly inspected); code: .usa-alert--info/--warning/--success/--error/--emergency, driven by the $alert-icons Sass map. The 'Alert variants' documentation table enumerates exactly these five status variants plus --slim/--no-icon, matching the code's $alert-icons map keys one-to-one; the design-side property itself is not directly observed but is asserted by the deep_component's 'component' disposition.
  • Alert ARIA role (alert/status/region): runtime_only; design: not applicable: no corresponding Figma property is described; code: role="alert"|"status"|"region" attribute chosen per alert type, per the 'Alert ARIA roles' guidance table. This is an accessibility/semantics decision made by the implementing developer based on message urgency, not a visual design choice a Figma component property would represent; the doc page frames it as implementation guidance, not a design variant.
  • Modal open/close wiring (data-open-modal, data-close-modal, aria-controls): runtime_only; design: not applicable: no corresponding Figma property is described; code: data-open-modal/data-close-modal attributes and aria-controls wiring implemented in usa-modal/src/index.js. These are DOM event-handler wiring concerns with no visual representation; the modal JavaScript (toggleModal, OPENER_ATTRIBUTE/CLOSER_ATTRIBUTE constants) is purely a runtime mechanism outside any design surface.
  • Modal size (default/large): shared_contract; design: Figma Modal size variant (asserted, not directly inspected); code: .usa-modal--lg modifier class, documented in the 'Modal variants' table. The doc page documents exactly one size modifier (.usa-modal--lg) as a supported consumer choice; the corresponding design-side variant property was not directly observed but is consistent with the component's 'component' disposition.
  • Layout grid column/gap/offset system: genuine_gap; design: Figma 'smart layouts' on layout components (claimed in design kit README, not machine-mapped); code: grid-container/grid-row/grid-col-[1-12]/grid-gap-*/grid-offset-* utility classes and Sass mixins. The layout-grid deep_component's own design metadata explicitly states the Figma-to-utility mapping 'is not available as a public machine-readable contract': the code side is extensively documented (grid-col, grid-gap, grid-offset, breakpoint tables) but no evidence ties any specific Figma smart-layout property to a specific utility class, so this is a genuine, evidence-backed gap rather than an assumed correspondence.
  • Table visual variants (striped/borderless/compact/scrollable/stacked): shared_contract; design: Figma Table component variant (asserted, not directly inspected); code: .usa-table--striped/--borderless/--compact modifier classes plus .usa-table-container--scrollable wrapper. Each visual variant documented on the Table page corresponds to an explicit, named code modifier class; the design-side property was not directly observed but is consistent with the component's 'component' disposition.
  • Table column sort interaction (aria-sort toggling, sort button): runtime_only; design: not applicable: no corresponding Figma property is described; code: JS-driven aria-sort attribute toggling and sort button injection (usa-table/src/index.js, toggleSort/sortRows/createHeaderButton). Sorting is purely a client-side interactive behavior implemented against live DOM state; no static design property would represent the current sort direction, so this is excludable from the parity comparison as a justified runtime-only concern.
Supporting evidence, 8 citation(s)
Token paritycritical
Assessor scores: 2, 2, 2; human review: approve2 / 4

The design kit's own documentation states it is 'built with USWDS design tokens' and represents 'All tokens as Figma variables,' indicating an intended semantic (not merely visual) token alignment between design and code. The code side is exhaustively and fully documented: the theme color tokens table lists token/settings-variable/default/hex value for every color, and the settings docs give full default/type/description tables for color, component, spacing, typography, and utility tokens across the whole system (this is full-file coverage on the implementation side).

However, no live Figma Variables export was collected: the design-kit evidence is limited to README/LICENSE/CONTRIBUTING/repository.json: so token identity, naming, and any modes cannot be directly verified against the code tables.

Compounding this, the design kit itself is a beta pinned to USWDS 3.11.0 (per its own changelog) while the evaluated code is 3.14.0, a documented version gap between the two token sources. This combination of a documented intention of full semantic alignment plus a disclosed, unresolved verification and version gap fits 'core semantic tokens align with documented gaps' rather than a directly confirmed identity/mode match.

Completeness
Complete
Sources
21 of 21
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Unknown

Scoring rule used: Core semantic tokens align with documented gaps

What a higher score requires: Token identity and modes align across design and code

What is still needed: Anchor 3 ('token identity and modes align across design and code') requires a live inspection of the Figma Variables (e.g. a Variables API export) to confirm that named tokens and any modes match the code's settings values; the evidence packet only contains the design kit's README/LICENSE/CONTRIBUTING/repository.json (no live variable export), and the design kit itself targets USWDS 3.11.0 while the evaluated code is 3.14.0, a version gap the study cannot resolve from available evidence.

Scope: foundation; unknown.

Subjects: USWDS color tokens, USWDS spacing tokens, USWDS typography tokens, Figma design kit beta 0.3 variables.

Limitation: No live Figma Variables API export was collected, so token identity, naming, and any modes on the design side are unconfirmed; the design kit's stated USWDS 3.11.0 target versus the evaluated 3.14.0 code release means some settings/values may have changed since the kit was last updated.

What broke
Design-side (Figma) token/variable identity, modes, and value parity with the code's semantic token tables cannot be verified from the evidence; the design kit also targets an older USWDS version (3.11.0) than the evaluated code release (3.14.0).
Impact
A designer using the Figma kit's 'primary' or 'accent-cool' variable may be working from token definitions that predate three point releases of code-side settings changes, risking value drift that isn't automatically caught.
Why
uswds-design-kit README states the beta kit is USWDS 3.11.0 while uswds-foundation-code package.json reports version 3.14.0; the code-side token system is fully documented (theme color tokens table, settings tables) but no live Figma Variables export was collected to confirm identity/mode parity.
What to change
Refresh the Figma kit to the current code release cadence (or publish a version-compatibility note) and capture a live Figma Variables API export to verify token name/value/mode parity against the code token tables.
Supporting evidence, 6 citation(s)
Traceability and deprecation
Assessor scores: 3, 3, 2; human review: revise2 / 4

Score 2 replaces the assessor median of 3. Code and documentation have maintained release and migration references, but the official design kit targets 3.11.0 and no versioned component-level mapping connects current Figma identifiers to 3.14.0 packages, classes, variants, or deprecations. That evidence meets maintained core references, not versioned cross-surface mappings.

Completeness
Complete
Sources
21 of 21
Verification
Documented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Core assets have maintained references

What a higher score requires: Versioned mappings expose supported and deprecated APIs

What is still needed: Reach score 3 by publishing a versioned component-level manifest linking current Figma identifiers and variables to supported and deprecated USWDS code APIs.

Scope: mixed; system-wide.

Subjects: per-component changelog tables (Alert, Button, Card, Checkbox, Form, Header, Modal, Step indicator, Table, Text input, Layout grid), USWDS 3.0 migration guide, uswds-design-kit README changelog, package.json exports map.

Limitation: The 'Latest updates' changelog pattern was observed consistently across every sampled component doc page, suggesting it is a system-wide documentation feature on the code side; this does not, however, establish an equivalent system-wide, current, or machine-readable traceability mechanism on the design (Figma) side, where only a general, now-lagging changelog was found.

What broke
No formal manifest or Code Connect linkage ties Figma component/node identifiers to specific code component versions, and the Figma kit's own changelog was last updated for USWDS 3.11.0 while the evaluated code has since advanced to 3.14.0, leaving over a year of code-side changes unreflected in the kit's dated update log.
Impact
Consumers relying on the design kit for current guidance may unknowingly design against tokens, states, or markup patterns that code has since revised (for example, the 3.14.0 modal focus/aria fixes or the accordion icon-position default change), producing handoff mismatches that surface only during implementation.
Why
Code-side traceability is strong: every sampled component doc page carries a maintained, dated 'Latest updates' table with version numbers and explicit breaking-change flags, and a dedicated migration guide documents deprecated settings/classes with old-vs-new values; but the design kit's own dated changelog stops at January 2025 / USWDS 3.11.0, a version behind the evaluated 3.14.0 release, and no cross-surface manifest links specific Figma assets to specific code versions.
What to change
Establish a maintained cross-surface manifest (or Code Connect-style mapping) that ties each Figma component/version to the code component version it corresponds to, and resume or formalize updates to the design kit's changelog so it tracks current code releases rather than lagging by multiple minor versions.
Supporting evidence, 1 citation(s)

Components

Every score in this area completed review.

68.75
out of 100, partial, 100% reviewed
Core component coverage
Assessor scores: 3, 3, 3; human review: approve3 / 4

The public catalog (home page nav and component-lifecycle docs) lists a comprehensive set of components spanning navigation, forms, feedback, data display, and layout (accordion through validation), matching USWDS's stated scope of building fast, accessible, mobile-friendly government sites. The declared deep-component sample (button, form, text-input, checkbox, header, modal, alert, card, step-indicator, layout-grid, table) is backed by working SCSS/JS code, Storybook stories, and package dependency declarations, confirming the catalog entries are not merely named but implemented. This satisfies comprehensive coverage for the stated scope.

It falls short of anchor 4 because public evidence does not establish system-wide gap analysis or adoption tracking across the full catalog -- governance sources explicitly place internal adoption, review-time, and quality-trend data outside public scope, and while per-component accessibility test-result tables exist for the sampled set, there is no site-wide, current inventory of catalog gaps or component health for all ~50 listed components.

Completeness
Complete
Sources
20 of 20
Verification
Documented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Coverage is comprehensive for the stated scope

What a higher score requires: Gaps, adoption, and component health are measured

What is still needed: No public, current, system-wide measurement of catalog gaps or per-component adoption/health exists; only a subset of components have published accessibility test tables, and governance sources place adoption/quality-trend data outside public scope.

Scope: mixed; system-wide.

Subjects: catalog component list (accordion through validation), deep-component sample: button, form, text-input, checkbox, header, modal, alert, card, step-indicator, layout-grid, table.

Limitation: Catalog presence proves breadth and naming, not state/accessibility/responsive depth for every listed item; depth claims are grounded only in the declared deep sample.

What broke
No confirmed break; the gap is that public evidence does not extend gap/adoption/health measurement to the full catalog, only to the sampled deep components.
Impact
Consumers cannot verify from public evidence alone whether less-sampled catalog components (for example, combo box, date picker, character count) are equally mature or maintained.
Why
Governance sources explicitly scope adoption, review-time, and quality-trend data as internal/private; only per-component accessibility test tables are public, and those exist for a subset of components.
What to change
Publish a system-wide, dated component-health/gap dashboard covering the full catalog, not just accessibility test tables for individually-visited component pages.
Supporting evidence, 3 citation(s)
Normal, recovery, and permission statescritical
Assessor scores: 3, 2, 2; human review: revise2 / 4

Score 2 is retained with corrected evidence language. Component styles, templates, stories, and test source define common default, disabled, error, and selected states, but the frozen record contains no current test execution result and recovery-state ownership is uneven across the sample. This supports basic state contracts, not verified comprehensive normal-and-recovery coverage.

Completeness
Complete
Sources
20 of 20
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Common states have basic contracts

What a higher score requires: Normal and recovery states have comprehensive ownership and guidance

What is still needed: Reach score 3 by documenting recovery-state ownership consistently across the sample and saving current execution results that demonstrate those contracts.

Scope: deep-component; sample-only.

Subjects: button, checkbox, text-input, form (error_state story), modal (recovery fix), table (sortable state), complete-complex-form composition (declared, partially evidenced), form-error-recovery composition (declared, partially evidenced).

Limitation: Cannot be generalized to catalog components outside the deep sample (for example, combo box, date picker, file input, character count); composition-level states beyond validation-error are not directly evidenced.

What broke
Loading, empty, permission-gated, and retry states are not evidenced in any sampled deep component or composition, and the declared complex-form flow's review/corrected/submitted states lack an implemented example.
Impact
Teams building permission-gated or async-loading interfaces, or a full multi-step form with a review/submit/confirmation flow, cannot verify from public USWDS evidence that these states have first-party contracts or guidance beyond general pattern prose.
Why
USWDS's public component pages and pattern docs concentrate on normal/disabled/validation states; the complete-a-complex-form pattern pages (progress-easily, keep-a-record) describe principles (progressive disclosure, printable summary) without a corresponding implemented review/submitted template in this evidence set.
What to change
Publish a worked complete-complex-form reference implementation (or template) exhibiting review and submitted/confirmation states, and document loading/empty/permission state guidance for components where applicable.
Supporting evidence, 1 citation(s)
Responsive behavior
Assessor scores: 3, 3, 3; human review: approve3 / 4

USWDS implements responsive behavior through a single, documented, mobile-first breakpoint system (layout grid utilities plus the at-media Sass mixin) with named breakpoints (mobile-lg, tablet, tablet-lg, desktop, desktop-lg, widescreen) and this mechanism is applied consistently across the sampled deep components: button switches from full-width to auto-width at mobile-lg; the header's navbar/search/dropdown layout changes at $theme-header-min-width; the card component's flag layout, media positioning, and column widths change at $theme-card-flag-min-width and via grid utility classes; step-indicator hides/shows segment labels and adjusts spacing at $theme-step-indicator-min-width; the form component adjusts max-width at mobile-lg; and the table component ships dedicated stacked/scrollable/sticky-header variants documented with explicit small-screen guidance.

This is a cited, system-wide mechanism (not a single component's behavior) that multiple archetypally distinct components consistently draw on, supporting consistent adaptation across supported conditions.

It does not reach anchor 4 because no continuous, automated responsive/visual-regression testing across the breakpoint matrix is evidenced -- CI (test:ci) runs unit tests, Sass tests, and axe accessibility scans, but no responsive-layout regression suite.

Completeness
Complete
Sources
20 of 20
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Components adapt consistently across supported conditions

What a higher score requires: Responsive behavior is continuously tested across the matrix

What is still needed: No evidence of continuous, automated testing across the responsive breakpoint matrix (for example, visual regression per breakpoint); CI evidence covers unit, Sass, and accessibility tests but not responsive-layout regression.

Scope: mixed; system-wide.

Subjects: layout-grid breakpoint mechanism (system-wide), button, header, card, step-indicator, form, table.

Limitation: The breakpoint mechanism itself is system-wide and cited directly, but per-component visual correctness at each breakpoint is confirmed only for the sampled components, not the full catalog.

What broke
No confirmed break; the gap toward the top anchor is the absence of continuous automated testing across the responsive breakpoint matrix.
Impact
Teams cannot verify from public CI evidence that responsive layout regressions are caught automatically across breakpoints on every change, only that manual/documented breakpoint behavior exists.
Why
The observed CI pipeline (circleci config, test:ci script) runs lint, Sass tests, unit tests, and axe-based accessibility scans, but no responsive/visual-regression step across the breakpoint matrix is present in the evidence.
What to change
Add and publish a visual-regression or breakpoint-matrix test step to the CI pipeline (test:ci) so responsive adaptation is continuously measured, not just implemented.
Supporting evidence, 4 citation(s)
Accessibility behaviorcritical
Assessor scores: 3, 3, 4; human review: revise3 / 4

Score 3 is retained with a narrower claim. Normative accessibility guidance, component-specific behavior, an accessibility conformance report, and inspectable automated test definitions demonstrate comprehensive accessibility ownership across the sample. The frozen record does not establish that the 3.14.0 suite currently passed, so this score does not claim a current execution result.

Completeness
Complete
Sources
20 of 20
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Accessible behavior is comprehensive and tested

What a higher score requires: Assistive-technology coverage and regressions are continuously measured

What is still needed: Reach score 4 by publishing current assistive-technology and automated execution results, regression history, and measured exception use for the evaluated release.

Scope: mixed; system-wide.

Subjects: modal, table, button, alert, card, checkbox, step-indicator, text-input, CI axe automation (system-wide mechanism), VPAT/ACR (system-wide, periodic).

Limitation: The CI axe-scanning mechanism is system-wide and applies to all Storybook stories, but the specific pass/fail test-status numbers cited are per-component and only shown for the sampled set; the formal VPAT/ACR result content itself was not included in this evidence packet, only its existence and scope description.

What broke
No confirmed critical accessibility failure; the gap is that the published VPAT/ACR audit (44 components) is dated to USWDS 3.11.0, not the evaluated 3.14.0 release, and manual AT coverage is not shown as continuously re-measured.
Impact
Consumers cannot confirm from current public evidence that the formal accessibility conformance findings still hold for every component exactly as shipped in 3.14.0, only that automated axe scanning currently passes and per-component test tables (undated relative to 3.14.0 in this packet) show no failures.
Why
The accessibility docs state the ACR/VPAT assessment was conducted in March 2025 against USWDS 3.11.0 and published in May 2025, while the evaluated code release is 3.14.0 (2026-08-18), leaving a version gap between the formal manual audit and the current release.
What to change
Publish an updated VPAT/ACR (or a dated re-confirmation) aligned to each current stable release, and publish a continuously updated dashboard of automated axe results per component alongside the periodic manual audit.
Supporting evidence, 1 citation(s)

Structure

Every score in this area completed review.

75
out of 100, continue, 100% reviewed
Layout primitives
Assessor scores: 3, 3, 3; human review: approve3 / 4

The observed usa-layout-grid Sass implements grid-container, grid-row, grid-col, grid-gap, and grid-offset with full responsive breakpoint variants (mobile-lg through widescreen), and the layout-grid documentation thoroughly explains containers, auto-layout columns, offsetting, wrapping, gutters, theme settings, and utility mixins.

Crucially, this is not evaluated from isolated component sheets alone: the 404 page template (a real composed HTML artifact) uses grid-container/grid-row/grid-col classes directly, the extended header wraps its nav in grid-container, and card guidance explicitly ties usa-card-group/usa-card to grid-row/grid-col. This satisfies the 'stated product scope' anchor for the sampled compositions.

Completeness
Complete
Sources
17 of 17
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Layout primitives cover the stated product scope

What a higher score requires: Layout use and exceptions are validated and measured

What is still needed: Anchor 4 would require validated or measured grid usage and documented exceptions (for example, lint rules, usage telemetry, or a consistency audit); no such validation or measurement evidence is present in the packet.

Scope: mixed; sample-only.

Subjects: Layout grid (usa-layout-grid), 404 page template, Header extended/megamenu, Card component.

Limitation: Evidence confirms grid usage in the 404 template, header, and card guidance, but does not directly show grid classes inside the form templates referenced by the complete-complex-form composition, and cannot establish Figma-side layout parity.

What broke
No confirmed break in the code-side grid; the known gap is that the Figma-to-utility mapping for the grid is not published as a public machine-readable contract, and the Figma kit (beta 0.3, targeting 3.11.0) predates the evaluated 3.14.0 code.
Impact
Designers using the official Figma kit cannot verify with certainty that its smart-layout/auto-layout behavior stays token-for-token aligned with the current code grid, risking silent drift between design files and shipped layout primitives.
Why
The design-kit README documents smart layouts and Figma variables but the study did not have a live Figma API export of the variable inventory, and the layout-grid deep-component disposition is declared 'mixed' provenance for exactly this reason.
What to change
Publish a versioned, machine-readable mapping between Figma auto-layout/variable grid properties and the corresponding grid-container/grid-row/grid-col utility classes, kept in sync with each code release.
Supporting evidence, 4 citation(s)
Composition guidance
Assessor scores: 3, 3, 2; human review: approve3 / 4

Component documentation provides explicit, structured composition rules rather than isolated inventories: card header/media/body/footer slot and exdent rules, form fieldset/legend grouping and DOM-order requirements, an alert ARIA-role selection table keyed to alert severity, and modal guidance restricting in-modal interactions to buttons.

Pattern-level guidance (progress-easily, keep-a-record) gives explicit do/don't rules for combining step-indicator, modal, alert, and form components inside the complex-form flow, and the 404 template is a fully composed reference implementation showing real hierarchy and hand-off between header, grid, prose, button-group, footer, and identifier regions.

Completeness
Complete
Sources
17 of 17
Verification
Documented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Composition contracts cover supported product assemblies

What a higher score requires: Composition rules are executable or automatically validated

What is still needed: Composition rules are expressed as prose guidance and worked code examples, not as executable or automatically validated contracts (for example, no lint rule or schema enforcing slot usage), so anchor 4 is not supported.

Scope: composition; sample-only.

Subjects: form-error-recovery pattern, not-found-recovery pattern, complete-complex-form pattern (progress-easily, keep-a-record), card, modal, alert, form component composition guidance.

Limitation: The complete-complex-form flow is explicitly published as coordinated but separate pattern pages rather than one downloadable end-to-end implementation; this study does not claim the Figma kit contains a matching composed form flow, so composition contracts on the design side are not independently verified.

What broke
The complete-complex-form composition has no single, unified reference implementation; its composition guidance is spread across three separate pattern pages (establish trust, progress easily, keep a record) rather than one worked example.
Impact
Implementers assembling the full complex-form flow (introduction, in-progress, validation-error, review, submitted) must synthesize guidance from multiple pattern pages themselves rather than following one canonical composed example, increasing the risk of inconsistent assembly.
Why
USWDS's own documentation structure organizes the complex-form pattern as three linked sub-pages of guidance rather than a downloadable end-to-end template, unlike the fully composed not-found-recovery (404) template.
What to change
Publish one consolidated reference implementation (code + preview) for the complete complex-form flow, mirroring the model already used for the 404 template, showing all states (intro, in-progress, error, review, submitted) composed together.
Supporting evidence, 5 citation(s)
Patterns and templates
Assessor scores: 3, 3, 3; human review: approve3 / 4

Beyond isolated component sheets, USWDS ships a full, real HTML 404 page reference implementation (with English/Spanish variants) and code-level task templates (sign-in, address, name, password-reset forms) referenced directly from the usa-form package. The complex-form pattern itself is published as coordinated guidance (trust/progress/record sub-patterns) explicitly cross-linked to the components that implement it (modal, step indicator), rather than one downloadable end-to-end flow. Together these cover important tasks and remain linked to components, satisfying anchor 3, though not the measured-outcomes bar of anchor 4.

Completeness
Complete
Sources
17 of 17
Verification
Implemented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Patterns cover important tasks and remain linked to components

What a higher score requires: Pattern use, outcomes, and lifecycle are measured

What is still needed: Anchor 4 requires measured pattern use, outcomes, and lifecycle tracking; no usage/outcome telemetry or lifecycle metrics for any of these patterns or templates are present in the evidence.

Scope: composition; sample-only.

Subjects: 404 page template (code+guidance), sign-in/address/name/password-reset form templates (code), complete-a-complex-form guidance patterns (trust/progress/record).

Limitation: Evidence establishes that reference templates and cross-linked guidance patterns exist for the sampled tasks; it does not establish pattern adoption, outcomes, or lifecycle status, nor does it claim the Figma kit contains a matching complex-form flow.

What broke
The complete-a-complex-form pattern has no single downloadable reference implementation combining step-indicator, form, validation, review, and submission states; it is split across separate guidance pages (establish trust, progress easily, keep a record).
Impact
Implementers must self-assemble the full complex-form flow from multiple documentation pages and separately-documented components, increasing the risk of inconsistent or incomplete execution of the pattern across agencies.
Why
The complete-a-complex-form landing page and its trust/progress/record sub-pages are prose guidance cross-linked to components, not a working end-to-end code sample; this is an explicitly declared scope boundary of the study, not an inferred failure.
What to change
Publish a downloadable, working reference implementation (for example, a Storybook or template repo) that demonstrates the full complex-form flow across introduction, in-progress, validation-error, review, and submitted states.
Supporting evidence, 4 citation(s)
Navigation, focus, and state ownershipcritical
Assessor scores: 3, 3, 3; human review: approve3 / 4

For the two most interaction-heavy components in the declared flow, ownership is deeply and currently implemented and tested rather than merely documented: the modal JS owns focus-trapping, aria-hidden toggling of background content, and focus restoration to the opener, with an explicit unit test for the edge case where the opener element has left the DOM, and the 3.14.0 changelog confirms a shipped fix ensuring background content is always unhidden regardless of opener presence. The header JS owns mobile-nav toggling, dropdown collapse on escape/focus-out, and viewport-resize auto-close, including a documented Safari-specific fix.

Step-indicator composition intentionally delegates step navigation ownership to an external button-group rather than leaving it undefined. This is comprehensive for the tested components, but alert's dismiss-state ownership is explicitly still in development and depth is not evenly distributed across every declared component, so the score stops short of anchor 4's continuous-verification bar.

Completeness
Complete
Sources
17 of 17
Verification
Test defined
Test definition
Observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
Sample only

Scoring rule used: Navigation, focus, and state contracts are comprehensive

What a higher score requires: Cross-composition contracts are executable and continuously verified

What is still needed: Anchor 4 requires these contracts to be executable and continuously verified; modal test source exists (modal.spec.js) but the evidence does not confirm CI wiring or an observed execution/pass result, so continuous verification cannot be claimed. Comprehensive tested-ownership evidence is also concentrated in modal and header rather than spanning every declared component, since alert's dismiss-state ownership is explicitly still in progress.

Scope: mixed; sample-only.

Subjects: Modal (usa-modal index.js + modal.spec.js), Header (usa-header index.js), Alert dismiss-state (disclosed gap), Form VoiceOver fieldset/legend workaround.

Limitation: Comprehensive, tested ownership evidence is concentrated in modal and header; step-indicator, alert, checkbox, and text-input do not have equivalent depth of tested ownership evidence in the collected packet, and CI execution of the observed test files is not confirmed, only test source existence.

What broke
Alert does not yet own dismiss-interaction state (docs state USWDS is still 'working on a way to help developers implement a dismissible alert'), and form guidance discloses an unresolved VoiceOver limitation with fieldset/legend requiring a manual aria-labelledby workaround.
Impact
Teams implementing the form-error-recovery pattern must hand-build alert dismissal behavior themselves and manually apply the documented aria-labelledby workaround for VoiceOver, creating a real risk of inconsistent or incomplete ownership across different agency implementations.
Why
The alert component documentation directly discloses the missing first-party dismiss capability, and the form documentation directly discloses the VoiceOver fieldset/legend gap and its workaround, both current as of the evaluated documentation snapshots.
What to change
Ship first-party dismissible-alert state ownership in the alert package, and resolve (or continue prominently documenting with an automated check) the VoiceOver fieldset/legend limitation so downstream implementers cannot silently omit the workaround.
Supporting evidence, 5 citation(s)

Governance

Every score in this area completed review.

75
out of 100, continue, 100% reviewed
Named ownership
Assessor scores: 3, 3, 3; human review: approve3 / 4

GOVERNANCE.md names a single accountable federal role (the USWDS Lead/Product Owner) with final decision authority, supported by named part-time federal staff and an Internal Team, and COMMUNITY.md operationalizes a Contributor/Maintainer/Alumni ladder with distinct, enforced access privileges (for example, merge authority restricted to Administrators/Maintainers per CONTRIBUTING.md, and a CODEOWNERS review requirement for all changes). This goes beyond merely documenting contacts (anchor 2) into an operating decision/escalation structure and enforced support boundaries (anchor 3).

However, CODEOWNERS implements only a single blanket owner group rather than the granular per-area mapping COMMUNITY.md implies, and there is no public measurement of ownership health (response times, staffing adequacy, service-level trends): the governance evidence's own known_limitations explicitly place GSA staffing and review-time data outside public scope, so anchor 4 is unmet.

Completeness
Complete
Sources
9 of 9
Verification
Release documented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Decision rights and support boundaries are operational

What a higher score requires: Ownership health and service expectations are measured

What is still needed: No public evidence of measured ownership health or service expectations (for example, response-time SLAs, staffing trend data, escalation success rates); governance known_limitations explicitly place GSA staffing and review-time data outside this public evaluation.

Scope: governance; system-wide.

Subjects: USWDS Open Source Community governance (COMMUNITY.md), USWDS GOVERNANCE.md decision-making structure, CODEOWNERS file.

Limitation: This evidence describes public, documented governance structure and a real repository-level enforcement mechanism (CODEOWNERS); it cannot establish actual internal staffing levels, day-to-day escalation behavior, or whether documented role requirements (for example, 4 PR reviews per 3 months) are consistently met in practice.

What broke
CODEOWNERS defines only a single blanket owner group (@uswds/admins) for the entire repository; every illustrative per-directory/per-team CODEOWNERS pattern in the file is left commented out, so there is no machine-enforced granular ownership mapping despite COMMUNITY.md describing subject-matter Maintainer areas.
Impact
Contributors and downstream integrators cannot programmatically determine which specific person or team is accountable for a given package or component beyond a single blanket administrative group, limiting the practical value of the documented role ladder for routing review.
Why
files/.github/CODEOWNERS shows only the wildcard rule `* @uswds/admins`, with all path-specific CODEOWNERS examples present as inert comments rather than active rules.
What to change
Activate per-package or per-directory CODEOWNERS entries mapping components to their named Maintainer, and publish aggregate ownership-health metrics (for example, response time to first review) to support a future anchor-4 claim.
Supporting evidence, 5 citation(s)
Contribution and review
Assessor scores: 3, 3, 3; human review: approve3 / 4

Public evidence establishes an operational, cross-discipline contribution and review pipeline. CONTRIBUTING.md documents concrete PR requirements (verified/signed commits, linked issues, release-note statements) and a triage rubric (size, severity, priority) applied by Contributors and Maintainers. GOVERNANCE.md's Review guidelines specify named, operational review criteria (functional correctness, verified commit, performance, readability, testability, convention match, breaking-change flag) applied during PR review, plus a conventional-comments practice for review feedback.

The component lifecycle process shows a cross-discipline evaluation pipeline (community discussion, core-team proposal drafting, a minimum 45-day public comment period, core-team evaluation) with defined operational outcomes (approved, conditionally approved, returned for revision, will not pursue) and explicit start/end triggers. The design-assets documentation confirms cross-discipline separation of review: design submissions receive full design review while code-only changes are reviewed by developers. This combination of named reviewer roles, explicit operational criteria, and cross-discipline review satisfies anchor 3.

No public evidence quantifies review throughput, time-to-merge, or proposal approval/rejection rates, so anchor 4 is not met.

Completeness
Complete
Sources
9 of 9
Verification
Release documented
Test definition
Not observed
Automation wiring
Not observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Cross-discipline review criteria and decisions are operational

What a higher score requires: Review quality, throughput, and outcomes are measured

What is still needed: No public evidence quantifies review throughput, time-to-merge, or proposal approval/rejection rates, which anchor 4 requires.

Scope: governance; system-wide.

Subjects: PR review pipeline (CONTRIBUTING.md, GOVERNANCE.md Review guidelines), component proposal lifecycle (discussion, proposal, evaluation).

Limitation: Review throughput, backlog size, and outcome-rate data are not evidenced in the declared public scope.

What broke
No confirmed break: the contribution and review pipeline is operational and cross-discipline, not merely documented.
Impact
Contributors can predict how a submission will be evaluated and by whom, but cannot verify review speed or backlog health from public evidence.
Why
CONTRIBUTING.md, GOVERNANCE.md, and the component lifecycle docs together describe an operational, criteria-driven review pipeline with distinct design and engineering review paths; no public metrics on review throughput or outcome rates were found.
What to change
Publish aggregate review-throughput metrics (for example, median PR review time, proposal approval rate) to support a measured-outcomes governance claim.
Supporting evidence, 4 citation(s)
Releases, migration, and deprecationcritical
Assessor scores: 3, 3, 3; human review: approve3 / 4

The v3.14.0 release notes provide explicit, per-package breaking-change and markup-change flags with concrete 'teams should...' remediation guidance, and the USWDS 3.0 migration guide gives version-gated, step-by-step migration instructions tied to specific historical version thresholds. The component lifecycle defines an explicit deprecation contract (Deprecated → Retired) with named start/end triggers.

Critically, this is backed by real automated operational enforcement, not just prose: release-prep.yml and release.yml implement non-bypassable hash-verification and vulnerability gates (zero-tolerance for production dependencies, critical-severity block for dev dependencies), and the v3.14.0 release notes publish an actual observed vulnerability count for that exact release ('0 vulnerabilities in regular dependencies... 19 vulnerabilities (11 moderate, 3 high) in devDependencies'). This satisfies anchor 3's explicit operational contract for both deprecation and migration/release safety.

There is no public evidence, however, that migration success or downstream compatibility is measured across consumer projects after a release, so anchor 4 is unmet.

Completeness
Complete
Sources
9 of 9
Verification
Automation wired
Test definition
Not observed
Automation wiring
Observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Deprecation and migration have explicit operational contracts

What a higher score requires: Compatibility and migration success are validated and measured

What is still needed: No public evidence that migration success or downstream compatibility is measured across consumer USWDS implementations after a breaking release (for example, the 3.14.0 memorable-date and accordion markup changes); automated gates verify release-artifact integrity and vulnerability thresholds but not consumer migration outcomes.

Scope: governance; system-wide.

Subjects: USWDS 3.14.0 release notes, USWDS 3.0 migration guide, USWDS component lifecycle deprecation phase, release-prep.yml and release.yml CI workflows.

Limitation: This evidence establishes the current release's documented breaking changes and the CI workflows that gate every release; it cannot establish private post-release consumer migration outcomes or long-run compatibility trends across the broader USWDS adopter base.

What broke
No confirmed break in the release/migration process; automated release gates verify vulnerability status and artifact integrity, but there is no public measurement of migration success across consumer USWDS implementations after a breaking release.
Impact
Consumers and the USWDS team lack public evidence of how many downstream projects successfully absorbed a given breaking change (for example, the memorable-date per-field hint markup change in 3.14.0) versus encountering regressions.
Why
The v3.14.0 release notes explicitly flag several breaking/markup changes with 'Teams should...' guidance, and release-prep.yml/release.yml enforce hash and vulnerability gates, but no consumer-side migration outcome data is published.
What to change
Track and publish post-release adoption or regression signals (for example, issue volume tagged to a specific breaking-change release) to close the loop between shipping a breaking change and confirming safe migration.
Supporting evidence, 5 citation(s)
Quality enforcement and feedbackcritical
Assessor scores: 3, 3, 3; human review: approve3 / 4

Public evidence shows automated quality gates wired into CI across the supported lifecycle: CircleCI's unconditional 'build' job runs lint, gulp test, an accessibility test suite (test:a11y, which builds Storybook and runs test-storybook against it), and a Snyk scan on every push, while a separate CodeQL workflow runs static analysis on push, pull request, and a weekly schedule. The Storybook test-runner injects axe-core accessibility checks on every story via preVisit/postVisit hooks.

Accessibility documentation states this is a blocking gate: automated tools scan every code change and 'If it doesn't pass, we don't merge the code.' The release-prep workflow adds a zero-tolerance vulnerability gate for production dependencies and a critical-vulnerability gate for devDependencies before release, with the 3.14.0 release notes disclosing the measured counts (0 regular-dependency vulnerabilities; 19 devDependency vulnerabilities, 11 moderate/3 high, disclosed but non-blocking).

For anchor 3's exceptions clause, two governed accepted-deviation paths are evidenced: the Storybook a11y test-runner supports an explicit, code-reviewed opt-out (a11y.disable, axe.mode 'off', axe.skip true) for stories that intentionally bypass automated a11y checks, subject to the same PR review criteria documented in GOVERNANCE.md; and the component lifecycle's 'Use with caution' status is a formally governed, core-team-managed state for components that fail accessibility/usability/development requirements, distinct from silent noncompliance.

Automated gates spanning development through release, plus these two governed exception mechanisms, satisfy anchor 3's lifecycle-and-exceptions clause.

Anchor 4 requires quality, adoption, exceptions, and regressions to all be measured and acted on; only a subset (per-release vulnerability counts, a one-time March 2025 ACR/VPAT assessment of 44 components) is measured, and no adoption or regression-rate metrics are evidenced, so anchor 4 is not met.

Completeness
Complete
Sources
9 of 9
Verification
Automation wired
Test definition
Not observed
Automation wiring
Observed
Current result
Not observed
Generalizability
System wide

Scoring rule used: Quality gates cover the supported lifecycle and exceptions

What a higher score requires: Quality, adoption, exceptions, and regressions are measured and acted on

What is still needed: No public evidence shows adoption metrics or systematic regression measurement across releases, and only a one-time (March 2025) ACR/VPAT assessment exists rather than continuous measurement, so anchor 4's requirement that quality, adoption, exceptions, and regressions all be measured and acted on is not fully met.

Scope: governance; system-wide.

Subjects: CI pipeline (CircleCI, CodeQL), Storybook accessibility test-runner (axe-core) with governed opt-out, release vulnerability gates (release-prep.yml, release.yml), component lifecycle 'Use with caution' status.

Limitation: Actual invocation frequency of accessibility test exceptions, adoption metrics, and regression-rate measurement across releases are not evidenced in the declared public scope.

What broke
No confirmed break: automated gates cover the CI/release lifecycle and two governed exception paths are evidenced, but full quality/adoption/regression measurement is not.
Impact
Consumers can trust that most changes pass automated accessibility, lint, and vulnerability checks before merge and release, but cannot verify from public evidence how often exceptions are invoked, whether version adoption is tracked, or whether regressions are systematically measured across releases.
Why
CircleCI, CodeQL, and the Storybook a11y test-runner wire automated checks into the CI pipeline, and release-prep.yml/release.yml gate publishing on vulnerability scans; the a11y opt-out flags and the lifecycle's 'Use with caution' status provide governed exception paths; but adoption and regression metrics are not published.
What to change
Publish aggregate data on how often accessibility test exceptions are invoked, and track/report adoption and regression metrics across releases to support a fully measured quality-enforcement claim.
Supporting evidence, 7 citation(s)

How USWDS can get better

Start with the known problem. Then keep design and code aligned, test complete product experiences, and track whether the system improves. Open an item to see what to do, who should own it, and how to show it worked.

Score today68.75 / 100
Points this plan could add+31.25
4 stages to a score of 100Each stage builds on the one before it. The number shown is the score U.S. Web Design System could reach after a new evaluation confirms the work.
0TodayCurrent score
68.75Starting point
1Stage 1Fix known issues
68.75Possible score, +0 points
2Stage 2Align Figma and code
83.75Possible score, +15 points
3Stage 3Test the whole system
95Possible score, +11.25 points
4Stage 4Measure and improve
100Possible score, +5 points

How the score could change: The possible score of 100 is not a forecast. Each increase depends on USWDS meeting the stated acceptance criteria, retaining the evidence, and having that evidence approved in a future study.

Before starting new work, ask what already exists inside U.S. General Services Administration

Confirm whether capabilities unavailable in the evaluated public evidence already exist before commissioning duplicate work.

Ask for:

  • A current Figma component and variable export with its supported USWDS release
  • Internal complete-flow, responsive, and assistive-technology test results
  • Ownership, review, migration, adoption, exception, and regression trends
Stage 1

Fix the known problem and check what the team already does internally.

Project 1

Make the complete form reliable in every repeated run

Problem
Two of three corrected application runs passed every required check. The third compiled, passed accessibility checks, and remained responsive, but used Continue instead of the required Review application action and could not advance through the exact interaction path.
Action
  • Publish one complete three-step USWDS application reference with details, documents, and review steps.
  • Document each step's primary action label and destination, including Review application between Supporting documents and Review and submit.
  • Use grid-container and supported form markup so the reference preserves the responsive, typed, and accessible behavior demonstrated in the two passing runs.
  • Persist entered state across steps and receive submission behavior as an injected dependency.
  • Test empty validation, correction, navigation, success, failure, retry, keyboard use, accessibility, and narrow-screen layout.
  • Repeat the controlled form task three times after the guidance is published.
Owner
  • USWDS form and layout component owners
  • USWDS accessibility and pattern owners
  • USWDS documentation and developer-experience owners
Finish line

Designers, engineers, and agents can start from one complete USWDS form that keeps workflow labels, validation, layout, state, submission, and recovery behavior consistent together.

  • The canonical reference type-checks with strict TypeScript.
  • Axe, interaction, and 320-pixel responsive checks pass for every step and recovery state.
  • The documented action label for each workflow transition matches the executable reference and interaction test.
  • Three new controlled agent runs preserve every required workflow label and pass every check in a row.
Save for the next evaluation
  • Published reference implementation and agent-facing guidance
  • Type, accessibility, interaction, source-policy, and responsive results
  • Narrow-screen screenshots for every step
  • Three new controlled run outputs and harness records
Decision enabled
Whether USWDS public guidance is reliable enough for agent-assisted multi-step forms without routine human correction.
Stage 2

Keep Figma and code aligned.

Project 2

Keep the Figma kit and released code on one versioned contract

Problem
The public design-kit repository describes beta 0.3 as compatible with USWDS 3.11.0, while this study evaluated code release 3.14.0. No current Figma export or machine-readable mapping established naming, component-property, token, utility, and deprecation parity.
Action
  • Publish a dated export of current Figma components, properties, variants, variables, and modes with the exact supported USWDS code release.
  • Create a versioned manifest linking design identifiers to package exports, classes, utilities, supported choices, and deprecations.
  • Compare source tokens, generated outputs, Figma variables, and supported mode and breakpoint behavior during release.
  • Classify every design-only or code-only control with a rationale, owner, and review date.
  • Publish mapping coverage, drift, compatibility, and migration-impact results.
Owner
  • USWDS design-kit maintainers
  • USWDS token and component owners
  • USWDS documentation and release-infrastructure owners
Finish line

A designer, engineer, or agent can trace every supported design choice to the current code API, and a release cannot introduce an unexplained difference.

  • Every sampled component and token has a current design-to-code mapping or an approved, dated exception.
  • The Figma kit states compatibility with the current stable USWDS release or clearly identifies and documents its lag.
  • A seeded token, property, or deprecation mismatch fails the release check and names both affected surfaces.
  • The release report records mapping coverage, compatibility, drift, and migration impact.
Save for the next evaluation
  • Current Figma export and supported-release statement
  • Versioned cross-surface manifest and comparison implementation
  • Passing and intentionally failing release results
  • Compatibility, mapping-coverage, drift, migration, and exception reports
Decision enabled
Whether a Figma, token, utility, component, or package change is safe to publish as compatible.
Stage 3

Test complete product experiences, not only individual parts.

Project 3

Test difficult states and complete public-service patterns

Problem
USWDS documents components, responsive behavior, accessibility, layouts, and patterns well, but the study did not find one current matrix of executable results across difficult states and complete services. Loading, empty, permission, retry, review, corrected, and submitted states were not all demonstrated, and one of three complete-form runs used the wrong workflow transition label.
Action
  • Define the required normal, loading, empty, validation, permission, retry, review, corrected, and submitted states for each supported component and pattern.
  • Test required states across supported viewports, keyboard paths, screen readers, and high-contrast conditions.
  • Turn critical layout, composition, focus, state-ownership, and recovery rules into executable checks.
  • Add downloadable reference implementations for complete high-value public-service patterns.
  • Publish per-release pass, failure, and exception results with owners and expiration dates.
Owner
  • USWDS component and pattern maintainers
  • USWDS accessibility and quality owners
  • Agency product teams representing supported service flows
Finish line

Teams can see which states and environments each component and pattern supports, which checks passed, and who owns every remaining failure or exception.

  • Every supported component and pattern lists the states and environments that apply.
  • Current results cover responsive layout, interaction, keyboard, automated accessibility, and representative assistive technology.
  • A broken layout, focus path, validation relationship, state transition, or recovery flow fails an executable check.
  • Every failure and approved exception has an owner, review date, and recorded resolution.
Save for the next evaluation
  • Versioned component and pattern quality matrix
  • CI results for state, viewport, interaction, and accessibility coverage
  • Complete reference implementations and end-to-end results
  • Failure and exception register with resolutions
Decision enabled
Whether a supported component or public-service pattern is ready across the conditions USWDS promises.
Do this first
Make the complete form reliable in every repeated run, Keep the Figma kit and released code on one versioned contract
Stage 4

Use real results to decide what to improve next.

Project 4

Use operating evidence to direct USWDS investment

Problem
USWDS has clear public ownership, contribution, release, and quality practices. The evaluated evidence did not include current public trends for ownership health, review outcomes, consumer migrations, adoption, exceptions, or regressions, and the available accessibility conformance report covers 3.11.0 rather than the evaluated 3.14.0 release.
Action
  • First determine which ownership, review, migration, adoption, exception, regression, and accessibility results GSA already maintains internally.
  • Define a public baseline, target, trend, accountable owner, and review cadence for each approved measure.
  • Align accessibility conformance evidence or a dated reconfirmation with the current stable release.
  • Record why each exception exists, who owns it, when it expires, and what happened at review.
  • Publish the staffing, release, migration, or process decision made when a target is missed.
Owner
  • USWDS governance and release owners
  • USWDS accessibility and program leadership
  • USWDS component maintainers and agency adoption partners
Finish line

USWDS leadership can see whether releases migrate safely, quality problems close, agencies adopt supported versions, and ownership or process changes improve the result.

  • Current operating results show baselines, targets, trends, and accountable owners.
  • Accessibility conformance evidence covers the current stable release or clearly states the assessed version and unresolved delta.
  • Every approved exception has a reason, owner, expiration date, and recorded outcome.
  • The team can identify a staffing, release, migration, or process decision changed by the evidence.
Save for the next evaluation
  • Ownership, review, migration, adoption, exception, and regression trends
  • Current accessibility conformance evidence and automated results
  • Exception register with expirations and outcomes
  • Operating-review decisions and follow-up results
Decision enabled
Where USWDS leadership should invest, change ownership, adjust a release, or strengthen migration support.
Do this first
Test difficult states and complete public-service patterns
What U.S. Web Design System would need to show for a score of 100 (20 criteria)

This table lists every place where the system lost points. Scores only change after the work is complete and the evaluation is run again.

CriterionScore nowGoalPoints availableWhat is missing
Foundations: Token taxonomy and semantics
Why the system lost points

No evidence of automated, cross-consumer validation or maintenance of the token graph: the sole surfaced automated check (luminosity/contrast testing) is flagged internal and false-positive-prone, and the Figma kit's variable inventory (claimed but not independently exported) targets an older release (3.11.0) with no confirmed live parity to the 3.14.0 code tokens.

What the system needs to show: The token graph is validated, measured, and maintained across consumers

34+1.25Proof needed
Foundations: Primitive completeness
Why the system lost points

No public evidence that primitive coverage or adoption is measured or governed (for example, no audit data or usage telemetry showing what proportion of components consume tokenized primitives vs. hard-coded values), so anchor 4 is not supported.

What the system needs to show: Primitive coverage and adoption are measured and governed

34+1.25Proof needed
Foundations: Modes and adaptation
Why the system lost points

No evidence of continuous, cross-consumer validation of mode compatibility (for example, automated visual-regression or contrast testing across breakpoint/theme/accessibility combinations in CI); the only automated check surfaced is a narrow compile-time disabled-color contrast fallback. Density and native-platform modes are not evidenced as in-scope or supported.

What the system needs to show: Mode compatibility is continuously validated across supported consumers

34+1.25Proof needed
Foundations: Consumable delivery and versioning
Why the system lost points

No evidence of measured migration impact (for example, automated breaking-change impact analysis across downstream consumers) or delivery-contract validation beyond qualitative changelog entries, so anchor 4 is not supported.

What the system needs to show: Delivery contracts are validated and migration impact is measured

34+1.25Proof needed
Bindings: Naming parity
Why the system lost points

Reaching 'systematically aligned across surfaces' (anchor 3) requires direct, current evidence of Figma component/variant naming for the beta 0.3 kit (e.g. a live Figma API export or textual component inventory) confirming 1:1 alignment for every sampled component, including layout-grid, whose code class prefix already diverges from the 'usa-' convention and whose Figma-to-utility naming mapping is explicitly flagged in catalog metadata as not machine-readable.

What the system needs to show: Parity is automatically checked and drift is measured

24+2.5Proof needed
Bindings: Design-to-code contract correspondence
Why the system lost points

Anchor 3 ('supported choices, derived states, slots, and composition map coherently, and surface-specific controls are explicitly classified') requires confirming the design-side half of each mapping directly (actual Figma variant/property names), which the evidence does not provide beyond catalog-level disposition metadata; layout-grid is the one component where this gap is explicitly acknowledged as a missing 'public machine-readable contract,' and no comparable confirmation exists for the other ten sampled components either.

What the system needs to show: Machine-readable mappings continuously validate shared contracts and explicitly classify surface-specific controls

24+2.5Proof needed
Bindings: Token parity
Why the system lost points

Anchor 3 ('token identity and modes align across design and code') requires a live inspection of the Figma Variables (e.g. a Variables API export) to confirm that named tokens and any modes match the code's settings values; the evidence packet only contains the design kit's README/LICENSE/CONTRIBUTING/repository.json (no live variable export), and the design kit itself targets USWDS 3.11.0 while the evaluated code is 3.14.0, a version gap the study cannot resolve from available evidence.

What the system needs to show: Cross-surface token parity is automatically validated

24+2.5Proof needed
Bindings: Traceability and deprecation
Why the system lost points

Reach score 3 by publishing a versioned component-level manifest linking current Figma identifiers and variables to supported and deprecated USWDS code APIs.

What the system needs to show: Traceability and deprecation drift are automatically enforced

24+2.5Proof needed
Components: Core component coverage
Why the system lost points

No public, current, system-wide measurement of catalog gaps or per-component adoption/health exists; only a subset of components have published accessibility test tables, and governance sources place adoption/quality-trend data outside public scope.

What the system needs to show: Gaps, adoption, and component health are measured

34+1.25Confirmed gap
Components: Normal, recovery, and permission states
Why the system lost points

Reach score 3 by documenting recovery-state ownership consistently across the sample and saving current execution results that demonstrate those contracts.

What the system needs to show: State contracts are executable, tested, and measured

24+2.5Confirmed gap
Components: Responsive behavior
Why the system lost points

No evidence of continuous, automated testing across the responsive breakpoint matrix (for example, visual regression per breakpoint); CI evidence covers unit, Sass, and accessibility tests but not responsive-layout regression.

What the system needs to show: Responsive behavior is continuously tested across the matrix

34+1.25Confirmed gap
Components: Accessibility behavior
Why the system lost points

Reach score 4 by publishing current assistive-technology and automated execution results, regression history, and measured exception use for the evaluated release.

What the system needs to show: Assistive-technology coverage and regressions are continuously measured

34+1.25Confirmed gap
Structure: Layout primitives
Why the system lost points

Anchor 4 would require validated or measured grid usage and documented exceptions (for example, lint rules, usage telemetry, or a consistency audit); no such validation or measurement evidence is present in the packet.

What the system needs to show: Layout use and exceptions are validated and measured

34+1.25Confirmed gap
Structure: Composition guidance
Why the system lost points

Composition rules are expressed as prose guidance and worked code examples, not as executable or automatically validated contracts (for example, no lint rule or schema enforcing slot usage), so anchor 4 is not supported.

What the system needs to show: Composition rules are executable or automatically validated

34+1.25Confirmed gap
Structure: Patterns and templates
Why the system lost points

Anchor 4 requires measured pattern use, outcomes, and lifecycle tracking; no usage/outcome telemetry or lifecycle metrics for any of these patterns or templates are present in the evidence.

What the system needs to show: Pattern use, outcomes, and lifecycle are measured

34+1.25Confirmed gap
Structure: Navigation, focus, and state ownership
Why the system lost points

Anchor 4 requires these contracts to be executable and continuously verified; modal test source exists (modal.spec.js) but the evidence does not confirm CI wiring or an observed execution/pass result, so continuous verification cannot be claimed. Comprehensive tested-ownership evidence is also concentrated in modal and header rather than spanning every declared component, since alert's dismiss-state ownership is explicitly still in progress.

What the system needs to show: Cross-composition contracts are executable and continuously verified

34+1.25Confirmed gap
Governance: Named ownership
Why the system lost points

No public evidence of measured ownership health or service expectations (for example, response-time SLAs, staffing trend data, escalation success rates); governance known_limitations explicitly place GSA staffing and review-time data outside this public evaluation.

What the system needs to show: Ownership health and service expectations are measured

34+1.25Proof needed
Governance: Contribution and review
Why the system lost points

No public evidence quantifies review throughput, time-to-merge, or proposal approval/rejection rates, which anchor 4 requires.

What the system needs to show: Review quality, throughput, and outcomes are measured

34+1.25Proof needed
Governance: Releases, migration, and deprecation
Why the system lost points

No public evidence that migration success or downstream compatibility is measured across consumer USWDS implementations after a breaking release (for example, the 3.14.0 memorable-date and accordion markup changes); automated gates verify release-artifact integrity and vulnerability thresholds but not consumer migration outcomes.

What the system needs to show: Compatibility and migration success are validated and measured

34+1.25Proof needed
Governance: Quality enforcement and feedback
Why the system lost points

No public evidence shows adoption metrics or systematic regression measurement across releases, and only a one-time (March 2025) ACR/VPAT assessment exists rather than continuous measurement, so anchor 4's requirement that quality, adoption, exceptions, and regressions all be measured and acted on is not fully met.

What the system needs to show: Quality, adoption, exceptions, and regressions are measured and acted on

34+1.25Proof needed

Study footnotes

Use these notes and files to check how the study was run, how the results were scored, and which evidence was included.

How the study worked

Results and data

Agent-test files

Bundle records

Study notes

U.S. Web Design System study details
Publication status
Approved
Human review coverage
100%
Assessor agreement
80%
Warnings resolved
2
Warnings unresolved
0
Evidence completeness
100%
Evidence cutoff
2026-09-01
Assessor profile
claude-code/claude-sonnet-5/claude-json/contract-2
Passes
3
Disposition
pilot
Deep sample
11 components
Compositions
1 flow(s), 2 pattern(s)
Governance
public

How to read this score: Scores show how closely the captured evidence meets each rubric anchor. A criterion score of 3 maps to 75 and means the configured anchor is comprehensive, operational, or tested as defined by that criterion.

Evidence boundary: “Not observed” means the study did not find that result in the captured public evidence. It does not prove that the company lacks the capability internally. The team can share current internal results for a re-run.

Composition evidence: complete-complex-form: system-authored, form-error-recovery: system-authored, not-found-recovery: system-authored.

Component sample choices: alert: system-authored, button: system-authored, card: system-authored, checkbox: system-authored, form: system-authored, header: system-authored, layout-grid: mixed, modal: system-authored, step-indicator: system-authored, table: system-authored, text-input: system-authored. These choices set what the study covers. Any mappings written by the publisher are labeled separately.

Scope and limitations (9)
  • This scorecard describes capability supported by the configured evidence snapshot.
  • Missing public evidence is reported as unknown and is not evidence that an internal capability is absent.
  • Repeated outputs from one assessor model measure agreement, not statistical independence.
  • Deep component findings are scoped to 11 declared component samples across 10 archetypes unless system-wide evidence is cited.
  • Structure findings use 1 declared flow sample(s) and 2 declared pattern sample(s).
  • Governance findings describe public evidence only.
  • Internal GSA staffing, adoption, review-time, exception, and quality trend data are outside this public evaluation.
  • The public evidence does not establish every internal decision and approval used for design-kit and code changes.
  • The official design-kit repository states that USWDS had one staff member in March 2026 and did not expect to prioritize design-file updates; the study evaluates the resulting public evidence boundary without inferring unobserved internal capability.