企业官网建设流程全解析

impeccable/layout命令实战全解：把产品优先级转化为阅读顺序、分组、节奏与可用空间的结构化布局

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

layout是 impeccable 设计技能体系中专门处理布局、间距与视觉节奏的增强（Enhance）类命令，其定位在 .kiro/skills/impeccable/SKILL.md 的命令表中被概括为 "Fix spacing, rhythm, and visual hierarchy"，官方参考文档位于 .kiro/skills/impeccable/reference/layout.md。它并非"移动盒子"的排版工具，而是一套完整的诊断方法：先通过"斜眼测试（squint test）"、分组、节奏、结构、密度、自适应性、极端场景七个维度定位结构性问题，再以一次机械扫描作为第二重客观证据，最后在"空间论点（spatial thesis）"约束下动刀。读完本文，你将掌握 impeccable 布局改版的标准工作流、其底层评估模型，以及 Live 模式下密度参数的规范写法。

说明：本文所依据的参考文档在仓库中多处镜像分发，除 .kiro/skills/impeccable/reference/layout.md 外，还可在 skill/reference/layout.md、plugin/skills/impeccable/reference/layout.md 找到同源副本。

一、定位：先诊断结构问题，再动手移动盒子

参考文档开篇即给出整个命令的方法论基石：

Layout turns product priority into reading order, grouping, rhythm, and usable space. Diagnose the structural problem before moving boxes.

即：布局 = 把产品优先级转译为阅读顺序、分组、节奏与可用空间。这句话隐含了一个最重要的告诫——如果结构本身是错的，调整间距与对齐只是在掩盖问题。因此 impeccable 的布局流程绝不始于"哪里看着不舒服"，而是始于"这个问题到底属于哪一层"。

在命令元数据 .kiro/skills/impeccable/scripts/command-metadata.json 中，layout被进一步描述为：

Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.

由此可见，/impeccable layout [target]的典型适用信号是：布局不对、间距混乱、视觉层级弱、界面拥挤、对齐问题、希望更好的构图。它与polish（最终质量打磨）、adapt（跨设备适配）、distill（去繁存简）、new-work（全新视觉身份）有明确边界。

值得注意的是，这类"结构性问题"在仓库的反模式测试夹具中也有实证。例如 tests/fixtures/antipatterns/layout.html 用一个左右两栏 HTML 展示了"应被标记（should flag）"与"应通过（should pass）"两种布局形态，其中 flag 栏专门构造了"卡片套卡片（card inside card）""嵌套三层卡片"等经典结构反模式——这类"用容器补偿弱邻近关系"的问题正是 layout 参考文档在分组评估中要打击的对象。

二、访问者模式（Visitor mode）：布局姿态必须服从用户任务

参考文档把布局的设计空间首先交给"访问者模式"——layout不是无差别套用网格，而是按界面所在模式决定结构的可预测程度：

• Persuade + Experience（说服与体验）：当所选视觉世界配得上时，构图可以不对称、流动，甚至刻意具有破坏性。落地页、营销页、作品集这类"设计即产品"的表面允许更大胆的构图自由度。
• Operate + Read（操作与阅读）：可预测的结构、稳定的密度、可导航的线性本身就是 affordance（可供性）。后台界面、仪表盘、编辑器、文档这类表面，结构必须服从任务完成与信息理解。
• Native（原生平台）：导航、安全区 inset、适配、触控目标，必须遵循 ios.md 或 android.md 的平台参考。

同时文档划出一条不可逾越的红线：

Preserve the established visual world. A layout command changes structure inside it; identity replacement belongs to new-work.

也就是说，layout在既定视觉世界内部改变结构，它不负责更换品牌身份；身份级别的替换属于 new-work.md 的职责。理解这一点才能避免布局命令被误用为"偷偷换肤"。

三、两次互相隔离的评估：主观诊断与机械扫描缺一不可

参考文档要求，布局动手之前必须完成两次彼此隔离的评估。当存在可用且被允许的子代理工具时，两者应独立运行；否则就按顺序自己执行。

3.1 布局评估（Layout assessment）：基于渲染或源码证据回答 7 个问题

在代表性状态与视口（representative states and viewports）上逐条检查，且每条都必须有渲染或源码证据：

