This source did not publish a separate summary. Review SKILL.md before using the skill.
SKILL.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
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?
Programmatic Helper
Contrast ratios cannot be eyeballed. The AA line sits at 4.5:1, and #777777
on white is 4.478 (fails) while #767676 is 4.54 (passes) — no amount of
looking at a screenshot separates those. Compute them:
npx --yes notugly fix "#8ab4f8" "#ffffff" # ratio, APCA, and the nearest passing colour
npx --yes notugly onepager <url> --out review.html # every pairing, printable
npx --yes notugly vision # which colours merge for colour-blind viewers
notugly fix returns the ratio, the APCA lightness contrast, and the closest
colour to the one already chosen that passes — same hue, same chroma. Paste
those numbers into the tables below rather than estimating them.
Deterministic, zero dependencies, and no model call — so it costs nothing to
run and gives the same answer every time.
For the token consistency and accessibility sections, point it at the token
file directly:
npx --yes notugly tokens tokens.json # W3C design tokens or a Figma variables export
That names the failing pairs semantically — color.text.danger on surface.default is 2.99:1 — needs 4.5 — which is a bug with an owner, rather
than a general note about contrast. It also flags one colour defined under
several token names, which is the usual sign a system grew by copy-paste.
For drift over time, npx notugly watch <url> baseline.json distinguishes "a
new colour" from "a colour 0.003 away from one that already existed, because
somebody could not find the token".
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]
Establish contribution process with SLA for reviews
Medium — enables growth
Low
Sprint 3
P3
Dark mode token support
Medium — product parity
High
Quarter 3
P3
Design-code token sync tooling (Token Studio / Style Dictionary)
Medium — reduces drift
Medium
Quarter 2–3
Quality Checks
Coverage gaps are identified by comparing the design system to actual production UI, not assumed
Accessibility issues cite specific WCAG criterion and affected components
Adoption barriers are backed by evidence (interviews, survey, usage data) — not assumed
Remediation roadmap has effort estimates and is sequenced by impact
Both Figma and code (Storybook/implementation) are assessed — not just Figma
Stakeholders from design, engineering, and product have reviewed the audit
Anti-Patterns
Do not assess only the Figma library without checking the code implementation — Figma-code drift is one of the most common and costly design system failures
Do not score adoption without interviewing teams — audit tool metrics miss the human reasons teams build custom components instead of using the system
Do not treat all component gaps equally — prioritise gaps based on how many production screens rely on custom implementations, not alphabetically
Do not recommend adding more components without first auditing documentation quality — an undocumented component is often worse than no component
Do not schedule remediation without a named owner per initiative — design system improvements without ownership consistently stall
Example Trigger Phrases
"Audit our design system for consistency and coverage"
"Review our component library and identify gaps"
"Assess the health of our shared design system"
"Run a design system audit before we do a rebrand"
"What's wrong with our design system and what should we fix first?"
