Roast My Design System — Greg Kozakiewicz

I built Roast My Design System to answer a problem I kept seeing in AI-generated interfaces: the output is often almost right, but not quite.

The reason is often not the model. It is the repository.

Roast measures what is actually in the codebase, shows where the problems are, and turns the findings into rules an AI agent can use. It is free, open source and runs locally with no telemetry.

// 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 repository in front of it. If that repository contains 112 colours, four Button implementations and dozens of arbitrary spacing values, the agent has no reliable way to know which version is canonical.

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 how safe the repository was for an AI agent to build on.

The top of a Roast My Design System report for vercel/ai-chatbot: health score 80 out of 100, a one-line summary and three recommended fixes — The score measures how safely an AI agent can build on the repository without going off-system. View a live report for vercel/ai-chatbot ↗

// Measure what the agent sees

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

"Claude narrates; it never counts."

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 is grounded in three yardsticks: an Ideal Design System, a benchmark of public repositories and established design systems. Repo-kind profiles judge a shadcn app and an MUI product by different rulers, and anything that can't be measured reliably is reported as "not measured" rather than zero.

Report section listing 45 colours from outside the theme, with the files that carry them: weather.tsx 10 times, message.tsx 9 times and others — 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 a verdict, then reduces the work to three concrete moves, each with an expected score impact and a fix prompt the user can hand straight to their 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 repository itself (real tokens, canonical components, known duplicates) and injects them into the files agents actually 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 Where to start section: three recommended fixes, each with its expected score gain and a Copy the fix prompt button — Three concrete moves the user can hand to their agent.

The canonical components section of the generated rules, listing Button, Tooltip and others with their file paths and usage counts — The generated rules name the canonical components and show how the repository actually uses them.

// Put the design system inside the agent

The report was only the beginning. The MCP server lets an agent ask the repository about its design system while it is working: find the canonical component, find the right token, validate changes 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_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 ↗

July 23Project created
August 1npm CLI
August 15Agent rules and stale-rule detection
August 17MCP server
August 29guard-my-design-system
SeptemberProfiles, benchmark expansion, plugin and review workflow

// 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 under two months it grew from a Claude Code skill into a CLI, rules generator, MCP server and plugin, all built around the same scanning engine. 311 commits in two months.

// What happened

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