1. 阅读顺序（Reading order）：做"斜眼测试（squint test）"——眯起眼模糊细节后，是否仍能按顺序识别出主元素、次元素与主要分组？
2. 分组（Grouping）：相关项是否彼此靠近、不同组是否被清晰分开？还是说容器在补偿邻近关系的不足（这正是 tests/fixtures/antipatterns/layout.html 中嵌套卡片的病根）？
3. 节奏（Rhythm）：紧凑与宽松的间距是否构成了有意的韵律，还是单一间距值被重复使用、直到所有元素权重相等？
4. 结构（Structure）：拓扑结构是否匹配内容与任务？重复出现的卡片、列或区块是真正等价，还是仅仅是某个框架的默认产物？
5. 密度（Density）：每块区域的信息量是否与使用频率、决策复杂度及访问者模式匹配？
6. 自适应性（Adaptation）：在窄、中、宽、缩放与本地化状态下，什么会重排、折叠、换行、滚动或保持固定？DOM 与焦点顺序是否仍与视觉顺序一致？
7. 极端场景（Extremes）：长内容、空状态、遮罩层、sticky 元素、安全区、小触控目标，是否会暴露结构失效？

3.2 机械扫描（Mechanical scan）：检测器提供第二重客观证据

参考文档给出的命令为：

node .kiro/skills/impeccable/scripts/detect.mjs --json --scope layout [target files or dirs]

提示：按 .kiro/skills/impeccable/SKILL.md 的 Setup 约定，本技能中所有node .../scripts/...命令都会优先以运行时上报的技能基目录（skill base directory）解析，.kiro/skills/impeccable/scripts仅作为未上报基目录时的回退路径；执行扫描时请保持 cwd 位于用户项目根目录。因此在实际会话中，命令应理解为通过技能基目录解析出的detect.mjs。

文档同时强调两点：

• 除扫描结果外，还要人工检查检测器无法判定的任意间距、溢出、层叠与容器行为；
• 机械证据不得混入第一次评估，应在两次通道都完成后综合判断再编辑；
• 一次干净的扫描并不能证明层级与节奏的正确性——扫描是必要条件，不是充分条件。

这两次隔离评估的设计意图在于：主观视觉判断负责"层级与节奏"，机械扫描负责"可量化缺陷"，二者互不污染，避免"为了应付检测器而改代码"的误区。

四、先立"空间论点"（Spatial thesis）：动手前的五步宣言

参考文档要求在编辑前命名（name）以下内容，把隐性的设计直觉显性化为可验证的论点：

1. 主要的阅读路径或任务路径（primary reading or task path）；
2. 什么应该在一起、什么必须分离（what belongs together and what must separate）；
3. 哪个元素领衔、哪个元素支撑（which element leads and which supports）；
4. 预期的密度与间距节奏（intended density and spacing rhythm）；
5. 结构如何随容器、视口、输入方式与内容极端而变化（how the structure changes across containers, viewports, input modes, and content extremes）。

然后执行核心选择：

Choose the simplest structural model that expresses those relationships. Use layout primitives according to the relationships they control, and name reusable spacing and container roles semantically.

即选择能表达这些关系的最简结构模型；按"关系"而非"习惯"选用布局原语；可复用的间距与容器角色要语义化命名。这保证了布局决策是可推理、可复核、可沉淀进设计系统的，而不是随机的像素调整。

五、应用（Apply）：十二条实战原则

参考文档给出了完整的布局实施原则清单，逐条继承如下，其中每条都服务于"用结构表达优先级"这一核心：

• 按意义分组：先使用邻近性（proximity），再考虑加容器或装饰。
• 用紧凑与宽松间隔的刻意对比制造节奏。
• 使用有文档记录的间距刻度（documented spacing scale），而非一次性取值：通常 4 单位基底能提供 8 单位刻度所缺失的、有用的中间档位。
• 让层级跟随产品优先级，而不是跟随框架默认值。
• 让不同内容保持视觉上的可区分，但不要把每一组都变成孤立的组件。
• 让响应式行为成为结构性的：基于"什么仍然重要"来决定重排（reorder）、折叠（collapse）、回流（reflow）或揭示（reveal）。
• 当同一组件出现在不同上下文时，优先使用"容器感知"的组件（container-aware components）。
• 当gap比子元素 margin 更能直接表达兄弟关系时，用gap表达兄弟节奏。
• 即使可见标记很小，也要保证触控目标可用。
• 只在它确能澄清状态或层级时才使用深度（depth）。
• 光学修正（optical correction）只在检视过渲染结果之后进行。
• 变化本身不是目的：重复应服务于识别；只有当内容或优先级改变时才打破重复。

