swift-accessibility-skill

name	swift-accessibility-skill
description	Audits SwiftUI accessibility in the Lilium / BookNotes app against Apple's Human Interface Guidelines AND the project's own conventions (the mandatory .accessibilityLabel + dot-namespaced .accessibilityIdentifier on every interactive element), then reports findings with file:line, severity, and a concrete fix — and offers to apply them. Covers VoiceOver semantics, Dynamic Type, 44pt touch targets, color/contrast (incl. velvet-on-purple traps), Reduce Motion, and the .keyboard-toolbar / container-collapse AX-tree gotchas, with an optional live pass that drives the simulator via idb to confirm identifiers actually resolve. Use this WHENEVER the user wants to check, audit, review, or improve accessibility / a11y / VoiceOver / Dynamic Type support for a SwiftUI view, screen, or diff — even phrased as "is this screen usable with VoiceOver?", "did I miss any accessibility labels?", "make this view accessible", "check the new sheet for a11y", or "audit accessibility before I open the PR". Also trigger it proactively after building or restyling any SwiftUI view, since the type-checker can't see missing labels, clipped Dynamic Type, or undersized tap targets. Do NOT use it for backend/API code, for pure copy/localization review, or as a general SwiftUI correctness review (use swiftui-pro for that).
argument-hint	[files, a directory, or "the diff" — defaults to the current diff]
allowed-tools	Read, Edit, Grep, Glob, Bash

SwiftUI accessibility audit

Audit SwiftUI code so a VoiceOver, Switch Control, Voice Control, or Dynamic Type user can actually operate it — and so the agentic-QA bots can drive it. You are checking against two things at once: Apple's HIG (the objective rules in references/hig-rules.md) and this project's conventions (the label+identifier contract and the velvet/idb gotchas in references/lilium-conventions.md). Read both reference files before judging; they carry the why behind each rule so you can reason about borderline cases instead of pattern-matching.

The goal is real findings a real assistive-tech user would feel — not a lint dump. A clean build proves nothing here: the compiler never sees a missing label, a clipped frame at AX5 text, an undersized tap target, or a color-only state.

1. Establish scope

• Default (no argument, or "the diff"): the changed Swift files — scripts/a11y_scan.py --diff.
• A path/directory: audit those files.
• A whole surface ("the Groups screens"): glob the matching views.

Audit only SwiftUI view code (.swift files with view bodies). Skip tests, mocks, and non-view types.

2. Run the candidate finder

python3 scripts/a11y_scan.py <paths|--diff>

This is a heuristic pre-filter, not the verdict. Regex can't see Swift types or view composition, so each hit is a candidate: a child view may already supply the label, a small frame may not be the tap target, an Image may be decorative. Treat the output as a checklist of sites to open and confirm — never report a scanner hit as a finding without reading the code around it. The scanner's value is coverage (nothing interactive slips past) and a starting map.

It flags: icon-only buttons with no label (A11Y001), .onTapGesture without the button trait (A11Y002), hardcoded font sizes (A11Y003), sub-44pt frames near controls (A11Y004), .keyboard toolbars (A11Y005), interactive elements with no identifier (A11Y006), and duplicate identifier literals across the scanned files (A11Y007). A11Y007 is a candidate like the rest: the same id on two mutually-exclusive screens (sign-in vs sign-up) is usually fine; the real bug is the same id within one screen, or shared between a reusable component and a live call site — there the bots match the wrong element.

3. Read and judge each candidate, plus what the scanner can't see

Open each flagged site and the views in scope. Confirm or dismiss each candidate, and check the things regex misses — these need eyes on the code:

• The two-modifier contract (lilium-conventions.md): every interactive element has BOTH a label and a dot-namespaced identifier. Confirm the identifier's prefix matches the surface.

• VoiceOver semantics (hig-rules.md §1): state exposed not just drawn, decorative images hidden, compound rows grouped — and the container-collapse trap (an id or .combine on a container that holds buttons swallows their ids).

