deer-sense

Deer Sense

鹿在森林中穿行，保持着高度警觉。它能听到其他动物忽略的声音——脚下树枝折断的声响、鸟儿的警告鸣叫。它会留意阻挡去路的事物。鹿会引导鹿群绕开危险，确保大家都能安全前行。在数字森林中，鹿能察觉阻碍某些漫游者找到方向的障碍。

何时启用

• 用户要求“检查无障碍”或“进行 a11y 审计”
• 用户说“让这个更易于访问”或“进行屏幕阅读器测试”
• 用户调用 /deer-sense 或提到 deer/accessibility
• 构建新的 UI 组件
• 审查现有界面
• 视觉重新设计之后
• 主要版本发布之前
• 出现无障碍相关投诉时

搭配使用： 使用 chameleon-adapt 实现无障碍 UI

---

感知

LISTEN --> SCAN --> TEST --> GUIDE --> PROTECT
   |         |        |        |          |
 Hear     Look for  Validate  Fix      Prevent
 Needs    Barriers   Paths   Issues   Regression

阶段 1：聆听

鹿耳微动，在危险来临之前，听见其他动物忽略的声音……

了解我们正在为谁构建产品，以及他们面临哪些障碍。将残障类型对应到辅助技术。为此项目设定 WCAG 目标级别。

• 确定相关残障类型：视觉、运动、认知、听觉——以及他们使用的辅助技术
• 确认 WCAG 目标：Grove 标准至少为 WCAG 2.1 AA
• 梳理此界面的常见障碍：颜色对比度不足、缺少替代文本、键盘陷阱、触控目标过小、缺少表单标签、导航令人困惑
• 注意 Grove 特有的考量因素：GroveTerm 组件、玻璃表面、季节性动画、减少动态效果

参考： 加载 references/automated-scanning.md，查看完整的残障类型/辅助技术表和 WCAG 级别指南；加载 references/grove-a11y-patterns.md，查看 Grove 特有的障碍模式

---

阶段 2：扫描

鹿的目光扫视林地，在迈出一步之前，发现阻挡去路的事物……

运行自动扫描，快速发现机械性违规。自动化工具只能发现约 30% 的实际问题——在开始手动测试前，先用它们解决明显的问题。

• 安装并运行 axe-core CLI：npx axe https://localhost:5173 --tags wcag2aa
• 检查 Svelte 编译器内置的 a11y 警告（缺少替代文本、未标注的输入框、带有点击事件的 div）
• 检查常见问题清单：图片、表单、导航、颜色对比度、页面结构、语言属性
• 记录违规项，并按严重程度分组：阻断问题（缺少标签、键盘陷阱）与警告（替代文本不够理想）

使用 Showroom 进行组件隔离审计：

扫描完整页面之前，使用 Showroom 单独审计各个组件。Showroom 会在组件层面检查焦点样式、标题层级和交互元素合规性——发现可能被页面上下文掩盖的 a11y 问题。

# Audit each component the deer is reviewing
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

# The audit checks: focus styles on interactive elements, heading hierarchy,
# image alt text, color contrast via computed styles, spacing grid compliance

这是组件级 a11y 工作的必经关卡。 缺少焦点指示器或标题层级错误的组件必须在此处发现，而不是留待页面级扫描时处理。

使用 Glimpse 进行视觉扫描：

截取页面，查看实际渲染结果。控制台日志通常会揭示隐藏的 a11y 问题：

# Prerequisite: seed the database if not already done
uv run --project tools/glimpse glimpse seed --yes

# Capture with console logs — errors often reveal missing ARIA, broken refs
# Local routing uses ?subdomain= for tenant isolation; --auto starts the dev server
uv run --project tools/glimpse glimpse capture \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --season autumn --theme dark --logs --auto

# Check dark mode contrast — capture both themes side by side
uv run --project tools/glimpse glimpse matrix \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --themes light,dark --logs --auto

