docs: P9-B spec + implementation plan (a11y/keyboard batch — WCAG contrast tokens, toast live-region restructure, skip-link, SPA focus management, table column-header scope, star accessible names)

2026-10-01 21:26:32 +08:00
parent 9226926ebb
commit 0a7eba2682
2 changed files with 387 additions and 0 deletions
@@ -0,0 +1,115 @@
 # P9-B UX 第二批（可访问与键盘效率）· 实现计划
 spec：`docs/specs/2026-10-01-p9b-a11y-keyboard-design.md`（决策 D-A…D-K 以其为准；本计划与 spec 冲突时 spec 赢）。
 仓库：**仅 crearte**（`crearte-monorepo/crearte`），分支 `feat/p9b-a11y-keyboard`。server/deploy 零改动。
 npm 根：`crearte/src`（package.json 在此）。命令一律 `cd crearte/src` 后跑。
 ## 全局约束（逐字，进每个任务简报）
 1. 零新依赖：不得改 `package.json` dependencies/devDependencies；`version` 字段恒 `0.1.0` 不动。
 2. 禁触文件：`e2e/landing.spec.ts`、`e2e/noauth.spec.ts`、`e2e/author-page.noauth.spec.ts`、`e2e/merge-repo.spec.ts`、`e2e/ux.spec.ts`、`e2e/submit-flow.spec.ts`、`e2e/admin-flow.spec.ts`、`e2e/helpers.ts`、`playwright.config.ts`、`playwright.noauth.config.ts`、`vitest.config.ts`、`vite.config.ts`、`vite.config.test.ts`、`scripts/`、`runtime/`（本批完全不动，含 `GameHost.vue`）。
 3. 样式语言：新粗野主义既有 tokens（`border-2 border-ink`、`shadow-hard*`、`bg-paper/surface/ink/highlight/accent/accent-ink/success`、`btn-ink/btn-surface/lift`、`font-mono text-[0.6875rem]`、`sr-only`）。注释中文、标识符英文（仓内惯例）。`app/lib/no-gradient.test.ts` 守卫（禁渐变/禁圆角工具类/禁非零 border-radius）必须继续绿——本批不得引入 `rounded*`、`gradient`、非零 radius。
 4. TDD：先写/改 vitest 跑红，再实现跑绿；每个任务在自己报告里贴 RED/GREEN 的命令与输出摘要。
 5. 每任务独立 commit（前缀 `feat(a11y):` 或 `fix(a11y):` + 任务号）；**CHANGELOG 不由任务写**——控制者在波次末统一补 0.24.0。
 6. 验收命令（每任务收尾自跑并贴输出摘要）：`npm test -- <本任务改动面的测试文件>` + `npm run typecheck`。全量 `npm test` / `npm run build` / `npm run e2e` / `npm run e2e:noauth` 由控制者在波次末跑。
 7. 分支纪律：commit 前 `git branch --show-current` 必须是 `feat/p9b-a11y-keyboard`；不 merge、不 push、不碰 wrapper 仓（ROADMAP/spec/plan 记账归控制者）。
 8. 基线不回退：vitest **601** 全绿、主 e2e **77+1skip**、noauth **4**。既有测试断言只在 spec/本计划明确要求时才可改（本批有两处：`ToastHost.test.ts` 的 `bg-accent`→`bg-accent-ink` 与容器 role 断言反转）。
 9. 精确使用 spec 给定值：skip-link 文案 `跳到主内容`、`href="#main"`、`main` 的 `id="main" tabindex="-1"`；操作列表头 sr-only 文本 `操作`；星标 `aria-label` 模板 `评 ${i} 星`、分组 `aria-label` 模板（未评 `评分`，已评 `评分：${score} 星`）；`--color-success: #1f7a4d`；error toast 类 `bg-accent-ink text-paper`；toast 文本节点 `<p role="status" aria-live="polite" class="min-w-0 flex-1">`。
 10. 本批**不做**移动端汉堡菜单（spec D-K：实测 360px/320px 视口下 `documentElement.scrollWidth` 恰等于视口宽，无溢出）；**不做** `<td>`→`<th scope="row">` 行头重构（spec D-F）；**不做**暗色模式（C 包另行立项）。
 ---
 ### Task 1: 色彩对比达标 + toast 实时区重构（D-A / D-B / D-C / D-I）
 改动文件：`app/styles/main.css`、`app/components/ToastHost.vue`、新 `app/lib/contrast.test.ts`、扩 `app/components/ToastHost.test.ts`。
 **TDD 顺序**：
 1. 先写 `app/lib/contrast.test.ts`（RED：`success` 当前 `#2fa46a`，`paper on success` 只有 3.16，断言 ≥4.5 必红）。逐字实现 spec §3.1 的 `channel`/`luminance`/`contrast` 三个函数（放测试文件内即可，不必新建 lib 模块——它是守卫而非生产代码）。令牌解析：从 `app/styles/main.css` 读文本，正则 `/--color-([\w-]+):\s*(#[0-9a-fA-F]{6})/g` 建 map；先断言 map 至少含 `paper/surface/ink/ink-soft/ink-faint/accent/accent-ink/highlight/success` 九个键（解析失败要红得明确，不要静默跳过配对断言）。
 2. 断言 ≥4.5 的配对（`fg on bg`，逐字用 spec §3.1 清单）：`paper on success`、`paper on accent-ink`、`ink on highlight`、`ink on accent`、`ink-soft on paper`、`ink-faint on paper`、`ink-soft on surface`、`ink-faint on surface`、`paper on ink`、`accent-ink on paper`。断言 ≥3 的：`accent on paper`（焦点环，WCAG 1.4.11 非文本）。断言时给出实测值以便失败可读（例如 `expect(contrast(paper, success), 'paper on success').toBeGreaterThanOrEqual(4.5)`）。
 3. 改 `--color-success: #1f7a4d` → 跑 GREEN（预期 `paper on success` 4.76）。
 4. 改 `ToastHost.test.ts`：① 容器断言反转为**不含** `role`/`aria-live`（`expect(host.attributes('role')).toBeUndefined()`、`aria-live` 同）；② 新断言每条 toast 内 `p[role=status][aria-live=polite]` 存在且 `text()` 等于消息；③ 新断言关闭按钮是实时区**兄弟**：`button.element.parentElement === p.element.parentElement` 且 `p.element.contains(button.element) === false`；④ kind 配色断言里 `error` 的 `bg-accent` 改 `bg-accent-ink`（`success`/`info` 两行不动）；⑤ 既有「点关闭 → store 少一条」用例保留。先跑 RED。
 5. 按 spec §3.5 逐字重写 `ToastHost.vue` 模板 + 按 spec §3.1 改 `KIND_CLASS` 的 `error` 行 → GREEN。`<script setup>` 里除 `KIND_CLASS` 外一字不动（`PhX` import、`useToast` 解构都保留）。
 **陷阱**：容器去掉 `role="status"` 后，`data-testid="toast-host"` 与全部定位类（`pointer-events-none fixed bottom-4 right-4 z-[70] flex w-72 flex-col gap-2`）必须原样保留——`ux.spec.ts`（禁触）与既有单测靠 `data-testid` 定位。`useToast.ts` 一字不动。
 commit：`feat(a11y): P9B-T1 WCAG contrast tokens + toast live-region restructure (D-A/D-B/D-C/D-I)`
 ---
 ### Task 2: skip-link + SPA 导航后焦点管理（D-D / D-E）
 改动文件：`app/App.vue`、`app/router/index.ts`、扩 `app/router/index.test.ts`。
 **TDD 顺序**：
 1. 先扩 `app/router/index.test.ts`，新增 describe「SPA 导航后焦点（D-E）」，RED：
   - `beforeEach` 里往 `document.body` 注入 `<main id="main" tabindex="-1"></main>`（happy-dom 需要元素在文档里 `focus()` 才生效——P10 T5 已验证过这条），`afterEach` 移除它并 `document.activeElement?.blur?.()`，避免污染同文件既有标题用例。
   - 用例①：`makeRouter()` → `push('/')` → `push('/games')` → 断言 `document.activeElement?.id === 'main'`。
   - 用例②（同路径改 query 不抢焦点）：`push('/games')` 后把焦点挪到别的元素（注入 `<button id="probe">` 并 focus），再 `push('/games?tag=数字')` → 断言 `document.activeElement?.id === 'probe'`（**不是** main）。
   - 用例③（`#main` 缺失时静默）：移除注入的 main → `push('/docs')` 不抛错（`await expect(router.push('/docs')).resolves.not.toThrow()` 或包 try 后断言 `document.title` 仍被设置，证明 afterEach 其余职责照常执行）。
 2. 按 spec §3.2 逐字加 `focusMain()` 导出 + 改 `attachTitleHook` 回调为 `(to, from)` → GREEN。既有 `attachTitleHook` 的 title/description 两行与 `r.afterEach` 结构不动，只在末尾加 `if (to.path !== from.path) focusMain()`。
 3. 按 spec §3.2 逐字改 `App.vue` 模板（skip-link 作根 div 首子元素、`<main id="main" tabindex="-1">`）。`<script setup>` 一字不动。
 **陷阱**：`router/index.ts` 的 `routes`/`scrollBehavior`/`beforeEach`/`attachTitleHook(router)` 末行全部不动；`pageTitle.test.ts` 与 `router/index.test.ts` 既有用例（标题基线、description 复位、game 复合 id）必须继续绿。skip-link 用 Tailwind `sr-only focus:not-sr-only` 组合，**不要**在 `main.css` 新增 `.skip-link` 规则（spec D-D）。
 commit：`feat(a11y): P9B-T2 skip-link + focus main on SPA path navigation (D-D/D-E)`
 ---
 ### Task 3: 管理端表格列头语义 + 守卫（D-F / D-G）
 改动文件：`app/views/AdminView.vue`、`app/views/AdminUsersView.vue`、`app/views/AdminAuditView.vue`、新 `app/lib/tableScope.test.ts`。
 **TDD 顺序**：
 1. 先写 `app/lib/tableScope.test.ts`（RED：当前全仓 19 个 `<th>` 零 scope）。仿 `app/lib/no-gradient.test.ts` 的结构逐字复用其 `walk`/`candidates` 思路：递归扫 `app/**/*.vue`（跳过 `*.test.ts`），对每个文件把内容按 `<th` 出现处切分，取从 `<th` 起到其后第一个 `>` 止的片段作为「起始标签」，断言其中含 `scope=`（这样多行书写的 `<th\n  class=…\n>` 也能正确判定）。违规收集为 `相对路径:行号: 行内容` 并 `expect(violations).toEqual([])`。
 2. 给三个视图的每个 `<th>` 加 `scope="col"`（共 19 个），类名/文本/顺序一字不动。两处空表头（`AdminView.vue` 队列表 `<th class="px-3 py-2" />`、`AdminUsersView.vue` `<th class="px-3 py-2" />`）改为 spec §3.3 的 `<th scope="col" class="px-3 py-2"><span class="sr-only">操作</span></th>`。→ GREEN。
 **陷阱**：`AdminView.vue` 有 3 张表（队列/已通过/作品管理），`AdminUsersView.vue` 1 张、`AdminAuditView.vue` 1 张，全部要覆盖；不得改 `<td>`、`<thead>`、`<tbody>`、`data-testid`、任何列文本。`AdminUsersView.test.ts` / `AdminAuditView.test.ts` 既有用例（`listAdminUsers` 调用形状、`user-row-*`、`audit-status-*`）必须继续绿。`AdminView.vue` 无测试文件，不必新建（守卫测试已覆盖其表格语义）。
 commit：`feat(a11y): P9B-T3 table column-header scope on admin views + guard test (D-F/D-G)`
 ---
 ### Task 4: 五星评分可访问名（D-H）
 改动文件：`app/components/GameReactions.vue`、扩 `app/components/GameReactions.test.ts`。
 **TDD 顺序**：
 1. 先扩 `GameReactions.test.ts`，RED：
   - star-1..5 各自 `attributes('aria-label')` 为 `评 1 星`…`评 5 星`。
   - 分组容器（星标外层 `span`）`role="group"`；`rated: false` 的 VIEW 下 `aria-label === '评分'`；构造 `fetchMine` 返回 `ratings: { '<user>/<slug>': 4 }`（沿用该文件既有的 mock 范式，见其 `h.fetchMine.mockResolvedValue` 用例）使 `rated === true`，断言 `aria-label === '评分：4 星'`。
   - 每颗星内层字形 span 有 `aria-hidden="true"`。
   - **既有用例全部保留且必须继续绿**：`.text()` 为 `★`/`☆` 的断言（`aria-label` 不改文本内容，故兼容）、`4.5 · 2 人评分 · 3 收藏`、`fav-btn` 的 `aria-pressed`、点 ♥ 调 `setFavorite`、点星调 `setRating`/`unrate`。
 2. 按 spec §3.4 逐字改 `GameReactions.vue` 的星标分组 → GREEN。`data-testid`、`:disabled="busy"`、类名、`@click="pickStar(i)"`、`litStars` 逻辑、撤评语义（点当前分撤评）全部不动。
 **陷阱**：`role="group"` 加在既有的 `<span class="inline-flex items-center">` 上，不要新增包裹层（会改排版）。`rated`/`score` 是该组件既有 ref（`GameReactions.vue:15-16`），直接用，不要新造状态。
 commit：`feat(a11y): P9B-T4 accessible names for the five-star rating control (D-H)`
 ---
 ### Task 5（控制者本人执行，不派发）: e2e a11y.spec.ts（D-J）
 新增 `src/e2e/a11y.spec.ts` 三条用例（spec §3.6 逐字），既有 e2e 文件与 `helpers.ts` 一字不动。
 **已核实的运行期前提**（避免重蹈 P10 T6 的夹具错误）：
 - e2e 构建（`npm run build:e2e`）注入 `VITE_API_BASE_URL=http://localhost:4173` → `authEnabled` 与 `reactionsEnabled` 均为 true，故 `seedSession` 可用、`GameReactions` 会渲染。
 - `/admin/users` 的表格**需接口有数据才渲染 `<tbody>` 行**，但 `<thead>` 的 `columnheader` 在 `StatePanel` 插槽内、加载完成后即存在；`e2e/admin-flow.spec.ts` 的 `installAdminApi` **未导出**，故本用例自带最小 `page.route` mock：`${API}/api/admin/users**` 返回 `{ users: [<一个 AdminUser>], total: 1 }`，`AdminUser` 形状逐字为 `{ id, email, username, display_name, role, created_at }`（`app/data/types.ts:102-109`）。`toHaveCount(6)` 依赖 6 个 `<th>`（用户名/邮箱/显示名/角色/注册时间/操作）。
 - 星标用例走 `fixture/2048`：其源夹具 `runtime` 为 `external`，但本用例只断言 `star-3` 的可访问名，**不调 `openGame`**（不等 iframe ready），故 external 无碍；`GameReactions` 由 `v-if="game"` 门控，作品页加载完成即渲染。
 - skip-link 用例：`page.keyboard.press('Tab')` 的首站必须是 skip-link——它是根 div 首子元素，页头在其后。`Enter` 后原生锚点跳转把焦点交给 `#main`（`tabindex="-1"`）。
 波次末由控制者跑五腿：`npm test` / `npm run typecheck` / `npm run build` / `npm run e2e` / `npm run e2e:noauth`。
 commit：`test(e2e): P9B-T5 a11y spec — skip-link keyboard path, admin column headers, star accessible names (D-J)`
 ---
 ## 执行顺序与并行性
 T1/T2/T3/T4 改动文件两两不相交（T1: main.css+ToastHost+contrast.test；T2: App.vue+router；T3: 三 admin 视图+tableScope.test；T4: GameReactions）。但四者共用同一工作树与同一分支索引，并行 commit 会争 `index.lock` 并交叉 `git add`，故**串行派发**，每任务完成并过任务级审查后再派下一个。T5 由控制者在四者之后自己写并跑五腿。
 每任务审查重点（任务级审查者的核查项）：禁触清单零触碰、`no-gradient` 守卫仍绿、既有测试断言除授权两处外未被改动、spec 逐字代码与文案的偏差、以及各任务的 D 项是否真达成（不是「看起来改了」）。
@@ -0,0 +1,272 @@
 # P9-B UX 第二批设计：可访问与键盘效率（a11y / keyboard）
 日期：2026-10-01 ｜ 决策链：owner UX 摸底三包（A 浏览器反馈 / B 效率可访问 / C 暗色模式）——A 已作 P9 第一批交付（crearte 0.22.0），第一梯队日常交互包已作 P10 交付（crearte 0.23.0）。本批 = 摸底 **B 包**，并收口 P10 终审转办的 T1(d)（实时区内嵌交互控件）。总纲仍为「继续增强该项目，从用户体验方面」。
 仓库面：纯 `crearte`（前端）。零后端/部署改动。
 ## §1 现状勘查结论（已实测，不是推测）
 已经就位、本批**不动**的面（避免重复劳动与无谓回归）：
 - `:focus-visible { outline: 3px solid var(--color-accent); outline-offset: 2px }` 全局焦点环已在 `main.css:46`，`accent` 对 paper 3.26 / 对 surface 3.64，满足 WCAG 1.4.11 非文本对比 3:1。
 - `prefers-reduced-motion: reduce` 全局归零分支已在 `main.css:95-101`，覆盖 toast/lift/骨架动画。
 - 播放 iframe 已有 `:title="game.name"`（`GameHost.vue:105`）；封面 `<img :alt="game.name">`（`GameCover.vue`）；投稿封面预览 `alt="封面预览"`。
 - 页头三条主导航已有 `:aria-current="onX ? 'page' : undefined"`。
 - `FilterDrawer` 用原生 `<dialog>.showModal()`，焦点圈闭与 Esc 关闭由浏览器负责；关闭按钮有 `aria-label="关闭筛选"` 且 44px 触达面（`min-h-11 min-w-11`）。
 - `BaseSelect` 自绘 listbox 的键盘面已完整：trigger 上 ArrowDown/Up/Enter/Space 开面板，面板内 Esc 关并回焦、Arrow 移动、Enter/Space 选中、Tab 关不回焦，`role=listbox`/`role=option`/`aria-selected`/`aria-expanded`/`roving tabindex` 齐备。
 - 表单控件均有可见或 `sr-only` 的 `<label for>`（CatalogView / AdminUsersView 搜索、SubmitFormView 全字段）。
 - 登录/注册/账号三页的错误提示已做 `id` + `:aria-describedby` 字段级关联。
 - 收藏按钮已有 `:aria-pressed="favorited"`，心形字形已 `aria-hidden`。
 - **移动端页头无溢出**：实测 360px 与 320px 视口下 `documentElement.scrollWidth` 恰等于视口宽（320/360），页头内层 `scrollWidth` 亦相等。故本批**不引入汉堡菜单**——没有需要修的问题，加菜单只会增加键盘陷阱面。
 实测出的真实缺口（本批范围）：
 1. `--color-success: #2fa46a` 对 paper 仅 **2.83**，对 surface 3.16 —— 作为成功 toast 的底色配 `text-paper`（12px 粗体，非大字号）实测 **3.16**，AA 正文需 4.5，**FAIL**。
 2. 错误 toast 用 `bg-accent`（#e8552f）配 `text-paper` 实测 **3.64**，**FAIL**（AA 正文需 4.5）。
 3. 三个管理视图共 **19 个 `<th>` 零 `scope`**，且两个「操作」列的表头是空 `<th class="px-3 py-2" />`（无可访问名）；全仓 `scope="row"` 出现 0 次。屏幕阅读器读表格时无法把单元格与列头关联。
 4. 五星评分按钮的可访问名就是字形本身「★」/「☆」——读屏逐个念「星 星 星」，无法知道这是几分、当前评了几分、点了会怎样。
 5. 全站**无 skip-link**：键盘用户每个页面都要 Tab 过页头（logo + 3 条导航 + 贴纸 + 登录/用户菜单 4 项）才能到正文。
 6. SPA 导航后**无焦点管理**：`router` 的 `afterEach` 只设 title/description，焦点留在旧位置（通常是 body），读屏用户点链接后听不到任何新页面上下文。
 7. （P10 T1(d) 转办）toast 容器整体是 `role="status" aria-live="polite"`，而每条 toast 内含可交互的「关闭提示」按钮——实时区内嵌交互控件是公认反模式：读屏会在轮询实时区时把按钮一并播报，且用户无法可靠地把焦点停在该控件上。
 ## §2 决策表
 | # | 决策点 | 定案 | 理由 / 放弃的替代 |
 |---|---|---|---|
 | D-A | `success` 色令牌加深 | `--color-success: #1f7a4d`（`text-paper` 在其上 **4.76**、白 **5.32**；作文字色对 paper 4.76 / 对 surface 5.32） | 唯一消费者是成功 toast 底色，改令牌即全站生效且不留分叉。放弃「只改 toast 用别的绿」——会让令牌与实际用色脱节，下一个消费者重踩。放弃 #186039（6.79）：过暗，脱离新粗野主义的高饱和海报感。 |
 | D-B | 错误 toast 底色 | `error: 'bg-accent-ink text-paper'`（**4.87**） | `accent-ink` 已是既有令牌且已被 AdminUsersView 用作 `bg-accent-ink text-paper` 底色，复用即一致，不新增色。放弃新增 `--color-error` 令牌：与 `accent-ink` 同值同义，纯冗余。放弃给错误 toast 加白字：`text-paper` 本就是纸白，无需动。 |
 | D-C | 对比度守卫测试 | 新增 `app/lib/contrast.test.ts`：解析 `main.css` 的 `@theme` 令牌，按 WCAG 2.1 相对亮度算比值，钉死关键配色对 ≥4.5（焦点环 ≥3） | 仿既有 `app/lib/no-gradient.test.ts` 的源码级守卫范式，让「不许再引入低对比配色」成为可执行约束而非口头纪律。放弃逐组件视觉回归：成本高且测不到令牌层。 |
 | D-D | skip-link | `App.vue` 根 div 首子元素插 `<a href="#main" class="skip-link …">跳到主内容</a>`；`<main id="main" tabindex="-1">`；样式走 Tailwind `sr-only` + `focus:not-sr-only` 组合，**不新增 CSS 规则** | 原生锚点跳转会同时移动焦点（href 指向带 tabindex=-1 的 main），无需 JS。`focus:z-[80]` 压过 toast 的 `z-[70]`。放弃自绘 `.skip-link` CSS：工具类已足够，少一处需维护的样式。 |
 | D-E | 路由后焦点管理 | `attachTitleHook` 的 `afterEach` 改为 `(to, from)`，当 `to.path !== from.path` 时对 `#main` 调 `focus({ preventScroll: true })`；`#main` 不存在时静默 no-op | 只在**路径**变化时移焦：`/games → /games?tag=数字`（P10 T3 的标签点击）属同页筛选，抢焦点会打断用户；路径变化才是真正的「换页」。`preventScroll` 因为 `scrollBehavior` 已负责滚动，双重滚动会抖。放弃聚焦各页 h1：17 个视图有 2 个含双 h1（GameView / OutboundView 的 notFound 分支），聚焦目标不唯一，且 h1 加 tabindex 会污染 Tab 序。 |
 | D-F | 表格列头语义 | 三个管理视图全部 `<th>` 加 `scope="col"`；两个空的操作列表头改为 `<th scope="col" class="px-3 py-2"><span class="sr-only">操作</span></th>` | `scope="col"` 是最小且正确的修复。**不**改 `<td>` → `<th scope="row">`：那要把每行首格的排版结构（含 `<span>` 嵌套、font-bold 混排）重写成表头单元格，视觉回归风险大而收益有限（列头关联已解决读屏的主要痛点）。空表头补 sr-only 文本，否则操作列在读屏里是「无名第 5 列」。 |
 | D-G | 表格守卫测试 | 新增 `app/lib/tableScope.test.ts`：扫描 `app/**/*.vue`，断言每个 `<th` 都带 `scope=` | 与 D-C 同为源码级守卫，覆盖现有 5 张表与将来新增的表，比逐视图单测便宜且不随表格增删失效。放弃只测两个有单测的视图：AdminView 无测试文件，逐视图补测是 3 份重复劳动。 |
 | D-H | 五星评分可访问名 | 分组 `<span role="group" :aria-label="rated ? \`评分：${score} 星\` : '评分'">`；每颗星 `:aria-label="\`评 ${i} 星\`"`，内层字形 `<span aria-hidden="true">` | `aria-label` 覆盖字形成为可访问名，读屏念「评 3 星」而非「星」。分组标签携带当前值（已评几分），补齐「点了会怎样/现在是什么」。**不**用 `radiogroup`/`radio` + `aria-checked`：本控件支持「点当前分 = 撤评」，radio 无法表达取消选中；也**不**用逐星 `aria-pressed`——点亮是 `i <= litStars` 的连续区间，逐星 pressed 会把「4 分」播报成「1、2、3、4 星都按下」，语义反而更糊。 |
 | D-I | toast 实时区重构（收口 P10 T1(d)） | 容器去掉 `role`/`aria-live`，只留定位职责；每条 toast 内文本改为 `<p role="status" aria-live="polite" class="min-w-0 flex-1">{{ t.text }}</p>`，关闭按钮成为该 `<p>` 的**兄弟节点**（不再是实时区后代） | 实时区只包文本 → 读屏播报纯消息，不再夹带控件；按钮仍在 toast 内可正常 Tab 到。放弃「容器保留 role、按钮 aria-hidden」：那样按钮对读屏消失，鼠标用户能关、读屏用户关不掉，更糟。放弃把 toast 整体移出实时区：新消息就完全不被播报了，违背 toast 的存在意义。 |
 | D-J | e2e 覆盖 | 新增 `e2e/a11y.spec.ts` 三条：① Tab 首站是 skip-link、回车后焦点落 `#main`；② `/admin/users` 的 columnheader 可访问名齐备（含「操作」）；③ 作品页 star 按钮可访问名为「评 N 星」 | skip-link 是纯键盘时序行为，happy-dom 单测测不出真实 Tab 序；管理页需登录态（`helpers.seedSession(page,'admin')`）。既有 e2e 文件一字不动，只新增。 |
 | D-K | 移动端页头 | **本批不做**（实测无溢出，见 §1） | 没有问题就不修。引入汉堡菜单会新增焦点圈闭、Esc、aria-expanded 三处需维护的状态机，纯负收益。 |
 ## §3 设计细节（实现须逐字采用）
 ### 3.1 D-A / D-B / D-C：色彩对比
 `app/styles/main.css` 的 `@theme` 块内，唯一改动：
 ```css
  --color-success: #1f7a4d;
 ```
 `app/components/ToastHost.vue` 的 `KIND_CLASS`，唯一改动（`error` 行）：
 ```ts
 const KIND_CLASS: Record<ToastKind, string> = {
  success: 'bg-success text-paper',
  error: 'bg-accent-ink text-paper',
  info: 'bg-highlight text-ink'
 }
 ```
 新增 `app/lib/contrast.test.ts`：从 `main.css` 正则提取 `--color-<name>: #rrggbb`，实现 WCAG 相对亮度与对比度，断言下列配对（`fg on bg`）：
 - ≥ 4.5：`paper on success`、`paper on accent-ink`、`ink on highlight`、`ink on accent`、`ink-soft on paper`、`ink-faint on paper`、`ink-soft on surface`、`ink-faint on surface`、`paper on ink`、`accent-ink on paper`
 - ≥ 3：`accent on paper`（焦点环，1.4.11 非文本）
 亮度公式（逐字，别自创）：
 ```ts
 function channel(c: number): number {
  const s = c / 255
  return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
 }
 function luminance(hex: string): number {
  const h = hex.replace('#', '')
  const [r, g, b] = [0, 2, 4].map((i) => channel(parseInt(h.slice(i, i + 2), 16)))
  return 0.2126 * r + 0.7152 * g + 0.0722 * b
 }
 export function contrast(a: string, b: string): number {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x)
  return (hi + 0.05) / (lo + 0.05)
 }
 ```
 ### 3.2 D-D / D-E：skip-link 与路由后焦点
 `app/App.vue` 模板（`<AppHeader />` 之前插 skip-link，`<main>` 加 `id` 与 `tabindex`）：
 ```html
 <template>
  <div class="flex min-h-screen flex-col">
    <a
      href="#main"
      class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[80] focus:border-2 focus:border-ink focus:bg-highlight focus:px-3 focus:py-2 focus:text-sm focus:font-extrabold focus:shadow-hard"
    >跳到主内容</a>
    <AppHeader />
    <main id="main" tabindex="-1" class="mx-auto flex w-full max-w-6xl flex-1 flex-col px-4 py-6">
      <RouterView />
    </main>
    <AppFooter />
    <ToastHost />
  </div>
 </template>
 ```
 `app/router/index.ts`：新增导出函数 + 改 `attachTitleHook` 签名内的回调：
 ```ts
 // SPA 导航后把焦点交给主内容区：读屏用户据此获得新页面上下文（D-E）。
 // 仅路径变化时移动——同路径改 query（如目录 /games?tag=x 筛选）不打断用户焦点。
 // preventScroll：滚动由 router.scrollBehavior 负责，避免双重滚动抖动。
 export function focusMain(): void {
  document.getElementById('main')?.focus({ preventScroll: true })
 }
 export function attachTitleHook(r: Router): void {
  r.afterEach((to, from) => {
    setPageTitle(joinTitle(sectionTitleOf(to.name)))
    setPageDescription('')
    if (to.path !== from.path) focusMain()
  })
 }
 ```
 注意：`to.path !== from.path` 在首次导航时 `from` 是 `START_LOCATION`（path `/`），从 `/` 进 `/` 不会误触；从 `/` 进 `/games` 会正确触发。`#main` 尚未挂载（router 早于 app mount 就绪的边界）时 `getElementById` 返回 null，可选链静默 no-op。
 ### 3.3 D-F / D-G：表格列头
 三个文件的每个 `<th>` 加 `scope="col"`，类名与文本一字不动。两处空表头（`AdminView.vue:152` 队列表的 `<th class="px-3 py-2" />`、`AdminUsersView.vue:123` 的 `<th class="px-3 py-2" />`）改为：
 ```html
 <th scope="col" class="px-3 py-2"><span class="sr-only">操作</span></th>
 ```
 新增 `app/lib/tableScope.test.ts`：递归扫 `app/**/*.vue`（排除 `*.test.ts`），对每行匹配 `<th\b`，断言该 `<th` 起始标签内含 `scope=`。多行书写的 `<th` 需读到闭合 `>` 为止再判定（AdminUsersView 的空表头是单行，但守卫要对将来健壮）。违规时报告 `相对路径:行号: 行内容`，断言 `toEqual([])`——与 `no-gradient.test.ts` 同风格。
 ### 3.4 D-H：五星评分
 `app/components/GameReactions.vue` 的星标分组：
 ```html
    <span
      class="inline-flex items-center"
      role="group"
      :aria-label="rated ? `评分：${score} 星` : '评分'"
    >
      <button
        v-for="i in 5"
        :key="i"
        type="button"
        :data-testid="`star-${i}`"
        :aria-label="`评 ${i} 星`"
        :disabled="busy"
        class="px-0.5 font-mono text-base leading-none disabled:opacity-60"
        @click="pickStar(i)"
      ><span aria-hidden="true" :class="i <= litStars ? 'text-accent-ink' : 'text-ink-soft'">{{ i <= litStars ? '★' : '☆' }}</span></button>
    </span>
 ```
 `data-testid`、`disabled`、类名、点击语义（点当前分撤评）全部不动；既有测试对 `.text()` 的断言不受影响（`aria-label` 不改文本内容）。
 ### 3.5 D-I：toast 实时区
 `app/components/ToastHost.vue` 模板：
 ```html
 <template>
  <!-- 不 Teleport：容器常驻，屏幕阅读器语义稳定。
       容器只负责定位——role/aria-live 落在每条 toast 的文本上，
       使可交互的关闭按钮成为实时区的兄弟而非后代（P10 T1(d) 收口）。 -->
  <div
    data-testid="toast-host"
    class="pointer-events-none fixed bottom-4 right-4 z-[70] flex w-72 flex-col gap-2"
  >
    <TransitionGroup name="toast">
      <div
        v-for="t in toasts"
        :key="t.id"
        data-testid="toast"
        :class="[
          'pointer-events-auto flex items-start justify-between gap-2 border-2 border-ink px-3 py-2 text-xs font-bold shadow-hard',
          KIND_CLASS[t.kind]
        ]"
      >
        <p role="status" aria-live="polite" class="min-w-0 flex-1">{{ t.text }}</p>
        <button
          type="button"
          aria-label="关闭提示"
          class="-mr-1 shrink-0 cursor-pointer"
          @click="dismiss(t.id)"
        >
          <PhX :size="12" weight="bold" aria-hidden="true" />
        </button>
      </div>
    </TransitionGroup>
  </div>
 </template>
 ```
 `useToast.ts` 一字不动（store 语义与本批无关）。
 ### 3.6 D-J：e2e
 新增 `src/e2e/a11y.spec.ts`，三条用例，既有 e2e 文件与 `helpers.ts` 一字不动：
 ```ts
 import { expect, test } from '@playwright/test'
 import { seedSession } from './helpers'
 test('skip-link：Tab 首站可见，回车后焦点落在主内容区', async ({ page }) => {
  await page.goto('http://localhost:4173/')
  await page.keyboard.press('Tab')
  const skip = page.getByRole('link', { name: '跳到主内容' })
  await expect(skip).toBeVisible()
  await expect(skip).toBeFocused()
  await page.keyboard.press('Enter')
  await expect(page.locator('main#main')).toBeFocused()
 })
 test('管理端表格列头具备可访问名（含 sr-only 的操作列）', async ({ page }) => {
  await seedSession(page, 'admin')
  await page.goto('http://localhost:4173/admin/users')
  const headers = page.getByRole('columnheader')
  await expect(headers).toHaveCount(6)
  await expect(headers.nth(0)).toHaveAccessibleName('用户名')
  await expect(headers.nth(5)).toHaveAccessibleName('操作')
 })
 test('评分按钮的可访问名是「评 N 星」而非字形', async ({ page }) => {
  await seedSession(page, 'user')
  await page.goto('http://localhost:4173/games/fixture/2048')
  await expect(page.getByTestId('star-3')).toHaveAccessibleName('评 3 星')
  await expect(page.locator('[role=group][aria-label^="评分"]')).toHaveCount(1)
 })
 ```
 ## §4 边界与不做的事
 - 禁触：`e2e/landing.spec.ts`、`e2e/noauth.spec.ts`、`e2e/author-page.noauth.spec.ts`、`e2e/merge-repo.spec.ts`、`e2e/ux.spec.ts`、`e2e/submit-flow.spec.ts`、`e2e/helpers.ts`、`playwright.config.ts`、`vitest.config.ts`、`vite.config*.ts`、`scripts/`、`package.json`。
 - `runtime/` 本批**完全不动**（含 GameHost）——播放区可访问性（iframe title、全屏按钮语义）已在既有代码达标。
 - 不新增依赖、不改 `version`（恒 0.1.0）、不动 CHANGELOG（控制者统一写）。
 - 不改任何视觉设计：平面海报新粗野主义（无渐变/无圆角/硬阴影）必须保持，`no-gradient.test.ts` 守卫须继续绿。除 D-A/D-B 两处配色外，不动任何既有颜色与排版。
 - 不做移动端汉堡菜单（D-K，实测无溢出）。
 - 不做 `<td>` → `<th scope="row">` 的行头重构（D-F 理由）。
 - 不做暗色模式（C 包，另行立项）。
 ## §5 测试计划
 vitest（新增/扩展）：
 - 新 `app/lib/contrast.test.ts`：令牌解析成功（能取到 paper/ink/success/accent-ink/highlight/accent/ink-soft/ink-faint/surface）；§3.1 列出的 ≥4.5 配对逐条断言；焦点环 `accent on paper` ≥3。
 - 新 `app/lib/tableScope.test.ts`：守卫断言 `violations === []`（即全仓每个 `<th` 都带 scope）。
 - 扩 `app/components/ToastHost.test.ts`：① 容器**不再**有 `role`/`aria-live`（改为断言属性不存在）；② 每条 toast 的 `p[role=status][aria-live=polite]` 存在且文本正确；③ 关闭按钮是该 `<p>` 的兄弟（`button.parentElement === p.parentElement`，且 `p.contains(button) === false`）；④ kind 配色断言中 `error` 由 `bg-accent` 改 `bg-accent-ink`；⑤ 既有的「点关闭 → store 少一条」保留。
 - 扩 `app/router/index.test.ts`：新 describe「SPA 导航后焦点（D-E）」——先在 `document.body` 注入 `<main id="main" tabindex="-1">`，push `/` → `/games` 后断言 `document.activeElement.id === 'main'`；`/games` → `/games?tag=x` 后断言焦点**未**被 main 抢走（先 blur 或先聚焦别的元素再验）；`#main` 不存在时 push 不抛错。
 - 扩 `app/components/GameReactions.test.ts`：star-1..5 的 `aria-label` 为「评 N 星」；分组 `role=group` 且未评时 `aria-label === '评分'`、已评（`rated: true, score: 4`）时为「评分：4 星」；内层字形 `aria-hidden="true"`；既有 `.text()` 为 ★/☆ 的断言全部保留且仍绿。
 e2e：
 - 新 `e2e/a11y.spec.ts` 三条（§3.6 逐字）。
 - 既有全部 e2e 文件一字不动，且必须继续全绿（`landing.spec.ts` 的 `getByRole('heading', { level: 1 })`、`locator('main')`、`ux.spec.ts` 的 `locator('main').click({position:{x:5,y:5}})` 与 toast 断言均须不受影响——skip-link 在 main 之外、toast 的 `data-testid` 与文本内容不变）。
 验收腿：vitest 全绿（基线 601 + 新增）、`vue-tsc` 零错、`npm run build` OK、主 e2e（基线 77+1skip + 新增 3）、noauth 4。
 ## §6 CHANGELOG 口径（控制者写）
 版本 `0.24.0`。Added：skip-link、路由后焦点管理、表格列头语义、评分可访问名、对比度/表格守卫测试、a11y e2e。Changed：success 令牌加深、错误 toast 底色换 accent-ink、toast 实时区重构（交互控件移出）。Tests：数字以实跑为准。中英双语，同条目英中相邻行、条目间空行。