读懂 Impeccable 的 Craft Floor：AI 构建界面前的质量底线核查清单与拒绝清单

读懂 Impeccable 的 Craft FloorAI 构建界面前的质量底线核查清单与拒绝清单【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable在 Impeccable 技能体系中craft-floor是一份动手写代码之前最后加载的参考文档见 .gemini/skills/impeccable/reference/craft-floor.md它定义了 AI 生成前端界面的质量地板quality floor一批对成品而非意图的机械核查项以及一组默认拒绝的风格候选。方向已定、visual world 已被批准之后floor 负责把每一行 CSS 拉回到底线上同时绝不越权替你选择视觉方向。读完本文你将掌握 craft floor 的 9 条 Verify 核查与 13 条 Refuse 默认拒绝的完整内容理解它与设计检测钩子design hook、detector 规则、评审 Agent 之间的分工并能结合仓库中的反模式夹具一眼识别模型最容易偷工的地方。Craft floor 是什么机制地板不是创意天花板打开仓库里任意一份craft-floor.md副本开篇第一句话就是它的定位Load this after the direction is settled, and build without announcing the checklist.即只有当方向方向契约、DESIGN.md 承载的视觉世界、surface brief已经被用户拍板之后才加载加载之后安静地执行清单而不是向用户宣布清单。文档同时规定了三条优先级这在 Agent 协作场景中至关重要pinned brief被钉住的简报或已提交的 visual world 覆盖 floor 中的一切floor 是通用默认值不是一个可以覆盖具体项目决定的上位规范你自己的习惯agents own habit永远不能覆盖 floor模型在训练数据中形成的顺手做法恰恰是 floor 要对抗的对象当 design hook 处于激活状态钩子会在每次编辑时实时强制执行下面的机械检查这时你应当直接处理钩子的发现而不是再把每条规则手动复查一遍。仓库根目录的 README.md 将其概括为面向 AI coding agent 的设计指导1 个技能、23 条命令、live 浏览器迭代以及61 条确定性的 detector 规则。craft floor 与这些规则的关系是互补的可被机械捕捉的检查项沉淀为 detector 规则而没有任何扫描器能抓到的直觉/品味判断留在 craft floor 里。这一点在 .gemini/skills/impeccable/reference/hooks.md 中被直接言明Every hook is a mechanical pass. The reflexes no scanner catches live in craft-floor.md, which the skill loads before it edits UI, so they apply whether or not a hook is wired.因此无论项目是否接入了自动钩子craft floor 都是质量底线的最后一道人工兜底。工作流中的加载时机.gemini/skills/impeccable/SKILL.md 的 Setup 第 3 步规定了精确的加载时机After analysis and direction are resolved, load reference/craft-floor.md immediately 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.只做规划时不加载是刻意的floor 是为了约束产出物而存在的在还没到写代码环节前加载只会污染规划阶段的方向自由度。它属于 SKILL 路由表之外的共享 playbook与new-work.md、operate.md、routing.md并列这一点在 CLAUDE.md 的reference/目录说明中可以确认。v4曾经把typography.md、color-and-contrast.md、spatial-design.md、motion-design.md、ux-writing.md等按领域拆分的文件全部并入命令参考与craft-floor.md让它们只在适用时才被加载避免 Agent 每次任务都背一遍全套规范。值得注意该文档在多套 harness 目录下各有一份等价副本.gemini、.claude、.cursor、.grok、.github等仓库内还有 skill/reference/craft-floor.md 与 plugin/skills/impeccable/reference/craft-floor.md 两份主副本。主副本中的每一条检查/拒绝项都带一个 HTML 注释形式的规则标签如!-- rule:skill-craft-floor --把 prose 规范和 detector 的规则 ID 一一挂钩供实现与测试直接对齐。Verify只检查成品不检查意图文档明确写道Each of these is a check on the built result, not an intention.每一项都必须作用于真实渲染出来的结果而不是作用于我当时想做成什么样。同时它规定了一个重要的执行纪律Run them together in the batched inspection rounds, not as separate screenshot trips; the checks share one render.即所有检查必须在同一次批量巡检中完成同一份渲染而不是为每条规则单独截图往返。这与 SKILL.md 中批量一轮、批量修复、至多再确认一轮的有界验证哲学一致避免开放式自我 QA 消耗预算。Verify 共 9 项下面逐条展开并给出可直接落地的量化依据1. Contrast对比度正文与占位文本 ≥ 4.5:1大号文本 ≥ 3:1即 WCAG AA 门槛。文档特别强调在彩色表面上次要文本要用该色相或前景色做 tint永远不要用灰色。模型最常见的偷懒是把次级文字直接设为#999这在彩色卡片上一律达不到设计系统的标准正确做法是从底色取 hue 方向调配一个降低饱和/明度的衍生色。2. Depth层级/阴影阴影必须同时带有位移offset与柔和模糊blur。零位移的彩色光晕box-shadow: 0 0 20px #6ee7b7这类glow halo只是装饰不是深度语言不构成 elevation。3. Spacing间距小组件内部紧凑、组与组之间留白充足、标题上方的留白要大于标题下方。文档要求Read the computed values即必须读取浏览器计算后的实际数值而不是看代码里写的意图值。这与 layout 主题中optical as well as mathematical alignment的要求一致参见 .gemini/skills/impeccable/reference/polish.md。4. Type字体排印文档给出四个量化地板正文字宽measure65–75ch避免过长或过短的阅读行长展示级字号上限6rem字距下限tracking floor-0.04em不允许更极端的负字距训练数据里模型常用 -0.05em 甚至更紧来伪装精致标题需平衡balanced headings字号阶梯与字重阶梯要明显可辨。最后一条是硬约束在每一个断点跑真实文案修复任何溢出。这正好对应仓库反模式夹具 body-text-viewport-edge.html、extreme-negative-tracking.html 与 undersized-ui-text.html 所针对的溢出、负字距与过小字号问题。5. Motion动效只有一个精心编排的时刻one authored moment而不是到处散落的特效更不是每个 section 都套同一个入场动画。缓动使用从已可见的默认状态出发的指数缓出exponential ease-out并强调动效素材库要超越 transform 和 opacityblur、backdrop-filter、clip-path、mask、shadow只要保持流畅都属于可用的调色板。反模式 blinking-cursor.html、pulsing-dot.html 与 reveal-working.html 就是这类未经编排的动画的标本。6. States状态覆盖hover、disabled、loading、error、empty五态外加真实内容而非 lorem、可工作的控件、响应式组合、键盘焦点。这是能跑通主流程之外最容易缺失的一半模型常只写 happy pathloading/empty/error 全靠漏。7. Browser surfaces浏览器表面这是全文最精彩的一条也是文档点名模型跳过率最高的一环The parts you did not draw still carry the design.文本选区颜色、光标caret、自定义滚动条、focus ring、下划线偏移underline offset、表格数字的字体这些都由浏览器默认值提供而浏览器默认值不属于任何设计系统。文档的判断是把这些从调色板统一主题化是这页面是被精心构建的、而不是被拼装出来的最便宜的信号。对应的规则标签rule:skill-craft-browser-surfaces说明它已经进入 detector。8. Copy文案使用产品自己的语言控件命名其动作删除项目而非操作错误信息同时说出问题是什么 如何恢复。这与 [clarify.md] 家族命令的职责一致也对应rule:skill-copy-design-material。9. Coverage覆盖度简报中的每一项需求都必须出现并且在数秒内可找到。这是把方向契约与交付物对齐的最终闸门对应rule:skill-floor-brief-coverage。Refuse类别默认值不是禁令Refuse 清单有一个精确的定性前提必须先读清楚These are the categorys defaults, not bans: the briefs own words can earn any of them.它们是这类项目/这类模型产物的默认套路而非绝对禁止。只要简报的白纸黑字能挣回earn其中任何一项就可以用反之在轴线上自由的时候伸手去够这些默认值说明你根本没有在做决定you were not deciding而意识到这一点之后要做的不是软化这个元素而是重写它。清单分为两个层次页面脚手架page scaffolds与表面习惯surface habits。唯一的绝对禁令ban出现在脚手架第一条里后面详述。Page scaffolds页面脚手架1. 同尺寸的图标 标题 正文卡片阵列作为页面结构。文档的措辞很重卡片是懒惰的容器the lazy container嵌套卡片永远是错的nested cards are always wrong。这正对应规则rule:ban-identical-card-grids与rule:skill-layout-cards-lazyREADME 首页点名的 cards nested in cards 模型通病以及夹具 icon-tile-stack.htmlicon tile 堆叠与 design-system.html 所覆盖的场景。2. hero-metric 模板大数字 小标签 支撑性统计 accent 点缀rule:skill-ban-hero-metric。这类数星星型 hero 是 SaaS 模板重灾区。3. 标题上方加 kicker 或 eyebrow。这一条是禁令ban不是默认值原文明说 no brief earns it back没有任何简报能把这条挣回去。理由很干脆标题自己承担分量The heading carries its own weight删掉那行小标签让标题自己说话。仓库为此提供了最细致的夹具组kicker-above-heading.html 用两栏对比该报的 kicker与合法的大写标签hero-eyebrow-chip.html 则把 classic/span/pill/已大写四种 eyebrow 变体放进 Should flag 栏同时验证letter-spacing: normal的普通大写标签、heading-tag 排除、tabpanel 内上下文标签属于 Should pass。有趣的是eyebrow 禁令还演化出了长度上限的工程判定超过 60 字符的连续大写句不再判 eyebrow说明这条规则在 detector 里是被认真标定的。4. Section 编号01 / 02 / 03除非这个序号本身承载读者需要的信息如确需指明阅读顺序。夹具 numbered-section-markers.html 展示了01 Strategy、02 Prototype这类应该被标记的样式规则为rule:skill-ban-numbered-section-markers。5. 为一个既不需要打断、也不需要受保护焦点的任务开 modalrule:skill-reflex-modal-by-reflex。模态框是用轮子砸钉子的默认反应只在真正需要独占焦点时才合法。Surface habits表面习惯渐变文字gradient text强调应来自字重或字号而不是渐变填充。若想强调却去做渐变说明排印阶梯本身没立起来。玻璃与模糊glass / blur当作装饰而非某个具体效果如真正的毛玻璃分层语义。卡片、列表项、callout、alert 上超过 1px 的彩色border-left/border-right侧边彩色条纹。这类侧边条 浅底 圆角是仪表盘告警组件的最廉价写法。**硬位移阴影box-shadow: 4px 4px 0**出现在并非真正 neobrutalist 的世界里。零模糊块状阴影是戏服不是深度系统一个没有主动选择该风格的世界永远不该把它当默认值获得。Sparkline、进度环、带柔和阴影的圆角矩形冒充内容rule:skill-reflex-decorative-chrome用装饰性 chrome 占住本该由真实内容/图表占据的位置。用等宽字体扮演技术感monospace as a costume而不是真的在展示代码、数据或度量值。用系统展示字体Impact、Arial Black、平台无衬线体作自有世界页面的展示声部rule:skill-ban-system-display-face。文档要求去获取并自托管一个与已批准 lettering 气质相符的字型最接近的已安装字体是失败不是 fallback。用 Unicode 字符或 emoji 顶替图标系统。图标应该是画出来的——来自真正的图标库或手写 SVG且全程保持一致的描边与字重。用几何蒙版圆形、多边形、radial-gradient 抠图冒充有机轮廓。用几何形状近似照片主体边缘是廉价的版本读起来比干脆不抠还差正确做法是从真实图像导出 alpha matte或产出真正的 cut-out 素材。这与 docs/COMP-FIDELITY.md 中记录的撕裂纸张拱门被实现成 17 个顶点的clip-path: polygon案例互为印证。按类别选浅色/深色。light/dark 不应由这是 landing 还是 dashboard决定而应由使用场景决定谁在用、在哪用、在什么环境光下。动画红线永远不要 hover 时让图片动起来Refuse 清单之后还有一条独立的、不分情况的红线Never animate an image on hover, directly or through its parent. It is not an action target. Give the container the feedback.图片不是动作目标hover 一张产品图时让图片本身缩放/位移是错误交互正确做法是把反馈给到容器如边框、阴影、overlay 按钮。这条规则在仓库主副本中以rule:skill-interaction-gemini-no-image-hover标注。从文档到可执行craft floor、detector 与评审 Agent 的三层分工craft floor 的价值不在于多一份规范而在于它处在整个 Impeccable 治理链的一个精确节点上。从仓库内容可以还原出这样的协作结构编辑器内实时层design hookhooks.md 说明钩子会对.tsx/.jsx/.html/.vue/.svelte/.astro/.css/.scss/.sass/.less/.ts/.js等设计相关文件的直接编辑运行 detector每次编辑只报机械、无歧义、值得打断本次编辑的问题坏图、溢出裁切、对比度与可读性失败、渐变文字、glow 阴影、设计系统漂移更深层的品味问题在 Stop 事件上做一次性深度扫描。craft floor 之所以无需在钩子激活时逐条重审正是因为这些机械项已被钩子承接。写码前的人工层craft floor 本身凡是扫描器无法编码的——这是默认值还是被挣回的例外这张图该不该动这套字是不是在扮演技术感——全部由 floor 在编辑 UI 前加载兜底。成品评审层finish-reviewer 等 Agentplugin/agents/impeccable-finish-reviewer.md 明确要求评审 Agent 读取 craft floor 的 Refuse 清单并把截图逐项对照kickers and eyebrows, hard offset shadows outside a neobrutalist world, glyph icons, system display faces, gradient text, side stripes, and the rest被禁止的元素即使与 comp 完全一致也是必修项material fix因为 builder 在写它之前加载的是同一条禁令对 comp 的忠实不能授权 floor 拒绝的东西。这条检查存在的理由也很实在在无钩子的 harness 里最近两次 live 会话曾有五个 kicker 通过了从不检查的评审者。反向保护层documenterplugin/agents/impeccable-documenter.md 要求文档 Agent永远不要把 craft floor 的拒绝项制度化为设计系统规则若成品因简报/世界选择而携带了被 floor 拒绝的元素kicker、硬位移阴影、glyph 图标、系统展示字体只能记入 not-canonized 行作为这个 build 携带的缺陷绝不能写进 DESIGN.md 成为未来页面的家规。仓库给出的反例教训是一次 live 会话发了五个编造 kickerdocumenter 把它们的样式写进了 DESIGN.md一条违规就此变成了 house style。这套写码前加载 编辑中钩子 成品时对照的三明治结构正是 floor 文档中当 torn between refined and committed, commit这类判断能够被稳定执行的组织保障。落地建议把 floor 变成你自己的编码前检查表如果你在自己项目里使用 Impeccable 或只是借鉴这套方法论下面是一份可直接照抄的收缩版检查顺序按一次渲染、一次批量巡检执行[Verify] 1 对比度 正文/占位 ≥4.5:1大字 ≥3:1彩色面上的次要文字同色相 tint禁用灰 2 深度 阴影 offset blur零位移彩色光晕只是装饰 3 间距 读 computed value组内紧、组间松标题上留白 标题下留白 4 字体 行宽 65–75chdisplay ≤6remtracking ≥ -0.04em每个断点跑真文案防溢出 5 动效 只留一个编排时刻指数缓出素材库超出 transform/opacity 6 状态 hover/disabled/loading/error/empty 真内容 键盘焦点 7 浏览器面 选区/光标/滚动条/focus ring/下划线/表格数字全部主题化 8 文案 控件说动作错误说问题 恢复路径 9 覆盖 简报每一条需求都在、数秒可找 [Refuse]除非简报白纸黑字挣回 页面脚手架等尺寸 icon标题正文卡片阵列hero-metric标题上方 kicker/eyebrow绝对禁令 无信息量的 01/02/03 编号无打断需求却开 modal 表面习惯 渐变文字装饰性玻璃模糊1px 彩色侧边条非 neobrutalist 世界的 4px 4px 0 阴影 装饰 chrome 顶替内容等宽扮技术感系统展示字体emoji/Unicode 顶替图标 几何蒙版冒充有机抠图按品类而非使用场景选深浅色 红线 任何 hover 动效都不许落在图片上给容器把这条清单放在方向已定、即将开始写 CSS的那个时刻执行而不是放回规划阶段。它能拦下的大多数问题——eyebrow、hero-metric、渐变文字、图片 hover 动画——都是模型在训练数据里学来的默认值惯性当你注意到自己正伸手去够其中某一项时停下来重写元素而不是把它调淡一点继续用。结语地板只托底不指方向文档用两句话收束也是它全部方法论的分界线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.地板只负责机械层面的完整永远不替你选择视觉方向。当全部检查转绿就把页面预算花在已承诺的视觉世界上当你在打磨得更精致和忠实于已承诺的世界之间摇摆时选择忠实。对一次真正的构建而言detector、hook、craft floor 能保证的是没有一处低于地板而让页面高于地板的东西来自方向阶段已经钉死的那个世界不在这份清单里。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考