create-design-md

创建 DESIGN.md

为一个产品或结构统一的网站创建 DESIGN.md。记录主导其设计的语言，而不是所有现存的值。

范围限制

• 仅修改 DESIGN.md。不要更改产品源代码、依赖项、配置或生成的文件。
• 使用下方的 DESIGN.md 格式约定。不要另行发明一套结构。
• 不要把发现的每个令牌或组件都复制到文档中。
• 不要将重复出现的内容、局部样式或视觉偏好转化为产品意图。

1. 选择模式

仓库模式

本地有产品仓库时使用。在所选产品的根目录创建或更新 DESIGN.md。

如果仓库包含多个可部署产品，选择用户指定的产品。如果请求未指定产品且归属不明确，先询问再编写。

仓库证据可用于确定规范值、令牌名称、组件归属和已记录的设计理由。

URL 模式

用户提供公开 URL，但未提供其源代码仓库时使用。在当前工作区创建一份重建版 DESIGN.md 草稿。

URL 模式要求能够访问已渲染的页面。在桌面和移动端宽度下检查 DOM、计算样式和公开加载的样式表。截图可用于辅助理解，但不能单独用于确定精确值。

检查用户提供的页面及共享界面元素。对于全站请求，最多选取三个同源页面作为不同模板的代表进行抽查。

URL 证据只能用于确定可观察到的视觉模式和计算值。它无法确定内部令牌名称、组件归属、未记录的设计理由，或某种模式是否有意作为规范。

如果无法检查已渲染的页面，请索取截图或源文件。不要仅凭文案、元数据或 HTML 结构创建 DESIGN.md。

只要有源代码，就优先使用仓库模式。用户提供的 URL 可用于核验渲染效果，但不能取代仓库证据。

通用证据流程

两种模式仅在证据收集方式上有所不同，记录和输出流程必须相同：

role → value → source → scope → recurrence → confidence

1. 使用所选模式收集证据。
2. 记录每个候选项的来源、范围和重复情况。
3. 将候选项规范化为 DESIGN.md 模式。
4. 省略不确定、仅局部适用且无约定，或与实现无关的候选项。
5. 验证 frontmatter 结构及导出兼容性。
6. 只有规范化后的 frontmatter 通过验证后，才能编写 Markdown。

绝不能让仓库或 URL 证据引入第二套令牌结构。两种模式都适用相同的扁平令牌名称、映射形式的排版信息、省略规则和导出门槛。

验证通过前，生成的文档必须保持私有。lint 和导出成功前，绝不能返回、展示或概述 DESIGN.md 草稿。如果验证报告指出结构无效或缺少导出类别，请重写 frontmatter 并重新运行；如果无法修复该类别，则将其移除并报告为已省略。

2. 追踪证据

在仓库模式下，按以下顺序检查：

1. 现有的 DESIGN.md 和明确的仓库指南
2. 令牌、主题、变量和全局样式
3. 共享原语及其变体
4. 代表性路由和渲染它们的使用方
5. 局部于界面的实现

只有当所选产品导入、引用、继承或渲染某个来源时，该来源才算参与其中。排除提案、迁移、示例、生成的输出、旧版实现，以及名称相似但未被所选产品使用的软件包。

在 URL 模式下，抽样检查以下具有代表性的元素：

• 颜色和界面角色
• 字体排印角色
• 间距和布局
• 边框、圆角和层级效果
• 导航、按钮、输入框、卡片和重复的内容结构
• 桌面端和移动端的呈现

优先采用计算所得的值和已加载 CSS 声明，而不是视觉估算。

在撰写 URL 模式的正文或 YAML 前，为每个抽样页面和视口建立一份私有证据台账。对每个候选项，记录：页面、视口、元素角色、计算所得的属性/值，以及可用时与之匹配的已加载 CSS 声明或自定义属性。检查页面加载的公开样式表，包括自定义属性和媒体查询规则；只有当样式表中的值与已渲染元素相关联，或在抽样页面中反复出现时，该值才可使用。

只有满足以下任一条件时，才将 URL 值纳入 DESIGN.md：（a）已渲染的计算值与已加载的声明/自定义属性一致；或（b）相同的计算值在所需抽样中针对相同角色反复出现。若两者均不满足，则省略该值。只有在自定义属性的声明及其渲染用途都能直接观察到时，才可保留其名称；不要根据原始值臆造语义别名。

每条 URL 模式的陈述在写入前都必须具备以下三项证据：

