microsoft / microsoft/win-dev-skills
[Docs]: Recommend AxeWindowsCLI for automated accessibility checks
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 442
- Forks
- 33
- Avg merge
- 2h 59m
- Merged PRs (30d)
- 11
Description
Thanks for taking the time to flag a documentation issue! Broken cross-references between skills, outdated examples, and missing prerequisites are especially valuable to know about.
Where is the issue?
plugins/winui/skills/winui-ui-testing/SKILL.md, especially the accessibility testing guidance and recipes.
What's wrong?
The WinUI UI testing skill does not currently provide a documented recipe for using the official AxeWindowsCLI for autonomous Windows accessibility checks. The guidance should distinguish responsibilities clearly: use AxeWindowsCLI for automated accessibility rule checks, and continue using the official winapp CLI for UIA targeting, raw evidence, screenshots, and interaction.
Empirical evidence from the parent experiment:
- AxeWindowsCLI 2.4.2 found exactly two real unnamed-focusable-control defects in Paint.
- Calculator was clean.
- Settings failed with an empty
desktopElementsresult, so the skill needs to explain unavailable/failed scans rather than treating them as clean. - Accessibility Insights used the same Axe 2.4.2 rules, but its workflow was too intrusive for autonomous agents.
- Axe scans took roughly 12–15 seconds and emitted rich rule/property details plus a
.a11ytestartifact. - CLI output is human-readable text; error, finding, and clean exit codes need to be documented explicitly.
- The guidance must not make a compliance claim.
Suggested fix
Update the skill documentation and recipes only; do not implement an audit engine. Add installation and version-pinning instructions for AxeWindowsCLI 2.4.2, a minimal command/example for running a scan, interpretation of clean/finding/error outcomes, and graceful guidance when the CLI is unavailable or a scan fails. Keep winapp CLI as the UIA harness for locating/targeting elements, collecting raw evidence, taking screenshots, and performing interactions. Explain that Axe findings are automated rule results, not a compliance certification, and show how to preserve the rich text and .a11ytest output.
Additional context
The recommendation should favor a non-intrusive CLI workflow suitable for autonomous agents. Accessibility Insights can be mentioned as a manual/investigative alternative, but should not be the primary autonomous-agent recipe because it was too intrusive in the experiment.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with plugins/winui/skills/winui-ui-testing/SKILL.md, focusing on its accessibility testing guidance and recipes. Document AxeWindowsCLI 2.4.2 installation, scanning, output and failure interpretation while preserving winapp CLI responsibilities; done means the recipe covers findings, clean and error outcomes, unavailable scans, artifacts, and avoids compliance claims.
Written by the indexing model from the issue text.
Assessment
- Domain
- accessibility, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100