Roast My Design System — Greg Kozakiewicz

AI-generated UI is often almost right, but not quite. Sometimes the problem isn’t the AI. It’s the repo.

Roast looks at what’s actually in your codebase, finds where an agent might have to guess, and turns that into rules it can follow. Free, open source and local.

// The problem

AI can write the UI. But what does it learn from?

An AI coding agent does not start with a clean design system. It looks at the repo in front of it. If that repo contains 112 colours, 4 Button implementations and dozens of arbitrary spacing values, the agent has no reliable way to know which version to use.

The result is familiar: interfaces that look almost right, but gradually drift away from the product's actual design system. So instead of asking whether AI can generate good UI, I set out to measure what the repo teaches an AI agent, and where it leaves the agent to guess.

The top of a Roast My Design System report for dubinc/dub: design system health 20 out of 100, 1 gap found where the agent will have to guess (charts have no palette) and the first fixes that could raise the score — The score shows how well the repo follows the design system rules Roast checks. View a live report for dubinc/dub ↗

// Measure what the agent sees

The first principle was simple: measure the code, not the documentation. Roast scans the repo for the patterns an agent is likely to copy, and gives the same result every time: near-identical colours, off-scale spacing, duplicated components, inline styles, arbitrary values and stale agent rules. Every finding has a real file path.

"A script does the counting. Claude only explains."

The harder design problem was deciding what not to count. A chart can need its own colours. A component library can contain values that are not product code. So the score uses 3 yardsticks: what a good design system looks like, a benchmark of 112 public repos, and 10 established design systems such as Primer, Polaris and Carbon. A shadcn app is compared with other shadcn apps, and an MUI product with other MUI products. Anything that can't be measured reliably is reported as "not measured", not as zero.

The palette section of the dubinc/dub report: 127 colours against a healthy 24, 63 tokens and 64 strays, colour usage sized by count, and 12 nearly identical pairs such as #f5f5f5 and #f2f3f5 — Every finding points back to the code that produced it.

// From diagnosis to action

The output could have been a list of problems. Instead, I designed it around one question: what should you do next? The report starts with the places where an agent will have to guess. Then it gives 3 fixes, each with the score it could add and a prompt you can paste straight into your agent.

A repeated value might be a mistake, or it might be a decision that has never been given a name. The report helps tell the difference rather than encouraging blind cleanup.

Roast then turns the diagnosis into rules grounded in the repo itself (real tokens, the components to use, known duplicates) and adds them to the files agents read: CLAUDE.md, AGENTS.md and Cursor rules. It checks those files too, because a rule pointing at a file that no longer exists can be worse than no rule at all.

The Fixes you can make right now section: three fixes that could raise dubinc/dub from 20 to 50, each with its expected score gain and a Copy the fix prompt button — 3 fixes you can hand straight to your agent.

The canonical components section of the rules generated for dubinc/dub, listing Button, Modal, Tooltip and LoadingSpinner with their file paths, usage counts and most common usage — The generated rules name the components to use and show how the repo uses them.

// Put the design system inside the agent

The report was only the beginning. The MCP server gives the agent 5 tools to ask the repo about its design system while it works. It can check what to know before building, find the right component or token, check a change before saving and review the final diff.

The goal was to move the design system from something humans consult into something the agent can actively use.

01Context before buildingroast_get_context
02Find while buildingroast_find_componentroast_find_token
03Validate before savingroast_validate
04Review before finishingroast_review

A real MCP session against Unleash: the agent calls roast_get_context, roast_find_token and roast_validate twice, receiving repo-specific answers until no violations remain

A real session against Unleash, an MUI product. Every answer is the server's own text, unedited. See the live MCP example ↗

23 JulyProject created
1 Augustnpm CLI
15 AugustAgent rules and stale-rule detection
17 AugustMCP server
29 Augustguard-my-design-system
SeptemberProfiles, benchmark expansion, plugin, edit checks and a 259-session agent study

// I built it with Claude Code

I built Roast as designer, product owner and architect, with Claude Code as the implementation partner. I directed the product, experience, architecture, rules, benchmarks and tests, and used AI to move quickly through unfamiliar technical territory.

In just over 2 months it grew from a Claude Code skill into a CLI, rules generator, MCP server and plugin, all built on the same scanning engine. 388 commits so far.

// What happened

The project was released publicly from the beginning. As of 29 September 2026:

28K+npm downloads
129published versions
112benchmark repos
11hosted example reports

// Does it work?

I tested Roast on 10 open-source products across 259 agent sessions, with and without it.

Routine work stayed on-system either way. The problems came when the agent had to invent something new. Dub has no chart palette, and its charts already hardcode 17 colours. Asked for a new chart, the agent hardcoded 9 more.

Rules and MCP helped the stronger model. On a new theme, added findings fell from 28 to 2. The smaller model never used them. What worked for both was checking every edit, without waiting for the agent to ask. With that check on, new charts added no findings in 14 of 15 runs. For teams, guard-my-design-system does the same check on each pull request.

Nothing was rendered, so this is a floor, not a design review. But it showed me something useful: the mess an agent adds is a map of the gaps in your design system.