Skip to content

fix: read SwitchView to VoiceOver like a native toggle - #41

Merged
romchornyi merged 4 commits into
masterfrom
fix/switchview-voiceover
Oct 31, 2026
Merged

romchornyi merged 4 commits into
masterfrom
fix/switchview-voiceover

Conversation

@romchornyi

@romchornyi romchornyi commented Oct 31, 2026 •

Copy link
Copy Markdown
Collaborator

Issue being fixed or feature implemented

Closes #27.

SwitchView exposed itself to VoiceOver with a hand-made value, "On" / "Off", looked up with NSLocalizedString(_, bundle: .module). DashUIKit ships no localizations, so VoiceOver read the state in English in every locale. A native Toggle exposes the state as 1 / 0, which VoiceOver speaks in the user's language.

Measured before the change: the traits were already the same as a native Toggle (button + toggle bit, notEnabled when disabled), and activation already flipped the binding. The value was the only difference.

What was done?

  • SwitchView now describes itself with .accessibilityRepresentation { Toggle(isOn: $isOn) { EmptyView() }.labelsHidden().toggleStyle(.switch) } in place of the hand-made trait, value and action. The label, value, traits, disabled state and activation all come from the system control. The style is pinned so the role stays a switch on macOS, where the default Toggle style is a checkbox, and when a host sets toggleStyle on an ancestor.
  • The now unused "On" / "Off" strings are removed.
  • Docs: a SwitchView section in Buttons & inputs, covering how to name it and what UI tests read. Also rows in docs/README.md and the README catalog.
  • Public API is unchanged: SwitchView(isOn:).

UI tests and QA flows. The value that UI tests read changes from "On" / "Off" to "1" / "0", the same as any Toggle. Maestro's iOS driver uses the element's title, then its value, as text, so a label-less switch now matches "1" / "0". The Maestro flows in Roman's QA project that matched "On" / "Off" are updated to accept both values. They keep passing whichever DashUIKit revision dashwallet-ios has resolved. dashwallet-ios tracks master but resolves a pinned revision in Package.resolved.

How Has This Been Tested?

Accessibility tree dump on an iPhone 17 Pro simulator, iOS 27.0. The test package hosts each view in a UIHostingController with accessibility switched on and prints every accessibility element. Before = master, after = this branch. The table comes from the measurement of 2026-10-23: master at f61235e, where SwitchView and MenuItem are the same as today's master apart from the thumb's shadow color, and this change before .toggleStyle(.switch) was added. .switch is already the default Toggle style on iOS. A re-run on the current heads did not finish, because the simulator's test host hung under host load.

Element State Native Toggle SwitchView before SwitchView after
bare on, enabled label —, value 1, button + toggle label —, value On, button + toggle label —, value 1, button + toggle
bare on, disabled label —, value 1, button + toggle, notEnabled label —, value On, button + toggle, notEnabled label —, value 1, button + toggle, notEnabled
bare off, enabled label —, value 0, button + toggle label —, value Off, button + toggle label —, value 0, button + toggle
bare off, disabled label —, value 0, button + toggle, notEnabled label —, value Off, button + toggle, notEnabled label —, value 0, button + toggle, notEnabled
row, combined on, enabled label Advanced, value 1, button + toggle label Advanced, value On, button + toggle label Advanced, value 1, button + toggle
row, combined on, disabled label Advanced, value 1, button + toggle, notEnabled label Advanced, value On, button + toggle, notEnabled label Advanced, value 1, button + toggle, notEnabled
row, combined off, enabled label Advanced, value 0, button + toggle label Advanced, value Off, button + toggle label Advanced, value 0, button + toggle
row, combined off, disabled label Advanced, value 0, button + toggle, notEnabled label Advanced, value Off, button + toggle, notEnabled label Advanced, value 0, button + toggle, notEnabled

SwitchView's element is identical to the native Toggle's in all 8 states:

  • on / off × enabled / disabled;
  • bare, and inside a row combined with .accessibilityElement(children: .combine).

Activation (accessibilityActivate()):

  • enabled: flips the binding once per activation;
  • disabled: refused, and the binding is unchanged.

Both behaved the same before.

Before / After

Before After
Light
Dark
  • No visual change (refactor, tests, docs). Say why in "What was done?".

No pixels change. accessibilityRepresentation replaces only what assistive technologies see; the drawing chain (track, ThumbView, colors, animation, tap gesture) is untouched. The accessibility table above is the evidence for the change.

Breaking Changes

None in the API. UI tests that matched the switch's value "On" / "Off" must accept "1" / "0", as for a system Toggle.

Checklist:

  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have added or updated relevant unit/integration/functional/e2e tests
  • I have made corresponding changes to the documentation

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Added SwitchView, a design-system switch with a native switch control available to VoiceOver. It supports optional labeling and reflects whether it is enabled.
  • Documentation
    • Added SwitchView to the component catalog and Buttons & Inputs guide, including details about its appearance, accessibility, and use in menu items.

romchornyi and others added 4 commits October 31, 2026 15:22
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SwitchView set a hand-made accessibility value "On"/"Off" that DashUIKit
never localizes, so VoiceOver read it in English in every locale. Its
accessibility representation is now a label-hidden Toggle, so the value,
traits, disabled state and activation are the system control's, and
VoiceOver speaks the state in the user's language.

Documents SwitchView in Buttons & inputs and the catalogs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On macOS the default Toggle style is a checkbox, and a host's toggleStyle
would also reach the representation. Docs: say when to use SwitchView vs
DashSwitch, and that the 1/0 value is what iOS UI tests read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 31, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Walkthrough

SwitchView now uses a hidden-label native Toggle for its accessibility representation. The component catalog and documentation now include SwitchView and describe its usage and accessibility behavior.

Changes: SwitchView accessibility and documentation

Layer / File(s) Summary
Native Toggle accessibility representation
Sources/DashUIKit/Components/Switch/SwitchView.swift
Replaced the manually supplied toggle traits, state value, and action with a hidden-label native Toggle bound to isOn. Added implementation documentation and removed localized state-value constants.
Component catalog and usage documentation
docs/buttons-and-inputs.md, docs/README.md, README.md
Added SwitchView to the component catalogs and documented its usage, enabled state, and accessibility behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Possibly related PRs

Suggested reviewers: jeanpierreroma

Merge Risk: Minimal · up to 83bb2

The native Toggle representation and documentation changes have no established merge-blocking defect. Standalone accessibility-label propagation remains unverified.

Pre-merge checks: Passed 5
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: making SwitchView read to VoiceOver like a native toggle.
Linked Issues check Passed Issue #27 asks to check SwitchView's VoiceOver traits and state value against a native Toggle, then either add button and toggle traits or build the switch on a Toggle with system semantics. The diff …
Out of Scope Changes check Passed The reviewed diff for Sources/DashUIKit/Components/Switch/SwitchView.swift changes only the accessibility layer of SwitchView, removes the two now-unused NSLocalizedString constants ("On"/"Off"), and …
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Full details: Linked Issues check

Explanation

Issue #27 asks to check SwitchView's VoiceOver traits and state value against a native Toggle, then either add button and toggle traits or build the switch on a Toggle with system semantics. The diff replaces the hand-made .isToggle trait, accessibilityValue ("On"/"Off") and accessibilityAction in Sources/DashUIKit/Components/Switch/SwitchView.swift with .accessibilityRepresentation { Toggle(isOn: $isOn) { EmptyView() }.labelsHidden().toggleStyle(.switch) }. This uses the system Toggle semantics, which is the second option in the issue. The PR's accessibility-tree dump (iOS 27.0, simulator) reports the same label, value (1/0), traits (button + toggle) and notEnabled state as a native Toggle in 8 states, and activation flips isOn in both before and after. The issue's risks (missing activation hint, duplicate state announcement) are addressed by that comparison. Limits: the comparison is a tree dump, not a live VoiceOver session, and the re-run on the current head did not complete. The 'before' table was measured on master before .toggleStyle(.switch) was added; the PR states .switch is already the iOS default. The issue does not request automated tests, so their absence does not fail this check.

Full details: Out of Scope Changes check

Explanation

The reviewed diff for Sources/DashUIKit/Components/Switch/SwitchView.swift changes only the accessibility layer of SwitchView, removes the two now-unused NSLocalizedString constants ("On"/"Off"), and adds doc comments. These directly implement issue #27. The PR also adds a SwitchView section to docs/buttons-and-inputs.md, catalog rows in docs/README.md and the README catalog. These document the changed behavior and are related to the change. The public API is unchanged (SwitchView(isOn:)), and the drawing code (track, ThumbView, colors, animation, tap gesture) is not altered per the summary. The Maestro flow updates mentioned in the PR description are in an external QA project, not in this repository diff, so they are not evaluated here. No unrelated change was found in the reviewed paths.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 1 files. (3 skipped: 3 unsupported.)

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@romchornyi-pitcrew

romchornyi-pitcrew commented Oct 31, 2026 •

Copy link
Copy Markdown

✅ Review posted for commit 83bb23e · triage: normal · approve · took 4 min

@romchornyi-pitcrew romchornyi-pitcrew left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ no blockers · no majors · 1 untracked gap · 6 non-blocking recommendations — reviewed at 83bb23e6a4

Level Verdict
1 · Idea ✅ valid #27: the state was read as the English "On" / "Off" in every locale. Taking the semantics from a real Toggle is the second fix #27 proposes
2 · Architecture ✅ right layer The component owns its semantics. The public API is unchanged
3 · Completeness 🟡 untracked gap The same English-only accessibility strings remain elsewhere in the package (below)
4 · Code ✅ clean The representation replaces all three hand-made pieces (trait, value, action), so nothing is announced twice. .animation(value: isOn) covers toggles that come through the representation. .disabled reaches the Toggle through the environment. The removed strings were never translated (the package has no .lproj)

Untracked gap

  • private var accessibilityValue: String {
    guard case .state(let state) = criterion.mark else { return "" }
    switch state {
    case .pending:
    return NSLocalizedString("Not checked yet", bundle: .module, comment: "DashUIKit")
    case .checking:
    return NSLocalizedString("Checking", bundle: .module, comment: "DashUIKit")
    case .met:
    return NSLocalizedString("Met", bundle: .module, comment: "DashUIKit")
    case .failed:
    return NSLocalizedString("Not met", bundle: .module, comment: "DashUIKit")
    case .blocking:
    // Not just unmet: this is the rule that stops the user going on,
    // which the red text says to a sighted user.
    return NSLocalizedString("Not met, required to continue", bundle: .module, comment: "DashUIKit")
    — Criteria's accessibility values ("Met", "Not met", "Checking", …) and other NSLocalizedString(_, bundle: .module) labels resolve to English in every locale, for the same reason as #27: DashUIKit ships no localizations. Worth an issue for the class (ship .lproj files, or have hosts pass Text), so this does not stay a per-component fix.
6 non-blocking recommendations
  1. dashwallet-ios UI test looks the switch up as a button — https://github.com/dashpay/dashwallet-ios/blob/develop/DashWalletScreenshotsUITests/DashWalletScreenshotsUITests.swift#L92-L115 — AdvancedModeRowUITests finds the switch as row.buttons.firstMatch. Its comment says this relies on SwitchView "not being a Toggle" and carrying an On/Off value. With a real Toggle as the representation, XCUITest will most likely report a .switch. The query then finds nothing, or matches the row's own button and opens the explainer, which is exactly what the test guards against. The app tracks DashUIKit master through a pinned Package.resolved, so this lands at the next resolve. The screenshots UI test target is not in dashwallet-ios CI (unit-tests.yml runs dashwallet-dashpay only), so the failure would be silent. A companion app change (row.switches.firstMatch and the comment) linked from here would cover it. The PR's Breaking Changes mention only the value. (test code verified on develop; the element type is not verified at runtime)
  2. MenuItem's .toggle switch has no name —
    public var body: some View {
    HStack(spacing: 10) {
    leading
    central
    Spacer()
    trailing
    }
    .padding(10)
    }
    and
    // `SwitchView`, not `Toggle`: the system switch is green and sized
    // by UIKit, so a menu row rendered here did not match the switch
    // the same design system hands out everywhere else. It reads
    // `isEnabled` from the environment, which `.disabled` sets.
    SwitchView(isOn: isOn)
    — MenuItem neither combines its children nor labels the switch with its title, so VoiceOver reads "switch, off" and the title as separate stops. This predates the PR. The new docs say "MenuItem's .toggle accessory uses it" and, in the next sentence, that a combining row supplies the label, which together suggest MenuItem does that. Labelling the switch with title in MenuItem, or one sentence in the docs, would fix it.
  3. The shipped head was not measured —
    .accessibilityRepresentation {
    Toggle(isOn: $isOn) { EmptyView() }
    .labelsHidden()
    .toggleStyle(.switch)
    }
    — by the description, .toggleStyle(.switch) came after the accessibility-tree run, and the re-run hung. The .accessibilityLabel(_:) path the docs recommend, and macOS, are not in the table. A unit test that hosts the view and asserts traits and value, as the description's harness did, would pin all three.
  4. Docs promise more than was measured —
    ## SwitchView
    File `Components/Switch/SwitchView.swift`
    The design system's switch: the DS track and thumb drawn in SwiftUI, on iOS and macOS.
    `MenuItem`'s `.toggle` accessory uses it. It takes its enabled state from the environment,
    so `.disabled(true)` dims it and stops the tap. Use it where the DS switch is drawn;
    `DashSwitch` is the system switch with the DS tint, UIKit only.
    ```swift
    @State private var isOn = false
    SwitchView(isOn: $isOn)
    .accessibilityLabel("Advanced mode") // optional, see below
    ```
    To assistive technologies and UI tests it is a native switch-style `Toggle` with a hidden
    label: the same traits, the same state value, which VoiceOver speaks in the user's
    language, dimmed when disabled, and a double-tap flips `isOn`. Its own label is empty:
    name it with `.accessibilityLabel(_:)`, or put it in a row that combines its children
    (`.accessibilityElement(children: .combine)`), which then reads the row's text as the
    label and the switch's state as the value. On iOS, UI tests read the state as the value
    `"1"` / `"0"`, as for any `Toggle`.
    — "on iOS and macOS" and "name it with .accessibilityLabel(_:)" were not part of the measured matrix. Either measure them or narrow the wording. (not verified)
  5. One control, two descriptions — — a DS ToggleStyle on a real Toggle would bring native semantics, plus keyboard focus on macOS, which the representation does not give. It would also merge SwitchView and DashSwitch (which has a DashToggleStyle TODO). That is out of scope here, but a better long-term shape. (not verified)
  6. Doc comment: "a blue track" —
    /// The design system's switch: a blue track with a white thumb, drawn by hand
    /// rather than tinting the system `Toggle`.
    — the track is blue only when on and enabled; off is gray300Alpha50, disabled black1000Alpha20.
Review details

Tier: normal (accessibility semantics of a public component). Levels 1–3 inline, against #27. Level 4 used the general lane (/code-review high) and the UI/accessibility specialist lane, which covered:

  • host modifiers outside the representation;
  • MenuItem and the dashwallet-ios ConnectionRow / Settings rows;
  • disabled state, animation, double announcement, macOS, DashSwitch.

The verifier read the dashwallet-ios UI test and its CI workflows, and MenuItem / Criteria at this head. ConnectionRow in the app wraps the switch in its own .accessibilityElement() and is unaffected. CI was green at this head.

🤖 Reviewed with Claude Code

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional comments: 1
Sources/DashUIKit/Components/Switch/SwitchView.swift-56-57: 1

56-57: Minor · Potential issue · Quick win

Unverified finding
We couldn't verify this from the code. It is shown for review, not as a verified issue.

The representation's Toggle has an EmptyView label and hides labels, so SwitchView may lose a caller-supplied .accessibilityLabel(_:) if SwiftUI does not transfer that modifier to the represented control.

VoiceOver announces an unnamed switch rather than “Wi-Fi” and its state.

This can occur when: A caller labels a standalone SwitchView with .accessibilityLabel("Wi-Fi").


Review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between 402db65 and 83bb23e.

Files selected for processing: 4
  • README.md
  • Sources/DashUIKit/Components/Switch/SwitchView.swift
  • docs/README.md
  • docs/buttons-and-inputs.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SwitchView: check the VoiceOver traits (only .isToggle, no button trait)

2 participants