design-system-audit

# Design System Audit Skill

This skill produces a structured audit of a design system — covering component coverage, token consistency, documentation quality, accessibility compliance, contribution processes, and adoption health. Output is ready for a design system team, design leadership, or an engineering team evaluating their shared component library.

## Required Inputs

Ask the user for these if not provided:
- **Design system name** and what product(s) it serves
- **Audit scope** — component library / design tokens / documentation / contribution process / all of the above
- **Current tooling** — Figma / Storybook / Zeroheight / custom / combination?
- **Team using it** — how many designers and engineers, how many products?
- **Known pain points** — what do teams complain about most?
- **Governance model** — centralised team / federated contributors / no dedicated team?
- **Goal of the audit** — improve adoption / prepare for a rebrand / onboard new teams / justify investment?

## Output Structure

---

# Design System Audit: [System Name]

**Products served:** [List of products / apps]
**Audit scope:** [Full / Components only / Tokens only / Documentation]
**Auditor:** [Name / Team]
**Date:** [Date]
**Stakeholders:** [Design lead, Eng lead, CPO, etc.]

---

## Overall Health Score

| Dimension | Score (1–5) | Status |
|---|---|---|
| Component coverage | [X/5] | 🟢/🟡/🔴 |
| Token consistency | [X/5] | 🟢/🟡/🔴 |
| Documentation quality | [X/5] | 🟢/🟡/🔴 |
| Accessibility compliance | [X/5] | 🟢/🟡/🔴 |
| Adoption rate | [X/5] | 🟢/🟡/🔴 |
| Contribution process | [X/5] | 🟢/🟡/🔴 |
| **Overall** | **[X/5]** | 🟢/🟡/🔴 |

**Summary:** [2–3 sentences. What is the overall state of the design system? What are the top 2 issues and what is the biggest strength?]

---

## 1. Component Coverage Audit

**How to assess:** Compare components in the design system against the actual UI patterns in the product. Every pattern that exists in production but not in the system is a coverage gap.

### Component Inventory

| Category | Components present | Coverage | Gap |
|---|---|---|---|
| **Navigation** | [Navbar, Sidebar, Breadcrumb, Tabs] | [80%] | [Missing: Mega menu, mobile drawer] |
| **Forms & Inputs** | [Text input, Dropdown, Checkbox, Radio, Toggle, Date picker] | [90%] | [Missing: Multi-select, Rich text editor] |
| **Feedback & Alerts** | [Toast, Banner, Modal, Tooltip] | [60%] | [Missing: Inline validation, Progress indicator, Skeleton loader] |
| **Data Display** | [Table, Card, Badge, Avatar] | [50%] | [Missing: Data grid, Stat card, Timeline, Gantt] |
| **Layout** | [Grid, Container, Divider, Spacer] | [70%] | [Missing: Responsive breakpoint utilities] |
| **Buttons & Actions** | [Button, Icon button, FAB, Link] | [100%] | [None] |

**Coverage score:** [X% of production UI patterns are covered by the design system]

**Most impactful gaps:**
1. [Most used pattern not in the system — causing most duplication]
2. [...]
3. [...]

---

## 2. Component Quality Audit

For each component, assess against these quality criteria:

| Component | States complete | Responsive | Accessibility | Dark mode | Props documented | Code matches Figma |
|---|---|---|---|---|---|---|
| Button | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Modal | ⚠️ Loading state missing | ✅ | ✅ | ❌ | ⚠️ Partial | ✅ |
| Table | ❌ Sorting state missing | ❌ No mobile layout | ⚠️ No aria-sort | ❌ | ❌ | ⚠️ Drift |
| [Component] | [...] | [...] | [...] | [...] | [...] | [...] |

**Legend:** ✅ Complete — ⚠️ Partial / inconsistent — ❌ Missing

**Components with critical quality issues (fix before anything else):**
- [Component name]: [Specific issue and why it's blocking]
- [...]

---

## 3. Design Token Audit

**Token coverage:**

| Token type | Defined | Used consistently | Issues |
|---|---|---|---|
| **Colour** | [X tokens defined] | [⚠️ — 12 hardcoded hex values found in Figma] | [Inconsistent use of primary-500 vs primary-600 for CTAs across products] |
| **Typography** | [X tokens defined] | [✅] | [None — all type styles use token scale] |
| **Spacing** | [X tokens defined] | [⚠️ — custom spacing used in X components] | [Engineers using arbitrary px values instead of spacing tokens in X components] |
| **Border radius** | [X tokens defined] | [❌ — not defined; each component has hardcoded values] | [Button, card, modal all use different radius values with no token] |
| **Shadow / elevation** | [X tokens defined] | [⚠️] | [3 different drop-shadow values in use; no elevation scale] |
| **Animation / motion** | [X tokens defined] | [❌ — not defined] | [Transition durations inconsistent across components] |

**Semantic token layer:** [Does the system have semantic tokens (e.g. `color.action.primary` on top of `color.blue.500`) or only primitive tokens?]

**Token drift:** [Are code tokens and Figma tokens in sync? Use a tool like Token Studio, Style Dictionary, or manual comparison.]

---

## 4. Documentation Quality Audit

**Assessment per component / pattern:**

| Document type | Quality | Issues |
|---|---|---|
| **Usage guidelines** | [⚠️ — X% of components have guidelines] | [Button and Form components documented; Navigation and Data Display mostly undocumented] |
| **Do / Don't examples** | [❌ — mostly absent] | [Engineers frequently misuse components because intent is unclear] |
| **Accessibility notes** | [⚠️ — present for some components] | [No consistent format; accessibility notes missing for interactive components] |
| **Code examples** | [✅ — all Storybook components have code examples] | [...] |
| **Changelog** | [❌ — no component-level changelog exists] | [Breaking changes are not communicated; causes unexpected UI regressions] |
| **Migration guides** | [❌ — absent] | [Teams don't know how to upgrade to new component versions] |

**Documentation score:** [X% of components have complete, usable documentation]

**Most common designer / engineer complaint about docs:** [e.g. "I can't find whether to use Modal or Drawer for this use