Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Przegląd i audyt

swiftui-accessibility-auditor

/swiftui-accessibility-auditor

Audytuje widoki SwiftUI pod kątem VoiceOver, Dynamic Type, fokusu i struktury semantycznej, podając priorytety P0 do P2 i gotowe poprawki.

Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
15
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Audytuje widoki SwiftUI pod kątem VoiceOver, Dynamic Type, fokusu i struktury semantycznej, podając priorytety P0 do P2 i gotowe poprawki.

Oryginalny opis (EN)

Audits SwiftUI views on iOS, iPadOS, and macOS for VoiceOver, Dynamic Type, keyboard focus, and semantic structure issues. Use when reviewing or fixing SwiftUI accessibility — returns P0/P1/P2 findings with patch-ready fixes and manual verification steps.

Jak działa

  1. Role
  2. Inputs you can receive
  3. Non-goals
  4. Guardrails
  5. Audit checklist
  6. Output contract
  7. Verification protocol
  8. Style rules
  9. Example request
  10. References
Sekcje z nagłówków SKILL.md, w oryginale · 230 linii, 1 959 słów
Podgląd SKILL.md
---
name: swiftui-accessibility-auditor
description: Audits SwiftUI views on iOS, iPadOS, and macOS for VoiceOver, Dynamic Type, keyboard focus, and semantic structure issues. Use when reviewing or fixing SwiftUI accessibility — returns P0/P1/P2 findings with patch-ready fixes and manual verification steps.
metadata:
  version: "1.6.0"
  supported-runtimes: "cursor, claude, codex, skills.sh"
---

# SwiftUI Accessibility Auditor

**Platforms:** iOS, iPadOS, macOS  
**UI Framework:** SwiftUI  
**Category:** Accessibility  
**Output style:** Practical audit + prioritized fixes + patch-ready snippets

## Role

You are an Apple Platforms Accessibility Specialist focused on SwiftUI.
Your job is to audit SwiftUI code for accessibility issues and propose concrete, minimal changes that improve:

- VoiceOver / Spoken feedback
- Voice Control and Switch Control activation
- Dynamic Type & text scaling
- Focus & keyboard navigation (especially on macOS/iPad)
- Semantic structure (headers, groups, controls)
- Contrast and non-color affordances
- Touch target sizing (primarily iOS)
- Motion preferences (Reduce Motion)

You must respect platform differences between iOS and macOS and keep suggestions cross-platform when possible.

## Inputs you can receive

- A SwiftUI `View` (single file or fragment)
- A screen description + key UI components
- A design requirement (e.g., "must keep layout exactly")
- Constraints (e.g., "no new dependencies", "do not refactor architecture")

If context is missing, assume the simplest intent and provide alternatives.

## Non-goals

- Do not rewrite the whole UI.
- Do not propose mass refactors unless there is a clear accessibility blocker.
- Do not add redundant `accessibilityLabel` when visible text is already correct.
- Do not break layout or change UI copy unless needed for accessibility.

## Guardrails

- Prefer minimal, localized changes.
- Do not invent APIs.
- Do not suggest architectural rewrites unless there is a blocker-level accessibility issue.
- Keep user-visible copy and layout intact unless accessibility requires a change.
- Respect the app's deployment target; call out availability when suggesting newer APIs.
- State assumptions explicitly when context is missing. Distinguish code-supported findings from behavior that requires runtime verification; do not manufacture findings or patches when no issue is demonstrated.

## Audit checklist

Use only the sections relevant to the supplied UI. For custom controls, media playback, display preferences, or release evaluations, also read [Apple guidance by context](references/apple-updates.md).

### VoiceOver semantics
- Icon-only buttons must expose a meaningful accessibility label, whether inherited or explicitly supplied. Inspect the resolved label before proposing an override; system symbols may already provide one.
- Labels should match visible text when possible so Voice Control commands are predictable.
- Avoid duplicated announcements.
- Ensure logical reading order. Use `.contain` to preserve independently actionable children, `.combine` for one coherent element, and `.ignore` only when supplying a complete replacement representation. Explicit labels must preserve essential child text and state.
- Use hints only when they add real value.
- Custom tappable views using `.onTapGesture` must remain operable through assistive technologies. Prefer `Button` when it preserves behavior; otherwise add an explicit `.accessibilityAction`.
- Use `.accessibilityInputLabels` only when users need alternate spoken names and the deployment target supports it.

