1# SwiftUI Accessibility Patterns Reference
2 
3## Table of Contents
4 
5- [Core Principle](#core-principle)
6- [Dynamic Type and @ScaledMetric](#dynamic-type-and-scaledmetric)
7- [Accessibility Traits](#accessibility-traits)
8- [Decorative Images](#decorative-images)
9- [Element Grouping](#element-grouping)
10- [Custom Controls](#custom-controls)
11- [Summary Checklist](#summary-checklist)
12 
13## Core Principle
14 
15Prefer `Button` over `onTapGesture` for tappable elements. `Button` provides VoiceOver support, focus handling, and proper traits for free.
16 
17## Dynamic Type and @ScaledMetric
18 
19System text styles scale with Dynamic Type automatically. Prefer built-in styles like `.largeTitle`, `.title`, `.title2`, `.title3`, `.headline`, `.subheadline`, `.body`, `.callout`, `.footnote`, `.caption`, and `.caption2` when they fit your UI:
20 
21```swift
22VStack(alignment: .leading) {
23    Text("Inbox")
24        .font(.title2)
25    Text("3 unread messages")
26        .font(.body)
27    Text("Updated just now")
28        .font(.caption)
29}
30```
31 
32For custom fonts, use a Dynamic Type-aware font initializer so the text still follows the user's preferred content size:
33 
34```swift
35VStack(alignment: .leading) {
36    Text("Article")
37        .font(.custom("SourceSerif4-Semibold", size: 28, relativeTo: .title2))
38    Text("Body copy")
39        .font(.custom("SourceSerif4-Regular", size: 17))
40}
41```
42 
43`Font.custom(_:size:relativeTo:)` lets you match a specific text style. `Font.custom(_:size:)` scales relative to the body style. Avoid fixed-size custom fonts for primary content that should respond to Dynamic Type.
44 
45For non-text numeric values like padding, spacing, and image sizes, use `@ScaledMetric`:
46 
47```swift
48struct ProfileHeader: View {
49    @ScaledMetric private var avatarSize = 60.0
50    @ScaledMetric private var spacing = 12.0
51 
52    var body: some View {
53        HStack(spacing: spacing) {
54            Image("avatar")
55                .resizable()
56                .frame(width: avatarSize, height: avatarSize)
57            Text("Username")
58        }
59    }
60}
61```
62 
63Specify a `relativeTo` text style when the value should track a specific Dynamic Type style, including for images or icons that should stay proportional to nearby text:
64 
65```swift
66struct StatusRow: View {
67    @ScaledMetric(relativeTo: .body) private var iconSize = 18.0
68 
69    var body: some View {
70        HStack(spacing: 8) {
71            Image(systemName: "checkmark.circle.fill")
72                .font(.system(size: iconSize))
73            Text("Synced")
74                .font(.custom("AvenirNext-Regular", size: 17, relativeTo: .body))
75        }
76    }
77}
78```
79 
80## Accessibility Traits
81 
82Use `accessibilityAddTraits` and `accessibilityRemoveTraits` for state-driven traits:
83 
84```swift
85Text(item.title)
86    .accessibilityAddTraits(item.isSelected ? [.isSelected, .isButton] : .isButton)
87```
88 
89Use `.disabled(true)` to make VoiceOver announce "Dimmed" for non-interactive elements.
90 
91## Decorative Images
92 
93Use `Image(decorative:bundle:)` when an asset image is purely visual and should not appear in the accessibility tree.
94 
95```swift
96Image(decorative: "confetti")
97```
98 
99This is appropriate for backgrounds, flourishes, and icons that do not add meaning beyond nearby text.
100 
101If the image conveys information, keep it accessible and provide a clear label:
102 
103```swift
104Image("receipt")
105    .accessibilityLabel("Receipt")
106```
107 
108For non-asset images, such as SF Symbols, hide decorative content with `accessibilityHidden(true)` instead:
109 
110```swift
111Image(systemName: "sparkles")
112    .accessibilityHidden(true)
113```
114 
115## Element Grouping
116 
117### .combine -- Auto-join child labels
118 
119```swift
120HStack {
121    Image(systemName: "star.fill")
122    Text("Favorites")
123    Text("(\(count))")
124}
125.accessibilityElement(children: .combine)
126```
127 
128VoiceOver reads all child labels as one element, separated by commas.
129 
130### .ignore -- Manual label for container
131 
132```swift
133HStack {
134    Text(item.name)
135    Spacer()
136    Text(item.price)
137}
138.accessibilityElement(children: .ignore)
139.accessibilityLabel("\(item.name), \(item.price)")
140```
141 
142### .contain -- Semantic grouping
143 
144```swift
145HStack {
146    ForEach(tabs) { tab in
147        TabButton(tab: tab)
148    }
149}
150.accessibilityElement(children: .contain)
151.accessibilityLabel("Tab bar")
152```
153 
154VoiceOver announces the container name when focus enters/exits.
155 
156## Custom Controls
157 
158### Adjustable controls (increment/decrement)
159 
160```swift
161PageControl(selectedIndex: $selectedIndex, pageCount: pageCount)
162    .accessibilityElement()
163    .accessibilityValue("Page \(selectedIndex + 1) of \(pageCount)")
164    .accessibilityAdjustableAction { direction in
165        switch direction {
166        case .increment:
167            guard selectedIndex < pageCount - 1 else { break }
168            selectedIndex += 1
169        case .decrement:
170            guard selectedIndex > 0 else { break }
171            selectedIndex -= 1
172        @unknown default:
173            break
174        }
175    }
176```
177 
178### Representing custom views as native controls
179 
180When a custom view should behave like a native control for accessibility:
181 
182```swift
183HStack {
184    Text(label)
185    Toggle("", isOn: $isOn)
186}
187.accessibilityRepresentation {
188    Toggle(label, isOn: $isOn)
189}
190```
191 
192### Label-content pairing
193 
194```swift
195@Namespace private var ns
196 
197HStack {
198    Text("Volume")
199        .accessibilityLabeledPair(role: .label, id: "volume", in: ns)
200    Slider(value: $volume)
201        .accessibilityLabeledPair(role: .content, id: "volume", in: ns)
202}
203```
204 
205## Summary Checklist
206 
207- [ ] Use `Button` instead of `onTapGesture` for tappable elements
208- [ ] Use built-in text styles or Dynamic Type-aware custom fonts for text
209- [ ] Use `@ScaledMetric` for custom values that should scale with Dynamic Type
210- [ ] Mark purely decorative images as decorative or hidden from accessibility
211- [ ] Group related elements with `accessibilityElement(children:)`
212- [ ] Provide `accessibilityLabel` when default labels are unclear
213- [ ] Use `accessibilityRepresentation` for custom controls
214- [ ] Use `accessibilityAdjustableAction` for increment/decrement controls
215- [ ] Ensure navigation flow is logical when using VoiceOver grouping
216