A11y

/a11y — Master Accessibility Audit

Finds and fixes every accessibility violation across the entire app. Works programmatically (axe-core) and visually (keyboard screenshots), from critical to minor, screen by screen.

Full WCAG quick-reference and fix patterns: [WCAG.md](WCAG.md)

---

Phase 0 — Environment Setup

0a. Check / start dev server

curl -s --max-time 2 -o /dev/null -w "%{http_code}" http://localhost:3000

If not 200, find and start the dev command, then wait:

until curl -s --max-time 2 http://localhost:3000 > /dev/null 2>&1; do sleep 1; done && echo "ready"

0b. Find source root

find . -type d -name "src" \
  -not -path "*/node_modules/*" \
  -not -path "*/.next/*" \
  -not -path "*/dist/*" \
  -not -path "*/.turbo/*" \
  | head -1

If no src/: find . -type d -name "app" -not -path "*/node_modules/*" -not -path "*/.next/*" | head -1

Use the result as `` throughout.

0c. Verify axe-core

find . -path "*/axe-core/package.json" -not -path "*/node_modules/.cache/*" 2>/dev/null | head -1

If not found: install it (dev dependency only):

pnpm add -D axe-core 2>/dev/null || npm install -D axe-core 2>/dev/null || yarn add -D axe-core

Resolve the axe bundle path for later injection:

find . -path "*/axe-core/axe.min.js" -not -path "*/node_modules/.cache/*" 2>/dev/null | head -1

Store this as ``.

0d. Write the scan script

Write to the project root (needs node_modules). Deleted in Phase 4.

_a11y_scan.mjs:

import { chromium } from '@playwright/test';
import { mkdirSync, writeFileSync } from 'fs';
import { createRequire } from 'module';

const require = createRequire(import.meta.url);
const get = (f) => { const i = process.argv.indexOf(f); return i !== -1 ? process.argv[i+1] : null; };

const url        = get('--url');
const name       = get('--name') ?? 'screen';
const width      = parseInt(get('--width')  ?? '1280');
const height     = parseInt(get('--height') ?? '900');
const auth       = get('--auth');
const screenshot = get('--screenshot') ?? `/tmp/a11y-${name}.png`;
const report     = get('--report')     ?? `/tmp/a11y-${name}.json`;

if (!url) { console.error('--url required'); process.exit(1); }

mkdirSync('/tmp/a11y', { recursive: true });

const axePath = (() => {
  try { return require.resolve('axe-core'); }
  catch { console.error('axe-core not found — run: pnpm add -D axe-core'); process.exit(1); }
})();

const browser = await chromium.launch();
const context = await browser.newContext({
  viewport: { width, height },
  ...(auth ? { storageState: auth } : {}),
});
const page = await context.newPage();

try {
  await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
} catch {
  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
}

// Inject axe-core from local node_modules
await page.addScriptTag({ path: axePath });

// Run axe scan
const results = await page.evaluate(async () => {
  const r = await window.axe.run(document, {
    runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'] },
  });
  return {
    violations:  r.violations.map(v => ({
      id:          v.id,
      impact:      v.impact,
      description: v.description,
      help:        v.help,
      helpUrl:     v.helpUrl,
      nodes:       v.nodes.map(n => ({ html: n.html, target: n.target, failureSummary: n.failureSummary })),
    })),
    incomplete: r.incomplete.length,
    passes:     r.passes.length,
  };
});

await page.screenshot({ path: screenshot, fullPage: true });
await browser.close();

writeFileSync(report, JSON.stringify(results, null, 2));

const counts = { critical: 0, serious: 0, moderate: 0, minor: 0 };
for (const v of results.violations) counts[v.impact] = (counts[v.impact] ?? 0) + 1;

console.log(`saved: ${screenshot}`);
console.log(`report: ${report}`);
console.log(`violations: critical=${counts.critical} serious=${counts.serious} moderate=${counts.moderate} minor=${counts.minor}`);
console.log(`passes: ${results.passes} | incomplete: ${results.incomplete}`);

