Use this when you need to evaluate the health of an existing design system -- whether tokens cover what the product actually uses, whether components are specced and consistent, whether documentation exists and stays current. Produces a scored health report with prioritized gaps and a remediation roadmap.

Related skills: Pair with /style-guide for token foundations. Use /component-spec to spec components flagged as missing or incomplete. Reference /interaction-pattern-library for pattern consistency. Feed accessibility findings into /accessibility-audit for deeper evaluation.

Process

Step 1: Gather inputs

Ask the user to provide:

1. Design system location -- Storybook URL, Figma library, documentation site, or code repo
2. Component inventory -- list of components the system claims to offer (or where to find it)
3. Token system -- does it exist? Where are tokens defined (Figma, CSS variables, JSON, Style Dictionary)?
4. Product screens -- representative screenshots or flows showing how the system is actually used
5. Known pain points -- what does the team already know is broken, missing, or drifting?
6. Team context -- who maintains the system? How many products consume it?

If the user doesn't have a component inventory, note this as a finding -- a design system without a published inventory is already in trouble.

Step 2: Token coverage audit

Evaluate whether the token system covers foundational design decisions:

## Token Coverage

| Token category | Defined? | Count | Coverage assessment |
|---------------|----------|-------|---------------------|
| Color -- brand | Yes / No | (n) | (Are all brand colors tokenized? Any hardcoded hex in product?) |
| Color -- semantic | Yes / No | (n) | (Success, warning, error, info mapped? Dark mode variants?) |
| Color -- surface/background | Yes / No | (n) | (Elevation levels, card backgrounds, overlays) |
| Typography -- scale | Yes / No | (n) | (Heading levels, body, caption, overline) |
| Typography -- weight | Yes / No | (n) | (Regular, medium, semibold, bold at minimum) |
| Spacing | Yes / No | (n) | (Consistent scale? 4px/8px base? Covers padding + margin) |
| Border radius | Yes / No | (n) | (Consistent values? Component-specific overrides?) |
| Elevation/shadow | Yes / No | (n) | (Layering system? Consistent depth levels?) |
| Motion/duration | Yes / No | (n) | (Transition speeds, easing curves, prefers-reduced-motion?) |
| Breakpoints | Yes / No | (n) | (Responsive breakpoints defined as tokens?) |
| Z-index | Yes / No | (n) | (Managed scale or ad-hoc values?) |

### Token health indicators
- **Hardcoded values in product:** (High / Medium / Low -- are products using tokens or bypassing them?)
- **Naming convention:** (Consistent / Inconsistent / None)
- **Theming support:** (Yes / Partial / No -- can tokens swap for dark mode, white-label, etc.?)

Step 3: Component completeness audit

Compare what the design system offers against what the product actually needs:

## Component Completeness

### Inventory vs. usage

| Component | In system? | In product? | Specced? | Status |
|-----------|-----------|-------------|----------|--------|
| Button | Yes / No | Yes / No | Full / Partial / None | (Complete / Gap / Orphaned) |
| Input | Yes / No | Yes / No | Full / Partial / None | ... |
| (repeat for all components) |

### Status definitions
- **Complete** -- in system, used in product, fully specced
- **Gap** -- used in product but missing from system (or in system but not specced)
- **Orphaned** -- in system but not used in any product
- **Drift** -- exists in both but product version has diverged from system version

### Coverage summary
- Components in system: (n)
- Components used in product: (n)
- Gaps (in product, not in system): (n) -- 
- Orphaned (in system, not in product): (n)
- Drift (diverged): (n)

Step 4: Consistency check

Evaluate whether the system is internally consistent:

## Consistency Assessment

| Dimension | Rating | Findings |
|-----------|--------|----------|
| Naming conventions | Consistent / Mixed / No pattern | (e.g., "Button" vs "Btn" vs "ActionButton") |
| Variant patterns | Consistent / Mixed | (Do all components use the same variant naming? size=sm/md/lg?) |
| State coverage | Complete / Gaps | (Do all interactive components define hover, focus, active, disabled?) |
| Prop/API patterns | Consistent / Mixed | (Similar components use similar APIs? onChange vs onUpdate?) |
| Spacing application | Consistent / Ad-hoc | (Components use token spacing or hardcode values?) |
| Responsive behavior | Defined / Undefined | (Components have responsive rules or left to consumers?) |
| Error patterns | Consistent / Varies | (Error states follow a single pattern or each component differs?) |
| Empty states | Defined / Missing | (Components that display data have empty state designs?) |

