Eve library

Accessibility Requirements

Guide

Revision 1

On this page

import { Meta } from 'storybook/blocks';

<Meta title="Style Guide/Accessibility" />

Our design system is built with accessibility as a core principle, ensuring all users can interact with our application effectively.

Accessibility Standards#

We follow WCAG 2.1 Level AA guidelines as our minimum standard, with many components meeting AAA requirements.

Core Principles (POUR)#

Principle Description
Perceivable Content must be presentable in ways all users can perceive
Operable UI components must be operable by all users
Understandable Information and UI operation must be understandable
Robust Content must work with current and future assistive technologies

Color & Contrast#

Contrast Requirements#

Content Type Minimum Ratio Level
Normal text (< 18px) 4.5:1 AA
Large text (≥ 18px bold or ≥ 24px) 3:1 AA
UI components & graphics 3:1 AA
Enhanced contrast 7:1 AAA

Tested Color Combinations#

All our semantic colors meet contrast requirements:

tsx
// These combinations are verified accessible
<p className="text-neutral-900 bg-white">          {/* 17.4:1 ✓ */}
<p className="text-neutral-100 bg-neutral-900">    {/* 15.4:1 ✓ */}
<p className="text-primary-700 bg-white">          {/* 6.5:1 ✓ */}
<p className="text-error-700 bg-white">            {/* 5.9:1 ✓ */}

Don't Rely on Color Alone#

Always provide additional indicators:

tsx
// ❌ Bad: Color only indicates error
<Input className={hasError ? 'border-error-500' : ''} />

// ✓ Good: Color + icon + text
<Input
  state={hasError ? 'error' : 'default'}
  error={hasError && 'This field is required'}
/>

Keyboard Navigation#

Focus Management#

All interactive elements are keyboard accessible:

tsx
// All components include focus styles
<Button className="focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary-500">
  Accessible Button
</Button>

Tab Order#

Ensure logical tab order:

tsx
// Natural document order
<form>
  <Input name="firstName" />  {/* Tab 1 */}
  <Input name="lastName" />   {/* Tab 2 */}
  <Input name="email" />      {/* Tab 3 */}
  <Button type="submit" />    {/* Tab 4 */}
</form>

Keyboard Shortcuts#

Component Key Action
Button Enter, Space Activate
Select Arrow Up/Down Navigate options
Select Enter, Space Select option
Select Escape Close dropdown
Modal Escape Close modal
Modal Tab Move focus within modal
Tabs Arrow Left/Right Switch tabs

Focus Trapping#

Modals trap focus to prevent navigation outside:

tsx
// Modal automatically traps focus
<Modal open={isOpen} onClose={handleClose}>
  <ModalBody>
    {/* Focus cycles through focusable elements */}
    <Input autoFocus />
    <Button>Cancel</Button>
    <Button>Confirm</Button>
  </ModalBody>
</Modal>

Screen Readers#

Semantic HTML#

Always use semantic elements:

tsx
// ✓ Good: Semantic structure
<nav aria-label="Main navigation">
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>

<main>
  <article>
    <h1>Page Title</h1>
    <section aria-labelledby="section-heading">
      <h2 id="section-heading">Section</h2>
    </section>
  </article>
</main>

// ❌ Bad: Div soup
<div class="nav">
  <div class="nav-item">Home</div>
</div>

ARIA Labels#

Provide context for screen readers:

tsx
// Button with icon only needs label
<Button aria-label="Close" size="icon">
  <CloseIcon />
</Button>

// Input with label association
<Input
  id="email"
  label="Email Address"  // Creates associated label
  aria-describedby="email-hint"
/>
<p id="email-hint">We'll send confirmation to this address</p>

Live Regions#

Announce dynamic content:

tsx
// Announce form errors
<div role="alert" aria-live="polite">
  {error && <p className="text-error-600">{error}</p>}
</div>

// Announce loading states
<div aria-live="polite" aria-busy={isLoading}>
  {isLoading ? 'Loading...' : 'Content loaded'}
</div>

ARIA Attributes Reference#

Attribute Usage
aria-label Provides accessible name when visible text isn't sufficient
aria-labelledby References visible element as label
aria-describedby References element providing description
aria-expanded Indicates if a collapsible element is open
aria-haspopup Indicates element opens a popup
aria-controls Identifies element being controlled
aria-current Indicates current item in a set
aria-selected Indicates selection state
aria-invalid Indicates validation state
aria-disabled Indicates disabled state

