排版评审输出规范：为 talebook 前端质量门禁编写可执行的排版评审报告

本文以仓库 .agents/skills/better-typography/review-output.md 为核心主体，结合同目录技能文档与源码展开。它规定了一套「独立排版评审」的标准化输出格式：发现（Findings）如何按原则分组、用 Severity / Location / Before / After / Why 五列呈现，验证与结论（Verification and Verdict）如何给出 Block / Needs changes / Approve 三态判定。掌握这套规范后，你可以在 talebook 这类 Nuxt 前端项目中，把一次排版走查写成"可复现、可执行、可直接改代码"的评审报告，并融入大型功能的本地界面审查门禁。

为什么排版评审需要固定输出格式

排版问题的主观性很强：同一个「行高偏紧」或「数字跳动」在不同人眼里严重程度不同，评审结论也难以横向对比。review-output.md 的定位是终结这种不一致——它把评审结论压缩成一张可机器解析、可逐行执行的表格，并且明确划分了与 better-interface 的职责边界：

当 better-interface 负责编排时，输出格式、严重级别、合并规则、条数上限与最终结论都由它掌握；本技能只负责提供领域证据与发现（findings）。

这句话界定了两种工作模式：

• 独立排版评审（standalone）：按本文件（review-output.md）的格式输出；
• 编排式评审（orchestrated）：由 better-interface/SKILL.md 统一归并多个领域技能（accessibility、layout、typography、colors、ui），此时排版技能的 Reporting 部分被忽略，改用编排格式。

仓库中 tests/test_project_instructions.py 的 test_interface_review_skill_and_domain_dependencies_are_installed 用例验证了 better-typography 与 better-interface 等技能已被锁定安装（对应 skills-lock.json），说明这套评审机制是项目真实的工程流程而非文档摆设。

评审报告的两段式结构

独立排版评审报告固定分为两部分：

1. Findings（发现）：所有已确认的排版问题，按原则分组；
2. Verification and Verdict（验证与结论）：先列出实际执行的检查与结果，再给出唯一结论。

其中只有已确认（confirmed）的发现才能进入报告——不允许仅凭视觉印象推断代码问题，也不允许仅凭源码推断运行时表现。这是整个格式的纪律底线。

Findings：五列表格

所有已确认的发现按原则（principle）分组，每组使用一张 Markdown 表格，列固定为：

列	含义
Severity	严重级别：HIGH / MEDIUM / LOW
Location	定位：path/to/file:line；无源码的产物则写明具体界面与组件
Before	当前排版现状（贴真实实现，不贴臆测）
After	可操作的替换方案（可直接落进代码的写法）
Why	违反的原则 + 对可读性或层级的影响

格式硬性约束：绝不使用独立的 "Before:" / "After:" 文本行，问题与方案必须同处一行表格单元格内，保证报告的紧凑与可检索性。

Severity 分级语义

严重级别不是「感觉」，而是有明确判定标准的：

• HIGH：文本不可读、不可用，或结构上具有误导性（structural misleading）；
• MEDIUM：损害层级（hierarchy）、换行（wrapping）或扫读（scanning）体验；
• LOW：孤立的排版打磨问题（isolated typographic polish）。

Location：必须精确到行

每条发现必须能定位到 文件:行号。若评审对象没有源文件（如纯设计稿、第三方渲染产物），则改为「精确界面 + 组件名」。这一要求与 better-interface/SKILL.md 的"证据优先"原则一致：不能报告的发现就不该被报告。

Before / After：给出可直接落地的替换

After 列的价值在于可执行。以文档自带的两组格式示例为例（注意：以下路径是格式示范，并非本仓库真实文件）：

示例一：表格数字（tabular numbers）

Severity	Location	Before	After	Why
MEDIUM	src/Price.tsx:17	<span>{price}</span> 渲染实时价格	<span className="tabular-nums">{price}</span>	比例数字（proportional digits）会让价格变动时布局抖动
LOW	src/numbers.css:8	font-feature-settings: "tnum" 1	font-variant-numeric: tabular-nums	高层级属性保留了回退行为，字体不支持时不会失效

示例二：行高与行长（measure）

