Accessibility Guidelines

Building for everyone: humans with disabilities, assistive technologies, and AI agents

Here's the secret: accessibility and agent-friendliness are the same thing.Screen readers, voice assistants, and AI agents all rely on the same semantic structure, ARIA attributes, and clear content hierarchy. When you build for accessibility, you're automatically building for agents—and vice versa.

This isn't a coincidence. Both assistive technologies and AI agents need to understand your content without seeing it. Both navigate using semantic landmarks. Both need explicit labels for interactive elements. Both benefit from structured, meaningful markup. Accessibility isn't a separate concern in BiModal Design—it's the foundation.

Why Accessibility = Agent-Friendliness

Screen Readers Need

→Semantic HTML structure
→ARIA labels for context
→Clear heading hierarchy
→Descriptive link text
→Form labels and associations
→Alternative text for images

AI Agents Need

→Semantic HTML structure
→ARIA labels for context
→Clear heading hierarchy
→Descriptive link text
→Form labels and associations
→Alternative text for images

Notice something? They're identical. When you fix accessibility issues, you're simultaneously making your site more agent-friendly. Every ARIA label you add helps both screen reader users and AI agents. Every semantic HTML element serves both audiences.

WCAG Compliance Basics

The Web Content Accessibility Guidelines (WCAG) are the international standard for web accessibility. They define three conformance levels:

Level A

Minimum level of accessibility. Addresses the most critical barriers.

Essential but not sufficient for most sites.

Level AA

Recommended standard. Addresses major accessibility barriers.

Target this level for BiModal sites.

Level AAA

Highest level. Addresses all accessibility concerns.

Difficult to achieve for all content.

💡 BiModal Recommendation

Aim for WCAG 2.1 Level AA compliance as your baseline. This balances accessibility, feasibility, and legal requirements (many jurisdictions require AA). Achieving AA compliance automatically makes your site highly agent-friendly.

The Four Principles: POUR

WCAG is organized around four core principles. Every guideline falls under one of these:

1. Perceivable

Information and UI components must be presentable to users in ways they can perceive.

Key Requirements:

• Provide text alternatives for non-text content (images, videos)
• Provide captions and alternatives for multimedia
• Create content that can be presented in different ways
• Make it easier for users to see and hear content
• Use sufficient color contrast (4.5:1 for normal text, 3:1 for large)

<!-- ✓ Good: Perceivable image -->
<img
  src="chart.png"
  alt="Bar chart showing 40% increase in sales from Q3 to Q4"
/>

<!-- ✓ Good: Sufficient contrast -->
<button style="background: #0066cc; color: white;">
  <!-- 4.5:1 contrast ratio -->
  Submit
</button>

<!-- ✗ Bad: No alt text -->
<img src="chart.png" />

<!-- ✗ Bad: Poor contrast -->
<button style="background: #cccccc; color: #dddddd;">
  <!-- 1.2:1 - too low -->
  Submit
</button>

2. Operable

UI components and navigation must be operable by all users.

Key Requirements:

• Make all functionality available from a keyboard
• Give users enough time to read and use content
• Don't design content that causes seizures (flashing)
• Provide ways to help users navigate and find content
• Make it easier to use inputs other than keyboard

<!-- ✓ Good: Keyboard operable -->
<button onClick={handleClick}>
  Click me
</button>

<!-- ✓ Good: Skip to main content -->
<a href="#main" class="skip-link">
  Skip to main content
</a>

<!-- ✗ Bad: Not keyboard accessible -->
<div onClick={handleClick}>
  Click me
</div>

<!-- ✗ Bad: Auto-playing video without controls -->
<video autoplay>
  <source src="video.mp4" />
</video>

3. Understandable

Information and operation of UI must be understandable.

Key Requirements:

• Make text content readable and understandable
• Make web pages appear and operate in predictable ways
• Help users avoid and correct mistakes
• Use clear, simple language when possible
• Provide helpful error messages and instructions

