pr-accessibility

# Native Windows Accessibility Review Use this procedure for native WinUI/XAML/C++ accessibility review. The caller owns PR metadata, immutable revisions, trust boundaries, permitted edits, publication, and safe-output policy. This skill owns domain analysis, repository-specific evidence gathering, and focused validation. ## Mechanical evidence Use [`scripts/accessibility_review.py`](./scripts/accessibility_review.py) for deterministic preparation and final-report validation. It classifies changed native UI files, emits stable source signals, records unavailable runtime checks, and enforces the high-only repair contract. Treat its findings as evidence leads, not complete accessibility conclusions. The source rules are intentionally conservative: - `AXSTATIC001`: a changed interactive control explicitly placed in the raw UIA view. This is HIGH impact but medium confidence until peer, style, and intent are inspected, so it is not automatically repairable. - `AXSTATIC002`: an apparently icon-only changed control with no local name source. Treat as MEDIUM needs-review evidence. Content, `x:Uid`, bindings, styles, labels, and peers can provide a name. - `AXSTATIC003`: a changed literal accessible name. Treat as MEDIUM, high-confidence localization evidence, not an accessibility auto-fix. ## Review procedure 1. Read the caller-provided prepared report and immutable base/head identifiers. When supplied, use `comparison_base_sha` for the actual feature diff; `trusted_base_sha` identifies trusted workflow code, not base-only PR changes. Use the trusted staged skill and read-only prepared evidence when supplied; do not load PR-head instructions or regenerate that evidence. Read the exact changed hunks, not only summaries or changed-line snippets. For deletions and renames, use prepared `source_evidence` to distinguish immutable base content from a present head blob. Trace removed operations or replacement locations; never apply a head repair to a deleted file. 2. Inspect companion XAML, C++ implementation/header, styles/templates, `x:Uid` source resources, custom AutomationPeers, and focused UIA tests needed to understand the changed operation. 3. Determine accessible name, role/control type, value/state, label, description/help text, and required UIA patterns. Do not report a missing literal `AutomationProperties.Name` by itself: - standard controls can derive names from content or headers; - `x:Uid`, bindings, styles/templates, `LabeledBy`, and peers can supply accessible data; - decorative elements can intentionally be absent from control/content view. 4. Trace keyboard-only activation and traversal. Check tab and arrow-key order, access/accelerator keys, dialog/flyout entry and exit, focus restoration, traps, stashed/restored panes, and custom key handlers. 5. Trace screen-reader state changes. Check `LiveSetting`, UIA notification events, meaningful payloads, duplicate/noisy announcements, and whether disabled, unavailable, loading, and busy states are exposed. 6. Inspect visual accessibility: high-contrast and theme resources, color-only communication, text wrapping/trimming, fixed dimensions, 200% text/display scaling, clipping, reflow, and scroll reachability. - When a change replaces local control properties with a shared style, compare every removed alignment, size, wrapping, and focus-related property with the style's actual setters and the framework default. Do not assume the style preserves omitted behavior. - In Grid layouts, account for the default `Stretch` alignment and rows whose height is driven by wrapped sibling text. A picker or button that previously used centered/natural sizing can otherwise expand to the sibling's full height. 7. Apply the same review to tabs, panes, settings controls, titlebar controls, and agent cards. Preserve repository behavior and custom peer semantics. 8. Classify each finding with severity independent from confidence: - **HIGH**: a significant operation is inaccessible, with direct repository-specific evidence. - **MEDIUM/LOW**: advice or a risk requiring runtime confirmation. Unsafe or uncertain HIGH findings remain `remaining` or `blocked`. 9. Repair only a high-confidence HIGH defect when the caller exposes a trusted recipe for it. The only current recipe is `AXSTATIC001-remove-raw-view`: remove exactly the raw-view property from the matching prepared standard interactive control, which must already have a name source. Make no other hunk or file change; preserve the original encoding, BOM, and line endings. Set `repair_recipe` to that value and leave `validation` empty for the trusted validator to attest. A style reference alone is not a trusted name source. If naming depends on style setters, leave the finding remaining/blocked; the current recipe does not resolve styles to authenticate that name. 10. Keep runtime-dependent fixes `remaining` or `blocked`. The agent cannot authenticate its own command/result JSON, and the Ubuntu workflow cannot validate UIA patterns, focus, announcements, rendering, or scaling. 11. Re-read the complete final diff. Never repair MEDIUM/LOW findings merely to reduce the report, and never add unrelated or untracked files. Fork review is read-only. When the caller requires one commit per finding, commit each eligible repair separately on the verified PR-head branch before editing the next. Link each commit in that finding's summary row, then request one publication for the complete series. Do not change branches or edit after capture; the trusted gate verifies the captured series against the recipe-verified candidate. Follow the caller's publication policy: when the PR reviewer owns build/test validation, do not add post-fix builds, tests, native jobs or environment provisioning as prerequisites to an eligible repair commit or push. Preserve caller-configured native checks used to discover problems in the original revision; fix-publication policy does not disable that review. ## Localization Accessible names and descriptions are customer-facing. Reuse existing localized resources or bindings. Never add hard-coded English accessibility text. When a repair needs a new or changed string, leave a concrete blocking finding for the localization workflow. Do not edit `.resw` or locale YAML from this skill. ## Required review record For a PR review, account for every `required_review_checks` ID from the prepared evidence in `review_checks`, including dimensions with no static signal. Each record names the classified changed files it covers, explains the actual repository mechanism in `assessment`, and cites immutable source as `{file, revision: "head"|"base", line, text}`. Use companion styles, handlers, resources and peers where needed; `text` must quote the cited source line. The union of records must cover every classified changed file. Use `source-reviewed` only after tracing the relevant source behavior. Use `not-applicable` only with source evidence explaining why that dimension does not apply to the changed operation. Use `runtime-required` when source cannot establish the accessible behavior or a runtime-dependent finding needs confirmation; specify the exact scenario and expected observation. These statuses are not native PASS attestations. Do not turn a missing test into `not-applicable` or claim an Axe scan proves focus, announcements or layout. Report review checks even when there are no findings. A static-signal-only report, generic "followed the skill" statement, or empty findings array does not satisfy this procedure. The trusted gate checks coverage and source citations, not the semantic truth of the model's assessment. Domain judgment must still be supported by the actual source and any available runtime evidence. ## Axe.Windows and runtime checks [Axe.Windows](https://github.com/microsoft/axe-windows) is a native Windows UI Automation scanner. It evaluates runtime UIA hierarchy, properties, patterns, values, and children against independent Error, Warning, and NeedsReview rules. It is not a XAML/C++ source linter. Use Axe.Windows only with a built application on Windows and an interactive desktop. Navigate to every affected state, scan the exact process/window, and retain the caller-supported scan artifacts. Retain `.a11ytest` output when its capture prerequisites work. The pinned Axe.Windows 2.4.2 native harness uses the supported automation API with `OutputFileFormat.None`: `.a11ytest` generation captures a screenshot and has failed with a Win32 invalid-handle error even when UIA scanning works. In that lane, retain structured Axe rule results, per-state UIA hierarchy JSON, state/process/source identity, and logs. JSON is not an `.a11ytest` file and does not provide its screenshot or replay capabilities; record that capture gap rather than claiming equivalent output. The Windows smoke job covers FRE, Agents settings, and FRE settings after invoking Next. It scans the original immutable revision, not a proposed fix, and is independent of repair publication. The source agent's unavailable runtime records are not the separate Windows job's result; use that job's artifacts and outcome. This smoke does not cover every affected product state. Pair scans with: - keyboard-only traversal, activation, focus restoration, and trap checks; - UIA pattern invocation and property/state assertions; - Narrator observation of names and announcements; - high-contrast/theme and color-use inspection; - 200% text size/display scale, clipping, wrapping, and reflow checks. Axe.Windows does not by itself prove keyboard journeys, focus restoration, spoken announcement quality, rendered contrast, or scaling/clipping. When Windows, the built app, Axe.Windows, or an interactive desktop is unavailable, record the check as `SKIPPED` or `BLOCKED`, never `PASS`. Browser axe-core and Playwright accessibility snapshots are not native WinUI UIA coverage. ## Repository test path Prefer a focused test in `src/cascadia/WindowsTerminal_UIATests` for UI state, names, control types, patterns, and keyboard focus. Existing lower-level UIA provider behavior also lives under `src/host/ft_uia`. Do not add Axe.Windows or another dependency unless the caller permits a dependency change. Without that dependency and an interactive Windows lane, document the exact native gap rather than substituting a Linux source check. ## Findings Use the caller's machine-readable schema. Every finding must include a stable ID, severity, confidence, source/head SHA, file/line, observed behavior, expected behavior, user impact, evidence, proposed fix, validation, and disposition. Preserve prepared deterministic IDs when they apply. Derive new IDs from rule, normalized path, line, and normalized evidence. Emit only actual findings. Do not serialize false positives as findings and do not invent severities or dispositions outside the caller's enum. Every prepared signal must be accounted for: preserve its stable ID in an actual finding, or explain its dismissal separately in `dismissed_signals` with specific repository `reason` and `evidence`. No duplicate, unknown, unexplained, or silently omitted signal is permitted. Do not downgrade a prepared HIGH under its original ID: explain a false-positive dismissal explicitly, then use a distinct ID for any independent lower-severity finding. Confidence remains independent of severity. The trusted gate checks coverage, not the semantic truth of a model's dismissal. Put only actually executed checks in `validation`, using the caller's required object shape; describe unavailable checks in `runtime_checks`, never as validation strings. For a proposed trusted static repair, leave `validation` empty. The native gate rejects model-authored PASS claims, verifies the complete candidate against its recipe, and adds the trusted attestation itself. When the caller requests a human-readable Markdown summary, write it directly using its template. Keep the outcome in prose and actual results in a table: HIGH before MEDIUM before LOW, unresolved HIGH before fixed HIGH. Explain each blocker and the specific change, decision, or runtime check needed from a human. Keep it consistent with the structured report; do not claim publication or native-job success that the source agent cannot observe. Keep runtime prerequisites separate from findings. Do not turn unavailable native evidence into success. Make reruns idempotent and avoid duplicate comments. ## Validation ```powershell python .github\skills\pr-accessibility\tests\test_accessibility_review.py gh aw compile ghaw-pr-accessibility --no-check-update gh aw validate ghaw-pr-accessibility --no-check-update ```