Back to Details

swift-accessibility

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Swift Accessibility

Swift无障碍支持

Scan, fix, and audit accessibility in Swift projects. Detects missing VoiceOver labels, Dynamic Type issues, WCAG violations, and generates XCTest audit code. Supports both SwiftUI and UIKit with auto-detection per file. Covers all 9 Apple Accessibility Nutrition Label categories.
扫描、修复并审计Swift项目中的无障碍问题。检测缺失的VoiceOver标签、Dynamic Type问题、WCAG违规情况，并生成XCTest审计代码。支持SwiftUI和UIKit，可按文件自动识别。覆盖苹果无障碍营养标签的全部9个类别。

When to Apply

适用场景

Reference these guidelines when:
  • Working on iOS/macOS projects that need accessibility support
  • Adding VoiceOver, Voice Control, or Switch Control support
  • Running an accessibility audit or a11y review
  • Fixing Dynamic Type, contrast, or WCAG compliance issues
  • Preparing for App Store Accessibility Nutrition Labels
在以下场景中参考本指南：
  • 开发需要无障碍支持的iOS/macOS项目
  • 添加VoiceOver、语音控制或切换控制支持
  • 进行无障碍审计或无障碍评审
  • 修复Dynamic Type、对比度或WCAG合规性问题
  • 准备App Store无障碍营养标签

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1Missing VoiceOver LabelsCRITICAL
p0-
2Missing Context and DiscoverabilityHIGH
p1-
3Visual, Interaction, and System Setting ComplianceMEDIUM
p2-
优先级类别影响程度前缀
1缺失VoiceOver标签严重（CRITICAL）
p0-
2缺失上下文与可发现性高（HIGH）
p1-
3视觉、交互与系统设置合规性中（MEDIUM）
p2-

Quick Reference

快速参考

1. Missing VoiceOver Labels (CRITICAL)

1. 缺失VoiceOver标签（严重）

  • p0-images-without-labels
    — Images without 
    .accessibilityLabel
    are invisible to VoiceOver
  • p0-icon-only-buttons
    — Buttons with only an image and no label
  • p0-images-without-labels
    — 未添加
    .accessibilityLabel
    的图片对VoiceOver不可见
  • p0-icon-only-buttons
    — 仅含图片无标签的按钮

2. Missing Context and Discoverability (HIGH)

2. 缺失上下文与可发现性（高）

  • p1-missing-hints
    — Interactive elements without 
    .accessibilityHint
  • p1-missing-identifiers
    — Testable elements without 
    .accessibilityIdentifier
  • p1-missing-input-labels
    — Missing 
    accessibilityInputLabels
    for Voice Control support
  • p1-small-touch-targets
    — Touch targets below 44x44pt minimum (HIG requirement)
  • p1-color-only-information
    — Color used as the only way to convey information
  • p1-missing-hints
    — 无
    .accessibilityHint
    的交互元素
  • p1-missing-identifiers
    — 无
    .accessibilityIdentifier
    的可测试元素
  • p1-missing-input-labels
    — 缺失
    accessibilityInputLabels
    以支持语音控制
  • p1-small-touch-targets
    — 触摸目标小于44x44pt最小值（HIG要求）
  • p1-color-only-information
    — 仅通过颜色传递信息

3. Visual, Interaction, and System Setting Compliance (MEDIUM)

3. 视觉、交互与系统设置合规性（中）

  • p2-hardcoded-fonts
    — Hardcoded font sizes that break Dynamic Type
  • p2-ungrouped-elements
    — Related elements not grouped for VoiceOver
  • p2-missing-header-traits
    — Section headers without 
    .isHeader
    trait
  • p2-decorative-elements-visible
    — Decorative elements not hidden from VoiceOver
  • p2-contrast-insufficient
    — Colors that fail WCAG AA contrast ratios
  • p2-reduce-motion-ignored
    — Animations that ignore the Reduce Motion setting
  • p2-bold-text-ignored
    — Custom fonts that don't respond to Bold Text setting
  • p2-custom-actions-missing
    — Gesture-only interactions without accessible alternatives
  • p2-dynamic-content-not-announced
    — Content changes not posted as accessibility notifications
  • p2-modal-focus-management
    — Custom modals without proper focus management or escape support
  • p2-hardcoded-fonts
    — 硬编码字体大小，破坏Dynamic Type功能
  • p2-ungrouped-elements
    — 相关元素未分组，VoiceOver无法正确识别
  • p2-missing-header-traits
    — 章节标题未设置
    .isHeader
    属性
  • p2-decorative-elements-visible
    — 装饰性元素未对VoiceOver隐藏
  • p2-contrast-insufficient
    — 颜色对比度未达到WCAG AA标准
  • p2-reduce-motion-ignored
    — 动画未遵循减少动态效果设置
  • p2-bold-text-ignored
    — 自定义字体未响应粗体文本设置
  • p2-custom-actions-missing
    — 仅支持手势的交互无无障碍替代方案
  • p2-dynamic-content-not-announced
    — 内容变化未发送无障碍通知
  • p2-modal-focus-management
    — 自定义模态框未正确管理焦点或提供退出方式

