iOS SwiftUI Accessibility

Category: Data & AI | Uploader: cvs-health | Downloads: 0 | Version: v1.0（Latest）

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

Changelog: Source: GitHub https://github.com/cvs-health/ios-swiftui-accessibility-techniques

Directory Structure

Current level: tree/main/

📁 .claude/
- 📄 settings.json 580 B
📁 .github/
- 📁 workflows/
  - 📄 accessibility-snapshots.yml 662 B
  - 📄 swiftlint.yml 8.0 KB
- 📄 pull_request_template.md 709 B
📁 .vscode/
- 📄 launch.json 826 B
📁 A11yAgent/
- 📁 .github/
  - 📁 workflows/
    
    📄 a11y-check.yml 5.9 KB
- 📁 homebrew/
  - 📄 a11y-check.rb 1.4 KB
- 📁 mcp-server/
  - 📁 src/
    
    📄 index.ts 9.6 KB
  - 📄 .gitignore 41 B
  - 📄 claude-desktop-mcp-example.json 327 B
  - 📄 cursor-mcp-example.json 387 B
  - 📄 package-lock.json 56.4 KB
  - 📄 package.json 722 B
  - 📄 README.md 8.6 KB
  - 📄 tsconfig.json 297 B
  - 📄 vscode-mcp-example.json 359 B
  - 📄 windsurf-mcp-example.json 327 B
- 📁 Plugins/
  - 📁 A11yCheckBuildPlugin/
    
    📄 A11yCheckBuildPlugin.swift 2.2 KB
  - 📁 A11yCheckPlugin/
    
    📄 A11yCheckPlugin.swift 2.1 KB
- 📁 Sources/
  - 📁 A11yAgentCLI/
    
    📄 A11yCheck.swift 18.8 KB
    
    📄 BuildInfo.swift 50 B
  - 📁 A11yAgentCore/
    
    📁 Configuration/
    
    📄 A11yConfig.swift 7.6 KB
    
    📁 Models/
    
    📄 A11yDiagnostic.swift 3.2 KB
    
    📄 A11yScore.swift 5.4 KB
    
    📁 Rules/
    
    📄 A11yRule.swift 3.7 KB
    
    📄 AccessibilityHiddenRules.swift 3.1 KB
    
    📄 AnimationRules.swift 8.3 KB
    
    📄 ButtonRules.swift 8.6 KB
    
    📄 ColorContrastRule.swift 5.1 KB
    
    📄 DarkModeRules.swift 2.7 KB
    
    📄 DynamicTypeRules.swift 3.0 KB
    
    📄 FocusReturnRules.swift 9.7 KB
    
    📄 FormControlRules.swift 13.8 KB
    
    📄 GestureAlternativeRules.swift 4.8 KB
    
    📄 GroupingRules.swift 6.0 KB
    
    📄 HeadingRules.swift 6.7 KB
    
    📄 HintRules.swift 8.5 KB
    
    📄 ImageRules.swift 7.4 KB
    
    📄 InputPurposeRule.swift 9.2 KB
    
    📄 LabelInNameRules.swift 3.4 KB
    
    📄 LinkRules.swift 5.8 KB
    
    📄 OrientationRules.swift 4.5 KB
    
    📄 PageTitleRules.swift 3.3 KB
    
    📄 TimingRules.swift 3.2 KB
    
    📄 ToggleRules.swift 2.9 KB
    
    📄 TouchTargetRules.swift 5.7 KB
    
    📄 TraitRules.swift 1.6 KB
    
    📁 Utilities/
    
    📄 AssetCatalogParser.swift 3.6 KB
    
    📄 ColorParser.swift 7.0 KB
    
    📄 ContrastCalculator.swift 1.7 KB
    
    📁 Visitors/
    
    📄 GestureVisitor.swift 3.6 KB
    
    📄 ModifierCollector.swift 6.3 KB
    
    📄 ViewHierarchyVisitor.swift 7.6 KB
    
    📄 AutoFixer.swift 5.4 KB
    
    📄 BadgeGenerator.swift 3.0 KB
    
    📄 Baseline.swift 3.4 KB
    
    📄 DiffFilter.swift 4.4 KB
    
    📄 Formatters.swift 10.2 KB
    
    📄 HTMLFormatter.swift 41.6 KB
    
    📄 InlineSuppressionFilter.swift 2.9 KB
    
    📄 RuleDocsGenerator.swift 2.7 KB
    
    📄 RuleRegistry.swift 6.9 KB
    
    📄 SARIFFormatter.swift 4.6 KB
    
    📄 ScoreCalculator.swift 9.9 KB
    
    📄 ScoreFormatter.swift 7.8 KB
    
    📄 TrendTracker.swift 9.1 KB
    
    📄 ViewScorer.swift 6.5 KB
  - 📁 A11yAgentLLM/
    
    📄 LLMProvider.swift 6.6 KB