Severity	Location	Before	After	Why
MEDIUM	src/Article.tsx:33	正文段落使用 leading-none	leading-normal（1.5–1.6）	换行的正文需要足够的垂直间距
MEDIUM	src/article.css:12	全宽文章列	max-width 接近 16px 下的 65 字符	行长过长导致视线难以回行

注意示例一第二行揭示了一个重要原则：有高层级 CSS 属性时优先用属性，而不是底层原始标签（raw tags）。font-variant-numeric: tabular-nums 在字体不支持该特性时能优雅回退，而 font-feature-settings: "tnum" 1 做不到。这一原则来自技能主文档 SKILL.md 的核心原则第 2 条。

合并与省略规则

• 系统性重复问题合并为一行：同一根因在不同组件反复出现，只在表格中占一行，并在该行列出所有受影响位置；
• 无发现的原则不出现：不要为凑齐分组而硬造空表。

这两条与 better-interface 的"一个根因 = 一条发现"规则同源，避免报告变成逐处罗列的水文。

验证与结论（Verification and Verdict）

Findings 之后依次完成两件事：

1. Verification：逐一列出执行过的检查及其观察结果。格式规范点名要求覆盖以下维度（如适用）：

   • 换行（wrapping）
   • 层级（hierarchy）
   • 文本缩放（text resizing）
   • 字体加载（font loading）
   • 动态值稳定性（dynamic-value stability）

   如果某项检查没有执行，必须如实说明「仍待验证」，不得把验证缺口伪装成发现，也不得把未验证项当作通过。这与 better-interface/SKILL.md 原则 8「验证可验证之物」完全一致——检查报告要写确切的命令/交互与观察结果，未能运行的标记为 Not verified 并说明遗留事项。

2. Verdict：三选一，且只能三选一：

   • Block：仍存在任意 HIGH 发现（阻断合入）；
   • Needs changes：仅剩 MEDIUM / LOW 发现（需要修改）；
   • Approve：无任何可行动发现（通过）。

结论与发现数量是强绑定的：只要还有可行动的 HIGH，即使界面再小、表再短，也不能降级为 Needs changes 或 Approve——「有可行动发现却写 Approve」被 better-interface/SKILL.md 明确列为常见错误。

无发现时的完整输出

当评审没有任何问题时，报告按以下顺序输出：

1. 省略所有表格；
2. 陈述一句 "No actionable typography findings"；
3. 照常报告验证过程与结果；
4. 以 Approve 收尾。

空报告是合法结果——它证明了「克制」本身：好的排版大多时候是克制，而不是堆砌效果（见 SKILL.md 开篇）。

支撑 Why 列的原则依据：排版评审的知识底座

review-output.md 只定义格式，判定问题是否成立、以及 Why 列引用哪条原则，来自 SKILL.md。该文档给出 19 条核心原则，评审时常用到的包括：

原则	内容摘要	典型触发场景
原则 7 行高按角色	标题约 1.1，正文 1.5–1.6，用无单位值；换行到 3 行以上的文本至少 1.4	leading-none 用在多行卡片描述
原则 9 限制行长	长文每行 60–75 字符	全宽文章列
原则 10 刻意换行	标题用 text-wrap: balance，描述用 text-wrap: pretty，长文都不用	孤行单词、两行标题失衡
原则 11 表格数字	变化中的数字用 tabular-nums	计时器、计数器、价格
原则 12 截断不丢内容	单行 text-overflow: ellipsis，多行 line-clamp，全文保留在 tooltip 可达	书名、长描述被截断且无查看途径
原则 14 下划线取自字体	text-underline-position: from-font + text-decoration-thickness: from-font	下划线切断字母下行部（descender）
原则 15 移动端输入 16px	iOS Safari 对 <16px 输入会整页缩放	输入框字号过小
原则 16 字号与对比地板	长文正文从约 16px 起，UI 文本 14px、说明 13px，极少低于 12px	14px 上使用细字重
原则 17 根上字体平滑	antialiased 只在根布局应用一次	根布局遗漏字体平滑
原则 18 语言与双向文本	设置 lang/dir，数字不乱序，必要时 <bdi> 隔离	混合方向的值渲染顺序错误

Why 列填写时就是「违反原则 N + 后果」的固定句式，例如：「违反原则 7：换行正文缺少足够垂直间距」。

