roast-my-design-system：实践指南

工作中遇到相关需求时，roast-my-design-system值得先读说明，因为它主要用于AI设计系统扫描器+mcp服务器，对存储库评分 0-100，编写修复提示， 20K+ npm 下载。对部署与运行环境任务来说，权限、依赖和环境差异会放大维护成本往往决定它能否落地，不能只用安装成功来判断。我的评估方法是在非生产环境复现一次安装与运行，然后检查依赖锁定、权限边界、日志、回滚和资源消耗是否与文档一致。我的判断是，它更适合愿意维护环境并重视故障恢复的工程团队；若眼下没有这类需求，先保留观察即可。

烘焙我的设计系统

查找您的 AI 代理将在哪里发明 UI。

您的AI可以写入UI。这可确保它写入您的UI。

npx roast-my-design-system@latest

在 UI 存储库的根目录下运行它。一秒钟后，将打开一份报告。 没有帐户。没有网络。没有遥测。您的存储库中没有任何变化。

当前版本：9.1。 CHANGELOG.md 中的版本历史记录。

这个想法

特工复制其发现的内容。

它发明了仓库没有答案的地方。

我们在 10 个真实的开源产品、259 个代理会话（使用或不使用此工具）上进行了测试。

添加的每个会话的结果，按此工具自己的规则进行计数：

无论哪种方式，日常工作都会保留在系统上。发明发生了漂移。

Sonnet 在大约三分之一的会话中调用了 MCP 工具。 Haiku 从未这样做过，因此对于 Haiku 而言，MCP 本身没有任何改变。编辑挂钩在没有询问的情况下运行，并且该列变为零。

代理是哪里发明的？回购协议没有什么可复制的。 Dub 没有图表调色板。它自己的图表硬编码了 17 种颜色。当要求提供图表时，俳句又硬编码了 9 个。

因此，代理添加的混乱是系统中漏洞的地图。

该工具绘制地图。

烤。教。警卫。

烘烤仓库以找到其真正的设计系统、其中的混乱和差距。

通过生成的规则和本地 MCP 服务器来训练代理。

守护每次编辑，因此代理不必记得询问。

ROAST   what is in the repo, and what is missing
  ↓
TEACH   rules in the agent files, answers over MCP
  ↓
GUARD   every edit checked, the PR gated

你得到什么

你的代理人必须猜测哪里？

报告的可以先：回购协议尚未给出答案或“未发现差距”的地方。

• 间隙，在一条线上
• 证明这一点的文件
• 关闭它的一举一动

今天，有一个漏洞是众所周知的，因为运行发现了它：在没有图表调色板的存储库中对颜色进行图表硬编码。 126 个公共存储库中有 43 个看起来像这样。测量完成后，间隙就会加入列表。

修复代理猜测的问题

代理将复制的混乱情况，按照修复的价值进行排名。

• 发现了什么
• 其中，带有文件路径
• 为什么这很重要
• 要改变什么
• 复制按钮，其中包含针对您的代理的修复提示

修复，重新扫描，按下一步按钮。

您可以在会议中捍卫的分数

0 到 100。每次运行相同的数字。

根据三个标准进行衡量：设计系统的理想规范、以 112 个存储库基准为核心的 34 个产品存储库的中位数，以及 10 个信誉良好的系统（Primer、Polaris、Carbon、shadcn/ui 等）。

Monorepos 对每个包进行评分。 packages/ui 在 80 处停止隐藏 apps/web 在 40 处。

每个发现及其文件路径

• 每种硬编码颜色及其几乎相同的双胞胎
• 每个超出范围的间距值
• 每个重复的组件

还有8种，都在测量的是什么。一个 HTML 文件。打开它，放松它，通过电子邮件发送它。

您的代理人的规则

从您的存储库生成到 design-system-rules.md：

canonical components
the token file
known duplicates to avoid
spacing steps
typefaces
the kit's own vocabulary

--apply 将它们写入您拥有的每个代理文件中：Claude、Cursor、GitHub Copilot、Windsurf。每次扫描还会检查您已有的规则是否存在过时的引用。

脚本进行计数

每个数字都来自对文件的确定性读取。克劳德写下了解释，标记为 AI 所写，并与数字分开。

跑步是如何完成的

Claude Code，无头，关于 10 个公共产品，每个产品固定一个提交：cal.com、Dub、Metabase、Plausible、SigNoz、trigger.dev 以及另外四个。 259 个会话，Sonnet 5 和 Haiku 4.5，2026 年 9 月。每个更改的文件都会在会话结束时和固定提交时根据此工具的规则进行判断；仅当会话添加了结果时，该结果才算数。

