From design-system-ops
Audits design system component libraries for usage signals, complexity, duplication, and coverage gaps, producing tiered findings, inventory, and prioritized recommendations.
npx claudepluginhub murphytrueman/design-system-opsThis skill uses the workspace's default tool permissions.
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.
Assesses design system health across seven dimensions—tokens, components, documentation, adoption, governance, AI readiness, platform maturity—producing findings summary and prioritized actions.
Assesses design system maturity on 1-4 scale with metrics, evaluates adoption health and governance, analyzes component duplication, calculates custom vs system ratios, identifies barriers and debt trends.
Detects design systems in code, identifies token drifts with paired evidence blocks showing definitions vs conflicting usages. Use for auditing UI consistency.
Share bugs, ideas, or general feedback.
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.
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.
Before producing output, check for a .ds-ops-config.yml file in the project root. If present, load:
system.framework — pre-selects framework-specific inventory guidancesystem.component_count — pre-populates the small-system gateseverity.* — overrides for finding severity ratingsintegrations.* — enables auto-pull for component data (see below)recurring.* — enables comparison with previous auditIf integrations are configured in .ds-ops-config.yml, pull data automatically:
Figma MCP (integrations.figma.enabled: true):
integrations.figma.file_key via Figma MCPnpm registry (integrations.npm.enabled: true):
integrations.npm.package_name (or each package in integrations.npm.scoped_packages for monorepos) using npm view [package] --json or the npm registry APIStorybook (integrations.storybook.enabled: true):
integrations.storybook.url/index.jsonGitHub (integrations.github.enabled: true):
gh api search/code to count import references for each component across consuming repositoriesDocumentation platform (integrations.documentation.enabled: true):
zeroheight: use the Zeroheight API to pull page list and last-updated dates per componentsupernova: use the Supernova API to pull component documentation coveragestorybook: same as Storybook integration above (docs tab status)If an integration fails, log it and proceed with manual input.
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:
Include the classification in the report header as "Library type: [Design system / Component library / Pattern library / Utility collection]" and skip dimensions that don't apply.
Ask for or confirm (skip questions already answered by auto-pull):
.vue), Twig/Fractal (.twig), Svelte (.svelte), or Web ComponentsIf usage data is not available, the audit focuses on structural assessment rather than usage analysis. Note in the output which findings are based on direct analysis and which are inferred from structure.
Small-system note (fewer than 5 components): With 1–4 components, the audit shifts from pattern detection to per-component deep dive. Skip complexity distribution analysis (Step 3, Dimension 2) — it is not meaningful at this scale. Instead, focus on: completeness of each component's API and state coverage, documentation status per component, and whether the system covers the team's highest-frequency needs. The coverage gaps dimension (Step 3, Dimension 4) becomes the most valuable — what common patterns are teams building locally because the system does not yet provide them? The answer to that question is the system's roadmap.
Before proceeding to inventory and audit, establish which usage signals will ground the assessment in Dimension 1. Ask the user:
"Which usage signals will you track to assess component usage? Select all that apply:"
Document which signals are available for this audit. Usage assessment in Dimension 1 is only as strong as the signals used — if only one signal is available, note that the usage assessment is based on limited data and may be incomplete.
Monorepo handling:
Monorepo structures break standard usage signals. A component published as @system/button in its own package may show high npm downloads while @system/date-picker shows low — but the download count reflects bundling behaviour, not actual component usage by teams. Apply these adjustments:
-next or -v2 suffixes (e.g. button-next, DataTableV2) indicate in-flight migrations. Count both versions but flag the pair — the older version is a deprecation candidate, the newer is not yet fully adopted. Neither version's usage number is accurate in isolation._InternalBase, _LayoutHelper), components in directories named internal/, private/, or utils/, and components not re-exported from the package's public barrel file (index.ts) are internal implementation details. Exclude them from the public component count and from coverage gap analysis. Count them separately as "internal utilities."Box, Stack, Flex, Grid, VisuallyHidden, Portal) are infrastructure components, not user-facing UI. They should be counted in the inventory but categorised separately. A library with 30 components where 15 are layout utilities and 15 are UI components has a different health profile than one with 30 UI components.Framework-specific inventory notes:
.vue file in the components directory is typically one component. Check for <script setup> vs Options API — mixed patterns across the library are a consistency finding.01-atoms/, 02-molecules/, 03-organisms/). The Fractal config (fractal.config.js) defines the component engine and paths. Each .twig file with an associated .config.yml or .config.js is a component.Component.tsx + styles.ts). Count by exported component, not by file. Monorepo packages like @system/core may contain dozens of components in subdirectories.Create a working inventory of all components:
If the inventory does not yet exist, building it is Step 1 of the audit and may be the most valuable output in its own right.
Assess what usage data is available and what it suggests.
Direct signals (if available):
Indirect signals (structural inference):
For each component, assign a usage status: Actively used / Likely used / Unknown / Likely unused / Confirmed unused
Flag all "Likely unused" and "Confirmed unused" for the action list.
Assess the distribution of component complexity across the library.
Foundational components — primitives that serve as building blocks. Buttons, inputs, checkboxes, typography elements, icons. These should make up the largest portion of the library.
Compound components — compositions of foundational components. Cards, modals, dropdowns, navigation bars. These should be fewer than foundational components.
Feature components — components with significant built-in logic or high specificity to a particular product context. These are the category most likely to proliferate and least likely to be reusable.
Flag any library where:
Find components that solve the same problem with different implementations.
Look for:
Toast, Snackbar, and Alert all in the same system without clear distinctions)Modal and Dialog, Popover and Tooltip — flag these for disambiguation even if they are genuinely distinct, because the distinction needs to be explicit)For each duplication finding: describe what overlaps, note whether the components are genuinely distinct or redundant, and recommend either documenting the distinction or deprecating the redundant one.
For each potential duplication finding, use this worksheet to make the decision systematically:
For each pair of overlapping components (Component A and Component B):
Problem definition:
If the problems are the same:
If the problems are different:
Document this worksheet as part of the audit output. It makes deduplication decisions defensible and repeatable.
Identify common patterns that teams regularly need but the system does not provide.
Sources for gap identification:
For each gap: assess whether it is a genuine system gap (the need is common enough to belong in the system) or a local need (one team's requirement that is appropriately local).
Coverage gaps identified in this dimension often correspond to Classification E (system gap) findings in drift-detection. If running both skills in the same session:
This connection improves prioritisation — gaps with drift evidence indicate teams are already solving the problem locally, which raises the urgency of system provision.
Build a dependency graph of component composition relationships. This is the blast-radius view for component changes.
How to build the graph. Use whatever source is available, in order of reliability: (1) Component source code — look for import statements that reference other system components, JSX/template renders of system components, and component-tier token references in styled-components, CSS modules, or Tailwind classes. (2) Storybook story index — stories often reveal composition through subcomponents declarations and story decorators. (3) Figma component variants — layer structure shows composition visually. (4) Manual inventory — if none of the above are accessible, ask the team to list composition relationships. The skill should state which method was used, as it affects confidence.
For each component, identify:
Card composes Text, Button, Icon)Icon is composed in Button, Card, NavItem, Alert)Identify critical path components:
Token-to-component dependency:
Answering "if I change X, what breaks?" The graph should be queryable. For any component or token, the report should make it possible to trace: (1) direct consumers — components that import/compose this component, (2) indirect consumers — components that compose the direct consumers, and (3) product-level impact — if integration data is available, which products/teams are affected. Example: "Changing Icon directly affects 14 components (Button, Card, NavItem, Alert, ...). Indirectly affects 23 components through Button alone. Products affected: Checkout (12 Icon instances), Dashboard (34 instances), Mobile (8 instances)."
Include the composition graph as a section in the report. For systems with 20+ components, produce a summarised version (top 10 highest fan-in, all hub components, orphaned components) with the full graph available as a supplementary output.
Assess the library's readiness for AI consumption. This identifies what work is needed to make the system machine-readable.
Per-component checklist: For each component, check whether the following exist:
System-level indicators:
Produce a summary table showing which components have which checklist items. Flag components missing three or more items as priorities for AI-readiness work. Include specific recommendations for each missing area.
Based on the audit findings across all dimensions, assess the system's maturity level:
Ad-hoc: Components exist but are ungoverned. No consistent naming, no contribution process, inconsistent documentation. Managed: Library exists with some governance. Token architecture established. Documentation exists but varies in depth. Systematic: Consistent API contracts. Standard documentation format. Contribution and deprecation processes documented. Predictable release cadence. Measured: Adoption tracked quantitatively. Drift detected and classified. Health assessed across dimensions. Recurring reviews on a cadence. Optimised: Platform infrastructure. Versioned APIs with semver. Machine-readable manifests. Consumer contract testing. Calibrated quality bar.
Assess each dimension (usage, complexity, duplication, coverage, dependency graph, AI-readiness) against these maturity stages. The system's overall maturity is the lowest stage where it meets criteria across all dimensions — a system that is measured on usage but ad-hoc on documentation is effectively ad-hoc.
Include the maturity assessment in the report with: current stage, evidence for the assessment, and specific actions needed to reach the next stage.
Open with a headline sentence that tells the reader the overall state and where to focus.
Date: [date] Library size: [total component count] Audit method: [direct inspection / structural inference / combined]
One paragraph. What is the library's overall condition? What is the most significant finding across the four dimensions?
| Category | Count | Actively used | Unknown | Likely/confirmed unused |
|---|---|---|---|---|
| Navigation | ||||
| Forms | ||||
| Feedback | ||||
| Layout | ||||
| Data display | ||||
| Other | ||||
| Total |
Findings formatted as: ID, component or category, finding description, recommended action, priority.
Severity key: 🔴 Critical / 🟠 High / 🟡 Medium / ⚪ Low
Prioritised:
Immediate:
Planned:
Review:
End the report with:
A note on context: This audit sees your component library — it does not see the product decisions, team constraints, or historical context behind it. Some findings may flag patterns your team chose deliberately. If any finding describes an intentional decision, let me know — I'll exclude it from future runs and learn your system's conventions. The goal is to surface problems you haven't seen yet, not to second-guess choices you've already made.