onsystem

onsystem

**让编码 Agent 遵循你的设计系统：**在每次编辑和拉取请求中，发现调色板颜色、原生元素和你的系统缺少的 API，并提供修复方案。只需在设计系统包中设置一次；单体仓库中的每个应用都能使用。可在本地运行，并可与 @shadcn/lint 搭配使用。

专为拥有 React 设计系统包的设计系统和平台团队打造；shadcn/ui 应用可作为零配置演示。此前名为 @dgesteves/design-system-mcp（变更说明）。

在使用 GitHub Action？uses: dgesteves/onsystem@v0 会检查拉取请求中变更的行：请参阅 CI 和基线。

也兼容

网站和文档：onsystem.vercel.app，提供一个在线体验环境，可检查你自己的代码。

**欢迎反馈：**在发布反馈讨论帖中指出问题，在路线图中查看后续计划，或认领一个适合新手的议题。如果 onsystem 对你有帮助，点个星标能让更多人发现它。

https://github.com/user-attachments/assets/900cc1fa-387c-4e76-a524-a818521dd1a0

_{在网站上，Agent 起草了一张设置卡片，check_ui 找出 11 个问题并为每个问题提供一个修复方案，然后 Agent 应用这些修复。接着是一个使用该插件的真实 Claude Code 会话：Claude 在编写之前先查找组件，check_ui 检查通过。最后是基准测试。}

问题

