• 设计契约

状态、归属与范围

状态与日期：草案，2026-10-26；提出设计方向，不是实现契约

最终负责人：OINK 维护者；分别记录每个预设的验收决定

交付归属：主题维护者负责 CSS、解析器与专项检查器；文档维护者负责双语契约、真实站点夹具与浏览器审查；无障碍评审者负责人工任务证据

基线：OINK v1.4.0；本地源码身份与含未提交修改的快照边界见研究记录

受影响契约：架构、组件、外壳、Landing与视觉预设决策

版本意向：面向后续版本，完成精修后分别决定是否升级为稳定预设；不建议新增预设

背景与证据

Ink 与 Terminal 已作为显式启用的实验存在。共用外壳让读者切换风格后仍能沿用导航、搜索、外观控制与内容语义，这是它们的优势。剩余问题包括装饰重复、正文以外的字体分工、主题自有组件的形状不一致，以及验收覆盖不足。Ink 已经是 中性无衬线编辑风格；改为衬线会占用 Folio 的独立定位。Terminal 应成为 易读的工程手册，以等宽字体承载技术角色，以比例字体承载解释性正文。

带日期的研究区分了源码事实、实测结果、设计判断和有限 CSS 覆盖实验。正常字号测量、间距探测及专项检查提供了积极证据，但整页页脚溢出仍然存在。手动 200% 文字放大与 400% 浏览器缩放验收仍需独立于 32px 字号偏好探测完成。

目标与明确排除项

两种候选都必须适用于 Docs、Book、Blog、画廊、Expo 与 Landing，覆盖中英文、深浅色及宽窄视口。它们都不是独立外壳、无障碍模式或表格密度模式。本次排除新渲染器、全局间距改动、字体下载、运行时依赖、终端特效、移动选择轨迹、凸起 Tabs、带框 Field 名称和 Paper 标题尾线。

两个可选概念继续留在 1.4 范围之外：

提议行为与边界

保留配色，明确角色

初期保留以下源码颜色。表中为浅色／深色配对，不构成新的配置权威；预设 SCSS仍是实现归属。在改色相之前，先减少重复强调。

成功、警告、错误与信息保留各自的语义色、图标和标签。不能把 Ink 的全部状态变红，也不能把 Terminal 的全部状态变成薄荷色。中性徽章不能看起来像成功状态。装饰分隔线可以较淡；识别控件所必需的边界要独立测量对比度。

作者设置的 theme_color 继续控制强调表面。真实文档使用蓝色 #245f94/#5da2dd，Book 使用橙色 #9a3412/#fb923c，Blog 使用紫色 #6d28d9/#a78bfa。它们不会取代链接／代码文字角色。作者强调色和预设默认值均需审查。

保留阅读角色，验证真实字体回退

Book 图注、表格描述及供人阅读的搜索标题／摘要使用正文角色。作者编写的章节编号保留其含义，沿用所属标题的字体角色。Terminal 的技术路径、命令控件和标识符保持等宽。Field 名称保持无框、600 字重。描述性 Terminal 表头改用正文角色 0.875rem/600；普通正文保留 1rem/1.7 与共用阅读宽度。展示标题沿用页面尺度并允许换行；不能为了容纳等宽界面而缩小移动端正文。

现有无衬线回退顺序为 -apple-system、BlinkMacSystemFont、PingFang SC、Hiragino Sans GB、Microsoft YaHei、Segoe UI、Roboto、Helvetica Neue、Arial、Noto Sans SC、通用 sans-serif 与 emoji。等宽列表在 IBM Plex Mono 后依次为 SFMono-Regular、Cascadia Code、Roboto Mono、Menlo、Consolas、Liberation Mono、Sarasa Mono SC、Noto Sans Mono CJK SC 和通用 monospace。列出字体名称不会安装字体。YaHei 排在 Segoe 之前，也可能承载拉丁字符。中文不必占用拉丁等宽字符格。保留语言元数据、typography: system、显式角色及旧 Sass 优先级；在真实 Windows／Android 上分别检查字体已加载、被阻止、系统字体和角色覆盖条件。（字体匹配）

建立层级与按语言区分的链接规则

比较 Ink 正文 h1 的 750 字重／-.025em 字距、h2/h3 的 700／-.012em，以及替代现有粗线的 1px 强线条 token 顶线。中文标题字距为零。取消次级标题、表头、提示块标题的强制大写与字距。Terminal 标题使用 600／零字距；移除生成的 ##／### 及提示块括号，保留作者的 Book 编号、语义标签与标题锚点。不添加伪提示符、闪烁光标特效或装饰性标题尾线。

Ink 正文链接静止时保留原生下划线，包括列表、注释与引用。Terminal 保留持续可见的非颜色链接提示；在真实正文中验证既有半粗体提示，提示不足时使用原生下划线。导航依靠位置和持续的当前状态标记。悬停不得改变布局、字重或命中区域。（GOV.UK 链接）

下划线位置仍待评审。覆盖实验使用 max(1px, .06em) 线宽、.22em 偏移，并对中文比较 .25em／skip-ink: none。不接受一律使用 .25em 的规则。 应比较英文 .12–.18em 与中文 text-underline-position: under 加 0–.06em 小偏移，先使用 skip-ink: auto。按实际语言限定，覆盖英文页面内的中文块。测试混合字符、标点、下伸部、行内代码及跨行链接；线条不得碰撞字形或相邻行。（CSS Text Decoration 草案）

统一组件状态

自有组件圆角：Ink 0px、Terminal 2px，无层叠阴影；纳入目前写死 0.6rem 的 FileTree 圆角。保留图片、头像、状态圆点与 vendor 形状。

当前／选中：Ink 保留静态强调色侧线；Terminal 保留中性反色行／标记。保留程序可识别状态。悬停、选中与键盘焦点相互区分，不使用移动胶囊。

焦点：立即呈现静态指示，在每种相邻表面上独立测量，强制颜色模式下可见；不全局清除轮廓。

文字选择：从现有作者强调色填充开始：alpha 浅色 22%、深色 35%；测量合成后的文字／行内代码配对。必要时通过归属角色修复，不能假定该不透明度已经合格。

Tabs：扁平标签、静态底部选中线、独立焦点；无凸起活动标签。保留键盘、hash／存储行为、长标签和触控区域。

Fields 与输入框：技术 Field 名称不加框，说明保持正文。真正的输入控件仍需持续标签、可辨边界和关联错误文字；占位文字不能单独充当标签。

代码与表格：克制的单层边框；保留语法语义、注释、复制、标题、表头关系与数字对齐。描述性表头可换行，不全表大写。保留作者指定的宽度／溢出策略及局部滚动入口。

注释、引用、脚注：重要内容持续可见；语义标记／线条克制，出处紧邻，引用／返回链接可用。不添加巨大引号、全篇中文斜体或侧边注释栏。

卡片、步骤、徽章、折叠块：标签与形状稳定；区分可点击与静态内容，保留真实步骤编号、原生折叠语义及带标签的状态。

搜索与外观：搜索标题／摘要使用正文角色，技术路径等宽；匹配、选中和弱化文字均可读。保留对话框焦点及返回、输入法编辑、加载／错误／无结果反馈，以及移动键盘展开时的可操作性。

Landing、Blog／画廊、Book、Expo：保留现有构图与媒体行为；展示标题、图注、署名与工具适应各自阅读任务。不对图片表面施加全局方角重置。

保留输出、vendor 与安全边界

Mermaid／ECharts 继续 只跟随深浅模式；API 控件保留 vendor 配色及既有模式行为。不向 vendor DOM 增加预设重着色层。Giscus 自动配色跟随预设与模式，显式覆盖仍有优先权，但本次未验收被阻止的远程 iframe。打印在白纸上使用浅色预设；无 JavaScript 时保留站点默认浅色与可读内容。Markdown／RSS 保留语义内容，不泄漏装饰前缀或控件。继续使用现有转义、字体／颜色输入校验、本地素材和外观存储行为，不新增网络权限或脚本依赖。

兼容与迁移

保留预设名称、独立的模式／风格状态、外壳列宽、断点、内容语法与作者覆盖。Paper 继续默认，维护中的消费站保留显式 [paper, slate, ink, terminal] 菜单。精修可以随版本交付，同时继续保持实验状态。

升级为稳定预设会改变 preset_menu: true 的结果：它提供稳定预设与站点默认值，因此任一实验升级都会扩大自动集合。必须在 layouts/_partials/preset-config.html、归属检查器和双语配置／版本指引中明确处理。显式列表仍保留作者选择的成员。升级需要逐预设的维护者验收，不能只改状态标签。保留 Folio／Canvas 保留名称的警告／回退行为。

实现与归属检查器计划

运行时修改还需 node --test 'tests/js/**/*.test.js'；Schema 修改需 python3 bin/generate-config-schema.py --check。

验收门禁与待决问题

区分无障碍要求与项目强化目标

以 WCAG 2.2 A／AA 为基线（参考资料访问日期为 2026-10-26）。

完整任务记录先于稳定化升级

两种语言、两种模式都必须覆盖 320/390/768/1440px，包括正常、放大及覆盖间距的文字。审查长文顶部／中段／页脚、标题／Book 编号、URL、Fields、表格、代码、搜索、外观、媒体与 Landing。检查静止／悬停／当前／选中／焦点／文字选择、强制颜色、减少动态效果，以及无 JavaScript／打印／Markdown／RSS。记录实际颜色配对与 axe 不完整结果的人工审查。

真实 Windows Chrome／Edge、Android Chrome 的字体／渲染工作仍待完成，品牌版 macOS／iOS Safari 检查也未完成。记录设备、操作系统、浏览器与字体条件。人工任务仍需 Windows 上的 NVDA、真实 Safari 上的 VoiceOver、Android 上的 TalkBack：遍历标题及有意义编号，读取表格／字段错误，使用中文输入搜索，听取简洁状态反馈，打开／关闭对话框并恢复焦点。

待决事项包括中文下划线方案、项目强化目标、必要的状态颜色修复，以及各预设是否升级。门禁未关闭时，保持实验状态或推迟精修；其它 1.4 工作无需等待新风格。

决策日志