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

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Missing VoiceOver Labels	CRITICAL	`p0-`
2	Missing Context and Discoverability	HIGH	`p1-`
3	Visual, Interaction, and System Setting Compliance	MEDIUM	`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 Label	Rules Covering It
VoiceOver	p0-*, 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 Control	p1-missing-input-labels, p1-missing-hints, p2-custom-actions-missing
Larger Text (Dynamic Type)	p2-hardcoded-fonts
Sufficient Contrast	p2-contrast-insufficient
Dark Interface	p2-contrast-insufficient (checks both modes)
Differentiate Without Color Alone	p1-color-only-information
Reduced Motion	p2-reduce-motion-ignored
Bold Text	p2-bold-text-ignored
Touch Target Size	p1-small-touch-targets

营养标签	覆盖的规则
VoiceOver	p0-*, 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：项目发现

Glob for
```
**/*.swift
```
to find all Swift source files
Classify each file as SwiftUI (
```
import SwiftUI
```
), UIKit (
```
import UIKit
```
), or mixed

Grep for existing accessibility usage to understand current coverage:

SwiftUI:

.accessibilityLabel

.accessibilityHint

.accessibilityIdentifier

.accessibilityHidden

.accessibilityInputLabels

accessibilityReduceMotion

UIKit:

isAccessibilityElement

accessibilityLabel

accessibilityIdentifier

UIAccessibility.isReduceMotionEnabled

adjustsFontForContentSizeCategory

Report: total files, framework breakdown, current accessibility coverage percentage

通配匹配
```
**/*.swift
```
以找到所有Swift源文件
将每个文件分类为SwiftUI（包含
```
import SwiftUI
```
）、UIKit（包含
```
import UIKit
```
）或混合类型

搜索已有的无障碍代码使用情况，了解当前覆盖范围：

SwiftUI：

.accessibilityLabel

.accessibilityHint

.accessibilityIdentifier

.accessibilityHidden

.accessibilityInputLabels

accessibilityReduceMotion

UIKit：

isAccessibilityElement

accessibilityLabel

accessibilityIdentifier

UIAccessibility.isReduceMotionEnabled

adjustsFontForContentSizeCategory

生成报告：文件总数、框架分布、当前无障碍覆盖百分比

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:

Never overwrite existing accessibility code — only add missing properties

Add
[VERIFY]
comment markers on generated labels where semantic accuracy needs human review:

swift

.accessibilityLabel("Settings icon") // [VERIFY] confirm label matches intent

Preserve formatting — match the indentation and style of surrounding code
Group related fixes — apply all fixes to a single view/element together

Fix application order:

P0 Critical fixes first
P1 High fixes
P2 Medium fixes (comprehensive mode only)

使用编辑工具应用修复，遵循以下规则：

切勿覆盖现有无障碍代码——仅添加缺失的属性
在生成的标签上添加
```
[VERIFY]
```
注释标记，提示需要人工审核语义准确性：
swift
```
.accessibilityLabel("Settings icon") // [VERIFY] confirm label matches intent
```
保留格式——匹配周围代码的缩进和风格
分组相关修复——对单个视图/元素一次性应用所有相关修复

修复应用顺序：

先执行P0严重修复
再执行P1高优先级修复
最后执行P2中优先级修复（仅在全面模式下）

Phase 4: Audit Test Generation

阶段4：审计测试生成

Load

assets/audit-template.swift

and generate an XCTest file for the project.

Create
```
AccessibilityAuditTests.swift
```
in the project's test target directory
Add a test method for each view/screen that was modified
Use
```
performAccessibilityAudit()
```
with appropriate audit types
Include navigation setup to reach each view being tested

Match the project's existing test framework and patterns.

加载

assets/audit-template.swift

并为项目生成XCTest文件。

在项目的测试目标目录中创建
```
AccessibilityAuditTests.swift
```
为每个被修改的视图/屏幕添加测试方法
使用
```
performAccessibilityAudit()
```
并选择合适的审计类型
包含导航设置以到达每个待测试视图

匹配项目现有的测试框架和模式。

Phase 5: Report

阶段5：报告输出

Output a structured summary:

undefined

输出结构化总结：

undefined

Accessibility Audit Report

Issues Found

Priority	Category	Count
P0 Critical	...	...
P1 High	...	...
P2 Medium	...	...

Priority	Category	Count
P0 Critical	...	...
P1 High	...	...
P2 Medium	...	...

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

Feature	Status
VoiceOver	Ready / Needs Work
Voice Control	Ready / Needs Work
Larger Text	Ready / Needs Work
Sufficient Contrast	Needs Manual Review
Differentiate Without Color	Ready / Needs Work
Reduced Motion	Ready / Needs Work

Feature	Status
VoiceOver	Ready / Needs Work
Voice Control	Ready / Needs Work
Larger Text	Ready / Needs Work
Sufficient Contrast	Needs Manual Review
Differentiate Without Color	Ready / Needs Work
Reduced Motion	Ready / Needs Work

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

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
```
— 人工验证清单