---

name: accessibility-fundamentals description: | TRIGGERS: "is this accessible?", "a11y check", "screen reader", "WCAG", "keyboard navigation", "adding form", "button click", "interactive", "navigation", "building form", "input field", "dropdown", "modal", "dialog", "focus", "tab order", accessibility, ARIA, alt text, focus management, color contrast, forms, semantic HTML. USE WHEN: Junior is BUILDING forms, buttons, modals, or any interactive UI elements. PROVIDES: WCAG compliance, ARIA patterns, keyboard navigation, screen reader optimization. PROACTIVE: Triggers when junior mentions building interactive elements.

Accessibility Fundamentals Review

"Accessibility is not a feature, it's a requirement. If 15% of users can't use your app, you've failed 15% of users."

When to Apply

Activate this skill when:

• Reviewing JSX with buttons, links, or forms
• Seeing custom interactive components
• Forms with inputs and labels
• Navigation menus
• Modal dialogs
• Any user interaction code

---

The Accessibility Checklist

Must Have (Every Interactive Element)

• Keyboard accessible — All actions work with Tab + Enter/Space
• Focus visible — Clear visual indicator of focused element
• Semantic elements — <button> not <div onClick>
• Form labels — Every input has an associated <label>
• Alt text — Images have descriptive alt attributes
• Sufficient contrast — Text readable against background (4.5:1 ratio)

Should Have (Complex Interactions)

• ARIA labels — Icon-only buttons have aria-label
• Focus trapping — Modals trap focus until closed
• Skip links — "Skip to main content" for keyboard users
• Live regions — Dynamic content announced to screen readers
• Error messages — Linked to inputs with aria-describedby

Never Do

• Rely on color alone — Color should not be the only indicator
• Remove focus outlines — Never outline: none without replacement
• Use divs for buttons — Use semantic <button> or <a>
• Trap users — Always provide escape from modals/menus

---

Common Mistakes (Anti-Patterns)

1. Div as Button

Copy// ❌ BAD: Not keyboard accessible, no semantics
<div onClick={handleClick} className="button">
  Click me
</div>

// ✅ GOOD: Native button element
<button onClick={handleClick} className="button">
  Click me
</button>

Why it matters: <div onClick> doesn't receive keyboard focus, doesn't respond to Enter/Space, and isn't announced as a button by screen readers.

2. Missing Form Labels

Copy// ❌ BAD: Input has no label
<input type="email" placeholder="Email" />

// ✅ GOOD: Label linked to input
<label htmlFor="email">Email</label>
<input id="email" type="email" placeholder="example@email.com" />

// ✅ ALSO GOOD: Wrapping label
<label>
  Email
  <input type="email" />
</label>

3. Icon-Only Buttons

Copy// ❌ BAD: No accessible name
<button onClick={handleDelete}>
  <TrashIcon />
</button>

// ✅ GOOD: ARIA label for screen readers
<button onClick={handleDelete} aria-label="Delete item">
  <TrashIcon aria-hidden="true" />
</button>

4. Removed Focus Styles

Copy/* ❌ BAD: Focus invisible */
button:focus {
  outline: none;
}

/* ✅ GOOD: Custom but visible focus */
button:focus {
  outline: none;
  box-shadow: 0 0 0 3px rgba(66, 153, 225, 0.6);
}

/* ✅ BEST: Use focus-visible */
button:focus-visible {
  outline: 2px solid #4299e1;
  outline-offset: 2px;
}

5. Non-Descriptive Link Text

Copy// ❌ BAD: "Click here" tells screen reader nothing
<p>
  To read our privacy policy, <a href="/privacy">click here</a>.
</p>

// ✅ GOOD: Link text describes destination
<p>
  Read our <a href="/privacy">privacy policy</a>.
</p>

6. Missing Heading Hierarchy

Copy// ❌ BAD: Screen reader can't navigate
<div className="title">Welcome</div>
<div className="subtitle">Getting Started</div>

// ✅ GOOD: Proper headings
<h1>Welcome</h1>
<h2>Getting Started</h2>

---

Socratic Questions

Ask these instead of giving answers:

1. Keyboard: "Can you complete this action using only the keyboard?"
2. Focus: "If I tab through the page, can I see where I am?"
3. Semantics: "What does a screen reader announce for this element?"
4. Labels: "If the placeholder disappears, how do users know what to enter?"
5. Color: "If someone is colorblind, can they still understand this UI?"
6. Alt Text: "If the image doesn't load, what context is lost?"

---

Testing Accessibility

Manual Testing

1. Keyboard test: Navigate entire page with Tab only
2. Focus test: Can you always see where focus is?
3. Zoom test: Does layout break at 200% zoom?
4. Screen reader: Try VoiceOver (Mac) or NVDA (Windows)

Automated Testing

Copy# In your test file
# Pattern: axe-core for React Testing Library
import { axe } from 'jest-axe';

it('should have no a11y violations', async () => {
  const { container } = render(<YourComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

---

ARIA Reference

Common ARIA Attributes

The First Rule of ARIA

"No ARIA is better than bad ARIA."

Use semantic HTML first. Only use ARIA when HTML can't express what you need.

---

Stack-Specific Guidance

React

Copy// Pattern: Button with accessible name
<button
  onClick={handleAction}
  aria-label="Close modal"
>
  <XIcon aria-hidden="true" />
</button>

Form Error Pattern

Copy// Pattern: Error linked to input
<label htmlFor="email">Email</label>
<input
  id="email"
  type="email"
  aria-describedby={error ? "email-error" : undefined}
  aria-invalid={error ? "true" : undefined}
/>
{error && (
  <span id="email-error" role="alert">
    {error}
  </span>
)}

---

Red Flags to Call Out

---

Interview Connection

"I implemented accessibility best practices including semantic HTML, proper form labeling, and keyboard navigation, ensuring our app is usable by everyone."

STAR story material:

• "Identified accessibility issues with our form and fixed them..."
• "Implemented proper focus management in our modal component..."
• "Added screen reader support for our notification system..."

---

MCP Usage

Context7 - Framework Docs

CopyFetch: WAI-ARIA practices
Fetch: React accessibility documentation

Octocode - Real Examples

CopySearch: "aria-label" + "button" patterns
Search: Modal focus trapping implementations

---

Resources

• WCAG 2.1 Guidelines (check Context7)
• Deque's axe-core for automated testing
• WebAIM color contrast checker