Layout Witness
让页面更易于扫描和使用。为相关元素提供清晰的分组，保持重复组件的一致性，并在内容和视口大小变化时保留这些关系。在编辑时使用这些辅助线来决定需要修复的内容。
在现有的开发标签页中使用 Chrome 扩展。通过其本地代理连接来控制辅助线，并在终端中以 JSON 格式读取页面和元素的测量数据。使用可选的 Playwright CLI 在新的浏览器上下文中进行无人值守的捕获。
连接到现有标签页
将完整的 layout-witness 技能目录作为未打包的扩展加载到 chrome://extensions 中。需要 Chrome 116 或更高版本。
- 设置
WITNESS_DIR为已安装的技能目录。运行(cd "$WITNESS_DIR" && npm ci --omit=dev)一次，然后在一个持久的终端中启动node "$WITNESS_DIR/scripts/agent.mjs" serve。 - 在工具栏中打开开发标签页上的 Layout Witness。在 Agent access 下，粘贴终端打印的配对 URL 并选择 Connect agent。这将授权该标签页。如果缺少访问权限，请要求用户为该标签页配对一次。
- 在同一台机器的任何终端中使用 CLI。在编辑期间保持本地服务器运行。
node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# 编辑项目的 CSS 并等待开发服务器应用它。
node "$WITNESS_DIR/scripts/agent.mjs" measure
measure 会打印页面区域、检查结果以及当前选中的元素（如果可用）。该元素可以包括其渲染的盒模型、外边距、边框、内边距、网格和间距值、排版信息（如果可测量，包括视口基线 Y 坐标）以及 SVG 几何。使用匹配一个可见元素的选择器。在编辑时保持选择，并在浏览器应用更改后再次读取其 JSON。
使用 status 检查连接，clear 仅移除元素辅助线，pick 手动点击选择，import <rules.json> 加载项目规则，defaults 恢复默认规则。使用 stop 移除两条辅助线并清除选择以进行干净审查。使用 start 和 select 恢复。如果标签页应该停止接受命令，完成后使用 disconnect。同源的重载可以在同一路由上恢复辅助线和选择。不同的源或标签页关闭将结束配对。
对于手动审查，使用工具栏弹出窗口中的 Start guides、Inspect element 和 Stop guides。当你想保存副本时，可以使用 Download report。
使用辅助线工作
- 设置预期布局。 阅读项目的布局和组件规则，然后检查现有的 token 和可接受的兄弟组件。写下对任务重要的关系，例如共享的阅读边缘、导航组之间的间距或按钮的内联内边距。在新页面上，从需求文档中选择这些关系并记录你的假设。将扩展的默认网格视为探索性指南。
- 从页面检查到元素。 在编辑之前启动辅助线。捕获渲染的起点并选择拥有问题的元素。当标签拥挤时，使用报告获取精确测量值。对于新页面，在外壳渲染后启动辅助线，并在添加部分和控件时保持辅助线开启。
- 在选择激活时编辑源代码。 将测量值与预期值进行比较。修复拥有该关系的 CSS 或共享组件。当开发服务器应用编辑时，在切换到另一个元素之前检查同一元素的辅助线和测量值。如果重载替换了元素，确认恢复的选择仍然指向预期的控件。记录实际值、预期值和测量结果。
- 审查干净的渲染效果。 首先捕获修正后的辅助线，然后关闭辅助线并检查实际页面。检查分组、层级结构、对齐、换行以及在布局变化宽度处的可见焦点。包括长标签或翻译后的内容以及相关的展开、折叠或密集状态。报告剩余的问题以及你检查的宽度和状态。
| 范围 | 检查内容 |
|---|---|
| 页面外壳 | 使用页面辅助线检查共享的阅读边缘、外部边距以及页眉、侧边栏、主区域和页脚在断点处的适配方式。在干净渲染中，检查经常出现的操作是否仍然易于找到，并且主要任务获得最多的视觉强调。 |
| 组和重复组件 | 使用局部网格轨道检查区域内的对齐和跨度。分别比较组之间的空间与每个组件内部的内边距和间距。保持相关项目在视觉上分组，并在组堆叠时验证阅读顺序。 |
| 单个元素 | 选择控件以检查其盒模型、内边距以及图标到标签的间距。比较旨在对齐的标签之间的行高和基线。审查同一系列中的图标大小和描边，然后判断渲染大小的光学平衡。单独测量交互目标与其字形。 |
对于拥挤的侧边栏，首先检查相关链接是否读作一个组，并且相邻部分是否有清晰的间隙。然后选择一行，比较其内边距和图标到标签的间距与等效行的差异。如果共享组件要求每侧 16 像素，而辅助线显示一侧为 8 像素，则恢复 token 并重新测量同一选择。关闭辅助线以检查展开和折叠的侧边栏在上下文中的表现。
对显式预期（如 token 值、命名边缘之间的对齐以及溢出）使用严格检查。在渲染页面中判断层级结构和光学平衡。使用项目的字体比例来决定基线是否应该对齐。
设计参考
- Adobe Spectrum 2 解释了邻近性如何提示关系、间距如何因范围而异，以及如何审查图标间距和系列内的描边。 间距 · 图标基础
- Figma 展示了如何为页面、嵌套区域、组件内边距和文本基线选择辅助线。 布局网格
- Linear 的设计刷新是一个在密集工作空间中可预测的标题操作和视觉层次的案例研究。 设计刷新
当涉及可访问性时，使用 WCAG 检查重排、用户文本间距覆盖以及实际指针目标，包括适用的例外情况。 重排 · 文本间距 · 目标大小
可选的无人值守捕获
当自动化需要跨视口宽度或主题的新浏览器上下文时，使用 CLI。它需要 Node.js 22+ 和 Playwright Chromium。将 WITNESS_DIR 设置为已安装的技能目录并在其中安装其依赖项：
(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)
从项目目录运行 CLI，以便其配置和输出路径在那里解析：
node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
--config ./layout-witness.json --width 1440 --width 390 --strict \
--out .layout-witness/review
阅读生成的覆盖层和 JSON 报告。捕获模式会为每个宽度和主题打开一个新页面。有关区域和检查定义的详细信息，请参阅规则参考。使用 watch 进行交互式 CLI 工作流。