什么都没有渲染。零发现意味着按照这些规则进行系统：地板，而不是设计审查。方法、表格和限制在研究文章中，将单独发布。

实例

十一份报告，完全按照工具编写的方式托管。每个数字都是确定的，每条路径都是真实的。

• npx shadcn create，全新（工厂安装，所有 61 个组件）：读取为全新安装，“分数是套件的，不是你的”； 13种颜色，每个主题变量就位，shadcn自己的24个括号值已命名且未计算在内。没有分数。
• 释放 (MUI)：1,109 个文件导入套件，主题被读取 6,166 次；每 100 个套件文件有 4 种颜色和 2 种间距写入到组件上。得分 60。
• 元数据库 (Mantine)：它自己的 Mantine 包装器算作套件，因此读取了 2,679 个文件，而不是 392 个；组件上未写入任何内容，每 100 个套件文件有 2 个间距。得分 47。
• SigNoz（Ant Design）：在存在令牌的样式对象中编写的每 100 个套件文件有 2 种颜色和 7 种间距。得分 51。
• Apache Airflow (Chakra UI)：组件上未写入任何颜色，每 100 个套件文件有 4 个间距作为存在空格步长的像素字符串。得分 43。
• vercel/ai-chatbot（shadcn 安装）：在 Tailwind 比例之外写入 74 个值，例如 [13px]，并且每 100 个存在主题变量的文件有 66 个调色板颜色；嵌入克劳德的笔记。得分 80。
• excalidraw/excalidraw：78 个超出范围的间距值和 90 个！重要声明。得分 55。
• dubinc/dub：622 个任意括号值、22 个重复组件以及指定的图表调色板间隙。得分 20。
• telekom/scale（Stencil）：通过标签读取 95 个 Stencil 组件；刻度外有 66 个间距值，大约 12 个就可以了；嵌入克劳德的笔记。得分 55。
• magicuidesign/magicui（注册表）：根据其发布的组件进行计算，其附带的代码中每 100 个文件有 52 种偏离主题的颜色，其文档站点保留并命名。得分78。
• adobe/spectrum-web-components（亮起）：硬编码颜色位于 744 个颜色标记和 37 个！重要声明旁边。得分 66。

vercel/ai-chatbot 的完整报告。判决回答了智能体将在这里学到的内容，间隙部分首先出现，然后是“回购协议教智能体什么”，克劳德读到的扫描：

轻型模式下的相同报告（一个文件，内置切换）：

为什么这些数字成立

• 确定性。 零依赖节点脚本读取每个文件并每次运行返回相同的数字。在普通仓库上大约需要一秒钟。
• 只读。没有网络。无遥测。 如果 package.json 声明了依赖项，则测试套件将失败。
• 诚实的差距。 扫描无法读取的内容表示“未测量”并从分数中删除。
• 诚实的排除。 测试、故事、文档网站、艺术品和电子邮件模板都被排除在外。您自己的排除项将打印在报告标题中以及文件计数中。
• 真正的基准。 112 个公共 React 存储库。 34 艘核心船队设定了中线；其余的提供套件配置文件，因此 shadcn 存储库与 shadcn 存储库进行比较。建造者位于tools/benchmark/。
• 可导入评分。 scoreHarvest(harvest) 以纯数据形式返回分数和指标。该报告和 CI 检查得到相同的数字。

长版本包含扫描范围以及插件在您的计算机上运行的内容，位于 docs/reference.md 中。

与

框架

反应，Next.js，混音，Vite 模板、照明、自定义元素

套件和造型

Tailwind、shadcn/ui、MUI、Mantine、查克拉 UI、蚂蚁设计 CSS 模块、Sass、Less、情感、样式组件、香草提取物、CVA、缝合

四种存储库：产品、库、shadcn 安装、注册表。每个都与以相同方式构建的存储库进行比较。

已识别，尚未测量

Vue、Angular、Svelte：在标题中命名，计算颜色和间距，未测量组件。报告是这么说的。 HeroUI、NextUI、Radix Themes、Fluent UI、React Bootstrap、Grommet：在标头中命名，无套件规则。

每个命令

一次扫描即可为所有功能提供动力；标志决定磁盘上的内容。自由组合。

自己运行一下

为您的代理人

“为什么这很重要”是通用的，随该工具一起提供，并且在每个报告中都具有相同的内容。 “回购协议教给代理的内容”是您的代理对您的回购协议的读取，并且仅在代理通过它时才会出现。

通过 MCP 进行实时解答

报告和规则文件描述了扫描时的存储库。当您的代理工作时，--mcp 保持相同的引擎运行，因此问题可以从现在的代码中得到回答，并且错误可以在错误发生之前被捕获。