Form Accessibility#

Labels#

Every input needs an associated label:

tsx
// Built-in label support
<Input label="Username" id="username" />

// Renders as:
<label htmlFor="username">Username</label>
<input id="username" />

Error Messages#

Errors are programmatically associated:

tsx
<Input
  id="email"
  error="Please enter a valid email"
  aria-invalid={true}
  aria-describedby="email-error"
/>

// Component renders:
<input id="email" aria-invalid="true" aria-describedby="email-error" />
<p id="email-error" role="alert">Please enter a valid email</p>

Required Fields#

Indicate required fields clearly:

tsx
<Input
  label="Email"
  required
  aria-required="true"
/>
// Label shows asterisk: "Email *"

Fieldsets#

Group related fields:

tsx
<fieldset>
  <legend>Shipping Address</legend>
  <Input label="Street" />
  <Input label="City" />
  <Input label="Postal Code" />
</fieldset>

Component-Specific Guidelines#

Button#

tsx
// Accessible button
<Button
  aria-label="Submit form"        // If text isn't descriptive
  aria-disabled={isSubmitting}    // Prefer over disabled attribute
  aria-busy={isSubmitting}        // Indicates processing
>
  {isSubmitting ? <Spinner /> : 'Submit'}
</Button>

Select#

tsx
// Select with proper ARIA
<Select
  label="Country"
  aria-label="Select your country"  // Redundant if label exists
  aria-expanded={isOpen}
  aria-haspopup="listbox"
  aria-controls="country-listbox"
/>
tsx
// Accessible modal
<Modal
  open={isOpen}
  onClose={handleClose}
  aria-labelledby="modal-title"
  aria-describedby="modal-description"
>
  <ModalHeader>
    <ModalTitle id="modal-title">Confirm Delete</ModalTitle>
  </ModalHeader>
  <ModalBody>
    <p id="modal-description">
      This action cannot be undone.
    </p>
  </ModalBody>
</Modal>

Table#

tsx
// Accessible data table
<Table>
  <TableCaption>Monthly expenses</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead scope="col">Category</TableHead>
      <TableHead scope="col">Amount</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Food</TableCell>
      <TableCell>$500</TableCell>
    </TableRow>
  </TableBody>
</Table>

Tabs#

tsx
// Accessible tabs
<Tabs>
  <TabsList role="tablist" aria-label="Content sections">
    <TabsTrigger
      role="tab"
      aria-selected={isActive}
      aria-controls="panel-1"
      id="tab-1"
    >
      Tab 1
    </TabsTrigger>
  </TabsList>
  <TabsContent
    role="tabpanel"
    id="panel-1"
    aria-labelledby="tab-1"
  >
    Content
  </TabsContent>
</Tabs>

Touch Targets#

Minimum Size#

Touch targets must be at least 44x44 pixels:

tsx
// All buttons meet minimum touch target
<Button size="sm" className="min-h-[44px] min-w-[44px]">
  Small but tappable
</Button>

// Icon buttons are sized appropriately
<Button size="icon" className="h-11 w-11">  {/* 44px */}
  <SearchIcon />
</Button>

Spacing#

Adequate spacing between touch targets:

tsx
// Buttons have enough gap
<div className="flex gap-3">  {/* 12px gap */}
  <Button>Cancel</Button>
  <Button>Submit</Button>
</div>

Motion & Animation#

Reduced Motion#

Respect user preferences:

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

// Tailwind approach
<div className="motion-safe:animate-fade-in motion-reduce:animate-none">
  Content
</div>

Safe Animations#

Avoid problematic motion:

  • No flashing content (risk of seizures)
  • No parallax effects without opt-in
  • Subtle, purposeful transitions only

Testing Checklist#

Manual Testing#

  • Navigate entire page using only keyboard
  • Test with screen reader (VoiceOver, NVDA, JAWS)
  • Verify at 200% zoom level
  • Check with high contrast mode
  • Test with reduced motion preference

Automated Testing#

  • Run axe-core or similar tool
  • Verify color contrast ratios
  • Check for missing alt text
  • Validate HTML structure
  • Test focus order

Screen Reader Testing#

Task Expected
Read page heading H1 announced
Navigate form All fields labeled
Submit with error Error announced
Open modal Focus moves to modal
Close modal Focus returns to trigger

Resources#