Skip to content

bestdeejay-design/agent-skills / skills/frontend-a11y

frontend-a11y

Verified

Deep accessibility (a11y) audit of a webpage or static HTML/CSS, mapped to the full Front-End-Checklist Accessibility category (95 rules) — far beyond the ~12 basic rules in frontend-perfection. Runs offline static checks (Python stdlib, no browser/network) for structure, ARIA validity, headings, landmarks, tables, forms, media tracks, lists, and CSS signals; documents an optional Playwright+axe-core runtime runner for computed contrast, focus order, live regions, modal traps, and reflow; and lists manual screen-reader checks. Use it to audit, fix, or verify accessibility: 'accessibility audit', 'a11y check', 'wcag', 'wcag audit', 'wcag compliance', 'axe', 'contrast check', 'aria', 'screen reader test', 'keyboard navigation', 'keyboard trap', 'focus trap', 'accessibility testing', 'make it accessible', 'check this page for a11y', 'проверь доступность', 'глубокая доступность'. Also triggered when the /frontend orchestrator or mobile-frontend needs the deep a11y domain.

frontend-a11y

frontend-perfection owns measurable layout/perf/SEO/tokens polish and only touches ~12 basic a11y rules (img-alt, button/link-name, form-label, aria-valid, landmark-unique, plus lang/dir/headings). This skill owns the deep accessibility domain — the full Front-End-Checklist Accessibility category (95 rules), split into three checkable tiers so the right tool runs at the right time.

  • static — offline Python (scripts/a11y_audit.py), no browser, no network. Markup structure, ARIA validity, headings, landmarks, tables, forms, media tracks, lists, and a few CSS signals.
  • runtime — Playwright + axe-core (scripts/a11y_axe.mjs, optional npm deps). Computed contrast, ARIA parent/child relationships, live regions, focus order, modal traps, reflow at 400% zoom, touch targets.
  • manual — screen-reader testing and human-judgement rules (NVDA/JAWS/ VoiceOver/TalkBack, plain language, seizure flashing). Checklist-only; the report records them as severity: manual so they are not silently skipped.

When to use

  • User asks to "audit accessibility", "check WCAG", "run axe", "test keyboard navigation", "find focus traps", "verify contrast", "проверь доступность".
  • The /frontend orchestrator routes the a11y domain here; mobile-frontend calls it for touch-target / orientation / reflow checks.
  • After frontend-perfection passes its 12 basic rules and you need the other 83.

Composition

  • vs frontend-perfection — it owns layout/perf/SEO/tokens + 12 a11y rules (incl. computed contrast). This skill owns the remaining 83 a11y rules. Do NOT re-implement raw-hex token checks or computed-contrast here — those live in frontend-perfection/a11y_axe.mjs. Run frontend-perfection first for the shared baseline, then frontend-a11y for depth.
  • vs mobile-frontend — it calls frontend-a11y for the mobile-a11y rules (touch target size, orientation, reflow at 400%, reduced motion).
  • vs /frontend — the orchestrator runs frontend-perfection + this skill
    • (optionally) a11y_axe.mjs for the full a11y picture.

Workflow

Capture evidence at every step — run the scripts and paste the real command, its exit status, and the relevant JSON rows into the report. Assertions without the script output are not acceptable, because the audit ids are the only contract that proves a fix actually closed a violation.

  1. Locate the target — static index.html (+ CSS) or a served URL.
  2. Run the static audit (always, offline) and record its exit status:
    python3 scripts/a11y_audit.py --html index.html --css main.css css/demo.css --out a11y-static.json
    echo "exit=$?"
    
    Exit 0 = no violations, 1 = violations, 2 = runner error. Paste the exit= line and the violation summary into the report as evidence.
  3. Run the runtime audit (optional, needs deps) on a served URL, again recording the exit status:
    npm i playwright axe-core && npx playwright install chromium
    node scripts/a11y_axe.mjs --url http://localhost:8377/ --out a11y-axe.json
    echo "exit=$?"
    
    Paste the exit= line and the FAIL/manual rows so the runtime findings are verifiable, not assumed.
  4. Fix by audit id — every fix references the id it closes (a11y:img-alt, a11y:landmark-main, a11y:axe:color-contrast, …).
  5. Re-audit until green on static; resolve runtime FAIL rows; record manual rows as verified-or-pending in the report. Re-run the same command and show the new exit= so the improvement is demonstrable.
  6. Write the before/after report (see convention below): input paths, exact commands, real output, interpretation, and what was deliberately NOT done.

