Skip to main content

Foundations

The cross-cutting accessibility rules that apply across most SwiftUI work, independent of any single component. Each rule is a best practice an AI applies while authoring SwiftUI code. Component patterns reference these rules rather than restating them.

Verification (audits, contrast measurement, on-device and human/LLM review) is a QA concern and lives in the QA layer, not here.

Native First​

Scopecomponent

Must Haves​

  • An interactive control exposes three things to assistive technology: its role, its current value or state, and its actions. Reach for the control that already does all three rather than assembling one that does none.
  • SwiftUI's own control is the reference implementation of that contract. Button, Toggle, Slider, Stepper, Picker, TextField, and DatePicker carry their traits, values, and actions without being told. A view that wraps one of them satisfies the contract too.
  • A control assembled from Text, Image, Shape, and .onTapGesture satisfies none of it, and has to declare all three by hand. When that is the only option, follow global.custom-control-representation.
  • When a component's own pattern states a fallback and its conditions, follow that pattern rather than this rule. The conditions under which the native control cannot be used differ by component.

Donts​

  • Do not treat a visual match as a semantic match. An HStack of a checkmark Image and a Text renders like a checkbox and exposes none of a checkbox's trait or state.
  • Do not replace a native control to gain a visual treatment a style modifier could have given it. A custom ToggleStyle keeps the underlying Toggle; a hand-drawn switch does not.

Touch Target Size​

Scopecomponent

Must Haves​

  • Every tappable control has a hit area of at least 24x24 points.
    • Inline targets within a run of text are exempt from this minimum.
    • For icon-only controls where the visible glyph is smaller than 24x24, use .frame(minWidth: 24, minHeight: 24) on the tappable element to extend the hit area without resizing the glyph.
  • Prefer a 44x44 point hit area where layout allows, matching Apple's Human Interface Guidelines. Treat 44x44 as the target and 24x24 as the non-negotiable floor.

Donts​

  • Do not rely on the visible glyph size alone to satisfy the minimum; extend the frame, not the icon.

Focus States​

Scopecomponent

Must Haves​

  • Every interactive control shows a visible system focus indicator for Full Keyboard Access, external-keyboard, and Switch Control users. The default Button, Toggle, and other native control styles preserve this automatically.

Donts​

  • Do not apply a custom style modifier (e.g., a ButtonStyle or ToggleStyle built with PlainButtonStyle or a bespoke shape) that suppresses the system focus indicator without restoring an equivalent visible focus treatment.

Semantic Color​

Scopecomponent

Must Haves​

  • Use semantic color for text and control surfaces: the design system's color tokens, or SwiftUI system colors (.primary, .secondary, Color(.label), Color(.systemBackground), .tint). These adapt to light and dark mode and are pre-vetted for contrast.
  • Use native control styles (.borderedProminent, .roundedBorder, the system Toggle) so a control's border, track, and state fills inherit their contrast instead of being hand-drawn.
  • Give any custom-drawn indicator (a selection outline, a custom toggle track) a semantic or design-token color rather than a fixed literal.

Donts​

  • Do not hardcode raw colors (Color.black, Color.white, or gray literals like Color(white: 0.7)) for text or control chrome; they do not adapt to the color scheme and often fail contrast.
  • Do not restyle a native control in a way that strips its default border, track, or state contrast.
  • Do not convey a control's state (on/off, selected) by color alone; keep a shape, fill, or label difference as well.

Dynamic Type​

Scopelayoutcomponent

Must Haves​

  • Use a built-in text style (.body, .headline, .caption) or a Text with no fixed point size, so text scales with the user's setting.
  • Size any glyph-tracking dimension (icon size, control height, glyph padding) with @ScaledMetric(relativeTo:) rather than a fixed point value.
  • Let text wrap and containers grow, and place long content in a ScrollView. For a TextField that can hold long input, use axis: .vertical.

Donts​

  • Do not set a fixed .font(.system(size:)) on content text.
  • Do not apply a truncating .lineLimit() to meaningful text, or wrap it in a fixed-height frame that clips it when enlarged.
  • Do not clamp the app's Dynamic Type range to protect a layout; fix the layout instead.

Custom Control Representation​

Scopecomponent

Must Haves​

  • Any control drawn from primitives (shapes, Canvas, Path, raw gestures) rather than a native control exposes a hidden native equivalent through .accessibilityRepresentation { }, supplying an accessible name, the current value (for a slider, stepper, or toggle), the correct role and trait, and the control's actions.
  • Bind the representation and the visible control to the same state so the announced value stays in sync as the user interacts.
  • For a control adjusted by dragging, add .accessibilityAddTraits(.allowsDirectInteraction) so a VoiceOver user can move it directly.

Donts​

  • Do not ship a custom-drawn control with only a tap gesture and a visual label; it is unreachable and inoperable for VoiceOver, Switch Control, and Full Keyboard Access users.
  • Do not hand-rebuild the contract with loose .accessibilityLabel, .accessibilityValue, and traits when a native representation supplies the role behaviors (adjustable actions, toggling) that loose traits alone do not.
Scopescreen

Must Haves​

  • Set a navigationTitle on every pushed screen so its screen change is announced by name.
  • Let the system manage VoiceOver focus on a NavigationStack push; do not force focus to the back button or an arbitrary element.
  • On pop, restore focus to the row that triggered the navigation by binding it with @AccessibilityFocusState and setting that focus when the pushed screen is dismissed, where the system does not restore it.
  • On an app whose iOS deployment target is iOS 18 or lower, also follow global.focus-binding-visibility for every focus binding this rule calls for.

Donts​

  • Do not push a screen with no title, which leaves the change without a clear spoken announcement.
  • Do not override the system's push-focus placement.

Announcements​

Scopecomponent

Must Haves​

  • When a dynamic change updates on-screen content without moving focus (a status message, an updated cart count, an inline validation result, a passive confirmation), speak it to VoiceOver by posting an AccessibilityNotification.Announcement("...") so the user hears the change without losing their place.
  • Post the announcement after the content actually appears, with a short delay (DispatchQueue.main.asyncAfter(deadline: .now() + 0.1)), so VoiceOver does not drop the message while it commits the view update.
  • Announce, rather than move focus, when the change is passive: informational content the user did not have to act on. Reserve moving focus (see global.focus-management) for content the user must interact with immediately, such as a newly presented overlay or a blocking error. This is the passive status-message path a component like dialog.alert redirects to when acknowledgement is not required.
  • In a UIKit-backed view, post the equivalent UIAccessibility.post(notification: .announcement, argument:).

Donts​

  • Do not update an on-screen status silently; showing new Text without posting an announcement leaves VoiceOver users unaware the state changed.
  • Do not move VoiceOver focus to a passive status message, which interrupts the user's place for information they did not choose to act on. Announce it instead.
  • Do not post the announcement with no delay in the same run loop as the state change; VoiceOver may drop it before it speaks.

Focus Management​

Scopelayoutcomponent

Must Haves​

  • When content appears that the user must act on immediately (a modal overlay, a newly revealed section, an error that blocks progress), move VoiceOver focus to it with a property bound by @AccessibilityFocusState, so the user is placed on the new content rather than left where they were.
  • When an overlay closes, restore VoiceOver focus to the control that opened it. Bind that trigger with @AccessibilityFocusState and set it true as the overlay dismisses. Native .alert(), .confirmationDialog(), .sheet(), .fullScreenCover(), and .popover() do not restore focus automatically, an Apple platform defect, so restore it explicitly: from each action's closure for alerts and confirmation dialogs, or from the onDismiss: handler for sheets and full-screen covers.
  • For a TextField, @AccessibilityFocusState does not return focus automatically after the keyboard is dismissed; restore it from the keyboard toolbar's Done button.
  • This rule covers overlays, dynamic content reveals, and text-field focus restoration. For an in-app push/pop NavigationStack transition, follow global.navigation-focus instead.
  • On an app whose iOS deployment target is iOS 18 or lower, also follow global.focus-binding-visibility for every focus binding this rule calls for.

Donts​

  • Do not leave VoiceOver focus stranded behind a dismissed overlay; without an explicit restore, focus can jump to the top of the screen or an arbitrary element.
  • Do not depend on @AccessibilityFocusState to return focus from a Menu or a DatePicker; it does not work with either, an Apple platform defect, so do not build a focus-restore contract around those controls.
  • Do not move focus to passive content that does not require action; announce it instead (see global.announcements).

Focus Binding Visibility​

Scopecomponent

Applies when the app's iOS deployment target is iOS 18 or lower, because the app can then run on iOS 18. Check the deployment target before applying this rule. When it is higher than iOS 18, skip this rule and bind focus as global.focus-management and global.navigation-focus describe.

Must Haves​

  • Bind .accessibilityFocused only while the element is exposed to accessibility. On iOS 18, a focus binding on a view that stays in the hierarchy while hidden from accessibility, through .opacity(0), .accessibilityHidden(true), or both, re-renders the hosting view in an endless layout loop: VoiceOver focus jumps to the status bar and the app stops responding. This applies to every focus binding that global.focus-management and global.navigation-focus call for.
  • Remove the binding in the same state update that hides the view. Drive the binding and the hide from the same state, including when a parent fades the whole container.
  • When a control fades or slides out but stays mounted, such as an auto-hiding toolbar or media playback controls, keep the drawn control as one stable view hidden with .accessibilityHidden(true), and overlay a Color.clear element made with .accessibilityElement() that carries the label, the .isButton trait, and an .accessibilityAction. Bind focus on that overlay only while the control is shown, and swap it for an unbound, hidden overlay when the control hides. The drawn control keeps its identity, so its transition still animates.
  • The clear overlay declares its label, trait, and action by hand on purpose, as an exception to global.custom-control-representation. It stands in for a plain button, so loose traits lose no role behavior.
  • Test focus moves and restores on iOS 18 with VoiceOver on.

Donts​

  • Do not remove the binding from an onChange after the view hides. The loop starts in the same update that hides the view, so a later change is too late.
  • Do not gate the binding with a conditional on the visible control (if/else, or a custom .if modifier). Each branch is a different view, so the control pops in and out instead of animating, even with VoiceOver off.
  • Do not leave a focus binding on a view that only looks hidden. A view at .opacity(0) is still mounted, and the binding still loops.