impeccable 的 `/document` 指令：从现有代码自动生成规范 DESIGN.md 设计系统文档的完整实战指南

设计系统（Design System）最大的敌人从来不是“没有设计”，而是“设计只在代码里、不在任何可以被消费的地方”。AI Agent 每次生成新页面都要靠猜测还原旧页面的视觉语言，一次猜测、一次漂移，几个版本后品牌就已面目全非。impeccable 的 document 指令正是为解决这个问题而存在：它扫描项目里已经落地运行的代码，把散落在 CSS 变量、Tailwind 配置、CSS-in-JS theme、组件源码中的视觉事实，抽取并固化为一根项目的根目录级规范文档 DESIGN.md 及配套 sidecar，让后续生成新界面的 Agent 始终有“品牌锚点”可依。

本文基于 impeccable 仓库中 .claude/skills/impeccable/reference/document.md 这份操作规范展开，系统讲解 DESIGN.md 的格式规范（YAML frontmatter token schema + 八个 canonical 段落）、Scan/Seed 两条执行路径、.impeccable/design.json sidecar schema 与组件翻译规则，并用仓库自带示例 demos/landing-demo/DESIGN.md 与 demos/landing-demo/DESIGN.json 作为对照实例。读完你可以：掌握 DESIGN.md 机器可读层与自然语言层的分工边界、按规范格式从既有代码反推出完整设计系统文档，并理解 impeccable 体系内该指令与 init、new-work、live 等指令的协作关系。

一、document 在 impeccable 中的定位与触发时机

在 impeccable 的命令体系（见 .claude/skills/impeccable/SKILL.md）中，document 属于 Build 类别，其作用用一句话概括即：在项目根目录生成一份 DESIGN.md，捕获当前视觉设计系统，使 AI Agent 生成新界面时保持在品牌轨道上。它与 init（捕获产品事实到 PRODUCT.md）形成分工：产品真相进 .claude/skills/impeccable/reference/init.md，视觉现实进 DESIGN.md。

何时运行 document

规范明确了四类典型触发场景：

1. new-work 发现了成体系的既有视觉系统，但项目没有 DESIGN.md——即“视觉已存在、文档缺失”；
2. 一个新 world 的首次实现完成，需要把实现过程中的临时决策“碳化”（carbonized）为正式规范；
3. 已有 DESIGN.md 已过时，设计与文档发生漂移（drift）；
4. 大规模改版之前，先把当前状态固化为参照基线。

其中蕴含一条硬性约束：如果 DESIGN.md 已经存在，绝不静默覆盖。必须先展示现有文件给用户，然后 STOP 并调用 AskUserQuestion 澄清，由用户在 refresh（刷新）、overwrite（覆盖）、merge（合并）三者之间选择。这与同仓库 degraded/documenter.md 中“已有 DESIGN.md 意味着更新而非替换”的要求一脉相承。

触发后的两条路径

路径	适用前提	产出
Scan mode（默认）	项目已有设计 token、组件或渲染输出，有代码可分析	自动抽取 token，经用户确认描述语言后写出 DESIGN.md + sidecar
Seed mode	项目尚未实现（pre-implementation），无视觉系统可抽取	写出方向性的 DESIGN.md seed（带 SEED 标记），不含虚构的 token

决策方式：先扫描。执行 Scan mode 的 Step 1；若扫描发现既没有 token、没有组件文件、也没有渲染站点，则应向用户提供 seed mode 选项，而不是悄悄切换。需要注意的是，/impeccable document --seed 会请求 new-work 的 world workshop，但并不授权替换成体系的现有代码——当既有系统存在时，应提供 scan mode，或把明确的身份替换请求路由给 new-work。

二、输出文件的格式规范：token 是规范性的，散文提供语境

document 的输出遵循官方 DESIGN.md 格式规范：可选 YAML frontmatter 承载机器可读的设计 token，其后最多八个固定顺序的 Markdown 段落。核心原则是——Token 是规范性的（normative），散文只是解释如何应用它们的语境。段落可以按需省略，但凡是出现的段落都必须保持规定顺序，并使用 canonical 标题，以便文件在各类 DESIGN.md 感知工具间可移植。

2.1 Frontmatter token schema

frontmatter 是机器可读层，它是 Stitch 的 linter 校验的对象，也是 live panel 渲染 tile 的数据来源。规范强调要“保持精简”：每一项都应对应项目真正使用的 token。

