企业官网建设流程全解析

impeccable typeset 排版指南：在既有视觉体系内打磨字体层级、可读性与加载策略

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

本文是一篇技术指南，围绕 AI 设计工程技能impeccable的typeset增强命令（对应参考文档.pi/skills/impeccable/reference/typeset.md）展开：当用户请求"改善排版 / 字体层级"时，Agent 应当如何在不替换既有视觉身份的前提下，用一套可复现的评估—设定—落地—验证流程提升界面排印质量。读完你会掌握 impeccable 对"排版即信息载体"的判断框架、其双轨评估方法与机械扫描命令的用法、落地排版系统时的具体规则（正文基准、行长、行高、暗色补偿、可变字体与回退字体），以及 live 变体模式下scale签名参数的正确书写方式。文中结论均可在仓库的 SKILL 定义、参考文档与脚本数据中得到印证。

1. typeset 在 impeccable 命令体系中的定位

在 impeccable 中，typeset是一个Enhance（增强）类命令。根据 .pi/skills/impeccable/SKILL.md 的 Commands 总表，它的正式定义是：

围绕它可以画出完整的命令关系网：

• 评估侧：critique（UX 设计评审）、audit（可访问性 / 性能 / 响应式技术检查）为排版问题提供入口，typeset的机械扫描阶段会调用其自带 detector；
• 增强侧：layout处理间距与节奏、colorize处理颜色，typeset专攻字体家族、字号层级、字重与阅读参数；
• 收尾侧：验证通过后移交/impeccable polish做最终打磨；
• 变更边界：若排版的改动会"创造一个新身份"（而非在既有身份内改良），则不属于typeset的职责，应路由到 reference/new-work.md 并更新 DESIGN.md。

skill 的 allowed-tools 声明了两种可用的执行方式：Bash(npx impeccable *)与Bash(node .pi/skills/impeccable/scripts/*)（见 SKILL.md 的 front-matter）。这也解释了参考文档中机械扫描命令为何以node .pi/skills/impeccable/scripts/...形式出现——它依赖 skill 自带脚本。值得注意的是，SKILL.md 的 Setup 步骤规定：脚本的<skill-base-dir>由运行时加载的 base directory 解析，.pi/skills/impeccable/scripts仅作为"运行时未报告 base directory 时"的兜底路径。

同类参考文档在仓库中针对不同助手运行时做了多份镜像（如 skill/reference/typeset.md、plugin/skills/impeccable/reference/typeset.md 以及.claude/、.cursor/、.gemini/等目录下的副本），内容同源。本仓库.pi目录下的这份是参考文档的权威载体。

2. 排版改良的首要原则：信息、层级与声音，都在既有视觉世界里发生

参考文档开宗明义：排版承载着信息（information）、层级（hierarchy）与声音（voice）。它的改良准则是——在已确立的视觉世界内部改进排版，除非用户明确要求，否则不要替换既有身份（identity）。这是typeset与"重设计"之间的分水岭：

• 若排版替换会创造一个新身份（比如系统性引入另一套字体家族、推翻既有比例体系），就必须路由到 new-work.md，并把结论写回 DESIGN.md；
• 否则，应当保留已被确认的字体家族，只改进它们的使用方式（字号角色、字重搭配、行距、字距、对比与加载）。

而"在哪个世界内工作"取决于目标表面的Visitor mode（访客模式）。impeccable 把界面按访客成功形态划分为四种模式，typeset只对其中两类给出差异化策略，并叠加原生平台特例：

从仓库源码结构看，原生平台是独立的分支：reference/目录中专门存放了 ios.md 与 android.md，并配套adapt.native.md、audit.native.md；CLAUDE.md 也明确说明，detectCLI 与设计 hook只面向 Web，当 PRODUCT.md 声明了ios/android/adaptive原生平台时，路由会跳过 live 与detect.mjs，hook 也会跳过扫描——因为原生项目恰好就是 hook 所监视的那类.tsx/.ts/.js文件。因此，在执行typeset前判断清楚目标表面属于哪种模式、跑在哪个平台，是第一位的方向性决策。

3. 双轨评估：排版评估与机械扫描必须隔离运行

参考文档要求在动手编辑前执行两项相互独立的评估，这是typeset方法论最鲜明的特征。若环境中存在可用的 sub-agent 工具且被允许，两项评估应并行独立进行；否则按顺序自行完成。关键约束是：绝不能让 detector（机械扫描）的发现锚定（anchor）设计评估——机械工具只能发现"规则可判定的机械问题"，无法判断字体是否契合产品气质、层级是否表达恰当。

3.1 排版评估：逐题回答，并给出文件 / 选择器 / 计算值证据

选取有代表性的页面与样式，回答下列六组问题，每个答案都必须落到文件、选择器或计算值上，不允许空泛断言：

3.2 机械扫描：跑 detector，只把它当"地板"

评估的第二轨是机械扫描，运行参考文档给出的命令：

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

其中--json让结果以结构化 JSON 输出，--scope type把扫描范围限定在排版/字体类型问题上，末尾传入目标文件或目录。此外，还要人工检查 detector 无法解读的动态或任意字体值（例如运行时注入的字体栈、通过 JS 拼装的font-family）。

随后把两条评估轨道的结果综合起来再动手，并留意"哪一类问题只有哪条轨道能发现"。参考文档特别强调：一次干净的机械扫描只是地板（a clean scan is a floor, not proof of good typography）——扫描零告警不等于排版优秀，它只证明没有踩到可机械判定的坑。

与这条规则配套的仓库事实：impeccable 用脚本来支撑对字体的量化理解。.pi/skills/impeccable/scripts/data/font-index.json是一份字体索引数据，记录着 pangram 检测文本、字号采样（[48, 14, "48c"]）以及一组可测量的特征：advance（字宽推进）、xRatio（x-height 比例）、stemW（字干宽）、contrast（笔画对比）、serif、roundFrac等，并把字体划分为sans / serif / display / handwriting / mono五类；同目录的font-index-failures.json记录无法完成分析的字体。也就是说，参考文档中"针对实际字面调校行高与字距"的建议，背后确实有按字体逐一量化的数据基础（从该数据文件的 schema 字段可推断，skill 的检测/分析链路会针对具体字体计算上述特征）。

4. 设定排版系统（Set the system）：先声明，再动手

在编辑之前，参考文档要求先陈述清楚"系统"。这不是走过场，而是确保所有后续改动有同一套坐标。需要明确声明的内容包括：

• 界面需要哪些角色（role：primary / secondary / body / metadata / data 等）；
• 这些角色之间预期的对比关系（intended contrast）；
• 阅读的行长与密度（reading measure and density）；
• 哪些既有字面与字重是权威的（authoritative）；
• 是否存在性能、本地化或无障碍约束。

设定系统的两条纪律：

1. 用最少的角色与家族把层级做到无可辩驳——多一个角色、多一个家族都必须有它不可替代的职责；
2. 组合使用字号、字重、空间与色调来表达层级，而不是让"字号"单独扛下所有对比任务；
3. 角色命名与 token 描述的是目的，而非数值（例如--text-body优于--text-16px），这样系统才能在不同缩放与上下文下被复用。

这与 impeccable 的整体设计语言一致：角色、token、间距规则都应表达"承担什么功能"，具体数值是派生结果。执行typeset前通常还会先加载 reference/craft-floor.md（SKILL.md 规定：进入编辑 UI 前必须加载它，它承载质量地板与绝对禁令）——排印改动同样适用这层质量底线。

5. 落地执行（Apply）：排版系统的具体规则

参考文档给出了一套可直接执行的排版操作规则，可归纳为五个主题：

5.1 正文基线与行长（Readable, zoomable body）

• 正文底线 1rem / 16px：普通 Web 正文以1rem / 16px为常态底线，除非密集角色、平台惯例或用户设置能证明更低是合理的。注意底线由 rem 表达，天然兼容用户浏览器字号设置。
• 散文行长 45–75ch：正文排版尽量保持在该区间内，超出后换行体验会显著劣化。

5.2 行高：与行长反向调校，且因人而异

• 行高与行长成反比：更宽的行通常需要更多 leading（行距）。经典排版实践是"行长越长，行距越松"。
• 行高必须针对字面、字宽、语言与对比度调校，而不是套一个普适的比例（如"永远 1.5"）。不同 x-height、不同语种（如东亚文字的基线差异）、不同表面的对比度都会改变最优行高。

5.3 深色表面的浅色文字：三条感知轴同时补偿

当浅色文字压在深色表面上时，只加字重是不够的，参考文档要求在三轴同时补偿：

1. 行高略增（slightly more line height）；
2. 字距略加（a touch more tracking）；
3. 字重升一档（one step more weight）——当字体本身需要时。

这三轴补偿同时作用，才能抵消发光表面（halation）对字形辨认的侵蚀。

5.4 一致性、特性与段落节奏

• 重复角色跨屏幕、跨状态保持一致：同一角色在不同页面出现时，字号/字重/颜色必须相同，这是"角色刻度"（role scale）而非"任意值集合"的体现。
• 善用字体特性：当内容受益时，使用数字特性（numeric）、表格数字（tabular figures）、代码特性（code）与标签特性（label）——例如表格中的等宽数字对齐、代码块中的连字处理。
• 段落节奏二选一：用段间距或首行缩进作为段落节奏的主要手段，两者并用通常会造成"双重标记"（double-marking）边界。

5.5 展示字体的响应与加载纪律

• 营销展示字体可以随可用空间响应：当有用时，让 display type 随视口空间伸缩（呼应 Persuade/Experience 模式下"responsive scale"的取向）；
• 密集产品与阅读表面保持空间可预期：让 Operate/Read 表面的版式在空间上稳定、可预测，不能随营销弹性随意漂移；
• 只加载用到的字体资产与字重；
• 提供度量兼容的回退字体（metric-compatible fallbacks），并避免阻塞文本渲染——防止隐形文字（FOIT）与破坏性 reflow（CLS）；
• 尊重浏览器缩放、用户字体设置、Dynamic Type 与平台文本缩放：排版不得破坏这些可访问性通道。

最后两条铁律：不要为了装饰性牺牲可读性；不要引入第二个字体家族，除非存在"只有它能完成"的明确角色。

6. 验证（Verify）：逐项举证，再跑一次扫描

完成编辑后，参考文档要求用渲染或源码证据逐项回答，禁止用一句干巴巴的 "yes" 代替验证。验证清单：

1. 主、次、正文、元数据各角色在不阅读文字的情况下即可辨认——层级必须由视觉本身承担；
2. 长文本在相关宽度与语言下仍保持舒适；
3. 排版归属于产品与其既有视觉世界——没有生造新身份；
4. 加载过程不产生破坏性 reflow 或隐形文字；
5. 缩放、文本缩放、焦点、对比度与缩小视口路径仍可用；
6. 最终一次机械扫描没有任何未解释的发现（unexplained findings）——即扫描结果与人工排查能对得上。

当层级确认成立后，typeset的职责即告完成，工作移交给/impeccable polish（见 reference/polish.md）做发布前的最终质量关卡。

7. Live 变体模式下的排印签名参数：scale

typeset还与 impeccable 的Live 变体模式（视觉变体：在浏览器中选取元素、批量生成备选方案）直接相关。参考文档规定：排版类的 live 变体必须声明一个粗粒度的scale参数，并把字号坡度（type ramp）写成基于var(--p-scale, 1)的公式。参考文档给出的参数声明 JSON 是：

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

其语义是：滑块取值在0.85（压缩排版）到1.3（放大排版）之间、步进0.05、默认1（原样）；UI 上展示为 "Scale"。这样，同一份字号 token 只需乘以--p-scale，就能在不动结构的前提下整体缩放整个排版系统。

配套的补充规则来自 reference/live.md 的参数契约与参考文档本身：

• 参数种类三选一：range（滑块，写入--p-<id>CSS 变量，字段为 min/max/step/default/label）、steps（分段单选，写入data-p-<id>属性）、toggle（同时驱动--p-<id>: 0|1与属性存在性）。scale属于range类。
• 写法：组件<style>要面向var(--p-<id>, default)书写规则（range/toggle），并用:global(...)包裹，以便运行时挂在根节点上的旋钮值能进入规则作用域。
• 克制：除了scale之外，最多再添加一个pair（配对）或 weight（字重）参数——只有它确实代表一个真实的系统选择时才允许，防止参数面板膨胀成自由样式编辑器。
• 变体差异取向：live.md 明确要求typeset系的每个变体走不同的 pairing 且不同的 scale ratio——即变体之间必须在"字体配对"与"比例"两个轴向上都拉开差距，而不是同一种排版换汤不换药。此外，live 模式的预算（budget）随元素的视觉重量分配，排印类变体也受此约束。

若把 live 变体参数在"烘焙（bake）"阶段固化回真实代码，live.md 也规定了步骤：把参数值代入选择器重写，把var(--p-<id>)字面量或变量的默认值落成确定值，只保留与所选值匹配的:scope[data-p-<id>="VALUE"]分支，并把@scope ([data-impeccable-variant="N"])重定位到真实语义类上——这保证"设计期可变"与"交付期确定"之间平滑过渡。

8. 相关参考与后续链路

typeset是 impeccable 排版能力树中的一个节点，相关文档形成一个相互引用的小生态：

综上，typeset的方法论可以凝练成一条可操作流水线：判断访客模式与平台 → 双轨评估（人工排版评估 +--scope type机械扫描）且互不锚定 → 声明排版系统（角色、对比、行长密度、权威字面、约束）→ 在既有视觉世界内按"角色系统"规则落地 → 用证据逐项验证并复跑扫描 → 移交 polish；若走 live 模式，则用scale范围参数 + 至多一个真实系统级参数驱动排版变体。这条链路把"把字体调好看"这种主观任务，拆成了可评估、可验证、可复现的工程过程。

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