Step 5: Accessibility compliance

Evaluate the system's accessibility posture at the system level -- not individual page compliance, but whether the system makes it easy or hard to build accessible products:

## Accessibility at the System Level

| Criterion | Status | Finding |
|-----------|--------|---------|
| Color contrast tokens meet 4.5:1 (text) and 3:1 (UI) | Pass / Fail | (details) |
| Focus styles defined in the system (not left to consumers) | Yes / No | (details) |
| Keyboard interaction patterns documented per component | Yes / No / Partial | (details) |
| ARIA patterns included in component specs | Yes / No / Partial | (details) |
| Touch target sizes meet 24px minimum (44px recommended) | Yes / No | (details) |
| Motion respects prefers-reduced-motion | Yes / No / Not applicable | (details) |
| Screen reader announcements documented for dynamic components | Yes / No | (details) |
| High-contrast/forced-colors compatibility | Tested / Untested | (details) |

Step 6: Documentation quality

Evaluate whether the system is actually usable by the people who need to build with it:

## Documentation Assessment

| Dimension | Status | Notes |
|-----------|--------|-------|
| Component specs exist for all components | All / Most / Few / None | (percentage) |
| Usage guidelines (when to use, when not to) | Yes / Partial / No | (details) |
| Code examples (copy-paste ready) | Yes / Partial / No | (details) |
| Visual examples (rendered states, variants) | Yes / Partial / No | (details) |
| Do/Don't guidance | Yes / Partial / No | (details) |
| Figma-to-code parity documented | Yes / No | (details) |
| Contribution guidelines (how to add/modify) | Yes / No | (details) |
| Migration guides (for breaking changes) | Yes / No / Not applicable | (details) |
| Changelog maintained | Yes / No | (details) |
| Search/discovery (can people find what they need?) | Good / Poor | (details) |

Step 7: Health scorecard and recommendations

## Design System Health Scorecard

| Dimension | Score (1-5) | Summary |
|-----------|-------------|---------|
| Token coverage | (n) | (one-line summary) |
| Component completeness | (n) | (one-line summary) |
| Internal consistency | (n) | (one-line summary) |
| Accessibility posture | (n) | (one-line summary) |
| Documentation quality | (n) | (one-line summary) |
| **Overall health** | **(avg)** | **(one-line overall)** |

### Score definitions
- **5** -- Mature. Comprehensive coverage, consistent patterns, well-documented.
- **4** -- Strong. Minor gaps, mostly consistent, documentation covers the important parts.
- **3** -- Developing. Notable gaps, some inconsistencies, documentation is spotty.
- **2** -- Fragile. Significant gaps, inconsistent patterns, documentation is sparse or outdated.
- **1** -- Nascent. Major foundational work needed.

### Priority recommendations

| Priority | Recommendation | Dimension | Effort | Impact |
|----------|---------------|-----------|--------|--------|
| P0 | (Fix immediately -- blocking teams or causing defects) | (which) | S/M/L | High |
| P1 | (Fix this cycle -- significant friction or drift) | (which) | S/M/L | High/Medium |
| P2 | (Plan for next cycle -- improvement, not urgent) | (which) | S/M/L | Medium |

### Quick wins
- (Improvement that's small effort, visible impact)

### Systemic issues
- (Patterns that need structural changes, not patches)

### What's working well
- (Strengths to protect and build on)

Step 8: Review

Ask the user:

• Do the scores match your gut sense of system health?
• Are any priority recommendations wrong (too high, too low, missing)?
• What's the team's capacity for design system investment right now?
• Is there a specific dimension you want to dig deeper on?

Adjust scores and recommendations based on their input.

Output location

Present the audit as formatted text in the conversation. The health scorecard and recommendations can be exported for team review or backlog planning.