---
name: <project title>
description: <one-line tagline>
colors:
  primary: "#b8422e"
  neutral-bg: "#faf7f2"
  # ...one entry per extracted color; key = descriptive slug
typography:
  display:
    fontFamily: "Cormorant Garamond, Georgia, serif"
    fontSize: "clamp(2.5rem, 7vw, 4.5rem)"
    fontWeight: 300
    lineHeight: 1
    letterSpacing: "normal"
  body:
    # ...
rounded:
  sm: "4px"
  md: "8px"
spacing:
  sm: "8px"
  md: "16px"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.neutral-bg}"
    rounded: "{rounded.sm}"
    padding: "16px 48px"
  button-primary-hover:
    backgroundColor: "{colors.primary-deep}"
---

围绕这套 schema 有几条“必须遵守的规则”：

• Token 引用使用 {path.to.token} 形式（如 {colors.primary}、{rounded.md}）。组件可以引用 primitive；primitive 之间不能互相引用。
• 颜色接受任何合法 CSS 颜色字符串。十六进制是推荐的可移植默认；但当项目以 rgb()、hsl()、oklch()、广色域或混合颜色作为规范性源头时，应保留原有值。没有明确理由，绝不分裂事实源头（同一 token 在 frontmatter 与正文中出现两个不同值即是分裂）。
• 组件子 token 只限 8 个属性：backgroundColor、textColor、typography、rounded、padding、size、height、width。阴影、动效、focus ring、backdrop-filter 都不属于这套 schema——它们应放进 sidecar（Step 4b）。
• Scale key 是开放式的：沿用项目自身命名（如 oxblood-deep、surface-container-low），不要改写成 Material 默认名。
• Variant 是命名约定而非 schema：button-primary / button-primary-hover / button-primary-active 作为兄弟 key 平铺即可。

2.2 Markdown 正文：八个 canonical 段落

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

规范的要点是省略无关段落优于用编造的规则填满它们：响应式布局放 Layout、深度放 Elevation & Depth、圆角与造型语言放 Shapes、组件级行为放 Components。格式允许保留未知段落，但新的视觉指引凡是能用 canonical 结构表达的都应优先使用。同时严禁对段落标题做“近似改名”（如把 "Colors" 写成 "Color Palette & Roles"），因为工具链解析依赖精确标题。

三、Scan mode 全流程：先抽取、后确认、再成文

Scan mode 的完整方法描述为 “approach C: auto-extract, then confirm descriptive language”（先自动抽取，再确认描述语言）。

Step 1：按优先级查找设计资产

扫描代码库时按下列优先级依次查找（记录名称、值、定义文件三要素）：

1. CSS custom properties：在 CSS 文件中 grep --color-、--font-、--spacing-、--radius-、--shadow-、--ease-、--duration- 声明（常见位置 src/styles/、public/css/、app/globals.css）；
2. Tailwind config：若存在 tailwind.config.{js,ts,mjs}，读取 theme.extend 块中的 colors、fontFamily、spacing、borderRadius、boxShadow；
3. CSS-in-JS theme 文件：styled-components、emotion、vanilla-extract、stitches 等，查找 theme.ts、tokens.ts 或等价物；
4. 设计 token 文件：tokens.json、design-tokens.json、Style Dictionary 输出、W3C token 社区小组格式；
5. 组件库：扫描主要 button、card、input、navigation、dialog 组件，记录其 variant API 与默认样式；
6. 全局样式表：根 CSS 文件通常承载基础排版与颜色分配；
7. 可见渲染输出：若浏览器自动化工具可用，加载线上站点并从关键元素（body、h1、a、button、.card）取样计算样式——这能捕获 token 遗漏的值。

Step 2：自动抽取可抽取的内容，并完成角色归类

把发现的结构化信息组织成草稿：

• Colors：按 Primary / Secondary / Tertiary / Neutral（Stitch 沿用的 Material 派生角色）分组。若项目只有一个强调色，就表达为 Primary + Neutral，宁可省略 Secondary 与 Tertiary 也不要编造。
• Typography：把观测到的字号、字重映射到 Material 层级（display / headline / title / body / label），记录字体栈与缩放比率。
• Elevation：清点阴影词汇表。如果项目是扁平设计、靠色调分层（tonal layering）而非阴影表达深度，那也是合法答案——但要显式写清楚。
• Components：对每个常见组件（button、card、input、chip、list item、tooltip、nav）抽取形状（圆角）、颜色分配、hover/focus 处理、内部 padding。
• Layout + spacing：抽取网格、容器、断点、节奏（rhythm）与密度行为进 Layout。
• Shapes：抽取圆角、边角、边框、裁切与反复出现的造型行为进 Shapes。