循环：构建前的上下文、构建时查找、保存前验证、完成前检查。

一场真实的交易所，针对 在 60/100 释放，一种 MUI 产品。代理手里有灰色，心里有填充：

roast_find_token #6b7280
→ Nearest token: #607d8b, 11 channel steps from #6b7280. Unless the difference is a deliberate decision, use the token.

roast_validate (first draft)
→ ✕ L5 Colour #6b7280 written onto an MUI component, and the theme has no such colour.
     Fix: Add it to the theme once (frontend/src/themes/dark-theme.ts), then read it there: color: 'text.secondary' in sx.
  ✕ L5 Pixel size p: 12px on an MUI component.
     Fix: 12px is between steps 1 (8px) and 2 (16px). Keep it with a comment, or use the nearest step in sx.

roast_validate (second draft: color: 'text.secondary', p: 1.5)
→ No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing …

四次调用，低于 800 个标记，新组件读取主题而不是添加颜色编号 44。

图表有自己的规则，因为图表需要几种彼此不同的颜色，而大多数设计系统从不命名它们。在存储库保留图表调色板的情况下，在图表文件中手写的颜色是命名调色板的发现。如果存储库有图表但没有调色板，则手动绘制的新图表会收到一个警告，指出现有图表执行相同操作并要求调色板一次。该警告就是实时差距报告。

服务器按照报告的方式读取存储库。在基于 MUI、Mantine、Chakra UI 或 Ant Design 构建的产品上，上下文命名主题文件和套件自己的读取方式，roast_find_token 以间距步骤进行回答，检查标记写入套件组件（其中主题具有值）的颜色或像素大小。在 Tailwind 主题或 shadcn 存储库上，它们标记了一个调色板类，例如 text-gray-500，其中主题命名了此类颜色。粘贴到组件中的令牌的原始值用令牌的名称进行标记，并且从头开始构建的按钮（其中存储库已经有一个常用的按钮）会收到一条警告，指定要使用的导入行。

roast-fix 提示提供从新扫描开始的顶部移动，与报告的复制按钮字节相同。在Claude Code中输入/mcp__roast__roast-fix，添加一个号码来插队。修复它，再次询问，下一步已经上升到顶部：扫描是进度条。

安装了Claude Code插件吗？ 服务器已经有了。否则：

claude mcp add roast -- npx roast-my-design-system@latest --mcp

在 Claude Code、Cursor 和 Windsurf（现在的 Devin Desktop）中进行了验证。 每个都经过端到端测试：服务器连接、列出所有 5 个工具、编辑者自己的聊天中的真实答案。本地、只读、启动时一次扫描、无端口、无帐户。

光标：将其放在项目内的 .cursor/mcp.json 中（项目，因此扫描会看到一个存储库，而不是整个磁盘），然后第一次在“设置”→“工具”和“MCP”下启用 roast：

{ "mcpServers": { "roast": { "command": "npx", "args": ["roast-my-design-system", "--mcp"] } } }

Windsurf (Devin Desktop)：其 MCP 配置是全局的 (~/.codeium/windsurf/mcp_config.json)，因此命名项目文件夹以将扫描范围限制在一个存储库：

{ "mcpServers": { "roast": { "command": "npx", "args": ["roast-my-design-system", "--mcp", "/path/to/your/repo"] } } }

任何其他 MCP 客户端都可以注册相同的 stdio 命令。

在CI

扫描仪使用 SARIF，因此将其连接到 GitHub 代码扫描需要 6 行。结果显示在“安全”选项卡中，并在文件本身上进行了注释：

- uses: actions/checkout@v5
- run: npx roast-my-design-system@latest . --sarif --no-open
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: design-system-roast.sarif

要仅在新的混乱情况下使拉取请求失败，请使用 Guard-my-design-system。

安装

无需安装，无需克劳德：

npx roast-my-design-system@latest

克劳德代码（推荐）：

/plugin marketplace add gregkozakiewicz/roast-my-design-system
/plugin install roast-my-design-system@roast-my-design-system

它安装的内容：两项技能，一项本地 MCP 服务器和一项编辑挂钩，仅此而已。 烤（/roast-my-design-system，或“烤我的设计系统”）扫描整个存储库，用克劳德读取的其中数字编写报告，然后与您一起进行修复。 审查（/roast-my-design-system:review，或“审查我的 UI 更改”）仅检查更改的内容，大约一秒钟。该钩子在代理编辑每个文件后运行，并返回编辑添加的结果；没有任何新内容的文件不会收到任何消息。

如果这些命令出错，则说明您的克劳德代码早于插件市场。更新它，或使用手动路线：

