roast-my-design-system

Your AI can write the UI. This makes sure it writes your UI.

A free CLI tool (and Claude Code skill) that roasts your repo's design system with real data, then generates the rules that keep your AI agent on-system.

New in 5.10: it reads Tailwind v3 shadcn, and every colour space. shadcn on Tailwind v3 stores colour tokens as bare HSL channels, for the opacity trick. So a textbook shadcn repo used to scan as "2 colours, none defined as CSS variables". It now reads those tokens. It finds the greys (an oklch palette used to report 0). And it spots twins across notations: a token written as hsl and a hardcoded copy written as rgb are the same colour, and now count as a near-identical pair. Checked before and after on 6 real shadcn repos.

New in 5.9: the agent card knows which doors your rules actually reach. The report now states, as plain fact, which tools can read the rules files you have. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor reads AGENTS.md and .cursor/rules. Where a door is missing, the card shows the one-line fix: Claude Code skips AGENTS.md, and a CLAUDE.md containing the single line @AGENTS.md closes the gap. The scan also finds rules files nested in subfolders, which is how monorepos really do it (twenty carries 35 AGENTS.md files; a root-only look reported 1). It recognises GEMINI.md, .windsurf/rules and .github/instructions too.

New in 5.8: every finding can explain itself. A "why this matters" toggle sits under each finding. It unfolds the calm story behind the brutal number. How the mess arrives innocently, what it costs later, how an agent multiplies it, and why the ideal sits where it sits, benchmark medians included. Written to a plain-language standard and reviewed word by word.

New in 5.0: it runs as a local MCP server. One command, and your agent asks the design system before writing UI, then gets the work checked after. Which Button is canonical? Which token holds that colour? Review my changes. Local, deterministic, nothing leaves your machine. See Live answers over MCP.

Run it on your codebase and get, in about a second:

• A health score you can defend in a meeting. 0 to 100, deterministic, and benchmarked against 3 yardsticks: Ideal Design System norms, 34 scanned public repos and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…).
• Per-package scores for monorepos. One blended number hides which package is the problem: packages/ui scores 80 while apps/web scores 40, and now you can see it.
• Reads React and web components alike. Stencil, Lit and custom elements are detected by tag registration and counted by kebab tag. Libraries get composition maps, not adoption accusations. Earned token namespaces are named in the header. Anything the scan can not read is declared "not measured" instead of scored.
• The receipts behind it. Every colour and its near-identical twin. Every spacing value, typeface, duplicated or never-imported component, inline style and !important. All with real file paths, in one self-contained HTML report you can open, Slack or email.
• The first fixes ranked by payoff, each with its prompt. A "Where to start" list derived from your own numbers. Every move carries a copy button with a ready-made fix prompt for your agent: the finding, the files, the expected payoff, and rules that respect deliberate craft. Fix, re-run the scan, press the next button.
• Rules that stop the mess coming back. A generated design-system-rules.md with canonical components, your token file, and known duplicates to avoid, so your AI agent follows your system instead of guessing at it. --apply injects them into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore. And the agent card states which tools can actually read the rules you have (Claude Code, Codex, Cursor), with the one-line fix where a door is missing.

Why this exists

Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in your repo. If your repo has 112 colours and 4 Button implementations, your agent guesses which one is canonical, and it picks wrong half the time. That's why AI-generated UI looks almost-but-not-quite right. The first step to fixing it is seeing the mess measured.

Every command

One scan powers all of it; the flags decide what lands on disk. Combine freely.

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 use cases