企业官网建设流程全解析

• AI 技能
• AI 插件

本文围绕 stitch-skills 仓库中stitch::extract-design-md技能（SKILL.md）展开，讲解如何在不构建、不渲染应用的前提下，直接从 React、Vue、Svelte、Angular、纯 HTML/CSS 等前端源码中分析出完整的设计系统（颜色、排版、间距、组件模式、布局原则），并产出 Stitch 可解析的DESIGN.md文档。读完本文，你将掌握完整的三阶段提取工作流、六维深度分析方法、DESIGN.md的 YAML frontmatter 与正文结构规范，以及如何将该文档进一步接入manage-design-system技能同步进 Stitch。

Skill 定位：为什么需要从源码提取设计系统

仓库中的另一个技能design-md（见 plugins/stitch-utilities/skills/design-md/SKILL.md）基于渲染后的 HTML工作：它通过 Stitch MCP Server 拉取已设计屏幕的截图与 HTML 源码来合成语义化设计系统。但实践中常常存在如下处境：

• 依赖缺失、构建失败，应用根本无法运行；
• 只想快速审计某个前端仓库的视觉语言，不必启动项目；
• 需要把既有项目的视觉身份迁移到 Stitch；
• 需要统一或调和代码库中不一致的样式。

extract-design-md正是为这些场景设计：它直接读取源文件本身——样式表、组件文件、主题配置、Tailwind 配置——而非渲染产物。因此它更快、更轻，且几乎不受环境限制，是design-md渲染路线的互补方案。

从技能元数据（SKILL.md）可以看到，该技能声明了name: stitch::extract-design-md，允许使用stitch*:*（Stitch MCP 工具）、Bash、Read、Write、web_fetch等工具，说明它既能纯本地读取源码，也具备与 Stitch 服务联动的能力。

适用场景与前置条件

何时使用

以下任一需求出现时，都应优先调用本技能：

• 用户持有前端代码库，希望提取或记录其设计系统；
• 用户想把项目视觉身份迁移进 Stitch；
• 用户要求"审计样式"或"理解代码库的设计语言"；
• 用户希望从现有源码创建DESIGN.md；
• 应用无法构建/渲染，但源码可用；
• 用户希望统一或调和代码库中不一致的样式。

用户甚至只需要说一句"这个应用长什么样？"或"从这段代码里把设计抽出来"，就足以触发本技能。

前置条件

• 能够访问前端项目的源码目录；
• 不需要任何构建或运行时依赖——本技能只读取源文件，这使其在 CI 审计、只读仓库、离线环境等场景下依然可用。

Phase 1：项目发现（Project Discovery）

提取工作的第一步是搞清楚"面对的是什么技术栈"，这决定了后续使用哪套提取模式。

1. 检测框架与工具链

扫描项目根目录的特征文件，快速定位框架与样式工具：

务必先读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

这些参考文档包含定位颜色、排版、间距与组件样式的框架特有模式。以 React 栈为例，react-tailwind.md 给出的文件读取优先级是：tailwind.config.js/ts（最重要，自定义theme.extend即设计系统定义）→globals.css/index.css（CSS 自定义属性与@font-face）→theme.ts/tokens.ts（显式令牌）→ 根布局文件（全局字体与背景）→ 5~8 个代表性组件。其核心思想是"优先级越高的文件越代表设计意图，优先级越低越接近实际交付物"。

Phase 2：深度提取（Deep Extraction）

这是整个技能的核心阶段。逐维度系统化地处理每个设计维度：先从源文件中收集原始数据，再将其综合为描述性语言。

目标不是倾倒每一个 CSS 属性，而是理解样式选择背后的意图，并用人工编辑式的语言加以描述，使另一位设计师（或 Stitch）能据此复刻同样的视觉感受。

1. 视觉主题与氛围（Visual Theme & Atmosphere）

先读最宏观的样式以把握整体基调：

• 根背景：body或根元素背景是什么？浅奶油色（#f区间）暗示轻盈/干净；深色（#0–#2区间）暗示忧郁/戏剧性；
• 留白哲学：间距值是否慷慨（32px+）还是紧凑？检查根容器、区块包裹器与卡片组件的 padding/margin；
• 密度：统计每页/每区块的组件数量。少而疏 = 极简；多而密 = 信息密集；
• 色温：中性色偏暖（奶油、棕褐）还是偏冷（蓝灰、石板灰）？
• 整体感受：综合成 1~2 句丰富的句子，捕捉其情绪基调。

在源码中寻找这些信号：

2. 调色板与角色（Color Palette & Roles）

从代码库提取每一个独特颜色，并赋予功能角色。需要在所有层中搜索：

颜色来源：

按功能而非色相分组：

1. Primary Foundation（主要基底）—— 背景与表面颜色
2. Accent & Interactive（强调与交互）—— CTA 按钮、激活态、链接
3. Typography & Text Hierarchy（排版与文本层级）—— 一级、二级、三级文本
4. Functional States（功能状态）—— 成功、错误、警告、信息

为每个颜色创建能唤起其性格的描述性名称，而非生硬的十六进制值：

