MaarkssDN/Birthub-360 / .agents/skills/axe-a11y
axe-a11y
VerifiedUse whenever pages or components need automated accessibility scanning: axe-core via axe.run(), @axe-core/playwright or the CLI on every PR, rule configuration and CI-gateable results, plus pa11y, Lighthouse CI accessibility, WAVE and IBM Equal Access (Section 508) in its references.
| File | Kind | Size |
|---|---|---|
| .tessl-plugin/plugin.json | config | 409 B |
| SKILL.md | skill md | 9.1 KB |
| evals/dialog-fix-signed-off-by-a-green-run/criteria.json | config | 7.5 KB |
| evals/dialog-fix-signed-off-by-a-green-run/task.md | markdown | 10.1 KB |
| evals/pr-bot-has-said-no-issues-for-four-months/criteria.json | config | 7.6 KB |
| evals/pr-bot-has-said-no-issues-for-four-months/task.md | markdown | 10.1 KB |
| evals/three-scanners-one-number-for-the-board/criteria.json | config | 7.6 KB |
| evals/three-scanners-one-number-for-the-board/task.md | markdown | 14.6 KB |
| evals/two-symptoms-since-we-added-accessibility/criteria.json | config | 5.5 KB |
| evals/two-symptoms-since-we-added-accessibility/task.md | markdown | 7.3 KB |
| evals/zero-tolerance-announced-for-monday/criteria.json | config | 7.7 KB |
| evals/zero-tolerance-announced-for-monday/task.md | markdown | 10.0 KB |
| references/ibm-equal-access.md | markdown | 5.2 KB |
| references/lighthouse-a11y.md | markdown | 5.5 KB |
| references/pa11y.md | markdown | 5.0 KB |
| references/results-and-config.md | markdown | 3.0 KB |
| references/wave.md | markdown | 4.8 KB |
references/pa11y.md
View on GitHub# pa11y - CLI scanner (htmlcs + axe engines)
Companion reference for `axe-a11y`. Consult when the project needs scriptable
a11y scans without a full test framework (CI cron job, docs publication,
static-site CI), or when a Node-stack project wants a single-command scanner
instead of framework-integrated axe tests.
pa11y is "your automated accessibility testing pal" - a Node.js CLI that runs
a11y tests on a page via the command line or a programmatic API
([pa11y][readme]). It can use HTML CodeSniffer (htmlcs, default) or axe-core
as the underlying engine. If the project already runs Playwright / Cypress
with axe-core, prefer the direct axe integration in SKILL.md - pa11y adds a
layer.
[readme]: https://github.com/pa11y/pa11y
## Install and run
```bash
npm install -g pa11y # or --save-dev per-project
pa11y https://example.com
```
(Per [pa11y][readme].)
## Key flags
| Flag | Effect |
|----------------------|---------------------------------------------------------------|
| `--reporter <name>` | Output format: `cli` (default), `csv`, `json`, `html`, `tsv`. |
| `--standard <name>` | WCAG standard: `WCAG2A`, `WCAG2AA` (default), `WCAG2AAA`. |
| `--runner <name>` | Engine: `htmlcs` (default) or `axe`; repeat to run both. |
| `--include-warnings` | Include warning-level issues (excluded by default). |
| `--include-notices` | Include notice-level issues. |
| `--ignore <rules>` | Skip specific rules (comma-separated). |
| `--threshold <n>` | Allow up to N issues before failing (exit-code gate). |
| `--timeout <ms>` | Page-load timeout. |
| `--config <file>` | Use a `.pa11yrc` config file. |
pa11y's `WCAG2AA` standard is 2.0/2.1; WCAG 2.2 SCs (2.4.11, etc.) need
`--runner axe` alongside `htmlcs`.
## Multi-URL with pa11y-ci
`pa11y-ci` (https://github.com/pa11y/pa11y-ci) batches a URL set from a
`.pa11yci` config and exits non-zero if any URL exceeds threshold - the
canonical CI gate signal:
```json
{
"defaults": {
"standard": "WCAG2AA",
"runners": ["axe", "htmlcs"],
"includeWarnings": true,
"threshold": 0
},
"urls": [
"https://staging.example.com/",
"https://staging.example.com/dashboard",
"https://staging.example.com/checkout"
]
}
```
## Programmatic API and results structure
```javascript
const pa11y = require('pa11y');
const results = await pa11y('https://example.com', {
standard: 'WCAG2AA',
runners: ['axe', 'htmlcs'],
includeWarnings: true,
});
console.log(results.issues);
```
`results.issues[]` holds one object per finding with `code`, `type`
(error / warning / notice), `typeCode`, `selector`, `context`, `message`, and
`runner`. When both engines run, the same defect appears twice under
different codes - WCAG-SC-coded from htmlcs
(`WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail`), rule-coded from axe
(`color-contrast`) - and `a11y-violation-gate` collapses the pair via its
`fingerprint` field.
## Worked example
```bash
pa11y --standard WCAG2AA \
--runner htmlcs --runner axe \
--include-warnings \
--reporter json \
--threshold 0 \
https://staging.example.com/checkout > pa11y-results.json
```
The run exits non-zero (threshold 0 exceeded) and `pa11y-results.json` holds
the `issues[]` array for the gate.
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|-------------------------------------------------|---------------------------------------------------------------------|-----|
| Default `WCAG2AA` without WCAG 2.2 specifics | The htmlcs standard is 2.0/2.1; 2.2 SCs need the axe runner. | Always include `--runner axe`. |
| Threshold 0 on a project with debt | Every PR fails until the entire backlog is fixed. | Use `a11y-violation-gate` ratchet OR raise threshold incrementally. |
| Running only htmlcs | Different rule coverage than axe; misses issues. | Run both runners; deduplicate at the gate. |
| Ignoring rules without config comments | Lost institutional knowledge. | Inline justification + quarterly review. |
## Limitations
- **Selector reliability.** htmlcs sometimes produces selectors that don't
uniquely identify the failing element; axe is more precise.
- **JS-rendered content.** pa11y's default Chromium runner waits for the
`load` event; SPAs may need `--wait-for-selector` before scanning.
- **No native test-framework integration.** For Playwright / Cypress, use
the direct axe integration in SKILL.md.
## References
- pa11y - https://github.com/pa11y/pa11y (install, CLI flags, runners,
reporter formats).
- pa11y-ci - https://github.com/pa11y/pa11y-ci (multi-URL).
- HTML CodeSniffer (the htmlcs runner) - https://github.com/squizlabs/HTML_CodeSniffer
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |