Impeccable typeset 命令技术解析: AI 设计语言中的排版系统双重评估与落地实践-港品优选

Impeccable typeset 命令技术解析: AI 设计语言中的排版系统双重评估与落地实践

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

Impeccable 是一个面向 AI 编码代理的设计语言项目,通过单一 Skill 加 23 条命令、实时浏览器迭代与 61 条确定性检测器规则来提升 AI 生成前端的设计质量。其中的typeset参考文档(.agent/skills/impeccable/reference/typeset.md)专门解决"排版"这一垂直问题:如何在既定视觉世界中评估、设定并改进一个产品界面的字体系统。读完本文,你可以掌握 Impeccable 的排版工作流全貌——从"设计评估 + 机械扫描"的双重独立评估,到impeccable detect --json --scope type的机械检测命令,再到 Live 模式下scale排版参数的声明契约,并理解每条规则背后的源码与测试依据。

文档定位:typeset 在 Impeccable 技能体系中的位置

typeset 是 Impeccable Skill 的 reference 参考文档之一。仓库中它有三个同源副本,分别对应不同安装位置:

源模板:skill/reference/typeset.md,使用{{scripts_path}}占位符,由构建流程填充;
插件版:plugin/skills/impeccable/reference/typeset.md,命令形如node "<skill-base-dir>/scripts/detect.mjs" --json --scope type;
已安装 harness 版(即本文主体文档):.agent/skills/impeccable/reference/typeset.md,命令指向随 Skill 一起安装的本地可执行脚本.agent/skills/impeccable/scripts/impeccable。

文档开篇给出总原则:排版承载信息、层级与声音;应在既定视觉世界内部改进排版,除非用户明确要求,否则不要替换产品身份。这条原则贯穿全文,也是 Impeccable 与"推倒重来式重设计"的根本区别——它是存量界面的渐进式改良,而非新作品创作。

Visitor mode:按访问者模式区分策略

文档将界面用途分为三种访问者模式,排版策略随之不同:

Persuade + Experience(说服 + 体验型):展示型排版可以承载品牌声音。当构图受益时,使用果断的对比与响应式字号缩放;
Operate + Read(操作 + 阅读型):稳定性、可扫描性与阅读度量(measure)优先。一个精心调校的字族族系配合固定的角色字号阶梯,往往就是正确答案;
Native(原生平台):遵循 ios.md 或 android.md,包括平台缩放与可访问性行为。

文档同时划出身份边界:如果替换排机会创造出一个新身份,就必须走 new-work.md 流程,并更新根目录的 DESIGN.md;否则保留已确认的字族,只改进其使用方式。

双重评估:两份彼此独立的诊断报告

这是 typeset 文档的核心方法论:在有子代理工具且被允许时,让两个评估独立运行;否则由执行者按顺序自行完成。关键纪律是——不要让检测器的发现锚定(anchoring)设计评估。两份评估分别是:

1. 排版设计评估(六问)

检查代表性页面与样式,要求每个问题都回答到"文件、选择器或计算值"的精度:

权威性与契合度(Authority and fit):哪些字族、字重、角色是既定的?它们契合产品与所选世界,还是未经审视的默认值?每个字族是否都是必要的?
层级(Hierarchy):标题、正文、标签、元数据、数据五类角色能否一眼区分?相邻的字号或字重是否过于接近,以至于无法承担不同的工作?
尺度与一致性(Scale and consistency):是刻意的角色字号阶梯,还是任意数值的堆砌?重复出现的角色在不同屏幕与状态下是否保持一致?
阅读(Reading):正文是否保持在 45–75 字符的舒适度量内?行高、段落节奏、对比度、字距是否针对实际的字面、宽度、语言与表面进行了调校?
压力测试(Stress):遇到长标题、本地化文本膨胀、缩放、窄容器、缺失字重、字体回退时会发生什么?
交付(Delivery):是否只加载了用到的字体资源?回退度量、加载策略与可变字体设置是否避免了不可见文本(invisible text)与破坏性重排(reflow)?

2. 机械扫描(Mechanical scan)

运行文档指定的确定性检测命令:

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

该命令对目标文件/目录执行type作用域下的确定性排版规则检查,并以 JSON 输出。除命令输出外,还要人工检查检测器无法解释的动态或任意字体值(例如 JS 运行时拼装的 style、变量插值等)。最后将两份评估综合后再动手编辑,并记录"各自单独捕获了什么"。文档给出了一句重要告诫:干净的扫描只是地板,不是好排版的证明。

检测命令的仓库实现证据

从源码结构看,这条命令有清晰的落地链路:

CLI 入口 cli/bin/cli.js 将detect子命令(以及npx impeccable src/这类把路径当命令的简写形式)路由到检测引擎../engine/detect-antipatterns.mjs,引擎本体随 npm 包分发,仓库内保留入口与分发逻辑;

README.md 中给出的独立 CLI 用法与 typeset 命令一一对应:

npx impeccable detect src/ # 扫描一个目录 npx impeccable detect index.html # 扫描单个 HTML 文件 npx impeccable detect https://example.com # 扫描 URL(Puppeteer) npx impeccable detect --json . # CI 友好的 JSON 输出 npx impeccable detect --no-config src/ # 原始扫描,忽略项目配置/上下文 npx impeccable ignores list # 查看检测器忽略规则

README 说明检测器共覆盖61 条确定性规则,范围从 AI 生成设计的高频劣化模式(侧边 tab 边框、紫色渐变、弹跳缓动、暗色光晕)到通用设计质量(行长、局促内边距、过小触控目标、跳级标题等);
detect默认读取.impeccable/config.json与.impeccable/config.local.json中的detector.ignoreRules、detector.ignoreFiles、detector.ignoreValues、detector.designSystem.enabled配置,与/impeccable hooks命令共享同一份 detector 配置。

