Accessibility

Fabrk targets WCAG 2.2 Level AA compliance. All components are built with accessibility as a core requirement, not an afterthought.

• Text alternatives for non-text content
• Captions and alternatives for multimedia
• Content adaptable without losing meaning
• Distinguishable foreground from background

• All functionality via keyboard
• Enough time to read and use content
• No content that causes seizures
• Navigable structure and wayfinding

• Readable and predictable text
• Predictable UI behavior
• Input assistance for errors

• Compatible with assistive technologies
• Valid semantic HTML
• Proper ARIA usage where needed

Fabrk uses OKLCH color format for perceptually uniform contrast. All theme tokens are pre-validated for WCAG 2.2 compliance.

/* WCAG 2.2 AA Requirements */
Text (normal):     4.5:1 minimum
Text (large):      3:1 minimum
UI Components:     3:1 minimum (borders, icons, controls)
Focus indicators:  3:1 minimum against adjacent colors

/* Example OKLCH token with sufficient contrast */
--foreground: oklch(98% 0.01 145);  /* Light text */
--background: oklch(15% 0.02 145);  /* Dark bg, ~12:1 ratio */

Test your customizations with these tools:

• OKLCH.com - Convert and check OKLCH values
• WebAIM Contrast Checker - WCAG ratio calculator
• axe DevTools - Browser extension for automated testing
• WAVE - Web accessibility evaluation tool

All Fabrk components support full keyboard navigation. Focus rings are always visible for keyboard users.

/* Focus ring styles (applied globally) */
:focus-visible {
  outline: 2px solid var(--ring);
  outline-offset: 2px;
}

/* Never hide focus for keyboard users */
.focus-visible:focus-visible {
  outline: 2px solid var(--ring);
}

Fabrk components use semantic HTML first, ARIA attributes only when necessary.

/* Icon-only button - REQUIRES aria-label */
<Button aria-label="Close dialog" size="icon">
  <X className="h-4 w-4" />
</Button>

/* Decorative icons - hide from screen readers */
<Icon aria-hidden="true" />

/* Live regions for dynamic updates */
<div role="status" aria-live="polite">
  {statusMessage}
</div>

/* Dialog with proper labeling */
<Dialog>
  <DialogContent aria-labelledby="dialog-title" aria-describedby="dialog-desc">
    <DialogTitle id="dialog-title">Confirm Action</DialogTitle>
    <DialogDescription id="dialog-desc">Are you sure?</DialogDescription>
  </DialogContent>
</Dialog>

Fabrk respects the prefers-reduced-motion media query. Users who prefer reduced motion see minimal or no animations.

/* CSS approach */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* Framer Motion approach (built-in) */
<motion.div
  initial={{ opacity: 0 }}
  animate={{ opacity: 1 }}
  /* Framer Motion automatically respects reduced motion */
/>

• Keep animations under 400ms for optimal perception
• Avoid flashing content (no more than 3 flashes per second)
• Use subtle movements (8-16px translation max)
• Provide pause/stop controls for auto-playing content
• Never use animation to convey critical information alone

/* Every input needs an associated label */
<div className="space-y-2">
  <Label htmlFor="email">Email address</Label>
  <Input id="email" type="email" aria-describedby="email-error" />
  {error && (
    <p id="email-error" role="alert" className="text-destructive text-xs">
      [ERROR]: {error}
    </p>
  )}
</div>

/* Required fields */
<Label htmlFor="name">
  Name <span aria-hidden="true">*</span>
  <span className="sr-only">(required)</span>
</Label>
<Input id="name" required aria-required="true" />

/* Group related inputs */
<fieldset>
  <legend className="text-sm font-medium">Notification Preferences</legend>
  <RadioGroup name="notifications" aria-label="Notification preferences">
    <RadioGroupItem value="email" id="notify-email" />
    <Label htmlFor="notify-email">Email</Label>
    ...
  </RadioGroup>
</fieldset>

• Use role="alert" for error messages to announce immediately
• Associate errors with inputs via aria-describedby
• Don't rely on color alone to indicate errors
• Provide clear, actionable error messages
• Focus first invalid field on form submission