- 📁 Tests/
  - 📁 A11yAgentCoreTests/
    
    📁 Fixtures/
    
    📄 ButtonFixtures.swift 1.6 KB
    
    📄 HeadingFixtures.swift 573 B
    
    📄 ImageFixtures.swift 1.0 KB
    
    📄 MiscFixtures.swift 1.7 KB
    
    📄 A11yAgentCoreTests.swift 37.6 KB
- 📄 a11y-badge.svg 1.0 KB
- 📄 generate-build-info.sh 317 B
- 📄 Package.resolved 848 B
- 📄 Package.swift 2.4 KB
- 📄 README.md 32.7 KB
📁 Formula/
- 📄 a11y-check.rb 1.2 KB
📁 iOSswiftUIa11yTechniques/
- 📁 a11yTechniques Watch App/
  - 📁 Assets.xcassets/
    
    📁 AccentColor.colorset/
    
    📄 Contents.json 123 B
    
    📁 AppIcon.appiconset/
    
    📄 Contents.json 318 B
    
    📄 swiftUIa11yIcon.jpg 58.2 KB
    
    📁 barcode.viewfinder.symbolset/
    
    📄 barcode.viewfinder.svg 19.3 KB
    
    📄 Contents.json 169 B
    
    📁 get10off.imageset/
    
    📄 Contents.json 306 B
    
    📄 get10off.png 37.3 KB
    
    📁 newspaper.symbolset/
    
    📄 Contents.json 160 B
    
    📄 newspaper.svg 19.4 KB
    
    📄 Contents.json 63 B
  - 📁 Preview Content/
    
    📁 Preview Assets.xcassets/
    
    📄 Contents.json 63 B
  - 📄 a11yTechniquesApp.swift 266 B
  - 📄 AccessibilitySortPriorityWatch.swift 4.2 KB
  - 📄 CombiningFocusWatch.swift 5.5 KB
  - 📄 ContentViewWatch.swift 2.5 KB
  - 📄 DecorativeImagesWatch.swift 7.1 KB
  - 📄 FunctionalImagesWatch.swift 9.0 KB
  - 📄 HeadingsWatch.swift 8.8 KB
  - 📄 InformativeImagesWatch.swift 7.8 KB
  - 📄 PickersWatch.swift 8.5 KB
  - 📄 SheetsWatch.swift 6.4 KB
  - 📄 TabsWatch.swift 13.9 KB
  - 📄 TargetSizeWatch.swift 6.4 KB
  - 📄 Techniques.swift 561 B
  - 📄 TextFieldsWatch.swift 13.7 KB
- 📁 a11yTechniques Watch AppTests/
  - 📄 a11yTechniques_Watch_AppTests.swift 363 B
- 📁 a11yTechniques Watch AppUITests/
  - 📄 a11yTechniques_Watch_AppUITests.swift 1.4 KB
  - 📄 a11yTechniques_Watch_AppUITestsLaunchTests.swift 865 B
