从前端代码提取设计系统
分析前端源代码，提取一份全面的设计系统文档（DESIGN.md），捕获项目的视觉语言——颜色、排版、间距、组件模式和布局原则——直接来自源文件，无需构建或运行应用程序。
为什么需要这个技能
design-md 技能基于渲染后的 HTML 工作。但通常，你拥有一个代码库，并希望先了解其设计系统后才能运行应用程序——也许依赖缺失、构建出错，或者你只想快速审计。此技能直接读取源文件本身：样式表、组件文件、主题配置和 Tailwind 设置。它更快，并且适用于任何场景。
何时使用
- 用户拥有前端代码库并希望提取或记录其设计系统
- 用户希望将项目的视觉标识迁移到 Stitch
- 用户要求“审计样式”或“理解设计语言”
- 用户希望从现有源代码创建 DESIGN.md
- 应用程序无法构建/渲染，但源代码可用
- 用户希望统一或调和代码库中不一致的样式
前提条件
- 访问前端项目的源目录
- 无需构建或运行时依赖——此技能仅读取源文件
工作流
第一阶段：项目发现
首先了解你所处理的项目。这决定了使用哪些提取模式。
1. 检测框架和技术栈
扫描项目根目录，寻找特征文件：
| 信号文件 | 框架/工具 |
|---|---|
package.json 中包含 react | React / Next.js |
package.json 中包含 vue | Vue / Nuxt |
package.json 中包含 svelte | Svelte / SvelteKit |
package.json 中包含 @angular/core | Angular |
tailwind.config.js/ts | Tailwind CSS |
postcss.config.js | PostCSS 管道 |
styled-components 或 @emotion 在依赖中 | CSS-in-JS |
仅包含 .css / .scss / .less 文件 | 纯 CSS / SASS |
theme.js / theme.ts / tokens.js | 设计令牌文件 |
首先读取 package.json ——它会揭示框架、CSS 工具以及任何设计令牌库（例如 style-dictionary、@chakra-ui/react、@mui/material、ant-design）。此上下文告诉你应该在哪里查找样式信息。
2. 映射源代码树
确定要分析的关键目录和文件：
src/
├── components/ ← 组件级样式
├── styles/ ← 全局样式表
├── theme/ ← 主题定义、令牌
├── assets/ ← 字体、图片
├── app.css ← 根样式
└── index.css ← 入口 CSS
同时检查以下内容：
tailwind.config.js/tailwind.config.ts—— 自定义颜色、字体、间距globals.css/global.css—— CSS 自定义属性（变量）- 任何
theme.*或tokens.*文件 - 组件库配置（例如
chakra-theme.ts、vuetify.config.ts）
3. 读取框架特定的指南
查阅相应参考文档以了解提取模式：
- React / Next.js / Tailwind → references/react-tailwind.md
- Vue / Nuxt → references/vue.md
- Svelte / SvelteKit → references/svelte.md
- Angular → references/angular.md
- 纯 CSS / SASS / Less → references/plain-css.md
这些参考文档包含特定于框架的模式，用于定位颜色、排版、间距和组件样式。在继续前，请阅读匹配的参考文档。
第二阶段：深度提取
系统地处理每个设计维度。对于每一个维度，从源文件中收集原始数据，然后将其综合为描述性语言。
目标不是转储每个 CSS 属性——而是理解样式选择背后的意图，并用人类、编辑化的语言描述它们，以便其他设计师（或 Stitch）可以重现相同的视觉感受。
1. 视觉主题与氛围
首先阅读最宽泛的样式，以了解整体基调：
- 根背景：
body或根元素的背景是什么？浅奶油色（#f 范围）表示通风/干净；深色（#0-#2 范围）表示情绪化/戏剧化。 - 空白哲学：间距值是否宽裕（32px+）还是紧凑？检查根容器、部分包裹器和卡片组件上的 padding/margin 值。
- 密度：统计每个页面/部分的组件数量。数量少且空间大 = 极简；数量多且紧密排列 = 信息密集。
- 色温：中性色是暖色（奶油色、黄褐色）还是冷色（蓝灰色、石板色）？
- 整体感受：综合成 1-2 句丰富的句子，捕捉整体氛围。
在源代码中查找这些信号：
| 源位置 | 告诉你的信息 |
|---|---|
根 background-color 或布局上的 Tailwind bg-* | 整体明亮/黑暗程度 |
| Tailwind 配置或 CSS 变量中的间距比例 | 空白哲学 |
| 组件数量与包裹器 padding | 密度 |
自定义属性命名（--warm-* vs --cool-*） | 色温意图 |
| 主题文件中的注释 | 开发者自己话语中的设计意图 |
2. 调色板与角色
提取代码库中每个独特的颜色，并分配功能角色。跨所有层搜索：
在哪里找到颜色：
| 层 | 搜索什么 |
|---|---|
| CSS 自定义属性 | --color-*、--primary、--bg-* |
| Tailwind 配置 | theme.extend.colors |
| 主题/令牌文件 | 颜色对象、调色板 |
| 组件样式 | background-color、color、border-color |
| 内联/作用域样式 | 模板中的 bg-*、text-* 类 |
| CSS-in-JS 主题对象 | colors、palette 键 |
如何组织： 按功能分组颜色，而不是按色相：
- 主要基础 — 背景和表面颜色
- 强调与交互 — CTA 按钮、活跃状态、链接
- 排版与文本层次 — 一级、二级、三级文本
- 功能状态 — 成功、错误、警告、信息
对于每种颜色，创建一个唤起颜色特征的描述性名称，而不是其原始十六进制值：
- ❌
#294056→ "蓝色" - ✅
#294056→ "深哑光蓝绿色" — 主要 CTA、活跃导航
去重很重要。 代码库通常具有接近重复的颜色（例如 #333 和 #2C2C2C）。将它们合并到一个最能代表预期颜色的名称下。
3. 排版规则
提取完整的排版系统：
字体系列：
- 检查 CSS
font-family、TailwindfontFamily、Google Fonts 链接或本地@font-face声明。 - 注意每种字体的特征：几何 vs 人文主义、衬线 vs 无衬线、它所唤起的感受。
字号层次（层级）：
- 找到每个标题级别（H1-H6）和正文，注意：
font-size（以 rem 或 px 为单位）font-weight（数值 + 描述性名称）letter-spacing（以及原因——优雅？紧凑？）line-height（为可读性而宽松？为展示而紧密？）
- 映射组件用途：产品卡片使用哪个标题级别？英雄区域呢？
间距原则：
- 文本间距如何与整体间距比例相关联？
- 标题与正文上的字间距模式
- 行高哲学（正文宽松/放松，展示文本更紧密）
4. 组件样式
分析 4-5 个最重要的 UI 原语：
按钮：
- 圆角半径（以及它传达的信息——俏皮？专业？极简？）
- 主要、次要和幽灵变体的配色方案
- 悬停/焦点/活跃状态和过渡时间
- 内边距比例（水平 vs 垂直）
卡片 / 容器：
- 圆角半径（通常与按钮不同——略微更圆）
- 阴影策略：平面、微妙的悬停阴影或始终升高？
- 边框处理：细线边框、彩色强调边框或无边框？
- 内部内边距（宽裕或紧凑？）
- 卡片内的图像处理（全出血、带内边距、圆角？）
导航：
- 布局模式（水平栏、垂直侧边栏、抽屉）
- 排版处理（大写、字间距、字重）
- 活跃/悬停状态指示器（下划线、颜色、背景）
- 移动端行为（汉堡菜单、底部导航、抽屉）
输入与表单：
- 边框样式和焦点状态行为
- 圆角样式与按钮的一致性
- 内边距和触摸目标尺寸
领域特定组件：
- 识别 1-2 个此项目独有的组件（例如产品卡片、仪表板小部件、聊天气泡），并描述其样式模式。
5. 布局原则
提取结构系统：
网格与结构：
- 最大内容宽度（来自容器上的
max-width） - 列系统（CSS Grid、Flexbox 模式、定义的断点）
- 响应式断点（来自媒体查询或 Tailwind 配置）
空白策略：
- 基本间距单位（8px 网格？4px？自定义？）
- 部分边距（主要部分之间的间距大小）
- 边缘内边距（不同断点处的页面边距）
对齐与视觉平衡：
- 文本对齐模式（居中英雄区、左对齐正文）
- 图像与文本的比例
- 视觉重量分布
响应式行为：
- 移动优先还是桌面优先？
- 网格如何折叠？内边距比例？
- 触摸目标尺寸
6. Stitch 生成笔记
将提取结果综合为可操作的 Stitch 提示：
- 氛围语言：将基调转换为自然描述符
- 颜色参考：按描述性名称 + 十六进制值列出颜色
- 组件提示：编写 2-3 个示例提示，用于在 Stitch 中重建关键组件
- 迭代指导：在此设计系统中优化屏幕的提示
第三阶段：编写 DESIGN.md
将所有内容整合到标准的 DESIGN.md 格式中。将其放在项目目录下的 .stitch/DESIGN.md（如果 .stitch/ 目录不存在，则创建它）。
[!IMPORTANT] 你必须在文件顶部包含带有
name和colors映射的 YAML 前导元数据，完全按照 examples/DESIGN.md 中的示例所示。此结构化数据是其他技能解析设计系统所必需的。未能包含此至少包含核心颜色令牌的 YAML 块意味着未能正确使用此技能。
使用 examples/DESIGN.md 中的示例作为模板。文件必须以 YAML 块开头，后跟 Markdown 部分：
# 设计系统：[项目名称]
**项目 ID：** [如果已知，否则省略]
## 1. 视觉主题与氛围
[关于基调、哲学和关键特征的 2 段丰富描述]
## 2. 调色板与角色
### 主要基础
### 强调与交互
### 排版与文本层次
### 功能状态
## 3. 排版规则
### 层次与字重
### 间距原则
## 4. 组件样式
### 按钮
### 卡片与[领域特定容器]
### 导航
### 输入与表单
### [领域特定组件]
## 5. 布局原则
### 网格与结构
### 空白策略
### 对齐与视觉平衡
### 响应式行为与触摸
## 6. 用于 Stitch 生成的设计系统笔记
### 要使用的语言
### 颜色参考
### 组件提示
### 增量迭代
第四阶段：集成（可选）
如果用户希望将设计系统推送到 Stitch：
- 将任务移交给
manage-design-system技能，用于 MCP 创建/更新调用 - 你编写的 DESIGN.md 是输入——
manage-design-system技能处理 Stitch API 集成
如果用户只需要文档，则在第三阶段后完成。
质量检查清单
在交付 DESIGN.md 之前，验证：
- 每种颜色都有描述性名称、十六进制代码和功能角色
- 排版包括字体系列、特征描述和完整层次
- 组件样式描述了形状、颜色、状态和过渡
- 布局包括最大宽度、网格、断点和间距策略
- Stitch 生成笔记使用自然语言，而不是 CSS 语法
- 氛围部分读起来像编辑文案，而不是技术文档
- 接近重复的颜色已合并
- 文档捕获了样式背后的意图，而不仅仅是原始值
更好的提取技巧
- 阅读注释和提交信息。 开发人员经常在代码注释（
/* 英雄区域 — 透气 */）和提交信息中记录设计意图。这些是理解为什么的宝贵资料。 - 检查设计令牌库。 如果项目使用
style-dictionary、@tokens-studio或类似工具，这些文件是设计值最权威的来源。 - 主题文件比组件样式信号更强。 定义了调色板的
theme.ts告诉你预期的设计系统；组件中分散的内联样式告诉你实际发布的内容。两者都很重要，但要从主题开始。 - Tailwind 配置是一个设计系统。 如果项目有自定义的
tailwind.config.js，那就是设计系统——首先从中提取，然后抽查组件是否存在覆盖。 - CSS 自定义属性是有意为之的。 如果开发者定义了
--brand-primary，他们是在告诉你这是一个设计令牌。请尊重这一点。