• [ ] Navigate entire page with Tab key only
• [ ] Activate all buttons/links with Enter and Space
• [ ] Navigate menus and tabs with Arrow keys
• [ ] Close dialogs with Escape key
• [ ] Test with screen reader (VoiceOver, NVDA, or JAWS)
• [ ] View page at 200% zoom without horizontal scroll
• [ ] Verify focus rings visible on all interactive elements
• [ ] Check form error messages are announced

# Run accessibility audit with axe-core
npx playwright test --project=a11y

# Or use Lighthouse in Chrome DevTools
# Run accessibility audit category

# ESLint jsx-a11y rules (built into Fabrk)
npm run lint

# axe-core programmatic testing
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('page has no accessibility violations', async () => {
  const { container } = render(<Page />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

/* ALWAYS add aria-label to icon-only buttons */

// CORRECT
<Button aria-label="Delete item" variant="ghost" size="icon">
  <Trash className="h-4 w-4" />
</Button>

// WRONG - screen reader announces nothing useful
<Button variant="ghost" size="icon">
  <Trash className="h-4 w-4" />
</Button>

/* Announce loading state to screen readers */

<Button disabled={isLoading} aria-busy={isLoading}>
  {isLoading ? (
    <>
      <TerminalSpinner size="sm" aria-hidden="true" />
      <span className="sr-only">Loading...</span>
    </>
  ) : (
    '> SUBMIT'
  )}
</Button>

/* For page-level loading */
<div role="status" aria-live="polite" aria-busy={isLoading}>
  {isLoading ? 'Loading content...' : children}
</div>

/* Provide skip link for keyboard users */

<a
  href="#main-content"
  className="sr-only focus:not-sr-only focus:absolute focus:z-50
             focus:bg-background focus:p-4 focus:text-foreground"
>
  Skip to main content
</a>

<main id="main-content" tabIndex={-1}>
  {/* Page content */}
</main>

1. 1. Press Cmd + F5 to enable VoiceOver
2. 2. Use VO + Arrow keys to navigate (VO = Ctrl + Option)
3. 3. Press VO + Space to activate buttons/links
4. 4. Use VO + U to open rotor (headings, links, landmarks)
5. 5. Press Cmd + F5 again to disable

What to check: All interactive elements announce their purpose, form labels are read, error messages announce, loading states communicate.

1. 1. Download NVDA from nvaccess.org (free)
2. 2. Press Insert + Down Arrow to read continuously
3. 3. Use Tab to navigate form controls
4. 4. Press H to jump between headings
5. 5. Press Insert + Q to quit NVDA

• Missing labels: Inputs without associated labels announce as "edit text"
• Icon buttons: Without aria-label, announced as "button" only
• Dynamic content: Updates not announced without aria-live regions
• Focus trapping: Modal content should trap focus until dismissed
• Reading order: Visual order should match DOM order

/* Polite - waits for user to finish current task */
<div aria-live="polite" aria-atomic="true">
  {notificationCount} new notifications
</div>

/* Assertive - interrupts immediately (use sparingly) */
<div role="alert" aria-live="assertive">
  [ERROR]: Session expired. Please log in again.
</div>

/* Status - implicit polite, for status messages */
<div role="status">
  Saving changes...
</div>

/* Log - for chat/feed updates */
<div role="log" aria-live="polite">
  {messages.map(m => <p key={m.id}>{m.text}</p>)}
</div>

/* Timer - countdown or elapsed time */
<div role="timer" aria-live="off" aria-atomic="true">
  {formatTime(remainingSeconds)}
</div>

/* PREFER: Native HTML elements (built-in accessibility) */
<button onClick={handleClick}>Click me</button>
<a href="/page">Link text</a>
<input type="checkbox" />
<select><option>Choice</option></select>

/* AVOID: Div with ARIA (requires more work) */
<div role="button" tabIndex={0} onClick={handleClick}
     onKeyDown={handleKeyDown}>Click me</div>

/* Native elements provide FREE: */
// - Keyboard activation (Enter/Space)
// - Focus management
// - Screen reader announcements
// - Form submission behavior
// - Proper semantics

Use ARIA only when native HTML can't provide the needed semantics:

• Tabs: No native tab element, use role="tablist"
• Combobox: Custom autocomplete, use role="combobox"
• Tree: Hierarchical lists, use role="tree"
• Slider: Custom sliders may need role="slider"

Rule of thumb: If a native HTML element exists, use it. ARIA can override but never add behavior - you must implement keyboard handling yourself.