A11y check local

Skill idimsh/tdds-frontend-skills/a11y-check-local

Frontend AI agent skills (SKILL.md) for UI pre-delivery checks, accessibility audits, and fixing patterns across Next.js, React, and other web projects

Install

npx -y skills add idimsh/tdds-frontend-skills --skill a11y-check-local

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Run instant WCAG 2.2 accessibility audits on a live local dev server and fix all violations. Use when the user asks to check, audit, fix, or improve accessibility compliance (a11y, WCAG, ADA, EAA). Requires Node.js and a running dev server.

SKILL.md

6.2 KB, as published. Nobody here has run it

<CRITICAL_CONSTRAINTS>

YOU MUST run the audit BEFORE touching any code. Never fix what you have not measured.
YOU MUST save the JSON report to disk. Never rely on terminal output alone.
YOU MUST fix violations in order: critical → serious → moderate → minor.
YOU MUST re-run the audit after fixing to confirm zero regressions.
Never auto-fix incomplete violations. Flag them for human review only. </CRITICAL_CONSTRAINTS>

A11y Compliance Skill

Integrate WCAG 2.2 accessibility audits into the local development cycle using @axe-core/cli.

Step 0 — Confirm Dev Server with Operator

YOU MUST ask the operator (the developer running this session) before scanning:

Before I run the audit, please confirm:
1. Is the dev server running locally?
2. What is the URL and port? (e.g. http://localhost:3000)
3. Which routes/pages should I audit? (list them, or say "homepage only")

Do NOT proceed to Step 1 until the operator confirms the server is up and provides the URL. Never assume a default port.

Step 1 — Audit

Run the scan using the URL and routes confirmed by the operator.

npx @axe-core/cli http://localhost:PORT \
  --tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa \
  --save a11y-report.json \
  --exit \
  --chrome-options="no-sandbox,disable-dev-shm-usage" \
  --load-delay 1500

Multiple routes (not a crawler — list each explicitly):

npx @axe-core/cli \
  http://localhost:PORT \
  http://localhost:PORT/about \
  http://localhost:PORT/contact \
  --tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa \
  --dir ./a11y-reports \
  --exit \
  --chrome-options="no-sandbox,disable-dev-shm-usage" \
  --load-delay 1500

Replace PORT with the actual port (3000, 5173, 4000, etc.). If unsure, check package.json scripts.

SPA / React / Vue / Next.js: increase --load-delay to 2000–3000 if results look incomplete.

Step 2 — Parse the Report

Read a11y-report.json. Focus on the violations array. Ignore passes and inapplicable.

{
  "violations": [
    {
      "id": "color-contrast",
      "impact": "serious",
      "description": "Elements must have sufficient color contrast",
      "helpUrl": "https://dequeuniversity.com/rules/...",
      "tags": ["wcag2aa", "wcag21aa"],
      "nodes": [
        {
          "html": "<p class=\"subtitle\">...</p>",
          "target": [".subtitle"],
          "failureSummary": "Fix any of: Element has insufficient color contrast..."
        }
      ]
    }
  ],
  "incomplete": [...],
  "passes":  [...],
  "inapplicable": [...]
}

Key fields per violation:

impact — priority: critical > serious > moderate > minor
nodes[].html — the exact element to fix
nodes[].target — CSS selector to locate it in source
failureSummary — what specifically failed and what to do

Step 3 — Fix Violations

Work through violations grouped by impact. For each node:

Use nodes[].target (CSS selector) to locate the element in source files
Apply the fix described in failureSummary
Do NOT guess — reference helpUrl for the WCAG rule if intent is unclear

Common fixes by rule ID:

Rule ID	Fix
`color-contrast`	Increase contrast ratio to ≥ 4.5:1 (text) or ≥ 3:1 (large text/UI)
`image-alt`	Add descriptive `alt` attribute to `<img>`
`label`	Associate `<label for="id">` with every form input
`html-has-lang`	Add `lang="en"` (or correct locale) to `<html>` tag
`button-name`	Add visible text or `aria-label` to every `<button>`
`link-name`	Add descriptive text or `aria-label` to every `<a>`
`heading-order`	Fix heading hierarchy (no skipping h1→h3)
`landmark-one-main`	Wrap main content in `<main>`
`region`	Wrap all content in landmark regions (`<header>`, `<main>`, `<footer>`, `<nav>`)
`focus-visible`	Ensure visible focus ring on all interactive elements
`aria-required-attr`	Add missing required ARIA attributes
`duplicate-id`	Ensure all `id` attributes are unique per page

Step 4 — Verify

Re-run the exact same audit command after fixing:

npx @axe-core/cli http://localhost:PORT \
  --tags wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa \
  --save a11y-report-after.json \
  --exit \
  --chrome-options="no-sandbox,disable-dev-shm-usage" \
  --load-delay 1500

Pass = zero entries in violations. --exit will return code 0.

If new violations appear that were not in the original report, you introduced a regression. Fix before proceeding.

Step 5 — Report Incompletes

For every item in incomplete, YOU MUST create a clearly worded note — do NOT auto-fix:

⚠️  NEEDS HUMAN REVIEW
Rule:    {id}
Element: {nodes[].html}
Reason:  axe-core could not determine compliance automatically.
Action:  Manual test required — {failureSummary}

Incompletes require manual keyboard testing, screen reader validation, or visual inspection.

Tag Reference

Tag	Standard
`wcag2a`	WCAG 2.0 Level A
`wcag2aa`	WCAG 2.0 Level AA
`wcag21a`	WCAG 2.1 Level A
`wcag21aa`	WCAG 2.1 Level AA
`wcag22aa`	WCAG 2.2 Level AA
`best-practice`	Deque best practices (optional, non-normative)

YOU MUST include all five WCAG tags. Stricter rulesets do NOT inherit looser ones — omitting any tag silently skips those rules.

Scope Flags (optional)

--include "main"          # Scan only the <main> element and its children
--exclude ".third-party"  # Skip known third-party widgets you don't own
--rules color-contrast    # Run only specific rule(s) for targeted fixes
--disable duplicate-id    # Skip a specific rule (use sparingly)

<KEY_REMINDERS>

Audit first. Fix second. Verify third. Always in that order.
All five --tags are required every time. Missing one = silent gaps.
incomplete = flag for human review, never auto-fix.
--load-delay 1500+ is mandatory for SPAs and JS-heavy apps.
Zero violations in violations[] = passing audit. passes[] is irrelevant. </KEY_REMINDERS>