Step 2b：先起草 frontmatter

从自动抽取结果直接起草 YAML frontmatter（真正写入时它位于 DESIGN.md 顶部）：

• Colors：每个抽取出的颜色一条；key 用描述性 slug（oxblood-deep、editorial-magenta，而不是 blue-800）；值采用项目视为 canonical 的格式（OKLCH 或 hex）。不分裂事实源头：frontmatter 里用一种格式，不要在正文用另一个值重定义同一 token。
• Typography：每个角色一条（display、headline、title、body、label）。Typography 是对象，只包含对项目真实存在的属性（fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation）。
• Rounded / Spacing：使用项目实际用到的 scale steps 与其自有的命名（sm/md/lg，或 surface-sm，或数字步进）。
• Components：每个 variant 一条（button-primary、button-primary-hover、button-ghost），通过 {colors.X}、{rounded.Y} 引用 primitive。若某个 variant 需要 Stitch 的 8 属性集合无法承载的属性（shadow、focus ring、backdrop-filter），把完整 snippet 放进 sidecar 而非硬塞。

项目没有的东西一律跳过——空的 scale key 与凭空捏造的 token 都会污染规范。

Step 3：向用户征询无法自动抽取的定性语言

以下内容需要创造性输入，无法自动抽取，分两轮、每轮至多三个问题（或取 harness 的更低上限）结构化提问，轮次之间要等待：

• Creative North Star：整个系统的单一命名隐喻（如 "The Editorial Sanctuary"、"The Golden State Curator"、"The Lab Notebook"）。基于 PRODUCT.md 的品牌人格给出 2-3 个候选；
• Overview voice：氛围形容词、2-3 句美学主张，以及已确认的视觉反参考（anti-reference）；
• Color character（针对自动抽取的颜色）：描述性命名（"Deep Muted Teal-Navy"，而非 "blue-800"），按色相/饱和度给每个关键色建议 2-3 个选项；
• Elevation philosophy：flat / layered / lifted；若存在阴影，其角色是环境光（ambient）还是结构性（structural）？
• Component philosophy：用一个短语概括按钮、卡片、输入框的质感（"tactile and confident" 对比 "refined and restrained"）。

规则提醒：只有当 PRODUCT.md 中的某句话是真正约束视觉系统的持久品牌承诺时才可引入；页面策略与表面概念不属于此处。

Step 4：写出 DESIGN.md

文件以 Step 2b 起草的 YAML frontmatter 开头，随后按上文 canonical 结构写正文。规范的段落骨架（含每个组件的记录清单）整理如下：

## Overview
**Creative North Star: "[Named metaphor in quotes]"**
[2-3 段整体描述：人格、密度、美学主张，从 North Star 出发向外展开；
只陈述已确认的视觉拒绝；以 **Key Characteristics:** 要点列表收尾]

## Colors
[一句话描述调色板气质]
### Primary / Secondary(可选) / Tertiary(可选) / Neutral
- **[描述性名称]** (#HEX / oklch(...)): [在哪里、为什么使用。要说语境而非笼统角色]
### Named Rules (可选)
**The [Rule Name] Rule.** [简短有力的禁令或信条]

## Typography
**Display Font / Body Font / Label-Mono Font + Character 描述**
### Hierarchy
- **Display** ([weight], [size/clamp], [line-height]): [用途]
- **Headline / Title / Body / Label** 同理；Body 如有需要标注 65–75ch 行长上限

## Layout
[网格或空间模型、容器行为、密度、响应式变化、间距节奏；只写观测到的精确值]

## Elevation & Depth
[一段话：阴影 / 色调分层 / 混合？"无阴影"也要显式声明并说明如何传达深度]
### Shadow Vocabulary (适用时)
### Named Rules (可选)

## Shapes
[造型语言：圆角策略、边框、裁切、反复出现的轮廓几何]

## Components
### Buttons / Chips / Cards/Containers / Inputs/Fields / Navigation / [Signature Component]
[每个组件先一句 character line，再给 shape、颜色分配、状态、独特行为]

## Do's and Don'ts
### Do: / ### Don't:
[以 "Do"/"Don't" 开头的具体护栏；只在有依据时给出精确值]

同一参考文档给出几项务实写作建议：描述性优先于技术性（"Gently curved edges (8px radius)" 优于 "rounded-lg"，技术值放在括号里）；功能性优先于装饰性（对每个 token 说明在哪里、为什么用，而不只是它是什么）；使用 Named Rules（The [Name] Rule. + 一句话教义），它们比列表对 AI 消费者更易记忆、可引用，每节目标 1-3 条；证据确凿处用硬语气（真不变量），暂定指导用软语气。

Step 5：确认与精修

向用户展示完整的 DESIGN.md；高亮非显而易见的创意决策（描述性颜色名、氛围语言、named rules）。顺带说明 .impeccable/design.json 也已写入，live panel 现在会渲染该项目真实的按钮/输入框/导航 primitive 而不是通用近似物。最后提供精修入口："Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" 会话内后续命令无需重载——本次写入即最新事实源。

四、Seed mode：无代码阶段的“方向性种子”

Seed mode 面向还没有可抽取视觉系统的项目。它产出的是用户选定的视觉世界脚手架（scaffold），而不是虚构的 token spec——两者的差别是原则性的。

Step 1：路由到 new-work 的 workshop

PRODUCT.md 是前置条件；缺失时应先加载 .claude/skills/impeccable/reference/init.md 完成产品访谈——没有持久的产品语境，不创建视觉身份。若 PRODUCT.md 已存在，加载 .claude/skills/impeccable/reference/new-work.md 解决视觉权威问题，运行其 Create or replace the visual world 流程与 Commit the world，在 direction seed 与 surface brief 完成后停止，不进入实现。若本次会话中 new-work 已完成 workshop，直接采用其选定方向，不再重复询问。

Step 2：写出 seed DESIGN.md

使用与 Scan mode 相同的 canonical 段落顺序，填入选定方向，把未落实的实现事实写成诚实的占位符。文件首行必须带：

<!-- SEED: established with the user before implementation; re-run /impeccable document once there's code to capture the actual tokens and components. -->

各段落写法的差异规则：Overview 写选定设计论点、布局行为、材质性格、图像立场、动效语法与可复用签名——首个 surface 的构图留在 surface brief 中，不提升进全局 world；Colors / Typography 只在用户、已有资产或 new-work 探索确立后才写值，否则标记为 [to be resolved during implementation]；Layout 写出选定的空间语法与响应式行为，不假装精确测量已定案；Elevation & Depth 把选定材质与深度行为作为不变量陈述；Shapes 写选定造型与圆角语言；Components 整节省略（尚无组件存在）；Do's and Don'ts 只记录 world 选择过程中确认的持久护栏，不记任务局部拒绝。

Seed 的 frontmatter 只写 name 与 description；colors/typography/rounded/spacing/components 全部留空——真实 token 在下次 Scan mode 落地。同理，seed mode 跳过 sidecar：没有可渲染的东西。Step 3 确认时明确告知用户这是 seed，并提示“有了代码后重跑 /impeccable document，那一遍会抽取真实 token 并生成 sidecar”。

五、.impeccable/design.json sidecar：承载 schema 装不下的扩展

5.1 职责边界与 schemaVersion 2

frontmatter 拥有 token primitive（colors、typography、rounded、spacing、components）；sidecar 位于 .impeccable/design.json，承载 Stitch 的 schema 装不下的内容：每个颜色的 tonal ramp、shadow/elevation token、motion token、breakpoints、完整组件 HTML/CSS snippet（panel 把这些渲染进 shadow DOM）以及叙事层（north star、rules、do's/don'ts）。它扩展 frontmatter，而不是重复它。凡是重新生成根 DESIGN.md 时都必须重新生成 sidecar；若用户只要求刷新 sidecar（例如来自 live panel 的 stale-hint），则应保留 DESIGN.md 只写 .impeccable/design.json。

规范给出了完整 schema 参考：

{
  "schemaVersion": 2,
  "generatedAt": "ISO-8601 string",
  "title": "Design System: [Project Title]",
  "extensions": {
    "colorMeta": {
      "primary":    { "role": "primary", "displayName": "Editorial Magenta", "canonical": "oklch(60% 0.25 350)", "tonalRamp": ["..."] },
      "cool-paper": { "role": "neutral", "displayName": "Cool Paper",    "canonical": "oklch(96% 0.005 230)", "tonalRamp": ["..."] }
    },
    "typographyMeta": {
      "display": { "displayName": "Display", "purpose": "Hero headlines only." }
    },
    "shadows": [
      { "name": "ambient-low", "value": "0 4px 24px rgba(0,0,0,0.12)", "purpose": "Diffuse hover glow under accent elements." }
    ],
    "motion": [
      { "name": "ease-standard", "value": "cubic-bezier(0.4, 0, 0.2, 1)", "purpose": "Default easing for state transitions." }
    ],
    "breakpoints": [
      { "name": "sm", "value": "640px" }
    ]
  },
  "components": [
    {
      "name": "Primary Button",
      "kind": "button | input | nav | chip | card | custom",
      "refersTo": "button-primary",
      "description": "One-line what and when.",
      "html": "<button class=\"ds-btn-primary\">SAVE CHANGES</button>",
      "css": ".ds-btn-primary { background: #191c1d; color: #fff; ... }"
    }
  ],
  "narrative": {
    "northStar": "The Editorial Sanctuary",
    "overview": "2-3 paragraphs of the philosophy, pulled from DESIGN.md Overview section.",
    "keyCharacteristics": ["...", "..."],
    "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }],
    "dos":   ["Do use ..."],
    "donts": ["Don't use ..."]
  }
}

schemaVersion 1 → 2 的变化：旧版 sidecar 携带 token primitive 数组（tokens.colors[]、tokens.typography[]），这些值现在移到 frontmatter；sidecar 只保留 frontmatter 放不下的元数据（tonal ramp、当 hex 只是近似值时的 canonical OKLCH、displayName、role hint），并以 frontmatter token 名作为 key（colorMeta.<token-name>、typographyMeta.<token-name>）。组件仍携带完整 HTML/CSS，因为 Stitch 的 8 属性集合装不下它们。

5.2 组件翻译规则：自包含、可直接注入 shadow DOM

html 与 css 字段必须是自包含、即插即用（drop-in）的 snippet，注入 shadow DOM 后可直接正确渲染。panel 直接应用它们：无后处理、无框架运行时。六条硬性规则：

1. Tailwind 展开：若源码用 Tailwind（className="bg-primary text-white rounded-lg px-6 py-3"），必须把每个工具类展开为 css 字符串中的字面 CSS 属性；不得引用 Tailwind 类、不得假设 Tailwind bundle 已加载——每个组件自包含。
2. Token 解析：若项目在 :root 上以 CSS 自定义属性暴露 token（如 --color-primary、--radius-md），用 var(--color-primary) 引用——它们会穿过 shadow DOM 继承并保持实时绑定；若 token 只存在于 JS theme 对象（styled-components、CSS-in-JS），则生成时解析为字面值。
3. 图标：以内联 SVG 形式给出。不引用 Lucide/Heroicons 包、图标字体或 <img src="...">；典型图标 16-24px，直接复制 SVG path 数据。
4. 状态：必须内联 :hover、:focus-visible，有意义时含 :active。只有静态默认快照的组件会让 panel 显得“死气沉沉”。
5. 重置膨胀控制：只抽取组件独有的 CSS（背景、颜色、padding、圆角、排版、transition）；跳过通用 reset（box-sizing、line-height: inherit、-webkit-font-smoothing）——panel 已有中性画布，不要重复运输 resets。
6. 作用域类名：每个类加 ds- 前缀（ds-btn-primary、ds-input-search），避免同一 shadow DOM 内不同组件的 CSS 互相碰撞。

5.3 收录范围与 tonal ramp

目标是精选 5-10 个最能代表视觉系统的组件：Canonical primitive（项目有则必含）为 button（每个 variant 单独一条）、input/text field、navigation、chip/tag、card；signature 组件（有特色就含）是那些反复出现、真正定义了实现系统的自定义模式；其余（utility 组件、表单积木、包裹布局）除非视觉独特否则不收录。若项目尚无组件库（裸 landing page、新项目），则依据 token 按 DESIGN.md 规则、用最佳实践默认值综合出 canonical primitive——每个 .impeccable/design.json 从第零天起都有可渲染的东西。

Tonal ramp：为每个颜色 token 生成 8 步数组，由暗到亮、保持同色相同彩度、亮度从约 15% 步进到约 95%（panel 在色块下方渲染为条带）。项目若已定义音阶（Material surface-container-low 家族、Tailwind 式 blue-50..blue-900）就用现有值，否则以 OKLCH 合成。

5.4 Narrative 映射：不转述

叙事字段直接从刚写好的 DESIGN.md 拉取，不要改写措辞：narrative.northStar ← Overview 的 **Creative North Star: "..."** 行；narrative.overview ← Overview 哲学段落；narrative.keyCharacteristics ← **Key Characteristics:** 要点列表；narrative.rules ← 全文所有 **The [Name] Rule.** [body]，标注 section；narrative.dos / narrative.donts ← Do's and Don'ts 的列表逐字复制。panel 把叙事作为次级可折叠上下文展示，Markdown 里的话语声音必须原样延续。

六、实战对照：demos/landing-demo 的 Lumina 设计系统

仓库自带的可运行示例 demos/landing-demo/DESIGN.md 与 demos/landing-demo/DESIGN.json 是理解上述全部规范的“标准答案”。这套系统叫 Lumina，North Star 是 "Editorial confidence in warm light"，frontmatter 与规范完全对应：

name: Lumina
description: Editorial-warm landing page for an AI-native workflow tool.
colors:
  cream: "#faf6ef"
  cream-warm: "#f4ebdc"
  peach: "#f6dfcb"
  line: "#e6dccb"
  ink: "#1f1a15"
  soft: "#5b4f44"
  accent: "#c8552b"
  accent-deep: "#a8431f"
typography:
  display:
    fontFamily: "Fraunces, Georgia, serif"
    fontSize: "clamp(3rem, 7vw, 5.5rem)"
    fontWeight: 400
    lineHeight: 1.05
    letterSpacing: "-0.02em"
rounded:
  card: "20px"
  icon: "14px"
  pill: "999px"
spacing:
  xs: "8px"
  sm: "16px"
  md: "24px"
  lg: "32px"
  xl: "56px"
  2xl: "80px"
  3xl: "120px"
components:
  button-primary:
    backgroundColor: "{colors.ink}"
    textColor: "{colors.cream}"
    rounded: "{rounded.pill}"
    padding: "14px 28px"

对照检查可以验证规范的可操作性：

• Colors 只分 Primary（Burnt Orange + Accent Deep）与 Neutral，未编造 Secondary/Tertiary；每个角色描述都说明在哪里、为什么（如 accent "Decorative; never a surface, never a button background"）；
• Typography 按角色对象建模，display/headline 用 Fraunces、body/label 用 Inter，并带 fallback；
• 组件引用 primitive：button-primary 的 rounded: "{rounded.pill}"、backgroundColor: "{colors.ink}" 正是 {path.to.token} 语法的实际落地；
• 8 属性上限与 variant 平铺都被遵守（button-primary / button-ghost / nav-pill / card / icon-tile 为兄弟 key）。

Markdown 正文则完整示范了 **Named Rules 与“先描述、技术值括注”**的写法，例如：

• The Cream-Family Rule. Every neutral surface tints toward the brand hue. No pure white anywhere, no pure black, no untinted gray.
• The 10% Accent Rule. The burnt orange covers no more than 10% of any rendered surface. Its rarity is the point.
• The One-Italic Rule. Italic appears exactly once per page: on a single emphasized word inside the hero headline.
• The No-Gradient-Text Rule. Type is solid color, always.
• The Flat-By-Default Rule. Surfaces are flat at rest. Hover lift uses transform: translateY(-1px), never a shadow.

正文还示范了“项目是扁平设计就显式说明深度如何传达”：Depth 由三种且仅三种方式表达——tonal layering（cream → cream-warm → ink 分层）、hairline borders（1px line 色）、sticky-nav 的 backdrop-filter: blur(10px)（系统里唯一的 blur）。

配套 demos/landing-demo/DESIGN.json 则逐条落实 sidecar 约定：

• extensions.colorMeta 用 frontmatter token 名作 key，补充 displayName、canonical OKLCH（如 cream 的 oklch(96.5% 0.012 80)）与 8 步 tonalRamp；
• extensions.motion 记录按钮 150ms ease、卡片 300ms ease；extensions.breakpoints 记录 container 1180px、logo-strip 1100px；extensions.shadows 为空数组——与正文 Flat-By-Default 一致；
• components 提供 7 个可直接渲染的组件（Primary Button、Ghost Button、Nav Pill、Eyebrow Chip、Feature Card、Hero Headline、Logo Strip Wordmark），css 全部带 ds- 前缀、字面属性展开、无外部依赖，hero 的 <em> 斜体强调恰好实现 The One-Italic Rule；
• narrative 的 rules/dos/donts 与 DESIGN.md 逐字一致（"Do not reword" 原则）。

把这对产物（DESIGN.md + DESIGN.json）与正文规范并排阅读，即可直观看出“token 进 frontmatter、装不下的进 sidecar、叙事双向对齐”的完整闭环。

七、风格准则与反模式：写一份真正会被遵守的规范

7.1 Style guidelines 摘要

准则	含义
Frontmatter first, prose second	token 进 YAML，散文负责语境；不得在两处重定义同一 token 值，frontmatter 是规范性的
Carry only durable product constraints	只有真正约束视觉系统的绑定资产（logo、身份资产、无障碍需求、品牌承诺）才能从 PRODUCT.md 进入 DESIGN.md；surface 策略留在 surface brief
Match the spec	八个 canonical 段落按序、无关即省；动效指引放受影响的 world/component 处，不创建 schema 不支持的 token 组
Descriptive > technical	"Gently curved edges (8px radius)" 优于 "rounded-lg"；描述打头、技术值括注
Functional > decorative	每个 token 说清 WHERE/WHY，不只说 WHAT
Use Named Rules	**The [Name] Rule.** [短教义]，比列表更易被 AI 消费者记住与引用，每节 1-3 条
Be decisive where evidence is decisive	真不变量用硬语气，暂定指引用软语气
Reference PRODUCT.md selectively	产品真相解释“world 为何成立”，不默认充当页面构图或 do/don't 清单来源
Group colors by role	按 Primary/Secondary/Tertiary/Neutral 角色分组，不按 hex 或色相排序

7.2 Pitfalls：文档层反模式清单

• 不要粘贴原始 CSS 类名——翻译成描述性语言；
• 不要抽取每一个 token——停在真正被复用的地方，一次性值会污染系统；
• 不要编造不存在的组件——项目只有按钮和卡片就只记录按钮和卡片；
• 不要不经询问覆盖已有 DESIGN.md；
• 不要重复 PRODUCT.md 内容——DESIGN.md 严格限于视觉；
• 不要用近义词替换 canonical 段落（Layout 放布局与响应式、动效跟受影响的 world/component 走）；
• 不要改动段落标题哪怕一点（"Colors" 不能改成 "Color Palette & Roles"）——解析依赖精确标题；
• 不要在 frontmatter 与散文间重复 token 值；
• 不要发明 frontmatter 顶层 token 组——Stitch 的 Zod schema 只接受 colors、typography、rounded、spacing、components，motion:、breakpoints:、shadows: 之类一律放进 sidecar 的 extensions。

这些约束共同保证一件事：DESIGN.md 是“跨工具可移植”的规范文档，而不是又一个只在单个会话里有效的 Markdown 备注。

八、Ground truth 原则与降级执行

规范隐含的最终原则是事实源头是已发布的产物。这在同目录降级角色的 degraded/documenter.md（Impeccable Documenter）中有更尖锐的表述：每条 token 与规则都必须由已构建代码证明，而不是由“计划”证明——"Writing the system after the fact is the point; a rulebook written before the build gets defended against reality instead of describing it"（先于构建写下的规则书会去对抗现实，而不是描述现实）。当方向契约（direction contract）的 OWN-WORLD 与最终构建出现分歧时，构建胜出，散文可注明分歧。该角色还警惕两种“记录错误”方式：禁令禁掉了 world 本身原生使用的装置，或用记录来为缺陷背书。craft-floor 层面的拒绝（如 kicker/eyebrow）不得被 canonize 进系统——一次违规变成“house style”正是通过文档层完成的。

对实际使用者，这些提示收敛为三条实操要点：写 DESIGN.md 时要对照真实样式表与组件采样而非脑补；与 .claude/skills/impeccable/reference/init.md（产品事实）与 .claude/skills/impeccable/reference/new-work.md（视觉世界创建）保持流程先后清晰：init 先建立产品语境，new-work 创建或替换 world，document 则始终记录已成文存在的视觉现实；在代码尚未存在时用 seed mode 写诚实占位符，一旦有代码即重跑 scan mode 让真实 token 落地——这正是 demos/landing-demo/DESIGN.md 这类完整产物得以持续保鲜的机制。