Apple Accessibility Nutrition Label Coverage

苹果无障碍营养标签覆盖情况

Nutrition LabelRules Covering It
VoiceOverp0-*, p1-missing-hints, p1-missing-identifiers, p2-ungrouped-elements, p2-missing-header-traits, p2-decorative-elements-visible, p2-custom-actions-missing, p2-dynamic-content-not-announced, p2-modal-focus-management
Voice Controlp1-missing-input-labels, p1-missing-hints, p2-custom-actions-missing
Larger Text (Dynamic Type)p2-hardcoded-fonts
Sufficient Contrastp2-contrast-insufficient
Dark Interfacep2-contrast-insufficient (checks both modes)
Differentiate Without Color Alonep1-color-only-information
Reduced Motionp2-reduce-motion-ignored
Bold Textp2-bold-text-ignored
Touch Target Sizep1-small-touch-targets
营养标签覆盖的规则
VoiceOverp0-*, p1-missing-hints, p1-missing-identifiers, p2-ungrouped-elements, p2-missing-header-traits, p2-decorative-elements-visible, p2-custom-actions-missing, p2-dynamic-content-not-announced, p2-modal-focus-management
语音控制p1-missing-input-labels, p1-missing-hints, p2-custom-actions-missing
更大字体（Dynamic Type）p2-hardcoded-fonts
足够对比度p2-contrast-insufficient
深色界面p2-contrast-insufficient（检查两种模式）
无需仅通过颜色区分p1-color-only-information
减少动态效果p2-reduce-motion-ignored
粗体文本p2-bold-text-ignored
触摸目标大小p1-small-touch-targets

Workflow

工作流程

Execute these 5 phases in order. Load rule files on-demand — only read a rule when its content is needed for the current phase.
按顺序执行以下5个阶段。按需加载规则文件——仅在当前阶段需要时读取规则内容。

Phase 1: Project Discovery

阶段1：项目发现

  1. Glob for 
    **/*.swift
    to find all Swift source files
  2. Classify each file as SwiftUI (
    import SwiftUI
    ), UIKit (
    import UIKit
    ), or mixed
  3. Grep for existing accessibility usage to understand current coverage:
    • SwiftUI: 
      .accessibilityLabel
      , 
      .accessibilityHint
      , 
      .accessibilityIdentifier
      , 
      .accessibilityHidden
      , 
      .accessibilityInputLabels
      , 
      accessibilityReduceMotion
    • UIKit: 
      isAccessibilityElement
      , 
      accessibilityLabel
      , 
      accessibilityIdentifier
      , 
      UIAccessibility.isReduceMotionEnabled
      , 
      adjustsFontForContentSizeCategory
  4. Report: total files, framework breakdown, current accessibility coverage percentage
  1. 通配匹配
    **/*.swift
    以找到所有Swift源文件
  2. 将每个文件分类为SwiftUI（包含
    import SwiftUI
    ）、UIKit（包含
    import UIKit
    ）或混合类型
  3. 搜索已有的无障碍代码使用情况，了解当前覆盖范围：
    • SwiftUI：
      .accessibilityLabel
      , 
      .accessibilityHint
      , 
      .accessibilityIdentifier
      , 
      .accessibilityHidden
      , 
      .accessibilityInputLabels
      , 
      accessibilityReduceMotion
    • UIKit：
      isAccessibilityElement
      , 
      accessibilityLabel
      , 
      accessibilityIdentifier
      , 
      UIAccessibility.isReduceMotionEnabled
      , 
      adjustsFontForContentSizeCategory
  4. 生成报告：文件总数、框架分布、当前无障碍覆盖百分比

Phase 2: Issue Detection

阶段2：问题检测

Scan files for anti-patterns. Read rules from 
rules/
directory for detection patterns.
For each issue found, record: file path, line number, priority, description, and suggested fix.
扫描文件查找反模式。从
rules/
目录读取规则以获取检测模式。
对于发现的每个问题，记录：文件路径、行号、优先级、描述及建议修复方案。

Phase 3: Automated Fixes

阶段3：自动修复

Apply fixes using Edit tool, following these rules:
  1. Never overwrite existing accessibility code — only add missing properties
  2. Add 
    [VERIFY]
    comment markers     on generated labels where semantic accuracy needs human review:
    swift
    .accessibilityLabel("Settings icon") // [VERIFY] confirm label matches intent
  3. Preserve formatting — match the indentation and style of surrounding code
  4. Group related fixes — apply all fixes to a single view/element together
Fix application order:
  1. P0 Critical fixes first
  2. P1 High fixes
  3. P2 Medium fixes (comprehensive mode only)
