Audit swiftui accessibility
Skill yigitkonur/plugin-swiftui/skills/audit-swiftui-accessibility
Audits a finished or in-progress macOS SwiftUI codebase for accessibility defects — icon-only controls with no label, ungrouped composite controls, custom controls with no value, color-only state, no Reduce-Motion path, undescribed Chart/Canvas, missing traits, broken VoiceOver focus — and writes per-finding Markdown to swiftui-audits/. Use when the user says VoiceOver reads nothing or the wrong thing, an icon button is unlabeled, a chart or canvas is unreadable, the app fails Differentiate Without Color or Reduce Motion, focus order is wrong, or when AI may have written accessibilityText, voiceOverLabel, a11yLabel, the legacy accessibility(label:) modifier, or an isToggle trait ungated below macOS 14. AUDIT-ONLY, macOS-only, SwiftUI-only. Not for AppKit NSAccessibility, not for keyboard @FocusState (controls-forms), not for Dynamic-Type sizing (typography-text), not for writing new accessible UI from scratch.From its SKILL.md
npx -y skills add yigitkonur/plugin-swiftui --skill audit-swiftui-accessibilityAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
19.9 KB, as published. Nobody here has run it
Audit SwiftUI Accessibility
AUDIT-ONLY · macOS-only · SwiftUI-only. Run this on a finished or in-progress macOS SwiftUI project to detect — and where certain, fix — every way the assistive-technology experience breaks: unlabeled icon controls, composites that read as fragments, custom controls with no value, color- or motion-only information, undescribed charts/canvases, missing traits, stranded VoiceOver focus, and hallucinated or legacy accessibility APIs. Findings are written to disk in the toolkit's unified schema; the mechanical defects (invented names, the legacy combinator) are fixed under the fix-safety protocol. This is never a from-scratch accessibility generator.
Accessibility modifiers are additive and invisible — the code compiles and looks right with none of them. The lint only locates candidates; whether a label is missing, wrong, or correctly present is an LLM judgment from READING the view. Be suspicious wherever a control has no visible text.
Boundary / seam note (stay in lane)
- AppKit
NSAccessibility*is out of scope. If audited code drops to anNSViewRepresentableand setsNSAccessibilityproperties, note it in one line and defer to the futureaudit-appkit-accessibility— do not audit AppKit accessibility here. - Keyboard
@FocusState(Tab-key focus) belongs toaudit-swiftui-controls-forms; this skill ownsAccessibilityFocusState(VoiceOver focus). Different wrappers — keyboard = controls, VoiceOver = a11y. .helptext is authored byaudit-swiftui-controls-forms; this skill reuses that.helpstring as the.accessibilityLabelfor an icon-only control. Keep both, cross-linked (cross_ref controls-forms).- Dynamic-Type sizing is
audit-swiftui-typography-text; Differentiate-Without-Color / WCAG contrast construction isaudit-swiftui-appearance-color; Reduce-Motion construction isaudit-swiftui-animation-motion— this skill owns only "the flag is ignored". Chart/Canvas descriptors are intentionally double-detected withcharts/drawing-canvas(cross-link, don't collapse).
The four assistive-technology axes (the lens)
- Perceivable. Every control conveys its identity without sight: a label (icon-only →
.accessibilityLabel), a value (custom control →.accessibilityValue), and never information by color or motion alone. - Operable. Anything tappable carries an actionable trait (
.isButton,.isToggle) and a sane VoiceOver focus order (AccessibilityFocusState,.accessibilitySortPriority). - Grouped. A composite (HStack/VStack of Text+Image that is one control) is collapsed with
.accessibilityElement(children: .combine/.ignore); decorative imagery is.accessibilityHidden(true). - Represented. A
Chart/Canvasexposes an.accessibilityChartDescriptor/.accessibilityRepresentation.
The element test: ask "what does VoiceOver announce when it lands here, and can the user act?" No
answer → a finding. Full reasoning + the per-control coverage artifact: references/labels-and-traits.md.
Defect index (a11y-01 … a11y-12)
id · tell · severity · fix · open reference. Severities: hard-fail (invented name / build-or-floor
break), warning (compiles but inaccessible), advisory (judgment / partial). auto = mechanical
single-answer fix; flag = show the ✅, dev applies.
| id | One-line tell | Sev | Fix | Reference |
|---|---|---|---|---|
| a11y-01 | icon-only control (Image(systemName:)/Label icon) is the sole content, no .accessibilityLabel | warning | flag | labels-and-traits.md |
| a11y-02 | purely-decorative Image not .accessibilityHidden(true) (VoiceOver clutter) | advisory | flag | labels-and-traits.md |
| a11y-03 | custom composite (Text+Image as one control) with no .accessibilityElement(children:) | warning | flag | grouping-and-values.md |
| a11y-04 | custom value control (hand-rolled gauge/slider/progress) with no .accessibilityValue | warning | flag | grouping-and-values.md |
| a11y-05 | state conveyed by color only — no label/shape/symbol fallback (Differentiate-Without-Color) | warning | flag | perceptual-paths.md |
| a11y-06 | animation/transition with no accessibilityReduceMotion branch (ignores the flag) | advisory | flag | perceptual-paths.md |
| a11y-07 | Chart / Canvas with no a11y representation (accessibilityChartDescriptor/Representation) | warning | flag | perceptual-paths.md |
| a11y-08 | .onTapGesture/.onLongPressGesture on a non-Button, no .isButton/.isToggle trait | warning | flag | labels-and-traits.md |
| a11y-09 | AccessibilityFocusState declared-but-never-driven, or broken VoiceOver reading order | advisory | flag | grouping-and-values.md |
| a11y-10 | INVENTED name — .voiceOverLabel/.a11yLabel/.accessibilityText(/.screenReaderLabel/.accessibilityName( | hard-fail | auto | accessibility-api-surface.md |
| a11y-11 | LEGACY combined .accessibility(label:/hint:/addTraits:/value:) modifier | warning | auto | accessibility-api-surface.md |
| a11y-12 | .isToggle trait (macOS 14) or closure-form label/value (macOS 15) ungated under a lower floor | warning | flag | labels-and-traits.md |
.accessibility(label:) IS confirmed deprecated — Apple docs show macOS 10.15–26.5 Deprecated, replacement
accessibilityLabel(_:) (the whole combined family — hint:/value:/hidden:/identifier:/addTraits:/
removeTraits:/sortPriority: — is deprecated likewise). The corpus deprecated:false was a false negative.
Carry a11y-11 as a warning migration with source: macOS 10.15–26.5 Deprecated → accessibilityLabel(_:).
The real API, at a glance
Real (exist on macOS): accessibilityLabel(_:) (string StringProtocol macOS 11; string LocalizedStringResource macOS 13; closure macOS 15), accessibilityValue(_:)
(macOS 11; closure form macOS 15), accessibilityHint(_:) (13), accessibilityHidden(_:) (11),
accessibilityElement(children:) (10.15), accessibilityAddTraits(_:)/accessibilityRemoveTraits(_:) (11),
accessibilityFocused(_:) + AccessibilityFocusState (12), accessibilitySortPriority(_:) (11),
accessibilityChartDescriptor(_:) (12), accessibilityRepresentation(representation:) (12),
@Environment(\.accessibilityReduceMotion) / \.accessibilityDifferentiateWithoutColor (10.15).
AccessibilityTraits.isToggle is macOS 14.0+ — NOT 10.15; never assert it on a lower floor.
Hallucinated (never exist): .voiceOverLabel, .a11yLabel, .accessibilityText(…), .screenReaderLabel,
.accessibilityName(…), .voiceOverHint. A swiftui-ctx lookup exit 3 corroborates each.
Real-but-legacy: the combined .accessibility(label:/hint:/addTraits:/value:) modifier → split into the
per-aspect modifiers.
Signatures, the full ❌→✅ rewrites, and the canonical shapes (via swiftui-ctx lookup): the reference files.
Floor values are the reconciled truth in ${CLAUDE_PLUGIN_ROOT}/references/_shared/floors-master.md and the
canonical invented-name list in ${CLAUDE_PLUGIN_ROOT}/references/_shared/hallucination-blacklist.md — read,
never restate them.
✅ Correct — the grounded shape (real corpus, not invented)
The fix for an icon-only control (a11y-01) is the swiftui-ctx consensus shape accessibilityLabel(_)
(100% of real uses, bash ${CLAUDE_PLUGIN_ROOT}/scripts/swiftui-ctx lookup accessibilityLabel --json) — a
string label chained outside the visual node. Real shipping example, fetched live via
swiftui-ctx file ex_e9a36e4789 --smart (jordanbaird/Ice, 28k★):
// github.com/jordanbaird/Ice …/Ice/UI/IceBar/IceBar.swift#L406
Image(nsImage: image)
.contentShape(Rectangle())
.overlay { IceBarItemClickView(item: item, leftClickAction: …, rightClickAction: …) }
.accessibilityLabel(item.displayName) // ← the icon now announces a real name
.accessibilityAction(named: "left click", leftClickAction)
.accessibilityAction(named: "right click", rightClickAction)
- Permalink:
https://github.com/jordanbaird/Ice/blob/11edd39115f3f43a83ae114b5348df6a0e1741cf/Ice/UI/IceBar/IceBar.swift#L406 - Spec (Sosumi
doc:):https://sosumi.ai/documentation/swiftui/view/accessibilitylabel(macOS 13.0+, string form).
Every finding's ## Correct is built this way — never a hand-written snippet. The label text stays
flag-only (a judgment call); the shape is the corpus consensus above.
The 8-step audit workflow (execute verbatim)
- ORIENT.
tree/findthe SwiftUI sources. Read the deployment target (project.pbxprojMACOSX_DEPLOYMENT_TARGET, orPackage.swiftplatforms:). It is load-bearing: a11y-12 fires only when the floor is below macOS 14 (.isToggle) or below 15 (closure-form label/value). Record it. - LOCATE. Run the shared hybrid lint runner:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/swiftui-lint.sh --skill audit-swiftui-accessibility --dir <sources> --json /tmp/a11y.json --sarif /tmp/a11y.sarif. It runs this skill's tier-1 grep tells (lint/grep-tells.tsv) + tier-2 structural ast-grep rules (lint/ast-grep/*.yml— the undescribed-Chart containment rule grep can't express), plus a per-file parse probe, and emits unified JSON + SARIF. Read itsparse_warnings— a flagged file did not fully parse, so a structural miss can't masquerade as clean; READ those by hand. The runner only LOCATES. Engine + rule-file format + degradation:${CLAUDE_PLUGIN_ROOT}/references/_shared/lint-architecture.md. - READ. Open every located file in full — never pattern-match-and-patch blind. Whether a control
already has a label, whether an
Imageis decorative, whether a composite is one control, and the focus order are all invisible to grep. Build a per-view inventory: each control → its announced label + value + trait + (for composites) its grouping + (for charts/motion) its representation/Reduce path. - DETECT. Apply the index. Assign each candidate a confidence; report a finding only at 100%
certainty (e.g. an invented name, an icon-only Button with provably no label, an
.isToggleunder a <14 floor). An absence (no label) is a finding only after you have read the whole view and confirmed it. - VERIFY. For anything ≤ ~70% confidence (a symbol you're unsure exists, a floor you can't place, a
deprecation claim), run both evidence sources. (a) Practice —
bash ${CLAUDE_PLUGIN_ROOT}/scripts/swiftui-ctx lookup <api> --json(andswiftui-ctx deprecated <api>for a11y-11): read itsconsensus(the canonical shape),deprecated+replacement,recommendedpermalink,introduced_macos, andco_occurs_with; alookupexit 3 (with a did-you-meansuggestion) corroborates an a11y-10 hallucination — no shipping Mac app uses the symbol. (b) Spec — confirm via Sosumi:curl -sSL https://sosumi.ai/<apple-path>usingreferences/source-directory.mdfor the path and${CLAUDE_PLUGIN_ROOT}/references/_shared/sosumi-reference.mdfor the protocol (neverWebFetchdeveloper.apple.com). Cross-checkintroduced_macosagainstfloors-master.mdand the Sosumidoc:floor. The CLI contract is${CLAUDE_PLUGIN_ROOT}/references/_shared/swiftui-ctx-reference.md. Promote with the citation or discard. - REPORT. Write each confirmed finding (output contract below). One finding per file, zero-padded,
ordered. Emit
cross_refon the shared seams (a11y-05 → appearance-color, a11y-06 → animation-motion, a11y-07 → charts/drawing-canvas, a11y-01/08 → controls-forms.help). Write the run's_index.md. - FIX. Apply corrections under the fix-safety protocol
(
${CLAUDE_PLUGIN_ROOT}/references/_shared/fix-safety-protocol.md): clean-tree gate, findings-first, onlyfix_mode: auto(a11y-10 invented-name swap, a11y-11 legacy-combinator split), one conventional commit per finding citing itsrule_id, never weaken a check. The ✅ "Correct" is not a hand-written snippet — it is the swiftui-ctx consensus shape put in## Correct, backed by a real macOS example fetched withbash ${CLAUDE_PLUGIN_ROOT}/scripts/swiftui-ctx file <recommended.id> --smartwhose GitHub permalink (plus the Sosumidoc:) goes in## Source. The label text itself (a judgment call) staysflag-only— never auto-invent a string. Leaveflag-onlyfindingsopenwith that ✅ in## Correct. - DOUBLE-CHECK. Re-grep each fixed file to confirm the tell no longer matches; record the evidence in
## Fix applied?. Re-confirm every citation still resolves and its floor still matches. If a fix introduced a new tell (e.g. an added.isTogglenow needs a macOS-14 gate), loop that file back to DETECT.
Confidence gating (load-bearing)
Report a finding only at 100% certainty. An accessibility absence (missing label/value/trait) is a
finding only after reading the whole view and confirming nothing supplies it — a .help, an
.accessibilityLabel on a parent, or a native control's built-in semantics can all already cover it.
Anything ≤ ~70% goes to VERIFY (step 5). Auto-fix only the mechanical set (a11y-10/11); the label/value/trait
content is always fix_mode: flag-only.
Output contract
Inherits the toolkit's unified contract (full schema + body sections + frontmatter keys:
${CLAUDE_PLUGIN_ROOT}/references/_shared/finding-schema.md — do not restate it). Specialized for this domain:
- Findings:
swiftui-audits/accessibility/<context>/NN-slug.md(one finding per file, zero-padded, ordered). Per-run index:swiftui-audits/accessibility/_index.md. domain: accessibility. Frontmatter is the canonical schema;fix_modeisautofor a11y-10/11, elseflag-only.availabilityreads fromfloors-master.md.sourceis an Apple URL + access date (via Sosumi) orverify against Xcode 26 SDK. Additive fielda11y_axisrecords the broken axis —perceivable|operable|grouped|represented— so a run can be read by assistive-tech failure mode.
Starter <context> folders (file here when…):
<context> | File a finding here when… |
|---|---|
missing-label/ | an icon-only control has no announced label, or a decorative image isn't hidden (a11y-01, a11y-02) |
missing-value/ | a custom value control announces no value (a11y-04) |
grouping/ | a composite reads as fragments — no accessibilityElement(children:) (a11y-03) |
traits-and-focus/ | a tappable lacks an actionable trait, or VoiceOver focus order is broken (a11y-08, a11y-09) |
color-and-motion/ | information is color-only or motion ignores Reduce Motion (a11y-05, a11y-06) |
chart-canvas-representation/ | a Chart/Canvas is undescribed to VoiceOver (a11y-07) |
hallucinated-api/ | a name doesn't exist, or the legacy combined modifier is used (a11y-10, a11y-11) |
availability-gating/ | .isToggle / closure-form label/value used ungated under a lower floor (a11y-12) |
New-folder rule: if a finding does not fit any existing context folder, create a new one under
swiftui-audits/accessibility/ with a lowercase-hyphen slug naming the sub-category, and note it in the run's
_index.md. Prefer an existing folder when the fit is reasonable; consistency across runs is a hard
requirement. Two runs over the same code produce structurally identical trees.
Go-beyond artifact (optional):
swiftui-audits/accessibility/_coverage-map.mdlisting every interactive view with its announced label/value/trait and a per-axis coverage score — seereferences/labels-and-traits.md.
Reference routing
| File | Open when |
|---|---|
references/accessibility-api-surface.md | a name/signature/existence question — the real allow-list, the invented ❌→✅, the legacy-combinator split (a11y-10/11) |
references/labels-and-traits.md | icon-only labels, decorative hiding, missing traits, .isToggle/closure-form gating, the coverage map (a11y-01/02/08/12) |
references/grouping-and-values.md | composite grouping, custom-control values, VoiceOver focus order (a11y-03/04/09) |
references/perceptual-paths.md | color-only state, Reduce-Motion path, Chart/Canvas representation (a11y-05/06/07) |
references/source-directory.md | step VERIFY — the Apple/WWDC/practitioner source map fetched via Sosumi |
lint/grep-tells.tsv + lint/ast-grep/*.yml | step LOCATE — this skill's declarative lint rule set fed to the shared runner (tier-1 grep tells + tier-2 structural ast-grep); edit here to tune detection |
Shared toolkit references (point in, never restate):
| Shared file | For |
|---|---|
${CLAUDE_PLUGIN_ROOT}/references/_shared/floors-master.md | every floor/availability value (the reconciled truth — incl. .isToggle=macOS 14, closure forms=15) |
${CLAUDE_PLUGIN_ROOT}/references/_shared/hallucination-blacklist.md | the canonical invented-name list |
${CLAUDE_PLUGIN_ROOT}/references/_shared/macos-arm-gating.md | the macOS-arm gating rule (a11y-12 floor gate) |
${CLAUDE_PLUGIN_ROOT}/references/_shared/finding-schema.md | the unified finding schema + frontmatter keys + the a11y_axis additive field |
${CLAUDE_PLUGIN_ROOT}/references/_shared/fix-safety-protocol.md | the fix-safety protocol (step 7) |
${CLAUDE_PLUGIN_ROOT}/references/_shared/sosumi-reference.md | the Apple-doc spec fetch protocol (step 5 VERIFY) |
${CLAUDE_PLUGIN_ROOT}/references/_shared/swiftui-ctx-reference.md | the practice-corpus CLI contract — lookup/deprecated/file --smart for the consensus shape + permalinked example (steps 5 VERIFY · 7 FIX) |
${CLAUDE_PLUGIN_ROOT}/references/_shared/cross-ref-graph.md | seam ownership + cross_ref targets (controls-forms, appearance-color, animation-motion, charts, drawing-canvas) |
Detection accelerator
bash ${CLAUDE_PLUGIN_ROOT}/scripts/swiftui-lint.sh --skill audit-swiftui-accessibility --dir <files-or-dir> [--json out.json] [--sarif out.sarif] — the toolkit's one shared hybrid lint engine, fed this skill's
declarative rules: tier-1 grep tells (lint/grep-tells.tsv, a11y-01/02/03/04/05/06/07/08/09/10/11/12)
- tier-2 ast-grep structural rules (
lint/ast-grep/*.yml— a11y-07 Chart-no-descriptor — the containment/absence form grep cannot express; a11y-01 stays grep-tier because a correct label chains outside the Button node, so a containment rule would false-positive). It runs a per-file parse probe (surfaces "did not fully parse" so a structural miss can't look clean), emits unified JSON + SARIF, exits 2 on any hard-fail (a11y-10/12) for a CI gate, and degrades to grep-only with a notice if ast-grep is unreachable (npx --package @ast-grep/cli ast-grep; faster:brew install ast-grep). It only LOCATES — accessibility is additive and invisible, so always READ each hit in full before reporting (step 3). The thinscripts/a11y-lint.shis a pointer to this runner. Engine + rule-file format + JSON/SARIF shape + safety rails:${CLAUDE_PLUGIN_ROOT}/references/_shared/lint-architecture.md.