另外,sibling 参考文档 layout.md 使用同一条命令的不同作用域(--scope layout),说明--scope是按设计维度切分检测规则集的机制——typeset 文档只消费其中排版相关的一条规则链。

Set the system:编辑前先把排版系统说清楚

文档要求在实际编辑代码之前先显式声明五件事:

界面需要的角色(roles)有哪些;
这些角色之间预期的对比度;
阅读度量(measure)与密度;
哪些现有字族与字重是权威性的;
性能、本地化、可访问性约束。

并给出两条系统级原则:用最少的角色与字族让层级无可辩驳;刻意组合字号、字重、留白与色调,而不是让字号独自承担所有工作。角色名与 token 应该描述用途而非数值(即--font-role-eyebrow优于--fs-12)。

Apply:十二条落地规则

文档的 Apply 一节是可直接执行的检查清单,逐条继承如下:

正文可读性底线:保持正文舒适可读且可缩放。普通 Web 正文下限为1rem / 16px,除非高密度角色、平台约定或用户设置另有理由;
阅读度量:散文保持在 45–75ch 区间;行高与度量反向调校——行越宽,通常需要越大的行距;
暗表面浅色文本补偿:需在三个感知轴同时补偿:略增行高、微增字距、必要时提升一档字重;
行高随字面调校:行高应针对具体字面、宽度、语言与对比度设定,而不是套用某个"通用比率";
重复角色一致性:同一角色在不同屏幕与状态下保持一致;
字体特性:在内容受益时使用font-variant-numeric(tabular/numeric)、代码与标签特性;
字体交付:只加载用到的字体资源与字重;提供度量兼容的(metric-compatible)回退字体;避免文字阻塞渲染;
展示型响应空间:营销展示排版在有益时可响应可用空间;密集产品界面与阅读界面则保持空间上的可预测性;
尊重用户与平台缩放:保留浏览器缩放、用户字体设置、Dynamic Type 与平台文本缩放;
段落节奏单一化:段间距与首行缩进二选一作为主要段落节奏——两者叠加通常等于"双重标记"段落边界;
反面约束:不要为了装饰牺牲理解力,也不要引入第二个字族却没有它能独自完成的明确角色。

这些规则与检测器是互补关系:检测器捕获可机判的劣化,而"第二字族是否必要""行高是否匹配字面"这类判断只能来自上面的设计评估——这正是"两份评估各自单独捕获了什么"要求的由来。

Verify:用证据回答验证清单

编辑完成后,按以下六条逐项验证,并要求每一项都用渲染或源码证据作答,重跑一次机械扫描;不允许用一个光秃秃的"yes"充当验证:

主、次、正文、元数据四类角色在不阅读内容时可被识别;
长文本在相关宽度与语言下依然舒适;
排版归属于产品及其既定世界;
字体加载没有造成破坏性重排或不可见文本;
缩放、文本缩放、焦点、对比度与窄视口路径仍然可用;
最终的机械扫描没有无法解释的发现。

当层级成立后,文档把工作交接给/impeccable polish命令继续,对应参考文档 polish.md。这体现了 Impeccable 命令间的流水线协作:typeset 负责把排版系统立起来,下游命令接力做最终打磨。

Live-mode 签名参数:scale 与参数契约

typeset 文档的最后一节定义了 Live 模式的"签名参数":每个 Live 变体(variant)都要声明一个粗粒度的scale参数,并针对var(--p-scale, 1)编写自己的排版阶梯(type ramp):

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

补充约束:仅当它代表一个真实的系统选择时,才至多追加一个配对(pairing)或字重参数;参数声明必须遵循 live.md 的参数契约。

参数契约的底层机制

live.md 定义了三种参数种类,这解释了上面 JSON 中kind: "range"的工作方式:

range(滑块):驱动--p-<id>自定义属性,组件内以var(--p-<id>, <default>)消费;字段为min/max/step/default/label——scale参数驱动--p-scale,所以 typeset 要求排版尺寸全部写成var(--p-scale, 1)的乘法基;
steps(分段单选):驱动data-p-<id>属性,以:scope[data-p-density="airy"] .grid { ... }这类选择器消费;字段为options/default/label;
toggle(开关):同时驱动--p-<id>: 0|1与属性存在性。

一个已知的限制也值得注意:切换 variant 时参数不会重置,每个 variant 从各自声明的默认值开始。

测试侧的印证

仓库的 Live e2e 测试 tests/live-e2e-agent-output.test.mjs 中,期望的代理输出里出现了--p-scale:1的内联样式(HTML 与 JSX 两种形态),说明scale参数确实贯穿了 Live 模式的代理输出与断言,不是纸面约定。

小结与延伸阅读

typeset 文档的方法论可以浓缩为四个阶段:定模式(Visitor mode)→ 双重评估(设计评估 +--scope type机械扫描)→ 声明系统(角色/对比/度量/权威字族/约束)→ 按十二条规则落地并用证据验证,最后在 Live 模式下以scale参数把排版阶梯接入参数契约。它的显著特点是"双轨制":确定性检测器保证下限,设计评估保证上限,两者互相不替代。

结合仓库可继续深入的文件:

文档主体:.agent/skills/impeccable/reference/typeset.md(源模板 skill/reference/typeset.md,插件版 plugin/skills/impeccable/reference/typeset.md);
相关参考文档:live.md(参数契约)、polish.md(下游交接)、new-work.md(身份替换流程)、ios.md / android.md(Native 平台排版);
CLI 与配置:cli/bin/cli.js(命令路由)、README.md(独立检测 CLI 用法与 detector 配置)。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析