design-md-adapter

一个把 74 个品牌规范"落地"到真实前端项目的自动化工作流 skill。此 skill 完全自包含 —— 74 个 DESIGN.md 数据源已经打包在同目录的 ./design-md/ 子目录下。

🚨 铁律（绝对遵守）

以下规则违反其一，视为 skill 执行失败：

1. ❌ NEVER 从零手写 HTML/Vue/TSX 代码
2. ❌ NEVER 修改骨架模板文件的结构、组件、逻辑 —— 只允许替换 {{XXX}} 占位符
3. ❌ NEVER 用纯 HTML 假装组件库 —— 探测到 Element Plus 就必须用 <el-button>，探测到 Antd 就必须用 <Button from 'antd'>
4. ❌ NEVER 在生成后忘记问用户"是否微调" —— Step 5 是必经环节
5. ✅ MUST 严格按 6 步顺序，不得跳步、不得合并
6. ✅ MUST 生成的骨架代码"复制进项目就能运行" —— 包含真实 import、真实组件标签

触发时机

• "帮我给项目挑一个设计规范"
• "把 xxx 品牌的规范套到我们项目"
• "生成 UI 预览"
• "推荐设计系统"

六步流程总览

┌──────────────────────────────────────────────────┐
│ Step 1 · 探测   项目栈 & 组件库                    │
│ Step 2 · 匹配   从 74 品牌选 Top 3 候选（气质差异）│
│ Step 3 · 视觉对比  → design-style-picker.html      │
│                    用户点选：方案 1/2/3            │
│ Step 4 · 骨架预览  → 按组件库分派模板：            │
│         · Element Plus → design-preview.vue        │
│         · Arco Vue → design-preview.vue            │
│         · Antd v5 → design-preview.tsx             │
│         · 无组件库 → design-preview.html           │
│ Step 5 · 微调询问  颜色/圆角/字体要改吗？          │
│         "不用" → Step 6                            │
│         "改" → 回 Step 4 重生成                    │
│ Step 6 · 落文档   写入 CLAUDE.md + theme.css       │
└──────────────────────────────────────────────────┘

Step 1 · 探测（≤ 5 秒）

Read 项目根 package.json 一次即可。

组件库识别 → 决定 Step 4 用哪个骨架

一句话汇报

> "识别到：Vue3 + Element Plus 2.5。骨架将使用 skeleton-element-plus.vue，输出 design-preview.vue。开始匹配…"

Step 2 · 匹配（≤ 10 秒）

Read brands-index.md，选出 Top 3 候选：

1. 兼容度按组件库过滤前 5
2. 从前 5 里挑气质差异明显的 3 个（一浅一深一渐变最佳）
3. 直接进入 Step 3，不要先给用户解释

Step 3 · 视觉对比（≤ 15 秒）

强制执行步骤

