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

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技能是 ECCThe agent harness performance optimization system为 Agent 提供的一套无障碍架构方法论。它确保数字界面对于使用屏幕阅读器、开关控制switch control或键盘导航的用户而言满足POUR四原则可感知Perceivable、可操作Operable、可理解Understandable、健壮Robust。该技能聚焦于 WCAG 2.2 达成标准的技术实现而非宏观设计规范。在 ECC 的技能体系中该技能与 frontend-a11yReact/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. 核心概念无障碍实现的五大基石POUR 原则WCAG 的根基即内容必须可感知、可操作、可理解、健壮。语义映射Semantic Mapping优先使用原生元素而非通用容器以利用浏览器/系统内置的无障碍支持。无障碍树Accessibility Tree辅助技术真正读取的 UI 表示形态。焦点管理Focus Management控制键盘/屏幕阅读器光标的顺序与可见性。标签与提示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 EntrySC 3.3.7避免在同一流程中重复询问相同数据。步骤 5验证健壮的兼容性使用正确的Name, Role, Value模式为动态状态更新实现aria-live或 live region。4. 无障碍架构从 UI 组件到辅助技术技能内置了一张 mermaid 架构图原文展示了同一 UI 组件在不同平台上的无障碍投射路径这条链路的本质是无障碍树Accessibility Tree是辅助技术唯一的信息来源。无论平台如何开发者要做的都是把 UI 的名称、角色、值、状态正确地投射到平台各自的无障碍 API 上——Web 靠 WAI-ARIAiOS 靠 SwiftUI 的 traits 与 labelsAndroid 靠 Jetpack Compose 的 semantics。5. 跨平台属性映射表下表是技能提供的核心速查表原文覆盖最常见的四类无障碍需求。它是把设计需求翻译成具体代码属性时的翻译字典功能Web (HTML/ARIA)iOS (SwiftUI)Android (Compose)主标签aria-label/label.accessibilityLabel()contentDescription辅助提示aria-describedby.accessibilityHint()Modifier.semantics { stateDescription ... }操作角色rolebutton.accessibilityAddTraits(.isButton)Modifier.semantics { role Role.Button }实时更新aria-livepolite.accessibilityLiveRegion(.polite)Modifier.semantics { liveRegion LiveRegionMode.Polite }映射要点解读**主标签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 rolesearch label forsearch-input classsr-onlySearch products/label input typesearch idsearch-input placeholderSearch... / button typesubmit aria-labelSubmit Search svg aria-hiddentrue.../svg /button /form要点视觉上隐藏sr-only但仍对屏幕阅读器可见的label建立了输入框的可访问名称图标按钮通过aria-label获得文本标识装饰性 SVG 通过aria-hiddentrue从无障碍树中移除。该写法与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技能明确列出了四类最常见的错误原文反模式问题本质Div 按钮用div/span承载点击事件却不加role与键盘支持屏幕阅读器与键盘用户都无法操作仅用颜色传达信息只用颜色变化如边框变红表示错误色盲用户无法感知必须附加文本/图标模态框焦点未封禁模态框打开时不封禁trap焦点键盘用户会导航到背景内容焦点必须被封禁且可通过Escape键或显式关闭按钮逃出WCAG SC 2.1.2冗余替代文本alt 文本写 Image of... / Picture of...屏幕阅读器本身就会播报图片角色造成重复播报a11y-architect还补充了更多反模式原文Click Here 链接无描述性屏幕阅读器按链接导航时不知道目的地、固定尺寸容器高缩放级别下阻止回流、破坏布局、键盘陷阱用户进入组件后无法继续导航页面其余部分、自动播放媒体干扰屏幕阅读器音频、分散认知障碍用户注意力、空按钮无aria-label/accessibilityLabel的纯图标按钮对屏幕阅读器不可见。8. 最佳实践检查清单技能提供了一份可直接执行的验收清单原文建议在提交代码审查前逐项核对交互元素满足24x24pxWeb或44x44pt原生目标尺寸焦点指示器清晰可见且高对比度模态框打开期间封禁焦点关闭时干净释放Escape键或关闭按钮下拉与菜单关闭时将焦点归还给触发元素表单提供基于文本的错误建议纯图标按钮都有描述性文本标签文本缩放时内容正确回流。9. 与 ECC 仓库其他模块的协同9.1 Agent 层a11y-architect仓库中的 a11y-architect 是专门执行本技能的 Agent它通过三步工作流落地方法论上下文发现Contextual Discovery判断目标是 Web / iOS / Android分析交互复杂度简单按钮 vs 复杂数据表格识别无障碍阻塞点如仅颜色指示、模态框缺少焦点封禁策略实现Strategic Implementation调用 accessibility 技能生成语义代码定义焦点流优化触控/指针目标尺寸最小24x24px间距或44x44px目标尺寸验证与文档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要求先渲染语义 HTMLbutton、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-patternsSwiftUI 模式。需要完整的无障碍与前端主题技能清单时可查阅 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考