Back to Details

accessibility

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Accessibility (WCAG 2.2)

无障碍设计（WCAG 2.2）

This skill ensures that digital interfaces are Perceivable, Operable, Understandable, and Robust (POUR) for all users, including those using screen readers, switch controls, or keyboard navigation. It focuses on the technical implementation of WCAG 2.2 success criteria.
本技能确保数字界面对所有用户而言都是可感知、可操作、可理解且健壮的（POUR），包括使用屏幕阅读器、切换控制或键盘导航的用户。它聚焦于WCAG 2.2成功标准的技术实现。

When to Use

适用场景

  • Defining UI component specifications for Web, iOS, or Android.
  • Auditing existing code for accessibility barriers or compliance gaps.
  • Implementing new WCAG 2.2 standards like Target Size (Minimum) and Focus Appearance.
  • Mapping high-level design requirements to technical attributes (ARIA roles, traits, hints).
  • 为Web、iOS或Android平台定义UI组件规范。
  • 审核现有代码中的无障碍障碍或合规缺口。
  • 实现WCAG 2.2新增标准，如《目标尺寸（最小值）》和《焦点外观》。
  • 将高层设计需求映射为技术属性（ARIA角色、特性、提示文本）。

Core Concepts

核心概念

  • POUR Principles: The foundation of WCAG (Perceivable, Operable, Understandable, Robust).
  • Semantic Mapping: Using native elements over generic containers to provide built-in accessibility.
  • Accessibility Tree: The representation of the UI that assistive technologies actually "read."
  • Focus Management: Controlling the order and visibility of the keyboard/screen reader cursor.
  • Labeling & Hints: Providing context through 
    aria-label
    , 
    accessibilityLabel
    , and 
    contentDescription
    .
  • POUR原则：WCAG的核心基础（可感知、可操作、可理解、健壮）。
  • 语义化映射：优先使用原生元素而非通用容器，以提供内置的无障碍支持。
  • 无障碍树：辅助技术实际“读取”的UI表示形式。
  • 焦点管理：控制键盘/屏幕阅读器光标的顺序与可见性。
  • 标签与提示：提供上下文信息，如
    aria-label
    、
    accessibilityLabel
    和
    contentDescription
    。

How It Works

工作流程

Step 1: Identify the Component Role

步骤1：确定组件角色

Determine the functional purpose (e.g., Is this a button, a link, or a tab?). Use the most semantic native element available before resorting to custom roles.
明确组件的功能用途（例如：这是按钮、链接还是标签页？）。在使用自定义角色之前，优先选用语义化最强的原生元素。

Step 2: Define Perceivable Attributes

步骤2：定义可感知属性

  • Ensure text contrast meets 4.5:1 (normal) or 3:1 (large/UI).
  • Add text alternatives for non-text content (images, icons).
  • Implement responsive reflow (up to 400% zoom without loss of function).
  • 确保文本对比度符合4.5:1（常规文本）或3:1（大文本/UI元素）。
  • 为非文本内容（图片、图标）添加文本替代方案。
  • 实现响应式重排（缩放至400%仍不丢失功能）。

Step 3: Implement Operable Controls

步骤3：实现可操作控件

  • Ensure a minimum 24x24 CSS pixel target size (WCAG 2.2 SC 2.5.8).
  • Verify all interactive elements are reachable via keyboard and have a visible focus indicator (SC 2.4.11).
  • Provide single-pointer alternatives for dragging movements.
  • 确保交互元素的目标尺寸最小为24x24 CSS像素（WCAG 2.2 SC 2.5.8）。
  • 验证所有交互元素均可通过键盘访问，且具有可见的焦点指示器（SC 2.4.11）。
  • 为拖拽操作提供单指针替代方案。

Step 4: Ensure Understandable Logic

步骤4：确保逻辑可理解

  • Use consistent navigation patterns.
  • Provide descriptive error messages and suggestions for correction (SC 3.3.3).
  • Implement "Redundant Entry" (SC 3.3.7) to prevent asking for the same data twice.
  • 使用一致的导航模式。
  • 提供描述性错误消息及修正建议（SC 3.3.3）。
  • 实现“重复输入避免”（SC 3.3.7），防止重复请求相同数据。

Step 5: Verify Robust Compatibility

步骤5：验证健壮兼容性

  • Use correct 
    Name, Role, Value
    patterns.
  • Implement 
    aria-live
    or live regions for dynamic status updates.
  • 使用正确的“名称、角色、值”模式。
  • 为动态状态更新实现
    aria-live
    或实时区域。

Accessibility Architecture Diagram

无障碍架构图