1. 观察：该模式或值在已渲染页面上可见，或可通过计算得出。
2. 依据：该值经过测量，或在所需抽样页面/视口中反复出现。
3. 影响：该值会改变 DESIGN.md 中的一项具体实现选择。

若缺少任何一项证据，就省略该陈述。不要把视觉印象变成令牌，不要把单次出现的情况说成全站规则，也不要把猜测的值写入 YAML。精确值必须基于计算样式或已加载的 CSS；否则应描述其角色但不提供值，或直接省略。

3. 确定应包含的内容

在仓库模式下，描述产品特征前，先找到明确的产品意图或设计参考。在 URL 模式下，不要臆造产品特征；概览只能说明网站可观察到的用途和呈现方式，并且必须指出该文档是重构所得。

仅根据治理来源中命名的共享令牌和角色编写 YAML。不要将工具类、重复出现的字面值或组件值转成令牌层级。

将 frontmatter 的结构视为硬性要求，而非风格选择：属于令牌组的值必须是映射，其子项必须是架构中定义的字段。绝不能输出标量排印条目（sans: Geist）、任意嵌套的来源对象（font-family: { mono: ... }），或照抄 CSS 变量名的圆角键（radius-sm、radius-md 等）。

令牌组必须使用映射，不能使用序列。如果治理来源定义了一个组级令牌（例如 --radius），则将其规范化为 base；否则保留来源中的令牌名称。

将来源值映射到 DESIGN.md 架构字段。保留语义令牌名称，而非来源对象的嵌套结构。例如，写成 typography.mono.fontFamily: Geist Mono，绝不要写成 typography.mono: Geist Mono；如果来源只有 --radius，则写成 rounded.base: 0.625rem，绝不要写成 rounded.radius 或派生的圆角阶梯。

写入精确值之前，先通过当前启用的主题或配置解析框架工具类。

编写 frontmatter 前，确认仓库的导出目标：Tailwind v4 使用 css-tailwind，Tailwind v3 使用 json-tailwind，其他情况使用 dtcg。令牌名称必须符合相应目标的要求。 编码主题模式前，请先检查已安装的 DESIGN.md 规范：

npx @google/design.md spec

如果该规范支持 themes 和 default-theme，请使用支持主题的令牌语法。否则，将默认主题值放在每个规范语义令牌下，并在 ## Themes 表格中保留精确的备用主题值。不要创建并行的 -light 和 -dark 令牌名称，不要舍弃备用主题值，也不要使用尚未发布的语法。备用 Themes 表格仅用于文档记录；不要假称它能让 frontmatter 支持主题。

在仓库模式下，每条说明性规则都必须有明确指导、具名的共享令牌或变体，或至少被两个已审查界面共用的所有者作为依据。否则请省略。

在 URL 模式下，每条说明性规则都必须能直接观察到。全站规则必须在至少两个采样模板中重复出现；否则请将规则限定到已检查的页面。使用重建的基于角色的名称，并将文档标记为草稿。

URL 模式的 YAML 有意保持精简，但若存在测量证据，也不能留空。至少有一个受支持的值或角色通过三重证据门槛时，就添加相应类别。颜色可使用计算值或经验证的公开自定义属性，但必须保持扁平且可安全导出；排版必须使用 fontFamily、fontSize、lineHeight 和 fontWeight 等规范字段；圆角和间距值必须来自计算样式或已加载的声明。不要仅为整理观察结果而创建 primary、elevated 或 display 等别名。组件部分只有在至少两个采样页面中重复出现相同的交互方式或表面处理，且这会改变具体实现选择时才需要添加。

URL 重建不会改变 frontmatter 架构。仅使用以下排版属性名称：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，也不要在排版比例中使用嵌套的 sans/mono 值。重建的角色名称可以变化；架构字段名称则不能。

对于 URL 输出，除非用户指定其他目标，否则请使用 css-tailwind 作为兼容性导出目标。将重建的颜色角色扁平化为有效的令牌名称。使用 background-primary、foreground-secondary 或 border-muted，不要使用 background.primary 或 foreground.secondary 等嵌套键。每个输出的令牌名称都必须匹配 ^[a-zA-Z0-9][a-zA-Z0-9-]*$；不符合此测试的键必须拒绝并重写。

编写任何 Markdown 之前，先规范化 URL frontmatter。顺序如下：收集证据，选择导出目标，将证据映射到规范架构，拒绝无效结构，然后编写文档。绝不要先起草说明文字，再回头补写 YAML。

URL frontmatter 必须满足以下结构规则：