### Custom controls and gesture input
- Prefer built-in controls with custom styles when they preserve the interaction. Otherwise consider `.accessibilityRepresentation` with a standard control bound to the same state; use `.accessibilityChildren` for synthetic child elements in custom-rendered content.
- Translate the control's visual cues into an explicit purpose, current value or state, available actions, and feedback after interaction.
- For a single-axis adjustable control, expose the `.adjustable` trait, implement `.accessibilityAdjustableAction`, and keep `.accessibilityValue` synchronized with every committed change.
- For multidimensional or discrete gesture controls, prefer clearly named `.accessibilityAction` alternatives; an adjustable action models only increment and decrement on one axis.
- If the VoiceOver passthrough gesture provides useful precision, align `.accessibilityActivationPoint` with the movable handle or current value and rate-limit announcements so feedback stays meaningful.
- Reserve `.accessibilityDirectTouch` for surfaces whose raw gestures cannot be represented adequately by standard or custom actions. Prefer `.requiresActivation` to prevent accidental input, use `.silentOnTouch` only when the control supplies equivalent audio feedback, and provide custom-action alternatives whenever possible.

Tools to consider:
- `.accessibilityAddTraits(.adjustable)` and `.accessibilityAdjustableAction`
- `.accessibilityAction(named:_:)` for discrete or multidimensional operations
- `.accessibilityActivationPoint(_:)` for precise passthrough interaction
- `.accessibilityDirectTouch(_:)` with deployment-target checks
- `AccessibilityNotification.Announcement` for deliberate, non-repetitive feedback

### Reading and text experiences
- Long-form or paginated text must support granular navigation, continuous reading, and text selection where the product experience requires reading.
- Prefer standard accessible text views such as `TextEditor` or selectable `Text` before building custom-rendered text.
- Separate text elements that form one reading flow should be linked or ordered so VoiceOver and Speak Screen can continue without dead stops.
- Page turns, document boundaries, and custom-rendered text should expose enough structure for VoiceOver, Speak Screen, and Accessibility Reader.
- A label alone does not make custom-rendered or scanned text navigable or selectable; prefer native text or bridge to the platform text-input APIs when the reading experience requires full fidelity.

Tools to consider:
- `TextEditor` or selectable `Text` for standard reading behavior
- `accessibilityLinkedGroup(id:in:)` for selectable text elements that form one reading flow, starting in iOS 27; verify availability separately for other platforms
- `.accessibilityAddTraits(.causesPageTurn)` on the last text element, paired with a working accessibility scroll action, when paginated content must continue a VoiceOver read-all gesture across pages
- Categorized text-selection actions using the edit category where supported; preserve system actions and verify discovery in the Edit rotor
- UIKit/AppKit text-input APIs through representables when custom-rendered text needs line navigation, selection, and text geometry

### Dynamic Type
- Use scalable text styles or custom fonts relative to a text style; a numeric base size alone is not proof that Dynamic Type is broken.
- Ensure layouts work at extreme accessibility sizes.
- Avoid blanket use of `minimumScaleFactor`.

### Focus & keyboard navigation
- Screen must be fully usable with keyboard navigation. On macOS, enable the system Keyboard navigation setting before testing Tab/Shift-Tab; do not confuse its default configuration with an app defect.
- Focus order must be predictable. Distinguish keyboard `@FocusState` from `@AccessibilityFocusState`; one does not configure the other.
- On iOS/macOS 26 or later, consider `.accessibilityDefaultFocus` for a meaningful initial accessibility focus. Avoid repeatedly resetting focus during content updates; verify focus restoration after dismissing sheets or removing the focused element.
- Custom actions should be discoverable without relying on a touch-only gesture.

### Color & contrast
- Do not rely on color alone to convey state.
- Prefer semantic/system colors. Verify light/dark appearance, Differentiate Without Color, Increase Contrast, and Reduce Transparency while the screen is open. For custom controls also check Show Borders and Reduce Bright Effects using documented platform availability.

### Touch targets
- Tap areas should be at least ~44x44 pt where reasonable.
- Expand hit areas without changing visual design when needed.
- For custom tappable containers, pair expanded hit areas with semantic role and activation behavior.

### Motion
- Avoid aggressive animations.
- Respect Reduce Motion preferences. Separately check Animated Images and Dim Flashing Lights for relevant content; these preferences are not interchangeable.

### WWDC26 / OS 27 readiness
- Resizable windows, iPhone Mirroring, iPad windowing, and toolbar overflow/minimization must preserve readable text, logical focus, and stable VoiceOver order.
- Liquid Glass materials, scroll edge effects, and translucent backgrounds must remain legible with Reduce Transparency and Increase Contrast enabled.
- Reorderable containers, swipe actions outside `List`, drag/drop, and gesture-first flows must expose purpose, value, actions, and feedback through assistive technologies.
- Gate newer APIs by their documented OS/platform availability, not by SDK year; preserve an accessible fallback for earlier deployment targets.
- Media playback screens must provide subtitle selection, respect the person's system subtitle style, and prefer standard AVKit playback controls when possible.
- On iOS/macOS 27 or later, verify generated subtitles can be selected when the device, language, and media source support them, and expose subtitle-style preview instead of forcing users to leave playback to compare styles.
- Custom players must preserve accessible subtitle selection and style-preview behavior rather than replacing it with a visual-only menu. Preview may temporarily replace active captions: stop it when dismissed and verify captions resume. Selecting a subtitle style changes the system preference.
- Feature names, tabs, menu items, and action labels should be concrete, predictable, localizable, and aligned with visible text when possible.
- App Intents, Siri, or view annotations should use names and entities that make sense without relying only on visual context.

### Assistive Access and release evaluation (when in scope)
- When the project supports or requests a tailored cognitive-accessibility experience on iOS/iPadOS 26 or later, review the `AssistiveAccess` scene and `accessibilityAssistiveAccessEnabled` environment value. Preserve essential tasks and familiar, prominent controls; do not prescribe a separate UI for every ordinary audit.
- For App Store release evaluations, map tested core tasks to the Accessibility Nutrition Labels criteria. Distinguish verified support from gaps; a passing screen audit does not establish app-wide support or authorize publishing declarations.

## Output contract

For confirmed findings, include the items below. If no issue is demonstrated, say so without manufacturing a priority or patch; list only relevant pending runtime checks. Missing context or a possible improvement is not a confirmed defect. P0 requires evidence that an essential task is blocked.

Your response must include:

1. Findings grouped by priority: P0 blocks a core task, P1 significantly degrades accessibility, and P2 covers lower-impact improvements. Tie severity to demonstrated user impact.
2. Patch-ready code snippets for confirmed issues only
3. A short manual testing checklist

Each finding must include:
- File/line or the supplied snippet location, plus the code or runtime evidence supporting the finding
- What is wrong
- Why it matters (1-2 lines)
- The exact fix

## Verification protocol

Every response must include:
- concrete manual test steps
- expected accessibility outcomes
- a brief regression-risk note
- include Voice Control or Switch Control checks when the finding affects activation, labels, grouping, or custom actions on iOS/iPadOS
- include VoiceOver Read All, Lines rotor, text selection, and cross-page continuation when reading content is in scope
- include subtitle selection and style-preview checks when media playback is in scope

- Use Accessibility Inspector to inspect the element tree and audit the affected screens when the app can be run. Distinguish structural audit results from actual VoiceOver interaction.
- Optionally evaluate `XCUIVoiceOverService` for navigation/speech tests only after confirming SDK, platform, and runtime support. Consult the reference: the reviewed documentation marks it beta, and tests must restore the original VoiceOver state even on failure.
- If a compatible UI test target already exists, consider `XCUIApplication.performAccessibilityAudit(for:_:)` for representative screen states. Confirm availability for the test platform; investigate findings before filtering any false positives.
- Automated audits do not validate the complete assistive-technology experience. Keep manual checks and report which checks were actually run, which remain pending, and the OS/device used.

Validation reference:
- Read [checklist.md](checklist.md) relative to this skill and include the relevant checks in the response. Do not create or overwrite a checklist in the audited project unless requested.

Expectation:
- behavior should remain unchanged except accessibility semantics and discoverability.

## Style rules

- Be concise and practical.
- Do not invent APIs.
- Every accessibility modifier must have a reason.

## Example request

"Review this SwiftUI view for iOS + macOS accessibility and return prioritized findings with a patch-ready diff."

## References

These references represent the primary sources used when evaluating and prioritizing accessibility findings.

- Apple Human Interface Guidelines – Accessibility  
  https://developer.apple.com/design/human-interface-guidelines/accessibility

- Accessibility in SwiftUI  
  https://developer.apple.com/documentation/swiftui/accessibility

- Supporting Dynamic Type in SwiftUI  
  https://developer.apple.com/documentation/swiftui/dynamic-type

- SwiftUI accessibility linked groups
  https://developer.apple.com/documentation/swiftui/view/accessibilitylinkedgroup(id:in:)

- SwiftUI accessibility direct touch
  https://developer.apple.com/documentation/swiftui/view/accessibilitydirecttouch(_:)

- SwiftUI accessibility adjustable actions
  https://developer.apple.com/documentation/swiftui/view/accessibilityadjustableaction(action:)

- SwiftUI page-turn trait
  https://developer.apple.com/documentation/swiftui/accessibilitytraits/causespageturn

- WWDC26 – Refine accessibility for custom controls
  https://developer.apple.com/videos/play/wwdc2026/220/

- WWDC26 – Enhance the accessibility of your reading app
  https://developer.apple.com/videos/play/wwdc2026/219/

- WWDC26 – Discover generated subtitles and subtitle styles
  https://developer.apple.com/videos/play/wwdc2026/256/

- Performing accessibility audits for your app
  https://developer.apple.com/documentation/accessibility/performing-accessibility-audits-for-your-app

- WWDC25 – Evaluate your app for Accessibility Nutrition Labels
  https://developer.apple.com/videos/play/wwdc2025/224/

- WWDC25 – Make your Mac app more accessible to everyone
  https://developer.apple.com/videos/play/wwdc2025/229/

- WWDC25 – Customize your app for Assistive Access
  https://developer.apple.com/videos/play/wwdc2025/238/

- SwiftUI accessibility action categories
  https://developer.apple.com/documentation/swiftui/accessibilityactioncategory

## Version

1.6.0
Pliki w paczce (3)
  • SKILL.md 15 KB
  • checklist.md 6 KB
  • references/apple-updates.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie swiftui-accessibility-auditor.

Migawka bazy z 13.11.2026 · wersja paczki c64202b8d45d (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100uikit-accessibility-auditor
    Audytuje ekrany UIKit pod kątem VoiceOver, Dynamic Type, Voice Control i struktury, z ustaleniami P0 do P2.
  • 100appkit-accessibility-auditor
    Audytuje interfejsy macOS AppKit pod kątem VoiceOver, nawigacji klawiaturą, kolejności fokusu i struktury semantycznej, zwracając ustalenia P0/P1/P2 z gotowymi poprawkami i krokami weryfikacji ręcznej.
  • 100ios-accessibility
    Pomaga wdrażać i audytować dostępność aplikacji SwiftUI na iOS i macOS: VoiceOver, Dynamic Type, etykiety, fokus, kontrast i obszary dotyku.
  • 90iOS Accessibility Skill
    Pomaga projektować, wdrażać i testować dostępność w iOS i iPadOS: VoiceOver, Voice Control, Switch Control i Dynamic Type.
  • 87ios-accessibility
    Sprawdza i poprawia dostępność aplikacji iOS w SwiftUI i UIKit: VoiceOver, Dynamic Type, kontrast i zgodność z WCAG 2.2.
  • 100swift-accessibility-pro
    Dodaje dostępność do aplikacji SwiftUI i UIKit: etykiety VoiceOver, Dynamic Type, kontrast kolorów, redukcję ruchu i testy.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.