Impeccable Craft Floor 解读方向定稿后、动手编辑前AI 必须守住的“质量地板”与禁用模式清单【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccablecraft-floor“质量地板”是 Impeccable 项目中一份独立的设计参考文档它回答一个核心问题当视觉方向brief 或已定稿的 visual world被确定之后真正动手写 UI 代码的那一刻起有哪些机械性检查必须通过、有哪些默认模式必须拒绝。这份文档不做方向决策只负责兜底质量底线是本仓库 skill/SKILL.src.md 里明确规定的“编辑 UI 之前必读”的质量关卡。读完本文你将能系统掌握这套 verify/refuse 检查清单、它与 Impeccable 61 条确定性检测规则及自动 hook 的关系以及如何在自己的 AI 设计工作流中落实它。一、craft-floor 在 Impeccable 工作流中的位置要正确理解 craft-floor必须先看它在主技能流程中的加载时机。在 skill/SKILL.src.md 的 Setup 一节中技能规定了一套三步工作流每次会话运行一次node skill-base-dir/scripts/context.mjs读取PRODUCT.md、DESIGN.md与对应的 surface brief依据请求加载对应命令的 playbook 参考文档确定方向与实现路径在方向direction落定之后、真正编辑 UI 之前立即加载 reference/craft-floor.md。第三步里有一句关键限定“Do not load it for planning-only work.”纯规划类工作不加载它。也就是说craft-floor 不是用来帮你构思方向的灵感手册而是进入编辑阶段的纪律清单它只在“设计已选定、代码待产出”这个边界上生效。这份文档对自己的定位说得很直白“Load this after the direction is settled, and build without announcing the checklist.”——方向确定后加载动手构建时不要再把这份清单念出来。它同时定义了文档之间的优先级被钉住的 briefpinned brief或已提交的 visual world 优先于这里的一切而“你自己的习惯habit”优先级最低永远不能反过来覆盖文档规则。这一点与主技能中“The brief wins”的原则一致craft-floor 是兜底的默认值不是可以凌驾于明确设计意图之上的新权威。另一个重要前置关系在 skill/reference/hooks.md 中说得更直白当 Impeccable 的 design hook设计检测器被启用时它会在你编辑 UI 文件后自动执行一部分机械检查此时 craft-floor 的规则是直接依据 hook 给出的 findings 行动而不是把下面每条规则再手动重查一遍act on its findings instead of re-auditing each rule。hook 覆盖不到的那些“没有扫描器能抓到的反射行为reflexes”才真正由 craft-floor 全权负责——这正是 hooks.md 里那句 “The reflexes no scanner catches live in craft-floor.md” 的含义。二、Verify九类“对建成结果”的检查文档开头便划清了概念边界以下是检查“构建出来的结果built result”的条目而不是检查“意图intention”的条目。即你不能说“我本意是想做好对比度”你要去量。第二条纪律是批量执行方式这些检查应在一次批量巡检batched inspection rounds中一起跑完而不是拆成多次单独截图——因为它们共享同一次渲染the checks share one render。这与主技能中“build fully, inspect once with a batched round, fix in one batch”的核心理念完全对齐。1. 对比度Contrast正文与占位符placeholder文本对比度 ≥4.5:1大号文本 ≥3:1在彩色表面上次级文本要么从**该表面的色相hue**衍生出淡色要么直接用前景色——永远不要用灰色。这条规则在参考副本中对应规则标识rule:skill-color-verify-contrast。灰色文字叠在彩色背景上是 AI 生成页面最常见也最刺眼的通病gray 与彩色表面之间的明度差往往远低于 WCAG AA 门槛。仓库的检测器夹具目录 tests/fixtures/antipatterns/visual-contrast.html 与 tests/fixtures/antipatterns/undersized-ui-text.html 正是用来验证这类可被机器判定的对比失败样例。2. 纵深Depth阴影必须同时携带偏移量offset与柔和模糊soft blur。一个零偏移的彩色光晕halo不算阴影那只是“装饰decoration”。对应规则标识为rule:skill-color-no-glow-halo。这条把“发光”与“浮起”两种视觉效果严格分开真实的纵深来自光源方向offset与光线扩散blur而零偏移光晕只说明创作者用特效代替了深度模型。3. 间距Spacing紧凑的分组、宽松的区块间隔标题上方的空间要比下方更多more space above a heading than below it检查时必须读取计算后的实际值computed values而不是用肉眼估。这是最容易被偷工减料的一项——肉眼感觉“还行”不代表计算值成立。检测器规则rule:skill-layout-spacing-rhythm对应此条强调间距节奏是布局层级的可量化信号。对应夹具见 tests/fixtures/antipatterns/cramped-padding.html。4. 排版Type正文行长measure65–75ch展示级标题display字号上限 6rem字距tracking下限-0.04em即不能比 -0.04em 更紧标题要平衡balanced字号层级与字重要有明显的阶梯变化在每一个断点breakpoint下用真实文案渲染凡溢出即修复。对应规则标识为rule:skill-typo-floor排版地板与rule:skill-ban-text-overflow禁止文本溢出。仓库用 tests/fixtures/antipatterns/extreme-negative-tracking.html、tests/fixtures/antipatterns/oversized-h1.html、tests/fixtures/antipatterns/text-overflow.html 等夹具把这几条固化成可回归的负例。同源扩展在带规则标识的完整副本 skill/reference/craft-floor.md 中Codex 专属段落进一步补充tracking 实际停在 -0.04em而 -0.02em 到 -0.03em 通常读感更好——说明 -0.04em 是硬下限而非推荐值过度收紧字距是常见返工原因。5. 动效Motion整个页面只有一个“被精心编排的时刻one authored moment”而不是到处散落小动效也不是每个 section 都放一个一模一样的入场动画缓动采用从已可见默认状态出发的指数缓出exponential ease-out动效调色板不止 transform 与 opacityblur、backdrop-filter、clip-path、mask、shadow 在保持流畅时都属于可用材质。对应规则标识rule:skill-motion-floor、rule:skill-motion-materials-palette与rule:skill-motion-no-section-fade。含义是把动效当作一个设计决策一个高光时刻而非批量装饰用“从当前状态滑出”而非“从隐藏处整体淡入”的手法避免每个区块排队入场的模板感。6. 状态States与真实内容必须覆盖完整状态矩阵hover、disabled、loading、error、empty同时还要有真实内容、可用控件、响应式布局与键盘焦点keyboard focus。对应rule:skill-floor-shipping可交付状态。这要求页面不能只在“完美主路径截图”里成立——一个空状态、一个加载态、一次键盘 Tab 遍历都是交付前必须走通的验收项。7. 浏览器原生表面Browser surfaces“你没有亲手画的那部分也仍然承载着设计。”文本选区selection、光标caret、自定义滚动条、焦点环focus ring、下划线偏移underline offset、以及表格数据中的数字字形——这些都由浏览器默认样式提供而浏览器默认样式不属于任何设计系统。正确做法是从配色板palette中为它们取主题色。文档特别指出这是“页面是被构建出来的而非拼装出来的”成本最低的信号同时也是模型们最稳定跳过的环节。对应规则rule:skill-craft-browser-surfaces。这句话值得所有 AI 编码工具的使用者记住一套完整的产品级质感往往不在你写的那些组件里而在你根本没想到去写、却被浏览器用默认值填上的边角里。8. 文案Copy使用产品自己的语言。控件要说出自己的动作controls name their action错误信息要说清问题与恢复路径errors name the problem and the recovery。对应rule:skill-copy-design-material。UI 文案不是视觉后的填充物而是“设计素材”本身。9. 覆盖度Coveragebrief 中的每一条需求都必须出现并且能在几秒内被找到present and findable within seconds。对应rule:skill-floor-brief-coverage。这是把整份清单拉回到“brief 至上”的收尾检查质量地板不能以丢需求为代价。三、Refuse默认拒绝的脚手架与表面习惯与 verify 的“必须通过”不同refuse 列出的条目文档称之为“类目的默认值而非禁令the categorys defaults, not bans”——brief 自己的措辞可以为其中任何一项翻案。核心判断标准是当一个轴axis是自由的、你却伸手去拿某个默认模板时说明你没有在做决定意识到这一点意味着应该重写该元素而不是把它做柔和些rewriting the element, not softening it。也就是说默认模板是“想不出决定时偷懒的产物”。一旦你意识到自己在套模板正确动作是重写它而不是给模板打补丁式微调。但列表里有一个例外——它是一条真正的 ban不是 default。3.1 真正的禁令标题上方的 kicker / eyebrowA kicker or eyebrow above a heading. This one is a ban, not a default: no brief earns it back.在标题上方加一个小字眉标kicker/eyebrow如 “FEATURES”、“案例”是 AI 生成页面最泛滥的模板信号之一。craft-floor 的态度斩钉截铁这条是禁令不是默认——没有任何 brief 能把它赎回来。理由也说得清楚标题应该自己承担重量The heading carries its own weight删掉那个小标签让标题自己说话。对应规则rule:skill-ban-eyebrow-on-every-section检测器夹具 tests/fixtures/antipatterns/kicker-above-heading.html 与 tests/fixtures/antipatterns/hero-eyebrow-chip.html 即为此负例。3.2 页面脚手架类默认拒绝拒绝项说明对应规则标识同尺寸“图标标题文本”卡片铺满整页卡片是懒惰容器lazy container嵌套卡片永远是错的rule:skill-ban-identical-card-grids、rule:skill-layout-cards-lazyhero 指标模板大数字小标签支撑统计强调色一套被过度使用的营销页公式rule:skill-ban-hero-metric标题上方加 kicker/eyebrow真正的禁令见上rule:skill-ban-eyebrow-on-every-section章节编号01 / 02 / 03除非序列本身承载读者需要的信息否则不加rule:skill-ban-numbered-section-markers模态框仅当一个任务需要打断或受保护焦点时才可用rule:skill-reflex-modal-by-reflex关于章节编号检测器夹具 tests/fixtures/antipatterns/numbered-section-markers.html 与 tests/fixtures/antipatterns/numbered-section-labels.html 并列存在说明“编号作为真实信息”例如步骤说明与“编号当装饰”在规则层面是被分开对待的。3.3 表面习惯类默认拒绝渐变色文字强调应该来自字重或字号而非渐变。rule:skill-ban-gradient-text相关负例夹具 tests/fixtures/antipatterns/dark-gradient-ground.html、tests/fixtures/antipatterns/oklch-neon-text.html玻璃拟态与模糊只能作为“具体效果”不能当作装饰rule:skill-ban-glassmorphism-default。彩色左右边框border-left/right超过 1px不能用于卡片、列表项、标注框或提示条rule:skill-ban-side-stripe-borders。1px 以内的细线是合法的结构分隔1px 的彩色侧条则是廉价提示条的代名词。硬偏移阴影box-shadow: 4px 4px 0这类零模糊方块阴影只在真正的新粗野主义neobrutalist视觉世界里成立对没选这种风格的页面它只是戏服costume不是纵深系统rule:skill-ban-hard-offset-shadow。用迷你图sparklines、进度环、软阴影圆角矩形“代替”真实内容rule:skill-reflex-decorative-chrome。等宽字体扮“技术感”monospace 只能用于代码、数据或度量不能当作“我很技术”的戏服rule:skill-reflex-mono-as-technical。系统展示字体Impact、Arial Black、平台默认无衬线作为自有世界观页面的展示字应采购并自托管一个性格匹配已批字符风格的字面“最接近的已安装字体”是失败而非回退rule:skill-ban-system-display-face。用 Unicode 符号或 emoji 充当图标系统图标要“画出来”——来自真实图标库或手写 SVG且保持一致的描边与字重rule:skill-ban-glyph-icons。用几何蒙版冒充有机轮廓用圆形、多边形或 radial-gradient 裁剪来逼近照片主体的边缘是效果的低配版比干脆不裁更难看。正确做法是从真实图像中提取 alpha matte或产出真正的抠图资产rule:skill-ban-geometric-occlusion-mask。按“类目”挑浅色或深色主题明暗模式要按使用场景决定——谁在用、在哪里用、环境光如何rule:skill-reflex-theme-by-habit。从源码结构可以推断这些拒绝项中的绝大多数在 Impeccable 的确定性检测器里都有对应的机器可判规则标识上述表格中的rule:skill-ban-*、rule:skill-reflex-*均来自带规则标注的同源参考副本夹具目录 tests/fixtures/antipatterns/ 下的glow.html、color.html、named-color-borders.html、modern-color-borders.html、radial-spotlight-glow.html、pseudo-stripe.html、icon-tile-stack.html等正反例文件说明“哪些表面习惯该拦”是经过可复现测试验证的而非停留在文字建议层面。四、按运行环境细分的补充条款需要注意本仓库同时维护多份同源分发。除带规则标识的主副本 skill/reference/craft-floor.md 外插件目录还维护 plugin/skills/impeccable/reference/craft-floor.md。在规则更完整的副本中craft-floor 末尾还挂着按宿主环境细分的codex与gemini区块Codex 专属补充rule:skill-typo-codex-tracking-repeat、rule:skill-codex-elevation-radius、rule:skill-ban-codex-ghost-card、rule:skill-ban-codex-over-round、rule:skill-ban-codex-sketchy-svg、rule:skill-ban-codex-stripes、rule:skill-ban-codex-grid-backgrounds、rule:skill-codex-material-honesty、rule:skill-ban-codex-x-theater字距到 -0.04em 为止-0.02 ~ -0.03em 通常读感更好抬升感elevation一次性声明用边框或阴影二选一宽软阴影下再叠 1px 边框就成了“幽灵卡片ghost card”卡片圆角保持在12–16pxpills 只留给小控件插图要么是真插图要么没有手绘风的 SVG 场景、loose-sketch/doodle类名、feTurbulence噪点都读起来业余此条禁止的是用 SVG 模仿图片从不禁止 SVG 做几何——清晰矢量图形、示意图、动画线条、shader 效果仍是第一等媒介。判断标准是带明暗、透视或人物的线稿风插图也算“图片”而几何是指会话能精确指定的形状背景是“表面”只能从主体所在的世界取材纹理repeating-linear-gradient条纹和双轴网格背景底下必须有真实的画布、地图、蓝图或测量工具支撑论断与配置来自给定的真实信息示意性数值要诚实标注“先命名概念再用反讽消解它”不是论断material honesty。Gemini 专属补充永远不要让图片在 hover 时直接或经父级触发动画——图片不是动作目标反馈应给到容器rule:skill-interaction-gemini-no-image-hover。五、使用纪律与优先级再确认craft-floor 的收尾段定义了它在整个技能体系中的角色边界值得逐句理解“The floor holds the mechanics; it never picks the direction.”——地板管住机制从不选择方向。它不替你决定页面长什么样只保证你没把页面做坏在基本功上。“With every check green, spend the page on the committed world.”——当所有检查都绿了之后把整页的精力投入到那个**已承诺的视觉世界committed world**中去。“when torn between refined and committed, commit.”——当你在“更精致refined”与“已承诺committed”之间摇摆时选择已承诺的那个。方向定稿后克制住“再改优雅一点”的冲动忠于定稿世界本身就是 craft-floor 想灌输的最后一条纪律。结合 README.md 的定位1 skill, 23 commands, live browser iteration, and 61 deterministic detector rules与 skill/reference/hooks.md 的分工说明可以把 craft-floor 的地位概括为一句话检测器与 hook 负责能机器判定的 61 条确定性规则而 craft-floor 负责它们抓不到的部分——那些需要审美判断的对比度直觉、动效编排、文案语气与“该不该套这个模板”的决策自觉。它是 AI 设计交付的兜底协议不产生方向但保证无论哪个方向落地时都踩在一条体面的质量地板上。进一步阅读工作流上下文见 skill/SKILL.src.mdSetup 第三步的加载时机与 “Do not load it for planning-only work” 约束hook 与 craft-floor 的分工见 skill/reference/hooks.md带规则标识与平台区块的完整参考见 skill/reference/craft-floor.md可回归验证的负例夹具见 tests/fixtures/antipatterns/。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考