iOS SwiftUI Accessibility Techniques

This repo also includes a11y-check, a static analysis tool that scans your Swift/SwiftUI source code for accessibility issues — 45 rules across 24 WCAG 2.2 criteria, with scoring, auto-fix, and CI integration.

Download the iOS app from the App Store.

Read the blog post, Announcing the iOS SwiftUI Accessibility Techniques Open Source Project.

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.

Building this project

To see a11y-check accessibility warnings and errors inline in Xcode when you build, install the tool first:

brew tap cvs-health/ios-swiftui-accessibility-techniques https://github.com/cvs-health/ios-swiftui-accessibility-techniques.git
brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check

Without this step the project still builds and runs, but the a11y-check build phase is silently skipped.

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.

A11y Checker (a11y-check)

Static analysis for SwiftUI accessibility issues, mapped to WCAG 2.2 success criteria. 45 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.

Check your own iOS app

1. Install the tool once (choose one method below).
2. Run it: Open Terminal, go to your app’s project folder (the folder that contains your Swift files), and run:

cd /path/to/YourApp
   a11y-check .

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. Tip: Use a11y-check . --only error to show only errors, or a11y-check --list-rules to see all rules.

Install via Homebrew (easiest on any Mac):

brew tap cvs-health/ios-swiftui-accessibility-techniques https://github.com/cvs-health/ios-swiftui-accessibility-techniques.git
brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check

Then from your app folder: a11y-check .

To verify it installed: a11y-check --version To update later: brew uninstall a11y-check && brew install --HEAD cvs-health/ios-swiftui-accessibility-techniques/a11y-check

Or build from source: Requires Swift 5.9+ and macOS 13+ (Xcode or Swift.org toolchain). From a terminal:

git clone https://github.com/cvs-health/ios-swiftui-accessibility-techniques.git
cd ios-swiftui-accessibility-techniques/a11y-check
swift build

To run the checker on your app: from anywhere use the full path to the binary, with your app’s folder as the argument:

/path/to/ios-swiftui-accessibility-techniques/a11y-check/.build/debug/a11y-check /path/to/YourApp

(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.

See a11y-check/README.md for full usage, options, and CI integration.

Use with AI editors (MCP): An MCP server 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.

AI coding skill: A SKILL.md file is included that teaches AI coding assistants (Claude Code, CVS Code, Cursor, etc.) how to write accessible SwiftUI code. Copy it to your ~/.claude/skills/ directory or your editor's skills folder and it will automatically enforce WCAG 2.2 accessible coding patterns — labels, traits, Dynamic Type, contrast, touch targets, focus management, and more.

AI design annotation skill: A 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 banned-vocabulary table, exact grammar per type, a worked before/after example, and a 25-step self-check. Four 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 or control types (pick the right Figma component instead, so there is nothing to annotate), never annotate the default top-to-bottom reading order, and keep the set to the bare minimum of image names plus decorative marking. 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. Its annotations map one-to-one onto the SwiftUI modifiers in SKILL.md, so design and engineering use the same vocabulary.

Accessibility Techniques Documentation

A

• A11y-check
• Accessibility Actions
• Accessibility Custom Content
• Accessibility Detection
• Accessibility Hidden
• Accessibility Hint
• Accessibility Identifier
• Accessibility Input Labels
• Accessibility Label
• Accessibility Notifications
• Accessibility Representation
• Accessibility Responds To User Interaction
• Accessibility Sort Priority
• Accessibility Traits
• Accessibility Value
• Accordions
• Adjustable Action
• Alerts
• Assistive Access
• Attributed Strings

B

• Buttons

C

• Cards
• Carousels
• Charts
• Checkboxes
• Combining Focus
• Confirmation Dialogs
• Containers
• Contrast

D

• Dark Mode
• Data Tables
• Date & Time Pickers
• Decorative Images
• Device Orientation
• Dim Flashing Lights
• Drag & Drop
• Dynamic Type

E

• Error Validation
• Escape Action

F

• Focus Management
• Functional Images

G

• Grouping Controls

H

• Headings
• Horizontal Scroll Views

I

• Images
• Increase Contrast
• Informative Images
• Input Instructions

L

• Language
• Large Content Viewer
• Links
• Lists

M

• Magic Tap
• Maps
• Meaningful Accessible Names
• Menus
• Multi-Selection Lists

N

• Navigation

P

• Page Titles
• Pickers
• Popovers
• Progress Indicators

R

• Radio Buttons
• Reading Order
• Reduce Motion
• Reduce Transparency
• Redundant Entry
• Responsive Layouts
• Rotor

S

• Scroll Views
• Search Suggestions
• Segmented Controls
• Sheets
• Show Borders
• Sliders
• Smart Invert
• Steppers
• SwiftLint

T

• Tabs
• Text Fields
• TipKit
• Toggles
• Toolbars
• Touch Target Size

V

• Videos
• VoiceOver Automation Testing
• VoiceOver Pronunciation

W

• Web View Dynamic Type

X

• XCTest Accessibility Testing

Contributor Guide

1. Before contributing to this CVS Health sponsored project, you will need to sign the associated Contributor License Agreement.
2. See contributing page.

License

Copyright 2023-2026 CVS Health and/or one of its affiliates

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0]()

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.