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 总表它的正式定义是命令类别职责参考typeset [target]EnhanceImprove typography hierarchy and fonts改善排版层级与字体reference/typeset.md围绕它可以画出完整的命令关系网评估侧critiqueUX 设计评审、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只对其中两类给出差异化策略并叠加原生平台特例模式typeset 的策略取向适用表面举例Persuade说服 Experience体验展示字体display type可以承载声音。当构图需要时使用果断的对比度与响应式字号缩放让排版主动参与说服与氛围落地页、营销、定价页、作品集、画廊Operate操作 Read阅读稳定性、可扫描性与行长measure优先。通常一个经过精调的家族 一套固定的角色字号fixed role scale就是正确答案应用 UI、仪表盘、编辑器、管理后台、文档、指南Native原生平台遵循 ios.md 或 android.md包含平台级缩放与无障碍行为iOS / Android 应用从仓库源码结构看原生平台是独立的分支reference/目录中专门存放了 ios.md 与 android.md并配套adapt.native.md、audit.native.mdCLAUDE.md 也明确说明detectCLI 与设计 hook只面向 Web当 PRODUCT.md 声明了ios/android/adaptive原生平台时路由会跳过 live 与detect.mjshook 也会跳过扫描——因为原生项目恰好就是 hook 所监视的那类.tsx/.ts/.js文件。因此在执行typeset前判断清楚目标表面属于哪种模式、跑在哪个平台是第一位的方向性决策。3. 双轨评估排版评估与机械扫描必须隔离运行参考文档要求在动手编辑前执行两项相互独立的评估这是typeset方法论最鲜明的特征。若环境中存在可用的 sub-agent 工具且被允许两项评估应并行独立进行否则按顺序自行完成。关键约束是绝不能让 detector机械扫描的发现锚定anchor设计评估——机械工具只能发现规则可判定的机械问题无法判断字体是否契合产品气质、层级是否表达恰当。3.1 排版评估逐题回答并给出文件 / 选择器 / 计算值证据选取有代表性的页面与样式回答下列六组问题每个答案都必须落到文件、选择器或计算值上不允许空泛断言维度要回答的问题权威性与适配性Authority and fit当前确立的是哪些字体家族、字重与角色它们是契合产品与所选视觉世界的还是未经检视的默认值每一个家族都是必要的吗层级Hierarchy标题、正文、标签、元信息、数据等角色能否一眼区分相邻的字号或字重是否过近以至于承担不了不同的职责尺度与一致性Scale and consistency是深思熟虑的角色字号体系还是一堆任意值重复角色在不同屏幕与状态下是否保持一致阅读体验Reading正文是否落在舒适的45–75 字符行长内行高、段落节奏、对比度与字距是否针对实际字体、字宽、语言与表面做过调校压力测试Stress长标题、本地化展开、浏览器缩放、窄容器、缺失字重与字体回退发生时排版会怎样表现交付方式Delivery是否只加载了用到的资源回退字体度量、加载策略与可变字体设置是否避免了隐形文字invisible text与破坏性的 reflow3.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字宽推进、xRatiox-height 比例、stemW字干宽、contrast笔画对比、serif、roundFrac等并把字体划分为sans / serif / display / handwriting / mono五类同目录的font-index-failures.json记录无法完成分析的字体。也就是说参考文档中针对实际字面调校行高与字距的建议背后确实有按字体逐一量化的数据基础从该数据文件的 schema 字段可推断skill 的检测/分析链路会针对具体字体计算上述特征。4. 设定排版系统Set the system先声明再动手在编辑之前参考文档要求先陈述清楚系统。这不是走过场而是确保所有后续改动有同一套坐标。需要明确声明的内容包括界面需要哪些角色roleprimary / secondary / body / metadata / data 等这些角色之间预期的对比关系intended contrast阅读的行长与密度reading measure and density哪些既有字面与字重是权威的authoritative是否存在性能、本地化或无障碍约束。设定系统的两条纪律用最少的角色与家族把层级做到无可辩驳——多一个角色、多一个家族都必须有它不可替代的职责组合使用字号、字重、空间与色调来表达层级而不是让字号单独扛下所有对比任务角色命名与 token 描述的是目的而非数值例如--text-body优于--text-16px这样系统才能在不同缩放与上下文下被复用。这与 impeccable 的整体设计语言一致角色、token、间距规则都应表达承担什么功能具体数值是派生结果。执行typeset前通常还会先加载 reference/craft-floor.mdSKILL.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 深色表面的浅色文字三条感知轴同时补偿当浅色文字压在深色表面上时只加字重是不够的参考文档要求在三轴同时补偿行高略增slightly more line height字距略加a touch more tracking字重升一档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与破坏性 reflowCLS尊重浏览器缩放、用户字体设置、Dynamic Type 与平台文本缩放排版不得破坏这些可访问性通道。最后两条铁律不要为了装饰性牺牲可读性不要引入第二个字体家族除非存在只有它能完成的明确角色。6. 验证Verify逐项举证再跑一次扫描完成编辑后参考文档要求用渲染或源码证据逐项回答禁止用一句干巴巴的 yes 代替验证。验证清单主、次、正文、元数据各角色在不阅读文字的情况下即可辨认——层级必须由视觉本身承担长文本在相关宽度与语言下仍保持舒适排版归属于产品与其既有视觉世界——没有生造新身份加载过程不产生破坏性 reflow 或隐形文字缩放、文本缩放、焦点、对比度与缩小视口路径仍可用最终一次机械扫描没有任何未解释的发现unexplained findings——即扫描结果与人工排查能对得上。当层级确认成立后typeset的职责即告完成工作移交给/impeccable polish见 reference/polish.md做发布前的最终质量关卡。7. Live 变体模式下的排印签名参数scaletypeset还与 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-idCSS 变量字段为 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-idVALUE]分支并把scope ([data-impeccable-variantN])重定位到真实语义类上——这保证设计期可变与交付期确定之间平滑过渡。8. 相关参考与后续链路typeset是 impeccable 排版能力树中的一个节点相关文档形成一个相互引用的小生态需要时查阅作用仓库位置ios.md/android.md原生平台排版平台缩放与无障碍行为ios.md / android.mdnew-work.md当排版替换将创造新身份时改走重设计路由new-work.mdlive.mdlive 变体模式的参数契约、预算与烘焙规则live.mdpolish.mdtypeset 验证通过后的移交目标polish.mdlayout.md间距、节奏与视觉层级的相邻增强命令layout.mdSKILL.md命令表、模式定义与允许工具.pi/skills/impeccable/SKILL.md综上typeset的方法论可以凝练成一条可操作流水线判断访客模式与平台 → 双轨评估人工排版评估 --scope type机械扫描且互不锚定 → 声明排版系统角色、对比、行长密度、权威字面、约束→ 在既有视觉世界内按角色系统规则落地 → 用证据逐项验证并复跑扫描 → 移交 polish若走 live 模式则用scale范围参数 至多一个真实系统级参数驱动排版变体。这条链路把把字体调好看这种主观任务拆成了可评估、可验证、可复现的工程过程。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