audit-id scheme (95 rules)

Each checklist rule maps to a stable id tagged static / runtime / manual. Severity (critical/high/medium/low) mirrors the checklist priority and is emitted per check in the JSON report.

static — offline Python (a11y_audit.py)

idchecklist rule
a11y:img-altImages have alt text
a11y:img-button-altImage buttons (input[type=image]) have alt
a11y:img-alt-redundantNo redundant "image/photo" words in alt
a11y:button-nameButtons have accessible names
a11y:link-nameLinks have accessible names
a11y:link-distinctIdentical link text → identical destination
a11y:link-empty-brokenLinks are not empty/broken
a11y:link-text-descriptiveDescriptive link text (not "click here")
a11y:form-labelForm controls have associated labels
a11y:form-label-singleExactly one label per field
a11y:input-nameAll inputs have accessible names
a11y:select-nameSelects have accessible names
a11y:toggle-nameToggle fields (checkbox/radio/switch) named
a11y:aria-validARIA attribute names are valid
a11y:aria-valid-valueARIA attribute values are valid tokens
a11y:aria-deprecated-roleNo abstract/deprecated ARIA roles
a11y:aria-role-validARIA role values are valid
a11y:landmark-uniqueLandmarks are unique
a11y:landmark-mainExactly one <main> landmark
a11y:landmark-navMultiple <nav> have distinct labels
a11y:landmark-regionsLandmark regions used correctly
headings:single-h1Exactly one h1
headings:orderLogical heading order (no skipped levels)
headings:non-emptyHeadings contain text
html:lang<html lang> present (BCP 47)
html:dir-rtlRTL languages set dir="rtl"
html:lang-xml-matchlang matches xml:lang
a11y:skip-linkSkip-to-content link present
a11y:iframe-titleiframes/frames have titles
a11y:table-headersData tables have <th> headers
a11y:table-header-scopeHeaders scoped to cells
a11y:table-cell-headersCells linked to headers via ids
a11y:table-unique-nameTables have unique accessible names
a11y:table-semanticSemantic table markup (caption/role)
a11y:video-captions<video> has <track kind="captions">
a11y:video-audio-desc<video> has <track kind="descriptions">
a11y:autofocus-absentNo autofocus on fields
a11y:aria-hidden-body-absentNo aria-hidden on <body>
a11y:focusable-in-aria-hidden-absentNo focusable child in aria-hidden
a11y:list-structure<li> inside ul/ol/menu
a11y:list-correctul/ol contain only <li>
a11y:list-semanticSemantic list elements used
a11y:dl-structureValid <dl> (only dt/dd)
a11y:dl-wrapdt/dd wrapped in <dl>
a11y:decorative-hiddenDecorative elements hidden from AT
a11y:object-alt<object> has alternative content
a11y:meta-refresh-absentNo meta refresh redirect
a11y:accesskey-uniqueUnique accesskey values
a11y:unique-idUnique element ids
a11y:aria-ref-uniqueARIA-referenced ids unique/exist
a11y:tabindex-appropriateNo positive tabindex
a11y:role-text-no-focusablerole="text" has no focusable child
a11y:dialog-nameDialogs have accessible names
a11y:meter-nameMeter elements named
a11y:progress-nameProgress bars named
a11y:tooltip-nameTooltips named
a11y:treeitem-nameTree items named
a11y:command-nameARIA command elements named
a11y:interactive-nameRole-based interactive els named
a11y:autoplay-mediaNo autoplaying media
a11y:paste-allowedPasting allowed in inputs
a11y:autocomplete-authAuth inputs support autocomplete
a11y:links-in-text-distinguishableLinks distinct beyond color (CSS)
a11y:reduced-motionRespects prefers-reduced-motion (CSS)
a11y:instant-anchor-scrollInstant anchor-scroll option (CSS)

runtime — Playwright + axe-core (a11y_axe.mjs)