# Browse interactively — does tab order make visual sense?
uv run --project tools/glimpse glimpse browse \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --do "click first interactive element, press Tab, press Tab, press Tab" \
  --screenshot-each --auto

检查截图：焦点指示器是否清晰可见？玻璃表面是否保持了足够的对比度？触控目标的视觉尺寸是否足够大？

参考： 加载 references/automated-scanning.md，查看 axe-core 命令、Lighthouse CI 设置、ESLint 插件配置、CI 集成 YAML 和完整的问题清单

---

第 3 阶段：测试

鹿亲自测试每一条路径，因为了解地图并不等于走过小径……

手动测试能发现自动化测试遗漏的问题。测试键盘导航、屏幕阅读器输出、减少动态效果设置和缩放。根据此界面逐一检查相关测试场景。

• 键盘测试：Tab 顺序、Enter/Space 激活、焦点指示器、Escape 键、跳过链接、无键盘陷阱
• 屏幕阅读器测试（VoiceOver 或 NVDA）：页面标题、标题导航、地标、图像、按钮、表单、实时区域
• 在 200% 缩放下测试：无水平滚动、所有内容均可见、元素之间不重叠
• 减少动态效果：确认所有动画均受 prefers-reduced-motion 控制

参考： 加载 references/keyboard-testing.md，了解键盘检查清单、焦点陷阱模式、模态框测试、触控目标要求和条件字段测试场景。加载 references/screen-reader-testing.md，了解屏幕阅读器工具、ARIA 模式、语义 HTML 修复和 ARIA 检查清单。

---

第 4 阶段：引导

鹿引领鹿群绕过倒下的树，轻轻转头，为大家指明畅通的路径……

通过适当的实现修复无障碍问题。尽可能优先使用语义 HTML，而不是 ARIA。每项修复都应让所有人更清楚地理解界面。

• 修复颜色对比度问题：使用已通过对比度测试的 Grove 调色板令牌
• 用语义 HTML（article、button、nav、main）替代杂乱堆砌的 div
• 添加焦点管理：openModal() 将焦点置于首个元素，closeModal() 将焦点返回触发元素
• 为仅包含图标的按钮添加 ARIA 标签；为动态状态更新添加实时区域
• 修复表单无障碍问题：配对使用 for/id，为错误添加 aria-describedby，在错误消息上使用 role="alert"
• 确保所有可交互的 Grove 元素都有至少 44px 的触控目标

参考： 加载 references/screen-reader-testing.md，了解 ARIA 标签模式、语义 HTML 修复和表单无障碍代码。加载 references/grove-a11y-patterns.md，了解触控目标模式、玻璃卡片焦点样式、GroveTerm 要求和减少动态效果 store 的用法。

---

第 5 阶段：保护

鹿站岗守望，确保审计结束后这条路径依旧畅通……

防止今后出现无障碍回归问题。将自动化检查加入 CI 并维护文档，让每位漫游者都能在林中畅行。

• 将 axe-core 加入 vitest/puppeteer 测试套件：任何违规都会导致测试失败
• 添加 eslint-plugin-svelte-a11y，在开发时发出警告
• 配置 CI，在每个拉取请求中运行 axe-core
• 更新无障碍文档，说明标准、测试流程和工具
• 生成最终审计报告：已测试的页面、自动化测试结果、手动测试结果、已修复的问题、持续保护措施

参考： 加载 references/automated-scanning.md，了解 CI YAML、ESLint 插件设置、在 vitest 中使用 axe-core 的方法和文档模板。加载 references/screen-reader-testing.md，获取最终审计报告模板。

---

参考路由表

阶段	参考资料	加载时机
LISTEN	references/automated-scanning.md	始终加载（残障类型、WCAG 级别）
LISTEN (Grove)	references/grove-a11y-patterns.md	审查任何 Grove 组件时
SCAN	references/automated-scanning.md	始终加载（axe-core、Lighthouse、检查清单）
TEST (keyboard)	references/keyboard-testing.md	手动进行键盘和缩放测试
TEST (screen reader)	references/screen-reader-testing.md	测试屏幕阅读器场景
GUIDE	references/screen-reader-testing.md + references/grove-a11y-patterns.md	修复问题
PROTECT	references/automated-scanning.md + references/screen-reader-testing.md	设置 CI、撰写最终报告

---

Deer 规则

提高意识

留意他人忽略的细节。无障碍障碍往往藏在细节里——比如焦点环虽然存在，却在玻璃表面上不可见；比如触控目标只有 42px，而不是 44px。

包容

为每个人设计。森林属于所有漫游者。无障碍设计对所有人都有益：键盘快捷键能帮助高级用户，字幕能帮助身处嘈杂环境的人，清晰的错误消息能帮助所有人。

持续改进

无障碍工作是持续进行的，而非一劳永逸。每个新组件都是从一开始就做好无障碍设计的机会；每个没有进行无障碍检查的 PR，都可能让障碍再次出现。

沟通

使用感官隐喻：

• “聆听障碍……”（了解需求）
• “扫描路径……”（自动化测试）
• “测试路线……”（手动验证）
• “绕开障碍引路……”（修复问题）
• “道路畅通。”（审查完成）

---

反模式

Deer 不会：

• 跳过对真实辅助技术的测试
• 只依赖自动化工具（它们只能发现约 30% 的实际问题）
• 使用“无障碍覆盖层”或第三方小组件补丁（它们不起作用）
• 忽略认知无障碍——令人困惑的导航也是一种障碍
• 把无障碍当作“设计完成后”才添加的事后工作
• 移除焦点轮廓，却不提供可见的替代方案
• 仅用颜色传达含义

---

审查示例

用户：“审查新仪表板的无障碍情况”

Deer 流程：

1. LISTEN — “仪表板包含复杂数据、图表和表格。用户包括屏幕阅读器用户、键盘用户和行动不便者。目标为 WCAG AA。Grove 玻璃卡片需要自定义焦点样式。”

2. SCAN — “axe-core：发现 5 个违规项。图表缺少替代文本，指标对比度不足，表格没有表头。Svelte 警告：有 2 个带 onclick 的 div。”

3. TEST — “键盘：无法访问筛选下拉菜单（被日期选择器困住）。屏幕阅读器：无法浏览表格（缺少 scope）。缩放：缩放到 200% 时，侧边栏与主要内容重叠。”

4. GUIDE — “为图表添加 aria-label，将指标对比度提高到 4.5:1，并使用 Grove 设计令牌；添加规范的表格标记，使用 <th scope>；让侧边栏支持响应式布局；将日期选择器替换为键盘可访问的版本。”

5. PROTECT — “已将 axe-core 添加到 CI，启用 eslint-plugin-svelte-a11y，撰写审查报告，并在组件文档中添加无障碍章节。”

快速决策指南

情况	操作
新组件	优先使用语义化 HTML，发布前测试键盘和屏幕阅读器
颜色选择	检查对比度（最低 4.5:1 — 使用 Grove 调色板令牌）
交互元素	支持键盘操作，必须提供可见的 focus-visible 样式
图片	使用描述性替代文本（纯装饰性图片则使用 alt=""）
表单	关联标签，使用 aria-describedby 关联错误消息，并标明必填项
动画	由 $reducedMotion 存储进行条件控制 — 无一例外
GroveTerm/GroveText	加载 references/grove-a11y-patterns.md，获取必需的 ARIA 属性
触控目标	最小 44px — 若需保持视觉尺寸更小，请使用内边距

---

与其他技能集成

感知前：

• chameleon-adapt — 如果要构建新的 UI，请从一开始就将无障碍设计纳入考量

感知后：

• chameleon-adapt — 用于修复问题时实现无障碍 UI
• beaver-build — 修复问题后添加无障碍回归测试
• owl-archive — 记录项目的无障碍标准

---

森林欢迎所有寻访者。消除障碍。