Usage:

node _a11y_scan.mjs --url http://localhost:3000 --name home
node _a11y_scan.mjs --url http://localhost:3000/dashboard --name dashboard --auth /tmp/uiux-auth-state.json
node _a11y_scan.mjs --url http://localhost:3000/settings --name settings --width 375 --height 812

After every scan: read the JSON report and the screenshot.

0e. Write the keyboard navigation script

Write to the project root. Deleted in Phase 4.

_a11y_keyboard.mjs:

import { chromium } from '@playwright/test';
import { mkdirSync } from 'fs';

const get = (f) => { const i = process.argv.indexOf(f); return i !== -1 ? process.argv[i+1] : null; };

const url    = get('--url');
const name   = get('--name') ?? 'screen';
const width  = parseInt(get('--width')  ?? '1280');
const height = parseInt(get('--height') ?? '900');
const auth   = get('--auth');
const maxTabs = parseInt(get('--max-tabs') ?? '30');

if (!url) { console.error('--url required'); process.exit(1); }

mkdirSync('/tmp/a11y', { recursive: true });

const browser = await chromium.launch();
const context = await browser.newContext({
  viewport: { width, height },
  ...(auth ? { storageState: auth } : {}),
});
const page = await context.newPage();

try {
  await page.goto(url, { waitUntil: 'networkidle', timeout: 30000 });
} catch {
  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
}

const issues = [];

// Check for skip link as first tab stop
await page.keyboard.press('Tab');
const skipLink = await page.evaluate(() => {
  const el = document.activeElement;
  if (!el || el === document.body) return null;
  return { tag: el.tagName, text: el.textContent?.trim(), href: el.getAttribute('href') };
});

const hasSkipLink = skipLink?.text?.toLowerCase().includes('skip') && skipLink?.href?.startsWith('#');
if (!hasSkipLink) issues.push({ type: 'missing-skip-link', detail: 'First Tab stop is not a "Skip to main content" link' });

// Tab through interactive elements
const focusLog = [];
for (let i = 0; i  {
    const el = document.activeElement;
    if (!el || el === document.body) return null;
    const style   = getComputedStyle(el);
    const rect    = el.getBoundingClientRect();

    // Capture focused styles
    const focusedBorder     = style.borderColor;
    const focusedBackground = style.backgroundColor;

    // Briefly blur to capture unfocused styles, then refocus
    el.blur();
    const blurStyle       = getComputedStyle(el);
    const blurBorder      = blurStyle.borderColor;
    const blurBackground  = blurStyle.backgroundColor;
    el.focus();

    return {
      tag:                el.tagName,
      role:               el.getAttribute('role'),
      ariaLabel:          el.getAttribute('aria-label'),
      text:               el.textContent?.trim().slice(0, 60),
      outlineWidth:       style.outlineWidth,
      outlineStyle:       style.outlineStyle,
      boxShadow:          style.boxShadow,
      hasBorderChange:    focusedBorder     !== blurBorder,
      hasBackgroundChange:focusedBackground !== blurBackground,
      width:              Math.round(rect.width),
      height:             Math.round(rect.height),
    };
  });
  if (!focusInfo) break;

  // Detect focus visibility via outline, box-shadow, or meaningful border/background change.
  // Compare against a snapshot of the element's non-focused style by briefly blurring and refocusing.
  const hasVisibleFocus = (
    (focusInfo.outlineStyle !== 'none' && focusInfo.outlineWidth !== '0px')
    || (focusInfo.boxShadow && focusInfo.boxShadow !== 'none')
    || focusInfo.hasBorderChange
    || focusInfo.hasBackgroundChange
  );
  const hasName = !!(focusInfo.ariaLabel || focusInfo.text);
  const isTiny  = focusInfo.width  console.log(' -', JSON.stringify(i)));
} else {
  console.log('no keyboard issues found');
}

