Stitch 语义化设计系统文档实战：解析 Alpine Peak DESIGN.md 标准模板

DESIGN.md 是 Stitch 设计工作流中的"唯一事实来源"（source of truth）：它把一套完整的视觉语言——色彩、字体、间距、形状、组件与布局原则——以"YAML 设计令牌 + 语义化 Markdown 描述"的形式固化下来，供 Stitch 在生成新画面时对齐既有设计语言。本文以 stitch-skills 仓库中 extract-design-md skill 提供的 Alpine Peak 示例文档为骨架，逐层拆解这份标准模板的每一处结构、令牌含义与编写意图，并结合 extract-design-md、design-md 与 manage-design-system 的源码级说明，让你既能读懂这份模板，也能照着它为自己的前端项目产出、校验并上传设计系统。

一、DESIGN.md 是什么：为 Stitch 提供"设计语言说明书"

在 Stitch 的工作方式里，生成新画面靠的是"视觉描述 + 具体色值"的组合：自然语言描述画面的情绪、形状、层级，精确的十六进制色值锁定色彩细节。而 DESIGN.md 就是把这两者装进同一份文件的标准格式——前半部分是机器可读的 YAML frontmatter（设计令牌），后半部分是设计师/开发者可读的 Markdown 语义描述。

仓库中生成 DESIGN.md 有两条路径，输出格式完全一致：

路径	Skill	输入来源
从源码逆向	extract-design-md	前端源码文件（样式表、组件、主题配置、Tailwind 配置），无需构建或运行应用
从渲染产物逆向	design-md	Stitch 项目中已渲染屏幕的 HTML 代码与截图

Alpine Peak 示例正是 extract-design-md 路径的产物模板，位于 examples/DESIGN.md。它的对象是一个高山滑雪导航应用：品牌个性是"高性能、精致、可靠"，视觉语言用 Glassmorphism（玻璃拟态）营造"冻结"质感，并用高对比度保证雪地强光下的可读性。

一份合格的 DESIGN.md 由两部分构成：

1. YAML frontmatter：name + colors 映射是强制要求，extract-design-md 的 SKILL.md 明确说明：缺少至少核心色彩令牌的 YAML 块，就是没有正确使用该 skill；这份结构化数据是其他 skill 解析设计系统的入口。
2. Markdown 正文：按 "Visual Theme → Colors → Typography → Components → Layout → Stitch 生成笔记" 的固定骨架组织，语言必须是设计术语与自然语言，而不是 CSS 语法。

二、YAML Frontmatter：机器可读的设计令牌层

Alpine Peak 的 frontmatter 是整个文档的"数据层"，定义了三类令牌：色彩、字体样式、圆角与间距。它们是后续 create_design_system_from_design_md 等 MCP 工具解析的输入——tool-schema.md 指出，该方法会直接从上传的 DESIGN.md 解析出的 YAML frontmatter 自动填充并更新全部主题令牌。

2.1 colors：Material 3 风格的全量角色令牌

frontmatter 中的 colors 映射使用 Material Design 3 的令牌命名体系，覆盖了明暗表面、容器、反向、错误与固定色等完整角色。Alpine Peak 示例中值得注意的令牌结构：

令牌分组	示例键	示例值	语义
表面层级	surface / surface-dim / surface-bright	#fcf8fa / #dcd9db / #fcf8fa	基础表面及其明暗变体
表面容器	surface-container-lowest … surface-container-highest	#ffffff … #e4e2e4	5 级容器灰度，用于卡片、抽屉等
其上文字	on-surface / on-surface-variant	#1b1b1d / #45464d	表面上的主/次文字色
主次强调	primary / secondary / tertiary	#000000 / #5c5f61 / #000000	品牌强调色三元组
容器色	primary-container / on-primary-container	#131b2e / #7c839b	强调色的容器与容器内文字
反向与描边	inverse-surface / outline / outline-variant	#303032 / #76777d / #c6c6cd	反向表面、描边与描边变体
功能态	error / error-container / on-error-container	#ba1a1a / #ffdad6 / #93000a	错误状态全链路
固定色	primary-fixed / primary-fixed-dim / on-primary-fixed	#dae2fd / #bec6e0 / #131b2e	固定色与变体，供深色容器使用

