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?

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

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

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:

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:

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:

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 case — no guidance exists"]