accessibility-review

Accessibility Review

Runs automatically before every code-review completion. Reviews all generated and modified frontend files against the configured WCAG standard.

Configurable Standard

Value	Description
wcag-2.1-a	WCAG 2.1 Level A
wcag-2.1-aa	WCAG 2.1 Level AA
wcag-2.2-aa	WCAG 2.2 Level AA (default)
wcag-2.2-aaa	WCAG 2.2 Level AAA

Configure via .frontend-agent.json:

{
  "accessibility": {
    "standard": "wcag-2.2-aa"
  }
}

Check Categories

Semantic HTML

• Heading hierarchy must be sequential (h1 → h2 → h3); skipping levels (e.g., h1 → h3) is a blocker.
• Pages must use landmark regions: <main>, <nav>, <aside>, <footer> where appropriate. Missing <main> is a blocker.
• List content (menus, item sets) must use <ul> / <ol> + <li>, not <div> chains.
• Interactive elements must be <button> or <a href>, not <div onClick> / <span onClick>.

ARIA

• Every interactive element without visible text must have aria-label or aria-labelledby. Missing label is a blocker.
• Do not add redundant ARIA to elements that already have semantic meaning (e.g., role="button" on <button>). Flag as warning.
• Only use valid ARIA role values from the ARIA specification. Invalid roles are blockers.
• aria-hidden="true" must not be placed on focusable elements.

Keyboard Navigation

• Route changes must move focus to a relevant heading or skip-link target. Missing focus management on navigation is a blocker.
• Tab order must follow visual reading order. Use tabindex="0" for custom interactive elements; never use positive tabindex values (warning).
• Custom interactive components (dropdowns, modals, date pickers) must be keyboard-operable: Enter/Space to activate, Arrow keys for navigation within compound widgets, Escape to dismiss.
• No focus traps outside of modal dialogs. Modals must trap focus while open and restore focus on close.

Color and Contrast

• Flag any hardcoded hex/rgb color values in JSX style props or CSS-in-JS without verified contrast ratio. Severity: warning, requires manual verification.
• For Tailwind text/background class combinations, verify against WCAG ratios:
  • AA (default): 4.5:1 for normal text, 3:1 for large text (18pt / 14pt bold).
  • AAA: 7:1 for normal text, 4.5:1 for large text.
• Using color alone to convey information is a blocker.

Forms

• Every <input>, <select>, and <textarea> must have an associated <label> via htmlFor / id pair. Missing association is a blocker.
• Error messages must be linked to the relevant field via aria-describedby. Missing link is a blocker.
• Required fields must have aria-required="true" or the HTML required attribute. Missing is a warning.
• Autocomplete attributes (autocomplete) should be present on common fields (name, email, password). Missing is a nit.

Images and Media

• Every <img> element must have an alt attribute. Missing alt is a blocker.
• Decorative images (icons used alongside text, background images) must have alt="" and optionally aria-hidden="true". Descriptive alt on decorative images is a warning.
• SVG icons used as interactive elements require aria-label or a visually hidden <title>. Missing label is a blocker.
• <video> and <audio> elements must not have autoplay without muted. Auto-playing media with sound is a blocker.
• Video content must have captions (<track kind="captions">). Missing captions is a warning.

Dynamic Content

• Async updates (toasts, notifications, status messages) must be wrapped in an aria-live region (polite for non-urgent, assertive for critical alerts only). Missing live region is a blocker.
• Loading states (spinners, skeleton screens) must announce their status to screen readers using aria-label or visually hidden text (e.g., "Loading..."). Missing announcement is a warning.
• SPA route changes must announce the new page title or heading via an aria-live="polite" region. Missing announcement is a blocker.
• aria-busy="true" must be set on containers actively loading content.

Output Format

Produce a structured list grouped by severity, then by file.

[BLOCKER] Semantic HTML — Missing <main> landmark
  File: src/pages/Home.tsx, line 12
  Fix: Wrap page content in <main>

[BLOCKER] Forms — <input id="email"> has no associated <label>
  File: src/components/LoginForm.tsx, line 34
  Fix: Add <label htmlFor="email">Email</label> or aria-label on the input

[WARNING] Color & Contrast — Hardcoded color #aaa on white background; contrast unverified
  File: src/components/Badge.tsx, line 8
  Fix: Verify contrast ratio >= 4.5:1 or replace with a design token

[WARNING] ARIA — Redundant role="navigation" on <nav> element
  File: src/components/Sidebar.tsx, line 5
  Fix: Remove role attribute; <nav> is already a landmark

[NIT] Forms — Missing autocomplete="email" on email input
  File: src/components/SignupForm.tsx, line 19
  Fix: Add autocomplete="email" attribute

Blockers must be resolved before the skill reports success. Warnings and nits are reported but do not block completion.