从提取方法论看，这些令牌正是 extract-design-md 在 "Color Palette & Roles" 阶段要按功能（而非色相）归类的对象：主基础（背景/表面）、强调与交互（CTA/激活态/链接）、文字层级、功能状态。文档中每个角色都要有一个描述性名称 + 十六进制值 + 功能角色，例如把 #294056 命名为 "Deep Muted Teal-Navy — Primary CTA" 而不是笼统地叫 "Blue"。

2.2 typography：文本样式令牌

frontmatter 的 typography 定义了一套完整的文本样式表，每个样式包含 fontFamily、fontSize、fontWeight、lineHeight、letterSpacing 五个字段。Alpine Peak 共定义了 6 个样式层级：

样式键	字体	字号	字重	行高	字距	用途
display-lg	Inter	48px	800	56px	-0.02em	大屏展示标题
headline-md	Inter	24px	700	32px	-0.01em	中等标题
body-base	Inter	16px	400	24px	0	正文
body-bold	Inter	16px	600	24px	0	强调正文
label-caps	Lexend	12px	700	16px	0.05em	全大写标签
stat-lg	Lexend	32px	600	40px	-0.02em	速度/落差等数据

注意 letterSpacing 的细节：display-lg 用紧排负字距营造力量感，label-caps 用 +0.05em 的宽松字距增强全大写标签的可读性——这正是 design-md skill 所强调的"描述字距的性格（优雅？紧凑？）"。

2.3 rounded 与 spacing：几何与节奏令牌

rounded:
  sm: 0.25rem
  DEFAULT: 0.5rem
  md: 0.75rem
  lg: 1rem
  xl: 1.5rem
  full: 9999px
spacing:
  unit: 4px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
  gutter: 16px
  margin-mobile: 20px
  margin-desktop: 40px

圆角令牌从 0.25rem（sm）到 1rem（lg）、1.5rem（xl），再到全圆 9999px（pill 形状），与正文中"按钮/芯片用 rounded-lg 或 rounded-xl，小状态指示器用 pill 形状"的描述一一对应。间距令牌则建立在 4px 基础单元上，gutter（16px）、margin-mobile（20px）、margin-desktop（40px）分别定义了栅格槽宽与移动端/桌面端页面边距，为后文的 Fluid Grid 与响应式策略提供了数据支撑。

三、Brand & Style：把情绪转译为可执行的视觉语言

Alpine Peak 的 Brand & Style 段落给出了整份文档的"灵魂"：

品牌个性是高绩效、精致、可靠的，为在严苛环境中追求清晰与精确的现代滑雪者而设计；视觉语言既唤起山峰的晶体之美，又优先考虑户外导航所需的粗粝实用性。设计系统采用 Glassmorphism 达成"冻结"美学，模仿冰与压实雪的特性；搭配 High-Contrast 高对比哲学，确保步道状态、天气警报等关键数据在强烈山光或暴风雪低能见度下依然清晰可读。

这一段的作用是定义"氛围基调"。在提取方法论中，它对应的是 extract-design-md SKILL.md 里 "Visual Theme & Atmosphere" 阶段的产出要求：从根背景色（浅奶油色系暗示清爽，深色系暗示戏剧感）、留白哲学、信息密度、色温（暖奶油 vs 冷蓝灰）等信号综合出 1～2 句富有画面感的总结。design-md skill 同样要求用富有感染力的形容词（Airy、Dense、Minimalist、Utilitarian）捕捉整体氛围。

质量检查清单里对应有一条硬性标准："氛围段落读起来像编辑文案，而不是技术文档"——这就是为什么 Alpine Peak 用 "crystalline beauty"、"rugged utility" 这类措辞，而不是罗列 CSS 属性。

四、Colors：从令牌到角色命名

Colors 段落把 frontmatter 里的令牌翻译成有名字、有职责的色彩角色：

• Deep Peak Blue（深峰蓝）——深海军蓝，为白字与地图提供锚定对比；
• Powder White（粉雪白）——主画布色，让界面显得通透清冷；
• Safety Orange（安全橙）——严格保留给主要行动召唤、危险警告与紧急雪道关闭，保证视线即时锁定；
• Electric Blue（电光蓝，info 状态）——用于天气更新与常规交互；
• 雪道难度色——沿用行业标准的绿/蓝/黑，但以高饱和渲染，使其在白底上"跳"出来。

这套命名方式完整体现了两个提取原则：

1. 按功能角色命名而非按色相命名：#000000 被命名为 "Deep Peak Blue" 而非 "Black"，#fcf8fa 被命名为 "Powder White" 而非 "White"，因为名字要传达的是该颜色在系统中的职责。
2. 强调色要"稀缺"：Safety Orange 的"严格保留"策略正是高对比设计系统的核心——警告色用得越少，出现时越有效。

同时，正文颜色描述必须能回溯到 frontmatter 的令牌值，保证"语义层"与"数据层"不脱节：例如正文中的 "Deep Peak Blue" 锚定 primary: '#000000' 与 primary-container: '#131b2e'，"Powder White" 对应 surface: '#fcf8fa'。

五、Typography：Inter + Lexend 双字体体系

Typography 段落解释了字体选型与使用哲学：

• Inter 用于核心功能文本与正文，因其出众的 x-height（小字号下依然易读）——display-lg、headline-md、body-base、body-bold 均使用 Inter；
• Lexend 用于标签与统计数据，其"超易读、运动感"的字形契合速度、垂直落差等滑雪数据的"活跃"属性——label-caps、stat-lg 均使用 Lexend；
• 为对抗户外眩光，字重整体重于常规 Web 应用：display 样式用紧排（tight tracking）与重字重传达力量感，标签始终使用与背景高对比的颜色。

这套双字体分工（功能文本 vs 数据展示）与 tool-schema.md 中设计系统 theme 的 headlineFont / bodyFont / labelFont 三个可独立配置的字体字段形成映射——在 Stitch 侧，标题、正文、标签可以分别指定字体（服务端已验证的枚举值包括 INTER、ROBOTO、OPEN_SANS、LATO、MONTSERRAT、NOTO_SANS、NOTO_SERIF、PLUS_JAKARTA_SANS、BE_VIETNAM_PRO）。

提取方法论中，这一阶段还要记录完整的层级：每个标题级别与正文的字号、字重、字距及其原因，并映射到组件使用场景（商品卡片用哪一级标题？Hero 用什么？）。

六、Layout & Spacing：Fluid Grid 与 4px/8px 基线

Layout & Spacing 段落定义了结构系统：

• Fluid Grid 模型，配以慷慨的安全区域（safe areas）；
• 严格 4px/8px 基线节奏保持纪律感、专业感——这与 frontmatter 中 unit: 4px、xs: 4px、sm: 8px 的间距令牌完全一致；
• 触控目标刻意放大（最小 48×48px），以适配戴手套的用户；
• 卡片与容器内边距保持宽松（lg 24px 或 xl 32px），避免展示复杂雪道数据时界面显得拥挤。

对应到 extract-design-md SKILL.md 的 "Layout Principles" 提取维度，需要从源码中找出：容器 max-width（内容最大宽度）、栅格系统（CSS Grid / Flexbox 与断点）、基础间距单元（8px 网格？4px？自定义？）、区块间距与不同断点下的页面边距、以及触控目标尺寸。Alpine Peak 中 margin-mobile: 20px 与 margin-desktop: 40px 正是"边缘内边距随断点变化"的令牌化表达。

七、Elevation & Depth：三层"堆叠冰"层级

Depth 通过 Glassmorphism 与背景滤镜（backdrop filter）传达，而非传统厚重阴影。文档定义了三级透明度层级：

1. Base Layer（基础层）：实色 'Powder White' 或 'Deep Peak Blue'；
2. Middle Layer（卡片/弹窗）：70% 透明度白色 + 20px 背景模糊 + 1px 'Ice' 边框（40% 透明度白）；
3. Top Layer（悬浮操作）：90% 透明度 + 微妙的 4px 环境阴影，将元素与模糊背景分离。

这形成"堆叠冰"（stacked ice）效果：视觉清晰的同时具备高级、现代感。这与 design-md skill 的 "Describe Depth & Elevation" 步骤要求一致——要描述 UI 如何分层，以及阴影的存在与质感（"Flat"、"Whisper-soft diffused shadows" 或 "Heavy, high-contrast drop shadows"），而 Alpine Peak 给出的是一套可执行的量化规则（透明度 + 模糊半径 + 边框透明度）。

八、Shapes：圆角语言

形状语言由现代、有机的圆角定义，用来柔化高对比色板、让应用更有亲和力：

• 按钮与芯片等交互元素使用 rounded-lg（1rem）或 rounded-xl（1.5rem），营造触觉化的"卵石"感；
• 地图覆盖层等大型容器使用 1rem 圆角；
• 雪道难度等小型状态指示器使用 pill 全圆形状，便于瞬间识别。

这也是 design-md skill 中 "Translate Geometry & Shape" 的典型示范：把技术值翻译成物理描述——rounded-full 译为 "Pill-shaped"、rounded-lg 译为 "Subtly rounded corners"、rounded-none 译为 "Sharp, squared-off edges"。在 Stitch 侧，圆角最终映射为 roundness 枚举：ROUND_FOUR、ROUND_EIGHT、ROUND_TWELVE、ROUND_FULL。

九、Components：从设计令牌到 UI 原语

Components 段落逐一规范了五个核心组件原语，是整份文档中"可直接落地"的部分：

Buttons（按钮）

主按钮使用实色 'Safety Orange' 或 'Deep Peak Blue' 填充 + 白字；次要操作使用高对比描边。所有按钮最小高度 52px（比通用触控标准 48px 更高），专为戴手套的手部操作设计。

Cards & Modals（卡片与弹窗）

沿用玻璃拟态：半透明背景 + 1px 白色边框，让底下的地图或照片保持隐约可见，维持"冻结"美学——对应 Elevation 中的 Middle Layer 参数。

Trail Status Chips（雪道状态芯片）

Pill 形状 + 高饱和图标。绿（初级 Easy）、蓝（中级 Intermediate）、黑（高级 Expert）、双黑（极限 Extreme）四档难度。必须同时带文本标签与图标，以兼顾色盲用户的可访问性——这是"以功能角色命名色彩"之外，设计系统文档中少有的无障碍硬约束。

Input Fields（输入框）

'Cloud Gray' 背景 + 粗底部边框，聚焦时边框变为 'Electric Blue'；标签常驻字段上方，确保用户在明亮环境中不丢失上下文。

Weather Widgets（天气组件）

粗描边图标（最小 2pt 描边）表示太阳、雪、风；图标放大，温度与风速数据使用 'Lexend' 字体（对应 stat-lg 样式）。

从提取方法论看，组件分析通常聚焦 4～5 个最重要的 UI 原语（按钮、卡片/容器、导航、输入、领域特有组件），每个都需记录圆角、配色方案、悬停/聚焦/激活态与过渡时间、内边距比例等。Alpine Peak 的五个组件恰好覆盖了"通用原语 + 领域特有组件（雪道芯片、天气组件）"的完整组合。

十、如何产出这样一份 DESIGN.md：extract-design-md 三阶段工作流

Alpine Peak 示例本身就是 extract-design-md 工作流的输出产物。该 skill 的完整流程分三阶段：

Phase 1：项目发现

先探测技术栈，再决定用哪份框架专属提取参考：

信号文件	框架/工具	对应参考
package.json 含 react	React / Next.js	references/react-tailwind.md
package.json 含 vue	Vue / Nuxt	references/vue.md
package.json 含 svelte	Svelte / SvelteKit	references/svelte.md
package.json 含 @angular/core	Angular	references/angular.md
仅 .css / .scss / .less	Plain CSS / SASS	references/plain-css.md
tailwind.config.js/ts	Tailwind CSS	随框架参考一并读取
theme.js / tokens.js	设计令牌文件	高优先级信号

每份参考都给出了文件发现优先级与提取模式：例如 React 栈中 tailwind.config.js 是最重要的单一文件（其 theme.extend.colors、fontFamily、borderRadius 本身就是设计系统定义）；Vue 栈要关注 SFC 的 <style scoped> 块与 Vuetify 的 theme 定义；Svelte 栈的 src/app.css 与 src/lib/tokens.ts 是关键；Angular 栈需检查 angular.json 中列出的全局样式与 Material 主题 SCSS；纯 CSS 栈则把 :root 里的 CSS 自定义属性当作最干净的令牌来源。

Phase 2：深度提取

按六个维度系统性工作：视觉主题与氛围、色彩角色、字体规则、组件样式、布局原则、Stitch 生成笔记。方法论的核心原则是：目标不是倾倒每个 CSS 属性，而是理解样式选择背后的"意图"，并用人类编辑语言描述出来，让另一位设计师（或 Stitch）能复现同样的视觉感受。每条规则在 Alpine Peak 示例中都有对应物——例如"去重近色"（#333 与 #2C2C2C 合并为一个最能代表意图的名字）、"主题文件信号强于组件散落样式"、"Tailwind 配置本身就是设计系统"。

Phase 3：写入 DESIGN.md

将结果按标准骨架组装，输出到项目目录的 .stitch/DESIGN.md（目录不存在则创建）。必须包含 YAML frontmatter 的 name 与 colors 映射，格式严格以 examples/DESIGN.md 为模板；正文依次为：Visual Theme & Atmosphere → Color Palette & Roles（Primary Foundation / Accent & Interactive / Typography & Text Hierarchy / Functional States）→ Typography Rules（Hierarchy & Weights / Spacing Principles）→ Component Stylings（Buttons / Cards / Navigation / Inputs / 领域组件）→ Layout Principles（Grid & Structure / Whitespace Strategy / Alignment & Visual Balance / Responsive Behavior & Touch）→ Design System Notes for Stitch Generation（Language to Use / Color References / Component Prompts / Incremental Iteration）。

Phase 4（可选）：集成到 Stitch

若需把设计系统推入 Stitch，交给 manage-design-system 处理 MCP 集成，流程为：

1. 上传 DESIGN.md：优先使用 upload_to_stitch.py 脚本，它会在进程内 base64 编码 Markdown 并通过 /v1/projects/{projectId}/screens:batchCreate 端点上传，绕开模型输出令牌上限：

   python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
     --project-id <PROJECT_ID> \
     --file-path /path/to/DESIGN.md \
     --api-key <API_KEY> \
     --generated-by <GENERATED_BY>
   

   返回 sourceScreen ID 与 screenInstance ID；上传前需先向用户确认设计系统摘要（显示名、关键色、字体、圆角）。
2. 创建设计系统：调用 create_design_system_from_design_md，传入 projectId 与 selectedScreenInstance（含 id 和 sourceScreen）。它会直接解析上传文档的 YAML frontmatter 并自动填充全部主题令牌，无需再调用 update_design_system。
3. 应用到屏幕：调用 apply_design_system，注意 selectedScreenInstances 只能含 id 与 sourceScreen，不得携带 x/y/width/height 字段，否则请求会因 "invalid argument" 失败。
4. 更新项目元数据：同步维护 .stitch/metadata.json（记录 projectId、title、所有已知屏幕与设计系统摘要），格式参考 examples/metadata.json。

创建完成后，设计令牌驻留在 Stitch 项目级，后续生成提示中无需重复携带。

十一、质量检查清单与最佳实践

extract-design-md SKILL.md 的交付前检查清单，正可以拿 Alpine Peak 示例逐条对照：

• [x] 每个颜色都有描述性名称、十六进制值与功能角色（Deep Peak Blue / Powder White / Safety Orange…）
• [x] 字体包含字族、性格描述与完整层级（Inter 的 x-height 优势、Lexend 的运动感、6 级样式表）
• [x] 组件样式描述了形状、颜色、状态与过渡（52px 按钮、聚焦变色的输入框、≥2pt 描边图标）
• [x] 布局包含最大宽度、栅格、断点与间距策略（Fluid Grid、4px/8px 基线、48×48px 触控目标）
• [x] Stitch 生成笔记使用自然语言而非 CSS 语法
• [x] 氛围段落是编辑文案而非技术文档
• [x] 近色已合并，文档捕捉的是样式背后的"意图"而非裸值

提取进阶建议同样值得铭记：多读代码注释与提交信息——开发者常把设计意图写进注释（如 /* hero section — breathable */），这是理解"为什么"的金矿；优先使用设计令牌库（style-dictionary、@tokens-studio 等），它们是最权威的设计值来源；主题文件信号高于组件散落样式（theme.ts 定义的是"意图"，组件内联样式代表"实际交付"，两者都重要但从主题开始）；CSS 自定义属性是刻意的——开发者定义 --brand-primary 就是在宣告这是设计令牌，应当尊重。

结语

Alpine Peak DESIGN.md 的价值不在于它是某个真实应用的样式快照，而在于它是 stitch-skills 仓库给出的标准答案模板：前端任意技术栈的项目，都可以通过 extract-design-md 的"发现 → 提取 → 写入"三阶段，产出同样结构、同样密度、同样可被 Stitch 解析的 DESIGN.md。读懂这份示例，你就同时掌握了它的"数据层"（YAML 令牌如何组织与取值）、"语义层"（如何把视觉意图写成编辑级文案）与"交付层"（如何经 manage-design-system 上传、创建并应用到项目屏幕）——这正是把任意代码库的视觉语言迁移进 Stitch 的完整闭环。