git clone https://github.com/gregkozakiewicz/roast-my-design-system.git
cp -r roast-my-design-system/skills/roast-my-design-system roast-my-design-system/skills/review ~/.claude/skills/

（在存储库中使用 .claude/skills/ 与您的团队共享。review 技能旁边需要 roast-my-design-system 文件夹。）

OpenAI Codex CLI（相同的 SKILL.md，相同的文件夹）：

git clone https://github.com/gregkozakiewicz/roast-my-design-system.git
cp -r roast-my-design-system/skills/roast-my-design-system ~/.codex/skills/

使用 $roast-my-design-system 调用。在存储库中使用 .codex/skills/ 与您的团队共享。

npx skills： npx skills add gregkozakiewicz/roast-my-design-system 适用于读取 ~/.agents/skills/ 的代理。克劳德代码读取 ~/.claude/skills/，因此更喜欢上述路线之一。

需要节点 18+。

使用

在您想要烘焙的存储库中打开 Claude Code 并输入：

/roast-my-design-system

一旦您拥有值得保护的设计系统，第二项技能将仅检查您更改的内容：

/roast-my-design-system:review

它对 git diff 中的文件运行与 --check 相同的检查，并在 MUI、Mantine、Chakra、Ant Design 或 Tailwind 主题存储库上的套件自己的词汇表中列出每个发现及其修复。没有分数，没有报告：周二下午的小额支票。克劳德还从简单的词语中提取出它，例如“检查我的 UI 更改”或“我是否破坏了设计系统”。

您可以在聊天室中获得信息，并在您的存储库根目录中获得 design-system-roast.html，这是一个独立的页面，其中包含：

• 根据您的数字与理想值的对比情况计算出的健康分数
• “存储库教给代理的内容”：克劳德读取的扫描结果，嵌入到您将转发的文件中，标记为克劳德编写，并与测量的数字分开。光是分数就可以平坦；此部分保持共享的 85/100 诚实
• 统计图块将您与所有 3 个标准进行比较
• 一个文件中的 light/dark 主题切换
• 使用加权调色板栏、灰色斜坡、超比例间距收据、具有可点击文件路径的重复组件收据以及最严重违规者分类帐
• a 修复代理猜测的原因列表：最多 3 个从您的存储库自己的数字派生的移动，每个移动都有一个文件路径收据
• 您的代理必须在哪里猜测？ 打开报告：存储库尚未给出答案的差距，以及证明每个差距的文件以及关闭它的举措，或“未发现差距”
• 向代理人提供答案：design-system-rules.md 包裹在报告内作为礼物。解开包装，然后复制或下载扫描生成的代理规则

烘焙后，该技能会将 design-system-rules.md 写入磁盘并将其合并到 CLAUDE.md、.cursor/rules 或 AGENTS.md 中。

四种尝试提示

Roast my design system.

How bad is my CSS? Scan this repo and show me the receipts.

连接 MCP 服务器后：

Is there already a Button component in this repo, and which one should I use?

日常的，在你改变了一些 UI 之后：

Review my UI changes against the design system.

故障排除

• “找不到命令”或插件将无法安装。更新克劳德代码；插件市场需要最新版本。手动安装适用于任何版本。
• “没有什么可烘烤的”或近乎空的报告。扫描发现几乎没有颜色或间距。该样式可能位于另一个存储库、CDN 或已安装的软件包中。从保存样式的存储库运行它。
• 看起来错误的分数。 检查报告标题：它列出了存储库的读取方式（产品、库、shadcn、套件、Tailwind 主题）以及每个遗漏的文件夹。如果游乐场或旧应用程序使数字模糊，请使用 .roastignore 或 --exclude 进行扫描。
• 报告未打开。 它被写入存储库根目录下的 design-system-roast.html。在任何浏览器中打开它；它不需要服务器，也不发出请求。
• MCP服务器没有出现。添加后重新启动客户端。在Claude代码中，claude mcp list显示是否已连接。它需要 Node 18 或更高版本。

支持

错误和问题请转至 GitHub 问题。其他所有内容均通过 gregkozakiewicz.com 到达 Greg。安全问题：参见SECURITY.md。

隐私

该工具读取您指向的存储库，并将其输出写入它旁边。它不发出网络请求，不收集数据，也不进行遥测。 MCP 服务器通过同一本地扫描进行应答。您的代码、提示或对话的任何内容都不会发送给任何人，包括作者。

它衡量什么

是的，回购中位数已经一团糟了。这就是重点。到达其中的特工将忠实地复制混乱，并在混乱耗尽的地方添加一些自己的。

您的AI可以写入UI。这确保它写入您的UI。