ios-accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Accessibility

iOS无障碍开发

Overview

概述

This skill provides expert guidance on iOS accessibility, covering VoiceOver, Dynamic Type, assistive technologies, inclusive design practices, and both UIKit and SwiftUI implementations. Use this skill to help developers build apps that work for everyone.

本技能提供iOS无障碍开发的专业指导，涵盖VoiceOver、Dynamic Type、辅助技术、包容性设计实践，以及UIKit和SwiftUI的实现方案。借助本技能，开发者可打造适配所有用户的应用。

The Approach

实施方法

Shift-left — Accessibility is part of the process. It needs to be considered even in prototypes or MVPs.
User-centric — Accessibility is about people. Checklists help, but the goal is not checklist compliance. The goal is to offer a great experience for users with disabilities.
Progress over perfection — Anytime is a good time to start. Focus on iterative and incremental improvements as you go. It goes a long way.
Test as you go — Manual testing is part of development.

左移理念 —— 无障碍开发是流程的一部分，甚至在原型或MVP阶段就需要考虑。
以用户为中心 —— 无障碍开发的核心是服务用户。清单虽有帮助，但目标并非仅满足清单要求，而是为残障用户提供优质体验。
渐进优化 —— 任何时候开始都不算晚。专注于迭代式、渐进式的改进，长期来看会有显著成效。
边开发边测试 —— 手动测试是开发流程的一部分。

Agent Behavior Contract

Agent行为约定

Accessibility is non-deterministic. Propose potential solutions in order of confidence and present with clear pros, cons, and trade-offs.
Before proposing fixes, identify the platform (UIKit vs SwiftUI) and the assistive technology, accessibility feature, or design consideration in context.
Do not recommend accessibility fixes without considering the user experience impact.
Prefer manual testing guidance alongside code changes, together with any automated or semi-automated solutions.
Cross-reference multiple assistive technologies when relevant (VoiceOver, Voice Control, Switch Control, Full Keyboard Access).

无障碍开发无绝对标准答案。按可信度排序提出潜在解决方案，并清晰说明各方案的优缺点与权衡点。
在提出修复方案前，先明确平台（UIKit还是SwiftUI），以及上下文对应的辅助技术、无障碍功能或设计考量点。
不要在未考虑用户体验影响的情况下推荐无障碍修复方案。
在提供代码修改建议的同时，优先搭配手动测试指导，以及任何自动化或半自动化解决方案。
相关联时，交叉参考多种辅助技术（VoiceOver、Voice Control、Switch Control、全键盘访问）。

Anti-Patterns to Avoid

需避免的反模式

Do not add trait names to labels — Say "Close", not "Close button" (VoiceOver adds "button" automatically, when using the button trait)
Do not use
.accessibilityHidden(true)
on interactive elements — Users won't be able to access them
Do not use fixed font sizes — Always use text styles for Dynamic Type support
Do not use hardcoded colors for text — Use semantic colors (
```
.label
```
,
```
.secondaryLabel
```
) for contrast and Dark Mode
Do not group UIKit elements without a clear combined label — If
```
isAccessibilityElement = true
```
, set
```
accessibilityLabel
```
(and value/traits as needed).
Do not group SwiftUI elements without a clear combined label — If
```
.accessibilityElement(children: .ignore)
```
is used, provide label/value/traits manually.
Do not add hints unless needed — It should be clear what a component expresses, and does, by its label/value/traits. Only configure for adding extra clarity or context.
Do not rely on
onTapGesture
alone — Prefer semantic controls like
```
Button
```
. If gesture handling is unavoidable, add button traits and clear labels.
Do not scale chrome controls with Dynamic Type — For navigation bars, toolbars, and tab bars, prefer Large Content Viewer (iOS 13+) using
```
.accessibilityShowsLargeContentViewer
```
/
```
UILargeContentViewerItem
```
.

不要在标签中添加特性名称 —— 应使用“关闭”而非“关闭按钮”（当使用按钮特性时，VoiceOver会自动添加“按钮”字样）
不要在交互元素上使用
.accessibilityHidden(true)
—— 残障用户将无法访问这些元素
不要使用固定字体大小 —— 始终使用文本样式以支持Dynamic Type
不要为文本使用硬编码颜色 —— 使用语义化颜色（
```
.label
```
、
```
.secondaryLabel
```
）以确保对比度并适配深色模式
不要在未设置清晰组合标签的情况下分组UIKit元素 —— 如果设置
```
isAccessibilityElement = true
```
，需同时设置
```
accessibilityLabel
```
（必要时还需设置值/特性）。
不要在未设置清晰组合标签的情况下分组SwiftUI元素 —— 如果使用
```
.accessibilityElement(children: .ignore)
```
，需手动提供标签/值/特性。
不要随意添加提示信息 —— 组件的用途应通过其标签/值/特性清晰体现，仅在需要额外说明上下文时配置提示。
不要仅依赖
onTapGesture
—— 优先使用语义化控件如
```
Button
```
。若必须使用手势处理，需添加按钮特性和清晰标签。
不要让导航控件随Dynamic Type缩放 —— 对于导航栏、工具栏和标签栏，优先使用iOS 13+推出的Large Content Viewer，通过
```
.accessibilityShowsLargeContentViewer
```
/
```
UILargeContentViewerItem
```
实现。

General Guidance

通用指导

Prefer native components: Whenever possible, use Apple's native components and customize them to your needs instead of building custom components from scratch.

Design system first: Whenever the project uses a design system of its own (colors, text styles, component catalog), propose changes in the design system itself so the improvement snowballs everywhere in the app using an improved component.

Platform parity: The same accessibility principles apply to both UIKit and SwiftUI, but APIs and implementation details differ.

优先使用原生组件：只要有可能，就使用Apple的原生组件并按需自定义，而非从零开始构建自定义组件。

先从设计系统入手：如果项目有自己的设计系统（颜色、文本样式、组件库），建议直接在设计系统中修改，这样应用中所有使用该组件的地方都能同步受益。

平台一致性：无障碍原则在UIKit和SwiftUI中通用，但API和实现细节有所不同。

Project Settings Intake (Evaluate Before Advising)

项目设置评估（提供建议前需确认）

Before providing accessibility guidance, determine:

在提供无障碍开发指导前，需明确以下信息：

Project Capabilities

项目能力

Is the project using SwiftUI, UIKit, or a mix of both?

iOS deployment target — Some APIs require specific versions:

iOS 13+:
Large Content Viewer (
```
UILargeContentViewerInteraction
```
)
, SF Symbols

iOS 14+: Switch Control action images (

UIAccessibilityCustomAction.init(name:image:actionHandler:)

)

iOS 15+:

AccessibilityFocusState

.accessibilityRotor

iOS 16+:

.accessibilityRepresentation

.accessibilityActions { }

syntax

iOS 17+:
```
.sensoryFeedback
```

Check minimum OS — Look for
```
#available
```
checks and deployment target in project settings

项目使用SwiftUI、UIKit还是两者混合？

iOS部署目标 —— 部分API需要特定iOS版本：

iOS 13+：
Large Content Viewer (
```
UILargeContentViewerInteraction
```
)
、SF Symbols

iOS 14+：Switch Control动作图片 (

UIAccessibilityCustomAction.init(name:image:actionHandler:)

)

iOS 15+：

AccessibilityFocusState

、

.accessibilityRotor

iOS 16+：

.accessibilityRepresentation

、

.accessibilityActions { }

语法

iOS 17+：
```
.sensoryFeedback
```

检查最低系统版本 —— 查看项目设置中的
```
#available
```
检查和部署目标

Project Conventions

项目约定

Design system — Does the project define its own design system (colors, text styles, UI component catalogue)? Propose changes in the design system when appropriate, not only per-feature.
Semantic colors and text styles — Does the project use semantic colors (
```
.label
```
,
```
.systemBackground
```
) and text styles (
```
.preferredFont(forTextStyle:)
```
in UIKit,
```
.font(.body)
```
in SwiftUI) vs hardcoded values?
Existing accessibility patterns — Search for
```
.accessibilityLabel
```
,
```
.accessibilityTraits
```
, etc. to match project style.
Localization — Accessibility labels, values, and hints should be localized. Match the project's localization conventions.
UI construction — Interface Builder (XIB/Storyboard) or code-only?
Custom gestures — Identify if custom gestures need accessible alternatives.
Accessibility test coverage — Existing UI tests auditing for accessibility?

设计系统 —— 项目是否有自己的设计系统（颜色、文本样式、UI组件库）？适当时建议修改设计系统，而非仅针对单个功能调整。
语义化颜色和文本样式 —— 项目使用语义化颜色（
```
.label
```
、
```
.systemBackground
```
）和文本样式（UIKit中的
```
.preferredFont(forTextStyle:)
```
、SwiftUI中的
```
.font(.body)
```
）还是硬编码值？
现有无障碍实现模式 —— 查找
```
.accessibilityLabel
```
、
```
.accessibilityTraits
```
等代码，以匹配项目现有风格。
本地化 —— 无障碍标签、值和提示信息需支持本地化，需匹配项目的本地化约定。
UI构建方式 —— 使用Interface Builder（XIB/Storyboard）还是纯代码？
自定义手势 —— 确认是否需要为自定义手势提供无障碍替代方案。
无障碍测试覆盖 —— 是否已有用于审计无障碍的UI测试？

When Settings Are Unknown

当设置信息未知时

If you can't determine the above, ask the developer to confirm before giving version-specific or framework-specific guidance.

如果无法确定上述信息，请先让开发者确认，再提供特定版本或框架的指导。

Quick Decision Tree

快速决策树

When a developer needs accessibility guidance, follow this decision tree:

VoiceOver issues?
- Core concepts: Read
```
references/voiceover.md
```
- UIKit implementation: Read
```
references/voiceover-uikit.md
```
- SwiftUI implementation: Read
```
references/voiceover-swiftui.md
```
Dynamic Type, text scaling, or adaptive layout?
- Core concepts: Read
```
references/dynamic-type.md
```
- UIKit implementation: Read
```
references/dynamic-type-uikit.md
```
- SwiftUI implementation: Read
```
references/dynamic-type-swiftui.md
```
Other assistive technologies?
- Voice Control: Read
```
references/voice-control.md
```
- Switch Control: Read
```
references/switch-control.md
```
- Full Keyboard Access: Read
```
references/full-keyboard-access.md
```
Testing accessibility?
- Manual testing: Read
```
references/testing-manual.md
```
- Automated testing: Read
```
references/testing-automated.md
```
Cross-cutting concerns?
- Contrast, targets, motion, haptics: Read
```
references/good-practices.md
```
- Culture and mindset: Read
```
references/concepts-and-culture.md
```
Quick reference needed?
- Common mistakes, patterns, checklists: Read
```
references/playbook.md
```
Need definitions or sources?
- Glossary: Read
```
references/glossary.md
```
- Sources and further reading: Read
```
references/resources.md
```

当开发者需要无障碍开发指导时，遵循以下决策树：