<!-- ✓ Good: Clear error message -->
<form>
  <label for="email">Email</label>
  <input
    type="email"
    id="email"
    aria-describedby="email-error"
    aria-invalid="true"
  />
  <p id="email-error" role="alert">
    Please enter a valid email address (e.g., name@example.com)
  </p>
</form>

<!-- ✗ Bad: Unclear error -->
<form>
  <input type="email" />
  <p style="color: red;">Invalid!</p>
</form>

4. Robust

Content must be robust enough to be interpreted reliably by a wide variety of user agents, including assistive technologies.

Key Requirements:

• Maximize compatibility with current and future user agents
• Use valid HTML (well-formed markup)
• Provide names, roles, and values for custom components
• Ensure parsing and compatibility with assistive technologies

<!-- ✓ Good: Valid, semantic HTML -->
<nav aria-label="Main navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

<!-- ✓ Good: Custom component with ARIA -->
<div
  role="button"
  tabindex="0"
  aria-label="Close dialog"
  onKeyPress={handleKeyPress}
>
  ×
</div>

<!-- ✗ Bad: Invalid HTML -->
<div>
  <p>Paragraph
  <span>Unclosed tags
</div>

All functionality must be accessible via keyboard. This serves keyboard-only users, power users, and helps agents understand interactive elements.

Essential Keyboard Shortcuts

TabMove to next interactive element

Shift + TabMove to previous element

EnterActivate link or button

SpaceActivate button, toggle checkbox

EscClose dialog or modal

Arrow keysNavigate within widgets

Focus Management Rules

✓ Visible focus indicators on all interactive elements
✓ Logical tab order (left-to-right, top-to-bottom)
✓ Skip links for keyboard users
✓ Focus trapped in modals until closed
✓ Focus returned after modal closes
✗ Never remove outline without replacement
✗ Never use tabindex values > 0

Skip Link Implementation

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

<style>
.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  background: #000;
  color: #fff;
  padding: 8px;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}
</style>

<main id="main">
  <!-- Main content -->
</main>

⚠ Testing Your Keyboard Navigation

Unplug your mouse and try using your site with only the keyboard. Can you reach every interactive element? Can you complete core tasks? If not, your site isn't accessible to keyboard users or agents who navigate via keyboard simulation.

Color and Contrast

WCAG Contrast Requirements

Level AA:

• Normal text: 4.5:1 minimum
• Large text (18pt+): 3:1 minimum
• UI components: 3:1 minimum

Level AAA:

• Normal text: 7:1 minimum
• Large text: 4.5:1 minimum

Don't Rely on Color Alone

Color-blind users and agents can't distinguish colors. Always provide additional cues:

✓ Icons + color for status
✓ Text labels + color
✓ Patterns + color in charts
✗ Red/green for errors/success only

Good vs Bad Color Usage

<!-- ✗ Bad: Color only -->
<p style="color: red;">Error</p>
<p style="color: green;">Success</p>

<!-- ✓ Good: Icon + color + text -->
<p style="color: #dc2626;">
  <svg aria-hidden="true">❌</svg>
  <strong>Error:</strong> Please enter a valid email
</p>

<p style="color: #16a34a;">
  <svg aria-hidden="true">✓</svg>
  <strong>Success:</strong> Your message was sent
</p>

Alternative Text for Images

Alt text serves both screen reader users and AI agents. It's required for all images with content or function.

Informative Images

Describe the content and purpose:

<!-- ✓ Good: Descriptive alt text -->
<img
  src="revenue-chart.png"
  alt="Line chart showing 25% revenue increase from Q1 to Q4 2024"
/>

<!-- ✗ Bad: Generic alt text -->
<img src="chart.png" alt="Chart" />

Decorative Images

Use empty alt text or aria-hidden:

<!-- ✓ Good: Empty alt for decorative image -->
<img src="divider.png" alt="" />

<!-- ✓ Good: Hide from assistive tech -->
<img src="divider.png" aria-hidden="true" />

<!-- ✗ Bad: Describing decoration -->
<img src="divider.png" alt="Decorative line separator" />

Functional Images (Buttons, Links)

Describe the function, not the image:

<!-- ✓ Good: Describes function -->
<button>
  <img src="trash.svg" alt="Delete item" />
