swift-accessibility-skill

What this skill does

# Platform Accessibility

## Overview

Apply accessibility for SwiftUI, UIKit, and AppKit across all supported platforms. Covers all 9 App Store Accessibility Nutrition Label categories — VoiceOver, Voice Control, Larger Text, Dark Interface, Differentiate Without Color, Sufficient Contrast, Reduced Motion, Captions, and Audio Descriptions.

This skill prioritizes native platform APIs (which provide free automatic support) and fact-based guidance without architecture opinions.

## First-Draft Rules

Include accessibility in the **first draft** — never write a bare element and patch it later. Retrofitting accessibility is harder, gets skipped, and produces worse results than building it in from the start.

No inline commentary unless a pattern is non-obvious. Mark inferred labels with `// [VERIFY]` because SF Symbol names don't always match the intended user-facing meaning.

| Situation | Required on first write |
|---|---|
| `Button` / `NavigationLink` — icon-only | `.accessibilityLabel("…")` with `// [VERIFY]` |
| `Button` / `NavigationLink` — visible text | Nothing extra — text is the label automatically |
| `Image` — meaningful | `.accessibilityLabel("…")` |
| `Image` — decorative | `.accessibilityHidden(true)` |
| `withAnimation` / `.transition` / `.animation` | `@Environment(\.accessibilityReduceMotion)` + gate animation |
| `.font(.system(size:))` | Replace with `.font(.body)` or `@ScaledMetric` |
| Color conveys state/status | Add shape, icon, or text alongside color |
| `onTapGesture` on non-`Button` | `.accessibilityElement(children: .ignore)` + `.accessibilityAddTraits(.isButton)` + `.accessibilityLabel` |
| Custom slider / toggle / stepper | `.accessibilityRepresentation { … }` or `.accessibilityValue` + `.accessibilityAdjustableAction` |
| Async content change | Post announcement with availability guards (`AccessibilityNotification.Announcement` on iOS 17+, fallback to `UIAccessibility.post`) |
| System `.sheet` / `.fullScreenCover` | Nothing extra — SwiftUI traps focus automatically (custom overlays still need focus management) |
| `AVPlayer` / video | Use `AVPlayerViewController` — captions and Audio Descriptions for free |
| Custom tappable view | `.frame(minWidth: 44, minHeight: 44)` |
| Any new SwiftUI view | Verify with Xcode Canvas Variants (see Accessibility Summary) |
| `NSButton` — icon-only (AppKit) | `setAccessibilityLabel("…")` with `// [VERIFY]` |
| Custom `NSView` interactive element (AppKit) | `setAccessibilityElement(true)` + role (`setAccessibilityRole(.button)`) + label |
| AppKit modal/popup UI | Trap focus and ensure dismiss action is keyboard + VoiceOver reachable |
| Any new AppKit view/controller | Verify with Accessibility Inspector and full keyboard navigation |

Prefer native controls (`Button`, `Toggle`, `Stepper`, `Slider`, `Picker`, `TextField`) — they get full accessibility automatically. Custom interactive views require explicit work.
For AppKit, prefer native controls (`NSButton`, `NSPopUpButton`, `NSSlider`, `NSSegmentedControl`, `NSTextField`) before custom `NSView` interaction.

**Example — icon-only button:**
```swift
Button {
    shareAction()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share") // [VERIFY] confirm label matches intent
```

**Example — gating animation on Reduce Motion:**
```swift
@Environment(\.accessibilityReduceMotion) private var reduceMotion

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

Full testing and verification procedures → `references/testing-auditing.md`

## Workflow

### Reference Routing Rule
Before answering, select one **primary** reference file that best matches the user's intent and load it first.
Load additional reference files only when the request explicitly spans multiple domains (for example, VoiceOver + Dynamic Type + WCAG mapping) or when the primary file does not cover a required criterion.

### 1) Implement new code
Apply **First-Draft Rules** — accessibility in the first draft, no commentary.
For APIs introduced after iOS 15, always add `#available` guards and provide older-OS fallback behavior.
After writing, verify against the First-Draft Rules table — fix any gaps before outputting.
After the code, append an **Accessibility Summary** (see below).

### 2) Improve or fix existing code
Apply fixes silently, no commentary.
For APIs introduced after iOS 15, always add `#available` guards and provide older-OS fallback behavior.
After fixing, verify against the First-Draft Rules table — fix any gaps before outputting.
After the code, append an **Accessibility Summary**.
- For transformation patterns → `examples/before-after-swiftui.md`, `examples/before-after-uikit.md`, or `examples/before-after-appkit.md`
- For platform issues → `references/platform-specifics.md`

### 3) Audit existing code
Only when user explicitly asks ("audit", "how accessible is this?", "review accessibility").

**Quick fix mode** — when the user asks for blocker-only/critical-only scope (for example: "just fix the blockers", "quick fix", "critical only"): address only Blocks Assistive Tech and Degrades Experience issues. Skip Incomplete Support.

**Comprehensive mode** (default) — address all severity levels including Incomplete Support and Nutrition Label gaps.

- Identify issues by category → **Triage Playbook** below
- Format with **Audit Output Format** below
- For WCAG compliance mapping → `references/wcag-mapping.md`
- Hand off to QA → `resources/qa-checklist.md`

### 4) Prepare Nutrition Label recommendation
→ `references/nutrition-labels.md` — all 9 categories with official pass/fail criteria

When the user asks to prepare or draft an App Store Accessibility Nutrition Label recommendation, output this format:

```
**Accessibility Nutrition Label recommendation**

**App version evaluated:** [version or "Current build"]
**Scope reviewed:** [common tasks / screens evaluated]

**You could claim:**
- [labels where every common task is ✅ or —]

**Why you could claim them:**
- [label]: [brief reason tied to completed common-task coverage]

**You should not claim:**
- [labels blocked by any ❌]
- [labels that are not applicable]

**Why you should not claim them:**
- [label]: [blocked task or why the label is not applicable]

**Common-task verification**
| Common Task | VoiceOver | Voice Control | Larger Text | Dark Mode | No Color | Contrast | Motion | Captions | Audio Desc |
|---|---|---|---|---|---|---|---|---|---|
| [task] | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — |

**Recommendation summary**
- You could claim: [labels]
- You should not claim: [labels]
```

Do not say "claim" without qualification. Phrase the output as a recommendation based on the reviewed scope.
Do not suggest a label if any common task in that column is ❌. Use `—` only when the label is genuinely not applicable to that app or flow.

## Accessibility Summary

Append after all code generation and fix tasks (modes 1, 2), unless the user explicitly requests code-only output. No preamble.

```
**Accessibility applied:**
- [one bullet per pattern added — e.g. "`.accessibilityLabel` on icon-only Share button"]

**Verify in Xcode:**
- Use Canvas **Dynamic Type Variants** (grid icon → Dynamic Type Variants) to check layout at all text sizes
- Use Canvas **Color Scheme Variants** to check light and dark mode
- Use **Accessibility Inspector** (Xcode → Open Developer Tool) Settings tab to simulate Increase Contrast, Reduce Motion, Bold Text on the Simulator

**If Xcode is unavailable:**
- Run equivalent checks with platform accessibility inspector tools and manual setting toggles (Dynamic Type, Contrast, Reduce Motion, VoiceOver/Voice Control)

**Test on device:**
- [relevant items from Must Test on Device checklist]
```

Omit "Accessibility applied" entirely if nothing was added (all native controls).
Omit "Nutrition Label readiness" unless the user asked about it.

## Audit Output Format

On