VoiceOver相关问题？
- 核心概念：参考
```
references/voiceover.md
```
- UIKit实现：参考
```
references/voiceover-uikit.md
```
- SwiftUI实现：参考
```
references/voiceover-swiftui.md
```
Dynamic Type、文本缩放或自适应布局相关问题？
- 核心概念：参考
```
references/dynamic-type.md
```
- UIKit实现：参考
```
references/dynamic-type-uikit.md
```
- SwiftUI实现：参考
```
references/dynamic-type-swiftui.md
```
其他辅助技术相关问题？
- Voice Control：参考
```
references/voice-control.md
```
- Switch Control：参考
```
references/switch-control.md
```
- 全键盘访问：参考
```
references/full-keyboard-access.md
```
无障碍测试相关问题？
- 手动测试：参考
```
references/testing-manual.md
```
- 自动化测试：参考
```
references/testing-automated.md
```
跨领域问题？
- 对比度、交互区域、动效、触觉反馈：参考
```
references/good-practices.md
```
- 文化与思维：参考
```
references/concepts-and-culture.md
```
需要快速参考？
- 常见错误、模式、检查清单：参考
```
references/playbook.md
```
需要定义或参考资料？
- 术语表：参考
```
references/glossary.md
```
- 参考资料与延伸阅读：参考
```
references/resources.md
```

Quick Playbook (Start Here)

快速操作指南（从这里开始）

Confirm framework (UIKit vs SwiftUI) and iOS target.
Identify assistive technology and user-experience issue.
Use the Decision Tree and jump into the relevant reference file.
Whenever it makes sense, provide 2-3 options with trade-offs and expected UX impact.
Always include testing guidance alongside any code changes.

For common mistakes, inspector warnings, code patterns, version-specific APIs, and checklists, use

references/playbook.md

确认框架（UIKit或SwiftUI）和iOS目标版本。
明确辅助技术类型和用户体验问题。
使用决策树跳转至相关参考文档。
合理情况下，提供2-3种解决方案，并说明权衡点和预期用户体验影响。
提供代码修改建议时，始终搭配测试指导。

如需了解常见错误、检查器警告、代码模式、特定版本API和检查清单，可参考

references/playbook.md

。

Example Prompts and Expected Shape

示例提问与预期回复格式

Example prompt: “VoiceOver reads ‘button’ for my close button.” Expected response:

Confirm framework and iOS target if unknown.
Provide options when there are multiple viable approaches (for example, add an accessibility label vs a labeled button using icon-only style), with trade-offs.
Include a framework-appropriate snippet.
Add testing steps (VoiceOver, Voice Control...).

Example prompt: “Dynamic Type breaks my header layout in UIKit.” Expected response:

Confirm
```
preferredContentSizeCategory
```
handling and iOS target.
Suggest layout adaptation strategies (stack axis change vs constraints).
Include a UIKit snippet and testing steps at Large Accessibility Sizes.

示例提问： “VoiceOver会为我的关闭按钮读取‘按钮’字样。” 预期回复：

若信息未知，先确认框架和iOS目标版本。
若有多种可行方案，提供选项（例如，添加无障碍标签 vs 使用仅图标样式的带标签按钮），并说明权衡点。
提供适配对应框架的代码片段。
添加测试步骤（VoiceOver、Voice Control等）。

示例提问： “UIKit中Dynamic Type破坏了我的头部布局。” 预期回复：

确认
```
preferredContentSizeCategory
```
的处理方式和iOS目标版本。
建议布局适配策略（改变栈轴方向 vs 调整约束）。
提供UIKit代码片段和在大尺寸无障碍模式下的测试步骤。

Edge Cases and Gotchas

边缘情况与注意事项

Mixed UIKit/SwiftUI screens: use correct API set per view layer.
Custom controls or gestures: always provide a VoiceOver/Voice Control alternative.
Unknown iOS target: ask before suggesting version-specific APIs.
No code context: ask for relevant view code or a screenshot of the Accessibility Inspector.
Localization: all labels, values, and hints (and any other string parameter like custom content, or accessibility announcements, etc.) must be localized.

混合UIKit/SwiftUI的页面：为不同视图层使用正确的API集合。
自定义控件或手势：始终提供VoiceOver/Voice Control替代方案。
未知iOS目标版本：建议前先询问清楚。
无代码上下文：请求提供相关视图代码或无障碍检查器的截图。
本地化：所有标签、值、提示信息（以及任何其他字符串参数，如自定义内容或无障碍通知等）都必须支持本地化。