a11y-fix

name	a11y-fix
description	"Fix accessibility issues in current code. Works through findings from a11y-audit, a11y-scan, or a11y-review. Makes changes, explains rationale, notes what to test manually. Use when asked to "fix accessibility", "make this accessible", or after any a11y assessment."

Fix accessibility issues in the current code. Target {{area}} if specified, otherwise work through all identified issues from most critical to least.

→ Consult the a11y-agent skill and its reference files for correct patterns.

Fix Process

For each issue:

1. Identify the problem — what fails and which WCAG criterion applies
2. Implement the fix — use the correct semantic pattern
3. Explain why — brief rationale for the change
4. Flag what to test — note keyboard and screen reader testing needed

Fix Priority Order

1. Keyboard access — divs→buttons, add focus management, skip links
2. Accessible names — labels on inputs, aria-labels on icon buttons, alt on images
3. Semantic structure — heading hierarchy, landmarks, lists
4. ARIA states — expanded, pressed, selected, invalid, current
5. Focus management — modal trapping, return focus, roving tabindex
6. Screen reader announcements — live regions for dynamic content
7. Visual — contrast, focus indicators, reflow, motion

Common Fixes

div → button

Replace <div onClick> with <button>. Update CSS to reset button styles:

.your-button {
  background: none;
  border: none;
  padding: 0;
  cursor: pointer;
  font: inherit;
  color: inherit;
}

Add form labels

<!-- Before -->
<input placeholder="Email">

<!-- After -->
<label for="email">Email</label>
<input id="email" type="email" placeholder="[e-mail]">

Fix heading hierarchy

Don't change visual appearance — add CSS utility classes instead:

<!-- Before: skipped h2 -->
<h1>Site Name</h1>
<h3>Section Title</h3>

<!-- After: correct hierarchy with style class -->
<h1>Site Name</h1>
<h2 class="heading-sm">Section Title</h2>

Add focus indicator

/* Remove the bad wildcard reset if present */
/* * { outline: none; } ← DELETE THIS */

/* Add visible focus styles */
:focus-visible {
  outline: 2px solid var(--focus-color, #005fcc);
  outline-offset: 2px;
}

Restore focus outline that was removed

Look for * { outline: 0 } or * { outline: none } in stylesheets and remove it.

prefers-reduced-motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Mega menu — hidden items still tabbable

/* Before: items invisible but tabbable */
.submenu { display: flex; opacity: 0; }
.submenu.active { opacity: 1; }

/* After: items fully hidden when inactive */
.submenu { display: none; }
.submenu.active { display: flex; }

Add aria-expanded on the trigger button. Bind Escape to close and return focus to trigger.

Client-side routing — missing focus management

After route change, update document.title and move focus to new content:

useEffect(() => {
  document.title = `${pageTitle} | Site Name`;
  mainRef.current?.focus();
}, [location.pathname]);

Add tabindex="-1" to the focus target if it's not natively focusable.

Form validation — errors not announced

The live region element MUST exist at page load. Inject error text into it:

<!-- Present at page load, starts empty -->
<p role="alert" aria-atomic="true">{errorMessage}</p>

On submit failure: set error message text, mark fields with aria-invalid="true", link errors via aria-describedby, focus the first invalid field.

Modal — background not inert

function openModal() {
  document.querySelector('main').inert = true;
  dialogRef.current.focus();
}
function closeModal() {
  document.querySelector('main').inert = false;
  triggerRef.current.focus(); // Return focus to trigger
}

After Each Fix

1. Tab through the component — does keyboard access work?
2. Run axe DevTools or a11y-scan — did violations decrease?
3. Test with a screen reader if the fix involves ARIA or announcements
4. Check contrast if the fix involves visual changes
5. Zoom to 200% if the fix involves layout

After Fixing

Remind the developer to manually test:

• Tab through the component with keyboard only
• Test with VoiceOver (Mac/Safari) or NVDA (Windows/Chrome)
• Check contrast with CCA or DevTools
• Zoom to 200% and verify reflow
• Run axe DevTools scan

Automated tests can verify regressions but can't replace manual testing with assistive technology.