/component-audit

name: component-audit
description: "Deep audit of a component library: inventory, usage, duplication, complexity, coverage gaps. Triggers: audit my components, unused components, what components do I have, assess my library. Not for a whole-system view (system-health) or AI index files (codebase-index)."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*), Bash(sort:*), Bash(tail:*), Bash(wc:*), Bash(npm view:*)
references:
  - ../../knowledge-notes/component-governance.md
  - ../../knowledge-notes/component-bestiary-reference.md
  - ../../knowledge-notes/output-discipline.md

Component audit

A skill for auditing a design system's component library across four dimensions: usage signals, complexity distribution, duplication, and coverage gaps. Produces an inventory with tiered findings and 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

Component libraries accumulate silently. New components arrive through contributions. Old components persist because nobody wants to be the one who removes them. Variants proliferate because each edge case adds one more. The result is a library that grows in mass without growing proportionally in value.

A component audit brings the library back into focus: what is there, what is used, what duplicates what, and what is missing that teams have been building around. It is the maintenance work that makes the next year of development faster.

---

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.framework` — pre-selects framework-specific inventory guidance
• `system.component_count` — pre-populates the small-system gate
• `severity.*` — finding severity overrides
• `integrations.*` — component data sources (see below)
• `recurring.*` — comparison with the previous audit

Auto-pull integrations

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

• Read the published library from `integrations.figma.file_key` via Figma MCP
• Extract the component inventory: names, variant counts, description status
• Figma library analytics (detach and insertion counts per component) are available only through the REST Library Analytics API on an Enterprise plan. If the team has it, pull detach rates; if not, say so and don't list detach rates as a signal
• Cross-reference the Figma inventory against the code inventory to detect components that exist in design but not in code (or vice versa)

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

• Pull download statistics for `integrations.npm.package_name` (or each package in `integrations.npm.scoped_packages` for monorepos) using `npm view [package] --json` or the npm registry API
• Use download trends (last 30 days, last 90 days) as a usage signal in Dimension 1
• For monorepos: note that per-package downloads are unreliable (see monorepo handling) — use as a directional signal only

**Storybook** (`integrations.storybook.enabled: true`):

• Fetch the story index from `integrations.storybook.url/index.json`
• Extract component list, story counts per component, and documentation status
• Components with zero stories are likely undocumented — flag in Dimension 1

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

• Use `gh api search/code` to find consuming repositories that import each component, then read or clone those repos to count (see the note's GitHub caution)
• Pull PR activity for the component library — no PRs in 12+ months is a maintenance signal, not evidence the component is unused
• Pull open issues tagged with component names to surface known problems

**Documentation platform** (`integrations.documentation.enabled: true`):

• If platform is `zeroheight`: use the Zeroheight API to pull page list and last-updated dates per component
• If platform is `supernova`: use the Supernova API to pull component documentation coverage
• If platform is `storybook`: same as Storybook integration above (docs tab status)
• Map documentation coverage to the component inventory — components without docs pages are flagged in Dimension 3

Step 0: Identify what you're looking at

Before auditing components, determine what kind of shared UI this is. The library type changes which dimensions matter and how findings should be framed.

**Classify from codebase signals:**

• **Design system** — Full template applies. All four audit dimensions (usage, complexity, duplication, coverage) plus composition graph and AI readiness.
• **Component library** — Focus on complexity distribution, duplication, and coverage gaps. Usage signals may not exist yet — note this rather than flagging it as a problem. Skip AI readiness unless the team has signalled interest.
• **Pattern library** — Focus on duplication and documentation completeness per pattern. Complexity distribution is less meaningful because patterns are reference implementations, not consumed packages. Coverage gaps should be framed as "patterns your team builds frequently but hasn't documented" rather than "components missing from the system."
• **Utility collection** — Focus on duplication and naming consistency. A utility collection with overlapping helpers is actively harmful; one with clear, non-overlapping utilities is doing its job. Skip coverage gaps — a utility collection