JSX a11y Audit

What this skill does

Statically audits a JSX or TSX tree for WCAG 2.1 AA accessibility violations. It runs eslint-plugin-jsx-a11y plus a custom set of rules for label-association and focus order, and produces a report keyed to file:line.

Inputs

• repo_dir: project root containing JSX/TSX components.
• glob (optional): default src/**/*.{jsx,tsx}.
• wcag_level (optional): A, AA (default), or AAA.

Steps

1. Run npx eslint --no-eslintrc --plugin jsx-a11y --extends plugin:jsx-a11y/strict <glob> to get the baseline violations as JSON (-f json).
2. Parse each affected file with @typescript-eslint/parser and walk the JSX tree.
3. Apply custom checks not covered by the plugin:
   • For every <input>, find a parent or sibling <label htmlFor> matching its id. Flag missing id or unmatched.
   • For every <button> with no children (icon-only), require either aria-label or aria-labelledby.
   • For every <img>, require non-empty alt unless role="presentation" is present.
   • For every interactive component (custom onClick on a non-button), require role and tabIndex.
4. Detect heading hierarchy: walk the file order; flag jumps of more than one level (h1 -> h3) at the file scope.
5. Detect color references in inline styles (e.g., color: '#888') and emit a warning that contrast must be tested at runtime — static color extraction with a placeholder background is unreliable.
6. Group findings by severity using WCAG SC numbers (e.g., 1.1.1, 1.3.1, 2.4.6).
7. Sort findings: blockers first (1.x and 4.x SCs), then warnings.
8. Emit a markdown report.

Output

a11y-audit.md containing a summary header (counts per WCAG SC), a per-file section with file:line citations and the violated SC code, and a "Manual Checks Required" section for items needing browser testing (contrast, focus visibility, motion).

Verification

Re-run eslint-plugin-jsx-a11y after applying any fixes to verify that the auto-detected violations drop to zero. For a sample of three custom-rule findings, open the file and verify by eye. Cross-reference the SC codes with the WCAG quickref to confirm the chosen severity matches the official "Level A/AA/AAA" tier; downgrade reports that conflate AAA with AA.

Edge cases

• Components rendering children dynamically from props: missing labels may be supplied by the caller; surface as "needs review" rather than blocker.
• Custom design system components (e.g., <DSButton>): check if a wrapper handles a11y, otherwise flag with a note.
• React Native components (<View>, <Text>): most jsx-a11y rules don't apply; refuse to run on *.native.tsx files.
• Auto-generated files (e.g., from Figma exports): skip via .eslintignore and note the skip in the report.