fix: resolve WCAG accessibility violations across all app pages

[karkarl]

Motivation

A programmatic UI Automation accessibility scan of the OpenClaw Windows Companion app revealed 14 HIGH-severity and 8 MEDIUM-severity WCAG 2.1 violations. Screen reader users could not identify interactive controls (buttons, combo boxes) or navigate the sidebar effectively because elements lacked accessible names and decorative icons were announced unnecessarily.

Approach

Added AutomationProperties.Name to all interactive controls missing accessible names, and marked decorative navigation icons with AutomationProperties.AccessibilityView="Raw" so they are skipped by assistive technology.

Per-page fixes:

• Voice & Audio -- Named Refresh, Start, Stop buttons and Language combo box
• Sandbox -- Named 3 preset buttons (with descriptive text), 3 folder-access combo boxes, and the unavailable-action button
• Permissions -- Named the rule-action combo box
• Settings -- Named the notification-sound combo box
• Connection -- Set accessible name on gateway row cards (bound to gateway display name) and overflow "more options" button (localized "Options for {name}")
• HubWindow (global) -- Added AutomationProperties.Name="Main navigation" to NavigationView; marked all 20 ImageIcon elements as decorative

Validation

• Full repo build: passing
• Shared tests: 2691 passed, 0 failed
• Tray tests: 1505 passed, 0 failed
• Localization string added to all 5 locales (en-us, fr-fr, nl-nl, zh-cn, zh-tw) with proper translations

Notes

• Title bar button keyboard focus (Minimize/Maximize/Close not focusable) is a WinUI framework behavior with custom title bars -- standard keyboard shortcuts (Alt+F4, Win+Arrow) serve as alternatives and this is not actionable without framework changes.
• Color contrast and dynamic content (dialogs, flyouts) were not part of this scan and may need separate review.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 2, 2026, 6:58 PM ET / 22:58 UTC.

Summary
The branch adds WinUI AutomationProperties names to tray controls, marks static NavigationView ImageIcon elements decorative, and adds one localized gateway-options accessibility string across resource files.

Reproducibility: yes. from source inspection, not from a live scan: current main lacks the added accessibility names on the cited controls and the HubWindow nav icons are present without Raw markings. I did not run the UI Automation scan locally.

Review metrics: 1 noteworthy metric.

• UI sweep size: 11 files changed: 6 WinUI/code files and 5 locale files. The patch spans several app pages, so proof should cover representative controls rather than only build and unit-test output.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add a ## Real behavior proof section with redacted UI Automation or Narrator output, screenshots/video, or copied diagnostics showing the named controls and skipped decorative nav icons on the current PR head; updating the PR body should trigger a fresh ClawSweeper review, or a maintainer can comment @clawsweeper re-review.
• Mark high-contrast replacement icons and dynamically generated agent nav icons as decorative, then include that path in the proof.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists validation counts but does not include after-fix UIA/Narrator output, screenshot/video, copied diagnostics, logs, or linked artifacts from the current PR head. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Mantis proof suggestion
A desktop UIA/Narrator diagnostic proof would materially help because the changed behavior is accessibility-tree state, not ordinary visual appearance. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis visual task: on the PR head, use Accessibility Insights or Narrator to verify the newly named controls and that NavigationView decorative icons are skipped, including high-contrast mode.

Risk before merge

• [P1] The contributor has not provided current-head UI Automation, Narrator, screenshot/video, or copied diagnostic proof, so tests alone do not satisfy the repo's UI proof policy.
• [P1] The static NavigationView icon fix may leave decorative icons announced in high-contrast mode and for dynamically generated agent nav items because those icons are recreated in code without AccessibilityView.Raw.

Maintainer options:

1. Decide the mitigation before merge
   Land a narrow accessibility patch that covers static XAML, high-contrast, and dynamic nav icons, with required validation plus redacted current-head UIA or Narrator proof in the PR body.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• [P1] The remaining blockers are contributor-supplied real behavior proof and maintainer review of the high-contrast/dynamic icon coverage, not a safe automated takeover of this external PR.

Security
Cleared: The diff only changes WinUI UI semantics and resource strings; it does not touch secrets, dependencies, CI, install scripts, or command execution paths.

Review findings

• [P2] Mark replacement nav icons as decorative too — src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml:418

Review details

Best possible solution:

Land a narrow accessibility patch that covers static XAML, high-contrast, and dynamic nav icons, with required validation plus redacted current-head UIA or Narrator proof in the PR body.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection, not from a live scan: current main lacks the added accessibility names on the cited controls and the HubWindow nav icons are present without Raw markings. I did not run the UI Automation scan locally.

Is this the best way to solve the issue?

No, not yet: the proposed fix is mostly narrow, but the nav icon implementation must also mark high-contrast and dynamically generated icons decorative before the accessibility claim is complete.

Full review comments:

• [P2] Mark replacement nav icons as decorative too — src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml:418
  This only marks the XAML ImageIcon instances as Raw. In high-contrast mode HubWindow.xaml.cs replaces each nav icon with a new FontIcon, and dynamic agent nav items also come from BuildAgentItemIcon(); those replacement icons do not get AccessibilityView.Raw, so UIA/Narrator can still announce decorative glyphs in those paths. Please set the raw view when constructing or swapping these icons, ideally through a shared helper.
  Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.87

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 74604aebafef.

Label changes

Label changes:

• add P2: The PR addresses screen-reader accessibility across core tray pages, but the blast radius is bounded to UI semantics and resource strings.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists validation counts but does not include after-fix UIA/Narrator output, screenshot/video, copied diagnostics, logs, or linked artifacts from the current PR head. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: The PR addresses screen-reader accessibility across core tray pages, but the blast radius is bounded to UI semantics and resource strings.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists validation counts but does not include after-fix UIA/Narrator output, screenshot/video, copied diagnostics, logs, or linked artifacts from the current PR head. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its UI proof guidance applies because this PR touches tray UX, Settings, permissions, and Connection UI surfaces. (AGENTS.md:46, 74604aebafef)
• Proof skill read: The OpenClaw proof skill requires PR real behavior proof for UI changes, preferably screenshot/video or copied UI diagnostics from the current head. (.agents/skills/openclaw-proof-validation/SKILL.md:57, 74604aebafef)
• PR diff scope: The diff changes 11 files across WinUI pages, HubWindow, and locale resources to add accessibility names and decorative icon markings. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml:369, b164f1881a22)
• Real behavior proof gap: The PR body includes build/test validation and describes the prior scan, but it has no Real behavior proof section, linked UIA scan output, Narrator output, screenshot/video, or copied diagnostics showing the fixed state after the patch. (b164f1881a22)
• Navigation icon coverage gap: Current main replaces NavigationView icons with new FontIcon objects in high-contrast mode and builds dynamic agent icons in code; those replacement icons do not set AccessibilityView.Raw, so the PR's static XAML markings do not cover every nav icon path. (src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs:1417, 74604aebafef)
• Maintainer notes check: No .agents/maintainer-notes directory was present in the checkout, so there were no matching internal notes to apply for this PR. (74604aebafef)

Likely related people:

• shanselman: Git blame and git show tie the central HubWindow, Connection, Sandbox, Settings, Permissions, and VoiceSettings UI files to commit 4166e0f in the current checkout history. (role: introduced current WinUI baseline; confidence: high; commits: 4166e0fd63f8; files: src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml, src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs)
• bkudiess: Commit 74604ae and the merged connection snapshot work recently touched HubWindow.xaml.cs and nearby connection state UI behavior. (role: recent adjacent contributor; confidence: medium; commits: 74604aebafef; files: src/OpenClaw.Tray.WinUI/Windows/HubWindow.xaml.cs)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[shanselman]

Hi Karen — bot review with Scott's maintainer feedback folded in. First: thank you for this. The direction is absolutely right, and this is the kind of accessibility cleanup we want in the app. We are not at Scott's >=90% merge-confidence bar yet, but this looks very salvageable.

What is holding this one back:

1. We need real accessibility-tree proof from the PR head. The code changes are plausible, but this repo treats UI/a11y changes as behavior changes, so build/unit tests are not enough. Please add a ## Real behavior proof section to the PR body with current-head evidence: Accessibility Insights output, Narrator/UIA output, copied diagnostics, or screenshots/video showing the fixed controls have names and decorative icons are skipped.

2. The decorative icon fix only covers the static XAML icons. HubWindow.xaml marks the XAML ImageIcons as AccessibilityView="Raw", but the app also creates/replaces navigation icons in code paths such as high-contrast fallback and dynamic agent nav items. Those code-created/replacement icons still need the same Raw accessibility treatment, otherwise the claim "decorative nav icons are skipped" is only partially true.

3. Most new accessible names are hardcoded English. Some are correctly localized (ConnectionPage_GatewayOptionsA11y), but many XAML names like Rule action, Sandbox action, Documents access level, Voice language, and the preset labels are hardcoded. For a screen-reader fix, localized builds should not get English-only accessible names.

Bot-ready repair prompt you can give your coding agent:

Please repair PR #921 for OpenClaw. Keep the existing accessibility fixes, but make them complete and merge-ready.

Requirements:
1. Find all navigation icons created or replaced in code, especially HubWindow high-contrast fallback icons and dynamic agent navigation icons. Ensure every decorative navigation icon, whether from XAML or code, has AutomationProperties.AccessibilityView set to Raw. Prefer a shared helper so future icon creation stays consistent.
2. Localize every new AutomationProperties.Name added by this PR. Use x:Uid/resource-backed names for XAML controls, and LocalizationHelper for code-created controls. Add the needed resource entries for en-us, fr-fr, nl-nl, zh-cn, and zh-tw.
3. Preserve the already-correct ConnectionPage gateway-options localization.
4. Add or update focused tests/source contract tests where practical to pin dynamic/high-contrast icon Raw behavior and the resource keys for the new a11y names.
5. Update the PR body with a `## Real behavior proof` section containing current-head UIA/Narrator/Accessibility Insights output or screenshots that show representative fixed controls and decorative nav icons.
6. Run the repo-required validation: .\build.ps1, Shared tests, and Tray tests.

Once those are addressed and proof is in the PR body, this should be a much easier approval path. The core idea is good; we just need the implementation and proof to cover all the paths the app actually uses.