跳到主要内容

第 37 期 · 前端重构 P5:收尾、无障碍检查与首屏体积审计

· 阅读需 4 分钟

前端重构系列收官阶段(P5 收尾,对应设计文档 07 §8–§10 与 ADR 0042):完成全站无障碍盘点与修复、多宽度多主题 Playwright 冒烟脚本落地,以及对照 P0 前代码的首屏 JS 与中文字体真实传输体积审计。

无障碍系统检查与修复​

对照 WCAG 结构与键盘可达性规则对所有页面和 @skinloom/ui 组件做了一轮排查,修掉了以下问题:

  • 跳到正文与唯一 <main> 地标:在 (site)、(app) 外壳及 404 页面统一接入 <SkipLink />(#main,使用 bg-popover / --shadow-popover token 与 scroll-mt-14);修复之前 <SidebarInset> 与内层 <main> 嵌套渲染出两个 <main> 地标的错误。
  • 地标与控件可读名称:HeaderNav、MobileMenu、AppSidebar、AppTabNav 与组件总览锚点导航补齐 aria-label;AppSidebar 菜单项补齐 aria-current="page",后台设置中心分组切换按钮补 aria-current;UsageMeter 的 role="meter" 通过 useId() 关联可见标签(aria-labelledby)并提供格式化 aria-valuetext。
  • 页面主标题层级:CardTitle 增加 as 属性支持,登录、注册、找回/重设密码、邮箱验证、第三方绑定、首次安装和 OAuth 授权页面全部以 <h1> 输出主标题;SkinViewer 已在上一阶段将 role="img" 移至 <canvas> 而不再包裹工具栏按钮。

首屏 JS 体积优化与 P0 前基线实测对比​

在 Chromium 1228 无缓存冷启动下,使用 1280×800 视口对比了重构前基线提交(7a7f569)与当前版本的真实网络传输:

  1. 发现并修复 @skinloom/ui 桶文件泄漏:排查 chunk 清单时发现 /skinlib 与所有用户/后台页因为同时引入未标注客户端边界的服务端/纯组件与 export * 桶文件,把未使用的 cmdk(102.4 KB)与 Accordion(74.4 KB)等模块一起打了进去。将 index.ts 改为显式命名导出并在 next.config.ts 启用 experimental.optimizePackageImports: ['@skinloom/ui'] 后,/skinlib 消除 6 个冗余 chunk,首屏 JS 从 1148.5 KB 降至 888.4 KB(立减 260.1 KB / -22.7%)。
  2. 与重构前基线对比(原始字节 / gzip):
    • /:565.3 KB(167.6 KB gzip) → 1594.4 KB(454.8 KB gzip,新增了异步加载的 three + skinview3d 约 620 KB 用于 3D 走秀);
    • /skinlib:567.1 KB(168.3 KB gzip) → 888.4 KB(276.0 KB gzip,+56.6%);
    • /skinlib/show/1:1083.1 KB(295.9 KB gzip) → 1633.0 KB(468.1 KB gzip,+50.8%);
    • /about:559.4 KB(165.3 KB gzip) → 876.6 KB(272.2 KB gzip,+56.7%);
    • /auth/login:568.1 KB(168.8 KB gzip) → 896.9 KB(279.8 KB gzip,+57.9%)。
    • 未启用 3D 的公开页多出的约 317 KB 原始 JS(约 107 KB gzip)主要来自 ADR 0042 选定的 Base UI 交互层、@tanstack/react-query 与 sonner(替换了原先原生 <select>、window.confirm 与手写状态请求),无法压在 +20% 以内,已如实记录在 ADR 0042 中。
  3. 中文字体评估结论:@fontsource-variable/noto-sans-sc 在冷启动各页面按 unicode-range 仅下载 10–13 片(565.1–743.7 KB,首页为 12 片 688.8 KB),全部字体(含 Inter 与 JetBrains Mono)共 612.2–830.2 KB。由于标题、按钮与正文同时用到 400、500 与 600 字重,若改用双档静态字重反而会产生双份切片请求,故继续保留可变字体按需分片方案。

多宽度、双主题与亮暗模式自动化冒烟​

新增可复用的 web/scripts/smoke.mjs(bun run smoke),并在 default / brocade 两种主题 × light / dark 两种模式 × 375 / 768 / 1280 三种宽度 × 28 个公开、404 与登录后路由上完成 336 个视图组合 自动化巡检:

  • scrollWidth <= clientWidth 横向零溢出;
  • 顶栏、SkinViewer 与导航地标(aria-label、aria-current)合规,并实测 Skip Link Tab 聚焦跳转 #main 及 375px 移动端抽屉开关交互;
  • 全流程无控制台错误、无未捕获异常及非预期 HTTP 错误。