ARIA APG 组件模式契约

大理论

复杂 widget 的失败常常不是视觉不对，而是角色、焦点、键盘和状态暴露不一致。APG 提供的是模式语言：什么时候使用某个角色、有哪些必需状态、哪些键应该工作、DOM focus 或虚拟焦点如何移动、示例代码展示了哪些边界。agent 在实现前应把这些内容转成组件契约，而不是边写边试。

小知识点

1. 先判断是否能用原生 HTML 控件；原生 select、button、dialog、details 能满足时，不要强行 ARIA 化。
2. 复杂组件先选 APG pattern：combobox、dialog、tabs、treegrid、menu button、listbox、slider、accordion 等。
3. 为每个 pattern 摘出 roles、states、properties，例如 aria-expanded、aria-controls、aria-selected、aria-activedescendant。
4. 键盘表要变成测试断言：Enter、Escape、Arrow、Home/End、Tab、Shift+Tab 的进入、退出、循环和取消行为。
5. 焦点策略要明确：DOM focus 进入 popup，还是留在 input 并用 aria-activedescendant 表示活动项；不要混用。
6. APG 示例不是完整产品组件；本地仍要补 loading、empty、error、disabled、mobile、RTL、forced-colors 和表单提交边界。

设计判断

如果组件契约能回答“当前焦点在哪、读屏听到什么、哪个键改变哪个状态、状态如何映射到 DOM/ARIA、关闭后焦点回到哪里”，才可以进入视觉实现。答不出来时优先用 Radix、React Aria、Ariakit 或原生控件。

实现建议

生成组件前输出 apgPatternContract：patternName、sourceHref、nativeAlternative、roles、statesProps、keyboardInteractions、focusModel、selectionModel、labelling、liveRegion、escapeBehavior、formIntegration、mobileNotes、testAssertions。Playwright/Testing Library 测试覆盖键盘路径和 ARIA 状态，不只截图。

反例/风险

给 div 加 role=button 但不能 Space 触发；combobox 弹层打开后 DOM focus 和 aria-activedescendant 混乱；tabs 只能鼠标点击；dialog 关闭后焦点丢失；menu item 用链接视觉但没有菜单键盘模型；treegrid 只画层级没有行列语义。

案例分析

APG 首页说明它用于学习如何把 ARIA 语义应用到常见设计模式和 widgets，并提供设计模式、功能示例和基础实践。APG combobox 模式区分 listbox、grid、tree、dialog 等 popup 的键盘行为，并指出某些 popup 通过 aria-activedescendant 保持 DOM focus，dialog popup 则会把 DOM focus 移入 dialog。可学习点是：同一个“下拉建议框”的视觉，可以对应多种焦点模型；实现前必须先选模式。

来源链接

WAI-ARIA APG: https://www.w3.org/WAI/ARIA/apg/ APG Patterns: https://www.w3.org/WAI/ARIA/apg/patterns/ APG Combobox Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/ W3C aria-practices repository: https://github.com/w3c/aria-practices W3C Software and Document License: https://www.w3.org/copyright/software-license/