Usage:

node _a11y_keyboard.mjs --url http://localhost:3000 --name home
node _a11y_keyboard.mjs --url http://localhost:3000/dashboard --name dashboard --auth /tmp/uiux-auth-state.json --max-tabs 50

0f. Handle auth-protected screens

ls /tmp/uiux-auth-state.json /tmp/animate-auth-state.json /tmp/copy-auth-state.json 2>/dev/null | head -1

If found, pass --auth to all script calls for protected routes.

If not found and protected screens exist, write _a11y_auth.mjs to the project root:

import { chromium } from '@playwright/test';
const { TEST_EMAIL, TEST_PASSWORD, LOGIN_URL, SUCCESS_URL } = process.env;
if (!TEST_EMAIL || !TEST_PASSWORD) { console.error('Set TEST_EMAIL and TEST_PASSWORD'); process.exit(1); }
const browser = await chromium.launch();
const page    = await browser.newPage();
await page.goto(LOGIN_URL ?? 'http://localhost:3000/sign-in');
await page.fill('input[type="email"]',    TEST_EMAIL);
await page.fill('input[type="password"]', TEST_PASSWORD);
await page.click('button[type="submit"]');
await page.waitForURL(SUCCESS_URL ?? '**/dashboard**', { timeout: 15000 });
await page.context().storageState({ path: '/tmp/a11y-auth-state.json' });
await browser.close();
console.log('saved → /tmp/a11y-auth-state.json');

---

Phase 1 — Accessibility Audit

1a. Find all screens

Every page.tsx in App Router, every page in Pages Router, modals, drawers, auth flows, settings, onboarding. List each with its route.

1b. Run axe scan on every screen

For each screen, run at both desktop and mobile viewports. Tap target failures only appear at mobile.

node _a11y_scan.mjs --url http://localhost:3000 --name -desktop
node _a11y_scan.mjs --url http://localhost:3000 --name -mobile --width 375 --height 812

Read both JSON reports and both screenshots. Group violations by impact:

• Critical — impact: "critical" — content inaccessible to assistive tech
• Serious — impact: "serious" — major barrier, usually WCAG AA failure
• Moderate — impact: "moderate" — degrades the experience
• Minor — impact: "minor" — best-practice violation

1c. Run keyboard nav test on every screen

For each screen, run _a11y_keyboard.mjs. Read stdout for issues. Read the keyboard screenshot.

node _a11y_keyboard.mjs --url http://localhost:3000 --name 

Check manually from the output:

• Is the first Tab stop a skip link?
• Do all interactive elements have a visible focus ring?
• Do all buttons and links have accessible names?
• Are all tap targets ≥44×44px?

1d. Code-level scan for structural issues

SRC=

# Images without alt
grep -rn " → 
   →  (unless ARIA role is truly needed)
   missing alt → alt="" for decorative, descriptive alt for informative
  heading skip (h1→h3) → add missing h2

Labels:
   no label → add aria-label or associate 
   no text → add aria-label describing the action
  icon-only button → add aria-label, add 

ARIA:
  aria-label on non-interactive div → move to the interactive child
  role="button" on  → remove role, keep  with href
  aria-hidden on focusable element → remove aria-hidden or tabIndex={-1}

Contrast:
  Use HSB adjustments: darker = increase S + decrease B
  Prefer token changes over component-level overrides

Focus:
  Add to global CSS or Tailwind config:
    focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand
  Never suppress with: outline: none (unless replacing with custom focus style)

Skip link:
  Add as first child of :
    
      Skip to main content
    
  Add id="main-content" to the  element.

aria-live regions:
  // Non-urgent announcements (search results, save confirmations)
  {statusMessage ?? ''}

  // Urgent interruptions (form errors, session expiry)
  {errorMessage}

  // CRITICAL: container must be in the DOM BEFORE content changes.
  // Wrong:  {message && {message}}
  // Right:  {message ?? ''}

