Impeccable Documenter 设计系统记录机制以构建产物为唯一事实源的设计规则提炼指南【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读Impeccable Documenter 是 impeccable 项目中负责在设计系统构建完成之后将实际落地的视觉系统记录为DESIGN.md与.impeccable/design.json侧车文件的专用 Agent。本文以 plugin/skills/impeccable/reference/degraded/documenter.md 的角色定义为主线结合仓库中的 document.md 格式规范、craft-floor 工艺底线 与 demos/landing-demo 的落盘产物完整展开其输入契约、五步工作流、输出契约以及以产物为准、禁止将缺陷神圣化的两条核心防错准则。读完本文你将掌握如何让 AI 从已构建代码中反向提炼可被后续生成任务复用的设计 token 与规则并理解为什么构建前写的规则书会被现实反驳。角色定位记录已发生的事实而非描述计划中的意图Impeccable Documenter 的职责是在构建完成之后记录项目的设计系统。角色定义的立身原则只有一句话Ground truth is the shipped artifact: every token and rule you write must be evidenced by the built code, never by what was planned.即唯一事实源是交付的产物——写入的每一个 token、每一条规则都必须由已构建的代码佐证而不是由最初的计划佐证。事后记录正是这个角色的存在意义一份在构建之前写好的规则书会在现实面前被不断辩护而不是描述现实。因此角色也被赋予了System Scribe / Token Surveyor / Ground Truth等昵称见 skill/agents/impeccable-documenter.md 的nickname-candidates。该角色在 plugin/agents/impeccable-documenter.md 中登记的工具集为Read, Write, Bash, Glob, Grepeffort: medium、maxTurns: 30属于中等强度的收尾审计型角色。degraded 目录下的版本即关联文档说明当宿主 harness 不具备子代理能力时该角色以内联方式运行——父代理即是文档者自身需要先按完整输出契约产出结果再亲自执行它并在报告中用一行说明这个替代。输入契约Input Contract角色运行前必须确认以下输入齐备项目根目录project root产物路径artifact path(s)即待记录的已构建代码方向契约文本direction contract text包含 THESIS、OWN-WORLD、STORY、FIRST VIEWPORT、FORM 五个区块PRODUCT.md 路径技能自带规范文档路径即reference/document.md记录边界boundary写入发生在项目根project root还是应用根app root。一个关键约定若已存在DESIGN.md本次操作是更新而非替换。要保留已确认的现行决策incumbent decisions并将它们与当前构建调和一致。这呼应了 document.md 规范中的禁令If aDESIGN.mdalready exists, do not silently overwrite it——必须先向用户展示现有文件由用户选择刷新、覆盖或合并。五步工作流从产物到规则书第 1 步完整阅读格式规范先完整读取reference/document.md它是DESIGN.md的格式、token schema、侧车文件和章节顺序的操作规范operating spec必须严格遵守。规范的全文即 skill/reference/document.md。第 2 步扫描产物扫描对象按优先级覆盖样式表、CSS 自定义属性custom properties、源码中的计算值computed values、组件模式、间距节奏spacing rhythm、实际使用的字体梯度type ramp。扫描方式要求批量读取、先取样式表、组件抽样而非遍历整棵树以在 turn 上限内完成检查。方向契约中的 OWN-WORLD 区块给世界命名而构建展示这个世界如何落地。当两者出现分歧时构建胜出且行文可以注明该分歧。第 3 步写出 DESIGN.md 与其侧车若是全新世界new world或经批准的系统变更从构建中持久复用的规则durable, reused rules出发写出DESIGN.md和侧车文件若是普通扩展保留现行系统报告中标注已存在的漂移pre-existing drift未获要求不得擅自修复无论如何不要为了证明本次运行发生了而写东西Do not write merely to prove this pass ran。第 4 步校验两条经典出错路径文档明确指出一条被记录的规则有且仅有两种实测中反复出现的错误方式禁令反噬世界自身一条禁令prohibition禁止了世界自身原生使用的装置。例如世界自己就在用某种装饰性元素规则却禁止它——这等于把自己家园的门焊死。必须拿每一条禁令去对照世界自己的素材the worlds own materials。用记录为缺陷洗白一个值被记录进来只是为了给某个缺陷背书。文档给出的验收标准是一个值靠构建和可读性赢得位置绝不靠让一个 finding 消失a value earns its place by the build and by legibility, never by making a finding disappear。第 5 步不将工艺底线craft-floor的拒绝升级为系统规则craft-floor 是构建时的工艺底线清单见 skill/reference/craft-floor.md它拒绝某些默认做法标题上方的 kicker / eyebrow 标签This one is a ban, not a default: no brief earns it back非新粗野主义世界中的硬偏移阴影box-shadow: 4px 4px 0零模糊块阴影是戏服而非深度系统用字形图标/emoji 顶替图标系统glyph icons用系统显示字体Impact、Arial Black 等充当自有世界的 display 字体。documenter 必须绝不把工艺底线的拒绝内容 canonize 进系统被底线禁止的元素kickers and eyebrows、非新粗野主义世界的硬偏移阴影、glyph icons、系统显示字体一律记录在未 canonize 行not-canonized line里作为构建背负的缺陷defect the build carries而不是作为未来表面可以继承的设计系统规则。文档给出了一个真实教训一次 live 会话交付了五个凭空发明的 kicker文档者把它们的样式写进了 DESIGN.md——一条违规就这样变成了 house style。这正是本角色存在的反例警示。输出契约Output Contract输出被严格约束为三类内容且除此之外无其他行文No other prose写入的路径列表或 No changes 及所检查的源码与系统文件五行系统摘要调色板palette、字体梯度type ramp、命名规则named rules一行说明未被 canonize 或未修复的缺陷/漂移及其原因。落盘物标准DESIGN.md 与 .impeccable/design.jsondocumenter 写出的DESIGN.md遵循 skill/reference/document.md 定义的格式可选 YAML frontmatter 携带机器可读设计 token后接最多八个按固定顺序排列的 Markdown 章节。token 是规范性的Tokens are normativeprose 只提供如何应用它们的上下文。frontmatter token 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 引用使用{path.to.token}如{colors.primary}、{rounded.md}。组件可以引用原语原语之间不得互相引用颜色接受任意合法 CSS 颜色字符串。推荐默认使用 hex 以保证可移植性但当项目以rgb()、hsl()、oklch()、宽色域或混色值作为规范来源时保留原有值——不得无理由割裂事实源组件子 token 限 8 个属性backgroundColor、textColor、typography、rounded、padding、size、height、width。阴影、动效、焦点环、backdrop-filter 都装不下一律放进侧车文件Step 4b刻度键是开放式的沿用项目自己的名字oxblood-deep、surface-container-low不要改成 Material 默认名变体是命名约定而非 schemabutton-primary/button-primary-hover/button-primary-active作为兄弟键平铺。八个规范章节固定顺序## Overview→## Colors→## Typography→## Layout→## Elevation Depth→## Shapes→## Components→## Dos and Donts。规范要求无关章节省略而非用虚构规则填满响应式布局放 Layout深度放 Elevation Depth圆角与形态语言放 Shapes逐组件行为放 Components。文档同时强调Dont rename sections even slightly——解析工具依赖精确的标题文本。.impeccable/design.json 侧车schema 装不下的扩展层frontmatter 只拥有 token 原语colors、typography、rounded、spacing、components侧车文件.impeccable/design.json承载Stitch 的 schema 装不下的内容每个颜色的色调梯度tonal ramp、阴影/抬升 token、动效 token、断点、完整组件 HTML/CSS 片段面板将其渲染进 shadow DOM以及叙事north star、规则、dos/donts。它扩展 frontmatter绝不重复它。每当重新生成根级DESIGN.md就必须重新生成侧车若用户只要求刷新侧车例如 live 面板的陈旧提示触发则保留DESIGN.md只写.impeccable/design.json。侧车的组件片段必须自包含、可直接注入 shadow DOM并遵守六条转换规则Tailwind 展开源里用了className就必须把每个 utility 展开为字面 CSS不得依赖 Tailwind 包已加载Token 解析:root上暴露的自定义属性用var(--color-primary)引用保持活绑定只在 JS theme 对象里存在的 token 在生成时解析为字面值图标内联为 SVG禁止引用 Lucide/Heroicons 包、图标字体或img src状态齐全内联:hover、:focus-visible和有意义时的:active只给默认快照会让面板显得死板去除重置样板只提取组件独有 CSS跳过box-sizing等通用重置类名加ds-前缀避免同一 shadow DOM 内组件 CSS 互相冲突。目标是一个5–10 个组件的精选集规范原语按钮各变体、输入框、导航、chip、卡片优先签名组件真正定义该系统的重复自定义模式视独特性纳入工具型组件与包装布局一律跳过。即便项目尚无组件库也应从 token 合成符合 DESIGN.md 规则的规范原语保证.impeccable/design.json从第一天起就有东西可渲染。每个颜色 token 需生成 8 步tonalRamp同色相同色度、亮度约 15%→95% 步进面板以条带形式渲染在色卡下方。仓库中的真实落盘样例Lumina 设计系统demos/landing-demo/DESIGN.md 及其 DESIGN.json 侧车 是上述全部机制的落地证据。其 frontmatter 以cream: #faf6ef、ink: #1f1a15等描述性 slug 记录 8 个颜色 tokentypography定义 display/headline/title/body/lede/label 六级梯度rounded记录card: 20px、icon: 14px、pill: 999px组件通过{colors.ink}、{rounded.pill}引用原语。正文体现了 documenter 的输出风格——**命名规则Named Rules**是全文的记忆锚点The Cream-Family Rulecolors所有中性表面向品牌色相靠拢无纯白、无纯黑、无未染灰The 10% Accent Rulecolors焦橙占据任意渲染表面不超过 10%稀缺即重点The One-Italic Ruletypography每页斜体恰好出现一次——hero 标题内单个强调词logo 排字是例外The No-Gradient-Text Ruletypography文字永远纯色hero 的渐变只是区块背景The Flat-By-Default Ruleelevation静止表面全平hover 抬升用transform: translateY(-1px)而非阴影。侧车文件 demos/landing-demo/DESIGN.json 展示了完整结构colorMeta为每个色 token 提供 8 步tonalRampOKLCH 表达components中每个条目给出可注入 shadow DOM 的html与css例如 Primary Button 的ds-btn-primary类、Hero Headline 的ds-hero-h1与其中的em强调规则narrative直接从 DESIGN.md 原文映射northStar、keyCharacteristics、rules、dos/donts逐字搬运不做改写Do not reword。注意其中shadows: []为空数组——项目扁平、无阴影就诚实记录为无这正是 document.md 规范所言如果项目是扁平且用色调分层表达深度那也是有效答案必须明确陈述。与 craft-floor 的衔接记录者的边界感documenter 之所以要单独声明绝不把工艺底线的拒绝 canonize是因为 craft-floor 的禁令与设计系统规则在形式上都像禁止做什么但性质完全不同craft-floor 的拒绝如 kicker/eyebrow、硬偏移阴影、glyph icons、系统显示字体是构建类默认值brief 自己的措辞可以挣回其中任何一个它们从不是世界的固有属性设计系统规则则是该世界的事实由构建产物佐证、供未来表面继承。若文档者把前者误记为后者就会发生文档所述的一条违规变成 house style事故。正确的处理是把未被批准却已出现在构建里的拒绝项记入 not-canonized 行作为缺陷披露在输出契约的第 3 项一行说明让读者知道这是系统背负的债务而非可以继续复用的规则。适用前提与限制本文所述机制以当前仓库 skill/reference/document.md、skill/agents/impeccable-documenter.md、plugin/agents/impeccable-documenter.md 与 plugin/skills/impeccable/reference/degraded/documenter.md 的实际内容为准degraded 版本面向无子代理能力的 harness运行时需内联替代并如实披露具备子代理能力的宿主如 plugin/agents/impeccable-documenter.md 登记的 30 轮上限版本则按独立 Agent 调度记录发生在构建之后因此先有可扫描的代码、样式与组件再运行记录是硬前提对尚无实现的项目应走 document.md 定义的 Seed 模式先经 new-work 的视觉世界工作坊产出方向性种子待有代码后重跑扫描模式而不是虚构 token 规范。小结Impeccable Documenter 的可复制要点可以压缩为四句话以构建产物为唯一事实源事后记录而非事前规定每条禁令对照世界自身素材校验、每个值靠构建与可读性而非让 finding 消失赢得位置工艺底线的拒绝只记入缺陷披露行、永不升级为系统规则输出严格收敛为路径/变更声明、五行系统摘要与一行缺陷说明。把握住这四点任何 AI 工作流都能从一段已构建的代码中提炼出一份真实、可复用、可被工具解析的设计系统而不是一份在现实面前不断被辩护的愿望清单。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
