Design System Health Check

When to Use

• Monthly or quarterly design system review
• Before presenting a status update to leadership
• After a major release to assess where you stand
• When joining a new team and evaluating the existing system

The Prompt

Run a design system health check. I'll describe the current state, and you rate each area on a 1-5 scale with specific recommendations.

Current state:
- **Tokens:** [describe: how many, what format, light/dark mode, where stored]
- **Components:** [describe: how many, what framework, Figma parity]
- **Documentation:** [describe: where hosted, completeness, last updated]
- **Adoption:** [describe: how many products/teams use it, % adoption]
- **Tooling:** [describe: build pipeline, linting, testing, CI/CD]
- **Governance:** [describe: contribution process, release cadence, team size]

Rate each area:

1. **Token Health** (1-5) — Are tokens well-structured, complete, and consistently used?
2. **Component Health** (1-5) — Are components well-built, accessible, and covering real needs?
3. **Documentation Health** (1-5) — Can someone find what they need and use it correctly?
4. **Adoption Health** (1-5) — Are teams actually using the system? What's the friction?
5. **Tooling Health** (1-5) — Is the DX smooth? Can you ship confidently?
6. **Governance Health** (1-5) — Is there a clear process for changes, contributions, and releases?

For each area:
- Score (1-5)
- What's working
- What's at risk
- One quick win (can fix this week)
- One strategic investment (takes 1-3 months)

End with an overall health score and a prioritized list of the top 3 actions.

Example Output

## Design System Health Check — March 2026

| Area           | Score | Status     |
|----------------|-------|------------|
| Tokens         | 4/5   | Healthy    |
| Components     | 3/5   | Needs work |
| Documentation  | 2/5   | At risk    |
| Adoption       | 3/5   | Growing    |
| Tooling        | 4/5   | Healthy    |
| Governance     | 2/5   | At risk    |

**Overall: 3.0 / 5 — Functional but fragile**

### Tokens (4/5)
- Working: Well-structured 3-tier system, light + dark modes
- At risk: No responsive token layer for mobile
- Quick win: Add missing disabled-state tokens (5 tokens, 1 hour)
- Strategic: Build responsive token modes for spacing and typography

### Components (3/5)
- Working: 24 components in React, good accessibility basics
- At risk: 8 components exist in Figma but not in code
- Quick win: Add missing loading states to Button and Input
- Strategic: Close the Figma-to-code gap by building the 8 missing components

### Documentation (2/5)
- Working: Storybook exists with basic stories
- At risk: No usage guidelines, no do's/don'ts, no token docs
- Quick win: Add descriptions to all Storybook stories (2-3 hours)
- Strategic: Launch a documentation site with guidelines and examples

### Top 3 Priorities
1. Launch a documentation site (biggest adoption blocker)
2. Define a governance/contribution model (prevents drift)
3. Close the Figma-to-code component gap (builds trust)