1. Overview【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable2. Colors3. Typography4. Layout5. Elevation Depth6. Shapes7. Components8. Dos and Donts 注意规范顺序是本仓库文档给出的顺序真实的 [demos/landing-demo/DESIGN.md](https://link.gitcode.com/i/dd488f075cc1922b8223c590e64e3d08) 示例省略了不相干小节无 Layout、Shapes并按“1. Overview、2. Colors、3. Typography、4. Elevation、5. Components、6. Dos and Donts”组织——这正是文档所说“**省略不相关小节而不是用编造的规则填充**”的体现。未知小节格式会被保留forward-compatible但新视觉指导应优先使用规范结构。 各小节职责划分摘自文档 - **Overview**Creative North Star创意北极星带引号的命名隐喻 2~3 段整体描述人格、密度、审美哲学以 **Key Characteristics:** 要点列表收尾。只陈述确认过的视觉反参考anti-references。 - **Colors**按角色分组Primary / Secondary / Tertiary / Neutral而不是按 hex 或色相排序。每个颜色给出描述性名称与使用场景WHERE/WHY可选 Named Rules。 - **Typography**Display/Body/Label 字体配对 分层层级Display/Headline/Title/Body/Label每层注明字重、字号、行高、用途。 - **Layout**网格或空间模型、容器行为、密度、响应式变化、间距节奏只有观测到确切值时才给出精确值。 - **Elevation Depth**明确该系统用阴影、色调分层tonal layering还是混合方案若是“无阴影”要明确写出并说明深度如何传达。可选 Shadow Vocabulary。 - **Shapes**角/圆角策略、边框、裁切与反复出现的造型语言。 - **Components**每个组件先给一句性格描述再说明造型、配色、状态与独特行为Buttons、Chips、Cards、Inputs、Navigation 及可选 Signature Component。 - **Dos and Donts**以“Do/Dont”开头给出具体视觉护栏只有已被既有实现或用户确认的条目才写任务级的具体概念不应上升为系统级禁令。 **Named Rules 是全文的粘合剂****The [Name] Rule.** [short doctrine]如 Stitch 输出中常见的 “The No-Line Rule”、“The Ghost Border Fallback”。文档强调它们“对 AI 消费者比项目符号更难忘、更可引用”每节建议 1~3 条。demos 中落地了五个具名规则 - **The Cream-Family Rule**colors所有中性面都向品牌色相靠拢任何地方都没有纯白、纯黑或未着色的灰。 - **The 10% Accent Rule**colors烧橙色覆盖不超过任何渲染表面的 10%稀缺才是重点。 - **The One-Italic Rule**typography斜体每页只出现一次位于 hero 标题的单个强调词内。 - **The No-Gradient-Text Rule**typography文字永远是纯色hero 的奶油到桃色渐变只是区块背景。 - **The Flat-By-Default Rule**elevation静止时表面是平的hover 抬升用 transform: translateY(-1px)绝不用阴影。 --- ## 四、何时运行 document触发条件与覆盖保护 ### 4.1 触发时机 文档列出的四种典型场景 - new-work 发现存在自洽的既有视觉系统但没有 DESIGN.md - 新世界的首次实现完成临时决定需要“碳化”carbonize为正式规范 - 现有 DESIGN.md 已过期设计漂移design drifted - 大型重设计之前把当前状态作为参考基线固化下来。 ### 4.2 覆盖保护绝不静默覆盖 **如果 DESIGN.md 已存在绝不要静默覆盖。** 先向用户展示现有文件然后给出 refresh / overwrite / merge 三种选择{{ask_instruction}}。 这条规则在仓库的 context 层有对应的状态信号支撑例如 [crates/context/src/context_cli.rs](https://link.gitcode.com/i/925c4e34ca985aa50b5ce6c272c3ad8f) 中的 NO_PRODUCT_MD、EXISTING_VISUAL_SYSTEM、INCUMBENT_WORLD_UNDOCUMENTED 等指令都会区分“已有视觉实现但缺文档”与“真正全新的项目”并给出是否先走 init/new-work 的路由建议。 --- ## 五、两条生成路径Scan mode 与 Seed mode document 有两种模式**先扫描再决定**Decide by scanning first | 模式 | 适用场景 | 产出 | |---|---|---| | **Scan mode**默认 | 项目已有设计令牌、组件或渲染输出有代码可分析 | 自动抽取令牌 → 向用户确认定性语言 → 写出完整 DESIGN.md sidecar | | **Seed mode** | 项目尚在实现之前没有可抽取的视觉系统 | 通过 new-work 的视觉世界工作坊确立方向写出带 SEED 标记的方向性 DESIGN.md 种子 | 关键约束**先扫描Scan mode Step 1。** 如果扫描发现没有令牌、没有组件文件、也没有渲染站点才提供 seed mode**不要静默切换**。/impeccable document --seed 会请求 new-work 的世界工作坊但它不授权替换自洽的既有代码——当存在既有系统时应提供 scan mode或将明确的“身份替换”请求路由给 new-work。 --- ## 六、Scan mode 实战从发现资产到确认定性语言 Scan mode 的完整工作流为**发现资产 → 自动抽取 → 起草 frontmatter → 询问定性语言 → 写文件 → 确认精修**。 ### Step 1按优先级发现设计资产 按文档给定的优先级顺序搜索代码库 1. **CSS 自定义属性**在 CSS 文件中 grep --color-、--font-、--spacing-、--radius-、--shadow-、--ease-、--duration- 声明常见位置src/styles/、public/css/、app/globals.css记录名称、值与定义文件。 2. **Tailwind 配置**若存在 tailwind.config.{js,ts,mjs}读取 theme.extend 中的 colors、fontFamily、spacing、borderRadius、boxShadow。 3. **CSS-in-JS 主题文件**styled-components、emotion、vanilla-extract、stitches查找 theme.ts、tokens.ts 等。 4. **设计令牌文件**tokens.json、design-tokens.json、Style Dictionary 输出、W3C token community group 格式。 5. **组件库**扫描主按钮、卡片、输入框、导航、对话框组件记录其变体 API 与默认样式。 6. **全局样式表**根 CSS 通常承载基础排版与颜色分配。 7. **可见渲染输出**若浏览器自动化可用加载线上站点对关键元素body、h1、a、button、.card采样 computed styles——这能捕捉令牌遗漏的值。 ### Step 2自动抽取结构化草稿 对每类令牌执行抽取 - **Colors**分组为 Primary / Secondary / Tertiary / NeutralStitch 使用的 Material 派生角色。若项目只有一个强调色就表达为 Primary Neutral**省略 Secondary/Tertiary 而不是编造**。 - **Typography**将观测到的字号/字重映射到 Material 层级display / headline / title / body / label记录字体栈与缩放比。 - **Elevation**清点阴影词汇表。如果项目是扁平风、用色调分层表达深度那也是合法答案要明确写出来。 - **Components**对每个常见组件button、card、input、chip、list item、tooltip、nav抽取造型圆角、配色、hover/focus 处理、内边距。 - **Layout spacing**把网格、容器、断点、节奏、密度行为归入 Layout。 - **Shapes**把圆角、边角、边框、裁切与反复出现的造型行为归入 Shapes。 ### Step 2b起草 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 ring、backdrop-filter把完整片段放进 sidecar。 原则**跳过项目没有的东西。** 空的刻度键或捏造的令牌会污染规范。 ### Step 3向用户询问定性语言两轮每轮最多三问 以下内容无法自动抽取需要创造性输入**分两轮、每轮不超过三个问题**或 harness 的更低上限两轮之间等待用户回复 - **Creative North Star**为整个系统命名的单个隐喻如 “The Editorial Sanctuary”、“The Golden State Curator”、“The Lab Notebook”提供 2~3 个尊重 PRODUCT.md 品牌人格的选项。 - **Overview voice**情绪形容词、2~3 句审美哲学、确认过的视觉反参考。 - **Color character**为自动抽取的颜色取描述性名称“Deep Muted Teal-Navy”而非 “blue-800”基于色相/饱和度建议每色 2~3 个选项。 - **Elevation philosophy**flat / layered / lifted若有阴影其角色是 ambient环境还是 structural结构。 - **Component philosophy**用一句话描述按钮、卡片、输入框的感觉“tactile and confident” vs “refined and restrained”。 只有 PRODUCT.md 中**持久性的品牌承诺**约束视觉系统的部分才可以被带入 DESIGN.md页面策略与表面概念不属于这里。 ### Step 4写 DESIGN.md 文件以 Step 2b 起草的 YAML frontmatter 开头随后是规范结构的 Markdown 正文。文档给出了完整的正文模板见第四节结构 完整示例模板关键填充指引 - Overview 从 North Star 出发向外展开只陈述确认过的视觉拒绝以 **Key Characteristics:** 列表收尾 - 每个颜色条目遵循 **Descriptive Name** (#HEX / oklch(...)): [Where and why this color is used] 的格式强调具体语境而非仅角色 - Dos and Donts 中的条目只有在既有实现或用户决定支撑时才写一句话的审计测试胜过一段原则。 ### Step 5确认与精修 1. 向用户展示完整的 DESIGN.md突出非显而易见的创意选择描述性颜色名、氛围语言、具名规则。 2. 说明 .impeccable/design.json 也已一并写出live panel 将渲染该项目的真实按钮/输入框/导航原语而不是通用近似物。 3. 主动提供精修“Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?”可意译为需要我修改某节、补充遗漏的组件模式或调整氛围语言吗 本次会话中你自己写出的文件就是最新来源后续命令无需 reload。 --- ## 七、Step 4b.impeccable/design.json sidecar扩展层 ### 7.1 分工与再生成原则 frontmatter 拥有令牌原语colors、typography、rounded、spacing、components**sidecar 携带 Stitch schema 装不下的东西** - 每个颜色的色调渐变tonal ramps - 阴影/抬升令牌、动效令牌、断点 - 完整组件 HTML/CSS 片段panel 渲染进 shadow DOM - 叙述层north star、rules、dos/donts sidecar **扩展** frontmatter不重复它。每当重新生成根 DESIGN.md 时都要重新生成 sidecar如果用户只想刷新 sidecar例如 live panel 的 stale-hint 提示则保留 DESIGN.md只写 .impeccable/design.json。 ### 7.2 SchemaschemaVersion 2 json { 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 ...] } }仓库的真实实现 demos/landing-demo/DESIGN.json 完整展示了这一 schema8 个colorMeta条目每个含role、displayName、canonicalOKLCH 值与 8 步tonalRamp、6 个typographyMeta、2 个motion令牌、2 个breakpoints、7 个组件含refersTo与可注入 shadow DOM 的html/css以及完整的narrativenorthStar、overview、5 条 rules、5 条 dos、5 条 donts。7.3 从 schemaVersion 1 到 2 的变化旧版 sidecar 携带令牌原语数组tokens.colors[]、tokens.typography[]等。这些值现在移入 frontmattersidecar 只携带 frontmatter 放不下的元数据色调渐变、当 hex 只是近似时的规范 OKLCH、显示名、角色提示并以 frontmatter 令牌名为键colorMeta.token-name、typographyMeta.token-name。组件仍携带完整 HTML/CSS因为 Stitch 的 8 属性集装不下它们。schema 版本常量对应实现DESIGN_SIDECAR_SCHEMA_VERSION 2crates/context/src/artifact_schema.rs。7.4 组件翻译规则自包含、可直接注入 shadow DOMhtml与css字段必须是自包含、即插即用的片段注入 shadow DOM 后能正确渲染。panel 直接应用它们无后处理、无框架运行时。六条硬规则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 继承并保持 live-bound若令牌只存在于 JS 主题对象styled-components、CSS-in-JS则在生成时解析为字面值。图标内联为 SVG。不要引用 Lucide/Heroicons 包、图标字体或img src...。典型图标 16–24px直接复制 SVG path 数据。状态内联包含:hover、:focus-visible以及有意义的:active规则。只有静态默认快照会让 panel 显得死板CSS 中的 hover focus 规则让它有生命感。重置去冗余只抽取组件的特色CSS背景、颜色、内边距、圆角、排版、过渡。跳过通用 resetbox-sizing: border-box、line-height: inherit、-webkit-font-smoothing——panel 已有中性画布不需要重新携带 reset。作用域类名每个类以ds-前缀如ds-btn-primary、ds-input-search避免同一 shadow DOM 内组件间 CSS 冲突。7.5 内容选择5~10 个代表性组件目标是精选 5~10 个最能代表视觉系统的组件规范原语项目有则必含button每个变体作为独立组件条目、input/文本框、navigation、chip/tag、card。签名组件有特色才含定义已实现系统的反复出现的自定义模式。跳过其余工具组件、表单积木、包裹布局——除非视觉上有特色否则不值得记录。若项目还没有组件库裸落地页、新项目可从令牌出发、用与 DESIGN.md 规则一致的最佳实践默认值合成规范原语——每个.impeccable/design.json都至少有东西可渲染哪怕是在第零天。7.6 色调渐变Tonal ramps对每个颜色令牌生成 8 步tonalRamp数组从暗到亮保持同一色相与色度chroma亮度从约 15% 步进到约 95%。panel 把渐变渲染为色卡下方的条带。若项目已定义自己的色调标尺Materialsurface-container-low家族、Tailwind 风格blue-50..blue-900使用这些值否则在 OKLCH 中合成。demos 中的creamramp 从oklch(15% 0.012 80)到oklch(96.5% 0.012 80)即为典型示例。7.7 叙述映射Narrative mapping直接从刚写好的 DESIGN.md 搬运不改写panel 把它们作为次级可折叠上下文展示与 Markdown 中相同的声音需要延续sidecar 字段来源DESIGN.md 中narrative.northStarOverview 的**Creative North Star: ...**行narrative.overviewOverview 的哲学段落narrative.keyCharacteristics**Key Characteristics:**要点列表narrative.rules全文所有**The [Name] Rule.** [body]标注sectionnarrative.dos/narrative.dontsDos and Donts 的要点列表逐字八、Seed mode实现之前的视觉世界种子Seed mode 适用于还没有可抽取视觉系统的项目产出的是“用户选择的视觉世界脚手架”而不是编造的令牌规格。Step 1经由 new-work 的工作坊路由PRODUCT.md 是前置条件。若缺失先加载 skill/reference/init.md 完成产品访谈——没有持久的产品语境不要创建视觉身份。若 PRODUCT.md 存在加载 skill/reference/new-work.md 解决视觉权威问题。Seed mode 需要一个具体的首面first surface使用用户指定的 target或询问用户想先做什么。运行 new-work 的Create or replace the visual world流程然后Commit the world让视觉世界与它的首面表达一起被选定。在方向性 DESIGN.md 种子与 surface brief 之后停止不要实现。结构化的模拟用户也算用户必须获得同样的选择权。若本次会话中 new-work 已完成工作坊直接使用其选定方向不要重复询问。Step 2写 seed DESIGN.md使用与 Scan mode 相同的规范小节顺序填充选定的工作坊方向未决的实现事实留作诚实的占位符。种子承诺一个世界及其不变量不假装实现令牌已经存在。文件以如下 SEED 标记开头!-- SEED: established with the user before implementation; re-run /impeccable document once theres code to capture the actual tokens and components. --【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 1. Overview
1. Overview【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable2. Colors3. Typography4. Layout5. Elevation Depth6. Shapes7. Components8. Dos and Donts 注意规范顺序是本仓库文档给出的顺序真实的 [demos/landing-demo/DESIGN.md](https://link.gitcode.com/i/dd488f075cc1922b8223c590e64e3d08) 示例省略了不相干小节无 Layout、Shapes并按“1. Overview、2. Colors、3. Typography、4. Elevation、5. Components、6. Dos and Donts”组织——这正是文档所说“**省略不相关小节而不是用编造的规则填充**”的体现。未知小节格式会被保留forward-compatible但新视觉指导应优先使用规范结构。 各小节职责划分摘自文档 - **Overview**Creative North Star创意北极星带引号的命名隐喻 2~3 段整体描述人格、密度、审美哲学以 **Key Characteristics:** 要点列表收尾。只陈述确认过的视觉反参考anti-references。 - **Colors**按角色分组Primary / Secondary / Tertiary / Neutral而不是按 hex 或色相排序。每个颜色给出描述性名称与使用场景WHERE/WHY可选 Named Rules。 - **Typography**Display/Body/Label 字体配对 分层层级Display/Headline/Title/Body/Label每层注明字重、字号、行高、用途。 - **Layout**网格或空间模型、容器行为、密度、响应式变化、间距节奏只有观测到确切值时才给出精确值。 - **Elevation Depth**明确该系统用阴影、色调分层tonal layering还是混合方案若是“无阴影”要明确写出并说明深度如何传达。可选 Shadow Vocabulary。 - **Shapes**角/圆角策略、边框、裁切与反复出现的造型语言。 - **Components**每个组件先给一句性格描述再说明造型、配色、状态与独特行为Buttons、Chips、Cards、Inputs、Navigation 及可选 Signature Component。 - **Dos and Donts**以“Do/Dont”开头给出具体视觉护栏只有已被既有实现或用户确认的条目才写任务级的具体概念不应上升为系统级禁令。 **Named Rules 是全文的粘合剂****The [Name] Rule.** [short doctrine]如 Stitch 输出中常见的 “The No-Line Rule”、“The Ghost Border Fallback”。文档强调它们“对 AI 消费者比项目符号更难忘、更可引用”每节建议 1~3 条。demos 中落地了五个具名规则 - **The Cream-Family Rule**colors所有中性面都向品牌色相靠拢任何地方都没有纯白、纯黑或未着色的灰。 - **The 10% Accent Rule**colors烧橙色覆盖不超过任何渲染表面的 10%稀缺才是重点。 - **The One-Italic Rule**typography斜体每页只出现一次位于 hero 标题的单个强调词内。 - **The No-Gradient-Text Rule**typography文字永远是纯色hero 的奶油到桃色渐变只是区块背景。 - **The Flat-By-Default Rule**elevation静止时表面是平的hover 抬升用 transform: translateY(-1px)绝不用阴影。 --- ## 四、何时运行 document触发条件与覆盖保护 ### 4.1 触发时机 文档列出的四种典型场景 - new-work 发现存在自洽的既有视觉系统但没有 DESIGN.md - 新世界的首次实现完成临时决定需要“碳化”carbonize为正式规范 - 现有 DESIGN.md 已过期设计漂移design drifted - 大型重设计之前把当前状态作为参考基线固化下来。 ### 4.2 覆盖保护绝不静默覆盖 **如果 DESIGN.md 已存在绝不要静默覆盖。** 先向用户展示现有文件然后给出 refresh / overwrite / merge 三种选择{{ask_instruction}}。 这条规则在仓库的 context 层有对应的状态信号支撑例如 [crates/context/src/context_cli.rs](https://link.gitcode.com/i/925c4e34ca985aa50b5ce6c272c3ad8f) 中的 NO_PRODUCT_MD、EXISTING_VISUAL_SYSTEM、INCUMBENT_WORLD_UNDOCUMENTED 等指令都会区分“已有视觉实现但缺文档”与“真正全新的项目”并给出是否先走 init/new-work 的路由建议。 --- ## 五、两条生成路径Scan mode 与 Seed mode document 有两种模式**先扫描再决定**Decide by scanning first | 模式 | 适用场景 | 产出 | |---|---|---| | **Scan mode**默认 | 项目已有设计令牌、组件或渲染输出有代码可分析 | 自动抽取令牌 → 向用户确认定性语言 → 写出完整 DESIGN.md sidecar | | **Seed mode** | 项目尚在实现之前没有可抽取的视觉系统 | 通过 new-work 的视觉世界工作坊确立方向写出带 SEED 标记的方向性 DESIGN.md 种子 | 关键约束**先扫描Scan mode Step 1。** 如果扫描发现没有令牌、没有组件文件、也没有渲染站点才提供 seed mode**不要静默切换**。/impeccable document --seed 会请求 new-work 的世界工作坊但它不授权替换自洽的既有代码——当存在既有系统时应提供 scan mode或将明确的“身份替换”请求路由给 new-work。 --- ## 六、Scan mode 实战从发现资产到确认定性语言 Scan mode 的完整工作流为**发现资产 → 自动抽取 → 起草 frontmatter → 询问定性语言 → 写文件 → 确认精修**。 ### Step 1按优先级发现设计资产 按文档给定的优先级顺序搜索代码库 1. **CSS 自定义属性**在 CSS 文件中 grep --color-、--font-、--spacing-、--radius-、--shadow-、--ease-、--duration- 声明常见位置src/styles/、public/css/、app/globals.css记录名称、值与定义文件。 2. **Tailwind 配置**若存在 tailwind.config.{js,ts,mjs}读取 theme.extend 中的 colors、fontFamily、spacing、borderRadius、boxShadow。 3. **CSS-in-JS 主题文件**styled-components、emotion、vanilla-extract、stitches查找 theme.ts、tokens.ts 等。 4. **设计令牌文件**tokens.json、design-tokens.json、Style Dictionary 输出、W3C token community group 格式。 5. **组件库**扫描主按钮、卡片、输入框、导航、对话框组件记录其变体 API 与默认样式。 6. **全局样式表**根 CSS 通常承载基础排版与颜色分配。 7. **可见渲染输出**若浏览器自动化可用加载线上站点对关键元素body、h1、a、button、.card采样 computed styles——这能捕捉令牌遗漏的值。 ### Step 2自动抽取结构化草稿 对每类令牌执行抽取 - **Colors**分组为 Primary / Secondary / Tertiary / NeutralStitch 使用的 Material 派生角色。若项目只有一个强调色就表达为 Primary Neutral**省略 Secondary/Tertiary 而不是编造**。 - **Typography**将观测到的字号/字重映射到 Material 层级display / headline / title / body / label记录字体栈与缩放比。 - **Elevation**清点阴影词汇表。如果项目是扁平风、用色调分层表达深度那也是合法答案要明确写出来。 - **Components**对每个常见组件button、card、input、chip、list item、tooltip、nav抽取造型圆角、配色、hover/focus 处理、内边距。 - **Layout spacing**把网格、容器、断点、节奏、密度行为归入 Layout。 - **Shapes**把圆角、边角、边框、裁切与反复出现的造型行为归入 Shapes。 ### Step 2b起草 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 ring、backdrop-filter把完整片段放进 sidecar。 原则**跳过项目没有的东西。** 空的刻度键或捏造的令牌会污染规范。 ### Step 3向用户询问定性语言两轮每轮最多三问 以下内容无法自动抽取需要创造性输入**分两轮、每轮不超过三个问题**或 harness 的更低上限两轮之间等待用户回复 - **Creative North Star**为整个系统命名的单个隐喻如 “The Editorial Sanctuary”、“The Golden State Curator”、“The Lab Notebook”提供 2~3 个尊重 PRODUCT.md 品牌人格的选项。 - **Overview voice**情绪形容词、2~3 句审美哲学、确认过的视觉反参考。 - **Color character**为自动抽取的颜色取描述性名称“Deep Muted Teal-Navy”而非 “blue-800”基于色相/饱和度建议每色 2~3 个选项。 - **Elevation philosophy**flat / layered / lifted若有阴影其角色是 ambient环境还是 structural结构。 - **Component philosophy**用一句话描述按钮、卡片、输入框的感觉“tactile and confident” vs “refined and restrained”。 只有 PRODUCT.md 中**持久性的品牌承诺**约束视觉系统的部分才可以被带入 DESIGN.md页面策略与表面概念不属于这里。 ### Step 4写 DESIGN.md 文件以 Step 2b 起草的 YAML frontmatter 开头随后是规范结构的 Markdown 正文。文档给出了完整的正文模板见第四节结构 完整示例模板关键填充指引 - Overview 从 North Star 出发向外展开只陈述确认过的视觉拒绝以 **Key Characteristics:** 列表收尾 - 每个颜色条目遵循 **Descriptive Name** (#HEX / oklch(...)): [Where and why this color is used] 的格式强调具体语境而非仅角色 - Dos and Donts 中的条目只有在既有实现或用户决定支撑时才写一句话的审计测试胜过一段原则。 ### Step 5确认与精修 1. 向用户展示完整的 DESIGN.md突出非显而易见的创意选择描述性颜色名、氛围语言、具名规则。 2. 说明 .impeccable/design.json 也已一并写出live panel 将渲染该项目的真实按钮/输入框/导航原语而不是通用近似物。 3. 主动提供精修“Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?”可意译为需要我修改某节、补充遗漏的组件模式或调整氛围语言吗 本次会话中你自己写出的文件就是最新来源后续命令无需 reload。 --- ## 七、Step 4b.impeccable/design.json sidecar扩展层 ### 7.1 分工与再生成原则 frontmatter 拥有令牌原语colors、typography、rounded、spacing、components**sidecar 携带 Stitch schema 装不下的东西** - 每个颜色的色调渐变tonal ramps - 阴影/抬升令牌、动效令牌、断点 - 完整组件 HTML/CSS 片段panel 渲染进 shadow DOM - 叙述层north star、rules、dos/donts sidecar **扩展** frontmatter不重复它。每当重新生成根 DESIGN.md 时都要重新生成 sidecar如果用户只想刷新 sidecar例如 live panel 的 stale-hint 提示则保留 DESIGN.md只写 .impeccable/design.json。 ### 7.2 SchemaschemaVersion 2 json { 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 ...] } }仓库的真实实现 demos/landing-demo/DESIGN.json 完整展示了这一 schema8 个colorMeta条目每个含role、displayName、canonicalOKLCH 值与 8 步tonalRamp、6 个typographyMeta、2 个motion令牌、2 个breakpoints、7 个组件含refersTo与可注入 shadow DOM 的html/css以及完整的narrativenorthStar、overview、5 条 rules、5 条 dos、5 条 donts。7.3 从 schemaVersion 1 到 2 的变化旧版 sidecar 携带令牌原语数组tokens.colors[]、tokens.typography[]等。这些值现在移入 frontmattersidecar 只携带 frontmatter 放不下的元数据色调渐变、当 hex 只是近似时的规范 OKLCH、显示名、角色提示并以 frontmatter 令牌名为键colorMeta.token-name、typographyMeta.token-name。组件仍携带完整 HTML/CSS因为 Stitch 的 8 属性集装不下它们。schema 版本常量对应实现DESIGN_SIDECAR_SCHEMA_VERSION 2crates/context/src/artifact_schema.rs。7.4 组件翻译规则自包含、可直接注入 shadow DOMhtml与css字段必须是自包含、即插即用的片段注入 shadow DOM 后能正确渲染。panel 直接应用它们无后处理、无框架运行时。六条硬规则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 继承并保持 live-bound若令牌只存在于 JS 主题对象styled-components、CSS-in-JS则在生成时解析为字面值。图标内联为 SVG。不要引用 Lucide/Heroicons 包、图标字体或img src...。典型图标 16–24px直接复制 SVG path 数据。状态内联包含:hover、:focus-visible以及有意义的:active规则。只有静态默认快照会让 panel 显得死板CSS 中的 hover focus 规则让它有生命感。重置去冗余只抽取组件的特色CSS背景、颜色、内边距、圆角、排版、过渡。跳过通用 resetbox-sizing: border-box、line-height: inherit、-webkit-font-smoothing——panel 已有中性画布不需要重新携带 reset。作用域类名每个类以ds-前缀如ds-btn-primary、ds-input-search避免同一 shadow DOM 内组件间 CSS 冲突。7.5 内容选择5~10 个代表性组件目标是精选 5~10 个最能代表视觉系统的组件规范原语项目有则必含button每个变体作为独立组件条目、input/文本框、navigation、chip/tag、card。签名组件有特色才含定义已实现系统的反复出现的自定义模式。跳过其余工具组件、表单积木、包裹布局——除非视觉上有特色否则不值得记录。若项目还没有组件库裸落地页、新项目可从令牌出发、用与 DESIGN.md 规则一致的最佳实践默认值合成规范原语——每个.impeccable/design.json都至少有东西可渲染哪怕是在第零天。7.6 色调渐变Tonal ramps对每个颜色令牌生成 8 步tonalRamp数组从暗到亮保持同一色相与色度chroma亮度从约 15% 步进到约 95%。panel 把渐变渲染为色卡下方的条带。若项目已定义自己的色调标尺Materialsurface-container-low家族、Tailwind 风格blue-50..blue-900使用这些值否则在 OKLCH 中合成。demos 中的creamramp 从oklch(15% 0.012 80)到oklch(96.5% 0.012 80)即为典型示例。7.7 叙述映射Narrative mapping直接从刚写好的 DESIGN.md 搬运不改写panel 把它们作为次级可折叠上下文展示与 Markdown 中相同的声音需要延续sidecar 字段来源DESIGN.md 中narrative.northStarOverview 的**Creative North Star: ...**行narrative.overviewOverview 的哲学段落narrative.keyCharacteristics**Key Characteristics:**要点列表narrative.rules全文所有**The [Name] Rule.** [body]标注sectionnarrative.dos/narrative.dontsDos and Donts 的要点列表逐字八、Seed mode实现之前的视觉世界种子Seed mode 适用于还没有可抽取视觉系统的项目产出的是“用户选择的视觉世界脚手架”而不是编造的令牌规格。Step 1经由 new-work 的工作坊路由PRODUCT.md 是前置条件。若缺失先加载 skill/reference/init.md 完成产品访谈——没有持久的产品语境不要创建视觉身份。若 PRODUCT.md 存在加载 skill/reference/new-work.md 解决视觉权威问题。Seed mode 需要一个具体的首面first surface使用用户指定的 target或询问用户想先做什么。运行 new-work 的Create or replace the visual world流程然后Commit the world让视觉世界与它的首面表达一起被选定。在方向性 DESIGN.md 种子与 surface brief 之后停止不要实现。结构化的模拟用户也算用户必须获得同样的选择权。若本次会话中 new-work 已完成工作坊直接使用其选定方向不要重复询问。Step 2写 seed DESIGN.md使用与 Scan mode 相同的规范小节顺序填充选定的工作坊方向未决的实现事实留作诚实的占位符。种子承诺一个世界及其不变量不假装实现令牌已经存在。文件以如下 SEED 标记开头!-- SEED: established with the user before implementation; re-run /impeccable document once theres code to capture the actual tokens and components. --【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考