内容
# 设计系统治理 MCP
[](https://www.npmjs.com/package/@shiroe_nguyen/dsmcp)
[](LICENSE)
[](package.json)
[](https://xshiroenguyenx.github.io/design-system/)
🔗 **[在线演示](https://xshiroenguyenx.github.io/design-system/)** — 所有 18 种模式 × 6 种字体下的每个令牌和组件，均有两种实时切换器。
**合约 + 强制执行，使 AI 使用固定的设计令牌、组件和规则，而不是猜测样式** — 生成的 UI 一致性高，处于正确模式，无漂移。
> **“AI 可以调用工具” ≠ “AI 遵守”** 引擎纯 TypeScript，通过三个接口暴露：**MCP**（建议 — AI 调用 `get_contract` 进行生成），**CLI** 和 **hooks / CI**（确定性强制执行，无论 AI 是否配合）。所有逻辑位于 `src/engine/`；无导入 MCP SDK。
状态：**v0.1.0 — 功能完整**（阶段 0–5，所有 4 个堆栈）。参见 [PLAN.md §0](PLAN.md) 获取完整范围和有意延迟的功能。
## 功能
- **DTCG 令牌模型** — 3 层（原始 → 语义 → 组件），模式感知值，`extends` 继承。解析器标记缺失模式、循环和悬空引用。
- **18 种颜色模式** 开箱即用 — 10 种功能模式（`light`、`dark`、`dim`、`midnight`、高对比度浅色/深色、`sepia`、solarized 浅色/深色、`nord`）+ 8 种美学模式（`love`、`future`、`synthwave`、`sakura`、`forest`、`ocean`、`coffee`、`aurora`）。**每种模式都通过 WCAG-AA 对比度和完整性测试**。通过 `[data-theme]` 切换。
- **独立字体轴** — 6 种字体包（`system`、`serif`、`mono`、`rounded`、`humanist`、`slab`）与颜色模式**独立**切换，通过 `[data-type]`。字体包重新指向 `--font-family-sans|mono`，因此整个 UI 跟随，无需组件更改。两个轴自由组合（模式 × 字体）。
- **验证器** — `no-raw-color`、`single-mode-strategy`、`mode-completeness`、`contrast-aa` 和旗舰 `interactive-completeness`（每个交互元素必须在每种模式下定义悬停/活动/焦点可见/禁用）。结构化发现 + 合规性评分 + `suggest_fix`。
- **4 个目标堆栈** — CSS 变量、Tailwind、纯 CSS 和 Flutter。规则针对堆栈，因此每个堆栈仅运行适用的规则。
- **脚手架和采用** — `scaffold_theme` 生成令牌 + 受控组件 + 模式/字体切换器 + 采用工件（`CLAUDE.md` / `.cursorrules` / 预提交 / GitHub Actions / 停止钩子）。`generate_demo` 构建一个展示所有令牌在所有轴上的实时演示。
## 安装
```bash
npm install -g @shiroe_nguyen/dsmcp # 将 `dsmcp` + `dsmcp-mcp` 放在您的 PATH 上
# 或在不安装的情况下运行：
npx @shiroe_nguyen/dsmcp doctor
```
## 快速入门（CLI）
```bash
dsmcp doctor # 自我检查捆绑主题（所有模式解析 + 对比度）
dsmcp scaffold --out ./app --stack css-vars # 令牌 + 组件 + 切换器 + 采用文件
dsmcp demo --out ./app/demo # 生成实时演示
dsmcp validate ./app # 如果有错误，则退出 1 → 提交失败 / CI
dsmcp report ./app --json # 合规性报告（始终退出 0；CI 工件）
```
其他查找：`dsmcp contract --stack css-vars`、`dsmcp list-tokens --category color`、`dsmcp resolve color.bg.default --mode dark`、`dsmcp component button`。
## 作为 MCP 服务器使用
软件包附带一个 `dsmcp-mcp` stdio 服务器。在 `.mcp.json` 中，参数按原样传递（无 shell），因此作用域名称无需引用 — 直接复制：
**macOS / Linux:**
```json
{
"mcpServers": {
"dsmcp": { "command": "npx", "args": ["-y", "-p", "@shiroe_nguyen/dsmcp", "dsmcp-mcp"] }
}
}
```
**Windows** （用 `cmd /c` 包装 — 客户端无法直接生成 `npx.cmd`）：
```json
{
"mcpServers": {
"dsmcp": { "command": "cmd", "args": ["/c", "npx", "-y", "-p", "@shiroe_nguyen/dsmcp", "dsmcp-mcp"] }
}
}
```
> **在终端中测试？** 引用作用域名称 — PowerShell 否则读取 `@…` 为 splatting 并删除包：
> `npx -y -p "@shiroe_nguyen/dsmcp" dsmcp doctor`
**11 种工具**：`get_contract`、`list_tokens`、`resolve_token`、`get_component_spec`、`scaffold_theme`、`generate_demo`、`validate_code`、`validate_project`、`suggest_fix`、`import_theme`、`register_theme`。
## 作为库使用
```js
import { loadDefaultTheme, scaffoldTheme, validateProject } from "@shiroe_nguyen/dsmcp";
const theme = loadDefaultTheme();
const report = validateProject("./app", { stack: "css-vars" });
console.log(report.score, report.findings);
```
## 演示
**▶ 直播：https://xshiroenguyenx.github.io/design-system/**
该页面在 **所有 18 种模式 × 6 种字体** 下渲染每个令牌和受控组件，均有两种独立的实时切换器。它在每次推送到 `main` 时自动部署到 GitHub Pages（参见 [.github/workflows/demo.yml](.github/workflows/demo.yml)）。
随时生成：
```bash
dsmcp demo --out ./demo
npx serve ./demo # 或任何静态服务器，然后打开打印的 URL
```
## 开发
```bash
npm install
npm test # 构建 + MCP stdio 烟雾测试（11 种工具）+ 脚手架/字体 + 验证器 + 导入器
```
编译后的 CLI 是 `node dist/cli.js <cmd>`（与 `dsmcp <cmd>` 相同的命令）。
```
src/engine/ 纯核心（令牌、解析器、规则、合约）— 无 MCP/CLI 依赖
src/mcp/ MCP stdio 接口
src/cli.ts CLI 接口
themes/default 默认 DTCG 主题 + typefaces.json
test/ 烟雾测试 + 良好与漂移的固定装置
```
## 文档
- **[PLAN.md](PLAN.md)** — 完整设计、架构和交付状态（§0）。
- **[RELEASE.md](RELEASE.md)** — 如何发布（手动 + 标签驱动的 CI）。
## 许可证
[MIT](LICENSE)