</button>

<a href="/search">
  <img src="magnify.svg" alt="Search" />
</a>

<!-- ✗ Bad: Describes image -->
<button>
  <img src="trash.svg" alt="Trash icon" />
</button>

Forms and Labels

Properly labeled forms are essential for both accessibility and agent comprehension.

Complete Accessible Form

<form action="/contact" method="POST">
  <!-- Text input with label -->
  <div>
    <label for="name">
      Name <span aria-label="required">*</span>
    </label>
    <input
      type="text"
      id="name"
      name="name"
      required
      aria-required="true"
    />
  </div>

  <!-- Input with hint text -->
  <div>
    <label for="email">Email</label>
    <input
      type="email"
      id="email"
      name="email"
      aria-describedby="email-hint"
      required
    />
    <p id="email-hint">We'll never share your email</p>
  </div>

  <!-- Input with error -->
  <div>
    <label for="phone">Phone</label>
    <input
      type="tel"
      id="phone"
      name="phone"
      aria-describedby="phone-error"
      aria-invalid="true"
    />
    <p id="phone-error" role="alert">
      Please enter a valid phone number (e.g., 555-123-4567)
    </p>
  </div>

  <!-- Radio group -->
  <fieldset>
    <legend>Contact preference</legend>
    <label>
      <input type="radio" name="contact" value="email" />
      Email
    </label>
    <label>
      <input type="radio" name="contact" value="phone" />
      Phone
    </label>
  </fieldset>

  <!-- Checkbox -->
  <label>
    <input type="checkbox" name="subscribe" />
    Subscribe to newsletter
  </label>

  <!-- Submit button -->
  <button type="submit">Send Message</button>
</form>

✓ DO

• Use <label> for every input
• Associate labels with for attribute
• Use <fieldset> for radio/checkbox groups
• Provide helpful error messages
• Use aria-describedby for hints

✗ DON'T

• Use placeholder as label
• Leave inputs without labels
• Use generic error messages ("Error")
• Rely only on color for validation
• Use title attribute as label

Testing Tools

axe DevTools

Browser extension that automatically detects accessibility issues

Get axe DevTools →

WAVE

Visual accessibility evaluation tool with inline highlighting

Use WAVE →

Lighthouse

Built into Chrome DevTools - audits accessibility automatically

DevTools → Lighthouse → Accessibility

Color Contrast Checker

Verify WCAG contrast ratios for text and UI elements

Check Contrast →

Screen Readers

Test with actual screen readers

• NVDA (Windows, free)
• JAWS (Windows, paid)
• VoiceOver (macOS/iOS)

pa11y

Automated accessibility testing in CI/CD pipelines

npm install -g pa11y

Accessibility = Universal Access

Remember: every accessibility improvement you make simultaneously improves your site for AI agents. Screen readers and agents both rely on semantic structure, clear labels, and logical organization. By building accessibly, you're automatically building for the BiModal future.

Continue to Testing & Validation →

← Progressive Enhancement Testing & Validation →

Accessibility Guidelines

Why Accessibility = Agent-Friendliness

Screen Readers Need

AI Agents Need

WCAG Compliance Basics

Level A

Level AA

Level AAA

The Four Principles: POUR

1. Perceivable

Key Requirements:

2. Operable

Key Requirements:

3. Understandable

Key Requirements:

4. Robust

Key Requirements:

Keyboard Navigation

Essential Keyboard Shortcuts

Focus Management Rules

⚠ Testing Your Keyboard Navigation

Color and Contrast

WCAG Contrast Requirements

Level AA:

Level AAA:

Don't Rely on Color Alone

Alternative Text for Images

Informative Images

Decorative Images

Functional Images (Buttons, Links)

Forms and Labels

✓ DO

✗ DON'T

Testing Tools

axe DevTools

WAVE

Lighthouse

Color Contrast Checker

Screen Readers

pa11y

Accessibility Quick Checklist

Structure

Images & Media

Forms

Keyboard & Focus

Color & Contrast

Content

Accessibility = Universal Access