mermaid
flowchart TD
  UI["UI Component"] --> Platform{Platform?}
  Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
  Platform -->|iOS| SwiftUI["Accessibility Traits + Labels"]
  Platform -->|Android| Compose["Semantics + ContentDesc"]

  ARIA --> AT["Assistive Technology (Screen Readers, Switches)"]
  SwiftUI --> AT
  Compose --> AT
mermaid
flowchart TD
  UI["UI Component"] --> Platform{Platform?}
  Platform -->|Web| ARIA["WAI-ARIA + HTML5"]
  Platform -->|iOS| SwiftUI["Accessibility Traits + Labels"]
  Platform -->|Android| Compose["Semantics + ContentDesc"]

  ARIA --> AT["Assistive Technology (Screen Readers, Switches)"]
  SwiftUI --> AT
  Compose --> AT

Cross-Platform Mapping

跨平台映射表

FeatureWeb (HTML/ARIA)iOS (SwiftUI)Android (Compose)
Primary Label
aria-label
/ 
<label>
.accessibilityLabel()
contentDescription
Secondary Hint
aria-describedby
.accessibilityHint()
Modifier.semantics { stateDescription = ... }
Action Role
role="button"
.accessibilityAddTraits(.isButton)
Modifier.semantics { role = Role.Button }
Live Updates
aria-live="polite"
.accessibilityLiveRegion(.polite)
Modifier.semantics { liveRegion = LiveRegionMode.Polite }
特性Web（HTML/ARIA）iOS（SwiftUI）Android（Compose）
主标签
aria-label
/ 
<label>
.accessibilityLabel()
contentDescription
辅助提示
aria-describedby
.accessibilityHint()
Modifier.semantics { stateDescription = ... }
操作角色
role="button"
.accessibilityAddTraits(.isButton)
Modifier.semantics { role = Role.Button }
实时更新
aria-live="polite"
.accessibilityLiveRegion(.polite)
Modifier.semantics { liveRegion = LiveRegionMode.Polite }

Examples

示例

Web: Accessible Search

Web：无障碍搜索框

html
<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>
html
<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>

iOS: Accessible Action Button

iOS：无障碍操作按钮

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

Android: Accessible Toggle

Android：无障碍开关

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

Anti-Patterns to Avoid

需避免的反模式

  • Div-Buttons: Using a 
    <div>
    or 
    <span>
    for a click event without adding a role and keyboard support.
  • Color-Only Meaning: Indicating an error or status only with a color change (e.g., turning a border red).
  • Uncontained Modal Focus: Modals that don't trap focus, allowing keyboard users to navigate background content while the modal is open. Focus must be contained and escapable via the 
    Escape
    key or an explicit close button (WCAG SC 2.1.2).
  • Redundant Alt Text: Using "Image of..." or "Picture of..." in alt text (screen readers already announce the role "Image").
  • Div按钮：使用
    <div>
    或
    <span>
    绑定点击事件，但未添加角色和键盘支持。
  • 仅用颜色传递信息：仅通过颜色变化（如将边框改为红色）来表示错误或状态。
  • 未受控的模态框焦点：模态框未捕获焦点，导致键盘用户在模态框打开时仍能导航至背景内容。焦点必须被限制在模态框内，且可通过
    Escape
    键或显式关闭按钮退出（WCAG SC 2.1.2）。
  • 冗余的替代文本：在替代文本中使用“图片...”或“照片...”（屏幕阅读器已会播报其“图片”角色）。

Best Practices Checklist

最佳实践检查清单

  • Interactive elements meet the 24x24px (Web) or 44x44pt (Native) target size.
  • Focus indicators are clearly visible and high-contrast.
  • Modals contain focus while open, and release it cleanly on close (
    Escape
    key or close button).
  • Dropdowns and menus restore focus to the trigger element on close.
  • Forms provide text-based error suggestions.
  • All icon-only buttons have a descriptive text label.
  • Content reflows properly when text is scaled.
  • 交互元素的目标尺寸符合**24x24像素（Web）或44x44点（原生平台）**要求。
  • 焦点指示器清晰可见且对比度达标。
  • 模态框在打开时捕获焦点，关闭时正确释放焦点（支持
    Escape
    键或关闭按钮）。
  • 下拉菜单和标签页在关闭时将焦点恢复至触发元素。
  • 表单提供文本形式的错误建议。
  • 所有纯图标按钮都配有描述性文本标签。
  • 文本缩放时内容可正常重排。

References

参考资料

Related Skills

相关技能

  • frontend-patterns
  • frontend-design
  • liquid-glass-design
  • swiftui-patterns
  • frontend-patterns
  • frontend-design
  • liquid-glass-design
  • swiftui-patterns