id (prefixed a11y:axe:)checklist rule
color-contrastMinimum color contrast (WCAG 1.4.3)
aria-required-parentARIA roles contained by required parent
aria-required-childrenARIA roles contain required children
aria-allowed-attrOnly allowed ARIA attrs per role
label-content-name-mismatchVisible label matches accessible name
focus-order-semantics / tablistLogical focus order
focus-not-obscuredFocused el not hidden by sticky chrome
modal-aria / focus-trappingModal dialog keyboard accessible
aria-live / regionDynamic content announced (live regions)
scrollable-region-focusableReflow at 400% zoom
target-sizeSufficient touch target size
orientationPortrait + landscape support
blink / css-animation-no-pauseNo seizure-triggering flashing

manual — screen reader / human judgement

idchecklist rule
a11y:screen-reader-testTest with NVDA/JAWS/VoiceOver/TalkBack
a11y:content-without-cssUsable with author CSS disabled
a11y:sensory-only-instructionsNo sensory-only instructions
a11y:images-of-textAvoid images of text
a11y:scrolljackingNo hijacked scroll
a11y:redundant-entryNo redundant entry in a flow
a11y:help-consistentHelp in consistent location
a11y:session-timeoutWarn before session timeout
a11y:seizure-flashingNo >3 flashes/sec
a11y:parallax-altAlternatives to parallax
a11y:inclusive-languageInclusive language
a11y:plain-languagePlain language
a11y:label-name-matchVisible label ⊆ accessible name

Scripts

a11y_audit.py (static, offline, stdlib)

Reads one or more --html files and optional --css. Emits a JSON report (--out / --json) where every check has id, title, severity, ok, detail, file. Exit codes: 0 no violations, 1 violations, 2 runner error. No PyYAML, no requests, no network.

python3 scripts/a11y_audit.py --html index.html --css main.css --out a11y.json
python3 scripts/a11y_audit.py --html a.html b.html --json   # stdout JSON

a11y_axe.mjs (runtime, optional deps)

Real Chromium via Playwright; injects axe-core and runs the WCAG tag set. Documents required deps in its header; it does NOT run at build time. Exit codes mirror the static script (0/1/2). incomplete axe results are emitted as severity: manual so they surface for human confirmation instead of being counted as hard failures.

npm i playwright axe-core && npx playwright install chromium
node scripts/a11y_axe.mjs --url http://localhost:8377/ --out a11y-axe.json

Before/after report convention

Bind every claim to an audit id. Format:

## Accessibility audit — <project>
Inputs: index.html, main.css
Commands:
  python3 scripts/a11y_audit.py --html index.html --css main.css --out a11y.json
  (exit 1, 14 violations)

Before: 14 violations (a11y:img-alt ×3, headings:order, a11y:landmark-main, …)
Fixes:
  - a11y:img-alt: added alt to hero/banner/icons
  - headings:order: h1→h3 gap closed (inserted h2)
  - a11y:landmark-main: removed duplicate <main>
After: 0 violations (exit 0)

Runtime (axe): 2 FAIL (color-contrast on footer), 3 manual pending
Manual: screen-reader pass pending (NVDA) — NOT done this run
Not done: computed-contrast (owned by frontend-perfection), design tokens.

Constraints / non-goals

  • a11y_audit.py is offline and stdlib-only — no PyYAML, no requests, no network, no browser. Keep it runnable with only python3 so the audit works in any CI or offline environment without extra installs.
  • Computed color contrast and design-token hex checks are out of scope here (owned by frontend-perfection and a11y_axe.mjs). Don't add them to the static script, or the two skills will duplicate and drift apart.
  • a11y_axe.mjs requires npm i playwright axe-core + npx playwright install chromium; it is documented, not executed, at build time.
  • Don't depend on the external Front-End-Checklist MCP server; the 95-rule mapping is embedded above so the skill runs without network or that dependency.
  • Fix at the root (real semantics). Avoid hiding audits with aria-hidden spray or tabindex=-1 hacks — those mask the violation instead of resolving it, so the next audit still fails and users are still blocked.
  • Record manual rules; never silently drop them, so they appear as severity: manual in the report and get a human confirmation.

Boundaries

  • Do not use for broad visual/performance polish; use frontend-perfection or frontend-performance.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall