/system-health

name: system-health
description: "Run an overall health assessment across a design system, producing a findings-based summary across seven dimensions. This produces a holistic, cross-cutting health assessment, NOT a deep dive into a single dimension like components or tokens. Trigger when someone says: how healthy is my design system, overall system assessment, system health check, rate my system, design system audit, give me the big picture on my system, or anything asking for a holistic view of system quality rather than a focused audit of one area. Do NOT trigger for a deep component library audit — use component-audit for that."
references:
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/human-oversight-framework.md
  - ../../knowledge-notes/agent-orchestration-guide.md
  - ../../knowledge-notes/mcp-setup-guide.md
  - ../../knowledge-notes/output-discipline.md

System health

A skill for producing a holistic design system health assessment across seven dimensions: tokens, components, documentation, adoption, governance, AI readiness, and platform maturity. Output is a findings-based executive summary with a prioritised action list.

Context

Token audits find naming violations. Component audits find unused variants. Adoption analysis finds coverage gaps. But none of these in isolation tells you whether the system is healthy. Health is a function of how well all five dimensions are working together — a system with excellent tokens and terrible governance is still a fragile system, and a well-adopted system with thin documentation is one team member departure away from collapse.

This assessment is designed to give a snapshot of the whole system, not a deep dive into any single area. It is useful as a starting point for prioritisation, as a quarterly review artefact, or as background for a stakeholder conversation about where investment is needed.

For deeper work on any individual dimension, route to the relevant specialist skill (token-audit, component-audit, etc.).

---

Configuration

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `system.*` — pre-populates system size, framework, and theming context
• `severity.*` — calibrates finding severity thresholds
• `integrations.*` — enables auto-pull across all five dimensions (see below)
• `recurring.*` — enables trend tracking across periodic health assessments

Auto-pull integrations

System health benefits from every configured integration — it is the broadest assessment. Pull automatically where available:

**Figma MCP** (`integrations.figma.enabled: true`):

• Pull component count, variant count, and library analytics for the Components and Adoption dimensions
• Pull variable collections for the Tokens dimension

**npm registry** (`integrations.npm.enabled: true`):

• Pull download trends for the Adoption dimension — rising, flat, or declining downloads over the last 4 quarters
• For monorepos, pull per-package stats as directional signals

**GitHub** (`integrations.github.enabled: true`):

• Pull PR frequency and contributor count for the Governance dimension
• Pull issue count and staleness for the Documentation dimension
• Pull commit frequency on token and component files for the Tokens and Components dimensions

**Storybook / Documentation** (`integrations.storybook.enabled` or `integrations.documentation.enabled`):

• Pull documentation coverage percentage for the Documentation dimension
• Compare against component inventory to calculate docs-per-component ratio

These signals are supplementary — the dimension assessment still requires the structured checks in Step 2. But auto-pulled data replaces estimated figures with measured ones, which makes the findings more defensible.

Recurring workflow

If `recurring` is configured in `.ds-ops-config.yml`:

1. **Load the previous health report** from `recurring.output_directory`. 2. **Compare dimension statuses:** which dimensions improved, held steady, or regressed. 3. **Add a "Health trend" section** before the action list:

• Previous status, current status, and direction for each dimension
• One sentence: "System health is improving / stable / declining since [date]"
• Highlight any dimension that worsened — this is a regression

4. **Save output** and prune per `recurring.retain_count`.

Step 0: Identify what you're looking at

Before assessing health, determine what kind of shared UI this actually is. Not everything is a design system, and the distinction changes what advice is useful.

**Classify the library type from the codebase signals:**

• **Design system** — Tokens + components + documentation + governance. Multiple tiers of tokens, a component library with contribution guidelines, versioned releases, and a documentation site. This is the full template — all seven dimensions apply.
• **Component library** — A shared component package without the broader system infrastructure. Has components, may have tokens, but no formal governance, contribution process, or adoption tracking. Common in mid-size teams. Assess Tokens, Components, and Documentation. Governance and Adoption are stretch goals, not gaps — frame them as "when you're ready" not "you're missing this."
• **Pattern library** — Documented UI patterns, often in Fractal, Storybook, or a static site generator. May use Twig, Nunjucks, or vanilla HTML. Focus is on reference and consistency rather than consumption as a package. Assess Documentation and Components. Token architecture is often absent by design — do not flag it as a gap unless the team is trying to build one.
• **Utility collection** — A grab-bag of shared helpers, mixins, base styles, or layout primitives. Often a developer's first step toward shared UI. Assess what's there without projecting a design system roadmap onto it. The most useful output is "