- 📁 Documentation/
  - 📄 A11yCheck.md 9.4 KB
  - 📄 AccessibilityActions.md 1.6 KB
  - 📄 AccessibilityDetection.md 1.6 KB
  - 📄 AccessibilityHidden.md 1.5 KB
  - 📄 AccessibilityHint.md 1.9 KB
  - 📄 AccessibilityIdentifier.md 1.4 KB
  - 📄 AccessibilityInputLabels.md 1.4 KB
  - 📄 AccessibilityLabel.md 1.8 KB
  - 📄 AccessibilityNotifications.md 1.6 KB
  - 📄 AccessibilityRepresentation.md 1.3 KB
  - 📄 AccessibilityRespondsToUserInteraction.md 1.5 KB
  - 📄 AccessibilitySortPriority.md 1.4 KB
  - 📄 AccessibilityTraits.md 1.4 KB
  - 📄 AccessibilityValue.md 1.7 KB
  - 📄 Accordions.md 1.7 KB
  - 📄 AdjustableAction.md 1.5 KB
  - 📄 Alerts.md 1.8 KB
  - 📄 AssistiveAccess.md 1.6 KB
  - 📄 AttributedStrings.md 1.4 KB
  - 📄 Buttons.md 1.7 KB
  - 📄 Cards.md 1.5 KB
  - 📄 Carousels.md 1.5 KB
  - 📄 Charts.md 1.4 KB
  - 📄 Checkboxes.md 1.7 KB
  - 📄 CombiningFocus.md 1.6 KB
  - 📄 ConfirmationDialogs.md 1.7 KB
  - 📄 Containers.md 1.6 KB
  - 📄 Contrast.md 2.1 KB
  - 📄 DarkMode.md 1.5 KB
  - 📄 DataTables.md 2.0 KB
  - 📄 DateTimePickers.md 2.4 KB
  - 📄 DecorativeImages.md 1.5 KB
  - 📄 DeviceOrientation.md 1.4 KB
  - 📄 DimFlashingLights.md 1.4 KB
  - 📄 DragDrop.md 2.0 KB
  - 📄 DynamicType.md 2.5 KB
  - 📄 ErrorValidation.md 2.0 KB
  - 📄 EscapeAction.md 1.3 KB
  - 📄 FocusManagement.md 2.1 KB
  - 📄 FunctionalImages.md 1.6 KB
  - 📄 GroupingControls.md 1.6 KB
  - 📄 Headings.md 2.4 KB
  - 📄 HorizontalScrollViews.md 1.3 KB
  - 📄 Images.md 1.4 KB
  - 📄 IncreaseContrast.md 1.5 KB
  - 📄 InformativeImages.md 1.6 KB
  - 📄 InputInstructions.md 1.4 KB
  - 📄 Language.md 1.8 KB
  - 📄 LargeContentViewer.md 1.5 KB
  - 📄 Links.md 2.5 KB
  - 📄 Lists.md 1.4 KB
  - 📄 MagicTap.md 1.2 KB
  - 📄 Maps.md 1.5 KB
  - 📄 MeaningfulAccessibleNames.md 1.8 KB
  - 📄 Menus.md 1.5 KB
  - 📄 MultiSelectionLists.md 1.7 KB
  - 📄 Navigation.md 1.5 KB
  - 📄 PageTitles.md 1.1 KB
  - 📄 Pickers.md 2.4 KB
  - 📄 Popovers.md 1.8 KB
  - 📄 ProgressIndicators.md 1.6 KB
  - 📄 RadioButtons.md 2.0 KB
  - 📄 ReadingOrder.md 1.7 KB
  - 📄 ReduceMotion.md 1.4 KB
  - 📄 ReduceTransparency.md 1.6 KB
  - 📄 RedundantEntry.md 1.4 KB
  - 📄 ResponsiveLayouts.md 1.7 KB
  - 📄 Rotor.md 1.3 KB
  - 📄 ScrollViews.md 1.2 KB
  - 📄 SearchSuggestions.md 1.2 KB
  - 📄 SegmentedControls.md 1.4 KB
  - 📄 Sheets.md 2.2 KB
  - 📄 Sliders.md 1.8 KB
  - 📄 SmartInvert.md 1.3 KB
  - 📄 Steppers.md 1.4 KB
  - 📄 SwiftLint.md 1.4 KB
  - 📄 Tabs.md 2.5 KB
  - 📄 TextFields.md 2.3 KB
  - 📄 TipKit.md 1.2 KB
  - 📄 Toggles.md 1.7 KB
  - 📄 Toolbars.md 1.5 KB
  - 📄 TouchTargetSize.md 1.5 KB
  - 📄 Videos.md 2.4 KB
  - 📄 VoiceOverPronunciation.md 1.6 KB
  - 📄 XCTestAccessibility.md 4.9 KB
