BMAD-METHOD/docs/visual-elements/accessibility-guide.md

BMAD Method Accessibility Guide

This guide ensures that all BMAD Method documentation and visual elements are accessible to users with diverse abilities and needs.

Accessibility Principles

1. Perceivable

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

2. Operable

User interface components and navigation must be operable by all users.

3. Understandable

Information and the operation of user interface must be understandable.

4. Robust

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

Color and Contrast Standards

WCAG AA Compliance

All text and interactive elements meet or exceed WCAG AA standards:

```css /* High contrast color combinations / .high-contrast-text { color: #000000; / Black text / background: #ffffff; / White background / / Contrast ratio: 21:1 */ }

.primary-text { color: #1a365d; /* Dark blue text / background: #ffffff; / White background / / Contrast ratio: 12.6:1 */ }

.secondary-text { color: #4a5568; /* Gray text / background: #ffffff; / White background / / Contrast ratio: 7.2:1 */ }

/* Interactive elements / .interactive-element { color: #ffffff; / White text / background: #2563eb; / Blue background / / Contrast ratio: 8.6:1 */ }

.interactive-element:focus { outline: 2px solid #1d4ed8; outline-offset: 2px; /* Focus indicator clearly visible */ } ```

Color-Blind Friendly Palette

Our color system works for users with various types of color vision deficiency:

```css /* Color-blind friendly palette / :root { --accessible-blue: #0066cc; / Distinguishable blue / --accessible-green: #228b22; / Forest green / --accessible-red: #cc0000; / Clear red / --accessible-orange: #ff8c00; / Dark orange / --accessible-purple: #6a0dad; / Blue violet / --accessible-gray: #666666; / Medium gray */ }

/* Never rely on color alone */ .status-indicator { display: inline-flex; align-items: center; gap: 0.5rem; }

.status-success { color: var(--accessible-green); }

.status-success::before { content: "✓"; font-weight: bold; }

.status-error { color: var(--accessible-red); }

.status-error::before { content: "✗"; font-weight: bold; }

.status-warning { color: var(--accessible-orange); }

.status-warning::before { content: "âš "; font-weight: bold; } ```

Typography and Readability

Font Selection and Sizing

```css /* Accessible typography / body { font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; font-size: 16px; / Minimum 16px for body text / line-height: 1.6; / Adequate line spacing / letter-spacing: 0.01em; / Slight letter spacing for clarity */ }

h1, h2, h3, h4, h5, h6 { font-weight: 600; line-height: 1.3; margin-bottom: 0.5em; }

/* Large text for better readability */ .large-text { font-size: 18px; line-height: 1.7; }

/* Ensure text can be zoomed to 200% */ @media (min-resolution: 2dppx) { body { font-size: 18px; } } ```

Reading Flow and Structure

```html

BMAD Method Documentation

Getting Started

<article>
  <h3>First-Time Setup</h3>
  <p>Clear, concise instructions...</p>
  
  <h4>Environment Configuration</h4>
  <p>Step-by-step guidance...</p>
</article>

Skip to main content Skip to navigation ```

Keyboard Navigation

Focus Management

```css /* Visible focus indicators */ *:focus { outline: 2px solid var(--bmad-primary); outline-offset: 2px; border-radius: 2px; }

/* Enhanced focus for interactive elements */ button:focus, a:focus, input:focus, select:focus, textarea:focus { outline: 3px solid var(--bmad-primary); outline-offset: 2px; box-shadow: 0 0 0 1px rgba(37, 99, 235, 0.2); }

/* Skip links */ .skip-link { position: absolute; top: -40px; left: 6px; background: var(--bmad-primary); color: white; padding: 8px; text-decoration: none; border-radius: 4px; z-index: 1000; }

.skip-link:focus { top: 6px; } ```

Keyboard Interaction Patterns

```javascript // Accessible dropdown menu class AccessibleDropdown { constructor(element) { this.dropdown = element; this.trigger = element.querySelector('.dropdown-trigger'); this.menu = element.querySelector('.dropdown-menu'); this.items = element.querySelectorAll('.dropdown-item');

this.init();

}

init() { // Keyboard event handlers this.trigger.addEventListener('keydown', (e) => { switch(e.key) { case 'Enter': case ' ': case 'ArrowDown': e.preventDefault(); this.openMenu(); this.focusFirstItem(); break; } });

this.items.forEach((item, index) => {
  item.addEventListener('keydown', (e) => {
    switch(e.key) {
      case 'ArrowDown':
        e.preventDefault();
        this.focusNextItem(index);
        break;
      case 'ArrowUp':
        e.preventDefault();
        this.focusPreviousItem(index);
        break;
      case 'Escape':
        e.preventDefault();
        this.closeMenu();
        this.trigger.focus();
        break;
    }
  });
});

}

openMenu() { this.menu.style.display = 'block'; this.trigger.setAttribute('aria-expanded', 'true'); }

closeMenu() { this.menu.style.display = 'none'; this.trigger.setAttribute('aria-expanded', 'false'); }

focusFirstItem() { this.items[0].focus(); }

focusNextItem(currentIndex) { const nextIndex = (currentIndex + 1) % this.items.length; this.items[nextIndex].focus(); }

focusPreviousItem(currentIndex) { const prevIndex = currentIndex === 0 ? this.items.length - 1 : currentIndex - 1; this.items[prevIndex].focus(); } } ```

