企业官网建设流程全解析

ECC 无障碍技能实战指南：基于 WCAG 2.2 Level AA 的跨平台（Web / iOS / Android）可访问性设计与审计

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本篇技术指南以 ECC 仓库中的 accessibility 技能 为主体，系统讲解如何运用 WCAG 2.2 Level AA 标准设计与审计可访问的数字产品。你将掌握 POUR 原则、ARIA 语义映射、跨平台无障碍属性对照（HTML/ARIA、SwiftUI、Jetpack Compose）、关键成功准则（SC 2.5.8 目标尺寸、SC 2.4.11 焦点外观、SC 3.3.7 冗余输入）的落地写法，并学会规避 Div 按钮、仅靠颜色传达信息等常见反模式。

1. 技能概述：它是做什么的

accessibility技能是 ECC（The agent harness performance optimization system）为 Agent 提供的一套"无障碍架构方法论"。它确保数字界面对于使用屏幕阅读器、开关控制（switch control）或键盘导航的用户而言，满足POUR四原则：可感知（Perceivable）、可操作（Operable）、可理解（Understandable）、健壮（Robust）。该技能聚焦于 WCAG 2.2 达成标准的技术实现，而非宏观设计规范。

在 ECC 的技能体系中，该技能与 frontend-a11y（React/Next.js 层面的无障碍实践）、frontend-patterns（通用前端组件模式）相互配合：前者负责"设计并生成无障碍代码"，后者负责在具体组件中执行。同时，react-patterns 中的"Accessibility-First Composition"章节明确要求：优先渲染语义 HTML、保证每个交互元素可通过键盘访问、表单输入必须有标签，并交叉引用本技能以覆盖 WCAG 标准与模式库。

使用时机（When to Use）

• 为Web、iOS、Android定义 UI 组件规格；
• 审计现有代码中的无障碍障碍或合规差距；
• 实现 WCAG 2.2 新增标准，如目标尺寸（最小）（Target Size (Minimum)）和焦点外观（Focus Appearance）；
• 将高层级设计需求映射为技术属性（ARIA 角色、trait、hint）。

2. 核心概念：无障碍实现的五大基石

1. POUR 原则：WCAG 的根基，即内容必须可感知、可操作、可理解、健壮。
2. 语义映射（Semantic Mapping）：优先使用原生元素而非通用容器，以利用浏览器/系统内置的无障碍支持。
3. 无障碍树（Accessibility Tree）：辅助技术真正"读取"的 UI 表示形态。
4. 焦点管理（Focus Management）：控制键盘/屏幕阅读器光标的顺序与可见性。
5. 标签与提示（Labeling & Hints）：通过aria-label、accessibilityLabel、contentDescription提供上下文信息。

3. 实现方法论：五步工作流

该技能把无障碍实现拆解为五个可执行的步骤，这也是a11y-architectAgent 在 工作流 中遵循的核心路径。

步骤 1：识别组件角色

确定功能目的（这是按钮、链接还是标签页？）。在依赖自定义角色之前，优先使用可用的、最具语义的原生元素。例如"点击提交"应该用<button>，而不是用带onClick的<div>。

步骤 2：定义可感知属性

• 文本对比度满足4.5:1（正常文本）或3:1（大号文本/UI 组件）；
• 为非文本内容（图片、图标）添加文本替代；
• 实现响应式回流（reflow），在400%缩放下不丢失功能。

步骤 3：实现可操作的控件

• 最小24x24 CSS 像素目标尺寸（WCAG 2.2 SC 2.5.8）；
• 所有交互元素可通过键盘到达，并具有可见的焦点指示器（SC 2.4.11）；
• 为拖拽操作提供单指针替代方案。

步骤 4：确保可理解的逻辑

• 使用一致的导航模式；
• 提供描述性错误消息和修正建议（SC 3.3.3）；
• 实现"冗余输入（Redundant Entry）"（SC 3.3.7），避免在同一流程中重复询问相同数据。

步骤 5：验证健壮的兼容性

• 使用正确的Name, Role, Value模式；
• 为动态状态更新实现aria-live或 live region。

4. 无障碍架构：从 UI 组件到辅助技术

技能内置了一张 mermaid 架构图（原文），展示了同一 UI 组件在不同平台上的无障碍投射路径：

这条链路的本质是：无障碍树（Accessibility Tree）是辅助技术唯一的信息来源。无论平台如何，开发者要做的都是把 UI 的"名称、角色、值、状态"正确地投射到平台各自的无障碍 API 上——Web 靠 WAI-ARIA，iOS 靠 SwiftUI 的 traits 与 labels，Android 靠 Jetpack Compose 的 semantics。

5. 跨平台属性映射表

下表是技能提供的核心速查表（原文），覆盖最常见的四类无障碍需求。它是把设计需求翻译成具体代码属性时的"翻译字典"：

映射要点解读

• **主标签（Primary Label）**解决"这是什么"：Web 端尽量使用可见的<label>关联表单控件；仅当没有可见文本时才用aria-label。iOS/Android 端则分别对应accessibilityLabel与contentDescription。
• **辅助提示（Secondary Hint）**解决"怎么用"：用于补充说明操作后果，例如删除按钮的"将永久移除该项"。这与 frontend-a11y 中aria-describedby的用法一致。
• **操作角色（Action Role）**解决"能做什么"：显式声明交互语义，让屏幕阅读器正确播报。
• **实时更新（Live Updates）**解决"发生了什么"：动态内容（如异步加载状态、校验错误）需要 live region 主动播报，而不是等用户重新聚焦才发现。

6. 三平台代码示例

Web：可访问的搜索表单

<form role="search"> <label for="search-input" class="sr-only">Search products</label> <input type="search" id="search-input" placeholder="Search..." /> <button type="submit" aria-label="Submit Search"> <svg aria-hidden="true">...</svg> </button> </form>