- 📁 iOSswiftUIa11yTechniques/
  - 📁 Assets.xcassets/
    
    📁 AccentColor.colorset/
    
    📄 Contents.json 701 B
    
    📁 AppIcon.appiconset/
    
    📄 Contents.json 219 B
    
    📄 swiftUIa11yIcon.jpg 58.2 KB
    
    📁 barber-shop.imageset/
    
    📄 barber-shop.jpg 316.5 KB
    
    📄 Contents.json 309 B
    
    📁 barcode.viewfinder.symbolset/
    
    📄 barcode.viewfinder.svg 19.3 KB
    
    📄 Contents.json 169 B
    
    📁 carousel.imageset/
    
    📄 carousel.jpg 453.3 KB
    
    📄 Contents.json 306 B
    
    📁 get10off.imageset/
    
    📄 Contents.json 306 B
    
    📄 get10off.png 37.3 KB
    
    📁 mardi-gras.imageset/
    
    📄 Contents.json 308 B
    
    📄 mardi-gras.jpg 310.7 KB
    
    📁 newspaper.symbolset/
    
    📄 Contents.json 160 B
    
    📄 newspaper.svg 19.4 KB
    
    📁 stained-glass.imageset/
    
    📄 Contents.json 311 B
    
    📄 stained-glass.jpg 1.1 MB
    
    📄 Contents.json 63 B
  - 📁 Preview Content/
    
    📁 Preview Assets.xcassets/
    
    📄 Contents.json 63 B
  - 📁 Prototypes/
    
    📄 ContactAtlanta.swift 10.3 KB
    
    📄 ContactAustin.swift 10.2 KB
    
    📄 ContactBoston.swift 13.7 KB
    
    📄 ContactFormView.swift 1.5 KB
    
    📄 ContactOrlando.swift 10.8 KB
    
    📄 ContactReno.swift 9.8 KB
    
    📄 ContactSeattle.swift 9.7 KB
    
    📄 DOBpicker.swift 3.0 KB
    
    📄 MarkdownView.swift 5.6 KB
    
    📄 PrototypesView.swift 1.9 KB
    
    📄 SignUp0.swift 16.2 KB
    
    📄 SignUp1.swift 31.8 KB
    
    📄 SignUp2.swift 28.8 KB
    
    📄 SignUpA.swift 10.9 KB
    
    📄 SignUpB.swift 4.9 KB
    
    📄 SignUpC.swift 5.3 KB
    
    📄 SignUpD.swift 3.4 KB
    
    📄 ThankYou.swift 1.3 KB
  - 📄 A11yCheckView.swift 43.3 KB
  - 📄 A11yEnhancementsView.swift 2.2 KB
  - 📄 AccessibilityHidden.swift 5.5 KB
  - 📄 AccessibilityHintView.swift 9.2 KB
  - 📄 AccessibilityIdentifier.swift 4.1 KB
  - 📄 AccessibilityLabelView.swift 8.2 KB
  - 📄 AccessibilityNotificationsView.swift 4.6 KB
  - 📄 AccessibilityRepresentationView.swift 7.8 KB
  - 📄 AccessibilityRespondsToUserInteraction.swift 4.5 KB
  - 📄 AccessibilitySortPriority.swift 4.2 KB
  - 📄 AccessibilityTraitsView.swift 6.4 KB
  - 📄 AccessibilityValueView.swift 11.0 KB
  - 📄 AccordionsView.swift 6.9 KB
  - 📄 ActionsView.swift 18.4 KB
  - 📄 AdjustableActionView.swift 6.5 KB
  - 📄 AlertsView.swift 5.2 KB
  - 📄 AssistiveAccessView.swift 3.3 KB
  - 📄 ATdetectionView.swift 7.4 KB
  - 📄 AttributedStringsView.swift 5.2 KB
  - 📄 ButtonsView.swift 10.8 KB
  - 📄 CardsView.swift 21.6 KB
  - 📄 CarouselView.swift 31.2 KB
  - 📄 CarouselViewBad.swift 14.3 KB
  - 📄 ChartsView.swift 9.9 KB
  - 📄 CheckboxesView.swift 10.2 KB
  - 📄 CombiningFocusView.swift 5.1 KB
  - 📄 ConfirmationDialogsView.swift 5.0 KB
  - 📄 ContainersView.swift 6.9 KB
  - 📄 ContentView.swift 9.5 KB
  - 📄 ContrastView.swift 9.6 KB
  - 📄 DarkModeView.swift 6.8 KB
  - 📄 DataTablesView.swift 16.8 KB
  - 📄 DateTimePickers.swift 9.0 KB
  - 📄 DecorativeView.swift 6.3 KB
  - 📄 DetailView.swift 1.0 KB
  - 📄 DeviceOrientationBad.swift 3.0 KB
  - 📄 DeviceOrientationGood.swift 2.4 KB
  - 📄 DeviceOrientationView.swift 3.4 KB
  - 📄 DimFlashingLightsView.swift 6.4 KB
  - 📄 DragDropView.swift 9.9 KB
  - 📄 DynamicTypeView.swift 14.1 KB
  - 📄 ErrorValidationView.swift 25.1 KB
  - 📄 EscapeView.swift 6.7 KB
  - 📄 FocusManagementView.swift 8.6 KB
  - 📄 FunctionalView.swift 7.8 KB
  - 📄 GroupingControlsView.swift 7.3 KB
  - 📄 HeadingsView.swift 11.0 KB
  - 📄 HomeTabView.swift 3.2 KB
  - 📄 HorizontalScrollView.swift 9.9 KB
  - 📄 ImagesView.swift 1.3 KB
  - 📄 IncreaseContrastView.swift 4.7 KB
  - 📄 Info.plist 352 B
  - 📄 InformativeView.swift 13.0 KB
  - 📄 InputInstructionsView.swift 7.3 KB
  - 📄 InputLabelsView.swift 5.2 KB
  - 📄 iOSswiftUIa11yTechniquesApp.swift 1.2 KB
  - 📄 LanguageOfPageBadView.swift 2.2 KB
  - 📄 LanguageOfPageGoodView.swift 2.2 KB
  - 📄 LanguageView.swift 6.3 KB
  - 📄 LargeContentViewerView.swift 6.8 KB
  - 📄 LinksView.swift 12.5 KB
  - 📄 ListsView.swift 3.8 KB
  - 📄 MagicTapView.swift 2.6 KB
  - 📄 MapView.swift 7.6 KB
  - 📄 MeaningfulAccessibleNamesView.swift 9.7 KB
  - 📄 MenusView.swift 12.5 KB
  - 📄 MessagesTabView.swift 2.4 KB
  - 📄 MultiSelectionListView.swift 10.7 KB
  - 📄 NavigationLinkView.swift 7.4 KB
  - 📄 PageTitleBad.swift 1.2 KB
  - 📄 PageTitleGood.swift 1.2 KB
  - 📄 PageTitlesView.swift 4.6 KB
  - 📄 PickersView.swift 12.5 KB
  - 📄 PopoversView.swift 6.1 KB
  - 📄 ProgressIndicatorsView.swift 7.4 KB
  - 📄 RadioButtonsView.swift 13.0 KB
  - 📄 ReadingOrderView.swift 7.0 KB
  - 📄 ReduceMotionView.swift 5.6 KB
  - 📄 ReduceTransparencyView.swift 4.1 KB
  - 📄 RedundantEntryView.swift 16.1 KB
  - 📄 ResponsiveLayoutsView.swift 15.7 KB
  - 📄 RotorView.swift 3.9 KB
  - 📄 ScrollViews.swift 3.4 KB
  - 📄 SearchSuggestionsView.swift 8.1 KB
  - 📄 SegmentedControlsView.swift 4.5 KB
  - 📄 SheetsView.swift 15.9 KB
  - 📄 SlidersView.swift 8.4 KB
  - 📄 SmartInvertView.swift 7.2 KB
  - 📄 SteppersView.swift 6.6 KB
  - 📄 SwiftLintView.swift 6.0 KB
  - 📄 TableView.swift 1.9 KB
  - 📄 TabsGoodView.swift 1.4 KB
  - 📄 TabsView.swift 12.5 KB
  - 📄 Techniques.swift 3.5 KB
  - 📄 TextEditorView.swift 1.5 KB
  - 📄 TextFieldsFocusManagement.swift 7.6 KB
  - 📄 TextFieldsView.swift 17.2 KB
  - 📄 TipKitView.swift 8.9 KB
  - 📄 TogglesView.swift 16.8 KB
  - 📄 ToolbarView.swift 10.0 KB
  - 📄 TouchTargetSize.swift 6.5 KB
  - 📄 UIControlsView.swift 3.4 KB
  - 📄 UserPreferencesView.swift 1.6 KB
  - 📄 VideosView.swift 7.4 KB
  - 📄 VoiceOverAnnouncementDelayView.swift 10.2 KB
  - 📄 VoiceOverPronunciationView.swift 5.5 KB
  - 📄 WebView.swift 2.1 KB
