Roast My Design System

What Roast My Design System MCP server does

Roast My Design System MCP server examines the UI code in a repository and maps the conventions an AI coding agent is likely to copy. The scan identifies findings such as hardcoded colors, spacing values outside the project’s scale, duplicated components, and other measured patterns. It also reports places where the repository lacks a clear answer, such as a missing chart palette.

The result is an HTML report with file paths, measured findings, suggested changes, and a score from 0 to 100. Monorepos can receive separate scores for individual packages rather than one score that hides differences between applications.

How it works

The command reads repository files locally and counts findings using deterministic rules. The numeric results do not depend on an AI-generated explanation. Claude may add commentary to the report, but that text is labelled separately from the measurements.

The project has three related stages. First, the roast describes what exists and where the system has gaps. Next, it creates agent guidance containing canonical components, token locations, duplicates to avoid, spacing steps, typefaces, and project vocabulary. Finally, the edit guard checks changes against that guidance so an agent does not need to remember to request an audit.

Setup and configuration

Run the package from the root of a UI repository:

npx roast-my-design-system@latest

The command opens a report after scanning. The README states that it does not require an account, make network requests, use telemetry, or modify the repository during the scan.

Use --apply to write generated rules into the supported agent files for Claude, Cursor, GitHub Copilot, and Windsurf. The generated guidance is stored in design-system-rules.md. Each scan also checks existing rules for references that have become stale.

Tools and capabilities

Roast My Design System MCP server provides a local MCP layer that serves repository-specific design-system rules and answers to an agent. Its documented workflow includes:

• auditing the repository and producing an HTML report;
• exposing generated rules through MCP;
• finding hardcoded colors and near-identical values;
• detecting off-scale spacing and duplicated components;
• identifying measured gaps where the repository provides no established pattern;
• generating fix prompts for reported findings;
• checking edits with a guard and supporting pull-request gating.

Limitations and notes

The scan is a consistency and gap detector, not a complete visual design review. A zero-finding result means the repository met the tool’s rules; it is not proof that every interface is well designed. The README also reports that MCP use varied by model in its experiments, while the edit hook operated without requiring the model to call an MCP tool.

Roast My Design System MCP server is focused on repository evidence. Its score and findings depend on the files and conventions it can read, so missing or ambiguous system definitions can appear as gaps rather than inferred design decisions.