• colors 是由有效令牌名称和值组成的扁平映射。
• typography 是由具名比例组成的映射；每个比例都是仅使用规范字段的映射。
• rounded 和 spacing 是由有效令牌名称和值组成的扁平映射。
• components 可以引用规范令牌路径，但不得引入第二套令牌架构。

如果规范化需要虚构令牌名称、字段、比例或语义关系，请省略该候选项。

除 Overview 外，每个 Markdown 句子都必须改变某项实现选择。删除组件清单、通用设计建议，以及仅仅重述 YAML 的说明文字。

保留每条规则的范围和方向。若实现与明确指导冲突，请记录该指导，并在 DESIGN.md 之外报告冲突。

4. 编写文档

从最小的有效 frontmatter 开始：

---
version: alpha
name: <string>
description: <string>
---

只有 name 是必填项。只有当权威来源已定义相应的命名系统或规范时，才添加 colors、typography、rounded、spacing 或 components。不要为了整理实现值而创建令牌名称。令牌引用使用 {path.to.token}。

使用符合架构的映射，而不是照搬源文件的嵌套结构。排版比例始终要有名称，并将其属性映射到名称之下：

typography:
  sans:
    fontFamily: Geist
  mono:
    fontFamily: Geist Mono

如果源文件只定义了 --radius，就写 rounded.base，而不是 rounded.radius；不要根据工具类或重复值推导出 sm、md、lg 或 xl。保存前，检查解析后的 frontmatter；如果 typography 下有任何标量值，或 rounded 包含权威来源中未出现的键，就自行拒绝该文档。

从 ## Overview 开始。只陈述产品的用途和有证据支持的设计方向。不要概述页面、组件、令牌或实现。只添加下列顺序中有依据支持的章节：

1. Colors
2. Themes
3. Typography
4. Layout
5. Elevation & Depth
6. Shapes
7. Components
8. Do's and Don'ts

不要仅仅因为格式中包含某个章节就创建该章节。不要调整或重复已添加章节的顺序。只有当有依据支持的指导无法归入标准章节时，才添加未知章节。

Markdown 用于记录设计意图和应用指导。除备用的 ## Themes 表格外，不要在 Markdown 中放入令牌清单、组件配置、源语法或文档方法。

只有当权威来源明确禁止某事时，才添加禁止事项。

• 将精确的规范值放入 YAML frontmatter，但当已安装的规范无法表示模式时，备用主题值除外。
• 将有依据支持的理由和应用指导放入 Markdown。
• 除非用户或当前权威证据要求替换，否则保留现有 DESIGN.md 中已接受的决策。
• 不要臆造品牌个性、受众或情感理由。
• 不要在 DESIGN.md 中加入引用、审查记录、已否决的候选项、冲突或未解决的问题。

保存前，删除：

• 任何未经权威来源命名的 YAML 令牌
• 任何被表述为产品级规则的页面局部行为
• 任何与明确指导相冲突的实现模式
• 任何未明确说明的禁止事项
• YAML frontmatter 或备用的 ## Themes 表格之外的任何精确实现值
• Markdown 中的任何组件配置或文档方法
• 任何不会改变最终 DESIGN.md 的句子

最后执行一遍无操作检查：删除“全面一些”“保持精致”或“运用良好判断”等模糊建议。只保留会影响文档的证据门槛、架构约束或应用规则。

5. 验证

运行结构检查：

npx @google/design.md lint DESIGN.md

然后使用上方选定的目标运行一次兼容性导出：

npx @google/design.md export --format <format> DESIGN.md

检查输出。目标支持的每个已填充前置元数据类别都必须输出对应的令牌类别；即使命令成功退出，类别为空或缺失也属于架构错误。重写前置元数据并重新运行验证，直至类别成功输出，除非目标确实无法表示该类别。只要导出中仍缺少任何已填充类别，就不得报告成功。若检查或导出失败，不得返回文档。不得仅为满足导出器的限制而删除受支持的设计信息；应报告该限制。不得创建或保留导出的文件。

对于 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-*，则文档无效，必须重写后才能报告。

更新现有文档时，暂时保留其原始内容，并运行：

npx @google/design.md diff <previous-file> DESIGN.md

恢复任何已删除且被接受的决策，除非当前权威证据或用户明确要求替换该决策。

6. 报告

返回：

• 模式及经审查的产品或 URL
• 已创建或更新的 DESIGN.md
• 使用的权威来源
• 未纳入文档的冲突或不受支持的领域
• 最终检查和导出结果

在 URL 模式下，将输出标注为重建草稿。