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:
// 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:
// ❌ 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:
// 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:
// 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:
// 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:
// ✓ 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:
// 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:
// 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:
// 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:
<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:
<Input
label="Email"
required
aria-required="true"
/>
// Label shows asterisk: "Email *"
Fieldsets#
Group related fields:
<fieldset>
<legend>Shipping Address</legend>
<Input label="Street" />
<Input label="City" />
<Input label="Postal Code" />
</fieldset>
Component-Specific Guidelines#
Button#
// 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#
// 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"
/>
Modal#
// 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#
// 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#
// 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:
// 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:
// 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:
// 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 |