Impeccable 排版实战指南：在既有视觉世界内重构字体层级、字体系统与版式度量

排版同时承载信息、层级与产品的声音（voice）。本文以开源仓库 impeccable 中排版技能的核心工作流文档为主体，完整梳理其 typeset 工作方法论：从“访问模式（visitor mode）”出发判断该保守还是该表现，用一套“双线隔离评估”定位真实问题，再在“设置系统—应用—验证”三步闭环中把字体、字号、字重、行距与行宽调成一套可复用、可缩放、可本地化的字体系统。读完你可以掌握一条可直接落地到前端项目的排版治理路径，也能理解 impeccable 如何用机械扫描与设计审阅相互校验、并以 --p-scale 参数把排版抽象成可在浏览器实时变体模式中调节的“系统旋钮”。

---

1. typeset 命令在整个技能体系中的定位

impeccable 是一套面向 AI 编码代理的“设计技能 + 反模式检测器”体系（见 package.json，版本 3.6.1）。在技能的命令表中，typeset 属于 Enhance（增强）类别，与 colorize、layout、animate、delight、overdrive 同级，其定位是“改善排版”：

通过修正字体选择、层级、字号、字重与可读性，让文字显得有意为之。当用户提到 fonts、type、readability、text hierarchy、sizing looks off，或希望获得更精致、更有意为之的排版时使用。

（见 skill/scripts/command-metadata.json，plugin/skills/impeccable/scripts/command-metadata.json 中同样存在该条目。）

值得强调的是：typeset 处理的是“排版”这一横切质量维度，它不负责整体视觉世界的重造——那属于 new-work，也不负责颜色（colorize）、间距网格（layout）与动效（animate）。当排版做完、层级成立之后，工作流会把手交给 /impeccable polish 做收尾质检。

2. 第一原则：在既定视觉世界里改善，而非替换

参考文档开门见山（.claude/skills/impeccable/reference/typeset.md）：

Typography carries information, hierarchy, and voice. Improve it inside the established visual world; do not replace the identity unless the user asked to.

即：排版必须发生在已经确立的视觉世界内部。技能总纲（.claude/skills/impeccable/SKILL.md）有对应的总原则：“Refinement preserves; redesign replaces”（精修保留、重造替换）——精修保留既有身份、文案与范围内的一切，只把字体用得更好。

由此引出两条硬性分流规则：

• 如果更换字体系统会创造一个全新的视觉身份，则不应走 typeset 的精修路径，而应路由到 new-work.md（新表面/替换视觉世界的完整流程），并同步更新根目录的 DESIGN.md；
• 否则，保留已确认的字族（confirmed families），只改善它们的使用方式：字重搭配、层级关系、字号刻度、行距行宽、平台缩放行为。

3. 访问模式决定排版策略

排版是保守还是放得开，取决于当前表面的“访问模式（visitor mode）”。SKILL.md 定义了四种模式：Persuade（说服/行动）、Operate（操作）、Read（阅读）、Experience（沉浸体验）。typeset 参考文档把四种模式两两分组，给出差异化的排版取向：

模式组合	排版取向
Persuade + Experience（营销落地页、作品集、展示）	展示级字体可以承载品牌声音；当构图受益时，使用果断的对比（decisive contrast）与响应式字号刻度（responsive scale）
Operate + Read（应用 UI、仪表盘、文档、后台）	稳定性、可扫读性（scanability）与行宽度量（measure）优先；一个调教良好的字族 + 固定的角色刻度往往才是正解
Native（iOS/Android）	跟随平台排版规范，遵循 ios.md 或 android.md，包含平台级缩放与无障碍行为

Native 分支的细节在平台参考中有具体可验证的规则。例如 ios.md 要求使用系统文本样式（Large Title 到 Caption）以跟随用户的 Dynamic Type 阅读字号、禁止硬编码点号尺寸，并在验证轮中于大号 Dynamic Type 下检查截断；android.md 则要求使用 Material 3 的类型角色（Display/Headline/Title/Body/Label 的 large/medium/small 映射），用 sp 单位而非固定 px，并以 adb shell settings put system font_scale 1.3 这类命令在真实字体缩放下验收（验完恢复 1.0）。

4. 两项相互隔离的评估

真正动手编辑前，typeset 要求做 两项彼此隔离的评估，且明确“不要让探测器的发现锚定（anchor）设计评估”：

When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let detector findings anchor the design assessment.

4.1 排版评估：六个必答问题

对代表性页面与样式逐一回答下列问题，每一项都必须给出文件、选择器或计算值作为证据（不能只答“是/否”）：