• ❌#294056→ "Blue"
• ✅#294056→"Deep Muted Teal-Navy"—— Primary CTA，激活导航

去重至关重要。代码库往往存在近重复颜色（如#333与#2C2C2C），应将它们合并到最能代表意图的单一名称之下。

对于没有显式令牌系统的项目，plain-css.md 建议对所有样式表搜索background-color:、background:、color:、border-color:、box-shadow:、fill:、stroke:等属性，收集全部hex、rgb()、rgba()、hsl()值，再按色相近邻分组、依据选择器上下文分配角色。

3. 排版规则（Typography Rules）

提取完整的排版系统：

字体族：

• 检查 CSSfont-family、TailwindfontFamily、Google Fonts 链接或本地@font-face声明；
• 记录每种字体的性格：几何还是人文主义、衬线还是无衬线、唤起何种感觉。

字号刻度（层级）：

• 找出每个标题层级（H1-H6）与正文，记录：
  • font-size（rem 或 px）
  • font-weight（数值 + 描述性名称）
  • letter-spacing（以及为什么——优雅？紧凑？）
  • line-height（为可读性而宽松？为展示而紧凑？）
• 映射组件用法：产品卡片用哪个标题层级？Hero 区块呢？

间距原则：

• 文本间距如何与整体间距刻度关联？
• 标题与正文的 letter-spacing 模式差异；
• line-height 哲学（正文宽松放松、展示紧凑）。

4. 组件样式（Component Stylings）

分析 4~5 个最重要的 UI 基元：

按钮（Buttons）：

• 圆角（传达什么——俏皮？专业？极简？）；
• primary、secondary、ghost 变体的配色方案；
• hover/focus/active 状态与过渡时长；
• padding 比例（水平 vs 垂直）。

卡片 / 容器（Cards / Containers）：

• 圆角（常与按钮不同——略圆）；
• 阴影策略：扁平、微妙的 hover 阴影、或常驻悬浮；
• 边框处理：发丝线边框、彩色强调线、或没有；
• 内部 padding（慷慨还是紧凑？）；
• 卡片内图片处理（全出血、留边、圆角？）。

导航（Navigation）：

• 布局模式（水平栏、垂直侧栏、抽屉）；
• 排版处理（大写、letter-spacing、字重）；
• 激活/悬停状态指示（下划线、颜色、背景）；
• 移动端行为（汉堡菜单、底部导航、抽屉）。

输入与表单（Inputs & Forms）：

• 边框样式与焦点行为；
• 与按钮的圆角一致性；
• padding 与触控目标尺寸。

领域专属组件（Domain-Specific Components）：

• 识别 1~2 个本项目特有的组件（如产品卡片、仪表盘组件、聊天气泡），并描述其样式模式。

5. 布局原则（Layout Principles）

提取结构系统：

网格与结构（Grid & Structure）：

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

留白策略（Whitespace Strategy）：

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

对齐与视觉平衡（Alignment & Visual Balance）：

• 文本对齐模式（居中 Hero、左对齐正文）；
• 图片与文字比例；
• 视觉重量分布。

响应式行为（Responsive Behavior）：

• 移动优先还是桌面优先？
• 网格如何折叠？padding 刻度如何变化？
• 触控目标尺寸。

6. Stitch 生成备注（Stitch Generation Notes）

将提取结果综合成可供 Stitch 直接使用的提示词材料：

• 氛围语言（Atmosphere language）：把情绪基调翻译为自然语言描述词；
• 颜色引用（Color references）：以"描述名 + 十六进制"形式列出颜色；
• 组件提示词（Component prompts）：写出 2~3 个可在 Stitch 中复刻关键组件的示例提示词；
• 迭代指引（Iteration guidance）：在此设计系统内优化屏幕的技巧。

这一维度与design-md技能的理念一脉相承：Stitch 通过"视觉描述 + 具体色值"来理解设计（见 design-md/SKILL.md），因此提取结果必须从技术数值转化为设计师友好、自然语言的表达，例如把rounded-full描述为"Pill-shaped（药丸形）"、把rounded-lg描述为"Subtly rounded corners（微圆角）"。

Phase 3：撰写 DESIGN.md

将所有内容组装进标准的DESIGN.md格式，放置于项目目录的.stitch/DESIGN.md（若.stitch/目录不存在则创建）。

[!IMPORTANT]必须在文件顶部包含带name与colors映射的 YAML frontmatter，格式与 examples/DESIGN.md 中的示例完全一致。这份结构化数据是其他技能解析设计系统所必需的。

未能包含至少核心颜色令牌的 YAML 块，即视为未正确使用本技能。

以 examples/DESIGN.md 为模板，文件必须以 YAML 块开头，随后是 markdown 章节：

# Design System: [Project Name] **Project ID:** [如已知，否则省略] ## 1. Visual Theme & Atmosphere [2 段式丰富描述：情绪基调、哲学、关键特征] ## 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

YAML frontmatter 结构解析

仓库自带的 examples/DESIGN.md（一个滑雪主题 "Alpine Peak" 设计系统）展示了完整的 frontmatter 骨架，可分为四组结构化数据：

