microsoft / microsoft/win-dev-skills

[Docs]: Recommend AxeWindowsCLI for automated accessibility checks

Open Beginner friendly
#139 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
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 desktopElements result, 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 .a11ytest artifact.
  • 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.