After 列的落地方案从哪来

写 After 列时可对照 css-cheat-sheet.md，它把技能覆盖的每条 CSS 声明映射到 Tailwind 4 等价工具类，保证建议贴合项目现有样式体系：

• 字号：font-size → text-*
• 行高：line-height → leading-*（无单位 1.5 → leading-normal）
• 表格数字：font-variant-numeric: tabular-nums → tabular-nums
• 行长上限：max-width 65ch → max-w-<a href="https://link.gitcode.com/i/8877ae2160aefe068537aadcad99e351" target="_blank">65ch]（Tailwind 的 max-w-xl ≈ 576px、max-w-2xl ≈ 672px，对应 16px 正文的 60–75 字符区间，见 [wrapping-and-punctuation.md）
• 标题平衡：text-wrap: balance → text-balance
• 描述防孤行：text-wrap: pretty → text-pretty
• 单行截断：text-overflow: ellipsis + 双隐藏 → truncate
• 多行截断：line-clamp → line-clamp-*
• 智能标点、  / ­ 的使用规则见 wrapping-and-punctuation.md

<a href="https://link.gitcode.com/i/2b7311dbbb461af525c69898643de7b9" target="_blank">SKILL.md</a> 的 Reporting 一节明确：独立排版评审在每条已确认发现都按本格式（review-output.md）报告、并附带验证与结论后，才算完成。也就是说，格式规范是评审闭环的收尾标准。

在 talebook 中应用这套规范

talebook 的前端是 Nuxt + Vuetify 体系，仓库实际渲染与字体加载具备评审验证的真实抓手：

• 字体加载检查：项目以 .woff2（Brotli 压缩、浏览器支持广泛）提供字体，例如 app/assets/css/fonts.css 中为 Roboto 的每个字重/子集分别声明 @font-face，配 font-display: swap 与 unicode-range 分片加载。评审验证环节可检查：实际网络加载的字体格式是否为 woff2（而不是 .ttf/.otf）、font-display: swap 是否生效、合成字重（synthesized weight）是否被误用——对应 SKILL.md 原则 1 与原则 3。
• 文本缩放与动态值检查：书库场景中的阅读进度、书页计数、下载量等数字若为实时变化值，应核对是否启用 tabular-nums 避免布局抖动（原则 11）。
• iOS 输入缩放检查：搜索框、登录表单在移动端应确认输入字号 ≥ 16px，或使用 details-and-accessibility.md 给出的「放大到 16px + transform: scale() 还原设计尺寸」两套方案之一（原则 15）。
• 行高与截断检查：书卡片、书架网格中多行书名与描述，应核对 leading-* 无单位取值与截断后的全文可达性（原则 7、12）。

评审结论输出后，若问题被修复，应重新执行受影响的验证项，并在新报告里更新验证结果与结论——这正是 better-interface 流程中「修复后必须重新执行 interface-review」的排版域镜像。

常见评审输出错误速查

以下错误形态来自 better-interface/SKILL.md 的 Common Mistakes，可直接用于自查评审报告本身：

错误	正确做法
多个领域各自输出一份报告	编排模式下合并为一张按严重度排序的表
同一问题被多个技能重复报告	归到拥有底层规则的技能，只报一次
发现无精确位置	引用 文件:行号 并给出当前实现
仅凭源码推断视觉表现	实际渲染确认，或标记 Not verified
无限堆 LOW 级打磨	遵守模式条数上限
悄悄修改代码	默认只读，除非用户要求实施修复
有可行动发现却写 Approve	使用 Needs changes 或 Block

小结

review-output.md 把排版评审从"主观意见"变成"结构化证据"：Findings 表让每条问题都有严重级别、精确位置、现状、可执行方案与原则依据；Verification 让结论可复核；三态 Verdict 让 Block / Needs changes / Approve 与问题存续严格绑定。在 talebook 中，这套格式既支撑独立的排版走查，也作为 better-interface 全界面审查中排版域的领域证据来源，并受 tests/test_project_instructions.py 的技能安装门禁保护。评审人员只需记住一条主线：报告写得能让人逐行执行修复，结论与证据严格对应，评审就完成了它的职责。