accessibility

Files (21)

• SKILL.md
• before-after-appkit.md · examples/
• before-after-swiftui.md · examples/
• before-after-uikit.md · examples/
• assistive-access.md · references/
• appkit-checklist.md · references/auditors/
• swiftui-checklist.md · references/auditors/
• display-settings.md · references/
• dynamic-type.md · references/
• media-accessibility.md · references/
• motor-input.md · references/
• nutrition-labels.md · references/
• platform-specifics.md · references/
• semantic-structure.md · references/
• testing-auditing.md · references/
• voice-control.md · references/
• voiceover-swiftui.md · references/
• voiceover-uikit.md · references/
• wcag-mapping.md · references/
• audit-template.swift · resources/
• qa-checklist.md · resources/

SKILL.md (first lines)

# 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](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-swiftui.md), [examples/before-after-uikit.md](examples/before-after-uikit.md), or [examples/before-after-appkit.md](examples/before-after-appkit.md)
- For platform issues → [references/platform-specifics.md](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](references/wcag-mapping.md)
- Hand off to QA → [resources/qa-checklist.md](resources/qa-checklist.md)

### 4) Prepare Nutrition Label recommendation
→ [references/nutrition-labels.md](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] | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — |

From ducko-im/ducko, GPL-3.0.

More from ducko-im/ducko