Skip to content

ACCESSIBILITY.md

Latest commit

 

History

History
212 lines (172 loc) · 5.71 KB

ACCESSIBILITY.md

File metadata and controls

212 lines (172 loc) · 5.71 KB

Accessibility Audit & ARIA Implementation Guide

Overview

This document outlines the accessibility improvements made to the terminal-ui component library, including ARIA attributes, keyboard navigation, and semantic HTML practices.

ARIA Implementation

1. Terminal Component

  • role="application": Identifies the component as an interactive application
  • aria-label: Describes the terminal purpose
  • aria-live="polite": Announces new output to screen readers
  • aria-atomic="true": Announces complete output changes
<div
  role="application"
  aria-label="Terminal interface"
  aria-live="polite"
  aria-atomic="true"
>
  {/* Terminal content */}
</div>

2. TerminalProgress Component

  • role="progressbar": Semantic role for progress indicators
  • aria-valuenow: Current progress percentage
  • aria-valuemin/max: Progress range (0-100)
  • aria-label: Descriptive label for the progress
<div
  role="progressbar"
  aria-valuenow={percent}
  aria-valuemin={0}
  aria-valuemax={100}
  aria-label={label}
>
  {/* Progress bar content */}
</div>

3. TerminalPrompt Component

  • role="textbox": Input field semantic role
  • aria-label: Describes the prompt purpose
  • aria-autocomplete="list": Indicates autocomplete availability
  • aria-expanded: Shows if suggestions are visible
  • aria-controls: Links to suggestion list
<input
  role="textbox"
  aria-label="Terminal command input"
  aria-autocomplete="list"
  aria-expanded={suggestions.length > 0}
  aria-controls="suggestions-list"
/>

4. TerminalTable Component

  • role="table": Semantic table role
  • role="row": Table row elements
  • role="columnheader": Header cells
  • role="cell": Data cells
  • aria-colindex: Column position
  • aria-rowindex: Row position
<div role="table" aria-label="Data table">
  <div role="row">
    <div role="columnheader" aria-colindex={1}>Header</div>
  </div>
  <div role="row">
    <div role="cell" aria-colindex={1}>Data</div>
  </div>
</div>

5. TerminalTree Component

  • role="tree": Hierarchical structure role
  • role="treeitem": Individual tree nodes
  • aria-expanded: Node expansion state
  • aria-level: Node nesting level
  • aria-posinset/aria-setsize: Position in node set
<div role="tree">
  <div
    role="treeitem"
    aria-expanded={isExpanded}
    aria-level={depth}
    aria-posinset={position}
    aria-setsize={totalSiblings}
  >
    {/* Node content */}
  </div>
</div>

Keyboard Navigation

Terminal Pane

  • Arrow Up/Down: Navigate command history
  • Tab: Auto-complete command
  • Enter: Execute command
  • Escape: Clear suggestions

TerminalPrompt

  • Arrow Up: Previous command in history
  • Arrow Down: Next command in history
  • Tab: Auto-complete with first suggestion
  • Escape: Close suggestions dropdown

TerminalTree

  • Arrow Up/Down: Navigate between nodes
  • Arrow Left: Collapse node
  • Arrow Right: Expand node
  • Enter: Activate node
  • Space: Toggle node expansion

TerminalTable

  • Tab: Navigate between cells
  • Arrow Keys: Move within table
  • Enter: Activate cell action (if applicable)

Semantic HTML

Best Practices Implemented

  1. Meaningful Headings: Use <h1> through <h6> for document structure
  2. List Elements: Use <ul>, <ol>, <li> for lists
  3. Form Controls: Proper <label> association with inputs
  4. Landmarks: Use <main>, <nav>, <aside> for page structure
  5. Alt Text: Provide descriptive alt text for images

Color Contrast

All text meets WCAG AA standards:

  • Normal text: 4.5:1 contrast ratio
  • Large text: 3:1 contrast ratio
  • UI components: 3:1 contrast ratio

Screen Reader Support

Announcements

  • New terminal output is announced via aria-live="polite"
  • Progress updates are announced with aria-valuenow changes
  • Autocomplete suggestions are announced as they appear

Navigation

  • All interactive elements are keyboard accessible
  • Focus indicators are clearly visible
  • Tab order follows logical page flow

Testing Recommendations

Automated Testing

# Run accessibility tests
npm run test:a11y

# Lighthouse audit
npm run audit:lighthouse

# axe DevTools integration
npm run test:axe

Manual Testing

  1. Keyboard Navigation: Test all features using only keyboard
  2. Screen Reader: Test with NVDA, JAWS, or VoiceOver
  3. Zoom: Test at 200% zoom level
  4. Color Blindness: Test with color blindness simulator
  5. Motion: Test with reduced motion preferences

WCAG 2.1 Compliance

Level A

  • ✅ Perceivable: All content is perceivable
  • ✅ Operable: All functionality is keyboard accessible
  • ✅ Understandable: Content is clear and predictable
  • ✅ Robust: Compatible with assistive technologies

Level AA

  • ✅ Contrast (Enhanced): 4.5:1 for normal text
  • ✅ Resize Text: Content reflows at 200% zoom
  • ✅ Focus Visible: Clear focus indicators
  • ✅ Language of Page: Language is identified

Future Improvements

  1. High Contrast Mode: Add high contrast theme variant
  2. Reduced Motion: Respect prefers-reduced-motion media query
  3. Dyslexia-Friendly Font: Optional dyslexia-friendly font option
  4. Text Spacing: Allow customizable text spacing
  5. Captions: Add captions for any video content

Resources

Feedback

If you find accessibility issues, please open an issue with:

  • Component affected
  • Assistive technology used
  • Expected vs. actual behavior
  • Steps to reproduce