Impeccable Craft Floor 深度指南：AI 生成界面的质量底线、批量验证清单与拒绝清单
【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable
本篇技术指南围绕 Impeccable 项目的craft-floor参考文档展开。它定义了 AI 在设计方向确定之后、动手编辑 UI 之前必须加载的"质量地板"（craft floor）：一套九项可机械验证的检查清单（Verify）与两族被明确拒绝的惰性模式（Refuse）。读完本文，你将掌握如何把对比度、间距、字体、动效、状态与浏览器原生表面等硬指标落地为可批量执行的检查，并理解为何"卡片网格 + 英雄数字 + eyebrow 标签"这类模板式产出被该项目视为必须重写而非微调的对象，以及设计检测 Hook 如何自动承担其中一部分机械检查。
一、Craft Floor 是什么：定位与加载时机
craft-floor不是一篇功能文档，而是 Impeccable 技能在工作流中的一道强制关卡。原文档开篇即给出三条加载纪律：
- 在方向确定之后加载：
Load this after the direction is settled。它用于"构建"（build）阶段，而非"规划"（planning）阶段。项目 SKILL.md 的 Setup 第 3 步明确写道："After analysis and direction are resolved, loadreference/craft-floor.mdimmediately before editing UI. It carries the quality floor, the absolute bans, and the reflexes no detector catches. Do not load it for planning-only work." - 构建时不宣读清单：
build without announcing the checklist——质量底线应内化为执行标准，而不是在交付里逐条罗列。 - 优先级明确：
A pinned brief or the committed visual world overrides anything here; your own habit does not.已固定的 brief（如 DESIGN.md 承诺的视觉世界）优先级高于本清单；而模型自身的固有习惯没有任何优先级。这意味着 floor 是最低标准，永远不能取代方向决策。
最后一条纪律直接关联到 Impeccable 的自动化能力：当设计 Hook 激活时，它在你编辑的同时就会强制执行下述机械检查——When the design hook is active it already enforces the mechanical checks below as you edit: act on its findings instead of re-auditing each rule.即：不要重复人工逐条审计，而是直接处理 Hook 给出的 findings。我们在第六节会还原这条 Hook 的源码链路。
二、Verify：九项可机械验证的检查清单
原文档强调一个关键的执行方式：这些检查针对的是"构建结果"（the built result），不是"意图"（not an intention）。同时它们应当"在批量检查轮次中一起运行，而不是分多次截图往返"——the checks share one render，即九项检查共享同一次渲染结果，桌面与移动端合并到同一批检查中（参见 SKILL.md 中"Verify in bounded passes, not a loop"的总原则）。
| # | 检查项 | 硬性参数（取自原文档） | 判定要点 |
|---|---|---|---|
| 1 | Contrast | 正文与占位文本 ≥ 4.5:1，大文本 ≥ 3:1 | 彩色表面上，次要文本从该色相或前景色取色，绝不使用灰色 |
| 2 | Depth | 阴影必须带 offset 与柔和模糊 | 零 offset 的彩色光晕属于装饰，不是深度 |
| 3 | Spacing | 紧凑分组、宽松分隔、标题上方留白多于下方 | 读取计算值（computed values），而非目测 |
| 4 | Type | 正文行长 65–75ch，display 最大 6rem，tracking 下限 -0.04em，标题平衡，字号与字重阶梯明显 | 在每个断点跑真实文案，修复一切溢出 |
| 5 | Motion | 只有一个"作者时刻"（one authored moment） | 从已可见的默认状态做指数缓出；效果需超越 transform/opacity 的组合 |
| 6 | States | hover、disabled、loading、error、empty | 加上真实内容、可用控件、响应式布局、键盘焦点 |
| 7 | Browser surfaces | 文本选区、光标、自定义滚动条、焦点环、下划线偏移、表格数字 | 全部从调色板主题化 |
| 8 | Copy | 产品自己的语言 | 控件命名动作；错误命名问题与恢复路径 |
| 9 | Coverage | brief 的每一项需求都存在且在数秒内可发现 | 逐条对照 brief 需求 |
2.1 Contrast：对比度是硬指标，灰色是惰性信号
- 正文与 placeholder 文本需要 ≥ 4.5:1（WCAG AA 级别的常见阈值），大文本（通常指 18px/14pt 以上加粗或 24px/18pt 以上常规文本）放宽到 ≥ 3:1。
- 关键规则在第二句：在彩色表面上，次要文本必须从"该色相"或前景色派生（tint secondary text from that hue or the foreground），绝不使用灰色。纯灰是与任何色板都无关的中性色，它割裂了表面与文字的视觉血缘——这是本项检查最容易被模型跳过、也最容易被用户一眼看出的破绽。
2.2 Depth：阴影必须"立得住"
- 合格阴影的两个必要条件：offset（偏移）+soft blur（柔和模糊），即
box-shadow: 0 8px 24px rgba(...)这类形态。 - 反向标准：
A zero-offset colored halo is decoration——一个没有偏移、只有模糊的彩色光晕是装饰而非深度。霓虹发光（glow）不属于深度系统。
2.3 Spacing：读计算值，不靠目测
- 节奏模式：紧凑的分组（tight groups）+ 宽松的分组间分隔（generous separation），以及标题上方留白多于标题下方——后者是经典的"段落归组"视觉规律。
- 执行方式被明确写死：
Read the computed values，即必须读取浏览器计算后的实际像素值来核对，而不是根据源码中的数值猜测。这与live工作流中基于真实渲染的检查方式一致。
2.4 Type：一组可直接复用的数值下限
- 正文行长（measure）65–75ch，超出行长会导致阅读疲劳；
- display 级字号上限6rem（约 96px），防止失控的巨型标题；
- 字距收紧下限-0.04em，更紧的 tracking 会破坏可读性——项目 skill/reference/craft-floor.md 的 codex 段落补充："Tracking stops at -0.04em. -0.02 to -0.03em usually reads better"，即实际落地时 -0.02 到 -0.03em 通常更耐读；
- 标题需要"平衡"（balanced headings），字号与字重要有明显的阶梯（obvious scale and weight steps），而不是靠颜色或装饰撑层级；
- 最后一条是硬性动作：在每个断点用真实文案运行（Run the real copy at every breakpoint）并修复一切溢出。
2.5 Motion：一个作者时刻，而非散弹式效果
- 数量纪律：
one authored moment, not scattered effects——整个页面只有一个精心设计的动效"时刻"，反对"每个 section 都放一个完全相同进入动画"（not one identical entrance on every section）。 - 曲线纪律：从已可见的默认状态做指数缓出（Exponential ease-out from an already-visible default），而不是从不可见状态大范围入场。
- 材质纪律：动效调色板要超越 transform 与 opacity——
blur, backdrop-filter, clip-path, mask, and shadow belong to the palette when they stay smooth。即只要保持流畅，模糊、背景滤镜、裁剪路径、遮罩和阴影都可以作为动效材质参与叙事。
2.6 States：把状态机补全
- 基础五态：hover、disabled、loading、error、empty。
- 在此之上，还要有真实内容（real content）、可用的控件（working controls）、响应式组成（responsive composition）与键盘焦点（keyboard focus）。空状态尤其容易被遗漏——它往往是最能体现设计意图的界面。
2.7 Browser surfaces：模型最稳定跳过的一层
这是原文档中唯一带"价值判断"的条目，值得原文引用：
The parts you did not draw still carry the design. ... they all ship with browser defaults that belong to no design system. Theme them from the palette. This is the cheapest signal that a page was built rather than assembled, and the one models skip most reliably.
"你没有亲手画的部分，依然在传递设计。"浏览器默认的文本选区、光标（caret）、滚动条、焦点环、下划线偏移量、表格数据的数字字形，都不属于任何设计系统，必须用调色板重新主题化。原文称这是"页面是构建出来而非拼装出来"的最廉价信号，也是模型最稳定跳过的一层——因为模型"看不见"这些浏览器层，除非被明确要求。对应规则的标识在技能仓库中为rule:skill-craft-browser-surfaces（见 skill/reference/craft-floor.md）。
2.8 Copy 与 Coverage：语言与覆盖度
- Copy：使用产品自己的语言。
Controls name their action（按钮文案说明动作，如"发布"而非"确认"）；errors name the problem and the recovery（错误信息同时说出问题与恢复路径，而不是"出错了"）。 - Coverage：brief 中的每一条需求都必须存在且能在数秒内被找到（present and findable within seconds）。这是一条可执行的对标动作：交付前把 brief 逐条打勾。
三、Refuse：拒绝清单的定位——"分类默认值，不是禁令"
原文档对本节有一段极其重要的定性，必须先理解，否则整张清单会被误读为教条：
These are the category's defaults, not bans: the brief's own words can earn any of them.
清单中的每一项都是**"按分类的默认值"（category defaults），不是绝对禁令**——brief 自己的措辞可以"赎回"（earn）其中任何一项。但紧接着是两条行为铁律：
Reaching for one when the axis is free means you were not deciding——当某个轴向是自由的而你仍伸手去拿这些默认模板，说明你没有在做决策；recognizing that means rewriting the element, not softening it——一旦意识到踩线，处理方式是重写该元素，而不是弱化它。
唯一的例外是kicker/eyebrow（眉题）：This one is a ban, not a default: no brief earns it back.它是整张清单中唯一被升级为绝对禁令的项——标题自己承担重量，删掉标签，让标题直接说话。
3.1 页面脚手架（Page scaffolds）族
- 同尺寸卡片网格：
Same-size cards of icon plus heading plus text as the page structure——卡片是"惰性容器"（the lazy container），嵌套卡片永远是错的（nested cards are always wrong）。对应规则rule:skill-ban-identical-card-grids与rule:skill-layout-cards-lazy。 - 英雄数字模板（hero-metric template）：大数字 + 小标签 + 支撑性统计 + 强调色，这组"数据营销页"拼装被整族拒绝（
rule:skill-ban-hero-metric）。 - 眉题/eyebrow：唯一绝对禁令，任何 brief 都不能赎回（
rule:skill-ban-eyebrow-on-every-section）。 - 章节编号（01 / 02 / 03）：除非序列本身携带读者需要的信息（如步骤、阶段），否则拒绝（
rule:skill-ban-numbered-section-markers）。 - 模态框：
A modal for a task that needs neither interruption nor protected focus——一个既不需要打断、也不需要受保护焦点的任务，不该用模态框（rule:skill-reflex-modal-by-reflex）。
3.2 表面习惯（Surface habits）族
- 渐变文字：强调来自字重或字号，而不是
background-clip: text的渐变（rule:skill-ban-gradient-text）。 - 玻璃拟态与装饰性模糊：glass 与 blur 只有在承担"特定效果"时才被允许，作为装饰即为拒绝（
rule:skill-ban-glassmorphism-default）。 - 彩色侧边条：卡片、列表项、callout、alert 上超过 1px 的
border-left/border-right（rule:skill-ban-side-stripe-borders）。 - 硬偏移阴影：
box-shadow: 4px 4px 0这类零模糊块状阴影只属于真正的新粗野主义（neobrutalist）世界；The zero-blur block shadow is a costume, not a depth system——一个没有选择该世界观的世界，永远不能把它当默认值（rule:skill-ban-hard-offset-shadow）。 - 用图表元素代替内容：Sparklines（迷你趋势线）、进度环、带柔和阴影的圆角矩形，当它们"顶替"真实内容时被拒绝（
rule:skill-reflex-decorative-chrome）。 - 等宽字体做"技术感"戏服：monospace 只用于代码、数据或度量，不能拿来假装"技术味"（
rule:skill-reflex-mono-as-technical）。 - 系统 display 字体：Impact、Arial Black、平台无衬线体不能作为自有世界（own-world page）的 display 声音。必须**获取并自托管（source and self-host）**一个气质与已批准字标匹配的字体；
the closest installed font is a failure, not a fallback——最接近的已装字体是失败，不是回退（rule:skill-ban-system-display-face）。 - Unicode 符号/emoji 冒充图标系统：图标必须是绘制出来的——来自真实图标库或手写 SVG，且保持一致的笔画与字重（
rule:skill-ban-glyph-icons）。 - 几何遮罩冒充有机轮廓：用圆形、多边形或 radial-gradient 切割来近似照片主体的边缘，是"廉价版效果"，比直接省略读起来更糟；正确做法是从真实图像推导 alpha matte或产出抠图资产（
rule:skill-ban-geometric-occlusion-mask）。 - 按分类选明暗主题：
Light or dark picked by category——不要因为"这是金融产品"就选深色。要从使用场景（谁、在哪、什么环境光下）决定（rule:skill-reflex-theme-by-habit）。
四、来自供应商补充段的附加纪律
项目 skill/reference/craft-floor.md 在正文之外还带有面向特定模型的补充段落，可视为对上述两条清单的实例化注解：
codex 段（针对擅长产出"看起来正确"但缺乏真实的模型输出）：
- 高程只声明一次——边框或阴影二选一：
A 1px border under a wide soft shadow is the ghost card；卡片圆角保持在12–16px，药丸形（pill）只留给小控件； - 真插画，或者没有：sketch 风格的 SVG 场景、
loose-sketch/doodle类名、feTurbulence颗粒质感都被视为业余；但禁止的是"用 SVG 模仿图片"，SVG 做几何仍然是头等媒体——清晰的矢量形状、图表、动画线稿、着色器驱动效果都允许（rule:skill-ban-codex-sketchy-svg）； - 背景是表面，只能来自主题世界的纹理：
repeating-linear-gradient条纹与双轴网格背景，只有在真实画布、地图、蓝图或测量工具之下才成立； - 诚实标注插画值：声明与配置必须来自提供的真实信息，示意性数值要如实标注（
rule:skill-ban-codex-x-theater）。
gemini 段：
- 永远不要悬停时动画图片本体（直接或通过其父级触发都不行）：图片不是动作目标，反馈应该给容器（
rule:skill-interaction-gemini-no-image-hover）。这一条可以回看 2.5 的"超越 transform/opacity"——它划清了哪些元素可以承载动效、哪些不能。
五、检测器如何把这些规则变成可判定的 finding
拒绝清单不是一句口号——仓库的检测引擎把其中多项规则实现成了可自动化判定的反模式（antipattern）。在 regex_matchers.rs 中可以看到gradient-text规则的实现，它同时匹配原生 CSS 与 Tailwind 两种写法：background-clip: text + gradient与bg-clip-text + bg-gradient都会被识别并输出对应的 finding 文案。
与之配套的回归夹具（fixtures）也证实了这些规则的可测性。在 tests/fixtures/antipatterns 目录下可以找到直接对应拒绝清单的测试页：
- hero-eyebrow-chip.html——对应眉题/eyebrow 绝对禁令；
- kicker-above-heading.html——对应标题上方标签模式；
- numbered-section-markers.html——对应章节编号默认拒绝。
这解释了原文档末尾那句"reflexes no detector catches"（见 SKILL.md Setup 第 3 步）的含义：检测器能抓到一部分，但 floor 的完整版——尤其是"这些是默认值而非禁令"的判断力——只能靠模型在执行时把握。
六、设计 Hook：让机械检查在编辑时自动执行
原文档所说的 "When the design hook is active it already enforces the mechanical checks below as you edit" 在仓库中有完整的实现链路。
1. 触发时机：插件注册了两个 Hook 事件（见 plugin/hooks/hooks.json）：
PostToolUse（匹配Edit|Write）：每次 UI 文件编辑后运行impeccable hook，状态消息为 "Checking UI changes"；Stop：对话停止时运行深度检查，状态消息为 "Design deep pass"。
2. 引擎实现：Hook 的 Rust 实现位于 hook_lib.rs，其中定义了默认配置（HookConfig::default）：
per_edit_rules: "immediate"——编辑后立即检查规则；- 会话内编辑计数阈值
EDIT_COUNT_THRESHOLD = 6（hook_lib.rs）：超过后抑制进一步的设计提示，提示改用audit复查； - 输出上限
max_findings: 5、max_chars: 8000、max_file_bytes: 131072（约 128KB），防止检查结果淹没工作区； - 受检扩展名
ALLOWED_EXTS覆盖.tsx/.jsx/.html/.htm/.vue/.svelte/.astro/.css/.scss/.sass/.less/.ts/.js（hook_lib.rs）。
3. 与 craft-floor 的衔接：在 live 变体工作流中，instructions.rs 对自由形式动作给出的指令是 "work from SKILL.md rules plus craft-floor.md; no sub-command file"，插入模式（insert mode）的指令也明确要求 "load craft-floor.md before writing net-new markup"（instructions.rs）。也就是说，只要是生成全新标记（net-new markup），craft-floor 都是必读前置。
4. 行为契约测试：scenarios.test.mjs 验证了工作流契约——craft-floor.md与polish.md等参考文件必须在正确的阶段才能被加载，规划阶段不得提前调用，确保"方向确定之后、编辑之前"这一时序不被打破。
七、结语：地板决定机制，永不决定方向
原文档以两句话收尾，也是整个 craft-floor 的哲学总纲：
The floor holds the mechanics; it never picks the direction. With every check green, spend the page on the committed world, and when torn between refined and committed, commit.
- 地板只持有机制，永不选择方向：对比度、间距、动效曲线、状态完整性这些是"工程正确性"；而"这个页面属于哪个视觉世界"是方向决策，由 brief 与 DESIGN.md 决定，floor 无权干预。
- 九项全绿之后，把页面花在已承诺的世界上：检查通过不是终点，而是把预算投向"已承诺的视觉世界"（the committed world）的起点。
- 在"精致"与"忠诚"之间摇摆时，选择忠诚（commit）：对 brief 的忠诚高于一切抛光冲动。
对 AI 驱动的前端工作流而言，这份文档的价值在于它把一个容易被"看起来不错"糊弄过去的环节，拆解成了可验证、可批量执行、可被检测器自动承担的硬指标，同时为创造力保留了明确的出口——所有默认拒绝项都可以被 brief 赎回，除了眉题。理解并落实这层"地板"，是让模型产出从"拼装感"迈向"构建感"的最短路径。
【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
