{ "areas": [ { "criteria": [ { "anchors": [ "No inspectable token system", "Mostly raw values or isolated constants", "A documented basic semantic layer exists", "Semantic layers and aliases are comprehensive and operational", "The token graph is validated, measured, and maintained across consumers" ], "critical": true, "guidance": "Evaluate raw, semantic, component, and alias relationships without treating naming alone as proof of semantics. System-wide design claims require full-file current-library variable evidence; representative selections remain sample-only.", "id": "token_taxonomy", "label": "Token taxonomy and semantics" }, { "anchors": [ "No reusable primitives are evidenced", "A small ad hoc primitive set exists", "Core primitives are documented and usable", "Primitives are comprehensive and consistently consumed", "Primitive coverage and adoption are measured and governed" ], "critical": false, "guidance": "Evaluate the reusable low-level visual and interaction primitives available to component and product authors.", "id": "primitives", "label": "Primitive completeness" }, { "anchors": [ "Required modes are unsupported or broken", "Modes rely on manual overrides", "Basic documented modes work in common cases", "Modes are systematic across tokens and components", "Mode compatibility is continuously validated across supported consumers" ], "critical": true, "guidance": "Evaluate theming, brand, density, responsive, platform, and accessibility modes that the system claims to support.", "id": "modes", "label": "Modes and adaptation" }, { "anchors": [ "No consumable foundation artifact", "Artifacts are informal or unversioned", "A versioned basic delivery mechanism exists", "Multiple consumers receive consistent versioned artifacts", "Delivery contracts are validated and migration impact is measured" ], "critical": false, "guidance": "Evaluate whether foundations are published in stable, versioned, machine-consumable forms.", "id": "delivery", "label": "Consumable delivery and versioning" } ], "detail": "tokens and primitives", "id": "foundations", "label": "Foundations" }, { "criteria": [ { "anchors": [ "Design and code identities cannot be reconciled", "Mappings are mostly tribal or ad hoc", "Common names are documented with known gaps", "Names are systematically aligned across surfaces", "Parity is automatically checked and drift is measured" ], "critical": false, "guidance": "Compare names across design assets, documentation, public package exports, and examples for the declared deep-component sample. Use catalog evidence only for inventory breadth.", "id": "naming_parity", "label": "Naming parity" }, { "anchors": [ "Shared design choices require unavailable, contradictory, or private implementation mechanisms", "Shared mappings contain material unexplained gaps or depend frequently on manual translation", "Core consumer choices correspond through documented APIs or runtime mechanisms, with justified surface-specific controls excluded", "Supported choices, derived states, slots, and composition map coherently, and surface-specific controls are explicitly classified", "Machine-readable mappings continuously validate shared contracts and explicitly classify surface-specific controls" ], "critical": true, "dispositions": [ "shared_contract: A consumer-controlled choice exists on both surfaces and should correspond, such as variant, size, tone, disabled, or composition.", "derived_mapping: The same meaning is expressed through different mechanisms, such as a Figma hover state mapping to CSS :hover or runtime interaction. Treat a supported mapping as correspondence, not a gap.", "design_only: An authoring, preview, annotation, or simulation control has no necessary code prop. Exclude it from the parity comparison when the rationale is supported.", "runtime_only: An event handler, identifier, routing, data, or other runtime concern has no necessary Figma property. Exclude it from the parity comparison when the rationale is supported.", "genuine_gap: A meaningful supported choice or behavior cannot be produced on the counterpart surface, conflicts with it, or lacks an evidence-backed rationale. This disposition lowers the score.", "unknown: Evidence cannot establish the intended mapping or disposition. Use insufficient evidence or request review; do not count it automatically as a mismatch." ], "guidance": "Evaluate whether consumer-controlled design choices correspond to supported code APIs or documented runtime mechanisms. Do not require identical property schemas. Recognize mappings to pseudo-states, platform primitives, internal state, or composition patterns. Exclude justified authoring-only and runtime-only controls; penalize only unsupported, contradictory, or unexplained gaps in the shared contract.", "id": "contract_correspondence", "label": "Design-to-code contract correspondence" }, { "anchors": [ "Design and implementation token models conflict", "Only visual values align manually", "Core semantic tokens align with documented gaps", "Token identity and modes align across design and code", "Cross-surface token parity is automatically validated" ], "critical": true, "guidance": "Evaluate whether design variables/styles and implementation tokens share semantics, modes, and supported values.", "id": "token_parity", "label": "Token parity" }, { "anchors": [ "No reliable traceability exists", "Links or mappings are informal and stale", "Core assets have maintained references", "Versioned mappings expose supported and deprecated APIs", "Traceability and deprecation drift are automatically enforced" ], "critical": false, "guidance": "Evaluate Code Connect, manifests, links, or other mechanisms that identify supported APIs and obsolete mappings.", "id": "traceability", "label": "Traceability and deprecation" } ], "detail": "how design maps to code", "id": "bindings", "label": "Bindings" }, { "criteria": [ { "anchors": [ "Core product needs lack reusable components", "Coverage is narrow or fragmented", "Common needs have documented components", "Coverage is comprehensive for the stated scope", "Gaps, adoption, and component health are measured" ], "critical": false, "guidance": "Evaluate catalog coverage against the system's stated product scope rather than a universal component count. Do not treat catalog presence as proof of deep state, responsive, binding, or accessibility quality.", "id": "core_coverage", "label": "Core component coverage" }, { "anchors": [ "Required states are absent or unsafe", "Only happy paths are consistently supported", "Common states have basic contracts", "Normal and recovery states have comprehensive ownership and guidance", "State contracts are executable, tested, and measured" ], "critical": true, "guidance": "Inspect loading, empty, error, disabled, validation, permission, retry, and partial-success behavior across the declared deep-component and composition samples. Do not generalize a single component's state matrix to the system.", "id": "state_coverage", "label": "Normal, recovery, and permission states" }, { "anchors": [ "Components fail required responsive conditions", "Responsive behavior is left to consumers", "Basic behavior and constraints are documented", "Components adapt consistently across supported conditions", "Responsive behavior is continuously tested across the matrix" ], "critical": false, "guidance": "Evaluate behavior across declared flow viewports plus the containers, density, and content conditions the system supports. Size variants alone do not prove responsive behavior.", "id": "responsive_behavior", "label": "Responsive behavior" }, { "anchors": [ "Confirmed critical accessibility failures", "Accessibility is inconsistent or consumer-owned", "Common interactions have documented accessible behavior", "Accessible behavior is comprehensive and tested", "Assistive-technology coverage and regressions are continuously measured" ], "critical": true, "guidance": "Evaluate implemented semantics, keyboard behavior, focus, names, contrast support, and assistive-technology guidance across the declared deep sample and flow states.", "id": "accessibility_behavior", "label": "Accessibility behavior" } ], "detail": "coverage and states", "id": "components", "label": "Components" }, { "criteria": [ { "anchors": [ "No reusable layout contract is evidenced", "Layout is mostly custom per feature", "Basic layout primitives and rules exist", "Layout primitives cover the stated product scope", "Layout use and exceptions are validated and measured" ], "critical": false, "guidance": "Evaluate grids, stacks, spacing, containers, shells, and supported responsive layout mechanisms using actual composed artifacts, not navigation titles or isolated component sheets.", "id": "layout_primitives", "label": "Layout primitives" }, { "anchors": [ "Components cannot be composed reliably", "Composition depends on undocumented examples", "Common combinations have basic guidance", "Composition contracts cover supported product assemblies", "Composition rules are executable or automatically validated" ], "critical": false, "guidance": "Evaluate rules for combining components, slots, hierarchy, density, content, and extension in the declared flow and pattern samples. Component inventories alone do not prove composition quality.", "id": "composition_guidance", "label": "Composition guidance" }, { "anchors": [ "No reusable product patterns are evidenced", "Examples are isolated and noncanonical", "Common patterns or templates are documented", "Patterns cover important tasks and remain linked to components", "Pattern use, outcomes, and lifecycle are measured" ], "critical": false, "guidance": "Evaluate the declared representative flow and additional patterns as reusable task patterns, page types, and reference implementations beyond isolated components.", "id": "patterns_templates", "label": "Patterns and templates" }, { "anchors": [ "Ownership conflicts create confirmed broken behavior", "Ownership is implicit and varies by implementation", "Common compositions document basic ownership", "Navigation, focus, and state contracts are comprehensive", "Cross-composition contracts are executable and continuously verified" ], "critical": true, "guidance": "Evaluate ownership across drawers, dialogs, routes, responsive transitions, async state, and nested compositions within the declared flow and patterns.", "id": "interaction_ownership", "label": "Navigation, focus, and state ownership" } ], "detail": "layout and composition", "id": "structure", "label": "Structure" }, { "criteria": [ { "anchors": [ "No ownership can be identified", "Ownership is informal or obsolete", "Core responsibilities and contacts are documented", "Decision rights and support boundaries are operational", "Ownership health and service expectations are measured" ], "critical": false, "guidance": "Evaluate accountable owners, support boundaries, decision rights, and escalation paths only within the declared public, private, or mixed governance evidence scope. Unavailable internal evidence is unknown.", "id": "ownership", "label": "Named ownership" }, { "anchors": [ "No review or contribution path is evidenced", "Review is informal and person-dependent", "A documented contribution and review path exists", "Cross-discipline review criteria and decisions are operational", "Review quality, throughput, and outcomes are measured" ], "critical": false, "guidance": "Evaluate proposal, contribution, design review, engineering review, and acceptance processes within the declared governance evidence scope, including named reviewers and operational acceptance criteria where evidenced.", "id": "contribution_review", "label": "Contribution and review" }, { "anchors": [ "Confirmed unsafe or opaque breaking-change process", "Changes rely on manual discovery and migration", "Versions and important changes are documented", "Deprecation and migration have explicit operational contracts", "Compatibility and migration success are validated and measured" ], "critical": true, "guidance": "Evaluate change communication, compatibility, deprecation, migration tooling, and lifecycle status within the declared governance evidence scope. Do not infer private migration outcomes from missing public reports.", "id": "release_safety", "label": "Releases, migration, and deprecation" }, { "anchors": [ "Required quality gates are absent or demonstrably ineffective", "Quality depends primarily on manual convention", "Core automated checks or review gates exist", "Quality gates cover the supported lifecycle and exceptions", "Quality, adoption, exceptions, and regressions are measured and acted on" ], "critical": true, "guidance": "Evaluate accessibility, testing, security, telemetry, adoption, waiver, and system-health gates within the declared governance evidence scope. Distinguish documented gates from measured outcomes.", "id": "quality_enforcement", "label": "Quality enforcement and feedback" } ], "detail": "review and ownership", "id": "governance", "label": "Governance" } ], "evidence_policy": { "precedence": [ "current observed implementation", "current normative documentation", "current examples and release material", "historical or potentially stale documentation" ], "proof_rules": [ "A sample-level observation must not be generalized to the whole system without system-wide evidence.", "A declared dependency or documented intention does not prove that a test or gate executes.", "Scores claiming tested, enforced, measured, or continuously validated capability require direct execution, result, or policy-enforcement evidence.", "Missing inaccessible evidence is unknown, not evidence of absence.", "Current observed implementation takes precedence over contradictory older prose, with the conflict disclosed." ], "score_proof_requirements": { "3": "Direct evidence must demonstrate comprehensive, operational behavior across the declared sample or a cited system-wide mechanism; documentation alone is insufficient when the anchor claims implementation or testing.", "4": "Direct evidence must demonstrate automated validation or measurement, current results, maintained ownership, and coverage across the claimed consumer or support matrix." } }, "id": "design-system-diagnostic", "sampling_profiles": { "cross-surface-comprehensive": { "accepted_foundation_coverage": [ "full-file" ], "deep_component_required_surfaces": [ "design", "code" ], "minimum_component_archetypes": 6, "minimum_components_per_flow": 5, "minimum_deep_components": 8, "minimum_flows": 1, "minimum_patterns": 2, "minimum_states_per_flow": 3, "minimum_viewports_per_flow": 2 }, "implementation-only": { "accepted_foundation_coverage": [ "implementation-only" ], "deep_component_required_surfaces": [ "code" ], "minimum_component_archetypes": 5, "minimum_components_per_flow": 5, "minimum_deep_components": 6, "minimum_flows": 1, "minimum_patterns": 2, "minimum_states_per_flow": 3, "minimum_viewports_per_flow": 2 }, "public-evidence-limited": { "accepted_foundation_coverage": [ "full-file", "representative", "unavailable" ], "deep_component_required_surfaces": [ "code" ], "minimum_component_archetypes": 5, "minimum_components_per_flow": 5, "minimum_deep_components": 6, "minimum_flows": 0, "minimum_patterns": 2, "minimum_states_per_flow": 3, "minimum_viewports_per_flow": 2 }, "specialized-system": { "accepted_foundation_coverage": [ "full-file", "representative", "implementation-only", "unavailable" ], "deep_component_required_surfaces": [ "code" ], "minimum_component_archetypes": 3, "minimum_components_per_flow": 3, "minimum_deep_components": 4, "minimum_flows": 0, "minimum_patterns": 1, "minimum_states_per_flow": 2, "minimum_viewports_per_flow": 1 } }, "score_max": 4, "title": "Design-system diagnostic", "version": "1.0.0" }