编码 Agent 根据训练数据而非你的设计系统来编写 UI。让它创建一张设置卡片，你得到的可能是 bg-[#ef4444]、p-[13px]、原生 <button>、给只有 destructive 变体的 Button 设置 variant="danger"，以及系统实际导出 CardHeader 却使用了 <Card.Header>。在上面的演示草稿中，tsc 报告了 11 个问题中的 3 个；其余问题只能等有人有空时在审查中发现。向 Agent 描述设计系统会有所帮助；真正可靠的做法，是在编辑时和提交拉取请求时检查它实际写出的内容。

检查内容

onsystem 使用 TypeScript 编译器从源码中读取组件、cva 和 tv 变体、部件及令牌，并据此检查 .tsx 和 .jsx。每条发现都包含规则 ID、位置和修复方案。令牌来自样式表、DTCG 2025.10 文件或 DESIGN.md，而 onsystem export 会将其导出为其中任一种格式。

规则	默认级别	检查内容
no-unknown-component	error	不存在的组件和部件（<Card.Header>、拼写错误）
no-unknown-prop	error	组件不接受的属性（tone、isDisabled）
no-unknown-variant	error	变体范围之外的值（variant="danger"）
prefer-design-system-component	error	设计系统已有对应组件的原生元素（<button> → <Button>）
no-hardcoded-color	error	Hex、rgb、hsl、oklch 和 Tailwind 调色板颜色（bg-gray-100 → bg-muted）
icon-button-accessible-name	error	缺少无障碍名称的纯图标按钮
no-hardcoded-spacing	warn	任意内边距、外边距和间距（p-[13px] → p-3）
no-hardcoded-radius	warn	任意圆角（rounded-[7px] → rounded-sm）

误报频率。 corpus 任务会在 12 个按提交固定版本的公开仓库上运行 check（Documenso、Dub、Cal.com、midday、Flowise 等：共运行 24 次，发现 14,539 条不同问题），运行时不安装这些仓库的依赖（两个 MUI 应用会安装 MUI）。从这些发现中按规则分层随机抽取 80 条，仅依据代码进行标注：由 AI 审阅者（Claude Opus 5.5）盲标，而非人工标注。其中 57 条判断正确，14 条有争议，9 条为误报：误报率为 11.2%（95% Wilson 置信区间为 6.0-20.0%）；按各规则在全部发现中的占比加权后，结果也大致相同（11.0%）。大多数误报来自 no-hardcoded-color（抽样的 65 条中有 7 条）。如果把项目自身设计系统已经使用的值视为有争议，那么 80 条中有 6 条是误报（7.5%，3.5-15.4%）。抽样结果列出了每条的标签、原因、标注者备注，以及用于得出这些数字的脚本。已发布的代码很少会自行定义组件、属性或变体；未安装依赖时，no-unknown-prop 会跳过属性无法解析的组件：这三条规则在语料库中共发现 56 条问题，其中 55 条来自一个使用 MUI 的 Flowise 应用，抽样中有 3 条，均判断正确，但数量太少，无法单独计算误报率。语料库中较早的标签由能看到发现内容、因此并非盲标的 AI 审阅者制作；如果其中一条真阳性不再被报告，或一条已修复的误报重新出现，任务就会失败。来自 shadcn 注册表的代码（例如聊天机器人的 components/ai-elements）尚无标签（来自 shadcn 注册表的代码）。规则参考通过示例展示了每条规则，以及如何抑制发现。

快速开始

使用 Node.js 20.19 或更高版本，可在应用文件夹中或 monorepo 根目录下运行：

npx -y onsystem inspect   # what it found; --explain says why
npx -y onsystem check .   # the same check the agent and CI run
npx -y onsystem init      # write the config, and offer a baseline

在monorepo 根目录，inspect 会列出每个应用和设计系统包，check 则根据每个文件所属项目的设计系统逐一检查。在设计系统包中，init 会为依赖该包的所有应用完成设置，应用中无需配置：无论该包是工作区包，还是从 npm 安装。已安装的应用会读取该包发布的源文件中的组件；如果包只发布编译后的 dist/，则会读取其中的类型声明（.d.ts），两种情况下都会应用所有规则（init 会检查其 files 列表）。如果包发布的是编译后的代码，且没有类型声明，那么应用只能获得令牌规则，无法检查组件、属性、变体或原生元素。

在新的 create-next-app 项目中，模板页面里硬编码的颜色就足以让第一次 check . 检查失败；init 可以将这些记录为基线，这样只有新发现的问题才会导致失败。从 shadcn 注册表安装的文件夹（例如 components/ai-elements）属于他人的代码：shadcn 注册表中的代码介绍了如何检查这些代码或将其排除。

Claude Code。 此插件包含钩子、MCP 服务和技能：

/plugin marketplace add dgesteves/onsystem
/plugin install onsystem@dgesteves

每次写入或编辑 .tsx 或 .jsx 文件后，钩子都会对该文件运行 onsystem check。错误会连同修复方法一起作为阻止性错误返回给 Claude，因此 Claude 会先修正文件再继续；警告则会作为备注返回。在没有设计系统的项目中，它会保持静默。Codex 会安装同一个插件，钩子会检查其 apply_patch 修改的文件。运行和操作的内容。

Cursor 或 VS Code。 ，或提交配置。Agent 会获得这些工具，并对其编写的内容运行 check_ui。

其他 Agent。 npx skills add dgesteves/onsystem 会将技能添加到任何支持 Agent Skills 的 Agent；此外还有适用于 Codex、GitHub Copilot CLI、VS Code 和 Cursor 的插件。

任何 MCP 客户端。 运行 npx -y onsystem，将其作为 stdio 服务。这里提供了适用于 Claude Desktop、Codex CLI、GitHub Copilot CLI、Windsurf、JetBrains IDEs、Zed、Gemini CLI、Antigravity 和 Grok Build 的配置。

CI。 将其安装为开发依赖，先接受一次代码库中已有的问题，然后仅在拉取请求引入新问题时使检查失败：

npm install --save-dev onsystem
npx onsystem check . --update-baseline   # writes onsystem.baseline.json: commit it

- run: npx onsystem check . --format github --require-design-system

问题会以注释的形式显示在拉取请求中；如果找不到设计系统，--require-design-system 会使作业失败。CI 和基线介绍了完整的工作流。

GitHub Action。 此action会运行相同的检查，遵循基线，并且只对拉取请求修改过的行添加注释。它会在检出代码并完成安装后运行，因此可以读取你的设计系统：

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-node@v7
    with:
      node-version: 24
      cache: npm
  - run: npm ci
  - uses: dgesteves/onsystem@v0

将其设为 Agent 拉取请求的必需检查介绍了完整的工作流及其输入。 ESLint。 ESLint 8.57、9 和 10 使用相同的规则：将 onsystem.configs.recommended 从 onsystem/eslint 添加到 eslint.config.mjs（ESLint 插件，搭配 @shadcn/lint）。

兼容 @shadcn/lint

@shadcn/lint 会在 Tailwind v4 中，以 ESLint 或 Oxlint 规则检查针对组件和主题编写的 Tailwind 类（重新设置样式、原始颜色、任意类和未知类）。onsystem 则会在 Tailwind v3 或 v4 中检查组件、属性和变体值是否存在，并标记原生元素和未命名的图标按钮。它的 MCP 服务会在 Agent 编写代码前向其展示你的组件和令牌；在 Claude Code 中，它的钩子会检查每次编辑。建议同时运行两者。Benchmark v2 还会使用 @shadcn/lint 对每项输出进行评分：请参阅独立评分器的表格。

它有帮助吗？

Benchmark v2 在 5 个开源代码库中，为来自 3 家提供商（Anthropic、OpenAI 和 Google）的 6 个模型安排了 20 项单文件 UI 任务，分别测试不使用 onsystem、使用其技能、MCP 服务或钩子，以及同时使用这三者的情况：共 1,200 次运行，每组 240 次。按照 onsystem 0.5.0 自身的检查结果，每次运行中的设计系统错误数从不使用 onsystem 时的 0.85 降至同时使用三者时的 0.00，而 tsc 通过率没有可测量的变化（93% → 92%）。

这一统计由 onsystem 自身完成，而 MCP 服务和钩子会向 Agent 展示相同的错误以供修正。在要求为没有成功令牌的设计系统添加绿色状态标签的任务中，使用 onsystem 的 Agent 经常使用 chart-* 令牌，而 onsystem 会将其计为无错误。由 AI 审查者进行的盲审标签每组仅覆盖 12 个文件，数量太少，无法确认这一统计；而审查者发现的所有违规项，无论是在使用钩子的组还是同时使用三者的组中，都是 Dub 中的调色板颜色，因为 0.5.0 没有读取 Dub 的令牌。基准测试页面列出了所有表格，bench/v2 中则包含测试方法、每次运行的数据和所有生成的文件。

兼容性

package.json 中的声明和 CI 中的测试：

项目	支持情况
Node.js	Node.js 20.19 或更高版本（engines）。CI 在 Node.js 22、24 和 26 上运行测试，并在 20.19 上测试构建后的包
操作系统	Linux、macOS 和 Windows：CI 会在每个平台上运行测试和打包测试
ESLint	仅 ESLint 插件支持 ESLint 8.57、9 和 10：eslint 是可选的 peer 依赖，CLI、MCP 服务、钩子和 Action 均不需要它
TypeScript	不会使用你项目中的 TypeScript，JavaScript 项目也无需安装：onsystem 使用自带的 TypeScript 6.0（作为依赖，而非 peer 依赖）读取 .tsx 和 .jsx 文件
React	支持为 React 18（使用 forwardRef）或 React 19（将 ref 作为 prop）编写的组件，可从源代码或类型声明中读取。onsystem 不依赖 React
Tailwind CSS	支持 v4（@theme）和 v3（读取 tailwind.config，但不会运行它）。若不使用 Tailwind，设计令牌可来自 CSS 自定义属性、DTCG 文件或 DESIGN.md
shadcn/ui	支持 Radix（asChild）和 Base UI（render）这两种基础组件，可搭配 Tailwind v3 或 v4 使用，无需配置
MCP 客户端	任何可启动 stdio 服务的客户端；CI 会通过 2025-11-25 和 2026-07-28 协议连接。设置你的 Agent列出了各客户端的配置和支持级别

文档

可在网站上查看，也可在 docs/ 中查看 Markdown 文档：

• 快速入门、Claude Code 插件、CI 和基线以及设置你的 Agent，其中包含各客户端的配置
• 配置、规则、MCP 工具和故障排查
• 工作原理、常见问题和从 design-system-mcp 迁移

仓库中还包含贡献指南、安全说明和更新日志。

许可证

MIT © Diogo Esteves