Impeccable layout 命令实战指南：以阅读顺序、间距节奏与密度为核心的界面布局修复方法论-开发者社区

数据库客户端
后端
前端
CLI
桌面应用
数据可视化
AI 应用

【免费下载链接】whodb

Where data access meets operational intelligence

项目地址：https://gitcode.com/gh_mirrors/wh/whodb

本篇指南围绕 whodb 仓库内置的 Impeccable 设计技能体系中的layout命令参考文档展开，讲解如何在保持既有视觉世界不变的前提下，系统性地诊断并修复界面布局的结构性问题——从"眯眼测试"与机械扫描的双通道评估，到设定空间论点、逐条应用布局原则、最终验证并移交 polish。读完你可以在自己的前端项目中复现这套"先诊断结构、再移动盒子"的工作流，并借助仓库内的反模式检测器获得可量化的机械证据。

layout 命令在 Impeccable 体系中的定位

在 Impeccable 技能体系中（见 SKILL.md 的 Commands 表），layout [target]属于Enhance（增强）类命令，职责是"修复间距、节奏与视觉层级"。它的边界非常明确：布局命令改变的是既定视觉世界内部的结构；而身份层面的整体替换（换视觉世界观、重建品牌面孔）属于 new-work.md，不属于 layout 的职责范围。

文档开篇点出了核心命题：布局（Layout）把产品优先级转化为阅读顺序、分组、节奏与可用空间。因此动手"移动盒子"之前，必须先诊断结构性问题的位置，否则一切调整都是在错误结构上打补丁。

按 Visitor mode 决定布局判断标准

布局的好坏没有绝对标准，取决于这个界面服务的是哪种访客模式：

Persuade + Experience（说服 / 体验）：当所选"世界"配得上时，构图可以是不对称的、流动的，甚至刻意具有破坏性——设计本身就是产品。
Operate + Read（操作 / 阅读）：可预测的结构、稳定的密度、可导航的线性是基本的 affordance（可供性），扫描性和一致性优先于表达。
Native（原生平台）：导航、安全区 insets、系统适配与触摸目标分别遵循 ios.md（iOS 44×44pt 触摸目标、Safe Area、系统导航）或 android.md（Material 3、48×48dp 触摸目标、edge-to-edge insets）。

一句话原则：保留既有的视觉世界。布局命令只在其内部改变结构；身份替换属于 new-work。

先诊断：两项相互独立、必须分开完成的评估

在有子代理工具可用且被允许时，两个评估应独立并行运行；否则按顺序自行完成。关键纪律是：机械证据不得混入第一项评估，两项结果综合之后再动手编辑。

评估一：布局评估（Layout assessment）

检查具有代表性的状态与视口，针对以下每个问题，都必须用渲染结果或源码证据作答：

阅读顺序（Reading order）：执行"眯眼测试"（squint test）——眯起眼睛模糊细节后，你还能按顺序识别出主要元素、次要元素和主要分组吗？
分组（Grouping）：相关内容是否紧密相邻、不同分组是否清晰分离？还是容器在替孱弱的邻近关系"背锅"？
节奏（Rhythm）：紧凑与宽松的间隔是否形成刻意的韵律？还是同一个间距值被重复使用到万物等重？
结构（Structure）：拓扑结构是否匹配内容与任务？重复的卡片、列或区块是否真正等价，还是仅仅在沿用某个框架默认模板？
密度（Density）：每个区域的信息量是否匹配使用频率、决策复杂度与访客模式？
适配（Adaptation）：在窄屏、中屏、宽屏、缩放、本地化等状态下，哪些内容重排、折叠、换行、滚动或保持固定？DOM 顺序与焦点顺序是否仍与视觉顺序一致？
极端情况（Extremes）：长内容、空状态、遮罩层、sticky 元素、安全区、小触摸目标是否会暴露结构缺陷？

评估二：机械扫描（Mechanical scan）

运行仓库内置的反模式检测器，只过滤布局相关规则：

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

从源码看，该命令的入口是 detect.mjs，它定位并转发到 detector/cli/main.mjs 中的detectCli()。--scope参数会先校验取值合法性（RULE_SCOPES仅包含规则实际声明的 scope 标签，如type、layout），再通过filterByScopes()只保留声明了layoutscope 的规则产物。当前仓库中声明了layoutscope 的规则（见 detector/registry/antipatterns.mjs）包括：

nested-cards：卡片套卡片，产生视觉噪音与过度的深度；应用间距、字体层级与分隔线来扁平化结构，而不是嵌套容器。
monotonous-spacing：同一个间距值用遍全页、毫无节奏变化；相关内容用紧凑分组，区块之间用宽松间隔。
icon-tile-stack：圆角方形图标容器堆叠在标题上方——AI 生成功能卡的通用模板。
text-overflow：内容渲染宽于容器，溢出或逼出横向滚动条。
cramped-padding：文字贴着容器边缘（有边框/描边/着色背景时至少 8px，理想 12–16px 内边距）。
body-text-viewport-edge：正文贴着视口左右边缘，缺少水平内边距（至少 16px，理想 24–32px）。
heading-rhythm：标题与其上方区块过于拥挤（标题上方的空间应大于下方的空间）。
edge-flush-cards：横向滚动容器内卡片贴着裁剪边缘，圆角被截断。
text-occlusion：文字被重叠的不透明元素遮住。
first-viewport-column-overflow：首屏多列布局中某一列远超一屏，另一列悬空。
content-hidden-at-rest：大量页面文字处于 opacity 0 / visibility hidden（失败的 reveal 动画签名）。
line-length：文本行宽超过约 80 字符（加 65ch–75ch 的 max-width）。
clipped-overflow-container：带 overflow 裁剪的容器截断了需要逃逸的 tooltip / 菜单 / 弹层。
repeated-container-text：同一段文字在单个容器内 3 个以上不同结构位置重复渲染。
content-hidden-at-rest等质量类规则同样挂载在 layout scope 下。

checkPageLayout的实现（见 detector/rules/checks.mjs 中checkPageLayout）可以印证nested-cards的判定逻辑：遍历所有元素，识别"卡片状"元素（isCardLike依据 shadow/border/radius/背景综合判定），排除pre/code、绝对定位、弹出层类（dropdown/popover/tooltip/menu/modal/dialog）后，向上寻找卡片状祖先；命中后只上报最内层的嵌套卡片。

此外，检测器无法解析的部分（任意间距、溢出、堆叠、容器行为）仍要人工检查。一份干净的扫描结果不能证明层级或节奏正确——这正是两个评估必须隔离的原因：机械证据服务于结构性发现，但不能替代对视觉层次的判断。

设定空间论点（Set the spatial thesis）

动手编辑之前，先明确命名以下五件事，形成本次布局改动的主张：

主要阅读或任务路径是什么；
哪些内容必须归组、哪些必须分离；
哪个元素领衔、哪个元素支撑；
预期的密度与间距节奏（松紧模式）；
结构如何随容器、视口、输入模式与内容极端情况变化。

然后选择能表达这些关系的最简结构模型：按照布局原语（layout primitives）实际控制的关系去使用它们，并对可复用的间距与容器角色做语义化命名（不要用space-1、box-2这类与含义脱钩的名字）。文档强调：先用邻近关系表达分组，容器与装饰只是补充手段。

应用原则（Apply）：十条可操作的布局准则

以下原则是 layout 文档的核心操作清单，结合检测器规则可逐条对照落地：

按含义分组（Group by meaning）：优先用邻近性（proximity）建立分组，而非先加容器或装饰。monotonous-spacing与nested-cards两条检测规则分别惩罚"间距无节奏"与"用容器堆砌层级"这两种反面做法。
以紧与宽的刻意对比创造节奏：不要一个间距值用到底。heading-rhythm规则（标题上方空间应大于下方）就是节奏对比的一个可检测落点。
使用文档化的间距刻度，而不是一次性数值：文档特别指出，以 4 为单位的基数（4-unit base）通常能提供纯 8 单位刻度缺失的中间档（如 4 / 8 / 12 / 16 / 24……），这是"刻度粒度"的实战建议。
让层级跟随产品优先级，而不是框架默认值：nested-cards、icon-tile-stack等规则针对的正是"框架/生成器默认模板"而非产品真实优先级。
不同内容保持视觉区分，但不要把每个分组都做成孤立组件：过度组件化同样制造噪音。
让响应式行为结构化：重排、折叠、回流或按需呈现（reorder / collapse / reflow / reveal）取决于"什么仍然重要"，而非机械地逐视口堆媒体查询。
容器感知组件：当同一组件出现在不同上下文时，优先使用容器感知（container-aware）的实现，让组件跟随宿主容器自适应。
用gap表达兄弟元素间的节奏：当gap比子元素各自的外边距更直接表达关系时，优先使用gap。
保持触摸目标可用：即使可见标记很小，可点击区域也不能缩水——原生平台参考 ios.md 与 android.md 的具体数值。
只在澄清状态或层级时才使用深度（depth）；并且光学修正（optical corrections）必须在你检查过真实渲染结果之后再做——不要在未渲染前凭想象微调。

最后一条元准则：变化本身不是目标。重复（repetition）服务于识别，只有内容或优先级真正改变时才打破重复。这与repeated-container-text的判定逻辑相呼应——合法的重复是结构性的（表格列、日历网格、导航列表），而非同一文本在互不相关的结构位置堆叠。

验证（Verify）：以证据作答，而非口头确认

结构修改完成后，逐项验证，每一条都必须用渲染或源码证据回答，禁止用一句光秃秃的"是"代替验证：

眯眼测试仍然能按顺序揭示主要、次要元素与主要分组；
在每种受支持的尺寸下，阅读与任务路径依然清晰；
相关内容自然归组，无关内容不会混为一团；
紧与宽的间距形成有意的节奏，而非单调重复；
密度匹配使用频率与内容复杂度；
长文本、空状态、本地化、缩放与动态内容不会破坏结构；
键盘、触摸与辅助技术的顺序与视觉顺序一致；
最终机械扫描没有无法解释的发现——即重新运行detect.mjs --json --scope layout，任何残留 finding 都要能给出合理解释或已修复。

结构稳固之后，将工作移交给$impeccable polish（参考 polish.md），由 polish 流程处理质量收尾与发布约束。

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

当布局工作进入 Live 变体模式（见 live.md 的参数契约）时，layout 是少数拥有签名参数的命令：每个布局变体都要声明一个粗粒度的density参数，并让间距围绕 CSS 变量var(--p-density, 1)编写：

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

参数语义：kind为range（滑杆），取值范围 0.6–1.4，步进 0.05，默认值 1，即"基准密度"。在 Live 预览中，浏览器会为每个变体渲染一个密度滑杆，用户无需重新生成即可实时调整间距松紧——这正是文档"粗粒度旋钮"哲学的体现：只要用户可能嘀咕"再紧凑一点"或"再舒展一点"，就值得暴露一个参数。

同时，只有当拓扑结构真正发生分支（topology genuinely branches）时，才额外添加一个结构参数；并且必须遵循 live.md 的参数契约（0–4 个参数/变体、按视觉体量配预算、声明在data-impeccable-params上）。默认的density参数承担了 90% 的间距调节需求，额外参数属于"拓扑分叉"这种真正的结构分歧，而不是把微小的 margin 微调塞进参数列表。