Skip to content

♿ Accessibility Guide

Comprehensive accessibility documentation for Chekameh.

🎯 Accessibility Philosophy

Chekameh is built with accessibility as a core principle, not an afterthought:

  • Inclusive by Default - Features work for everyone
  • WCAG 2.1 AA Compliant - Industry standard compliance
  • Multilingual - English and Persian support
  • RTL-Ready - Right-to-left text handling
  • Keyboard Navigation - Full keyboard support
  • Screen Reader Compatible - Works with assistive technology

♿ WCAG 2.1 Compliance

Level A (Basic)

✅ All requirements met

  • Adequate color contrast (4.5:1 for normal text)
  • Proper heading hierarchy
  • Alternative text for images
  • Keyboard accessible

Level AA (Intermediate)

✅ All requirements met

  • Enhanced color contrast (4.5:1 for all text)
  • Focus indicators visible
  • No timing restrictions
  • Error prevention

Level AAA (Enhanced)

🎯 Targeted compliance

  • Extra-high color contrast (7:1)
  • Audio descriptions for video
  • Sign language interpretation
  • Plain language explanations

🎨 Visual Accessibility

Color Contrast

Text Contrast Ratios:

/* All text on backgrounds meets or exceeds AA standards */

/* Body text on cream background */
#1A2A2A on #F9F6F0 → 7.1:1 ratio ✅ (AAA)

/* Links on cream background */
#009688 on #F9F6F0 → 5.5:1 ratio ✅ (AA)

/* Buttons with turquoise background */
White text on #009688 → 4.5:1 ratio ✅ (AA)

Check Contrast:

Color Blindness

Chekameh works for users with:

  • Deuteranopia (red-green)
  • Protanopia (red-green)
  • Tritanopia (blue-yellow)

Test with:

⌨️ Keyboard Navigation

Supported Keys

Key Action
Tab Move to next interactive element
Shift+Tab Move to previous element
Enter Activate button/link
Space Toggle checkbox or activate button
Arrow Keys Navigate timeline slider
Escape Close panel
Alt+/ Help menu (browser dependent)

Focus Management

/* Focus indicators are always visible */
button:focus,
input:focus,
a:focus {
  outline: 2px solid var(--turquoise);
  outline-offset: 2px;
}

Keyboard Testing Checklist

  • Tab through all interactive elements
  • Focus indicators visible
  • Can reach and activate all buttons
  • Timeline slider responds to arrow keys
  • Can close panels with Escape key
  • No keyboard traps (stuck in any element)

🔊 Screen Reader Support

Supported Screen Readers

  • NVDA (Windows) - Free, open source
  • JAWS (Windows) - Commercial, premium features
  • VoiceOver (macOS, iOS) - Built-in Apple
  • TalkBack (Android) - Built-in Android
  • ORCA (Linux) - Free, open source

ARIA Labels

All interactive elements have proper labels:

<!-- Buttons have accessible names -->
<button aria-label="Read poet biography">Read More</button>

<!-- Form controls have labels -->
<input id="search" aria-label="Search poets" />

<!-- Landmarks are semantic -->
<header role="banner">...</header>
<main role="main">...</main>
<nav role="navigation">...</nav>

Testing with Screen Readers

Windows (NVDA):

  1. Download NVDA
  2. Start reading (Insert+Down Arrow)
  3. Navigate with arrow keys
  4. Check headings announce correctly

macOS (VoiceOver):

  1. Enable: System Preferences → Accessibility → VoiceOver
  2. Start reading (Command+F5)
  3. Use VO (Control+Option) for navigation

Screen Reader Testing Checklist

  • Page has proper heading hierarchy (H1 → H2 → H3)
  • Images have alternative text
  • Buttons have clear labels
  • Links describe their purpose
  • Form fields have associated labels
  • Dynamic content announces updates
  • No irrelevant repeated content

📱 Mobile & Touch Accessibility

Touch Target Size

/* All interactive elements 48px × 48px minimum */
button {
  min-width: 48px;
  min-height: 48px;
  padding: 12px;
}

Mobile Screen Reader Support

iOS VoiceOver:

  • Settings → Accessibility → VoiceOver → On
  • Gestures: Tap, swipe right (next), swipe left (previous)

Android TalkBack:

  • Settings → Accessibility → TalkBack → On
  • Gestures: Tap, swipe right (next), swipe left (previous)

Testing Checklist

  • Touch targets at least 48×48 pixels
  • Landscape and portrait both work
  • Text readable without zoom
  • No horizontal scrolling needed
  • Tested with phone VoiceOver/TalkBack

🔤 Typography Accessibility

Font Choices

/* Dyslexia-friendly fonts */
--font-fa: "Vazirmatn", sans-serif; /* Clear Persian font */
--font-en: "Cormorant Garamond", serif; /* Easy to read English */
--font-code: "Roboto Mono", monospace; /* Monospace for code */

Font Size

/* Minimum 16px for body text */
body {
  font-size: 16px; /* ✅ Meets WCAG AA */
  line-height: 1.5; /* ✅ Adequate spacing */
}

/* Responsive scaling */
@media (max-width: 768px) {
  body {
    font-size: 15px; /* Never below 14px */
  }
}

