第 37 期 · 前端重构 P5:收尾、无障碍检查与首屏体积审计
· 阅读需 4 分钟
前端重构系列收官阶段(P5 收尾,对应设计文档 07 §8–§10 与 ADR 0042):完成全站无障碍盘点与修复、多宽度多主题 Playwright 冒烟脚本落地,以及对照 P0 前代码的首屏 JS 与中文字体真实传输体积审计。
无障碍系统检查与修复
对照 WCAG 结构与键盘可达性规则对所有页面和 @skinloom/ui 组件做了一轮排查,修掉了以下问题:
- 跳到正文与唯一
<main>地标:在(site)、(app)外壳及 404 页面统一接入<SkipLink />(#main,使用bg-popover/--shadow-popovertoken 与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)与当前版本的真实网络传输:
- 发现并修复
@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%)。 - 与重构前基线对比(原始字节 / gzip):
/:565.3 KB(167.6 KBgzip) →1594.4 KB(454.8 KBgzip,新增了异步加载的three+skinview3d约620 KB用于 3D 走秀);/skinlib:567.1 KB(168.3 KBgzip) →888.4 KB(276.0 KBgzip,+56.6%);/skinlib/show/1:1083.1 KB(295.9 KBgzip) →1633.0 KB(468.1 KBgzip,+50.8%);/about:559.4 KB(165.3 KBgzip) →876.6 KB(272.2 KBgzip,+56.7%);/auth/login:568.1 KB(168.8 KBgzip) →896.9 KB(279.8 KBgzip,+57.9%)。- 未启用 3D 的公开页多出的约
317 KB原始 JS(约107 KBgzip)主要来自 ADR 0042 选定的 Base UI 交互层、@tanstack/react-query与sonner(替换了原先原生<select>、window.confirm与手写状态请求),无法压在+20%以内,已如实记录在 ADR 0042 中。
- 中文字体评估结论:
@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 错误。