Accessibility Annotation Generator

Automatically adds ARIA labels, roles, alt text, and other accessibility annotations to HTML/JSX/Vue templates.

When to Use

• "Make this component accessible"

• "Add ARIA labels"

• "Add alt text to images"

• "Make accessible for screen readers"

• "Add accessibility annotations"

• "WCAG compliance"

Instructions

1. Scan for Accessibility Issues

Analyze HTML/JSX/Vue files for common issues:

Find images without alt text

grep -r "<img" src/ --include=".jsx" --include=".tsx" --include="*.vue" | grep -v "alt="

Find buttons without labels

grep -r "<button" src/ | grep -v "aria-label"

Find form inputs without labels

grep -r "<input" src/ | grep -v "aria-label" | grep -v "<label"

Find interactive elements without role

grep -r "onClick" src/ | grep -v "role="

2. Add Missing Alt Text

Images:

// Before <img src="/logo.png" /> <img src="/photo.jpg" className="avatar" />

// After <img src="/logo.png" alt="Company Logo" /> <img src="/photo.jpg" alt="Profile photo of John Doe" className="avatar" />

// Decorative images (no alt needed, but must be explicit) <img src="/decorative-line.png" alt="" role="presentation" />

Background images (CSS):

// Add ARIA label for meaningful background images <div className="hero-banner" role="img" aria-label="Team collaborating in modern office" style={{ backgroundImage: 'url(/hero.jpg)' }}

3. Add ARIA Labels to Interactive Elements

Buttons:

// Before <button onClick={handleDelete}> <TrashIcon /> </button>

// After <button onClick={handleDelete} aria-label="Delete item"

<TrashIcon aria-hidden="true" /> </button>

// Or with visible text <button onClick={handleDelete}> <TrashIcon aria-hidden="true" /> <span>Delete</span> </button>

Icon-only buttons:

// Before <button onClick={handleEdit}> <EditIcon /> </button>

// After <button onClick={handleEdit} aria-label="Edit profile" title="Edit profile"

<EditIcon aria-hidden="true" /> </button>

Links:

// Before <a href="/settings"> <SettingsIcon /> </a>

// After <a href="/settings" aria-label="Go to settings"> <SettingsIcon aria-hidden="true" /> </a>

// Avoid generic "click here" // Before <a href="/docs">Click here</a>

// After <a href="/docs">Read the documentation</a>

4. Add Form Accessibility

Labels for inputs:

// Before <input type="email" placeholder="Email" />

// After - Method 1: Visible label (preferred) <label htmlFor="email">Email address</label> <input type="email" id="email" name="email" aria-required="true" />

// After - Method 2: aria-label (if no visible label) <input type="email" aria-label="Email address" aria-required="true" placeholder="Email" />

Error messages:

// Before {error && <span className="error">{error}</span>}

// After <input type="email" id="email" aria-invalid={!!error} aria-describedby={error ? "email-error" : undefined} /> {error && ( <span id="email-error" role="alert" className="error"> {error} </span> )}

Required fields:

<label htmlFor="name"> Name <span aria-label="required">*</span> </label> <input type="text" id="name" required aria-required="true" />

Field descriptions:

<label htmlFor="password">Password</label> <input type="password" id="password" aria-describedby="password-requirements" /> <div id="password-requirements"> Must be at least 8 characters with 1 uppercase letter and 1 number </div>

5. Add Semantic HTML and Roles

Navigation:

// Before <div className="nav"> <a href="/">Home</a> <a href="/about">About</a> </div>

// After <nav aria-label="Main navigation"> <a href="/">Home</a> <a href="/about">About</a> </nav>

Landmarks:

<header role="banner"> <nav aria-label="Main navigation">...</nav> </header>

<main role="main"> <section aria-labelledby="products-heading"> <h2 id="products-heading">Our Products</h2> ... </section> </main>

<aside role="complementary" aria-label="Related articles"> ... </aside>

<footer role="contentinfo"> ... </footer>

Lists:

// Before <div className="menu"> <div>Home</div> <div>About</div> </div>

// After <ul role="list"> <li><a href="/">Home</a></li> <li><a href="/about">About</a></li> </ul>

6. Add Keyboard Navigation Support

Focusable elements:

// Before <div onClick={handleClick}>Click me</div>

// After <div role="button" tabIndex={0} onClick={handleClick} onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault() handleClick() } }} aria-label="Submit form"

Click me </div>

// Better: Use actual button <button onClick={handleClick} aria-label="Submit form"> Click me </button>

Skip links:

<a href="#main-content" className="skip-link"> Skip to main content </a>

<main id="main-content"> ... </main>

// CSS .skip-link { position: absolute; top: -40px; left: 0; background: #000; color: white; padding: 8px; z-index: 100; }

.skip-link:focus { top: 0; }

Tab order:

// Control tab order with tabIndex <button tabIndex={1}>First</button> <button tabIndex={2}>Second</button>

// Or keep natural order (preferred) <button>First</button> <button>Second</button>

7. Add Live Regions for Dynamic Content

Announcements:

// Status messages <div role="status" aria-live="polite"> {statusMessage} </div>

// Urgent alerts <div role="alert" aria-live="assertive"> {errorMessage} </div>

// Loading state <div role="status" aria-live="polite" aria-busy={isLoading}

{isLoading ? 'Loading...' : 'Content loaded'} </div>

Progress indicators:

<div role="progressbar" aria-valuenow={progress} aria-valuemin={0} aria-valuemax={100} aria-label="Upload progress"

{progress}% </div>

8. Add Modal/Dialog Accessibility

Modal:

<div role="dialog" aria-modal="true" aria-labelledby="modal-title" aria-describedby="modal-description"

<h2 id="modal-title">Confirm Delete</h2> <p id="modal-description"> Are you sure you want to delete this item? </p>

<button onClick={handleConfirm}>Confirm</button> <button onClick={handleCancel}>Cancel</button> </div>

// Focus management useEffect(() => { if (isOpen) { // Save current focus const previousFocus = document.activeElement

// Focus first element in modal
modalRef.current?.focus()

// Trap focus in modal
const handleKeyDown = (e) => {
  if (e.key === 'Escape') {
    handleClose()
  }
}

document.addEventListener('keydown', handleKeyDown)

return () => {
  document.removeEventListener('keydown', handleKeyDown)
  // Restore focus
  previousFocus?.focus()
}

} }, [isOpen])

9. Add Dropdown/Menu Accessibility

Dropdown menu:

<div> <button aria-expanded={isOpen} aria-haspopup="true" aria-controls="dropdown-menu" onClick={toggleMenu}

Menu

</button>

{isOpen && ( <ul id="dropdown-menu" role="menu" > <li role="menuitem"> <a href="/profile">Profile</a> </li> <li role="menuitem"> <a href="/settings">Settings</a> </li> <li role="menuitem"> <button onClick={handleLogout}>Logout</button> </li> </ul> )} </div>

Accordion:

<div> <h3> <button aria-expanded={isExpanded} aria-controls="panel-1" id="accordion-header-1" onClick={toggle} > Section 1 </button> </h3>

{isExpanded && ( <div id="panel-1" role="region" aria-labelledby="accordion-header-1" > Content here... </div> )} </div>

10. Add Table Accessibility

Data tables:

<table> <caption>Employee Information</caption> <thead> <tr> <th scope="col">Name</th> <th scope="col">Department</th> <th scope="col">Email</th> </tr> </thead> <tbody> <tr> <th scope="row">John Doe</th> <td>Engineering</td> <td>john@example.com</td> </tr> </tbody> </table>

Complex tables:

<table> <thead> <tr> <th id="name" scope="col">Name</th> <th id="monday" scope="col">Monday</th> <th id="tuesday" scope="col">Tuesday</th> </tr> </thead> <tbody> <tr> <th id="john" scope="row">John</th> <td headers="john monday">9-5</td> <td headers="john tuesday">9-5</td> </tr> </tbody> </table>

11. Framework-Specific Patterns

React:

import { useEffect, useRef } from 'react'

function AccessibleComponent() { const headingRef = useRef(null)

// Announce page changes to screen readers useEffect(() => { headingRef.current?.focus() document.title = 'New Page Title' }, [])

return ( <main> <h1 ref={headingRef} tabIndex={-1}> Page Title </h1> </main> ) }

Vue:

<template> <button @click="handleClick" :aria-label="buttonLabel" :aria-pressed="isPressed"

<Icon :aria-hidden="true" />

{{ text }}

</button> </template>

<script> export default { computed: { buttonLabel() { return ${this.text} (${this.isPressed ? 'active' : 'inactive'}) } } } </script>

Best Practices

DO:

• Use semantic HTML first (button, not div with onClick)

• Provide visible labels when possible

• Use aria-label only when no visible label

• Test with keyboard only (no mouse)

• Test with screen reader (NVDA, JAWS, VoiceOver)

• Maintain focus order that makes sense

• Announce dynamic changes

DON'T:

• Use positive tabIndex (except -1 for programmatic focus)

• Hide content that should be accessible

• Use color alone to convey information

• Create keyboard traps

• Disable zoom/pinch

• Remove focus outlines without replacement

Testing Checklist

• All images have alt text

• All buttons/links have labels

• All form inputs have labels

• Keyboard navigation works

• Focus visible on all elements

• Color contrast meets WCAG AA (4.5:1)

• Screen reader announces content correctly

• No keyboard traps

• Skip links work

• ARIA roles/labels correct

• Live regions announce updates

• Modals trap focus correctly

• Errors announced to screen reader