feat: /a11y — accessibility testing built on the infrastructure you already have

[HMAKT99]

The accessibility tree was there all along

Every time you run $B snapshot -i, gstack calls page.accessibility.snapshot() and reads the full ARIA tree. It assigns @e refs from it. The entire ref system — the thing that makes gstack's browser work — is built on the accessibility tree.

But nobody is using it to actually test accessibility.

/a11y changes that. It takes the accessibility tree gstack already reads and runs a WCAG 2.2 compliance audit against it. Same $B commands. Same browse daemon. New superpower.

What it looks like

You:   /a11y https://myapp.com

Claude: Auditing 5 pages against WCAG 2.2 Level AA...

        A11Y COMPLIANCE SCORE
        ══════════════════════
        Level A:    18/22 criteria met  (82%)
        Level AA:   14/20 criteria met  (70%)
        Status:     NON-CONFORMANT

        CRITICAL — blocks users:
        ────────────────────────
        [1] 3 images missing alt text
            WCAG 1.1.1 Non-text Content (Level A)
            Fix: Add alt="Team photo of 5 engineers" to img.team-photo
            Fix: Add alt="" role="presentation" to img.decorative-divider

        [2] 2 form inputs without labels
            WCAG 1.3.1 Info and Relationships (Level A)
            Fix: Add <label for="email">Email address</label>

        HIGH — significant barriers:
        ──────────────────────────
        [3] Body text contrast ratio 2.8:1 (needs 4.5:1)
            WCAG 1.4.3 Contrast Minimum (Level AA)
            Fix: Darken text from #999 to at least #767676

        [4] Heading hierarchy skips h1 → h4
            WCAG 1.3.1 Info and Relationships (Level A)
            Fix: Use h2 after h1, not h4

        Top 3 fixes that would improve the most:
        1. Add alt text to 3 images — resolves 3 findings
        2. Add form labels — resolves 2 findings
        3. Fix text contrast — affects every page

Why this belongs in gstack

It uses what you already built

gstack feature	How /a11y uses it
$B snapshot	Reads the full accessibility tree — heading hierarchy, landmarks, ARIA roles
$B snapshot -i	Gets @e refs — checks that every interactive element has an accessible name
$B snapshot -C	Finds cursor-interactive elements that might lack keyboard access
$B eval	Runs JS to compute color contrast ratios, check form labels, verify lang attributes
$B press Tab	Tests keyboard navigation — Tab traversal, focus visibility, keyboard traps
$B viewport	Tests responsive accessibility at mobile breakpoints (44px touch targets)

It follows gstack's existing patterns

• Diff-aware mode: /a11y --diff only audits pages affected by current branch — same pattern as /qa
• Severity levels: CRITICAL / HIGH / MEDIUM / LOW — same as /review
• Specific fixes: Not "add alt text" but "add alt='Team photo of 5 engineers at the YC office' to img.team-photo" — same specificity as /review
• Compliance scoring: 0-100 score like QA health scores

The world needs it now

• EU Accessibility Act: enforcement is active
• US DOJ: suing companies for inaccessible websites
• WCAG 2.2: published October 2023, now the standard
• Most teams skip accessibility because testing is manual and tedious — gstack makes it one command

Audit methodology

Phase 1: Setup + page discovery
Phase 2: Accessibility tree audit (7 categories)
  3A — Document structure (headings, landmarks, title, lang)
  3B — Images and media (alt text, decorative vs informational)
  3C — Interactive elements (button labels, link text, form labels)
  3D — Color contrast (luminance ratio calculation)
  3E — Keyboard navigation (Tab traversal, focus management)
  3F — ARIA validation (roles, required properties, redundancy)
  3G — Responsive accessibility (mobile viewport, touch targets)
Phase 3: Issue classification (WCAG criterion + severity)
Phase 4: Compliance scoring (Level A/AA/AAA pass rates)
Phase 5: Report with specific fixes per finding

Arguments

/a11y <url>              — full WCAG 2.2 audit
/a11y <url> --quick      — critical issues only
/a11y <url> --level AAA  — stricter conformance (default: AA)
/a11y <url> --pages ...  — specific pages
/a11y --diff             — audit pages affected by current branch

Test plan

• bun test — all tests pass, 0 failures
• bun run gen:skill-docs --dry-run — FRESH
• Uses {{PREAMBLE}} + {{BROWSE_SETUP}} — follows template pipeline
• Reports saved to .gstack/a11y-reports/