从现有产品仓库或公开网站提取设计语言并生成…

当需要为某个产品界面记录设计语言、重建视觉系统、提取设计 token 与规范，或为编码代理提供持久 UI 上下文时，用此流程生成或更新 DESIGN.md。

适用场景

解决思路

1. 只修改 DESIGN.md，不改动产品源码、依赖、配置或生成文件；使用规定的 DESIGN.md 格式契约，不发明竞争性 schema；不要把发现的每个 token 或组件都抄进文档；不要把重复、局部样式或视觉偏好当成产品意图。
2. 选择模式：有本地产品仓库时用 repository 模式，在所选产品根目录创建或更新 DESIGN.md；若仓库含多个可部署产品，按用户指定选择，归属不明时先询问再写。
3. URL 模式用于用户只给公开 URL 而无源码仓库的情况，在当前工作区创建重建版 DESIGN.md 草稿；需要渲染后的浏览器访问，检查 DOM、计算样式和公开加载的样式表，覆盖桌面与移动宽度；截图只能辅助解释，不能单独确立精确值。
4. URL 模式下检查给定页面和共享 chrome；若为全站请求，最多采样三个同源且代表不同模板的页面。URL 证据只能确立可观察的视觉模式和计算值，不能确立内部 token 名、组件归属、未记录的理由或某模式是否有意成为规范。
5. 若无法进行渲染检查，向用户索要截图或源文件；不要仅凭文案、元数据或 HTML 结构创建 DESIGN.md。只要源码可用就选 repository 模式；提供的 URL 可验证渲染表现，但不能替代仓库证据。
6. 两种模式共用同一记录与输出流水线：role → value → source → scope → recurrence → confidence。收集证据后，为每个候选记录来源、范围和复现情况，归一化到 DESIGN.md schema，剔除不确定、无契约的局部或与实现无关的候选，验证 frontmatter 形状与导出兼容性，通过后才写 Markdown。
7. 绝不让仓库或 URL 证据引入第二套 token schema；两种模式都使用相同的扁平 token 名、映射形 typography、省略规则和导出闸门。验证通过前文档视为私有，不得返回、展示或总结草稿；若验证报告形状无效或缺少导出类别，重写 frontmatter 并重跑；若类别无法修复则移除并报告为已省略。
8. repository 模式下按此顺序检查：现有 DESIGN.md 与显式仓库指南；tokens、themes、variables 和全局样式；共享原语及其变体；代表性路由和渲染消费者；表面局部实现。只有被所选产品 import、引用、继承或渲染的源才参与；排除提案、迁移、示例、生成输出、遗留实现及同名包，除非所选产品使用它们。
9. URL 模式下采样代表性元素：颜色与表面角色；排版角色；间距与布局；边框、圆角与高度；导航、按钮、输入、卡片和重复内容结构；桌面与移动呈现。优先使用计算值和已加载的 CSS 声明，而非视觉估计。
10. 在起草 URL 模式文字或 YAML 前，为每个采样页面和视口建立私有证据台账：记录页面、视口、元素角色、计算属性/值，以及可用的匹配已加载 CSS 声明或自定义属性；检查页面加载的公开样式表，包括自定义属性和媒体查询规则；样式表值只有在连接到渲染元素或在采样页面间复现时才可用。
11. URL 值满足以下任一条件才提升进 DESIGN.md：(a) 渲染计算值与已加载声明/自定义属性一致，或 (b) 同一计算值在同一角色上跨所需样本复现；否则省略。仅当某暴露的自定义属性名其声明与渲染使用可直接观察时，才可保留该名称；不要从原始值发明语义别名。
12. URL 模式每条声明写入前需三证齐全：Observation（模式或值在渲染页面上可见或可计算）、Basis（经过测量，或在所需采样页面/视口间复现）、Consequence（改变 DESIGN.md 中具体实现选择）。缺任一证明就省略；不要把视觉印象变成 token、把单次出现变成全站规则、把猜测值变成 YAML；精确值需要计算样式或已加载 CSS，否则只描述角色不带值或省略。
13. repository 模式下，描述产品性格前先找显式产品意图或设计参考；URL 模式下不要发明产品性格，Overview 只能陈述网站可观察的目的与呈现，并必须标明文档为重建版。
14. YAML 只依据治理源中已命名的共享 token 和角色来写；不要把工具类、重复字面量或组件值变成 token 尺度。frontmatter 形状是硬闸门：token 组必须是 mapping，其子项为 schema 字段；绝不输出标量 typography 条目（如 sans: Geist）、任意嵌套源对象（如 font-family: { mono: ... }）或从 CSS 变量名复制的圆角键（radius-sm、radius-md 等）。
15. token 组用 mapping，绝不用 sequence。当治理源只定义一个组级 token（如 --radius）时，归一化为 base；否则保留源 token 名。把源值映射到 DESIGN.md schema 字段，保留语义 token 名而非源对象嵌套。例如写 typography.mono.fontFamily: Geist Mono，绝不写 typography.mono: Geist Mono；源只有 --radius 时写 rounded.base: 0.625rem，绝不写 rounded.radius 或派生的圆角步进。
16. 写精确值前，先通过活动主题或配置解析框架工具类。写 frontmatter 前确定仓库导出目标：Tailwind v4 用 css-tailwind，Tailwind v3 用 json-tailwind，其他用 dtcg；token 名必须对该目标有效。
17. 编码主题模式前检查已安装的 DESIGN.md 规范：运行 npx @google/design.md spec。若规范支持 themes 和 default-theme，使用其主题感知 token 语法；否则把默认主题值放在每个规范语义 token 下，并在 ## Themes 表中保留精确的备用主题值。不要创建并行的 -light 和 -dark token 名、丢弃备用主题值或使用未发布语法；回退 Themes 表仅作文档，不要假装它让 frontmatter 具备主题感知。
18. repository 模式下，每条文字规则必须有显式指南、已命名的共享 token 或变体，或至少两个已审计表面使用的共享所有者支持；否则省略。URL 模式下，每条文字规则必须可直接观察；全站规则必须在至少两个采样模板间复现，否则限定到被检查页面；使用重建的基于角色的名称，并将文档标记为草稿。
19. URL 模式 YAML 有意稀疏，但有测量证据时不应为空。当至少一个受支持的值或角色通过三证闸门时添加类别。颜色可用计算值或已验证的公开自定义属性，但必须扁平且导出安全；typography 必须使用规范字段如 fontFamily、fontSize、lineHeight、fontWeight；圆角和间距值必须来自计算样式或已加载声明。不要仅为组织观察而创建 primary、elevated、display 等别名。组件部分要求同一交互或表面处理在至少两个采样页面间复现，并改变具体实现选择。
20. URL 重建不改变 frontmatter schema。typography 只使用这些属性名：fontFamily、fontSize、lineHeight、fontWeight、letterSpacing。例如：typography: sans: {fontFamily: Inter Variable}, display: {fontFamily: Inter Variable, fontSize: 64px, lineHeight: 64px, fontWeight: 510}。绝不输出 URL 特有别名如 family、size、weight、mobile-display，或 typography 尺度内嵌套的 sans/mono 值。重建角色名可不同，schema 字段名不可变。
21. URL 输出默认用 css-tailwind 作为兼容导出目标，除非用户指定其他目标。把重建的颜色角色扁平化为有效 token 名，如 background-primary、foreground-secondary、border-muted，而非嵌套键 background.primary 或 foreground.secondary。每个输出的 token 名必须匹配 ^[a-zA-Z0-9][a-zA-Z0-9-]*$；任何会失败的键都要拒绝并重写。
22. 写任何 Markdown 前先归一化 URL frontmatter，顺序为：收集证据、选择导出目标、把证据映射到规范 schema、拒绝无效形状、再写文档。绝不先起草文字再回头补 YAML。URL frontmatter 必须满足：colors 是有效 token 名到值的扁平映射；typography 是命名尺度的映射，每个尺度是只用规范字段的映射；rounded 和 spacing 是有效 token 名到值的扁平映射；components 可引用规范 token 路径，但不得引入第二套 token schema。若归一化需要发明 token 名、字段、尺度或语义关系，则省略该候选。
23. 除 Overview 外，每句 Markdown 都必须改变实现选择。删除组件清单、通用设计建议和仅复述 YAML 的文字。保留每条规则的范围和方向；当实现与显式指南冲突时，记录指南并在 DESIGN.md 之外报告冲突。
24. 从最小有效 frontmatter 开始：version: alpha、name: <string>、description: <string>。只有 name 必填。仅当治理源已定义该命名系统或契约时，才添加 colors、typography、rounded、spacing 或 components。不要为组织实现值而创建 token 名。Token 引用使用 {path.to.token}。
25. 使用 schema 形状的 mapping，而非复制的源嵌套。typography 尺度始终命名并在其下映射属性，例如 typography: sans: {fontFamily: Geist}, mono: {fontFamily: Geist Mono}。若源只定义 --radius，写 rounded.base，不写 rounded.radius；不要从工具类或重复值派生 sm、md、lg、xl。保存前检查解析后的 frontmatter，若任何 typography 子项是标量或 rounded 含治理源中不存在的键，自行拒绝。
26. 从 ## Overview 开始，只陈述产品目的和有证据的设计方向；不要总结页面、组件、token 或实现。只按此顺序添加受支持章节：1. Colors 2. Themes 3. Typography 4. Layout 5. Elevation & Depth 6. Shapes 7. Components 8. Do's and Don'ts。不要仅因格式中存在就创建章节；不要重排或重复已含章节；仅当受支持指南无法放入标准章节时才添加未知章节。
27. Markdown 记录设计意图和应用指南。除回退 ## Themes 表外，不要把 token 清单、组件配置、源语法或文档方法论放进 Markdown。仅当治理源明确禁止时才包含 Don't。
28. 把精确规范值放在 YAML frontmatter，除非已安装规范无法表示模式时的备用主题值；把受支持的理由和应用指南放在 Markdown；保留现有 DESIGN.md 中已接受的决策，除非用户或当前治理证据替换它们；不要发明品牌个性、受众或情感理由；不要在 DESIGN.md 内包含引用、审计笔记、被拒候选、冲突或未决问题。
29. 保存前删除：任何治理源未命名的 YAML token；任何被呈现为产品级规则的页面局部行为；任何与显式指南冲突的实现模式；任何未明确声明的禁止项；YAML frontmatter 或回退 ## Themes 表之外的任何精确实现值；Markdown 中的任何组件配置或文档方法论；任何不改变最终 DESIGN.md 的句子。
30. 最后做一次 no-op 检查：删除 be thorough、keep it polished、use good judgment 等模糊建议；只保留证据闸门、schema 约束或改变文档的应用规则。
31. 运行结构 lint：npx @google/design.md lint DESIGN.md。然后用上面选定的目标运行一次兼容导出：npx @google/design.md export --format <format> DESIGN.md。检查输出：目标支持的每个已填充 frontmatter 类别都必须发出对应 token 类别；即使命令成功退出，空或缺失类别也是 schema 失败。重写 frontmatter 并重跑验证直到类别发出，除非目标确实无法表示；任何已填充类别在导出中缺失时不得报告成功；lint 或导出失败时不得返回文档；不要仅为满足导出器限制而删除受支持设计信息，应报告该限制；不要创建或保留导出文件。
32. 对 css-tailwind，验证这些输出族：colors → --color-*；typography.<name>.fontFamily → --font-*；typography.<name>.fontSize → --text-*；rounded → --radius-*；spacing → --spacing-*。Typography 条目是命名尺度，把 fontFamily、fontSize、lineHeight 放在每个尺度内，绝不放在 font-family 等任意源嵌套下。若 typography 已填充但导出既无 --font-* 也无 --text-*，文档无效，报告前必须重写。
33. 更新现有文档时，临时保留其原始内容并运行：npx @google/design.md diff <previous-file> DESIGN.md。恢复任何被移除的已接受决策，除非当前治理证据或用户明确替换。
34. 报告返回：模式与已审计产品/URL；创建或更新的 DESIGN.md；使用的治理源；从文档中省略的冲突或不支持区域；最终 lint 与导出结果。URL 模式下将输出标记为重建草稿。

适用边界 · 注意事项

• 没有本地产品仓库且无法进行渲染浏览器检查时（URL 模式需要渲染访问，否则只能索要截图或源文件，不能仅凭文案、元数据或 HTML 结构创建）。
• 仓库含多个可部署产品且用户未指定、归属不明时，应先询问再写，不要擅自选择。
• 已安装的 DESIGN.md 规范不支持 themes/default-theme 时，不要使用未发布语法或创建并行的 -light/-dark token 名；应改用回退 ## Themes 表并说明其仅为文档。