1. Read compare-template.html（skill 目录）
2. 在文件的 <script> 内找到 const BRANDS = [
3. 只替换 3 个品牌对象（找 /* {{OPTION_1}} */、/* {{OPTION_2}} */、/* {{OPTION_3}} */ 注释锚点）
4. 禁止改动 HTML 结构、CSS 样式、JS 渲染逻辑
5. Write 到项目根：design-style-picker.html

交互话术

> ✅ 视觉对比页已生成 → design-style-picker.html
> 请双击打开，选好后告诉我 我选 1 / 2 / 3

Step 4 · 骨架预览（≤ 25 秒 · 最关键步骤）

强制执行步骤

根据 Step 1 探测到的组件库，选定对应的骨架文件：

1. Read 对应的 skeleton-XXX.vue / .tsx / .html（见上表）
2. Read design-md/<selected-slug>/DESIGN.md 获取完整 tokens
3. 从 YAML front-matter 提取以下值：
   - colors.primary → {{PRIMARY}}
   - colors.primary-active 或 primary-hover → {{PRIMARY_HOVER}}
   - colors.on-primary → {{ON_PRIMARY}}
   - colors.canvas → {{CANVAS}}
   - colors.canvas-soft / surface-soft → {{CANVAS_SOFT}}
   - colors.ink → {{INK}}
   - colors.body / muted → {{INK_MUTED}}
   - rounded.md 或按钮引用值 → {{RADIUS}}
   - rounded.pill → {{RADIUS_PILL}}
   - typography.display.fontFamily → {{FONT_DISPLAY}}
   - typography.body.fontFamily → {{FONT_BODY}}
   - 品牌名 → {{BRAND_NAME}}
   - 文件夹名 → {{BRAND_SLUG}}
4. 在骨架里逐个替换所有 {{XXX}} 占位符
5. Write 到项目根：design-preview.vue / .tsx / .html

🚨 严格禁止

• ❌ 修改 <template> 结构（Vue）
• ❌ 修改 <script> 逻辑（Vue）
• ❌ 修改 JSX return 里的组件（React）
• ❌ 增删任何 section
• ❌ 把 <el-button> 改成 <button>
• ❌ 把 <Button> (from antd) 改成 <button>

✅ 只允许

• 替换 {{XXX}} 占位符
• 替换 <style> 里的颜色/圆角/字体值

交互话术

> ✅ 骨架预览 → design-preview.vue（真实 Element Plus 组件 + {{BRAND_NAME}} 主题）

Step 5 · 微调询问（≤ 10 秒 · 必经）

生成完 Step 4 之后，必须 立即询问：

> 预览已生成，是否需要微调？
> · 主色：{{PRIMARY}} 当前值
> · 圆角：{{RADIUS}} 当前值
> · 字体：{{FONT_BODY}} 当前值
>
> 说 "不用" 继续 / 说 "主色改成 #xxx" 我重生成 / 说 "换品牌" 回到 Step 3

处理用户回复

Step 6 · 落文档（≤ 15 秒）

询问确认

> 满意吗？如果满意，我会：
> · 追加 CLAUDE.md（Design System 章节）
> · 生成 src/styles/theme.css（组件库主题覆盖）
>
> 确认 → 输入 是 / 写入

写入操作

参考 claude-md-template.md 的模板，替换所有 <XXX> 占位符。

已存在文件的处理：
- CLAUDE.md 存在 → 追加到末尾（先展示 diff）
- theme.css 存在 → 备份为 theme.css.bak.<timestamp> 再重写

各步骤耗时目标

交互脚本（AI 该说的话）

Step 1：识别到：<framework> + <lib> <version>。骨架 = <skeleton-file>，输出 <output-file>。开始匹配…

Step 2：（无输出，直接进 Step 3）

Step 3：✅ 视觉对比页 → design-style-picker.html。选好后告诉我 我选 X。

Step 4：✅ 骨架预览 → design-preview.<ext>（真实 <lib> 组件 + <brand> 主题）

Step 5：需要微调吗？（主色/圆角/字体/无）

Step 6：✅ 已写入 CLAUDE.md · theme.css。以后新 UI 会自动遵循这份规范。

常见错误自检清单

执行完每一步，AI 应该自问：

• [ ] Step 3 生成的对比页是否只改了 BRANDS 数组？（其他没动）
• [ ] Step 4 输出的文件扩展名对不对？（.vue / .tsx / .html）
• [ ] Step 4 里用的组件标签是不是真实的组件库标签？（不是原生 <button> <input>）
• [ ] 所有 {{XXX}} 占位符是否全部替换？（用 grep 自检文件里不再有 {{）
• [ ] Step 5 有没有跳过？（必须问）
• [ ] Step 6 有没有强行执行？（必须先问用户）

参考文件

• component-brand-map.md — 组件库 × DESIGN.md 兼容矩阵
• brands-index.md — 74 品牌快速索引
• compare-template.html — Step 3 视觉对比模板
• skeleton-element-plus.vue — Step 4 骨架（Element Plus）
• skeleton-arco-vue.vue — Step 4 骨架（Arco Vue）
• skeleton-antd.tsx — Step 4 骨架（Ant Design v5）
• skeleton-plain.html — Step 4 骨架（无组件库/纯 HTML）
• claude-md-template.md — Step 6 CLAUDE.md 格式
• preview-template.md — 骨架设计说明
• examples.md — 使用场景示例
• design-md/ — 74 品牌完整规范