使用编辑工具应用修复，遵循以下规则：
  1. 切勿覆盖现有无障碍代码——仅添加缺失的属性
  2. 在生成的标签上添加
    [VERIFY]
    注释标记，提示需要人工审核语义准确性：
    swift
    .accessibilityLabel("Settings icon") // [VERIFY] confirm label matches intent
  3. 保留格式——匹配周围代码的缩进和风格
  4. 分组相关修复——对单个视图/元素一次性应用所有相关修复
修复应用顺序：
  1. 先执行P0严重修复
  2. 再执行P1高优先级修复
  3. 最后执行P2中优先级修复（仅在全面模式下）

Phase 4: Audit Test Generation

阶段4：审计测试生成

Load 
assets/audit-template.swift
and generate an XCTest file for the project.
  1. Create 
    AccessibilityAuditTests.swift
    in the project's test target directory
  2. Add a test method for each view/screen that was modified
  3. Use 
    performAccessibilityAudit()
    with appropriate audit types
  4. Include navigation setup to reach each view being tested
Match the project's existing test framework and patterns.
加载
assets/audit-template.swift
并为项目生成XCTest文件。
  1. 在项目的测试目标目录中创建
    AccessibilityAuditTests.swift
  2. 为每个被修改的视图/屏幕添加测试方法
  3. 使用
    performAccessibilityAudit()
    并选择合适的审计类型
  4. 包含导航设置以到达每个待测试视图
匹配项目现有的测试框架和模式。

Phase 5: Report

阶段5：报告输出

Output a structured summary:
undefined
输出结构化总结：
undefined

Accessibility Audit Report

Accessibility Audit Report

Issues Found

Issues Found

PriorityCategoryCount
P0 Critical......
P1 High......
P2 Medium......
PriorityCategoryCount
P0 Critical......
P1 High......
P2 Medium......

Changes Applied

Changes Applied

  • Files modified: [list]
  • Issues fixed: [count] of [total]
  • Test file generated: [path]
  • Files modified: [list]
  • Issues fixed: [count] of [total]
  • Test file generated: [path]

Accessibility Nutrition Label Readiness

Accessibility Nutrition Label Readiness

FeatureStatus
VoiceOverReady / Needs Work
Voice ControlReady / Needs Work
Larger TextReady / Needs Work
Sufficient ContrastNeeds Manual Review
Differentiate Without ColorReady / Needs Work
Reduced MotionReady / Needs Work
FeatureStatus
VoiceOverReady / Needs Work
Voice ControlReady / Needs Work
Larger TextReady / Needs Work
Sufficient ContrastNeeds Manual Review
Differentiate Without ColorReady / Needs Work
Reduced MotionReady / Needs Work

Manual Review Required

Manual Review Required

Items marked with [VERIFY] that need human confirmation:
  • [list of VERIFY items with file:line references]
Items marked with [VERIFY] that need human confirmation:
  • [list of VERIFY items with file:line references]

Next Steps

Next Steps

  • Run VoiceOver testing (see assets/checklist.md)
  • Review [VERIFY] markers and update labels
  • Run generated accessibility tests
  • Test with Dynamic Type at all sizes (up to AX5)
  • Test in both Light and Dark modes
  • Enable Increase Contrast + Bold Text + Reduce Transparency and verify
  • Enable Reduce Motion and verify animations
  • Test with Voice Control ("Show Names", "Show Numbers")
undefined
  • Run VoiceOver testing (see assets/checklist.md)
  • Review [VERIFY] markers and update labels
  • Run generated accessibility tests
  • Test with Dynamic Type at all sizes (up to AX5)
  • Test in both Light and Dark modes
  • Enable Increase Contrast + Bold Text + Reduce Transparency and verify
  • Enable Reduce Motion and verify animations
  • Test with Voice Control ("Show Names", "Show Numbers")
undefined

Configuration

配置选项

  • Standard mode (default): Fixes P0 and P1 issues, reports P2
  • Comprehensive mode: Fixes all priority levels — invoke with "comprehensive" or "full audit"
  • 标准模式（默认）：修复P0和P1问题，报告P2问题
  • 全面模式：修复所有优先级级别的问题——通过传入"comprehensive"或"full audit"调用

Supporting Files

支持文件

Loaded on-demand during execution:
  • rules/
    — Individual detection and fix rules per issue category (16 rules)
  • references/swiftui-patterns.md
    — Full SwiftUI accessibility modifier catalog
  • references/uikit-patterns.md
    — Full UIKit accessibility API catalog
  • references/wcag-guidelines.md
    — WCAG AA and Apple HIG reference
  • assets/audit-template.swift
    — XCTest accessibility audit template
  • assets/checklist.md
    — Manual verification checklist
执行期间按需加载：
  • rules/
    — 按问题类别划分的检测与修复规则（共16条）
  • references/swiftui-patterns.md
    — 完整的SwiftUI无障碍修饰符目录
  • references/uikit-patterns.md
    — 完整的UIKit无障碍API目录
  • references/wcag-guidelines.md
    — WCAG AA与苹果HIG参考文档
  • assets/audit-template.swift
    — XCTest无障碍审计模板
  • assets/checklist.md
    — 人工验证清单