/system-health

name: system-health
description: "Holistic health check across tokens, components, docs, adoption, governance, AI readiness, platform maturity, with status labels and an inferred maturity stage. Triggers: how healthy is my system, health check, big picture, how do we compare with public systems. Not for one area (use its audit)."
allowed-tools: Read, Write, Grep, Glob, WebFetch, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*)
references:
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/ai-readiness.md
  - ../../knowledge-notes/design-to-code-contract.md
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/adoption-measurement.md
  - ../../knowledge-notes/documentation-coverage.md
  - ../../knowledge-notes/public-systems-reference.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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

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 seven 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

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `system.*` — system size, framework, and theming context
• `severity.*` — finding severity overrides
• `integrations.*` — measured signals across all seven dimensions (see below)
• `recurring.*` — the Health trend section (see below)

Auto-pull integrations

System health is the broadest assessment, so every configured integration feeds at least one dimension:

**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

Follows the recurring-run procedure in the configuration-and-recurring note. Specific to this skill:

• **Compare dimension statuses:** which dimensions improved, held steady, or regressed.
• **Add a "Health trend" section** before the action list, with previous status, current status and direction for each dimension. Highlight any dimension that worsened — this is a regression.

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 o