• Dynamic Type (§2): fixed heights around text, layouts that won't survive AX5.

• Touch targets (§3): confirm a flagged small frame is really the hit area.

• Color & contrast (§4): color-only state; velvet-on-purple traps (system-adaptive colors on the always-purple TIL card, the invisible-in-dark blended recipe).

• Reduce Motion (§4.3): big animations with no degraded path.

• Reachability & duplicate ids (A11Y007 + a quick check): for a reusable component, grep the repo for its type name (grep -rn "<TypeName>(" Lilium) — if it has no call site it's dead code, and the fix is to delete it, not to decorate it; say so instead of filing a11y findings against it. Confirm each A11Y007 duplicate: same id within one screen, or shared between a component and a live path, means the bots can match the wrong element — flag it; the same id on two screens that never coexist is fine.

When you add labels/identifiers to a view, also fix nearby interactive elements missing them — but don't fan out into unrelated files just to add coverage.

Precision — what NOT to flag

The skill's edge over a generic review is restraint: a report full of non-issues trains the user to ignore it. Before writing a finding, make sure it would actually hurt a real assistive-tech user. Common false alarms to suppress (the scanner will surface some of these as candidates — your job is to dismiss them):

• A .white / velvetParchmentFixed / velvetGold foreground inside the always-purple TIL card. That's the correct non-adaptive choice there (lilium-conventions.md). Don't recommend velvetInk/Color.primary for it — that's the actual bug, reversed.
• A Button whose label comes from a Text child or the highlight/title content. SwiftUI derives the VoiceOver label from it; an explicit .accessibilityLabel would double it up.
• Decorative images already .accessibilityHidden(true), and small frames on decorative shapes (an 8pt badge dot) that aren't the tap target.
• A static .scaleEffect/.offset with no animation. Reduce Motion is about animations — a constant transform isn't motion, so it isn't a Reduce Motion finding.
• .font(.system(.body, design: .serif)) and friends — that's a semantic style with a design, which scales. Only a literal .font(.system(size: 17)) breaks Dynamic Type.

4. Optional — verify live on the simulator

Offer this when identifiers/AX-tree reachability is the concern (the .keyboard and container-collapse gotchas only show at runtime), or when the user asks to confirm on device. It needs a running sim with the screen reachable. Follow the idb / AXUniqueId procedure in references/lilium-conventions.md: dump idb ui describe-all --json and confirm each id you expect appears under AXUniqueId. An id present in source but absent from the tree means a swallow, not a typo.

This drives the simulator — respect the screenshot/agentic-testing hygiene in the repo docs and don't collide with a running regression. Skip it for a pure source audit.

5. Report

Group findings by file, ordered by severity (Blocker → High → Medium → Low). For each:

### <file>:<line>  [<Severity>]  <rule>
What: <the problem, one line>
Why:  <who is affected and how — VoiceOver/Dynamic Type/motor/color-blind user>
Fix:  <concrete SwiftUI change, with the exact modifier/identifier to add>

Open with a one-line tally (e.g. "3 Blocker, 2 High, 1 Medium across 4 files"). If a screen is clean, say so plainly — don't invent findings to fill the report. Note anything that needs the live pass to confirm.

Severity meanings: Blocker = assistive-tech user can't operate/perceive it; High = degraded for a real setting (clips, mis-announced, hard to hit); Medium = unclear state or grouping; Low = polish. Definitions in hig-rules.md.

6. Offer to fix

After the report, ask whether to apply the fixes. The mechanical ones (add a missing identifier/label, enlarge a hit area, swap a hardcoded font for a semantic style) are safe to batch. The judgment ones (regrouping for VoiceOver, restructuring a .keyboard toolbar into a safeAreaInset) are worth confirming first. Per repo rules, code changes go in a worktree, not on main — if the user wants the fixes applied, set that up. If a fix changes what's on screen, the change still needs a screenshot to verify (the type-checker can't see it).