impeccable document 命令深度解析：DESIGN.md 设计系统文档的生成流程与 Stitch 令牌规范

impeccable document 命令深度解析DESIGN.md 设计系统文档的生成流程与 Stitch 令牌规范【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本篇技术指南聚焦 impeccable 的/impeccable document命令拆解它如何在项目根目录生成一份机器可读、人类与 LLM 均可消费的DESIGN.md设计系统文档从 YAML frontmatter 令牌 schema 的硬性规则到八个规范章节的固定顺序再到 Scan/Seed 双路径的完整操作流程与.impeccable/design.json侧车文件结构。读完后你可以独立撰写或审查一份符合 Stitch 格式的 DESIGN.md并理解 impeccable 底层解析器对该格式的实际消费方式。一、命令定位为 AI Agent 固化视觉系统document命令的职责一句话概括在项目根目录生成一个DESIGN.md文件捕获当前的视觉设计系统使得 AI Agent 在生成新界面时能保持在品牌之内。命令元数据中对它的官方描述是见 command-metadata.jsonGenerate a DESIGN.md file that captures the current visual design system. Auto-extracts colors, typography, spacing, radii, and component patterns from the codebase, then asks the user to confirm descriptive language for atmosphere and color character. Follows the Google Stitch DESIGN.md format so the file is tool-compatible.完整操作流程定义在 document.md该参考文档在 skill/reference/、cursor-plugin/skills/impeccable/ 等分发目录中各有一份镜像。它遵循官方 DESIGN.md 格式规范Google Stitch 生态维护可选的 YAML frontmatter 承载机器可读的设计令牌其后是按固定顺序排列的至多八个 Markdown 章节。令牌是规范性的normative散文只负责提供如何应用令牌的上文。章节在不相关时应当整体省略但存在的章节必须保持指定顺序使用规范标题才能让文件在 DESIGN.md 感知型工具之间保持可移植。二、Frontmatter令牌 Schema 与五条硬规则YAML frontmatter 是机器可读层——它既是格式校验器linter验证的对象也是 live 面板渲染色板/组件瓦片的直接数据源。原则是保持紧凑每一条都应对应项目真正使用的令牌。frontmatter 只允许五个顶层令牌组colors、typography、rounded、spacing、components。完整 schema 示例如下摘自参考文档原文--- 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} ---五条必须记住的规则Token 引用token refs使用{path.to.token}形式如{colors.primary}、{rounded.md}。组件可以引用基础令牌primitives但基础令牌之间不得互相引用。颜色接受任何合法 CSS 颜色字符串。十六进制是推荐默认值便于移植但当项目把某个rgb()、hsl()、oklch()、宽色域或混合颜色值当作规范性来源时必须原样保留不要无明确理由地拆分事实来源。组件子令牌component sub-tokens仅限 8 个属性backgroundColor、textColor、typography、rounded、padding、size、height、width。阴影、动效、focus 环、backdrop-filter 都不属于这个集合——它们要放进侧车文件Step 4b 的.impeccable/design.json。Scale 键是开放式的。用项目已经在用的名字oxblood-deep、surface-container-low不要改名为 Material 默认值。变体是命名约定不是 schema。button-primary/button-primary-hover/button-primary-active作为兄弟键并列。仓库根目录的 DESIGN.md 本身就是一个合规模板实例frontmatter 使用oklch()颜色、按角色命名的 typography 对象、rounded/spacing量表以及components组中大量{colors.kinpaku-gold}、{typography.title}形式的令牌引用——与上述 schema 完全一致。三、Markdown 正文八个规范章节正文至多八个章节顺序与标题都必须严格一致顺序规范标题承载内容1## Overview北极星隐喻、气质、Key Characteristics2## Colors按角色分组的调色板与命名规则3## Typography字体配对、层级、字号量表4## Layout网格、容器、断点、间距节奏、响应式5## Elevation Depth阴影词汇、色调分层、深度策略6## Shapes圆角、边框、裁剪、重复形态7## Components逐组件的形状/色彩/状态行为8## Dos and Donts具体视觉护栏不相关的章节应省略而不是填上虚构规则未知章节会被格式保留但新的视觉指导应优先使用规范结构。从底层解析器的正则见 design_md.rs 中的H2_RE看章节标题允许## 1. Overview: 副标题这种编号 冒号副标题的写法且标题匹配时会做大小写与撇号归一化、并支持关键词回退匹配match_canonical_section——但标题必须精确仍是对撰写者的要求因为不同工具的解析严格程度不同。四、何时运行 document 命令参考文档给出四个触发时机new-work 发现了一致既有的视觉系统但项目里没有DESIGN.md一个新世界的首次实现已完成其临时决策需要被碳化成炭carbonized固化既有DESIGN.md已过期设计已经漂移大型重设计之前先捕获当前状态作为参照。一条硬性红线若DESIGN.md已存在不得静默覆盖——先把现有文件展示给用户对无法推断的地方直接向用户提问由用户在 refresh刷新、overwrite覆盖、merge合并三者之间做选择。五、两条路径Scan 模式与 Seed 模式Scan 模式默认项目已有设计令牌、组件或可渲染产物。流程是先提取再向用户确认描述性语言。适用于有代码可分析的场景。Seed 模式项目尚处于实现前阶段。先确保PRODUCT.md存在然后复用 new-work 的视觉世界工作坊写下一份方向性的 DESIGN.md 种子等有了代码再重跑 Scan 模式。决策原则先扫描再决定。若扫描发现没有令牌、没有组件文件、也没有可渲染站点就提议 Seed 模式不得静默切换。/impeccable document --seed请求的是 new-work 的世界工作坊但不授权用一套新身份替换既有代码当既有系统存在时应提议 Scan 模式或把明确的替换品牌身份请求路由到 new-work。六、Scan 模式全流程Step 1按优先级查找设计资产按以下优先级搜索代码库CSS 自定义属性在 CSS 文件中 grep--color-、--font-、--spacing-、--radius-、--shadow-、--ease-、--duration-声明通常在src/styles/、public/css/、app/globals.css等位置。记录名称、取值与定义所在文件。Tailwind 配置若存在tailwind.config.{js,ts,mjs}读取theme.extend块中的 colors、fontFamily、spacing、borderRadius、boxShadow。CSS-in-JS 主题文件styled-components、emotion、vanilla-extract、stitches寻找theme.ts、tokens.ts或等价文件。设计令牌文件tokens.json、design-tokens.json、Style Dictionary 产物、W3C 令牌社区组格式。组件库扫描主要的 button、card、input、navigation、dialog 组件记录其变体 API 与默认样式。全局样式表根 CSS 文件通常承载基础排版与颜色分配。可见的渲染产物若有浏览器自动化工具可用加载线上站点并从关键元素body、h1、a、button、.card采样 computed styles——这能捕获令牌遗漏的取值。Step 2自动提取可自动提取的部分从发现的令牌构建结构化草稿按令牌类别处理颜色按 Primary / Secondary / Tertiary / Neutral 分组Stitch 使用的 Material 派生角色。若项目只有一个强调色表达为 Primary Neutral省略 Secondary 与 Tertiary而不是发明它们。排版把观察到的字号与字重映射到 Material 层级display / headline / title / body / label记录字体族栈与量表比率。高程Elevation编目阴影词汇表。若项目是扁平的、改用色调分层tonal layering那也是有效答案必须显式说明。组件对每个常见组件button、card、input、chip、list item、tooltip、nav提取形状圆角、颜色分配、hover/focus 处理与内边距。布局 间距把网格、容器、断点、节奏与密度行为提取进 Layout。形状把圆角、角、边框、裁剪与重复形态行为提取进 Shapes。Step 2b暂存 frontmatter在 Step 4 写 DESIGN.md 之前先把 YAML frontmatter 草拟出来最终会写在文件顶部Colors每个提取到的颜色一条。键 描述性 slugoxblood-deep、editorial-magenta而不是blue-800。值 项目视为规范的那一种格式OKLCH 或 hex见第二节规则。不要拆分事实来源frontmatter 里只用一种格式不要在散文里用不同值重新定义同一令牌。Typography每个角色一条display、headline、title、body、label。typography 是对象只包含项目真实存在的属性fontFamily、fontSize、fontWeight、lineHeight、letterSpacing、fontFeature、fontVariation。Rounded / Spacing项目实际使用的量表台阶用项目自己的量表名作键sm/md/lg或surface-sm或数字台阶。Components每个变体一条button-primary、button-primary-hover、button-ghost通过{colors.X}、{rounded.Y}引用基础令牌。若某变体需要 8 属性集合覆盖不到的属性阴影、focus 环、backdrop-filter把完整片段放进侧车。项目没有的东西一律跳过。空量表键或虚构令牌会污染规范。Step 3向用户征集定性语言以下内容无法自动提取需要创造性输入。分两轮结构化提问每轮不超过 3 个问题或 harness 允许的下限两轮之间等待Creative North Star整个系统的单一命名隐喻The Editorial Sanctuary、The Golden State Curator、The Lab Notebook。提供 2–3 个尊重PRODUCT.md品牌人格的选项。Overview voice2–3 句的气质形容词、审美哲学以及任何已确认的视觉反参照anti-reference。Color character为自动提取的颜色起描述性名称Deep Muted Teal-Navy 而非 blue-800。基于色相/饱和度为每个关键颜色建议 2–3 个选项。Elevation philosophyflat / layered / lifted若存在阴影其角色是 ambient 还是 structuralComponent philosophy用一句话概括 button、card、input 的手感tactile and confident 还是 refined and restrained。只有当PRODUCT.md中的某一行是真正约束视觉系统的持久品牌承诺时才引入它页面策略与 surface 概念不属于这里。Step 4写出 DESIGN.md文件以 Step 2b 暂存的 frontmatter 开头随后是规范结构的 Markdown 正文。完整模板如下摘自参考文档方括号为占位说明--- name: [Project Title] description: [one-line tagline] colors: # ... staged frontmatter from Step 2b --- # Design System: [Project Title] ## Overview **Creative North Star: [Named metaphor in quotes]** [2-3 段整体描述人格、密度、审美哲学。从北极星出发向外展开。只陈述已确认的视觉拒绝。以一段 **Key Characteristics:** 要点列表收尾。] ## Colors [一句话描述调色板气质。] ### Primary - **[Descriptive Name]** (#HEX / oklch(...)): [该颜色的使用位置与原因。具体到上下文而不只是角色。] ### Secondary (optional; omit if the project has only one accent) - **[Descriptive Name]** (#HEX): [Role.] ### Tertiary (optional) - **[Descriptive Name]** (#HEX): [Role.] ### Neutral - **[Descriptive Name]** (#HEX): [Text / background / border / divider role.] ### Named Rules (optional, powerful) **The [Rule Name] Rule.** [简短而有力的禁令或信条例如 The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point.] ## Typography **Display Font:** [Family] (with [fallback]) **Body Font:** [Family] (with [fallback]) **Label/Mono Font:** [Family, if distinct] **Character:** [1-2 句描述该字体配对的人格。] ### Hierarchy - **Display** ([weight], [size/clamp], [line-height]): [用途出现位置。] - **Headline** ([weight], [size], [line-height]): [用途。] - **Title** ([weight], [size], [line-height]): [用途。] - **Body** ([weight], [size], [line-height]): [用途。相关时附上最大行宽如 65–75ch。] - **Label** ([weight], [size], [letter-spacing], [case if uppercase]): [用途。] ### Named Rules (optional) **The [Rule Name] Rule.** [关于字体使用的简短信条。] ## Layout [描述网格或空间模型、容器行为、密度、响应式变化、间距节奏。只在有实测值时给出精确数值。] ## Elevation Depth [一段话系统使用阴影、色调分层还是混合若无阴影显式说明并用其他方式描述深度传达手段。] ### Shadow Vocabulary (if applicable) - **[Role name]** (box-shadow: [exact value]): [使用时机。] ### Named Rules (optional) **The [Rule Name] Rule.** [例如 The Flat-By-Default Rule. Surfaces are flat at rest. Shadows appear only as a response to state (hover, elevation, focus).] ## Shapes [描述形态语言圆角策略、边框、裁剪、以及任何重复的剪影或几何。] ## Components 每个组件先写一句气质短句再规定形状、颜色分配、状态与任何标志性行为。 ### Buttons - **Shape:** [圆角的描述括号内给精确值] - **Primary:** [颜色分配 内边距语义 精确表述] - **Hover / Focus:** [过渡与处理方式] - **Secondary / Ghost / Tertiary (if applicable):** [简要描述] ### Chips (if used) - **Style:** [背景、文字颜色、边框处理] - **State:** [选中 / 未选中筛选 / 操作变体] ### Cards / Containers - **Corner Style:** [radius] - **Background:** [使用的颜色] - **Shadow Strategy:** [引用 Elevation 章节] - **Border:** [if any] - **Internal Padding:** [scale] ### Inputs / Fields - **Style:** [stroke, background, radius] - **Focus:** [处理方式如 glow、边框位移等] - **Error / Disabled:** [if applicable] ### Navigation - **Style, typography, default/hover/active states, mobile treatment.** ### [Signature Component] (optional; if the project has a distinctive custom component worth documenting) [Description.] ## Dos and Donts 基于既有实现或用户所选世界给出具体视觉护栏。每条以 Do 或 Dont 开头只在已确立时给精确值。不要把任务级概念或 surface 策略升格为系统级禁令。 ### Do: - **Do** [具体处方含精确值 / 命名规则]. - **Do** [...] ### Dont: - **Dont** [既有系统或用户确认的具体禁令]. - **Dont** [...]Step 4b写.impeccable/design.json侧车仅扩展信息frontmatter 拥有令牌基础colors、typography、rounded、spacing、components。而.impeccable/design.json侧车承载Stitch schema 装不下的东西每个颜色的色调斜坡tonal ramp、阴影/高程令牌、动效令牌、断点、完整组件 HTML/CSS 片段面板把它们渲染进 shadow DOM、以及叙述性内容北极星、规则、Do/Dont。侧车扩展 frontmatter而不是复制它。规则每次重新生成根目录DESIGN.md时必须同步重新生成侧车。若用户只要求刷新侧车例如来自 live 面板的过期提示保留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; padding: 16px 48px; letter-spacing: 0.05em; text-transform: uppercase; font-weight: 500; border: none; border-radius: 0; transition: background 0.2s, transform 0.2s; } .ds-btn-primary:hover { background: oklch(60% 0.25 350); transform: translateY(-2px); } } ], 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: [Dont use ...] } }相比 schemaVersion 1 的变化旧侧车承载令牌基础数组tokens.colors[]、tokens.typography[]等这些值现在都进了 frontmatter。侧车只保留 frontmatter 装不下的元数据tonal ramp、hex 为近似值时的规范 OKLCH、展示名、角色提示并以 frontmatter 令牌名为键colorMeta.token-name、typographyMeta.token-name。组件仍携带完整 HTML/CSS因为 Stitch 的 8 属性集合装不下它们。组件翻译规则。html与css字段必须是自包含、可直接注入的片段在 shadow DOM 中注入后能正确渲染。面板直接应用它们无后处理、无框架运行时。具体六条Tailwind 展开。若源码使用 TailwindclassNamebg-primary text-white rounded-lg px-6 py-3把每个工具类展开为css字符串中的字面 CSS 属性。不要引用 Tailwind 类不要假设加载了 Tailwind CSS bundle。每个组件自包含。令牌解析。若项目把令牌作为:root上的 CSS 自定义属性暴露如--color-primary、--radius-md用var(--color-primary)引用——它们会穿透 shadow DOM 并保持实时绑定。若令牌只存在于 JS 主题对象中styled-components、CSS-in-JS在生成时解析为字面值。图标。内联为 SVG。不要引用 Lucide/Heroicons 包、图标字体或img src...。典型图标 16–24px直接拷贝 SVG path 数据。状态。内联包含:hover、:focus-visible以及若有意义:active规则。只有静态默认态的快照会让面板显得死气沉沉hover focus 规则让它活起来。去掉 reset 冗余。只提取组件有辨识度的 CSSbackground、color、padding、border-radius、typography、transition。跳过通用 resetbox-sizing: border-box、line-height: inherit、-webkit-font-smoothing。面板已有中性画布不要重复搬运 reset。作用域类名。所有类名加ds-前缀如ds-btn-primary、ds-input-search避免同一 shadow DOM 中组件 CSS 互相碰撞。收录范围目标是精选5–10 个最能代表视觉系统的组件规范基础组件有则必录button每个变体作为独立条目、input/text field、navigation、chip/tag、card。签名组件有辨识度就收录真正定义已实现系统的重复自定义模式。其余跳过。工具类组件、表单积木、包裹布局除非视觉上有辨识度否则不值得记录。若项目还没有组件库裸落地页、新项目从令牌出发、用与 DESIGN.md 规则一致的实践默认值合成规范基础组件。每一份.impeccable/design.json都有东西可渲染即使是在第零天。Tonal ramp色调斜坡为每个颜色令牌生成 8 步tonalRamp数组从暗到亮、同色相同彩度、明度从约 15% 到约 95% 递进。面板把它渲染为色块下方的一条色带。若项目已定义色调量表Material 的surface-container-low家族、Tailwind 风格blue-50..blue-900直接用那些值否则用 OKLCH 合成。Narrative 映射直接从刚写好的 DESIGN.md 抽取不做改写面板把这些作为可折叠的次级上下文展示Markdown 里的声音原样延续narrative.northStar→ Overview 中的**Creative North Star: ...**行narrative.overview→ Overview 的哲学段落narrative.keyCharacteristics→**Key Characteristics:**要点列表narrative.rules→ 所有章节中的每条**The [Name] Rule.** [body]带section标签narrative.dos/narrative.donts→ Dos and Donts 的要点列表逐字照搬Step 5确认与打磨向用户展示完整的 DESIGN.md简要点出非显而易见的创意决策描述性颜色名、氛围语言、命名规则。说明.impeccable/design.json也已一并写入live 面板现在渲染的是该项目真实的 button/input/nav 基础组件而非通用近似值。主动提出打磨建议需要我修改某个章节、补上遗漏的组件模式还是调整氛围语言自己刚写下的内容就是最新鲜的信息源本会话后续命令无需重新加载。七、Seed 模式实现前的方向性脚手架用于尚无可提取视觉系统的项目。产物是用户选定的视觉世界脚手架而不是伪造的令牌规范。Step 1路由到 new-work 的工作坊PRODUCT.md是前置条件。缺失时先加载 init.md 完成产品访谈——没有持久产品上下文就不要创建视觉身份。PRODUCT.md存在时加载 new-work.md 并解决视觉权威问题。Seed 模式需要一个具体的首屏使用用户指定的目标或询问他们想先做什么。执行 new-work 的Create or replace the visual world流程然后Commit the world让视觉世界与其第一次表达被一起选定。到方向性 DESIGN.md 种子与 surface brief 为止停下不要实现。结构化模拟用户视同真实用户必须得到同样的选择权。若 new-work 本会话已完成工作坊直接使用其选定方向不再追问。Step 2写种子 DESIGN.md沿用 Scan 模式的规范章节顺序填入工作坊选定的方向把未解决的实现事实留成诚实占位符。种子承诺的是世界及其不变量不假装实现令牌已经存在。文件开头先放标记!-- SEED: established with the user before implementation; re-run /impeccable document once theres code to capture the actual tokens and components. --各章节在 Seed 模式下的指引Overview选定的设计论点、布局行为、材质人格、影像立场、动效语法、可复用签名。首屏的具体表达留在它的 surface brief 里不要升格为全球世界。Colors选定的调色板策略与角色。只有当用户、既有资产或 new-work 探索确立了取值时才写值否则标记[to be resolved during implementation]。Typography选定的字体人格与角色关系。字体名同理未确立则标记[to be resolved during implementation]。Layout选定的空间语法与响应式行为不假装精确测量已定型。Elevation Depth选定的材质与深度行为作为不变量陈述而非从通用预设推断。Shapes选定的形态与圆角语言。Components整节省略组件尚不存在。Dos and Donts记录选世界过程中确认的持久护栏而不是任务级拒绝。Seed 模式只写最小 frontmatter仅name与description没有 colors、typography、rounded、spacing、components。真实令牌在下次 Scan 模式运行时落地。侧车同样跳过没有东西可渲染。Step 3确认展示种子 DESIGN.md明确指出它是种子那个标记就是字面承诺。告诉用户等有了代码重跑/impeccable document。那一轮会提取真实令牌并生成侧车。八、源码级印证解析器如何消费 DESIGN.md文档中的格式规定并非纸面约束——仓库内有一个与之严格对应的实现。crates/live/src/design_md.rs 的文件头注释说明它是 JS 版parseDesignMd的字节级一致移植byte-for-byte paritylive 服务器把解析结果作为/design-system.json的parsed字段交给设计面板。其中可以直接对上文格式条款逐条印证八个规范章节CANONICAL_SECTIONS常量数组按固定顺序定义了Overview、Colors、Typography、Layout、Elevation、Shapes、Components、Dos and Donts数组顺序同时就是匹配优先级L15-L24。这解释了为什么章节标题不能随意改名——Colors 不能写成 Color Palette Roles。Frontmatter YAML 子集解析parse_frontmatter与parse_yaml_subset只实现了一个紧凑的 YAML 子集两层缩进、标量、引号、注释并按 JSOrdinaryOwnPropertyKeys的键序规则数字键升序在前、其余按插入顺序见 js_key_order重排键保证与JSON.stringify输出逐字节一致。命名规则Named Rules的三种书写风格都被识别行内**The X Rule.**形式Impeccable 风格、H3 标题形式Stitch 风格、要点列表形式Stitch 风格分别由 extract_named_rules 中的三套正则处理。这就是为什么参考文档建议每节 1–3 条命名规则——它们是可被机器提取的独立实体而不只是修辞。北极星与 Key Characteristics同样有专门正则NORTH_STAR_RE精确匹配**Creative North Star: ...**行KEYCHAR_RE提取**Key Characteristics:**之后到下一个章节头之间的要点L427-L436。若你的 DESIGN.md 想被面板正确解析这两行的格式必须严格一致。侧车的下游消费者crates/detect/src/design_system.rs 在读取设计系统时直接加载.impeccable/design.json说明侧车不只是 live 面板的数据也是检测器理解项目色彩体系的输入。从仓库根目录的 DESIGN.md 还可以看到该格式在自举场景下的真实用法impeccable 用它自己的规范描述自己的 Neo Kinpaku 系统frontmatter 注释明确写着下方所有值逐字镜像site/styles/kinpaku-tokens.css该文件是事实来源这份 frontmatter 是它的可移植导出——这正是frontmatter 是规范性导出、不重复定义原则的示范。九、风格指南写作 DESIGN.md 的十条原则Frontmatter first, prose second.令牌进 YAML frontmatter散文负责语境化。不要把同一令牌值重定义在两处——frontmatter 是规范。只携带持久的产品约束。PRODUCT.md中有约束力的 logo、身份资产、可访问性需求或品牌承诺可以约束 DESIGN.mdsurface 策略留在 surface brief。贴合规范。八个规范章节按序使用无关章节省略。动效指导跟随它所影响的世界或组件不要创建 schema 不支持的令牌组。Descriptive technicalGently curved edges (8px radius) 优于 rounded-lg。技术值放括号里描述打头。Functional decorative每个令牌解释 WHERE 和 WHY而不只是 WHAT。Exact values in parenshex、px/rem、字重——描述旁边永远跟上括号里的精确数值。使用命名规则**The [Name] Rule.** [short doctrine]。它们可记忆、可引用对 AI 消费者远比要点列表粘性强The No-Line Rule、The Ghost Border Fallback。每节目标 1–3 条。证据确凿处下硬结论。真正的不变量用硬语言临时性指导用软语言。审计测试只在有系统观察或用户确认时给出。一句话的测试胜过一段原则。选择性地引用 PRODUCT.md。产品真相解释世界为何契合默认不提供页面构成或视觉 dont-list。颜色按角色分组而不是按 hex 顺序或色相顺序。Primary / Secondary / Tertiary / Neutral 是规范顺序。十、常见陷阱清单不要粘贴原始 CSS 类名翻译成描述性语言。不要提取所有令牌止步于真正被复用的部分一次性取值会污染系统。不要发明不存在的组件。项目只有 button 和 card就只写这两个。不要未询问就覆盖既有 DESIGN.md。不要复制PRODUCT.md的内容——DESIGN.md 严格只谈视觉。不要用近义标题替换规范章节布局与响应式行为放Layout动效跟随受影响的世界或组件。章节名一个字母都不要改Colors 而非 Color Palette RolesTypography 而非 Typography Rules。工具解析依赖精确标题。不要在 frontmatter 与散文之间重复令牌值。颜色若以 hex 写在colors.primary散文可以命名它、描述它的角色但不得重申另一个 hex。frontmatter 是规范。不要发明 Stitch schema 之外的 frontmatter 令牌组顶层禁止motion:、breakpoints:、shadows:。Zod schema 只接受colors、typography、rounded、spacing、components其余一律进侧车的extensions。十一、小结/impeccable document的本质是一条视觉事实固化流水线Scan 模式从 CSS 变量、Tailwind 配置、CSS-in-JS 主题、令牌文件、组件库与渲染产物中自动提取事实层再经两轮结构化提问补齐无法提取的定性层最终产出frontmatter 规范令牌 八章节叙事正文 侧车扩展三层结构Seed 模式则在零代码阶段只承诺世界与不变量把真实令牌留给下一次扫描。对 Agent 与工具链而言这份 DESIGN.md 是生成新界面时保持 on-brand 的单一事实来源对仓库自身而言design_md.rs 的解析器与 DESIGN.md 的自举实例共同证明了这套格式在实现层面的闭环。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考