What is Roast My Design System?
Roast My Design System is an MCP server bundled in the roast-my-design-system npm package. Run it once for a 0 to 100 health score and a ranked list of missing or inconsistent rules, or run it with --mcp so an agent gets live component and token answers while editing, plus a check before a file is saved.
Roast My Design System is an npm package that scans a front-end repo for design system gaps, then exposes the same knowledge to an agent through an MCP server. A plain run with no flags writes a report; adding --mcp starts the server instead.
The report ranks fixes by impact and compares the repo against a set of real-world benchmarks, so a team sees not just what is missing but how far off a healthy baseline it is.
What changes once it is running
- Before writing a new component, an agent can call a tool for existing canonical components and their usage examples instead of inventing a duplicate.
- Hardcoded colors, spacing and other raw values get mapped back to the project's own design tokens rather than left as magic numbers.
- A validate tool checks a file before it saves, and a review tool checks only the files changed in the current git diff.
- Rules the scan found get written out to a design-system-rules.md file that any agent file can point to.
Framework and library coverage
The scan reads React, Next.js, Vue, Angular, Svelte and plain web components, and recognizes design systems built on Tailwind, shadcn/ui, MUI, Mantine, Chakra UI and Ant Design. It runs read-only and reports no telemetry calls.
Who it is for
Best for
- Teams whose agents keep inventing one-off components or colors instead of reusing what the design system already has.
- A CI step that fails a pull request when changed files break design system rules, using the SARIF output for code scanning.
- Anyone who wants a single health score to track as a codebase grows.
Not for
- If what you need is a one-time written audit score for a design system, Design System Audit Skill covers that score and fix report directly.
- When the task is a written design critique of one screenshot instead of live repo rules, Impeccable Critique gives that scored review.
- When the gap is accessibility fixes rather than design token drift, Fixing Accessibility Skill handles that audit and the small edits after it.
- When you want line-level linter output scored across weighted dimensions for one file, UI UX Suite MCP gives that design linter detail.
Use it with UiChemy
The server keeps front-end code consistent with an existing design system as an agent writes it. For turning that same page into an editable WordPress build, UiChemy Composer and AI to WordPress cover the other half. Click Get Started on uichemy.com.
Connect Roast My Design System MCP: Scan, Score and Guard a Codebase to your AI client
npx roast-my-design-system@latest --mcpRun a first scan
In the project root, run
npx roast-my-design-system@latestwith no flags. It writes an HTML report with the health score and ranked fixes, read-only, in about a second on a typical repo.Start the MCP server
Run the same package with
--mcpadded, or add the config block above to your client's MCP settings file so it starts the server for you.Point an agent file at the rules
Run with
--applyonce to write design-system-rules.md, then reference that file from your agent's own instructions so it loads the rules every session.Add a CI check
Run with
--checkagainst only the files a pull request changed, or--sarifto feed the result into GitHub code scanning.
Client configuration
{
"mcpServers": {
"roast": {
"command": "npx",
"args": ["roast-my-design-system", "--mcp"]
}
}
}Endpoints and ports
npx roast-my-design-system@latestWrites the HTML report and score, no flags needed.npx roast-my-design-system@latest --mcpStarts the local server over stdio for live answers.npx roast-my-design-system@latest --checkValidates only files touched in the current change.What you can do with it
- Zero-dependency scanThe scanner ships with no runtime dependencies and makes no network calls, so a run stays local and fast, about a second on a typical repo.
- 0 to 100 health scoreEvery scan ends with a single score, weighed against a benchmark set the maintainer built from real-world repos, so a team can track drift over time.
- Five live MCP toolsOnce the server is running, an agent can pull context, find a component, resolve a token, validate a file or review a diff without leaving the editor.
- Rule file generationThe --apply flag writes a design-system-rules.md file an agent's own instructions can point to, so the rules persist between sessions.
- Multi-framework supportScans read React, Next.js, Vue, Angular, Svelte and web components, and recognize systems built on Tailwind, shadcn/ui, MUI, Mantine, Chakra UI and Ant Design.
- CI-ready outputThe --check flag limits validation to changed files, and --sarif formats the result for GitHub code scanning.
- Shareable summary cardThe --card flag renders a small SVG card with the score, useful for a README badge or a pull request comment.
Tools it exposes
roast_get_context
Returns the design system knowledge for a folder before an agent starts editing it.
roast_find_component
Looks up a canonical component by name or purpose and returns a usage example.
roast_find_token
Maps a hardcoded color, spacing or other raw value to the matching design token.
roast_validate
Checks a file against the project's rules before it is saved.
roast_review
Reviews only the files changed in the current git diff against the rules.
Frequently asked questions
What is Roast My Design System?
It is an npm package that scans a front-end repo for missing or inconsistent design system rules, scores the result 0 to 100 against real-world benchmarks, and can run an MCP server so an agent gets the same rules as live answers while it edits.
How do I run the Roast My Design System MCP server?
Install nothing up front; run npx roast-my-design-system@latest --mcp, or add a server entry to your client's MCP config with command npx and args roast-my-design-system and --mcp. The server starts over stdio and answers from the local scan.
Which frameworks does Roast My Design System support?
The scanner reads React, Next.js, Vue, Angular, Svelte and plain web components, and recognizes design systems built on Tailwind, shadcn/ui, MUI, Mantine, Chakra UI and Ant Design, so most front-end stacks are covered without extra setup.
What does the 0 to 100 score measure?
It compares the repo's design token usage, component reuse and consistency against a benchmark the maintainer built from scanning real-world repositories. A higher score means fewer hardcoded values and less duplicate or inconsistent UI.
Does it change my code automatically?
No. The scan and the MCP tools are read-only. The one write operation is --apply, which only creates or updates the design-system-rules.md rule file; it does not touch component or page code.
Can I run it in continuous integration?
Yes. The --check flag validates only the files a pull request changed, and --sarif outputs the result in the format GitHub code scanning expects, so a failing check can block a merge.
Does the MCP server work with agents besides Claude?
Yes. The README gives setup for Claude Code through a plugin marketplace command, Cursor through .cursor/mcp.json, and Windsurf through its own mcp_config.json file, all pointing at the same npx roast-my-design-system --mcp command.


