Web Accessibility Fundamentals: Building for Everyone

<!-- ❌ Bad: Non-semantic -->
<div class="header">
  <div class="nav">
    <div onclick="navigate()">Home</div>
    <div onclick="navigate()">About</div>
  </div>
</div>
<div class="main">
  <div class="article">
    <div class="title">Article Title</div>
    <div class="content">...</div>
  </div>
</div>

<!-- ✅ Good: Semantic -->
<header>
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
</header>
<main>
  <article>
    <h1>Article Title</h1>
    <p>...</p>
  </article>
</main>

<header>      <!-- Site/page header -->
<nav>         <!-- Navigation -->
<main>        <!-- Main content (one per page) -->
<article>     <!-- Self-contained content -->
<section>     <!-- Thematic grouping -->
<aside>       <!-- Tangential content -->
<footer>      <!-- Footer -->

<h1> to <h6>  <!-- Headings (hierarchy matters) -->
<button>      <!-- Interactive buttons -->
<a>           <!-- Links -->
<form>        <!-- Forms -->
<label>       <!-- Form labels -->

<!-- ❌ Bad: No alt -->
<img src="product.jpg">

<!-- ✅ Good: Descriptive alt -->
<img src="product.jpg" alt="Red leather handbag with gold clasp">

<!-- Decorative images -->
<img src="decoration.svg" alt="" role="presentation">

<!-- Complex images -->
<img 
  src="chart.png" 
  alt="Sales chart showing 30% increase in Q4"
  longdesc="#chart-description"
>
<div id="chart-description">
  Detailed description of the chart data...
</div>

<!-- ❌ Bad: No label -->
<input type="email" placeholder="Email">

<!-- ✅ Good: Explicit label -->
<label htmlFor="email">Email Address</label>
<input id="email" type="email" />

<!-- Alternative: Wrapping label -->
<label>
  Email Address
  <input type="email" />
</label>

<!-- aria-label when visual label isn't needed -->
<button aria-label="Close dialog">×</button>

<!-- ❌ Bad: Icon without text -->
<button>
  <TrashIcon />
</button>

<!-- ✅ Good: Visible text -->
<button>
  <TrashIcon /> Delete
</button>

<!-- ✅ Good: aria-label -->
<button aria-label="Delete item">
  <TrashIcon />
</button>

/* ❌ Bad: Removing focus outline */
button:focus {
  outline: none; /* Never do this! */
}

/* ✅ Good: Custom but visible focus */
button:focus {
  outline: 2px solid #0070f3;
  outline-offset: 2px;
}

/* Modern focus-visible (only for keyboard) */
button:focus-visible {
  outline: 2px solid #0070f3;
  outline-offset: 2px;
}

<!-- Natural tab order (default) -->
<button>First</button>
<button>Second</button>
<button>Third</button>

<!-- ❌ Bad: Forcing unusual order -->
<button tabindex="3">Third</button>
<button tabindex="1">First</button>
<button tabindex="2">Second</button>

<!-- ✅ Good: tabindex for non-interactive elements -->
<div tabindex="0" role="button" onClick={handler}>
  Click me
</div>

<!-- tabindex="-1" for programmatic focus only -->
<div tabindex="-1" ref={modalRef}>
  Modal content (focused when opened)
</div>

// ❌ Bad: Only mouse events
<div onClick={handleClick}>Click me</div>

// ✅ Good: Keyboard support
<div 
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      handleClick();
    }
  }}
>
  Click me
</div>

// ✅ Better: Use button element
<button onClick={handleClick}>Click me</button>

Level AA (Minimum):
- Normal text: 4.5:1
- Large text (18pt+): 3:1

Level AAA (Enhanced):
- Normal text: 7:1
- Large text: 4.5:1

/* ❌ Bad: Low contrast (2.1:1) */
.text {
  color: #999;  /* Light gray */
  background: #fff;  /* White */
}

/* ✅ Good: High contrast (7:1) */
.text {
  color: #333;  /* Dark gray */
  background: #fff;  /* White */
}

/* Check contrast for all states */
.button {
  color: #fff;
  background: #0070f3;  /* Check this */
}

.button:hover {
  background: #0051cc;  /* And this */
}

.button:disabled {
  background: #ccc;  /* And this */
}

// ❌ Bad: Color only
<span style={{ color: 'red' }}>Error: Invalid email</span>

// ✅ Good: Icon + color + text
<span style={{ color: 'red' }}>
  <ErrorIcon /> Error: Invalid email
</span>

// Form validation
<input 
  aria-invalid="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert">
  Please enter a valid email address
</span>

<!-- ✅ Best: Semantic HTML -->
<button>Click me</button>

<!-- ⚠️ OK but unnecessary -->
<div role="button" tabindex="0">Click me</div>

<!-- Labels -->
<button aria-label="Close dialog">×</button>
<input aria-labelledby="email-label">
<span id="email-label">Email</span>

<!-- Descriptions -->
<input 
  aria-describedby="password-hint"
  type="password"
>
<span id="password-hint">
  Must be at least 8 characters
</span>

<!-- States -->
<button aria-pressed="true">Bold</button>
<div aria-expanded="false">Collapsed</div>
<input aria-invalid="true">
<div aria-hidden="true">Hidden from screen readers</div>

<!-- Live regions -->
<div role="alert">Form submitted successfully!</div>
<div aria-live="polite">Loading...</div>

<!-- Roles -->
<div role="navigation">...</div>
<div role="dialog" aria-modal="true">...</div>
<div role="tablist">
  <button role="tab" aria-selected="true">Tab 1</button>
  <button role="tab" aria-selected="false">Tab 2</button>
</div>

function Accordion({ items }) {
  const [expanded, setExpanded] = useState(null);
  
  return (
    <div>
      {items.map((item, index) => (
        <div key={index}>
          <button
            aria-expanded={expanded === index}
            aria-controls={`panel-${index}`}
            onClick={() => setExpanded(expanded === index ? null : index)}
          >
            {item.title}
          </button>
          <div
            id={`panel-${index}`}
            role="region"
            aria-labelledby={`button-${index}`}
            hidden={expanded !== index}
          >
            {item.content}
          </div>
        </div>
      ))}
    </div>
  );
}

// Jest + Testing Library
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

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