prefers-reduced-motion:
  In globals.css — verify this rule exists, add if missing:
    @media (prefers-reduced-motion: reduce) {
      *, *::before, *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
      }
    }

3d. Re-scan after fixes

sleep 3  # hot reload
node _a11y_scan.mjs --url http://localhost:3000 --name -after-desktop
node _a11y_scan.mjs --url http://localhost:3000 --name -after-mobile --width 375 --height 812
node _a11y_keyboard.mjs --url http://localhost:3000 --name -after

Read the new JSON report. Compare violation counts before and after. Read the screenshots.

Verify:

1. Critical and serious violations cleared?
2. Keyboard focus visible on all interactive elements?
3. Skip link present and functional?
4. All buttons and inputs have accessible names?
5. Contrast ratios pass 4.5:1 (body) and 3:1 (large text, UI components)?

If any critical or serious violations remain: go back to 3c (increment iteration, max 3).

3e. Accessibility checklist

Before advancing to the next screen:

• [ ] Zero critical violations in axe report
• [ ] Zero serious violations in axe report
• [ ] lang attribute on `` element
• [ ] One ` landmark, one ` per page
• [ ] Heading hierarchy is sequential (no h1→h3 skip)
• [ ] Skip link is first focusable element, targets #main-content
• [ ] Every interactive element reachable by Tab in logical order
• [ ] Every focused element has a visible focus ring (not browser default removed)
• [ ] No keyboard traps (can Tab away from every element, including modals via Escape)
• [ ] Every ` has alt — empty ""` for decorative, descriptive for informative
• [ ] Every ` has an associated or aria-label`
• [ ] Every icon-only button has aria-label
• [ ] No onClick on non-interactive elements (`, , `)
• [ ] Color is not the only signal (errors have icon + text, not just color)
• [ ] Body text contrast ≥4.5:1, large text ≥3:1, UI components ≥3:1
• [ ] prefers-reduced-motion rule exists in global CSS
• [ ] Touch targets ≥44×44px (verified in keyboard script output)
• [ ] Modal/drawer traps focus while open, returns focus to trigger on close
• [ ] Dynamic content (toasts, errors, search counts, loading completion) wrapped in aria-live="polite" or role="alert" for urgent messages
• [ ] aria-live containers are in the DOM before content changes (not mounted and unmounted with the content)

Any critical/serious fail → go back to 3c. After iteration 3: flag and advance.

---

Phase 4 — Cleanup & Report

Delete temp scripts:

rm -f _a11y_scan.mjs _a11y_keyboard.mjs _a11y_auth.mjs

After each screen:

✓ Screen name (rank N, iteration K) — A critical + B serious + C moderate + D minor fixed

Final summary table:

| Rank | Screen | Route | Critical | Serious | Moderate | Minor | Iterations | State | |------|--------|-------|----------|---------|----------|-------|------------|-------| | 1 | ... | ... | 0 | 0 | ... | ... | ... | ✓ / ⚠ |

List all flagged violations at the bottom with the specific issue that couldn't be resolved.

---

Rules

1. Axe-core is the floor, not the ceiling. It catches ~30–40% of real accessibility issues. The keyboard test and code scan catch the rest.
2. Read the JSON, not just the count. Understand what each violation means before fixing.
3. Semantic HTML beats ARIA. A real ` is better than ` every time.
4. Never remove focus styles without replacing them. outline: none is a violation unless a custom focus style replaces it.
5. Color is never the only signal. Every state change visible only by color must also use an icon, text, or pattern.
6. Fix structural issues before visual ones. Landmarks, headings, and keyboard access first — contrast last.
7. Max 3 iterations per screen. Flag remaining issues and move on.
8. Never change logic or functionality. Only accessibility attributes, semantic elements, and styles.
9. Test at 375px too. Tap

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dawitlabs
• Source: dawitlabs/ui-skills
• License: MIT

Install and usage instructions live in the source repository linked above.