nself-chat (nchat) - Comprehensive Accessibility Documentation

Version: 1.0.0 | Last Updated: January 31, 2026

1. Overview
2. WCAG 2.1 AAA Compliance
3. Keyboard Navigation
4. Screen Reader Support
5. Visual Accessibility
6. Motion & Animation
7. Accessibility Settings
8. Testing & Validation
9. Common Patterns
10. Resources

nself-chat is committed to providing an accessible communication platform for all users, regardless of their abilities or assistive technologies. Our accessibility features are designed to meet and exceed WCAG 2.1 Level AAA standards.

1. Perceivable - Information and UI components must be presentable to users in ways they can perceive
2. Operable - UI components and navigation must be operable
3. Understandable - Information and operation of UI must be understandable
4. Robust - Content must be robust enough to be interpreted by a wide variety of user agents

• ✅ Full keyboard navigation support
• ✅ Screen reader optimized with ARIA labels
• ✅ High contrast modes (Normal, High, Higher)
• ✅ Customizable font sizes (Small, Medium, Large)
• ✅ Reduced motion preferences
• ✅ Skip navigation links
• ✅ Live region announcements
• ✅ Focus management and indicators
• ✅ Color contrast ratios exceeding AAA standards
• ✅ Dyslexia-friendly font option

All keyboard shortcuts support both Mac (Cmd) and Windows/Linux (Ctrl) modifiers.

All interactive elements have clear, visible focus indicators:

• Default: 2px solid ring with offset
• High Contrast Mode: 3px solid ring, increased offset
• Color: Matches theme accent color for consistency

Modal dialogs and dropdowns implement focus trapping:

1. Focus moves to first focusable element when opened
2. Tab cycles through elements within the component
3. Escape closes and returns focus to trigger element
4. Focus is restored when component closes

Skip links allow keyboard users to bypass repetitive content:

• Skip to main content: Jumps to message area
• Skip to sidebar: Jumps to channel list
• Skip to message input: Jumps to message composer

These links are visually hidden but appear on focus.

<header role="banner">
  <!-- Main header -->
  <nav role="navigation">
    <!-- Channel sidebar -->
    <main role="main" id="main-content">
      <!-- Message area -->
      <aside role="complementary">
        <!-- Member list -->
        <footer role="contentinfo"><!-- Footer --></footer>
      </aside>
    </main>
  </nav>
</header>

Dynamic content updates are announced via ARIA live regions:

• New messages: aria-live="polite" - announces without interruption
• Errors/Alerts: aria-live="assertive" - immediate announcement
• Status updates: role="status" - polite announcements
• Logs: role="log" - sequential updates (chat messages)

All interactive elements have appropriate labels:

// Button with icon
<button aria-label="Send message">
  <SendIcon />
</button>

// Input with description
<input
  aria-label="Search channels"
  aria-describedby="search-hint"
/>
<span id="search-hint">Enter channel name or keyword</span>

// Error message
<input
  aria-invalid="true"
  aria-describedby="error-message"
/>
<span id="error-message" role="alert">
  Password must be at least 8 characters
</span>

Users can enable enhanced screen reader features:

1. Screen Reader Optimization: Enhanced ARIA labels and descriptions
2. Announce Messages: Automatic announcement of new messages
3. Prefer Captions: Show captions for all media content
4. Verbose Mode: More detailed descriptions of UI state

All text and interactive elements meet AAA contrast requirements:

Three font size presets are available:

Optional dyslexia-friendly font (OpenDyslexic) with features:

• Weighted bottoms to prevent letter rotation
• Unique character shapes to reduce confusion
• Increased letter spacing for clarity
• Available in all font sizes

Additional visual accessibility options:

• Reduce Transparency: Removes transparency effects
• Increase Spacing: Larger padding and margins
• Larger Touch Targets: 44px minimum (WCAG AAA)
• Bold Text: System-wide bold font weight
• Cursor Size: Customizable cursor/pointer size

Respects user's system preference for reduced motion:

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Three animation modes available:

1. Full Animations (Default)

   • Smooth transitions
   • Enter/exit animations
   • Hover effects
   • Loading spinners

2. Reduced Motion

   • Instant transitions
   • Fade-only animations
   • No sliding/scaling effects
   • Static loading indicators

3. No Animations

   • All animations disabled
   • Instant state changes
   • Static UI throughout

Features that can trigger motion sensitivity:

• ❌ Auto-scrolling to new messages (optional)
• ❌ Parallax effects (disabled by default)
• ❌ Animated backgrounds (disabled)
• ✅ Typing indicators (can be disabled)
• ✅ GIF autoplay (can be disabled)
• ✅ Video autoplay (disabled by default)

The Accessibility Menu provides one-click access to common settings:

Location: Top navigation bar (Universal Access icon)

Features:

• Theme toggle (Light/Dark)
• Font size adjustment
• High contrast mode
• Reduce motion toggle
• Screen reader mode
• Keyboard shortcuts reference

Path: Settings → Accessibility

• High Contrast Mode: Normal / High / Higher
• Dyslexia-Friendly Font: On/Off
• Reduce Transparency: On/Off
• Color Adjustments: Hue, saturation, brightness

• Font Size: Small / Medium / Large
• Line Height: 1.4x / 1.6x / 1.8x / 2.0x
• Letter Spacing: Normal / Wide / Extra Wide
• Word Spacing: Normal / Wide