- 📁 iOSswiftUIa11yTechniques.xcodeproj/
  - 📁 project.xcworkspace/
    
    📁 xcshareddata/
    
    📁 swiftpm/
    
    📄 Package.resolved 1.8 KB
    
    📄 IDEWorkspaceChecks.plist 238 B
    
    📄 contents.xcworkspacedata 135 B
  - 📁 xcshareddata/
    
    📁 xcschemes/
    
    📄 a11yTechniques Watch App.xcscheme 4.6 KB
    
    📄 FastlaneSnapshotsUITests.xcscheme 1.9 KB
    
    📄 iOSswiftUIa11yTechniques.xcscheme 3.5 KB
    
    📄 iOSswiftUIa11yTechniquesTests.xcscheme 1.9 KB
  - 📄 project.pbxproj 117.4 KB
- 📁 iOSswiftUIa11yTechniquesTests/
  - 📁 __Snapshots__/
    
    📁 AccessibilitySnapshotTests/
    
    📄 testButtonsViewAccessibilitySnapshot.1.png 715.3 KB
    
    📄 testErrorValidationViewAccessibilitySnapshot.1.png 701.9 KB
    
    📄 testInformativeViewAccessibilitySnapshot.1.png 892.1 KB
  - 📄 AccessibilitySnapshotTests.swift 2.2 KB
