design-system-audit
# Design System Audit Skill This Claude Code skill conducts a comprehensive audit of design systems, assessing component coverage, design token consistency, documentation quality, accessibility compliance, and governance health. It generates a structured report with numerical health scores across six dimensions, identifies specific gaps and inconsistencies, flags accessibility issues, and delivers a prioritized remediation roadmap. Use this skill when stakeholders need to evaluate design system quality, prepare for rebranding, onboard new teams, justify investment, or improve adoption across products.
git clone --depth 1 https://github.com/mohitagw15856/pm-claude-skills /tmp/design-system-audit && cp -r /tmp/design-system-audit/plugins/pm-design/skills/design-system-audit ~/.claude/skills/design-system-auditSKILL.md
# 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
Conduct a structured ethical review of an AI or ML feature, model, or product. Use when preparing to deploy an AI system, assessing algorithmic risk, auditing a model for bias, or producing a responsible AI impact assessment. Produces a structured ethics review covering fairness, transparency, privacy, safety, accountability, and societal impact with a risk tier score, pre-deployment checklist, and prioritised mitigations.
Structure AI and ML product decisions with the rigour of any product decision. Use when building AI-powered features, evaluating LLM integrations, designing AI products, or assessing AI readiness. Produces a complete AI product canvas covering problem definition, model approach, data requirements, evaluation framework, UX design, responsible AI checklist, and launch monitoring plan.
Transform feature briefs into structured design briefs that give designers the context they need before opening Figma. Use when asked to write a design brief, create a design handoff, brief a designer on a new feature, or translate a PRD into design requirements. Produces a brief with user goal, emotional context, success criteria, constraints, edge cases, and out-of-scope boundaries.
Design statistically rigorous A/B tests and interpret experiment results. Use when asked to design an experiment, run an A/B test, calculate sample size, interpret test results, or assess whether an experiment was successful. Produces a complete experiment design with hypothesis, sample size, run time, success criteria, and risk flags — or a results interpretation with ship/iterate/kill recommendation.
Synthesises user signals from multiple research sources into a unified, weighted insight brief. Use when you have data from interviews, support tickets, NPS verbatims, app reviews, or sales calls and need to reconcile contradictions, surface the underlying need behind requests, or answer 'what are users really telling us'. Produces ranked insights with confidence ratings, source weighting rationale, divergent signal analysis by user segment, and a research gap identification section.
Structure a product data analysis, metric deep-dive, funnel analysis, or cohort study. Use when asked to analyse product metrics, investigate a drop in conversion, explain a data change to stakeholders, or find the root cause of a metric movement. Produces a structured analysis with question, root cause, confidence level, and recommended action.
Interpret product metrics against goals and surface actionable signals. Use when asked to analyse product health, review key metrics, investigate a performance issue, produce a health report, or assess product-market fit signals. Produces a structured health report with RAG status, trend analysis, root cause hypotheses, and prioritised actions.
Structure a retention analysis, churn investigation, or engagement deep-dive for any product team. Use when asked to analyse user retention, investigate churn, measure DAU/MAU, or build a retention improvement plan. Produces a retention snapshot with root cause hypotheses, aha-moment correlation, and prioritised interventions.