Screen Reader Support

Semantic HTML and ARIA

```html

BMAD Method Overview

1. Introduction
2. Personas
3. Workflow

Introduction

The BMAD Method is...

<!-- Interactive elements with proper ARIA -->
<div class="persona-selector" role="tablist" aria-label="Select persona">
  <button role="tab" 
          aria-selected="true" 
          aria-controls="pm-panel"
          id="pm-tab">
    Project Manager
  </button>
  <button role="tab" 
          aria-selected="false" 
          aria-controls="architect-panel"
          id="architect-tab">
    System Architect
  </button>
</div>

<div role="tabpanel" 
     aria-labelledby="pm-tab" 
     id="pm-panel">
  <h3>Project Manager Persona</h3>
  <p>Responsible for...</p>
</div>

Project Configuration

<label for="project-name">
  Project Name
  <span aria-label="required" class="required">*</span>
</label>
<input type="text" 
       id="project-name" 
       required 
       aria-describedby="name-help">
<div id="name-help" class="help-text">
  Enter a descriptive name for your project
</div>

<label for="project-type">Project Type</label>
<select id="project-type" aria-describedby="type-help">
  <option value="">Select project type</option>
  <option value="web">Web Application</option>
  <option value="mobile">Mobile Application</option>
  <option value="api">API Service</option>
</select>
<div id="type-help" class="help-text">
  Choose the primary type of project you're building
</div>

\```

Screen Reader Announcements

```javascript // Live region for dynamic content updates class AccessibleNotifications { constructor() { this.createLiveRegion(); }

createLiveRegion() { const liveRegion = document.createElement('div'); liveRegion.setAttribute('aria-live', 'polite'); liveRegion.setAttribute('aria-atomic', 'true'); liveRegion.className = 'sr-only'; liveRegion.id = 'live-region'; document.body.appendChild(liveRegion); }

announce(message, priority = 'polite') { const liveRegion = document.getElementById('live-region'); liveRegion.setAttribute('aria-live', priority); liveRegion.textContent = message;

// Clear after announcement
setTimeout(() => {
  liveRegion.textContent = '';
}, 1000);

} }

// Usage examples const notifications = new AccessibleNotifications();

// Announce progress updates notifications.announce('Step 1 of 4 completed');

// Announce errors with assertive priority notifications.announce('Error: Please fill in all required fields', 'assertive');

// Announce success notifications.announce('Project created successfully'); ```

Image and Media Accessibility

Alternative Text Guidelines

```html

The system architecture shows three main layers: Presentation layer with web and mobile interfaces, Application layer with orchestrator and persona management, and Data layer with knowledge base and templates.

Requirements Architecture

\```

Video and Audio Accessibility

```html

Video Description

This video introduces the BMAD Method, showing how different personas collaborate...

Full Transcript

Welcome to the BMAD Method introduction...

\```

Testing and Validation

Accessibility Testing Checklist

• Keyboard Navigation

  • All interactive elements are keyboard accessible
  • Tab order is logical and intuitive
  • Focus indicators are clearly visible
  • No keyboard traps exist

• Screen Reader Compatibility

  • Content is properly structured with headings
  • Images have appropriate alt text
  • Form labels are properly associated
  • ARIA attributes are used correctly

• Color and Contrast

  • Text meets WCAG AA contrast requirements
  • Color is not the only means of conveying information
  • Interactive elements have sufficient contrast

• Responsive Design

  • Content is readable at 200% zoom
  • No horizontal scrolling at standard zoom levels
  • Touch targets are at least 44px

• Motion and Animation

  • Animations can be disabled via prefers-reduced-motion
  • No content flashes more than 3 times per second
  • Auto-playing media can be paused

Automated Testing Tools

```javascript // Example accessibility testing with axe-core import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('BMAD documentation should be accessible', async () => { const { container } = render(); const results = await axe(container); expect(results).toHaveNoViolations(); });

// Manual testing helpers function announceToScreenReader(message) { const announcement = document.createElement('div'); announcement.setAttribute('aria-live', 'polite'); announcement.setAttribute('aria-atomic', 'true'); announcement.className = 'sr-only'; announcement.textContent = message;

document.body.appendChild(announcement);

setTimeout(() => { document.body.removeChild(announcement); }, 1000); } ```

---

Following these accessibility guidelines ensures that BMAD Method documentation is usable by everyone, regardless of their abilities or the assistive technologies they use.