1.colors（颜色令牌）：采用 Material Design 3 风格的完整语义色阶，包括：

• 表面体系：surface、surface-dim、surface-bright、surface-container-lowest~container-highest、surface-variant；
• 文本/轮廓：on-surface、on-surface-variant、outline、outline-variant、inverse-surface、inverse-on-surface、surface-tint；
• 主/次/第三角色：primary、on-primary、primary-container、on-primary-container、inverse-primary、secondary系列、tertiary系列；
• 固定态：primary-fixed、primary-fixed-dim、on-primary-fixed、on-primary-fixed-variant（secondary/tertiary 同理）；
• 错误与背景：error、on-error、error-container、on-error-container、background、on-background。

2.typography（排版令牌）：每个命名字体样式都带fontFamily、fontSize、fontWeight、lineHeight、letterSpacing五个字段，例如：

display-lg: fontFamily: Inter fontSize: 48px fontWeight: '800' lineHeight: 56px letterSpacing: -0.02em

3.rounded（圆角刻度）：sm: 0.25rem、DEFAULT: 0.5rem、md: 0.75rem、lg: 1rem、xl: 1.5rem、full: 9999px。

4.spacing（间距刻度）：以unit: 4px为基准，xs: 4px、sm: 8px、md: 16px、lg: 24px、xl: 32px，外加gutter: 16px、margin-mobile: 20px、margin-desktop: 40px。

正文部分则完全使用编辑式语言：该示例把深蓝命名为"Deep Peak Blue"、把主画布命名为"Powder White"，用 Glassmorphism、High-Contrast 等自然语言描述氛围与深度，用"最小 48x48px 触控目标（适配戴手套的用户）"描述可访问性决策——这正是"捕捉意图而非原始数值"的范本。

Phase 4：可选集成（Integration）

如果用户希望把设计系统推入 Stitch：

1. 转交给manage-design-system技能执行 MCP 的 create/update 调用；
2. 你写出的DESIGN.md就是输入——manage-design-system/SKILL.md 负责 Stitch API 集成。

若用户只需要文档本身，完成 Phase 3 即告结束。

从 manage-design-system/SKILL.md 的源码可以看出后续链路：通过upload-to-stitchPython 脚本（base64 编码.md文件，绕过输出 token 上限）上传到/v1/projects/{projectId}/screens:batchCreate，再调用create_design_system_from_design_md在项目级建立设计令牌；之后生成屏幕时无需在提示词中重复颜色/字体/圆角——Stitch 已在项目层持有这些令牌。这印证了DESIGN.md的 YAML frontmatter 是整条设计系统管线的数据基石。

质量检查清单（Quality Checklist）

交付DESIGN.md前逐项核验：

• 每个颜色都有描述性名称、十六进制代码与功能角色
• 排版包含字体族、字体性格描述与完整层级
• 组件样式描述形状、颜色、状态与过渡
• 布局包含 max-width、网格、断点与间距策略
• Stitch 生成备注使用自然语言而非 CSS 语法
• 氛围章节读起来像编辑文案而非技术文档
• 近重复颜色已合并
• 文档捕捉的是样式背后的意图，而非原始数值

更优提取的实用技巧（Tips for Better Extraction）

• 阅读注释与提交信息。开发者常在代码注释中记录设计意图（/* hero section — breathable */），提交信息同样如此。它们是理解"为什么"的金矿。
• 检查设计令牌库。若项目使用style-dictionary、@tokens-studio等，这些文件是设计数值的最权威来源。
• 主题文件比组件样式信号更强。定义调色板的theme.ts告诉你意图中的设计系统；组件中零散的内联样式告诉你实际交付的样式。两者都重要，但从主题入手。
• Tailwind 配置本身就是设计系统。如果项目有定制过的tailwind.config.js，那就是设计系统——先从中提取，再抽查组件找覆盖项。
• CSS 自定义属性是有意为之。开发者定义了--brand-primary，就是在告诉你这是设计令牌。请尊重它。

与其他技能的分工协作

在stitch-design插件（plugin.json）的生态中，extract-design-md与相邻技能形成了清晰的分工：

• design-md（plugins/stitch-utilities/skills/design-md/SKILL.md）：面向 Stitch 项目内已渲染屏幕，通过 MCP 拉取截图与 HTML 合成语义设计系统——"从成品反推"；
• extract-design-md（本技能）：面向任意前端源码仓库，纯静态读取——"从原料提炼"，覆盖design-md无法工作的场景（无渲染、无构建、纯审计）；
• manage-design-system（manage-design-system/SKILL.md）：消费两者产出的DESIGN.md，完成上传、建系统、应用到屏幕的 MCP 操作。

两条提取路线的产物都遵循同一DESIGN.md结构规范，因此无论设计系统来自"已渲染屏幕"还是"纯源码"，下游的 Stitch 集成链路完全一致。选择哪条路线只取决于你手上有什么：能跑的项目给design-md，只有代码的项目给extract-design-md。

• AI 技能
• AI 插件