Line Height & Spacing

/* Adequate spacing for readability */
body {
  line-height: 1.5; /* ✅ Minimum 1.5 for body */
}

h1 {
  line-height: 1.2; /* ✅ Minimum 1.2 for headings */
}

p {
  margin-bottom: 1.5rem; /* ✅ Paragraph spacing */
  letter-spacing: 0.02em; /* ✅ Comfortable letter spacing */
}

Text Resizing

/* Allows user zoom up to 200% */
meta {
  viewport = "width=device-width, initial-scale=1.0";
  /* Do NOT use user-scalable=no */
}

🌐 Language & RTL Support

Bilingual Content

<!-- Language specified -->
<html lang="fa" dir="rtl">
  <head>
    <meta charset="UTF-8" />
    <meta lang="fa" />
  </head>

  <!-- Content direction proper -->
  <p dir="rtl" lang="fa">متن فارسی</p>
  <p dir="ltr" lang="en">English text</p>
</html>

RTL Testing Checklist

  • Persian text displays right-to-left
  • Numbers display left-to-right
  • Mixed content (Persian + English) handled correctly
  • Timeline slider handles RTL
  • Panel navigation works RTL
  • All margins/padding flipped for RTL

🎯 Focus Management

Focus Visible

/* Focus always visible - NEVER remove outline */
*:focus {
  outline: 2px solid var(--turquoise);
  outline-offset: 2px;
}

/* ❌ NEVER do this */
*:focus {
  outline: none; /* Removes accessibility! */
}

Focus Order

<!-- Tab order follows document flow -->
<!-- For custom components, use tabindex carefully -->
<div role="tablist">
  <button role="tab" tabindex="0">Tab 1</button>
  <!-- Focused by default -->
  <button role="tab" tabindex="-1">Tab 2</button>
  <!-- Not in tab order -->
  <button role="tab" tabindex="-1">Tab 3</button>
</div>

🔔 Dynamic Content & Updates

Announce Changes

/* Use ARIA live regions for updates */
<div aria-live="polite" aria-atomic="true" id="status">
  <!-- Updates announced to screen readers -->
</div>

// Update content
document.getElementById('status').textContent = 'Poet loaded';
// Screen reader announces: "Poet loaded"

Loading States

<!-- Indicate loading status -->
<div aria-busy="true">Loading data...</div>

<!-- When done -->
<div aria-busy="false">Content loaded</div>

📋 Forms & Input Accessibility

Form Labels

<!-- ✅ Proper label association -->
<label for="poet-search">Search poets:</label>
<input id="poet-search" type="text" />

<!-- ❌ Not accessible -->
<input type="text" placeholder="Search poets:" />

Error Messages

<!-- Error clearly associated with input -->
<label for="email">Email:</label>
<input id="email" type="email" aria-describedby="email-error" />
<span id="email-error" role="alert"> Please enter a valid email </span>

Required Fields

<!-- Clearly marked -->
<label for="name"> Name <span aria-label="required">*</span> </label>
<input id="name" required aria-required="true" />

🧪 Testing Accessibility

Automated Tools

# Install accessibility testing tools
npm install --save-dev @axe-core/react
npm install --save-dev wave  # WAVE browser extension
npm install --save-dev lighthouse  # Built into Chrome DevTools

Running Tests:

  1. Chrome DevTools → Lighthouse → Accessibility
  2. Install WAVE extension → Run audit
  3. Use axe-core plugin for detailed analysis

Manual Testing

Keyboard Testing:

  • Tab through entire interface
  • Try navigation with only keyboard
  • Check focus indicators are visible

Screen Reader Testing:

  • Download NVDA or use built-in VoiceOver
  • Navigate through content
  • Verify page structure makes sense

Color Contrast:

  • Use color contrast checker tool
  • Test with color blindness simulator
  • Ensure meaningful information not in color alone

Testing Checklist

  • Keyboard navigation works
  • Screen reader compatible
  • Color contrast adequate
  • Focus indicators visible
  • Resize text to 200%
  • Test with NVDA/JAWS
  • Tested on mobile
  • No timing issues
  • Error messages clear
  • Language tags present

📚 Accessibility Resources

Learning

Tools

Testing

✅ Accessibility Audit Checklist

Before any release:

  • WCAG 2.1 AA compliance verified
  • All interactive elements keyboard accessible
  • Focus indicators visible
  • Color contrast 4.5:1 minimum
  • Headings properly structured (H1 → H6)
  • Images have alt text
  • Forms have associated labels
  • Error messages associated with inputs
  • RTL text displays correctly
  • Mobile screen readers tested
  • Zoom to 200% still functional
  • No keyboard traps
  • ARIA labels where needed
  • No auto-playing audio/video
  • Color not sole means of conveying info

🤝 Contributing Accessibility

Found an accessibility issue?

  1. Report on GitHub
  2. Include: issue type, browser, reproduction steps
  3. Mention accessibility concern specifically
  4. Reference WCAG guideline if applicable

📞 Getting Help

Accessibility benefits everyone. Thank you for helping Chekameh be inclusive! ♿💙