- 📁 iOSswiftUIa11yTechniquesUITests/
  - 📄 iOSswiftUIa11yTechniquesUITests.swift 40.3 KB
  - 📄 iOSswiftUIa11yTechniquesUITestsLaunchTests.swift 1.3 KB
- 📄 Gemfile.lock 6.0 KB
📄 .gitignore 2.2 KB
📄 .swiftlint.yml 1.1 KB
📄 a11y-check-report.html 742.1 KB
📄 CHANGELOG.md 6.7 KB
📄 CLAUDE.md 2.0 KB
📄 CONTRIBUTING.md 1.3 KB
📄 LICENSE 11.1 KB
📄 Package.swift 2.6 KB
📄 PRESENTATION.html 16.0 KB
📄 README.md 12.4 KB
📄 SKILL.md 12.2 KB
📄 xcode-a11y-check.jpg 997.4 KB

SKILL.md

---
name: iOS SwiftUI Accessibility
description: Enforces WCAG 2.2 accessible coding patterns when writing SwiftUI — labels, traits, Dynamic Type, contrast, touch targets, focus management, and more. Based on the ios-swiftui-accessibility-techniques project with 31 static analysis rules across 17 WCAG criteria.
---

# iOS SwiftUI Accessibility Coding Rules

Follow these rules when writing or reviewing SwiftUI code. Each rule maps to a WCAG 2.2 success criterion.

## Images (WCAG 1.1.1)

- Every `Image(systemName:)` and `Image("name")` must have `.accessibilityLabel("description")` describing what the image conveys.
- For decorative images that add no information, use `Image(decorative:)` or add `.accessibilityHidden(true)`.
- Never include words like "image", "icon", "graphic", or "button" in an `.accessibilityLabel` — VoiceOver already announces the element's trait.
- Describe what the image shows, not the file name or technical details.

```swift
// Good
Image(systemName: "heart.fill")
    .accessibilityLabel("Favorite")

// Good — decorative
Image(decorative: "background-pattern")

// Bad — no label
Image(systemName: "trash")

// Bad — includes role
Image(systemName: "heart.fill")
    .accessibilityLabel("Heart icon")
```

## Buttons (WCAG 4.1.2)

- Icon-only `Button` views must have `.accessibilityLabel("action")` describing what the button does.
- Never include "button" in the `.accessibilityLabel` — VoiceOver announces the button trait automatically, so users hear "Delete button, button".
- Prefer `Button` over `.onTapGesture`. If you must use `.onTapGesture`, add `.accessibilityAddTraits(.isButton)` so VoiceOver announces it as a button.
- Visually disabled buttons (using `.opacity()` or `.tint(.gray)`) must also use `.disabled(true)` so assistive technology knows the button is disabled.

```swift
// Good
Button(action: { deleteItem() }) {
    Image(systemName: "trash")
}
.accessibilityLabel("Delete")

// Bad — label includes role
Button(action: {}) {
    Image(systemName: "trash")
}
.accessibilityLabel("Delete button")

// Bad — looks disabled but isn't semantically
Button("Submit", action: {})
    .opacity(0.5)
// Fix:
Button("Submit", action: {})
    .disabled(true)
```

## Accessibility Label (WCAG 4.1.2, 2.5.3)

- Every interactive control must have a meaningful accessible name — either from visible text content or `.accessibilityLabel`.
- Labels should be concise (ideally 1–3 words), begin capitalized, and not end with a period.
- 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).
- Never include the control type in the label ("button", "tab", "link", "image").

```swift
// Good — specific label includes visible text first
Button("Add to cart") {}
    .accessibilityLabel("Add to cart, Wireless Headphones")

// Bad — accessible name doesn't contain visible text
Button("Add to cart") {}
    .accessibilityLabel("Purchase Wireless Headphones")
```

## Accessibility Value (WCAG 4.1.2)

- Use `.accessibilityValue` on custom controls to convey their current state or value (e.g., "3 out of 5", "Step 2 of 4", "enabled"/"disabled").
- Pair adjustable custom controls with `.accessibilityAdjustableAction` so VoiceOver users can swipe up/down to change the value.
- Use `.accessibilityValue` on tab bar items to convey badge notification counts (e.g., "3 notifications").