1. 权威性与契合度（Authority and fit）：已确立的字体、字重与角色有哪些？它们契合产品与所选视觉世界，还是未经审视的系统默认值？是否每个字族都有必要存在？
2. 层级（Hierarchy）：标题、正文、标签（label）、元信息（metadata）、数据（data）各角色能否一眼区分？相邻的字号/字重是否过近、无法承载不同的职能？
3. 刻度与一致性（Scale and consistency）：存在的是刻意的角色刻度（role scale），还是随意值的集合？同一角色在不同屏幕与状态下是否保持一致？
4. 阅读体验（Reading）：正文行宽是否落在舒适的 45–75 字符（ch） 区间？行高、段落节奏、对比度与字距是否针对真实字面（face）、宽度、语言与表面单独调校，而不是套通用比例？
5. 压力测试（Stress）：长标题、本地化文案扩展、浏览器缩放、窄容器、缺失字重与字体回退（fallback）时会发生什么？
6. 投递方式（Delivery）：是否只加载用到的字体资源？回退度量、加载策略与可变字体设置是否能避免“不可见文字”和“破坏性回流（reflow）”？

4.2 机械扫描：detector 的类型域检查

排版评估之外，独立运行机械扫描：

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

这份命令按技能运行时的脚本布局书写（{{scripts_path}} 在技能装载时会解析到实际基础目录）。参考文档特别指出：detect 读取的是本地 HTML/CSS，离线即可运行，无需网络、无需 npx（见 routing.md 中对“bundled detector”的说明），因此原生项目（iOS/Android）应跳过此步。在发布形态的仓库里，同样的检测能力由公共 CLI 暴露，见 cli/bin/cli.js：npx impeccable detect [file-or-dir-or-url...]，描述为 “Scan for UI anti-patterns and design quality issues”。

“scope type”扫描会命中哪些与排版直接相关的反模式？ 仓库的 DevTools 面板给出了规则 ID 与修复命令的映射表（extension/devtools/panel.js），其中被归类到 typeset 的典型规则包括：

• overused-font（字体用滥）
• flat-type-hierarchy（扁平的字号层级）
• line-length（行宽失控）与 tight-leading（行距过紧）
• tiny-text（UI 文字过小）与 undersized-ui-text 同类问题
• justified-text（两端对齐导致的排版瑕疵）
• all-caps-body（正文整段大写）
• wide-tracking（字距过宽）与 gradient-text（渐变文字，常与 distill 配合）

这些规则在仓库里有可验证的行为夹具（fixture）：例如 typography.html、typography-should-flag.html（应被判为问题）与 typography-should-pass.html（应通过），以及 overused-font.html、undersized-ui-text.html 等单点样例，说明检测器对“何种排版会被机器判定为不合格”有确定性的预期。

对于检测器无法解释的动态值或任意字体值（例如运行时拼接的 font-family、计算得到的字号），仍需排版评估人工审视。参考文档给出清醒的定位：“A clean scan is a floor, not proof of good typography.”——扫描全绿只是底线，不等于排版好；它需要与设计审阅互相补位。

5. 设置系统（Set the system）

编辑前先把系统约束说清楚，这是“设置系统”步骤。参考文档要求显式陈述：

• 界面需要的角色（roles）清单；
• 角色之间预期的对比度；
• 阅读度量与密度（measure 与 density）；
• 哪些既有字面与字重是权威的（authoritative）；
• 存在哪些性能、本地化或无障碍约束。

随后遵循两条取舍原则：

1. 用最少的角色与字族让层级毫不含糊——刻意组合“字号 × 字重 × 留白 × 色调”四要素，而不是让字号单打独斗；
2. 角色名与令牌应描述“用途”而非“数值”（describe purpose rather than values）。

仓库自身的 DESIGN.md 就是一个“用途化令牌 + 枚举角色刻度”的活样本：typography.scale 在 16px root 下枚举了 8px 到 88px 的整条梯度，每个字号同时给出 rem 写法，并逐一标注用途：

px	rem	角色用途示例
8	0.5rem	装饰性微字：徽标、上标标记
10	0.625rem	overline、最小可读的大写
11	0.6875rem	eyebrow、徽标、标签
12	0.75rem	元信息行、表格 chrome、行内代码
14	0.875rem	紧凑正文、列表行、控件
16	1rem	默认正文
20	1.25rem	卡片与面板标题
24	1.5rem	小节标题
32	2rem	大节标题
48	3rem	小型 display
64	4rem	大 display
80–88	5–5.5rem	英雄区 display（宽视口）

这段注释还记录了这条刻度的来历，恰好是 typeset 方法论的反例教材：被替换的旧字号列表曾有 86 个互不相同的字号，其中包括 6 个介于 13.7px 与 15.4px 之间、读者根本无法区分的近似档位——“Adding a step is a design decision, not a convenience”（增加一个档位是设计决策，不是顺手为之）。DESIGN.md 还说明：named roles 从该梯度中取值；唯一的例外是 display、headline 两个流式角色，它们用 clamp() 端点插值、允许落在档位之间——这正对应 typeset 中“让营销展示字体响应可用空间，同时让密集产品与阅读表面保持空间可预测”的分工。

6. 应用（Apply）：十条操作守则

动手改排版时，参考文档的操作守则可以概括为以下十条，每条都对应明确的工程行为：

