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/wave.md
View on GitHub# WAVE - WebAIM's visual-overlay scanner
Companion reference for `axe-a11y`. Consult when a regulatory audit requires
WebAIM-branded reports (common in US public-sector / education compliance),
when designers or non-technical reviewers need the visual overlay, when
auditing a third-party site without code access, or to cross-check axe /
pa11y findings. For purely automated CI gating, direct axe (SKILL.md) and
pa11y are simpler and free.
WAVE (Web Accessibility Evaluation Tool) is WebAIM's flagship scanner -
distinguished by a **visual overlay** that places icons directly on the
rendered page. It runs via browser extension (manual, visual), the WAVE API
(programmatic), or the commercial Stand-Alone API (self-hosted).
WAVE categorizes findings into: **errors** (definite WCAG failures),
**alerts** (likely issues needing review), **features** (positive patterns),
**structural elements** (landmarks, headings), **HTML5 / ARIA** semantics,
and **contrast errors**.
> **Source-fetch note (2026-05-04):** WAVE's documentation lives across
> `wave.webaim.org` and `webaim.org/articles`; the API specifics may evolve -
> verify the current WAVE API v3+ documentation at `wave.webaim.org/api`
> before authoring CI integrations against specific endpoints.
## Access
| Method | Cost |
|---------------------------------------------|-----------------------------------------|
| Browser extension (Chrome / Firefox / Edge) | Free. |
| WAVE API | Free credits + paid tiers (per WebAIM). |
| Stand-Alone API (self-hosted server) | Commercial license. |
## Manual usage (extension)
1. Install the WAVE extension; navigate to the page under test.
2. Click the WAVE icon - the page reloads with the overlay: red **error**
icons (definite failures), yellow **alert**, green **feature**, purple
**structural**, blue **HTML5/ARIA**.
3. The "Details" sidebar tab gives per-icon explanations.
## Programmatic usage (API)
```bash
curl 'https://wave.webaim.org/api/request?key=YOUR_KEY&url=https://example.com&reporttype=4'
```
Reporttype 4 returns the full JSON: a `statistics` block
(`errorcount`, `alertcount`, `featurecount`, ...) and a `categories` object
(`error` / `alert` / `feature` / `structure` / `html5` / `contrast`). Per
category, `items` is keyed by WAVE issue code (e.g. `alt_missing`,
`label_missing`, `contrast`); each entry has `description`, `count`,
`selectors[]`, and per-instance `xpath` / `selector` / `html`.
`jq` triage:
```bash
# All error-level codes + counts
jq -r '.categories.error.items | to_entries[] | "\(.key): \(.value.count)"' wave-results.json
# Failing selectors per issue
jq -r '.categories.error.items | to_entries[] | .value.selectors[] | tostring' wave-results.json
```
## CI integration
Capture WAVE API JSON per URL and feed it to the gate
(`a11y-violation-gate` owns the gate logic):
```yaml
- name: Run WAVE scan via API
env:
WAVE_API_KEY: ${{ secrets.WAVE_API_KEY }}
run: |
for url in https://staging.example.com/ https://staging.example.com/dashboard; do
slug=$(echo "$url" | tr '/:' '__')
curl -sS "https://wave.webaim.org/api/request?key=$WAVE_API_KEY&url=$url&reporttype=4" \
> "wave-$slug.json"
done
```
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---------------------------------------|----------------------------------------------------------------|-----|
| Treating "alerts" as errors | Alerts are flagged for human review, not auto-fail. | Block on errors; route alerts to review. |
| Storing the WAVE API key in config | Key leak; quota theft. | CI secrets only. |
| Running WAVE against production | API hits load production; possible PII leakage in scan data. | Staging / pre-prod only. |
| Using WAVE alone | Different rule coverage; misses some structural / ARIA issues. | Pair with axe for full coverage. |
| Dismissing "contrast errors" | They are SC 1.4.3 violations - definite WCAG failures. | Treat as errors; aggregate via the gate. |
## Limitations
- **Authenticated pages.** The WAVE API scans public URLs only; auth-required
pages need the Stand-Alone API or the extension manually.
- **SPAs.** URL-based scanning may not match the user's actual journey.
- **Quotas / costs.** The free API tier has limits; high-traffic CI usage
requires a paid tier.
- **Different rule coverage** than axe / pa11y - complementary, not a
replacement.
## References
- WAVE - https://wave.webaim.org/
- WAVE API documentation - https://wave.webaim.org/api/
- WebAIM - https://webaim.org/
- W3C WCAG 2.2 - https://www.w3.org/TR/WCAG22/
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | 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 |