# 组件精修验证，2026-10-25

> 四种预设的本地组件验证、资源体积测量，以及独立复现的画廊基线检查失败。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> [!IMPORTANT] 本地验收记录
> 本轮组件修改的 [第 0–3 阶段与第 5 阶段最终验收](/zh/docs/design/decisions/component-refinement/) 已完成。滑动选中背景试验继续暂缓。

## 输入与方法 {#inputs}

最终评审使用隔离的同级 checkout，基于主题 `7f9589f` 和文档 `855d890`，只叠加本任务的源码修改。并行进行的 PlantUML、工具链和工作流修改未混入验收候选，并保留在共享工作区。已验收的实现对应主题提交 `15c39ef`；指南、契约、示例和浏览器覆盖对应文档提交 `81e2be9`。

验证环境为 macOS ARM64、Hugo Extended 0.168.0 与内置 LibSass、Go 1.27.3、Node 26.12.0、npm 11.20.0。浏览器预览使用隔离的同级主题和 `hugo.yml,tests/fixtures/browser.yml`，关闭两种 workspace 机制、文件监听和自动刷新。截图来自真实文档输出，可复用示例归属 [双语对照指南](/zh/docs/components/presentation/)。

## 已执行验证 {#validation}

| 检查 | 结果与范围 |
| --- | --- |
| 主题组件归属检查 | SCSS／编译器钩子、字体、预设、内容原语、组件、代码块与 Landing 均通过。不支持的变体和不适用的命令条会告警并保留内容。 |
| 主题外壳与输出检查 | 外壳、动作、命令面板、键盘、运行时隔离与输出检查通过。输出安全检查覆盖 501 个 fixture 文件，显式允许 fixture 原有的第三方嵌入。 |
| 真实站点 | `make check` 的 64 项非浏览器测试全部通过，包括双语标题、Markdown 输出和内部链接。站点 Markdown 快照的变化来自已核对的导航与反链新增。 |
| 完整浏览器套件 | `make browser` 的 409 项 Chromium 测试通过。最后修正无 JavaScript 时的空命令操作列后，又在新构建上通过全部 20 项呈现测试及 SCSS 检查。 |
| 呈现覆盖 | 四种预设 × 明暗 × 中英双语，1440/768/390/320px 布局，原文复制，原生与完整卡片独立链接，原生折叠，无 JavaScript，打印，触摸目标，减少动态效果，强制颜色，以及 Landing 反馈宽度与对比度。 |
| 补充引擎复核 | Chromium 151.0.7922.34、Firefox 153.0、WebKit 26.5 通过 48 组预设／明暗／语言组合，覆盖 Tabs、Fields、卡片链接及 1440/390/320px 布局。最终的无 JavaScript 命令条也在三个引擎中通过。 |
| 视觉复查 | 查看 Paper、Slate、Ink、Terminal 的真实卡片、折叠块、标签页、命令条和参数名，覆盖明暗与桌面／移动端输出。待视口稳定后截图，确认各预设的几何特征和阅读层级保留。 |
| 生产构建 | 最终候选的压缩生产构建通过。下文资源测量读取生成页面实际引用的 CSS，前后两次构建使用相同文档源码。 |

完整套件的 `A11Y_PATHS` 覆盖中英双语的组件呈现、卡片、提示块、标签页、代码、字段，以及英文徽章和按键，共 14 条路由，另有原响应式无障碍矩阵。呈现 axe 检查扫描 390px 下的文章区域；Landing 检查扫描全部八种预设／明暗组合的命令框。Giscus 请求沿用现有套件做法予以阻止。

## 资源代价 {#assets}

导出的主题基线与最终候选使用相同文档源码和生产构建模式：

| 资源 | 修改前 | 修改后 | 差异 |
| --- | ---: | ---: | ---: |
| 压缩后的主 CSS | 528,665 字节 | 539,450 字节 | +10,785 字节 |
| 主 CSS，gzip | 79,541 字节 | 80,887 字节 | +1,346 字节 |
| 生成的 JavaScript | 39 个文件 | 哈希相同 | 0 字节 |

最终测量替代早期精修候选的 539,437 字节／80,856 字节记录。未新增框架、字体、远程资源或 JavaScript 依赖。

## Tab 评审修订 {#tab-review}

维护者不接受凸起的选中标签。最终样式让单个标签平时背景透明，仅在支持悬停的设备上显示淡底色，以链接色和 2px 底边线标识选中。文字保持相同的中等字重和位置；键盘焦点另有轮廓，粗指针设备的点击目标高度仍至少为 44px。最终引擎复核检查了这些状态、方向键切换和窄屏布局。

## 参数名与最终修正 {#final-corrections}

Terminal 参数名现在与其他预设一致，使用无边框的加重等宽文字。原生 Markdown 表格和完整 Fields 短代码均检查了中英双语与明暗输出。正文中的普通行内代码与按键边框保留各自的表达作用。

最终评审还复现并修正了两个边界问题：

- 原生卡片的整卡标题链接会拦截嵌在强调文字中的次级链接。现在次级控件保持在整卡目标之上，指针检查确认嵌套链接和卡片其余区域均跳转正确。标题的键盘焦点轮廓沿用卡片自身形状。
- 禁用 JavaScript 后，命令条仍保留一小列空白操作区域。现在复制控件可用之前，其包装容器保持隐藏。在三个引擎中，390px 样例的源码列均占满 356px 内部宽度，启用脚本后的复制控件仍正常可用。

## 基线失败与限制 {#limits}

以下两项主题检查在导出的基线和组件候选中完全相同地失败：

- `check-namespace.py`：已提交的博客画廊使用无前缀的 `data-height`、`data-width`、`data-mode`、`data-size`，并读取对应的无前缀 dataset 属性。
- `check-goldens.py`：现有主题快照尚未包含已提交画廊的首屏初始化条件、工具栏图标与画廊标记。用检查器自身的规范化规则对比基线和候选，全部 52 个快照表面均无新增差异。

组件检查器另有一处定向修正：按配置键识别已移除功能，避免把任何 `gallery` 字样都当作旧功能，允许合法的 `blog_gallery` 配置。

本地验收覆盖本轮组件修改和两项最终修正。Ink 与 Terminal 保持实验状态。运行时 JavaScript 未修改。

---

反链：

- [组件精修](/zh/docs/design/decisions/component-refinement/)
- [研究](/zh/docs/design/research/)
- [Ink 与 Terminal 评审](/zh/docs/design/research/2026-10-26-ink-terminal-stabilization/)