```swift
// Good — custom star rating
HStack {
    ForEach(1...5, id: \.self) { star in
        Image(systemName: star <= rating ? "star.fill" : "star")
    }
}
.accessibilityElement(children: .ignore)
.accessibilityLabel("Rating")
.accessibilityValue("\(rating) out of 5")
.accessibilityAdjustableAction { direction in
    switch direction {
    case .increment: rating = min(5, rating + 1)
    case .decrement: rating = max(1, rating - 1)
    @unknown default: break
    }
}
```

## Accessibility Hint (WCAG 3.3.2)

- Hints are optional — VoiceOver users can turn them off. Only add a hint when the result of activating an element is not obvious from the label alone.
- Use third-person singular verb describing the result: "Adds this item to your favorites." NOT "Add this item to your favorites."
- Never mention gestures ("tap", "double tap", "swipe") — VoiceOver already tells users how to interact.
- Never repeat the label text or include the control type ("button", "link").
- Begin capitalized, end with a period.

```swift
// Good
Button(action: { toggleFavorite() }) {
    Image(systemName: "heart")
}
.accessibilityLabel("Favorite")
.accessibilityHint("Adds this item to your favorites.")

// Bad — mentions gesture and control type
.accessibilityHint("Double tap to add this item to your favorites.")

// Bad — repeats label
.accessibilityHint("Favorite")
```

## Headings (WCAG 1.3.1)

- Add `.accessibilityAddTraits(.isHeader)` to all heading-styled text (`.title`, `.headline`, `.subheadline`, etc.) so VoiceOver users can navigate by headings using the Rotor.
- Never fake a heading by putting "heading" in the `.accessibilityLabel` — it won't appear in the Rotor.
- Use `.accessibilityHeading(.h1)` through `.h6` together with `.accessibilityAddTraits(.isHeader)` to set heading levels. Don't skip levels.

```swift
// Good
Text("Settings")
    .font(.title)
    .accessibilityAddTraits(.isHeader)

// Bad — fake heading
Text("Settings")
    .font(.title)
    .accessibilityLabel("Settings heading")
```

## Traits (WCAG 4.1.2)

- Use the correct accessibility trait so assistive technology announces the element's role:
  - `.isButton` — interactive elements that perform an action
  - `.isLink` — elements that navigate to a URL or another view
  - `.isHeader` — section headings
  - `.isSelected` — selected items in a list or tab
  - `.isImage` — informative images
- Prefer `Button` and `Link` views (which set traits automatically) over manual `.onTapGesture` + `.accessibilityAddTraits`.

## Dynamic Type (WCAG 1.4.4)

- Use text styles (`.title`, `.body`, `.caption`, `.headline`, etc.) instead of `.font(.system(size: N))` so text scales with the user's preferred size.
- Never use `.lineLimit(1)` — it truncates text at larger sizes.
- Wrap text content in a `ScrollView` so it remains accessible when enlarged.
- 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.
- Use `axis: .vertical` on `TextField` so entered text wraps instead of truncating.

```swift
// Good
Text("Welcome")
    .font(.largeTitle)
    .dynamicTypeSize(...DynamicTypeSize.xxxLarge)

// Bad — fixed size, won't scale
Text("Welcome")
    .font(.system(size: 34))
```

## Color and Contrast (WCAG 1.4.3, 1.4.11)

- 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.
- Text contrast ratio must be at least 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold).
- Non-text elements (icons, borders, focus indicators) must have at least 3:1 contrast ratio.
- Support the Increase Contrast accessibility setting.

```swift
// Good — adapts to dark mode
Text("Hello")
    .foregroundColor(.primary)

// Bad — won't adapt to dark mode
Text("Hello")
    .foregroundColor(.black)
```

## Touch Target Size (WCAG 2.5.8)

- Touch targets must be at least 24x24pt (WCAG 2.2 Level AA minimum). Use `.frame(minWidth: 24, minHeight: 24)` on icon-only buttons.
- Apple recommends 44x44pt for comfortable tapping. Inline targets within a line of text are exempt.

```swift
// Good
Button(action: {}) {
    Image(systemName: "xmark")
        .frame(minWidth: 44, minHeight: 44)
}
```

## Form Controls (WCAG 1.3.5, 3.3.2, 4.1.2)

