/system-benchmark

name: system-benchmark
description: "Benchmark a design system against industry standards and comparable public systems, producing a qualitative comparison across dimensions with specific, named reference points. Goes beyond an internal health assessment to answer 'how does our system compare to what good looks like out there?' Trigger when someone says: benchmark our system, how do we compare, industry comparison, rate our system against others, where do we stand, compare us to Material Design, how mature is our system, are we behind or ahead, competitive assessment of our design system, or anything about comparing a design system's maturity or quality against external benchmarks. Do NOT trigger for an internal health check without external comparison — use system-health for that. Do NOT trigger for auditing a specific dimension — use the specific audit skill for that."
references:
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/output-discipline.md

System Benchmark

A skill for benchmarking a design system against industry standards and comparable public systems, producing a qualitative comparison with specific reference points that answer: "How does our system compare to what good looks like?"

**Output type:** Proposal only. This skill produces analysis and comparisons. It does not make changes. It produces a benchmark report with findings, comparison context, and prioritised improvement areas.

---

Why this exists

System-health tells you if your system is healthy on its own terms. But it cannot answer: "Is our token architecture actually good? What do systems we admire look like at this layer?"

System Benchmark fills this gap. It compares your system against documented public benchmarks — published design system case studies, open-source system architectures, and industry maturity models — to give your findings context. A team that learns their token architecture is two tiers behind what mature enterprise systems typically have now has a specific target and gap to close.

This is not competitive intelligence. Design systems are not products competing in a market. This is calibration — understanding where your system sits on a maturity curve so you can prioritise investment.

---

Configuration

Check for `.ds-ops-config.yml` in the project root:

benchmark:
  system_type: "enterprise"          # enterprise, product, agency, government
  team_size: 5                        # Full-time design system team members
  system_age_months: 24               # How long the system has been in active development
  consumer_count: 12                  # Number of teams/products consuming the system
  comparison_targets:                 # Specific systems to compare against (optional)
    - "Material Design"
    - "Polaris"
    - "Carbon"

If no configuration exists, ask for: 1. System type (enterprise, product, agency, government) 2. Approximate team size 3. How long the system has been active 4. How many teams or products consume it

---

The benchmark framework

Twelve benchmark dimensions

The benchmark assesses twelve dimensions grouped into four pillars. For each dimension, assess the current state and compare it against what mature, publicly documented systems look like at that layer.

Pillar 1: Foundation quality

**1. Token architecture maturity** What to look for: Is there a formal token system? How many tiers (flat list, two-tier, three-tier)? Is aliasing consistent? Is the format standards-compliant (DTCG)? Is validation automated? Does it support multi-brand or multi-theme?

What mature systems look like: Full three-tier architecture with consistent aliasing, DTCG-compliant format, automated validation, and multi-brand support.

**2. Component API consistency** What to look for: Are prop naming conventions consistent across components? Are conventions documented? Are they enforced by linting? Are there typed API contracts?

What mature systems look like: Typed, linted, documented API contracts with automated consumer contract testing.

**3. Accessibility baseline** What to look for: Are ARIA attributes present and consistent? Is there automated a11y testing in CI? Has manual testing with assistive technology been done? Are keyboard patterns documented? Is reduced motion and high contrast supported?

What mature systems look like: Full WCAG 2.1 AA compliance verified by audit. Screen reader testing in CI. Reduced motion and high contrast support built in.

Pillar 2: Documentation and discoverability

**4. Component documentation completeness** What to look for: Is there documentation beyond source code? Is there a documentation site? Does it include usage guidelines, do/don't examples, and API reference? Is there an interactive playground?

What mature systems look like: Documentation site with interactive playground, usage analytics, and searchable component inventory with metadata.

**5. Token documentation** What to look for: Are tokens documented beyond code? Are there visual previews? Is semantic intent described? Are there migration guides for token changes?

What mature systems look like: Token documentation with visual previews, intent descriptions, do/don't examples, and automated sync between code and docs.

**6. AI readiness** What to look for: Do components have structured metadata? Are descriptions consistent and machine-optimised? Is there a machine-readable manifest? Are composition rules explicit?

What mature systems look like: AI-optimised descriptions, machine-readable composition rules, validation schemas, and components that are self-describing.

Pillar 3: Governance and process

**7. Release process maturity** What to look for: Is there a formal release process? Is semantic versioning applied? Are changelogs consistent? Is there an automat