• Reduce Motion: On/Off
• Disable Animations: On/Off
• Autoplay Media: Never / On WiFi / Always
• Typing Indicators: Show / Hide

• Always Show Focus: On/Off
• Larger Touch Targets: On/Off
• Keyboard Shortcuts: Enabled / Disabled
• Show Keyboard Hints: On/Off

• Screen Reader Optimization: On/Off
• Announce Messages: On/Off
• Prefer Captions: On/Off
• Verbose Descriptions: On/Off

We use multiple tools for automated accessibility testing:

1. axe DevTools: Component-level testing
2. Lighthouse: Overall accessibility score
3. Pa11y: CI/CD integration
4. Jest-axe: Unit test integration

• Lighthouse Score: 100/100
• axe Issues: 0 violations, 0 warnings
• WAVE Errors: 0 errors, 0 contrast errors
• Pa11y: All tests passing

• All images have descriptive alt text
• All buttons have accessible names
• Form inputs have associated labels
• Error messages are announced
• Loading states are announced
• Dynamic content updates are announced
• Focus order is logical
• Landmarks are properly labeled
• Headings are hierarchical
• Links are descriptive

• All functionality accessible via keyboard
• Focus indicators always visible
• No keyboard traps
• Tab order is logical
• Shortcuts work as documented
• Modal focus is managed correctly
• Dropdowns can be operated with keyboard
• Lists support arrow key navigation

• Contrast ratios meet AAA standards
• Text is readable at all sizes
• UI is usable at 200% zoom
• Color is not the only indicator
• Focus indicators are visible
• Touch targets are at least 44×44px
• Content reflows on small screens

import { Button } from '@/components/ui/button';

// Icon button with accessible name
<Button
  variant="ghost"
  size="icon"
  aria-label="Delete message"
  onClick={handleDelete}
>
  <TrashIcon />
</Button>

// Loading state with announcement
<Button
  disabled={isLoading}
  aria-busy={isLoading}
>
  {isLoading ? 'Sending...' : 'Send'}
</Button>

import { Input } from '@/components/ui/input'
import { Label } from '@/components/ui/label'
;<div>
  <Label htmlFor="email">Email Address</Label>
  <Input
    id="email"
    type="email"
    aria-describedby="email-hint"
    aria-invalid={!!error}
    error={error}
  />
  <span id="email-hint" className="text-sm text-muted-foreground">
    We'll never share your email
  </span>
  {error && (
    <span id="email-error" role="alert" className="text-sm text-destructive">
      {error}
    </span>
  )}
</div>

import { Dialog, DialogContent } from '@/components/ui/dialog'
import { useFocusManagement } from '@/hooks/use-focus-management'
;<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <DialogContent aria-labelledby="modal-title" aria-describedby="modal-description">
    <h2 id="modal-title">Confirm Delete</h2>
    <p id="modal-description">Are you sure you want to delete this message?</p>
    <div>
      <Button onClick={handleConfirm}>Delete</Button>
      <Button variant="ghost" onClick={handleCancel}>
        Cancel
      </Button>
    </div>
  </DialogContent>
</Dialog>

import { useRovingTabIndex } from '@/hooks/use-focus-management'

function ChannelList({ channels }) {
  const { containerRef } = useRovingTabIndex({
    orientation: 'vertical',
    loop: true,
  })

  return (
    <nav ref={containerRef} role="navigation" aria-label="Channels">
      <ul role="list">
        {channels.map((channel, index) => (
          <li key={channel.id}>
            <a
              href={`/channel/${channel.id}`}
              tabIndex={index === 0 ? 0 : -1}
              aria-current={currentChannelId === channel.id ? 'page' : undefined}
            >
              {channel.name}
            </a>
          </li>
        ))}
      </ul>
    </nav>
  )
}

import { useAnnouncer } from '@/components/accessibility/live-region'

function MessageSender() {
  const { announce } = useAnnouncer()

  const handleSend = async () => {
    try {
      await sendMessage(text)
      announce('Message sent successfully', 'polite')
    } catch (error) {
      announce('Failed to send message. Please try again.', 'assertive')
    }
  }

  return <Button onClick={handleSend}>Send</Button>
}

• WCAG 2.1 Guidelines
• WAI-ARIA Authoring Practices
• Section 508 Standards
• A11Y Project

• axe DevTools
• WAVE Browser Extension
• Lighthouse
• Color Contrast Analyzer

• NVDA (Free)
• JAWS
• VoiceOver (Built-in)

• Accessibility Insights
• axe DevTools
• WAVE
• Screen Reader Testing

For accessibility issues or questions:

• Email: [email protected]
• GitHub: Report an accessibility issue
• Documentation: Online Docs

• ✅ WCAG 2.1 AAA compliance achieved
• ✅ Full keyboard navigation support
• ✅ Screen reader optimization
• ✅ High contrast modes
• ✅ Reduced motion support
• ✅ Comprehensive documentation

• 🚧 Sign language interpretation support
• 🚧 Voice control integration
• 🚧 Customizable keyboard shortcuts
• 🚧 AI-powered alt text generation
• 🚧 Real-time caption customization

Last Updated: January 31, 2026 Maintained By: nself Accessibility Team License: MIT