{ "baseline_score": 68.75, "claim_boundary": "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.", "editorial": { "area_findings": { "bindings": { "summary": "Bindings scored 50%, the most concerning readiness result. The official Figma kit targets 3.11.0 while the evaluated code is 3.14.0, and no public machine-readable mapping resolved the gap.", "what_to_change": "Publish a current Figma export and a versioned manifest linking design component, variant, and variable identifiers to USWDS packages, classes, utilities, supported choices, and deprecations. Retain compatibility and intentional-mismatch results for a re-run.", "what_we_found": "Components and tokens exist in both design and code, but the available evidence did not confirm current names, properties, variables, supported choices, and deprecations one to one.", "why_it_matters": "Designers, engineers, and agents must otherwise guess whether the Figma choice, documentation name, class, utility, or package export is authoritative." }, "components": { "summary": "Components scored 68.75%, a mixed result. Core, responsive, and accessibility behavior are strong, while complete normal and recovery state coverage is incomplete.", "what_to_change": "Define which states apply to each component and pattern, implement representative recovery paths, and publish current type, interaction, responsive, keyboard, and accessibility results. Retain the matrix, tests, failures, exceptions, and fixes.", "what_we_found": "The sampled components have detailed implementation and accessibility guidance. Loading, empty, permission, retry, review, corrected, and submitted states were not all demonstrated as owned, executable examples.", "why_it_matters": "Users experience services in validation, waiting, failure, correction, and completion states as often as they experience the default component state." }, "foundations": { "summary": "Foundations scored 75%, a good result that shows mature tokens and delivery. The missing quarter reflects the absence of published cross-consumer validation and adoption measures.", "what_to_change": "Publish a release report that compares source tokens with generated outputs and the current Figma variables, tests supported modes and breakpoints, and records migration impact. Retain the manifest, passing result, seeded-failure result, and owner approval for a re-run.", "what_we_found": "USWDS provides a coherent token taxonomy, primitives, responsive settings, theme controls, and a versioned package. The study did not find a current published result comparing every supported output or measuring downstream use.", "why_it_matters": "A stable foundation reduces product-level variation, but release teams still need evidence that generated outputs and consumers remain compatible after changes." }, "governance": { "summary": "Governance scored 75%, a good result supported by clear public ownership, contribution, release, and quality practices. Public outcome trends were the main missing evidence.", "what_to_change": "Publish baselines, targets, trends, owners, and follow-up decisions for review, migration, adoption, exceptions, regressions, and accessibility conformance. Retain the metrics pack and decisions it changed.", "what_we_found": "USWDS documents how changes are proposed, reviewed, tested, released, and supported. The study did not find current public trends for review health, migrations, adoption, exceptions, or regressions, and the available accessibility conformance report covers 3.11.0 rather than 3.14.0.", "why_it_matters": "Leaders need results over time to know whether releases migrate safely, accessibility regressions close, contributors receive timely decisions, and the system reaches agencies." }, "structure": { "summary": "Structure scored 75%, a good readiness result, and the agent passed two of three complete-form runs. The remaining reliability gap was one incorrect workflow action label.", "what_to_change": "Publish one downloadable three-step reference using stable workflow labels with USWDS grid and form utilities, injected submission, exact validation, state persistence, success, failure, retry, and 320-pixel behavior. Require three fresh agent runs to pass every check.", "what_we_found": "USWDS layout grids, form patterns, validation, and multi-page guidance supported complete typed, accessible, responsive flows in two runs. The third used Continue instead of Review application at the Supporting documents transition.", "why_it_matters": "Complete journeys depend on stable labels and transitions as well as correct layout, state, validation, submission, and recovery behavior." } }, "bottom_line": "USWDS already provides strong code, components, accessibility guidance, patterns, and public governance. The highest-value readiness step is to keep the Figma kit and released package linked through a versioned mapping. A canonical three-step form with stable transition labels would address the one remaining agent failure, while broader executable quality and operating evidence would support continued improvement.", "central_finding": "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.", "concrete_example": "In the controlled three-step application task, runs 1 and 2 passed strict TypeScript, axe accessibility, interaction, submission, success, failure, retry, and responsive checks at 320 and 1024 pixels. Run 3 passed type, accessibility, and responsive checks but labeled the Supporting documents action Continue instead of Review application, so the exact interaction path stopped before submission.", "headline": "USWDS is mature in code, while its design kit remains the main readiness gap.", "hero": "USWDS was reviewed to answer two questions: How ready is the system to keep design and production aligned? Can an AI coding agent use its public guidance to produce working software?", "hero_asset": "uswds", "phase_summaries": { "next": { "action": "Publish a versioned manifest connecting current Figma components, properties, and variables to package exports, classes, utilities, supported choices, and deprecations. Compare it during release.", "decision": "Whether a design-kit or code change is safe to publish as compatible.", "finish_line": "Every sampled mapping is current, and a seeded mismatch fails the release check with the affected design and code identifiers.", "owner": "USWDS design-kit, token, component, documentation, and release-infrastructure teams", "problem": "The official Figma kit targets USWDS 3.11.0 while the evaluated package is 3.14.0, and the public evidence did not include a machine-readable cross-surface mapping.", "save": "Figma export, cross-surface manifest, comparison implementation, release results, drift report, and approved exceptions", "title": "Keep the design kit and released code on the same contract." }, "now": { "action": "Publish one canonical implementation that combines stable transition labels with USWDS grid utilities, exact validation, state persistence, injected submission, success, failure, retry, and 320-pixel behavior. Test it as a complete flow.", "decision": "Whether teams can use USWDS guidance for agent-assisted multi-step forms without routine correction.", "finish_line": "The reference passes type, accessibility, interaction, and responsive checks, followed by three new controlled agent runs in a row.", "owner": "USWDS pattern, component, accessibility, documentation, and developer-experience teams", "problem": "Two of three controlled three-step forms passed every check; the third used Continue instead of the required Review application transition.", "save": "Reference source, agent-facing guidance, screenshots, harness output, and three controlled run records", "title": "Make one complete public-service form work every time." }, "operate": { "action": "Publish the target, current result, trend, accountable owner, and next decision for each operating measure, including accessibility conformance for the current stable release.", "decision": "Where leadership should invest, change ownership, adjust a release, or strengthen migration support.", "finish_line": "The team can show current trends and identify a staffing, release, migration, or process decision changed by those results.", "owner": "USWDS governance, release, accessibility, program, and design-infrastructure leadership", "problem": "The public evidence did not show current trends for ownership health, review outcomes, migrations, adoption, exceptions, or regressions. GSA may already track some of this internally.", "save": "Metrics pack, current accessibility conformance evidence, exception outcomes, and recorded follow-up decisions", "title": "Use operating evidence to direct USWDS investment." }, "scale": { "action": "Define the required conditions for supported components and patterns, turn critical composition rules into executable checks, and publish current results with owned exceptions.", "decision": "Whether a supported component or public-service pattern is ready for release across its promised conditions.", "finish_line": "Required states, viewports, keyboard paths, accessibility checks, and complete patterns pass with current evidence and expiring exceptions.", "owner": "USWDS component, pattern, accessibility, quality, and agency implementation teams", "problem": "The study did not find one current results view spanning component states, breakpoints, assistive technology, layout rules, and complete service patterns.", "save": "Quality matrix, CI output, accessibility evidence, viewport screenshots, flow results, and exception register", "title": "Test difficult states and complete patterns across the system." } }, "publisher_name": "U.S. General Services Administration", "publisher_url": "https://designsystem.digital.gov/", "readiness_verdict": "USWDS is ready for agent-assisted work on the tested tokens, components, validated fields, governance process, and most complete-form attempts. Multi-step forms still benefit from human review of workflow labels and transitions. Design-to-code work needs a current compatibility statement or versioned mapping before teams can assume the Figma kit matches the released package.", "report_kicker": "USWDS evaluation", "report_title": "U.S. Web Design System report", "roadmap_heading": "How USWDS can get better", "standfirst": "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.", "strengths": [ "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" ], "why_it_matters": "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." }, "evidence_reconciliation": { "purpose": "Confirm whether capabilities unavailable in the evaluated public evidence already exist before commissioning duplicate work.", "requests": [ "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" ], "required": true }, "initiatives": [ { "acceptance_criteria": [ "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." ], "actions": [ "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." ], "classification": "observed-agent-failure", "criterion_impacts": [], "decision_enabled": "Whether USWDS public guidance is reliable enough for agent-assisted multi-step forms without routine human correction.", "dependencies": [], "effort": "medium", "evidence_to_retain": [ "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" ], "horizon": "now", "id": "agent-complete-form-reliability", "outcome": "Designers, engineers, and agents can start from one complete USWDS form that keeps workflow labels, validation, layout, state, submission, and recovery behavior consistent together.", "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.", "projected_overall_lift": 0.0, "score_effect": "agent-performance", "sequence": 1, "suggested_owners": [ "USWDS form and layout component owners", "USWDS accessibility and pattern owners", "USWDS documentation and developer-experience owners" ], "title": "Make the complete form reliable in every repeated run", "type": "agent-reliability" }, { "acceptance_criteria": [ "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." ], "actions": [ "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." ], "classification": "evidence-gap", "criterion_impacts": [ { "area": "foundations", "criterion_id": "token_taxonomy", "from_score": 3.0, "to_score": 4.0 }, { "area": "foundations", "criterion_id": "primitives", "from_score": 3.0, "to_score": 4.0 }, { "area": "foundations", "criterion_id": "modes", "from_score": 3.0, "to_score": 4.0 }, { "area": "foundations", "criterion_id": "delivery", "from_score": 3.0, "to_score": 4.0 }, { "area": "bindings", "criterion_id": "naming_parity", "from_score": 2.0, "to_score": 4.0 }, { "area": "bindings", "criterion_id": "contract_correspondence", "from_score": 2.0, "to_score": 4.0 }, { "area": "bindings", "criterion_id": "token_parity", "from_score": 2.0, "to_score": 4.0 }, { "area": "bindings", "criterion_id": "traceability", "from_score": 2.0, "to_score": 4.0 } ], "decision_enabled": "Whether a Figma, token, utility, component, or package change is safe to publish as compatible.", "dependencies": [], "effort": "large", "evidence_to_retain": [ "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" ], "horizon": "next", "id": "cross-surface-release-contract", "outcome": "A designer, engineer, or agent can trace every supported design choice to the current code API, and a release cannot introduce an unexplained difference.", "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.", "projected_overall_lift": 15.0, "score_effect": "readiness", "sequence": 2, "suggested_owners": [ "USWDS design-kit maintainers", "USWDS token and component owners", "USWDS documentation and release-infrastructure owners" ], "title": "Keep the Figma kit and released code on one versioned contract", "type": "capability-investment" }, { "acceptance_criteria": [ "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." ], "actions": [ "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." ], "classification": "confirmed-deficiency", "criterion_impacts": [ { "area": "components", "criterion_id": "core_coverage", "from_score": 3.0, "to_score": 4.0 }, { "area": "components", "criterion_id": "state_coverage", "from_score": 2.0, "to_score": 4.0 }, { "area": "components", "criterion_id": "responsive_behavior", "from_score": 3.0, "to_score": 4.0 }, { "area": "components", "criterion_id": "accessibility_behavior", "from_score": 3.0, "to_score": 4.0 }, { "area": "structure", "criterion_id": "layout_primitives", "from_score": 3.0, "to_score": 4.0 }, { "area": "structure", "criterion_id": "composition_guidance", "from_score": 3.0, "to_score": 4.0 }, { "area": "structure", "criterion_id": "patterns_templates", "from_score": 3.0, "to_score": 4.0 }, { "area": "structure", "criterion_id": "interaction_ownership", "from_score": 3.0, "to_score": 4.0 } ], "decision_enabled": "Whether a supported component or public-service pattern is ready across the conditions USWDS promises.", "dependencies": [ "agent-complete-form-reliability", "cross-surface-release-contract" ], "effort": "program", "evidence_to_retain": [ "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" ], "horizon": "scale", "id": "executable-quality-matrix", "outcome": "Teams can see which states and environments each component and pattern supports, which checks passed, and who owns every remaining failure or exception.", "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.", "projected_overall_lift": 11.25, "score_effect": "both", "sequence": 3, "suggested_owners": [ "USWDS component and pattern maintainers", "USWDS accessibility and quality owners", "Agency product teams representing supported service flows" ], "title": "Test difficult states and complete public-service patterns", "type": "capability-investment" }, { "acceptance_criteria": [ "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." ], "actions": [ "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." ], "classification": "evidence-gap", "criterion_impacts": [ { "area": "governance", "criterion_id": "ownership", "from_score": 3.0, "to_score": 4.0 }, { "area": "governance", "criterion_id": "contribution_review", "from_score": 3.0, "to_score": 4.0 }, { "area": "governance", "criterion_id": "release_safety", "from_score": 3.0, "to_score": 4.0 }, { "area": "governance", "criterion_id": "quality_enforcement", "from_score": 3.0, "to_score": 4.0 } ], "decision_enabled": "Where USWDS leadership should invest, change ownership, adjust a release, or strengthen migration support.", "dependencies": [ "executable-quality-matrix" ], "effort": "program", "evidence_to_retain": [ "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" ], "horizon": "operate", "id": "governance-outcome-evidence", "outcome": "USWDS leadership can see whether releases migrate safely, quality problems close, agencies adopt supported versions, and ownership or process changes improve the result.", "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.", "projected_overall_lift": 5.0, "score_effect": "readiness", "sequence": 4, "suggested_owners": [ "USWDS governance and release owners", "USWDS accessibility and program leadership", "USWDS component maintainers and agency adoption partners" ], "title": "Use operating evidence to direct USWDS investment", "type": "evidence-reconciliation" } ], "review_status": "approved", "reviewed_at": "2026-09-01T21:21:46Z", "roadmap_format": "ds-eval/implementation-roadmap@1", "score_ceiling": [ { "anchor_points_needed": 1.0, "area": "foundations", "area_label": "Foundations", "ceiling_anchor": "The token graph is validated, measured, and maintained across consumers", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "token_taxonomy", "current_score": 3.0, "gap": "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.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Token taxonomy and semantics", "maximum_overall_lift": 1.25, "next_anchor": "The token graph is validated, measured, and maintained across consumers", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "foundations", "area_label": "Foundations", "ceiling_anchor": "Primitive coverage and adoption are measured and governed", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "primitives", "current_score": 3.0, "gap": "No public evidence that primitive coverage or adoption is measured or governed (e.g., no audit data or usage telemetry showing what proportion of components consume tokenized primitives vs. hard-coded values), so anchor 4 is not supported.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Primitive completeness", "maximum_overall_lift": 1.25, "next_anchor": "Primitive coverage and adoption are measured and governed", "recommended_change": "Publish primitive-adoption or utility-usage audits (e.g., share of components using tokenized values vs. hard-coded values) as part of governance reporting." }, { "anchor_points_needed": 1.0, "area": "foundations", "area_label": "Foundations", "ceiling_anchor": "Mode compatibility is continuously validated across supported consumers", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "modes", "current_score": 3.0, "gap": "No evidence of continuous, cross-consumer validation of mode compatibility (e.g., 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.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Modes and adaptation", "maximum_overall_lift": 1.25, "next_anchor": "Mode compatibility is continuously validated across supported consumers", "recommended_change": "Add and publish continuous validation (e.g., automated visual regression or contrast/token-graph checks across breakpoints and theme configurations) covering the documented supported consumer matrix." }, { "anchor_points_needed": 1.0, "area": "foundations", "area_label": "Foundations", "ceiling_anchor": "Delivery contracts are validated and migration impact is measured", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "delivery", "current_score": 3.0, "gap": "No evidence of measured migration impact (e.g., automated breaking-change impact analysis across downstream consumers) or delivery-contract validation beyond qualitative changelog entries, so anchor 4 is not supported.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Consumable delivery and versioning", "maximum_overall_lift": 1.25, "next_anchor": "Delivery contracts are validated and migration impact is measured", "recommended_change": "Publish automated migration-impact reporting (e.g., breaking-change diffing tooling or downstream-consumer adoption telemetry) alongside the existing prose changelog." }, { "anchor_points_needed": 2.0, "area": "bindings", "area_label": "Bindings", "ceiling_anchor": "Parity is automatically checked and drift is measured", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "naming_parity", "current_score": 2.0, "gap": "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.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Naming parity", "maximum_overall_lift": 2.5, "next_anchor": "Names are systematically aligned across surfaces", "recommended_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." }, { "anchor_points_needed": 2.0, "area": "bindings", "area_label": "Bindings", "ceiling_anchor": "Machine-readable mappings continuously validate shared contracts and explicitly classify surface-specific controls", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "contract_correspondence", "current_score": 2.0, "gap": "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.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Design-to-code contract correspondence", "maximum_overall_lift": 2.5, "next_anchor": "Supported choices, derived states, slots, and composition map coherently, and surface-specific controls are explicitly classified", "recommended_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." }, { "anchor_points_needed": 2.0, "area": "bindings", "area_label": "Bindings", "ceiling_anchor": "Cross-surface token parity is automatically validated", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "token_parity", "current_score": 2.0, "gap": "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.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Token parity", "maximum_overall_lift": 2.5, "next_anchor": "Token identity and modes align across design and code", "recommended_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." }, { "anchor_points_needed": 2.0, "area": "bindings", "area_label": "Bindings", "ceiling_anchor": "Traceability and deprecation drift are automatically enforced", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "traceability", "current_score": 2.0, "gap": "Reach score 3 by publishing a versioned component-level manifest linking current Figma identifiers and variables to supported and deprecated USWDS code APIs.", "initiative_ids": [ "cross-surface-release-contract" ], "label": "Traceability and deprecation", "maximum_overall_lift": 2.5, "next_anchor": "Versioned mappings expose supported and deprecated APIs", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "components", "area_label": "Components", "ceiling_anchor": "Gaps, adoption, and component health are measured", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "core_coverage", "current_score": 3.0, "gap": "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.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Core component coverage", "maximum_overall_lift": 1.25, "next_anchor": "Gaps, adoption, and component health are measured", "recommended_change": "Publish a system-wide, dated component-health/gap dashboard covering the full catalog, not just accessibility test tables for individually-visited component pages." }, { "anchor_points_needed": 2.0, "area": "components", "area_label": "Components", "ceiling_anchor": "State contracts are executable, tested, and measured", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "state_coverage", "current_score": 2.0, "gap": "Reach score 3 by documenting recovery-state ownership consistently across the sample and saving current execution results that demonstrate those contracts.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Normal, recovery, and permission states", "maximum_overall_lift": 2.5, "next_anchor": "Normal and recovery states have comprehensive ownership and guidance", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "components", "area_label": "Components", "ceiling_anchor": "Responsive behavior is continuously tested across the matrix", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "responsive_behavior", "current_score": 3.0, "gap": "No evidence of continuous, automated testing across the responsive breakpoint matrix (e.g., visual regression per breakpoint); CI evidence covers unit, Sass, and accessibility tests but not responsive-layout regression.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Responsive behavior", "maximum_overall_lift": 1.25, "next_anchor": "Responsive behavior is continuously tested across the matrix", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "components", "area_label": "Components", "ceiling_anchor": "Assistive-technology coverage and regressions are continuously measured", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "accessibility_behavior", "current_score": 3.0, "gap": "Reach score 4 by publishing current assistive-technology and automated execution results, regression history, and measured exception use for the evaluated release.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Accessibility behavior", "maximum_overall_lift": 1.25, "next_anchor": "Assistive-technology coverage and regressions are continuously measured", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "structure", "area_label": "Structure", "ceiling_anchor": "Layout use and exceptions are validated and measured", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "layout_primitives", "current_score": 3.0, "gap": "Anchor 4 would require validated or measured grid usage and documented exceptions (e.g., lint rules, usage telemetry, or a consistency audit); no such validation or measurement evidence is present in the packet.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Layout primitives", "maximum_overall_lift": 1.25, "next_anchor": "Layout use and exceptions are validated and measured", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "structure", "area_label": "Structure", "ceiling_anchor": "Composition rules are executable or automatically validated", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "composition_guidance", "current_score": 3.0, "gap": "Composition rules are expressed as prose guidance and worked code examples, not as executable or automatically validated contracts (e.g., no lint rule or schema enforcing slot usage), so anchor 4 is not supported.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Composition guidance", "maximum_overall_lift": 1.25, "next_anchor": "Composition rules are executable or automatically validated", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "structure", "area_label": "Structure", "ceiling_anchor": "Pattern use, outcomes, and lifecycle are measured", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "patterns_templates", "current_score": 3.0, "gap": "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.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Patterns and templates", "maximum_overall_lift": 1.25, "next_anchor": "Pattern use, outcomes, and lifecycle are measured", "recommended_change": "Publish a downloadable, working reference implementation (e.g., a Storybook or template repo) that demonstrates the full complex-form flow across introduction, in-progress, validation-error, review, and submitted states." }, { "anchor_points_needed": 1.0, "area": "structure", "area_label": "Structure", "ceiling_anchor": "Cross-composition contracts are executable and continuously verified", "ceiling_score": 4.0, "classification": "confirmed-deficiency", "criterion_id": "interaction_ownership", "current_score": 3.0, "gap": "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.", "initiative_ids": [ "executable-quality-matrix" ], "label": "Navigation, focus, and state ownership", "maximum_overall_lift": 1.25, "next_anchor": "Cross-composition contracts are executable and continuously verified", "recommended_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." }, { "anchor_points_needed": 1.0, "area": "governance", "area_label": "Governance", "ceiling_anchor": "Ownership health and service expectations are measured", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "ownership", "current_score": 3.0, "gap": "No public evidence of measured ownership health or service expectations (e.g., response-time SLAs, staffing trend data, escalation success rates); governance known_limitations explicitly place GSA staffing and review-time data outside this public evaluation.", "initiative_ids": [ "governance-outcome-evidence" ], "label": "Named ownership", "maximum_overall_lift": 1.25, "next_anchor": "Ownership health and service expectations are measured", "recommended_change": "Activate per-package or per-directory CODEOWNERS entries mapping components to their named Maintainer, and publish aggregate ownership-health metrics (e.g., response time to first review) to support a future anchor-4 claim." }, { "anchor_points_needed": 1.0, "area": "governance", "area_label": "Governance", "ceiling_anchor": "Review quality, throughput, and outcomes are measured", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "contribution_review", "current_score": 3.0, "gap": "No public evidence quantifies review throughput, time-to-merge, or proposal approval/rejection rates, which anchor 4 requires.", "initiative_ids": [ "governance-outcome-evidence" ], "label": "Contribution and review", "maximum_overall_lift": 1.25, "next_anchor": "Review quality, throughput, and outcomes are measured", "recommended_change": "Publish aggregate review-throughput metrics (e.g., median PR review time, proposal approval rate) to support a measured-outcomes governance claim." }, { "anchor_points_needed": 1.0, "area": "governance", "area_label": "Governance", "ceiling_anchor": "Compatibility and migration success are validated and measured", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "release_safety", "current_score": 3.0, "gap": "No public evidence that migration success or downstream compatibility is measured across consumer USWDS implementations after a breaking release (e.g., the 3.14.0 memorable-date and accordion markup changes); automated gates verify release-artifact integrity and vulnerability thresholds but not consumer migration outcomes.", "initiative_ids": [ "governance-outcome-evidence" ], "label": "Releases, migration, and deprecation", "maximum_overall_lift": 1.25, "next_anchor": "Compatibility and migration success are validated and measured", "recommended_change": "Track and publish post-release adoption or regression signals (e.g., issue volume tagged to a specific breaking-change release) to close the loop between shipping a breaking change and confirming safe migration." }, { "anchor_points_needed": 1.0, "area": "governance", "area_label": "Governance", "ceiling_anchor": "Quality, adoption, exceptions, and regressions are measured and acted on", "ceiling_score": 4.0, "classification": "evidence-gap", "criterion_id": "quality_enforcement", "current_score": 3.0, "gap": "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.", "initiative_ids": [ "governance-outcome-evidence" ], "label": "Quality enforcement and feedback", "maximum_overall_lift": 1.25, "next_anchor": "Quality, adoption, exceptions, and regressions are measured and acted on", "recommended_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." } ], "scorecard_fingerprint": "7b6c8de05bad67e729f8d78d1de373fe10574714f98a02a0585a6b130d5ca234", "system": "uswds", "system_name": "U.S. Web Design System", "target_score": 100.0, "visibility": "public" }