- `TextField`, `SecureField`, `Slider`, `Stepper`, `Picker`, and `Toggle` all need visible labels. Use the built-in label parameter or add `.accessibilityLabel`.
- Never use `.labelsHidden()` without providing an `.accessibilityLabel`.
- Add `.textContentType(.emailAddress)`, `.textContentType(.password)`, etc. to text fields so autofill works correctly.

```swift
// Good — visible label above the text field
Text("Email")
TextField("Email", text: $email)
    .textContentType(.emailAddress)

// Bad — hidden label, no accessibility label
TextField("", text: $email)
    .labelsHidden()
```

## Navigation and Page Titles (WCAG 2.4.2, 2.4.3)

- Every view inside a `NavigationStack` must have `.navigationTitle("Page Title")` so VoiceOver announces the page when it appears.
- After dismissing a `.sheet()`, `.fullScreenCover()`, `.alert()`, or `.popover()`, return VoiceOver focus to the trigger element using `@AccessibilityFocusState`.

```swift
@AccessibilityFocusState private var isTriggerFocused: Bool

Button("Show Details") { showSheet = true }
    .accessibilityFocused($isTriggerFocused)
    .sheet(isPresented: $showSheet, onDismiss: {
        isTriggerFocused = true
    }) {
        DetailView()
    }
```

## Gestures (WCAG 2.1.1, 2.5.1)

- Custom gestures (`.onLongPressGesture`, `DragGesture`, `RotationGesture`, `MagnificationGesture`) must have:
  1. An `.accessibilityAction` alternative for VoiceOver users
  2. A visible single-tap `Button` alternative for touch users who cannot perform the gesture

```swift
// Good — drag gesture with button alternatives
ForEach(items) { item in
    Text(item.name)
        .onDrag { NSItemProvider(object: item.name as NSString) }
}
// Plus: Move Up / Move Down buttons or .accessibilityAction for reordering
```

## Animation and Motion (WCAG 2.3.1)

- Always check `@Environment(\.accessibilityReduceMotion)` or `UIAccessibility.isReduceMotionEnabled` before using `.animation()` or `withAnimation`. Remove or simplify animations when reduce motion is enabled.

```swift
@Environment(\.accessibilityReduceMotion) var reduceMotion

withAnimation(reduceMotion ? nil : .spring()) {
    isExpanded.toggle()
}
```

## Links (WCAG 2.4.4, 4.1.2)

- Use `Link("text", destination: url)` instead of a `Button` that calls `openURL`. This gives the element the correct link trait.
- Never use generic link text like "Click here", "Read more", "Learn more", or "Tap here". The link text must describe its destination.

```swift
// Good
Link("CVS Health Privacy Policy", destination: privacyURL)

// Bad — button used as link
Button("Click here") { openURL(privacyURL) }
```

## Grouping (WCAG 1.3.1, 1.3.2)

- 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.
- In a `ZStack` with multiple interactive elements, use `.accessibilitySortPriority()` or `.accessibilityElement` to control VoiceOver reading order.

## Sheets and Modals (WCAG 2.4.3)

- Always include a `ScrollView` inside `.sheet()` and `.fullScreenCover()` so content remains accessible at large Dynamic Type sizes.
- Manage focus return on dismiss to avoid losing VoiceOver focus.

## Tab Bars (WCAG 4.1.2)

- Every tab in a `TabView` must have a `.tabItem { Label("name", systemImage: "icon") }`.
- When using `.badge(count)`, also add `.accessibilityValue("\(count) notifications")` because `.badge()` is not automatically read by VoiceOver.

## Accessibility Hidden (WCAG 4.1.2)

- Never apply `.accessibilityHidden(true)` on a container that has interactive children (`Button`, `Toggle`, `TextField`, etc.) — this hides them from VoiceOver completely.
- Only use `.accessibilityHidden(true)` on purely decorative elements.

## Timing (WCAG 2.2.1)

- Content that auto-dismisses (using `Task.sleep` or `asyncAfter` with a dismiss) must give the user control to extend or pause the timer.

## Accessibility Notifications

- Use `UIAccessibility.post(notification: .announcement, argument: "message")` to announce dynamic content changes to VoiceOver users (e.g., search result counts, form validation errors).
- Use `.screenChanged` when the entire screen changes and `.layoutChanged` when part of the screen changes.

---

Source: [ios-swiftui-accessibility-techniques](https://github.com/cvs-health/ios-swiftui-accessibility-techniques) by CVS Health — 85+ technique examples, 31 static analysis rules, 17 WCAG 2.2 criteria.

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

iOS SwiftUI Accessibility

Directory Structure

SKILL.md

Report

Notice