stitch::extract-design-md

从前端代码中提取设计系统

分析前端源代码，提取一份全面的设计系统文档（DESIGN.md），直接从源文件中总结项目的视觉语言——颜色、字体排版、间距、组件模式和布局原则，无需构建或渲染应用。

为什么需要它

design-md 技能基于渲染后的 HTML 工作。但很多时候，你手头有一个代码库，想在运行应用之前了解它的设计系统——也许缺少依赖、构建失败，或者你只是想快速审查一下。此技能会读取源文件本身：样式表、组件文件、主题配置和 Tailwind 设置。它速度更快，也能在任何环境中使用。

使用时机

• 用户有一个前端代码库，希望提取或记录其设计系统
• 用户想将项目的视觉形象迁移到 Stitch
• 用户要求“审查样式”或“了解”代码库的“设计语言”
• 用户想根据现有源代码创建 DESIGN.md
• 应用无法构建或渲染，但源代码可用
• 用户想统一或协调代码库中不一致的样式

前置条件

• 可访问前端项目的源代码目录
• 无需构建或运行时依赖——此技能仅读取源文件

---

工作流

阶段 1：项目发现

首先了解你要处理的项目。这将决定要使用哪些提取模式。

1. 检测框架和技术栈

扫描项目根目录，查找以下特征文件：

特征文件	框架 / 工具
含有 react 的 package.json	React / Next.js
含有 vue 的 package.json	Vue / Nuxt
含有 svelte 的 package.json	Svelte / SvelteKit
含有 @angular/core 的 package.json	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/     ← Component-level styles
├── styles/         ← Global stylesheets
├── theme/          ← Theme definitions, tokens
├── assets/         ← Fonts, images
├── app.css         ← Root styles
└── index.css       ← Entry 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

这些参考文档包含了用于定位颜色、字体排版、间距和组件样式的框架专属模式。继续之前，请阅读与你的项目匹配的文档。

---

阶段 2：深入提取

系统地梳理每个设计维度。针对每个维度，先从源文件中收集原始数据，再将其归纳为描述性语言。

目标不是罗列每一条 CSS 属性，而是理解样式选择背后的意图，并用自然、具有编辑感的语言加以描述，让其他设计师（或 Stitch）能够据此还原相同的视觉感受。

1. 视觉主题与氛围

先阅读整体样式，了解总体氛围：

• 根背景：body 或根元素的背景是什么？浅色 奶油色（#f-range）给人轻盈、清爽的感觉；深色（#0-#2 范围）则营造出忧郁、戏剧化的氛围。
• 留白理念：间距值是宽松（32px 以上）还是紧凑？ 检查根容器、区块包装器和卡片组件上的内边距和外边距值。
• 密度：统计每个页面／区块中的组件数量。组件少、留白多 = 极简； 组件多且排列紧密 = 信息密集。
• 色温：中性色是偏暖（奶油色、棕褐色）还是偏冷（蓝灰色、石板色）？
• 整体观感：用 1-2 句丰富的描述概括整体氛围。

在源代码中查找以下信号：

源代码位置	可以说明什么
布局中的根 background-color 或 Tailwind bg-*	整体明暗程度
Tailwind 配置或 CSS 变量中的间距比例	留白理念
组件数量与包装器内边距的对比	密度
自定义属性命名（--warm-* 与 --cool-*）	色温意图
主题文件中的注释	开发者亲自描述的设计意图

2. 配色方案与用途

从代码库中提取所有独特颜色，并为它们指定用途。 搜索所有层级：

查找颜色的位置：

层级	搜索内容
CSS 自定义属性	--color-*、--primary、--bg-*
Tailwind 配置	theme.extend.colors
主题／设计令牌文件	颜色对象、调色板
组件样式	background-color、color、border-color
内联／局部样式	模板中的 bg-*、text-* 类
CSS-in-JS 主题对象	colors、palette 键

**组织方式：**按用途而非色相对颜色分组：

1. 基础主色 — 背景和表面颜色
2. 强调色与交互色 — CTA 按钮、激活状态、链接
3. 字体与文本层级 — 主要、次要、辅助文本
4. 功能状态 — 成功、错误、警告、信息

为每种颜色取一个能体现其特征的描述性名称，而不是直接使用其十六进制值：

• ❌ #294056 → “蓝色”
• ✅ #294056 → “深沉柔和的蓝绿海军蓝” — 主要 CTA、激活的导航项

去重很重要。代码库中常有非常相近的颜色（例如， #333 和 #2C2C2C）。将它们归并到一个最能体现其设计意图的名称下。

3. 字体排版规则

提取完整的字体排版系统：

字体系列：

• 检查 CSS font-family、Tailwind fontFamily、Google Fonts 链接或 本地 @font-face 声明。
• 说明每种字体的特征：几何风格还是人文风格，衬线还是无衬线， 能带来怎样的感受。

字号比例（层级）：

• 找出每个标题级别（H1-H6）和正文文本，并记录：
  • font-size（以 rem 或 px 为单位）
  • font-weight（数值 + 描述性名称）
  • letter-spacing（以及原因——优雅？紧凑？）
  • line-height（为提升可读性而宽松？为展示效果而紧凑？）
• 映射组件用途：产品卡片使用哪个标题级别？主视觉区块呢？

间距原则：

• 文本间距与整体间距比例有什么关系？
• 标题与正文的字间距模式
• 行高理念（正文宽松／舒展，展示文本更紧凑）

4. 组件样式

分析 4–5 个最重要的 UI 原语：

按钮：

• 圆角半径（以及传达的感觉——活泼？专业？简约？）
• 主按钮、次要按钮和幽灵按钮变体的配色方案
• 悬停／焦点／激活状态及过渡时长
• 内边距比例（水平与垂直方向）

卡片／容器：

• 圆角半径（通常与按钮不同，略圆一些）
• 阴影策略：无阴影、悬停时添加细微阴影，还是始终呈现悬浮效果？
• 边框处理：极细边框、彩色点缀，还是不使用边框？
• 内部边距（宽松还是紧凑？）
• 卡片内的图片处理方式（铺满、留白、圆角？）

导航：

• 布局模式（水平栏、垂直侧边栏、抽屉）
• 字体样式（大写、字间距、字重）
• 激活／悬停状态指示（下划线、颜色、背景）
• 移动端行为（汉堡菜单、底部导航、抽屉）

输入框与表单：

• 边框样式和焦点状态行为
• 圆角风格与按钮的一致性
• 内边距和触控目标尺寸

领域专属组件：

• 指出 1–2 个项目特有的组件（例如产品卡片、仪表盘小组件、聊天气泡），并描述其样式模式。

5. 布局原则

提取结构系统：

网格与结构：

• 内容最大宽度（取自容器上的 max-width）
• 列系统（CSS Grid、Flexbox 模式、定义的断点）
• 响应式断点（取自媒体查询或 Tailwind 配置）

留白策略：

• 基础间距单位（8px 网格？4px？自定义？）
• 区块间距（主要区块之间留多少空间）
• 边缘留白（不同断点下的页面边距）

对齐与视觉平衡：

• 文本对齐模式（居中的首屏区域、左对齐的正文）
• 图片与文本的比例
• 视觉重量的分布

响应式行为：

• 移动端优先还是桌面端优先？
• 网格如何折叠？内边距如何缩放？
• 触控目标尺寸

6. Stitch 生成说明

将提取结果综合为可用于 Stitch 的具体提示词：

• 氛围描述：将整体感觉转化为自然的描述词
• 颜色参考：按描述性名称 + 十六进制值列出颜色
• 组件提示词：编写 2–3 条示例提示词，用于在 Stitch 中复现关键组件
• 迭代建议：提供在此设计系统中优化屏幕的技巧

---

阶段 3：编写 DESIGN.md

将所有内容整理为标准的 DESIGN.md 格式。将其放在项目目录下的 .stitch/DESIGN.md（如果 .stitch/ 目录不存在，则创建该目录）。

重要

你 MUST 在文件顶部包含 YAML frontmatter，其中包含 name 和 colors 映射，格式必须与示例 examples/DESIGN.md 完全一致。其他技能需要解析此结构化数据。

如果未包含至少含有核心颜色令牌的 YAML 块，即未正确使用此技能。

使用示例 examples/DESIGN.md 中的格式作为模板。文件必须以 YAML 块开头，后接 Markdown 章节：

# Design System: [Project Name]
**Project ID:** [If known, otherwise omit]

## 1. Visual Theme & Atmosphere
[Rich 2-paragraph description of mood, philosophy, and key characteristics]

## 2. Color Palette & Roles
### Primary Foundation
### Accent & Interactive
### Typography & Text Hierarchy
### Functional States

## 3. Typography Rules
### Hierarchy & Weights
### Spacing Principles

## 4. Component Stylings
### Buttons
### Cards & [Domain-Specific Containers]
### Navigation
### Inputs & Forms
### [Domain-Specific Components]

## 5. Layout Principles
### Grid & Structure
### Whitespace Strategy
### Alignment & Visual Balance
### Responsive Behavior & Touch

## 6. Design System Notes for Stitch Generation
### Language to Use
### Color References
### Component Prompts
### Incremental Iteration

---

阶段 4：集成（可选）

如果用户希望将设计系统推送到 Stitch：

1. 将任务交接给 manage-design-system 技能，以执行 MCP 创建／更新调用
2. 你编写的 DESIGN.md 是输入内容——manage-design-system 技能负责处理 Stitch API 集成

如果用户只需要文档，则完成阶段 3 后即可结束。

---

质量检查清单

交付 DESIGN.md 前，请确认：

• 每种颜色都有描述性名称、十六进制代码和功能角色
• 排版内容包含字体系列、字符描述和完整层级
• 组件样式说明了形状、颜色、状态和过渡效果
• 布局包含最大宽度、网格、断点和间距策略
• Stitch 生成说明使用自然语言，而非 CSS 语法
• 氛围部分读起来像编辑文案，而非技术文档
• 已合并近似重复的颜色
• 文档捕捉了样式背后的意图，而不只是原始数值

更好地提取信息的技巧

• 阅读注释和提交消息。 开发者通常会在代码注释（/* hero section — breathable */）和提交消息中记录设计意图。这些信息有助于理解原因。
• 检查设计令牌库。 如果项目使用 style-dictionary、@tokens-studio 或类似工具，这些文件是最权威的设计值来源。
• 主题文件比组件样式更能反映设计意图。 定义调色板的 theme.ts 能告诉你预期的设计系统；组件中零散的内联样式则能告诉你实际交付的内容。两者都很重要，但应从主题文件入手。
• Tailwind 配置就是设计系统。 如果项目有自定义的 tailwind.config.js，它就是设计系统——先从中提取信息，再抽查组件是否有覆盖项。
• CSS 自定义属性是有意定义的。 如果开发者定义了 --brand-primary，他们是在告诉你这是一个设计令牌。请予以保留。