What is the design-system-audit skill?
The design-system-audit skill is a markdown file in the PM Skills library on GitHub. It makes an AI agent audit a component library and write a structured report: a health score across six dimensions, coverage gaps, token inconsistencies, accessibility issues and a prioritised remediation roadmap for design and engineering leads.
The design-system-audit skill is a single SKILL.md that tells an AI agent how to review a shared design system. The result is a structured document aimed at a design system team, design leadership or engineers evaluating a component library.
Instead of a loose opinion, the agent walks eight numbered sections, from component coverage to a prioritised remediation roadmap, and ends with a health score a team can track from one audit to the next.
What the agent asks before it starts
- The design system's name and which products it serves.
- Audit scope: components, tokens, documentation, contribution process, or all of them.
- Current tooling: Figma, Storybook, Zeroheight, custom, or a mix.
- Team size, number of products, known pain points and the governance model.
- The goal: improve adoption, prepare for a rebrand, onboard new teams or justify investment.
How the report is organised
- A health table scoring component coverage, token consistency, documentation, accessibility, adoption and contribution process from 1 to 5, plus an overall score.
- Sections for coverage, component quality, tokens, documentation, WCAG 2.2 accessibility, adoption and contribution process.
- A closing roadmap that labels each initiative P1, P2 or P3 with impact, effort and timeline.
Token checks with a command line helper
For the token and accessibility sections, the skill tells the agent to run npx --yes notugly tokens tokens.json on a W3C design tokens file or a Figma variables export. It names failing pairs by token, not as a general note.
The same command flags one colour defined under several token names, which the skill calls the usual sign a system grew by copy-paste. A watch command compares a live site against a baseline file to catch near duplicate colours.
Who the design-system-audit skill is for
Best for
- Design system leads preparing a rebrand or justifying headcount with a scored baseline.
- Engineering teams who inherited a shared library and need a ranked list of what to fix first.
- Anyone comparing Figma against code. The skill's checks cover both. For component level rules, see design-system.
Not for
- Starting a system from nothing. Building one in Figma is covered by figma-generate-library.
- Fixing the issues. The skill produces the audit and a roadmap, and the edits are a separate job.
- Scoring adoption from files alone. The anti-patterns say to interview teams, because tool metrics miss why people build custom components.
Use it with UiChemy
The audit is about your system, not your site. Once the Figma file reflects the fixes, use UiChemy Figma to WordPress to turn the finished screens into an editable WordPress page. Click Get Started on uichemy.com. For accessibility depth, see web-accessibility-skill.
How to install Design System Audit Skill: Score and Fix Your System
npx pm-claude-skills addRun the library installer
The README gives
npx pm-claude-skills addfor any tool, naming Cursor, Codex, Windsurf, Cline and Zed. The command installs the library, which includes this skill.Or add the Claude Code plugin
In Claude Code, run /plugin and search for pm-skills, which the README lists as the official Anthropic directory entry.
Or copy the folder manually
Clone with
git clone https://github.com/mohitagw15856/pm-claude-skills.git, then copy exports/openclaw/design-system-audit to the folder your agent loads skills from. The README says ChatGPT and Gemini users copy from the exports folder.Start an audit
Ask something like audit our design system for consistency and coverage, then answer the intake questions. Paste or attach your token file if you have one.
Check that it loaded
Ask the agent to audit a small component library. It should ask for scope, tooling and goal, then answer with the health table and the numbered sections ending in a roadmap.
Key features
- Seven-field intakeBefore auditing, the agent collects system name, scope, tooling, team makeup, pain points, governance model and the goal of the audit, so the report answers a real question.
- Six-dimension health scoreA table rates component coverage, token consistency, documentation, accessibility, adoption and contribution process from 1 to 5 with a red, amber or green marker, then adds an overall row.
- Coverage inventory by categoryNavigation, forms, feedback, data display, layout and buttons are compared against real production patterns, and the most used pattern missing from the system is listed first.
- Component quality matrixEach component is checked for complete states, responsiveness, accessibility, dark mode, documented props and whether code matches Figma. Legend marks show complete, partial or missing.
- Design token auditColour, typography, spacing, radius, shadow and motion tokens are checked for definition and consistent use. The agent also asks whether a semantic layer sits on top of primitive tokens.
- Documentation reviewUsage guidelines, do and don't examples, accessibility notes, code examples, changelogs and migration guides are each rated, and the most common complaint about the docs is captured.
- WCAG 2.2 accessibility passA table covers text and component contrast, keyboard navigation, focus visibility, screen reader support, touch target size and motion, then lists blockers to fix before the next release.
- Adoption and contribution auditAdoption is scored per product with the barriers ranked by severity. Contribution is checked for criteria, review process, release cadence, breaking change policy and versioning.
- Prioritised roadmapFixes are listed as P1, P2 and P3 with impact, effort and timeline. The anti-patterns require a named owner for each initiative, because unowned work tends to stall.
Frequently asked questions
What is the design-system-audit skill?
It is a markdown skill in the PM Skills library on GitHub. It instructs an AI agent to audit a design system and produce a structured report with a health score, coverage gaps, token inconsistencies, accessibility issues and a prioritised remediation roadmap.
How do I install the design-system-audit skill?
Run npx pm-claude-skills add, which the README documents for any tool, or search for pm-skills with /plugin in Claude Code. A manual route is to clone the repository and copy the exports/openclaw/design-system-audit folder into your agent's skills location.
What does the audit score?
The health table scores six dimensions from 1 to 5: component coverage, token consistency, documentation quality, accessibility compliance, adoption rate and contribution process. An overall score and a one paragraph summary of the top two issues and the biggest strength sit above the detailed sections.
Does it check both Figma and code?
Yes, by design. The anti-patterns warn against assessing only the Figma library, because drift between Figma and code is described as one of the most common and costly design system failures. The quality matrix has a column for whether code matches Figma.
What does the notugly command do?
The skill uses it for contrast and tokens. notugly fix returns the ratio, the APCA lightness contrast and the nearest passing colour. notugly tokens reads a tokens file and names failing pairs. The skill says it is deterministic, has zero dependencies and makes no model call.
Which AI agents can use the skill?
The repository README says the PM Skills library works with Claude, ChatGPT, Gemini, Cursor and Codex. The installer names Cursor, Codex, Windsurf, Cline and Zed. For ChatGPT and Gemini you copy the file text from the exports folder.
How is it different from the figma-component-audit skill?
The figma-component-audit skill focuses on a Figma library: naming, coverage gaps and variant completeness. This skill covers a whole system, including tokens, documentation, accessibility, adoption and contribution process. For another take on design systems, see kwp-design-system.
What license does the skill use?
The repository carries the MIT license, and the README states that PM Skills is MIT licensed. Check the repository for the current license file before you redistribute the skill folder inside a product or a client deliverable.