Design-anchor 是什么？

Design-anchor 是一套面向 AI coding 的本地设计系统控制面。它给 agent 补上写产品 UI 时最容易缺失的上下文：design token、组件规范、导入规则、audit 检查、MCP 工具，以及用于查看系统状态的 Portal。

它尤其适合 B 端和企业产品。Dashboard、表单、设置页、表格和运营工作流需要长期保持清晰、克制、稳定，而不是每一轮 prompt 都生成一套新的视觉语言。

快速开始

npm install -D design-anchor
npx design-anchor start

安装 npm 包本身不会初始化项目，也不会自动打开 Portal。它只安装 CLI 并打印提示。只有运行 Design-anchor 命令后，才会开始初始化或启动。

start 会创建本地控制面、写入根目录 design-tokens.json、按需安装 Portal 工具链，并打开 Portal。默认不会写入项目根的 AI 规则或 MCP 文件。

需要把组件写入业务源码时：

npx design-anchor add button

然后在业务代码里引用：

import { Button } from "@design";

export function SaveAction() {
  return <Button>保存修改</Button>;
}

如果是已有产品，只想先接 AI 治理规则：

npx design-anchor govern

核心能力

AI 生码规则

Design-anchor 默认把 AI 可读的组件 spec 和 token 契约留在本地 .anchor/ 控制面里。只有显式运行 npx design-anchor govern 时，才会为常见 AI coding 工具生成默认忽略的桥接文件。

这些契约会要求 AI：

• 写 UI 前先检查已安装的 @design 组件
• 使用 bg-primary、text-muted-foreground 这类语义 token class
• 避免硬编码颜色和 token-sensitive 的任意值 Tailwind
• 缺组件时用 npx design-anchor add <component> 按需添加
• UI 任务结束时输出 Design Anchor 自检

按需源码落地

Design-anchor 不会一次性把整套组件库写进项目。需要哪个组件，anchor add 就只把这个组件和它的本地依赖写入 src/components/。

这样前端能直接 review 和维护真实使用的组件，同时避免项目一开始背上完整组件库的维护负担。

从风格 prompt 提取 token

把产品风格 prompt 交给 Design-anchor：

npx design-anchor theme design-prompt.md

它会把可落地的 token 值写入项目根目录 design-tokens.json，在 .anchor/ 下重新生成本地 CSS 变量，并生成克制的 AI 风格指导。prompt 可以轻量影响节奏、层级、密度和氛围；组件规范和语义 token 始终是更强的约束。

Sync 和 Audit

npx design-anchor sync
npx design-anchor audit

sync 会重新生成 token CSS、Tailwind 扩展和 AI 可读规则。

audit 会检查常见设计系统漂移：

• 已有受治理组件时仍使用原生标签
• 硬编码颜色
• token-sensitive 的任意值 Tailwind
• 绕过已安装组件源码的 import

给 AI 工具用的 MCP

Design-anchor 提供可移植的 MCP 工具。默认情况下 MCP 配置保持本地化；如果希望 AI 客户端自动启动 MCP，可以手动加入下面这个默认忽略的桥接配置，或运行 npx design-anchor govern：

{
  "mcpServers": {
    "anchor": {
      "command": "npx",
      "args": ["--no-install", "design-anchor", "mcp", "./.anchor"]
    }
  }
}

AI 工具通常会自动启动 MCP。如果 .anchor/ 不存在，MCP 命令会先在本地重建它，再提供工具。日志走 stderr，stdout 保持干净的 JSON-RPC。

当前 MCP 工具包括：

list_components · read_component · create_component · list_tokens · update_token · list_schemas · read_schema · update_schema · run_audit · run_sync_rules · get_cursorrules · read_file · write_file

项目结构

接入后，业务项目大致会变成这样：

your-project/
├── src/components/          anchor add 后出现的用户自有组件源码
├── design-tokens.json                 项目 token 真源
├── .anchor/                           本地、通过 git exclude 忽略的控制面
│   ├── src/anchor/schema/             组件 spec 和 AI 契约
│   ├── src/anchor-portal/             Portal 应用
│   ├── design-tokens.generated.css    本地生成的 token CSS
│   └── package.json                   本地 Portal 工具链

默认只提交业务真正需要长期拥有的文件：src/components/ 下已添加的组件、项目根目录 design-tokens.json，以及 anchor add 注入运行时依赖时产生的正常包管理 manifest 变化。不要提交 .anchor/、生成 token CSS、AI 规则、MCP 配置或 Anchor manifest；协作者可以通过 MCP 自动恢复，也可以手动运行：

npx design-anchor hydrate

代码边界与 Git 策略

Design-anchor 把三类内容分开：

| 层 | 位置 | Git 策略 | |---|---|---| | 用户自有组件 | src/components/ | 提交。这里是真正被业务应用使用的组件源码，只在需要组件时写入。 | | Design token | design-tokens.json | 提交。这个单文件保证主题可以复现。 | | 运行时依赖 | package.json / lockfile | 仅当 anchor add 注入了已安装组件需要的依赖时提交。 | | Anchor 控制面 | .anchor/ | 不提交。本地生成、默认写入本地 git exclude、可以随时重建；生成 CSS 也在这里。 |

业务代码从 @design 或 @/components 引用已安装组件。不要从 .anchor/ 深路径引用组件实现。

CLI 命令

anchor start [dir]         初始化、安装必要依赖并打开 Portal
anchor init [dir]          scaffold 本地 .anchor/ 控制面
anchor hydrate [dir]       拉取仓库或清理后重建本地 .anchor/
anchor govern              只注入 AI 规则，不接完整组件工作区
anchor add <components>    按需添加组件源码
anchor theme <file>        从 design prompt 提取 token
anchor screenshot [img]    打印截图转 token 的工作流指导
anchor upgrade [dir]       更新模板文件并保留本地修改
anchor dev [dir]           启动 Anchor Portal
anchor portal [tab] [dir]  打开 Portal tab：tokens/theme/components/specs/docs
anchor sync [dir]          重新生成 tokens 和 AI 规则
anchor audit [dir]         扫描设计系统违规
anchor mcp [dir]           以 stdio 启动 MCP server

常见工作流

用 AI 写一个页面

1. 让 AI coding 工具实现页面。
2. 生成的规则会让它先检查已安装组件和 token。
3. 如果缺组件，运行 npx design-anchor add <component>。
4. 运行 npx design-anchor audit。
5. 让 AI 在总结里输出 Design Anchor 自检。

调整主题

npx design-anchor theme design-prompt.md
npx design-anchor sync
npx design-anchor portal theme

拉取仓库后恢复控制面

npm install
npx design-anchor hydrate

大多数 AI 工具也可以在依赖安装后，通过 MCP 自动恢复 .anchor/。

手动发布检查

维护者准备手动发布 npm 前，建议跑：

npm run typecheck
npx tsc --noEmit --noUnusedLocals --noUnusedParameters
npm run build
npm run check:anchor
npm run anchor:audit:all
npm pack --dry-run --ignore-scripts

然后手动发布：

npm publish

技术栈

• React 19
• Tailwind CSS v4
• Radix UI primitives
• Ant Design 色彩算法做 token 派生
• Vite Portal
• MCP stdio JSON-RPC

License

MIT