1. 正文保底 1rem/16px：保持正文舒适可读、可缩放；除非是密集角色、平台惯例或用户设置另有理由，否则 1rem/16px 是普通 Web 正文的地板（floor）。
2. 散文宽度落在 45–75ch；行高与行宽成反比——更宽的行通常需要更大的 leading。
3. 深色表面上的浅色文字要在三个感知轴上同时补偿：行高略增、字距略增、必要时字重加一档。
4. 行高针对字面、宽度、语言与对比度单独调校，而不是套一个万能比例。
5. 重复角色在不同屏幕与状态下保持一致。
6. 内容受益时，使用数字、表格数字（tabular）、代码、标签等字面特性。
7. 只加载用到的字体资源与字重；提供度量兼容（metric-compatible）的回退字体，避免阻塞文字渲染。
8. 营销展示字体可响应可用空间；密集产品界面与阅读表面保持空间可预测。
9. 保留浏览器缩放、用户字体设置、Dynamic Type 与平台文本缩放。
10. 段落节奏二选一：用段间距（paragraph spacing）或首行缩进（first-line indentation）作为主要段落节奏；两者叠加通常是对段落边界的重复标记。

同时两条红线不可逾越：不得为装饰而牺牲可理解性；不得在找不到“只能由它完成”的清晰角色时引入第二个字族。仓库字体度量数据（skill/scripts/data/font-index.json）按字族记录了 x 比例、字干宽度、对比度、密度区间等特征，可作为判断字面适配与回退策略时的数据支撑（其 schema: 2 结构含探测文本、字号与逐字族的特征条目）。

7. 验证（Verify）：以证据闭环，再跑一遍扫描

验证清单要求逐项给出渲染或源码证据，而不是用一句干巴巴的“yes”代替：

• 主/次/正文/元信息角色在不读内容的情况下也能一眼辨认；
• 长文本在相关宽度与语言下保持舒适；
• 排版属于该产品与其既定视觉世界（没有跑偏成别人的风格）；
• 加载不会造成破坏性回流或不可见文字；
• 缩放、文本缩放、焦点、对比度与收窄视口等路径仍然可用；
• 最终的机械扫描没有任何未解释的发现（unexplained findings）。

完成路径是：先做设计审阅 → 列出排版假设与目标 → 编辑 → 用渲染结果或源码证明每一项 → 重跑一次类型域机械扫描作为最终校验。当层级成立、验证通过后，工作流把手交给 /impeccable polish，进入发布前的最后质检，而不是无限自我打磨。

8. Live 模式下的排版签名参数（Signature Params）

如果 typeset 发生在 impeccable 的实时变体模式（live variant mode）中，排版还需要遵守一套“签名参数”约定：

Every variant declares a coarse scale parameter and authors its type ramp against var(--p-scale, 1).

每个变体必须声明一个粗粒度 scale 参数，并且整套字号梯度都以 CSS 变量 var(--p-scale, 1) 为基准来编写——后续调节 --p-scale 即可整体缩放字号系统：

{"id":"scale","kind":"range","min":0.85,"max":1.3,"step":0.05,"default":1,"label":"Scale"}

参数契约约束如下：

• kind 为 range：min: 0.85、max: 1.3、step: 0.05、default: 1，语义是“全局字号缩放倍率”；
• 当它代表真实的系统选择时，最多再增加一个配对（pairing）或字重参数，不允许堆参数；
• 整体必须遵循 live.md 的参数契约（详见其中的 section 7 预算、freeform bias 与默认主轴线说明）。

这也解释了 live 模式里 typeset 轴的含义——live.md 要求 typeset 变体每次都要同时换不同的字体配对 AND 不同的缩放比例（different pairing AND different scale ratio each），并且字型系统这一轴线被限定为“在可用字面内的配对逻辑、比例、大小写/字重”，新字体与新色相属于 departure mode 的专属动作。

9. 一套可复用的排版治理闭环

综合参考文档与仓库证据，可以把 impeccable 的 typeset 方法论压缩成一条可复用的治理闭环，供任何前端排版重构场景套用：

1. 判断模式：Persuade/Experience 允许展示字体出声；Operate/Read 要求稳定、可扫读、行宽优先；Native 交给平台规范。
2. 守住身份红线：会产出“新身份”的换字族路由到 new-work 并更新 DESIGN.md；否则保留权威字族、改善其用法。
3. 双线独立评估：设计审阅回答“权威/层级/刻度/阅读/压力/投递”六问并给证据；机械扫描执行 --scope type 离线类型域检查，二者结论合流后再编辑。
4. 设置系统：显式写下角色、对比、度量密度与约束；用最少的角色与字族、以“用途”命名令牌。
5. 应用：16px 正文地板、45–75ch 行宽、行高与行宽反比、深色底浅字的三轴补偿、角色跨状态一致、资源只载所需、段落节奏二选一。
6. 验证闭环：每项用渲染/源码证据作答，重跑扫描至无未解释发现，然后交给 /impeccable polish。

这套方法的核心洞察在于：排版不是把字号调“大”或“小”，而是在给定视觉身份内建立一套用途可读、比例刻意、压力可控、平台可缩放的字型系统，并用机器扫描守住“不退化”的底线。你可以在当前仓库中对照阅读参考文档本体（typeset.md）、其姊妹平台文档 ios.md 与 android.md，以及命令元数据与探测规则映射，进一步验证文中的每一条依据。