要点：视觉上隐藏（sr-only）但仍对屏幕阅读器可见的<label>建立了输入框的可访问名称；图标按钮通过aria-label获得文本标识；装饰性 SVG 通过aria-hidden="true"从无障碍树中移除。该写法与a11y-architect中的可访问搜索组件示例完全一致。

iOS：可访问的操作按钮

Button(action: deleteItem) { Image(systemName: "trash") } .accessibilityLabel("Delete item") .accessibilityHint("Permanently removes this item from your list") .accessibilityAddTraits(.isButton)

要点：图标按钮必须有accessibilityLabel（否则对屏幕阅读器不可见）；accessibilityHint描述操作后果；accessibilityAddTraits(.isButton)显式声明按钮角色。

Android：可访问的开关

Switch( checked = isEnabled, onCheckedChange = { onToggle() }, modifier = Modifier.semantics { contentDescription = "Enable notifications" } )

要点：Compose 通过Modifier.semantics块声明语义属性，contentDescription提供可访问名称。注意，Compose 的原生控件（如Switch）自带角色与状态语义，这里补充的是描述性文本。

7. 必须规避的反模式（Anti-Patterns）

技能明确列出了四类最常见的错误（原文）：

a11y-architect还补充了更多反模式（原文）："Click Here" 链接（无描述性，屏幕阅读器按链接导航时不知道目的地）、固定尺寸容器（高缩放级别下阻止回流、破坏布局）、键盘陷阱（用户进入组件后无法继续导航页面其余部分）、自动播放媒体（干扰屏幕阅读器音频、分散认知障碍用户注意力）、空按钮（无aria-label/accessibilityLabel的纯图标按钮对屏幕阅读器不可见）。

8. 最佳实践检查清单

技能提供了一份可直接执行的验收清单（原文），建议在提交代码审查前逐项核对：

• 交互元素满足24x24px（Web）或44x44pt（原生）目标尺寸；
• 焦点指示器清晰可见且高对比度；
• 模态框打开期间封禁焦点，关闭时干净释放（Escape键或关闭按钮）；
• 下拉与菜单关闭时将焦点归还给触发元素；
• 表单提供基于文本的错误建议；
• 纯图标按钮都有描述性文本标签；
• 文本缩放时内容正确回流。

9. 与 ECC 仓库其他模块的协同

9.1 Agent 层：a11y-architect

仓库中的 a11y-architect 是专门执行本技能的 Agent，它通过三步工作流落地方法论：

1. 上下文发现（Contextual Discovery）：判断目标是 Web / iOS / Android，分析交互复杂度（简单按钮 vs 复杂数据表格），识别无障碍"阻塞点"（如仅颜色指示、模态框缺少焦点封禁）；
2. 策略实现（Strategic Implementation）：调用 accessibility 技能生成语义代码，定义焦点流，优化触控/指针目标尺寸（最小24x24px间距或44x44px目标尺寸）；
3. 验证与文档（Validation & Documentation）：对照 WCAG 2.2 Level AA 清单复查，并输出"实现说明"解释aria-live、accessibilityHint等属性为什么要这样用。

其输出格式固定为三件套：代码（语义 HTML/ARIA 或原生代码）、无障碍树（屏幕阅读器会播报什么）、合规映射（覆盖了哪些 WCAG 2.2 准则）。对于重大 UI 决策，它还提供了ADR 模板（Accessibility Decision Record，原文），要求记录平台、对应 WCAG 成功准则、问题描述与具体实现选择——例如"移动端所有导航元素触摸目标至少 44x44 点、Web 端 24x24 CSS 像素，相邻目标之间保证至少 4px 间距"。

9.2 规则层与前端技能

• react-patterns 的"Accessibility-First Composition"要求：先渲染语义 HTML（<button>、<a>、<nav>、<main>）再考虑role；每个交互元素可键盘访问；表单输入需要标签（<label htmlFor>或图标场景用aria-label）；路由切换与模态框开合时要管理焦点；在组件测试中运行axe。
• frontend-a11y 提供了 React/Next.js 的具体落地模式：htmlFor/id标签关联、aria-describedby连接错误消息、aria-invalid标记校验状态、自定义下拉的combobox键盘交互（ArrowUp/ArrowDown/Enter/Escape）、模态框焦点恢复（previousFocusRef）、prefers-reduced-motion尊重系统减弱动画设置等——这些正是本技能在 React 生态中的实现细节。
• 规则目录 rules/web 与 rules/common 中的 coding-style、patterns、testing 等规则，为无障碍代码提供了工程化约束的配套上下文。

10. 参考资源

技能原文末尾列出的权威资料（原文）可作为深度学习的入口：WCAG 2.2 指南（W3C TR/WCAG22）、WAI-ARIA 创作实践、iOS 无障碍编程指南、iOS 人机界面指南-无障碍、Android 无障碍开发者指南。它们分别对应本文第 5 节映射表中的三列技术栈。

11. 相关技能

在 ECC 中，与无障碍技能协同工作的还有：frontend-patterns（通用前端模式）、design-system（设计系统一致性）、liquid-glass-design（液态玻璃设计规范）、swiftui-patterns（SwiftUI 模式）。需要完整的无障碍与前端主题技能清单时，可查阅 skills 目录 下的对应条目。

小结：本技能的价值在于把"包容性设计"转化为可执行、可审计、可映射的技术属性。无论是审计存量代码、实现 WCAG 2.2 新准则，还是跨 Web/原生三端输出组件规格，都可以按照"识别角色 → 定义可感知属性 → 实现可操作控件 → 确保可理解逻辑 → 验证健壮兼容"的五步法，配合跨平台映射表与检查清单完成交付。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC