Skip to content
Back to search

ios-swiftui-accessibility

Enforces WCAG 2.2 accessible coding patterns when writing SwiftUI — labels, traits, Dynamic Type, contrast, touch targets, focus management, orientation, and more. Based on the ios-swiftui-accessibility-techniques project with 46 static analysis rules across 24 WCAG criteria.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 12 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cvs-health/ios-swiftui-accessibility-techniques with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cvs-health/ios-swiftui-accessibility-techniques'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cvs-health--ios-swiftui-accessibility-techniques/badge.svg)](/listings/cvs-health--ios-swiftui-accessibility-techniques)

HTML

<a href="/listings/cvs-health--ios-swiftui-accessibility-techniques"><img src="/api/listings/cvs-health--ios-swiftui-accessibility-techniques/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 501 lines
  1. ---
  2. name: ios-swiftui-accessibility
  3. description: Enforces WCAG 2.2 accessible coding patterns when writing SwiftUI — labels, traits, Dynamic Type, contrast, touch targets, focus management, orientation, and more. Based on the ios-swiftui-accessibility-techniques project with 46 static analysis rules across 24 WCAG criteria.
  4. ---
  5. # iOS SwiftUI Accessibility Coding Rules
  6. Follow these rules when writing or reviewing SwiftUI code. Each rule maps to a WCAG 2.2 success criterion.
  7. ## Images (WCAG 1.1.1)
  8. - Every `Image(systemName:)` and `Image("name")` must have `.accessibilityLabel("description")` describing what the image conveys.
  9. - For decorative images that add no information, use `Image(decorative:)` or add `.accessibilityHidden(true)`.
  10. - Never include words like "image", "icon", "graphic", or "button" in an `.accessibilityLabel` — VoiceOver already announces the element's trait.
  11. - Describe what the image shows, not the file name or technical details.
  12. ```swift
  13. // Good
  14. Image(systemName: "heart.fill")
  15. .accessibilityLabel("Favorite")
  16. // Good — decorative
  17. Image(decorative: "background-pattern")
  18. // Bad — no label
  19. Image(systemName: "trash")
  20. // Bad — includes role
  21. Image(systemName: "heart.fill")
  22. .accessibilityLabel("Heart icon")
  23. ```
  24. ## Buttons (WCAG 4.1.2)
  25. - Icon-only `Button` views must have `.accessibilityLabel("action")` describing what the button does.
  26. - Never include "button" in the `.accessibilityLabel` — VoiceOver announces the button trait automatically, so users hear "Delete button, button".
  27. - Prefer `Button` over `.onTapGesture`. If you must use `.onTapGesture`, add `.accessibilityAddTraits(.isButton)` so VoiceOver announces it as a button.
  28. - Visually disabled buttons (using `.opacity()` or `.tint(.gray)`) must also use `.disabled(true)` so assistive technology knows the button is disabled.
  29. ```swift
  30. // Good
  31. Button(action: { deleteItem() }) {
  32. Image(systemName: "trash")
  33. }
  34. .accessibilityLabel("Delete")
  35. // Bad — label includes role
  36. Button(action: {}) {
  37. Image(systemName: "trash")
  38. }
  39. .accessibilityLabel("Delete button")
  40. // Bad — looks disabled but isn't semantically
  41. Button("Submit", action: {})
  42. .opacity(0.5)
  43. // Fix:
  44. Button("Submit", action: {})
  45. .disabled(true)
  46. ```
  47. ## Accessibility Label (WCAG 4.1.2, 2.5.3)
  48. - Every interactive control must have a meaningful accessible name — either from visible text content or `.accessibilityLabel`.
  49. - Labels should be concise (ideally 1–3 words), begin capitalized, and not end with a period.
  50. - The `.accessibilityLabel` must start with the visible label text so Voice Control users can activate the element by saying what they see (Label in Name — WCAG 2.5.3).
  51. - Never include the control type in the label ("button", "tab", "link", "image").
  52. ```swift
  53. // Good — specific label includes visible text first
  54. Button("Add to cart") {}
  55. .accessibilityLabel("Add to cart, Wireless Headphones")
  56. // Bad — accessible name doesn't contain visible text
  57. Button("Add to cart") {}
  58. .accessibilityLabel("Purchase Wireless Headphones")
  59. ```
  60. ## Accessibility Value (WCAG 4.1.2)
  61. - Use `.accessibilityValue` on custom controls to convey their current state or value (e.g., "3 out of 5", "Step 2 of 4", "enabled"/"disabled").
  62. - Pair adjustable custom controls with `.accessibilityAdjustableAction` so VoiceOver users can swipe up/down to change the value.
  63. - Use `.accessibilityValue` on tab bar items to convey badge notification counts (e.g., "3 notifications").
  64. ```swift
  65. // Good — custom star rating
  66. HStack {
  67. ForEach(1...5, id: \.self) { star in
  68. Image(systemName: star <= rating ? "star.fill" : "star")
  69. }
  70. }
  71. .accessibilityElement(children: .ignore)
  72. .accessibilityLabel("Rating")
  73. .accessibilityValue("\(rating) out of 5")
  74. .accessibilityAdjustableAction { direction in
  75. switch direction {
  76. case .increment: rating = min(5, rating + 1)
  77. case .decrement: rating = max(1, rating - 1)
  78. @unknown default: break
  79. }
  80. }
  81. ```
  82. ## Accessibility Hint (WCAG 3.3.2)
  83. - Hints are optional for standard buttons and taps — VoiceOver users can turn them off. Only add a hint when the result of activating an element is not obvious from the label alone.
  84. - **Hints are required** for elements with non-obvious interactions: `.onLongPressGesture`, `.onDrag`, `.onDrop`, `.contextMenu`, `.swipeActions`, `DragGesture`, and `LongPressGesture`. Without a hint, VoiceOver users won't know these interactions exist.
  85. - Use third-person singular verb describing the result: "Adds this item to your favorites." NOT "Add this item to your favorites."
  86. - Never describe the gesture method ("tap", "double tap", "swipe") — VoiceOver already tells users how to interact. Describe what happens, not how to do it.
  87. - Never repeat the label text or include the control type ("button", "link").
  88. - Begin capitalized, end with a period.
  89. ```swift
  90. // Good
  91. Button(action: { toggleFavorite() }) {
  92. Image(systemName: "heart")
  93. }
  94. .accessibilityLabel("Favorite")
  95. .accessibilityHint("Adds this item to your favorites.")
  96. // Bad — describes the gesture method
  97. .accessibilityHint("Double tap to add this item to your favorites.")
  98. // Bad — repeats label
  99. .accessibilityHint("Favorite")
  100. // Good — hint required for long press
  101. Text(item.name)
  102. .onLongPressGesture { showActions() }
  103. .accessibilityHint("Shows available actions.")
  104. // Good — hint required for context menu
  105. Button(item.name) { selectItem() }
  106. .contextMenu { /* menu items */ }
  107. .accessibilityHint("Shows additional options.")
  108. ```
  109. ## Headings (WCAG 1.3.1)
  110. - Add `.accessibilityAddTraits(.isHeader)` to all heading-styled text (`.title`, `.headline`, `.subheadline`, etc.) so VoiceOver users can navigate by headings using the Rotor.
  111. - **This applies to your design system's heading tokens too**, not just Apple's styles — `.headingXXL`, `.themeHeadingXL`, `.dsHeading2`. In most real apps that is where nearly all headings live, and they are the ones most often missed.
  112. - Pick the token for what the text *is*, not how large you want it. Rendering a paragraph, a price, or a field label at `.headline` or `.headingL` is a misuse: Apple's text styles are named semantically and `.body`, `.callout` and `.footnote` exist for secondary text. A value shown large is still a value, not a heading.
  113. - Never fake a heading by putting "heading" in the `.accessibilityLabel` — it won't appear in the Rotor.
  114. - Use `.accessibilityHeading(.h1)` through `.h6` together with `.accessibilityAddTraits(.isHeader)` to set heading levels. Don't skip levels.
  115. ```swift
  116. // Good
  117. Text("Settings")
  118. .font(.title)
  119. .accessibilityAddTraits(.isHeader)
  120. // Bad — fake heading
  121. Text("Settings")
  122. .font(.title)
  123. .accessibilityLabel("Settings heading")
  124. // Good — a design-system heading token still needs the trait
  125. PSText("Order summary", font: .headingL)
  126. .accessibilityAddTraits(.isHeader)
  127. // Bad — a value styled large is not a heading; it needs a label/value, not .isHeader
  128. PSText(item.price, font: .headingL)
  129. // Bad — body copy at a heading token. Fix the token, do not add the trait.
  130. PSText(longDescription, font: .headingS)
  131. ```
  132. ## Traits (WCAG 4.1.2)
  133. - Use the correct accessibility trait so assistive technology announces the element's role:
  134. - `.isButton` — interactive elements that perform an action
  135. - `.isLink` — elements that navigate to a URL or another view
  136. - `.isHeader` — section headings
  137. - `.isSelected` — selected items in a list or tab
  138. - `.isImage` — informative images
  139. - Prefer `Button` and `Link` views (which set traits automatically) over manual `.onTapGesture` + `.accessibilityAddTraits`.
  140. ## Dynamic Type (WCAG 1.4.4)
  141. - Use text styles (`.title`, `.body`, `.caption`, `.headline`, etc.) instead of `.font(.system(size: N))` so text scales with the user's preferred size.
  142. - Never use `.lineLimit(1)` — it truncates text at larger sizes.
  143. - Wrap text content in a `ScrollView` so it remains accessible when enlarged.
  144. - Cap already-large styles (`.largeTitle`, `.title`) with `.dynamicTypeSize(...DynamicTypeSize.xxxLarge)` to prevent excessive growth while still meeting the 200% resize requirement. Never cap body text or small text.
  145. - Use `axis: .vertical` on `TextField` so entered text wraps instead of truncating.
  146. ```swift
  147. // Good
  148. Text("Welcome")
  149. .font(.largeTitle)
  150. .dynamicTypeSize(...DynamicTypeSize.xxxLarge)
  151. // Bad — fixed size, won't scale
  152. Text("Welcome")
  153. .font(.system(size: 34))
  154. ```
  155. ## Color and Contrast (WCAG 1.4.3, 1.4.11)
  156. - Use semantic colors (`Color.primary`, `Color.secondary`) or Asset Catalog colors that adapt to light/dark mode. Never hardcode `.black`, `.white`, or `Color(red:green:blue:)` for foreground/background pairs.
  157. - Text contrast ratio must be at least 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold).
  158. - Non-text elements (icons, borders, focus indicators) must have at least 3:1 contrast ratio.
  159. - Support the Increase Contrast accessibility setting.
  160. ```swift
  161. // Good — adapts to dark mode
  162. Text("Hello")
  163. .foregroundColor(.primary)
  164. // Bad — won't adapt to dark mode
  165. Text("Hello")
  166. .foregroundColor(.black)
  167. // Bad — insufficient contrast (gray text on white background)
  168. Text("Subtitle")
  169. .foregroundColor(Color(red: 0.7, green: 0.7, blue: 0.7))
  170. .background(Color.white)
  171. // Good — sufficient contrast
  172. Text("Subtitle")
  173. .foregroundColor(.secondary)
  174. ```
  175. ## Touch Target Size (WCAG 2.5.8)
  176. - Touch targets must be at least 24x24pt (WCAG 2.2 Level AA minimum). Use `.frame(minWidth: 24, minHeight: 24)` on icon-only buttons.
  177. - Apple recommends 44x44pt for comfortable tapping. Inline targets within a line of text are exempt.
  178. ```swift
  179. // Good
  180. Button(action: {}) {
  181. Image(systemName: "xmark")
  182. .frame(minWidth: 44, minHeight: 44)
  183. }
  184. ```
  185. ## Form Controls (WCAG 1.3.5, 3.3.2, 4.1.2)
  186. - `TextField`, `SecureField`, `Slider`, `Stepper`, `Picker`, and `Toggle` all need a visible label that persists. **Where that label comes from differs by control, and getting this wrong is the most common form mistake:**
  187. - **`Toggle`, `Picker`, `Slider`, `Stepper`** — the built-in label parameter *is* a visible persistent label. Use it; no `.accessibilityLabel` needed.
  188. - **`TextField`, `SecureField`** — the built-in parameter is **placeholder text, not a label.** It needs a separate visible `Text` beside the field, set as the field's `.accessibilityLabel`.
  189. - **A placeholder is never a label.** `TextField("Email", text: $email)` renders its title as placeholder text, and **once the user types a value VoiceOver never speaks it again** — a populated field announces only its value. "120, text field" does not say whether it is systolic or diastolic. This fails 3.3.2 *and* 4.1.2, not just 3.3.2.
  190. - That makes placeholder-only labelling worse than it looks in testing: it **passes** a VoiceOver pass over an empty form and only fails after data entry. If your check is "open the screen and swipe through", you will not catch it. Fill the form in first.
  191. - Never use `.labelsHidden()` without providing an `.accessibilityLabel`.
  192. - Pickers with `WheelPickerStyle` or `SegmentedPickerStyle` require both `.accessibilityLabel("Label")` and `.accessibilityElement(children: .contain)` or VoiceOver will not speak the picker's label.
  193. - Add `.textContentType(.emailAddress)`, `.textContentType(.password)`, etc. to text fields so autofill works correctly.
  194. ```swift
  195. // Good — visible label above the text field, and set as the accessible name
  196. Text("Email")
  197. TextField("Email", text: $email)
  198. .accessibilityLabel("Email")
  199. .textContentType(.emailAddress)
  200. // Bad — placeholder only. Reads as "Email, text field" while empty,
  201. // then as just "jo@example.com, text field" once filled in.
  202. TextField("Email", text: $email)
  203. // Good — Toggle with built-in label
  204. Toggle("Enable notifications", isOn: $notificationsEnabled)
  205. // Bad — Toggle without a label
  206. Toggle(isOn: $notificationsEnabled) {
  207. Image(systemName: "bell")
  208. }
  209. // Fix: add .accessibilityLabel("Enable notifications")
  210. // Good — Slider with label
  211. Slider(value: $volume, in: 0...100) {
  212. Text("Volume")
  213. }
  214. // Bad — Slider without any label
  215. Slider(value: $volume, in: 0...100)
  216. // Fix: add .accessibilityLabel("Volume")
  217. // Good — Stepper with label
  218. Stepper("Quantity: \(quantity)", value: $quantity, in: 1...10)
  219. // Bad — Stepper without a label
  220. Stepper(value: $quantity, in: 1...10) {
  221. Image(systemName: "cart")
  222. }
  223. // Fix: add .accessibilityLabel("Quantity")
  224. // Good — segmented picker with both required modifiers
  225. Picker("Size", selection: $size) {
  226. Text("S").tag("S")
  227. Text("M").tag("M")
  228. Text("L").tag("L")
  229. }
  230. .pickerStyle(.segmented)
  231. .accessibilityElement(children: .contain)
  232. .accessibilityLabel("Size")
  233. // Bad — hidden label, no accessibility label
  234. TextField("", text: $email)
  235. .labelsHidden()
  236. ```
  237. ## Navigation and Page Titles (WCAG 2.4.2, 2.4.3)
  238. - Every view inside a `NavigationStack` must have `.navigationTitle("Page Title")` so VoiceOver announces the page when it appears.
  239. - After dismissing a `.sheet()`, `.fullScreenCover()`, `.alert()`, or `.popover()`, return VoiceOver focus to the trigger element using `@AccessibilityFocusState`.
  240. ```swift
  241. @AccessibilityFocusState private var isTriggerFocused: Bool
  242. Button("Show Details") { showSheet = true }
  243. .accessibilityFocused($isTriggerFocused)
  244. .sheet(isPresented: $showSheet, onDismiss: {
  245. isTriggerFocused = true
  246. }) {
  247. DetailView()
  248. }
  249. ```
  250. ## Gestures (WCAG 2.1.1, 2.5.1)
  251. - Custom gestures (`.onLongPressGesture`, `DragGesture`, `RotationGesture`, `MagnificationGesture`) must have:
  252. 1. An `.accessibilityAction` alternative for VoiceOver users
  253. 2. A visible single-tap `Button` alternative for touch users who cannot perform the gesture
  254. ```swift
  255. // Good — drag gesture with button alternatives
  256. ForEach(items) { item in
  257. Text(item.name)
  258. .onDrag { NSItemProvider(object: item.name as NSString) }
  259. }
  260. // Plus: Move Up / Move Down buttons or .accessibilityAction for reordering
  261. ```
  262. ## Animation and Motion (WCAG 2.3.1)
  263. - Always check `@Environment(\.accessibilityReduceMotion)` or `UIAccessibility.isReduceMotionEnabled` before using `.animation()` or `withAnimation`. Remove or simplify animations when reduce motion is enabled.
  264. ```swift
  265. @Environment(\.accessibilityReduceMotion) var reduceMotion
  266. withAnimation(reduceMotion ? nil : .spring()) {
  267. isExpanded.toggle()
  268. }
  269. ```
  270. ## Links (WCAG 2.4.4, 4.1.2)
  271. - Use `Link("text", destination: url)` instead of a `Button` that calls `openURL`. This gives the element the correct link trait.
  272. - Never use generic link text like "Click here", "Read more", "Learn more", or "Tap here". The link text must describe its destination.
  273. ```swift
  274. // Good
  275. Link("CVS Health Privacy Policy", destination: privacyURL)
  276. // Bad — button used as link
  277. Button("Click here") { openURL(privacyURL) }
  278. ```
  279. ## Reading Order / Grouping (WCAG 1.3.1, 1.3.2)
  280. - Use `.accessibilityElement(children: .combine)` on an `HStack` or `VStack` containing an `Image` and `Text` that represent a single concept, so VoiceOver reads them as one element.
  281. - Use `.accessibilityElement(children: .contain)` and `.accessibilityLabel("group label")` on containers of related Buttons (radio-style choices, rating buttons, control groups) so VoiceOver announces the group context when the user navigates into the group. This is analogous to a `<fieldset>` with a `<legend>` in HTML.
  282. - Never use `.accessibilityLabel` on a group container *without* `.accessibilityElement(children: .contain)` — it overrides the visible label text of every control inside the group and causes a Label in Name failure (WCAG 2.5.3).
  283. - In a `ZStack`, VoiceOver reads elements in source order (bottom to top visually), which often doesn't match the visual reading order. If overlaid elements are interactive, use `.accessibilitySortPriority()` or `.accessibilityElement` to control VoiceOver reading order — or restructure the view hierarchy so the source order matches the visual order.
  284. - Only use `.accessibilitySortPriority()` when the visual layout genuinely doesn't match VoiceOver's default left-to-right, top-to-bottom order (e.g., ZStack overlays). Prefer restructuring the view hierarchy or using `.accessibilityElement(children: .combine)` first — sort priority overrides are fragile and easy to get wrong. Overusing `.accessibilitySortPriority()` across many elements makes the reading order hard to maintain.
  285. ```swift
  286. // Good — combine image and text into one element
  287. HStack {
  288. Image(systemName: "star.fill")
  289. Text("Favorites")
  290. }
  291. .accessibilityElement(children: .combine)
  292. // Bad — ZStack with confusing reading order
  293. ZStack {
  294. Image("background")
  295. VStack {
  296. Text("Title")
  297. Button("Action") { doSomething() }
  298. }
  299. }
  300. // VoiceOver reads Image first, then Title, then Button — but Image is behind everything.
  301. // Fix: hide the background image and let the foreground content speak.
  302. // Good — group of related buttons with a container label
  303. VStack {
  304. Text("Delivery method")
  305. Button("Standard") { method = .standard }
  306. Button("Express") { method = .express }
  307. }
  308. .accessibilityElement(children: .contain)
  309. .accessibilityLabel("Delivery method")
  310. // Bad — container label without children: .contain
  311. VStack {
  312. Button("Standard") { method = .standard }
  313. Button("Express") { method = .express }
  314. }
  315. .accessibilityLabel("Delivery method")
  316. // Both buttons now report "Delivery method" instead of their visible text — a Label in Name failure.
  317. ```
  318. ## Sheets and Modals (WCAG 2.4.3)
  319. - Always include a `ScrollView` inside `.sheet()` and `.fullScreenCover()` so content remains accessible at large Dynamic Type sizes.
  320. - Manage focus return on dismiss to avoid losing VoiceOver focus.
  321. ## Tab Bars (WCAG 4.1.2, 2.4.2)
  322. - Every tab in a `TabView` must have a `.tabItem { Label("name", systemImage: "icon") }`. A tab without any label is invisible to VoiceOver — users won't know what the tab is for.
  323. - When using `.badge(count)`, also add `.accessibilityValue("\(count) notifications")` because `.badge()` is not automatically read by VoiceOver.
  324. ```swift
  325. // Good
  326. TabView {
  327. HomeView()
  328. .tabItem { Label("Home", systemImage: "house") }
  329. SettingsView()
  330. .tabItem { Label("Settings", systemImage: "gear") }
  331. .badge(3)
  332. .accessibilityValue("3 notifications")
  333. }
  334. // Bad — tab has no label
  335. TabView {
  336. HomeView()
  337. .tabItem { Image(systemName: "house") }
  338. }
  339. ```
  340. ## Accessibility Hidden (WCAG 4.1.2, 1.3.1)
  341. - Never apply `.accessibilityHidden(true)` on a container that has interactive children (`Button`, `Toggle`, `TextField`, etc.) — this hides them from VoiceOver completely.
  342. - Only use `.accessibilityHidden(true)` on purely decorative elements.
  343. - **Never apply `.accessibilityHidden(true)` to visible label text.** Moving a field's label onto the control with `.accessibilityLabel` and hiding the visible copy, so VoiceOver stops saying it twice, fails 1.3.1 Info and Relationships: the text is still on screen but gone from the accessibility tree, so swiping past the form skips it, Voice Control users cannot speak it to reach the field, and nothing is left if the control's label is later changed.
  344. Hearing a label twice is **not** a failure. The web behaves the same way — `<label for>` names the input and stays readable as text, `aria-describedby` is spoken on focus as well as being visible — and hides nothing to avoid it. Associate the two and accept the repetition.
  345. ```swift
  346. // Good — label is readable and names the field
  347. VStack(alignment: .leading) {
  348. Text("Email address")
  349. TextField("", text: $email)
  350. .accessibilityLabel("Email address")
  351. }
  352. // Bad — the visible label is deleted from the accessibility tree
  353. VStack(alignment: .leading) {
  354. Text("Email address")
  355. .accessibilityHidden(true)
  356. TextField("", text: $email)
  357. .accessibilityLabel("Email address")
  358. }
  359. ```
  360. Three cases where hiding text *is* right: it is decorative or very short (a badge count, a glyph) and the surrounding element already says what it means; it is `.strikethrough()`, where reading "$12.99" aloud would claim to be the current price; or it is a `.placeholder { ... }` overlay duplicating a name the field already carries.
  361. ## Timing (WCAG 2.2.1)
  362. - Content that auto-dismisses (using `Task.sleep` or `asyncAfter` with a dismiss) must give the user control to extend or pause the timer.
  363. ## Orientation (WCAG 1.3.4)
  364. - Never lock the app to a single orientation (portrait-only or landscape-only). Users with mounted devices (e.g., wheelchair mounts) may not be able to rotate their device.
  365. - Do not override `supportedInterfaceOrientations` to return only `.portrait` or only `.landscape`.
  366. - Do not call `requestGeometryUpdate` to force a single orientation.
  367. ```swift
  368. // Bad — locks to portrait only
  369. override var supportedInterfaceOrientations: UIInterfaceOrientationMask {
  370. .portrait
  371. }
  372. // Good — supports all orientations
  373. override var supportedInterfaceOrientations: UIInterfaceOrientationMask {
  374. .allButUpsideDown
  375. }
  376. ```
  377. ## Accessibility Notifications
  378. - Use `UIAccessibility.post(notification: .announcement, argument: "message")` to announce dynamic content changes to VoiceOver users (e.g., search result counts, form validation errors).
  379. - Use `.screenChanged` when the entire screen changes and `.layoutChanged` when part of the screen changes.
  380. ---
  381. Source: [ios-swiftui-accessibility-techniques](https://github.com/cvs-health/ios-swiftui-accessibility-techniques) by CVS Health — 91 technique examples, 46 static analysis rules, 24 WCAG 2.2 criteria.
  382. ----
  383. Copyright 2026 CVS Health and/or one of its affiliates
  384. Licensed under the Apache License, Version 2.0 (the "License");
  385. you may not use this file except in compliance with the License.
  386. You may obtain a copy of the License at
  387. [http://www.apache.org/licenses/LICENSE-2.0]()
  388. Unless required by applicable law or agreed to in writing, software
  389. distributed under the License is distributed on an "AS IS" BASIS,
  390. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  391. See the License for the specific language governing permissions and
  392. limitations under the License.
README.md · README · 231 lines · 1 finding marked
  1. # iOS SwiftUI Accessibility Techniques
  2. iOS and watchOS SwiftUI sample code demonstrating a variety of good and bad accessibility techniques. Learn how to apply WCAG 2.2 to iOS SwiftUI apps. Good and bad examples can be tested with VoiceOver and other iOS accessibility features.
  3. This repo also includes **[a11y-check](#a11y-checker-a11y-check)**, a static analysis tool that scans your Swift/SwiftUI source code for accessibility issues — 46 rules across 24 WCAG 2.2 criteria, with scoring, auto-fix, and CI integration.
  4. [Download the iOS app from the App Store.](https://apps.apple.com/app/accessibility-techniques/id6474141089)
  5. Read the blog post, [Announcing the iOS SwiftUI Accessibility Techniques Open Source Project](https://www.linkedin.com/pulse/announcing-ios-swiftui-accessibility-techniques-open-source-adam-ldahc/).
  6. Review project source code to learn how to apply the accessibility techniques in working SwiftUI code examples. A companion **watchOS app** is also included in the `a11yTechniques Watch App/` directory.
  7. ### Building this project
  8. To see **a11y-check** accessibility warnings and errors inline in Xcode when you build, install the tool first:
  9. ```bash
  10. brew tap cvs-health/ios-swiftui-accessibility-techniques https://github.com/cvs-health/ios-swiftui-accessibility-techniques.git
  11. brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check
  12. ```
  13. Without this step the project still builds and runs, but the a11y-check build phase is silently skipped.
  14. To verify it installed correctly, run `a11y-check --version`. To update later, run `brew uninstall a11y-check && brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check`.
  15. ## A11y Checker (a11y-check)
  16. Static analysis for SwiftUI accessibility issues, mapped to WCAG 2.2 success criteria. **46 rules** across **24 WCAG criteria** with a **0–100 scoring system**. Run it on your Swift sources to find missing labels, incorrect traits, touch target size, and more. Supports auto-fix (`--fix`), SARIF output for GitHub code scanning, trend tracking, and per-view scoring.
  17. ### Check your own iOS app
  18. 1. **Install** the tool once (choose one method below).
  19. 2. **Run it:** Open Terminal, go to your app’s project folder (the folder that contains your Swift files), and run:
  20. ```bash
  21. cd /path/to/YourApp
  22. a11y-check .
  23. ```
  24. The `.` means “this folder” — a11y-check will scan all `.swift` files here and in subfolders and print a list of issues (missing labels, small touch targets, etc.) with file and line.
  25. **Tip:** Use `a11y-check . --only error` to show only errors, or `a11y-check --list-rules` to see all rules.
  26. ---
  27. **Install via Homebrew (easiest on any Mac):**
  28. ```bash
  29. brew tap cvs-health/ios-swiftui-accessibility-techniques https://github.com/cvs-health/ios-swiftui-accessibility-techniques.git
  30. brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check
  31. ```
  32. Then from your app folder: `a11y-check .`
  33. To verify it installed: `a11y-check --version`
  34. To update later: `brew uninstall a11y-check && brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check`
  35. **Or build from source:**
  36. Requires **Swift 5.9+** and **macOS 13+** (Xcode or [Swift.org](https://swift.org) toolchain). From a terminal:
  37. ```bash
  38. git clone https://github.com/cvs-health/ios-swiftui-accessibility-techniques.git
  39. cd ios-swiftui-accessibility-techniques/a11y-check
  40. swift build
  41. ```
  42. To run the checker on your app: from anywhere use the full path to the binary, with your app’s folder as the argument:
  43. ```bash
  44. /path/to/ios-swiftui-accessibility-techniques/a11y-check/.build/debug/a11y-check /path/to/YourApp
  45. ```
  46. (Replace both paths with your actual paths.) If `swift build` fails, run `swift --version` (you need 5.9 or later); otherwise use the Homebrew method above.
  47. See **[a11y-check/README.md](a11y-check/README.md)** for full usage, options, and CI integration.
  48. **Use with AI editors (MCP):** An [MCP server](a11y-check/mcp-server/README.md) is included so you can run a11y-check from any MCP-compatible editor like Windsurf or Cursor (e.g. "check this project for accessibility"). Install a11y-check first, then add the MCP server config pointing at `a11y-check/mcp-server`.
  49. **AI coding skill:** A [SKILL.md](SKILL.md) file is included that teaches AI coding assistants (Claude Code, CVS Code, Cursor, etc.) how to write accessible SwiftUI code, enforcing WCAG 2.2 accessible coding patterns — labels, traits, Dynamic Type, contrast, touch targets, focus management, and more. A skill must live in its own directory whose name matches the skill's `name`, so copy it to `~/.claude/skills/ios-swiftui-accessibility/SKILL.md` (or the equivalent path in your editor's skills folder). A loose `SKILL.md` placed directly in `~/.claude/skills/` is not discovered.
  50. **AI design annotation skill:** A [FIGMA-ANNOTATIONS-SKILL.md](FIGMA-ANNOTATIONS-SKILL.md) file is included for the *design* stage — the rules an AI must follow when annotating an iOS design in Figma for accessibility. AI annotation reliably fails the same three ways: it over-annotates (thirty notes where six belong), it uses web ARIA vocabulary that does not exist on iOS (`alt text`, `role=`, landmarks, skip links, tab order, breakpoints), and it gets the content wrong (roles inside labels, hints that name the gesture, fake headings). This file fixes all three with ten stated principles, a bare-minimum rule with no annotation quota, a closed set of nine iOS annotation types, a 22-row banned-vocabulary table, exact grammar per type, a worked before/after example, and a 25-step self-check. Several of the principles are *never annotate this* rules — never annotate visible text as a label (it manufactures a Label in Name failure and produces redundant code), never annotate accessibility traits in any form (the modifier gets written onto a control that already has the trait), never annotate the default top-to-bottom reading order, and never annotate Dynamic Type behaviour (a layout that breaks at large text sizes needs a large-text *design*, not a note asking a developer to prevent it). Control types work the other way around: every control that is **not** a button gets named — `Link`, `Switch`, `Picker`, `Stepper`, `Slider` — because a button is the developer's default reading of any tappable element and a switch drawn as a pill is the same picture as a button drawn as a pill. A button is the one control never named, since saying it specifies nothing. One governs where annotations live: put the value in the Figma **properties panel** rather than a callout on the canvas, because a property is structured data attached to the layer that an AI can read reliably when generating an accessible prototype, while a floating callout's target can only be guessed at. Properties-panel values are the design specifying itself rather than notes competing for attention — and when a callout is unavoidable it points at exactly one element, so a decorative image with no field to set gets its own note rather than being lumped in with its neighbours. Paste it into Figma AI or your AI tool of choice before asking for annotations, or install it as a skill alongside `SKILL.md` at `~/.claude/skills/figma-a11y-annotations/SKILL.md`. Its annotations map one-to-one onto the SwiftUI modifiers in `SKILL.md`, so design and engineering use the same vocabulary.
  51. ## Accessibility Techniques Documentation
  52. ### A
  53. - [A11y-check](iOSswiftUIa11yTechniques/Documentation/A11yCheck.md)
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 84 on GitHub
  54. - [Accessibility Actions](iOSswiftUIa11yTechniques/Documentation/AccessibilityActions.md)
  55. - [Accessibility Custom Content](iOSswiftUIa11yTechniques/Documentation/AccessibilityCustomContent.md)
  56. - [Accessibility Detection](iOSswiftUIa11yTechniques/Documentation/AccessibilityDetection.md)
  57. - [Accessibility Hidden](iOSswiftUIa11yTechniques/Documentation/AccessibilityHidden.md)
  58. - [Accessibility Hint](iOSswiftUIa11yTechniques/Documentation/AccessibilityHint.md)
  59. - [Accessibility Identifier](iOSswiftUIa11yTechniques/Documentation/AccessibilityIdentifier.md)
  60. - [Accessibility Input Labels](iOSswiftUIa11yTechniques/Documentation/AccessibilityInputLabels.md)
  61. - [Accessibility Label](iOSswiftUIa11yTechniques/Documentation/AccessibilityLabel.md)
  62. - [Accessibility Notifications](iOSswiftUIa11yTechniques/Documentation/AccessibilityNotifications.md)
  63. - [Accessibility Representation](iOSswiftUIa11yTechniques/Documentation/AccessibilityRepresentation.md)
  64. - [Accessibility Responds To User Interaction](iOSswiftUIa11yTechniques/Documentation/AccessibilityRespondsToUserInteraction.md)
  65. - [Accessibility Sort Priority](iOSswiftUIa11yTechniques/Documentation/AccessibilitySortPriority.md)
  66. - [Accessibility Traits](iOSswiftUIa11yTechniques/Documentation/AccessibilityTraits.md)
  67. - [Accessibility Value](iOSswiftUIa11yTechniques/Documentation/AccessibilityValue.md)
  68. - [Accordions](iOSswiftUIa11yTechniques/Documentation/Accordions.md)
  69. - [Adjustable Action](iOSswiftUIa11yTechniques/Documentation/AdjustableAction.md)
  70. - [Alerts](iOSswiftUIa11yTechniques/Documentation/Alerts.md)
  71. - [Assistive Access](iOSswiftUIa11yTechniques/Documentation/AssistiveAccess.md)
  72. - [Attributed Strings](iOSswiftUIa11yTechniques/Documentation/AttributedStrings.md)
  73. ### B
  74. - [Buttons](iOSswiftUIa11yTechniques/Documentation/Buttons.md)
  75. ### C
  76. - [Cards](iOSswiftUIa11yTechniques/Documentation/Cards.md)
  77. - [Carousels](iOSswiftUIa11yTechniques/Documentation/Carousels.md)
  78. - [Charts](iOSswiftUIa11yTechniques/Documentation/Charts.md)
  79. - [Checkboxes](iOSswiftUIa11yTechniques/Documentation/Checkboxes.md)
  80. - [Combining Focus](iOSswiftUIa11yTechniques/Documentation/CombiningFocus.md)
  81. - [Confirmation Dialogs](iOSswiftUIa11yTechniques/Documentation/ConfirmationDialogs.md)
  82. - [Containers](iOSswiftUIa11yTechniques/Documentation/Containers.md)
  83. - [Contrast](iOSswiftUIa11yTechniques/Documentation/Contrast.md)
  84. ### D
  85. - [Dark Mode](iOSswiftUIa11yTechniques/Documentation/DarkMode.md)
  86. - [Data Tables](iOSswiftUIa11yTechniques/Documentation/DataTables.md)
  87. - [Date & Time Pickers](iOSswiftUIa11yTechniques/Documentation/DateTimePickers.md)
  88. - [Decorative Images](iOSswiftUIa11yTechniques/Documentation/DecorativeImages.md)
  89. - [Device Orientation](iOSswiftUIa11yTechniques/Documentation/DeviceOrientation.md)
  90. - [Dim Flashing Lights](iOSswiftUIa11yTechniques/Documentation/DimFlashingLights.md)
  91. - [Drag & Drop](iOSswiftUIa11yTechniques/Documentation/DragDrop.md)
  92. - [Dynamic Type](iOSswiftUIa11yTechniques/Documentation/DynamicType.md)
  93. ### E
  94. - [Error Validation](iOSswiftUIa11yTechniques/Documentation/ErrorValidation.md)
  95. - [Escape Action](iOSswiftUIa11yTechniques/Documentation/EscapeAction.md)
  96. ### F
  97. - [Focus Management](iOSswiftUIa11yTechniques/Documentation/FocusManagement.md)
  98. - [Functional Images](iOSswiftUIa11yTechniques/Documentation/FunctionalImages.md)
  99. ### G
  100. - [Grouping Controls](iOSswiftUIa11yTechniques/Documentation/GroupingControls.md)
  101. ### H
  102. - [Headings](iOSswiftUIa11yTechniques/Documentation/Headings.md)
  103. - [Horizontal Scroll Views](iOSswiftUIa11yTechniques/Documentation/HorizontalScrollViews.md)
  104. ### I
  105. - [Images](iOSswiftUIa11yTechniques/Documentation/Images.md)
  106. - [Increase Contrast](iOSswiftUIa11yTechniques/Documentation/IncreaseContrast.md)
  107. - [Informative Images](iOSswiftUIa11yTechniques/Documentation/InformativeImages.md)
  108. - [Input Instructions](iOSswiftUIa11yTechniques/Documentation/InputInstructions.md)
  109. ### L
  110. - [Language](iOSswiftUIa11yTechniques/Documentation/Language.md)
  111. - [Large Content Viewer](iOSswiftUIa11yTechniques/Documentation/LargeContentViewer.md)
  112. - [Links](iOSswiftUIa11yTechniques/Documentation/Links.md)
  113. - [Lists](iOSswiftUIa11yTechniques/Documentation/Lists.md)
  114. ### M
  115. - [Magic Tap](iOSswiftUIa11yTechniques/Documentation/MagicTap.md)
  116. - [Maps](iOSswiftUIa11yTechniques/Documentation/Maps.md)
  117. - [Meaningful Accessible Names](iOSswiftUIa11yTechniques/Documentation/MeaningfulAccessibleNames.md)
  118. - [Menus](iOSswiftUIa11yTechniques/Documentation/Menus.md)
  119. - [Multi-Selection Lists](iOSswiftUIa11yTechniques/Documentation/MultiSelectionLists.md)
  120. ### N
  121. - [Navigation](iOSswiftUIa11yTechniques/Documentation/Navigation.md)
  122. ### P
  123. - [Page Titles](iOSswiftUIa11yTechniques/Documentation/PageTitles.md)
  124. - [Pickers](iOSswiftUIa11yTechniques/Documentation/Pickers.md)
  125. - [Popovers](iOSswiftUIa11yTechniques/Documentation/Popovers.md)
  126. - [Progress Indicators](iOSswiftUIa11yTechniques/Documentation/ProgressIndicators.md)
  127. ### R
  128. - [Radio Buttons](iOSswiftUIa11yTechniques/Documentation/RadioButtons.md)
  129. - [Reading Order](iOSswiftUIa11yTechniques/Documentation/ReadingOrder.md)
  130. - [Reduce Motion](iOSswiftUIa11yTechniques/Documentation/ReduceMotion.md)
  131. - [Reduce Transparency](iOSswiftUIa11yTechniques/Documentation/ReduceTransparency.md)
  132. - [Redundant Entry](iOSswiftUIa11yTechniques/Documentation/RedundantEntry.md)
  133. - [Responsive Layouts](iOSswiftUIa11yTechniques/Documentation/ResponsiveLayouts.md)
  134. - [Rotor](iOSswiftUIa11yTechniques/Documentation/Rotor.md)
  135. ### S
  136. - [Scroll Views](iOSswiftUIa11yTechniques/Documentation/ScrollViews.md)
  137. - [Search Suggestions](iOSswiftUIa11yTechniques/Documentation/SearchSuggestions.md)
  138. - [Segmented Controls](iOSswiftUIa11yTechniques/Documentation/SegmentedControls.md)
  139. - [Sheets](iOSswiftUIa11yTechniques/Documentation/Sheets.md)
  140. - [Show Borders](iOSswiftUIa11yTechniques/Documentation/ShowBorders.md)
  141. - [Sliders](iOSswiftUIa11yTechniques/Documentation/Sliders.md)
  142. - [Smart Invert](iOSswiftUIa11yTechniques/Documentation/SmartInvert.md)
  143. - [Steppers](iOSswiftUIa11yTechniques/Documentation/Steppers.md)
  144. - [SwiftLint](iOSswiftUIa11yTechniques/Documentation/SwiftLint.md)
  145. ### T
  146. - [Tabs](iOSswiftUIa11yTechniques/Documentation/Tabs.md)
  147. - [Text Fields](iOSswiftUIa11yTechniques/Documentation/TextFields.md)
  148. - [TipKit](iOSswiftUIa11yTechniques/Documentation/TipKit.md)
  149. - [Toggles](iOSswiftUIa11yTechniques/Documentation/Toggles.md)
  150. - [Toolbars](iOSswiftUIa11yTechniques/Documentation/Toolbars.md)
  151. - [Touch Target Size](iOSswiftUIa11yTechniques/Documentation/TouchTargetSize.md)
  152. ### V
  153. - [Videos](iOSswiftUIa11yTechniques/Documentation/Videos.md)
  154. - [VoiceOver Automation Testing](iOSswiftUIa11yTechniques/Documentation/VoiceOverAutomationTesting.md)
  155. - [VoiceOver Pronunciation](iOSswiftUIa11yTechniques/Documentation/VoiceOverPronunciation.md)
  156. ### W
  157. - [Web View Dynamic Type](iOSswiftUIa11yTechniques/Documentation/WebViewDynamicType.md)
  158. ### X
  159. - [XCTest Accessibility Testing](iOSswiftUIa11yTechniques/Documentation/XCTestAccessibility.md)
  160. ## Contributor Guide
  161. 1. Before contributing to this CVS Health sponsored project, you will need to sign the associated [Contributor License Agreement](https://forms.office.com/r/tvFjdsisT2).
  162. 2. See [contributing](CONTRIBUTING.md) page.
  163. ## License
  164. iOS SwiftUI Accessibility Techniques is licensed under under the Apache License, Version 2.0. See LICENSE file for more information.
  165. Copyright 2023-2026 CVS Health and/or one of its affiliates
  166. Licensed under the Apache License, Version 2.0 (the "License");
  167. you may not use this file except in compliance with the License.
  168. You may obtain a copy of the License at
  169. [http://www.apache.org/licenses/LICENSE-2.0]()
  170. Unless required by applicable law or agreed to in writing, software
  171. distributed under the License is distributed on an "AS IS" BASIS,
  172. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  173. See the License for the specific language governing permissions and
  174. limitations under the License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.