六、验证（Verify）：没有证据的 "yes" 不是验证

编辑完成后，参考文档要求逐条自证，每条同样必须有渲染或源码证据，然后重跑一次机械扫描：

• 斜眼测试仍能按顺序揭示主元素、次元素与主要分组；
• 在每个支持的尺寸下，阅读与任务路径依然清晰；
• 相关内容自然成组，无关内容不混为一团；
• 紧凑与宽松的间距形成有意的节奏，而非单调重复；
• 密度匹配使用频率与内容复杂度；
• 长文本、空状态、本地化、缩放与动态内容不破坏结构；
• 键盘、触摸与辅助技术的顺序与视觉顺序一致；
• 最终一次机械扫描没有任何无法解释的发现。

文档的原话值得记住："Answer each item with rendered or source evidence, then rerun the scan. Do not substitute a bare 'yes' for verification."——即验证的标准动作是"给出证据 + 重扫"，而不是口头确认。

当结构稳定之后，工作流将移交给收尾命令：

/impeccable polish

这对应 polish.md 中"polish 是精炼而非伪装的重设计"的职责边界：layout 负责结构，polish 负责把结构上的每个细节打磨到发布标准。

七、Live 模式签名参数：density与var(--p-density, 1)

参考文档的最后一节把布局与 impeccable 的 Live 变体模式（见 live.md）对接起来。当用户在浏览器里对元素跑 Live 变体并选用 layout 动作时，每个变体必须声明一个粗粒度的density参数，并把间距对着var(--p-density, 1)来写：

{"id":"density","kind":"range","min":0.6,"max":1.4,"step":0.05,"default":1,"label":"Density"}

这份参数契约的解释如下：

• kind: "range"：渲染为滑杆，驱动 CSS 变量--p-density；
• min: 0.6 / max: 1.4：密度可在"紧凑约 0.6×"到"宽松约 1.4×"之间连续调节，默认值1为基准密度；
• 由于 CSS 默认值写作var(--p-density, 1)，即使参数控件尚未注入，样式仍能优雅回退到基准密度。

作者在被选元素的间距声明中统一使用calc()或乘法式写法（例如间距 = 刻度值 ×var(--p-density, 1)），即可让单个滑杆通吃整个元素内的间距韵律，且零再生成成本——这正是 live.md 参数预算中"粗旋钮（coarse knobs）"的设计意图：把用户可能嘀咕"再紧凑一点 / 再透气一点"的轴暴露成控件，而不是迫使每一次微调都重新生成一次变体。

最后，文档给出一个克制性约束：

Add one structural parameter only when the topology genuinely branches.

即：只有当拓扑结构真正分叉（例如同一内容需要"并排双栏 vs 纵向堆叠"两种真实不同的结构形态）时，才允许额外增加一个结构类参数；仅仅的间距微调应全部收归density一个旋钮。任何新增参数都必须遵守 live.md 的参数契约（0–4 个参数上限、按视觉体量分配预算、range/steps/toggle三种控件语义）。

八、小结：layout 命令的可执行心智模型

把参考文档浓缩为一套可复用的流程：

这套方法论的核心资产，是把"布局问题"从模糊的审美感觉中剥离出来，变成可提问、可扫描、可验证、可参数化的四步工程动作。对于希望让 AI 排版更可控的开发者而言，理解这份参考文档，就等于掌握了 impeccable 处理一切"结构不对"类改版请求时的标准答案——先证明问题在哪一层，再选择最简模型表达关系，最后用参数化把密度决定权交还给使用者。

若需在原生平台应用同一套流程，请并行阅读 ios.md 与 android.md；若本次请求实际是要替换整个视觉身份而非调整内部结构，请改走 new-work.md 的流程。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable