Your design system, measured.
Your AI can write the UI. This makes sure it writes your UI.
A free CLI tool on npm, and a Claude Code + Codex skill. A deterministic scanner reads your repo and returns:
- A health score you can defend in a meeting. 0-100, benchmarked against Ideal Design System norms, 34 public repos and 10 reputable design systems. Monorepos are scored package by package, so the disciplined UI library and the messy app stop hiding behind one blended number.
- The receipts behind it. Every colour and its near-identical twin, every spacing value, duplicated or never-imported component, inline style and !important, with real file paths. The values are rendered, not just counted: your type scale at real sizes, your radii as real corners. Findings an agent would copy and multiply are marked as agent traps.
- The first fixes ranked by payoff. A Where to start list derived from your own numbers, with what each move is worth and where the score lands if you do them all: three tweaks, 55 becomes 85.
- The analysis travels with the report. Run as the Claude Code skill, the shareable HTML carries What the numbers mean — Claude's read of your scan: which findings matter, which good numbers are accidents, what to fix first. Forwarded reports keep the interpretation, not just the score. Labelled as written by AI, never mixed into the measurement.
- Rules that stop the mess coming back. A generated design-system-rules.md with your canonical components and their most common real usage, quoted from your own code with a receipt. One flag injects it into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. And every scan checks the rules you already have for stale references, because a rule your agent obeys is worse than no rule when the repo has moved on.
- Live answers while the agent works. --mcp runs the scan as a local MCP server: your agent asks which Button is canonical, which token holds the colour it was about to hardcode, and gets its changed files reviewed before finishing. Five tools, one scan at startup, nothing leaves your machine.
Read only, no network, no telemetry, one shareable HTML report. Every release is provenance signed on npm and passes a 55-check snapshot suite before it ships.
/plugin install roast-my-design-system@roast-my-design-system
The full experience: the roast in chat and inside the report itself — npx gives you the numbers; the skill adds what they mean, in the same file you'll share. Then the fixes walked with you.
One command in any repo. No install, no Claude needed.
Your agent asks the design system before writing UI, and gets the work checked after. Local, read only, nothing leaves your machine. Any MCP client can register the same command; tested with Claude Code.
cp -r roast-my-design-system/skills/roast-my-design-system ~/.claude/skills/
Works everywhere, installs the same skill. Use ~/.codex/skills/ instead for OpenAI Codex.
Every command
One scan powers all of it; the flags decide what lands on disk. Combine freely. The full documentation, with every flag explained and the MCP tools in detail, lives at github.com/gregkozakiewicz/roast-my-design-system.
| Command | What you get |
|---|---|
npx roast-my-design-system@latest | The scan and design-system-roast.html, opened in your browser |
npx roast-my-design-system@latest <path> | Scan a different repo than the current directory |
... --apply | The generated agent rules injected into every agent file you have: CLAUDE.md, AGENTS.md, .cursorrules, .cursor/rules/, .windsurfrules and .github/copilot-instructions.md, inside a marked block. Re-running replaces only that block, never your own text |
... --rules | The same rules written to design-system-rules.md instead, for pasting by hand |
... --card | roast-card.svg: a shareable 1200x630 card with the score and worst findings. Pure SVG, embeds in a README |
... --sarif | design-system-roast.sarif for GitHub code scanning: upload it in CI and findings appear in the Security tab, annotated on files |
... --mcp | The scan as a local MCP server: five tools your agent calls while writing UI, from "is there a Button already?" to "review my changes". Nothing leaves your machine |
... --check | The working tree's changed files checked against the design system, in the terminal. Exits 1 on findings, so it slots into scripts |
... --by "Dwayne Hicks" | A requester credit in the report header, next to the scan date |
... --notes <file.md> | An agent-written analysis embedded in the report as "What the numbers mean": labelled as written by AI, kept apart from the measured numbers. The Claude Code skill writes and passes this automatically; the flag is here so any agent can |
... --section "Title" <file.md> | An agent-written chapter appended after the notes, same styling, same written-by-AI label, with sub-headings allowed. Repeatable, so analysis that outgrows the notes still lives inside the report instead of a hand-built page |
... --exclude lab/ | Leave a folder out of the scan, or list folders in a .roastignore file at the repo root. The report prints every exclusion in the header with its file count, so a scoped score always says it is scoped |
... --json | The scan summary as JSON on stdout, for scripts and pipelines |
... --theme light / --out <file> / --no-open | Light report, custom report path, don't open the browser |
/roast-my-design-system (in Claude Code) | The full experience: the roast in chat and embedded in the report as "What the numbers mean", the rules offer, and the fix loop with Claude on your own numbers |
One scan writes rules for every agent: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the agent rules you already have and flags stale references, no flag needed.
Example roasts
Real reports from public repos, hosted exactly as the skill generates them. Every number is deterministic; every path is real.
Your AI can write the UI. This makes sure it writes your UI.