Accessibility Guide

Why Accessibility Matters

• Inclusivity: Making our applications usable by people with disabilities
• Legal Compliance: Meeting accessibility standards and regulations
• Better UX for Everyone: Accessibility improvements benefit all users
• SEO Benefits: Many accessibility practices improve search engine visibility

Design System Accessibility Features

The LOKE Design System includes several built‑in accessibility features:

Keyboard Navigation

• All interactive components are keyboard accessible
• Focus states are clearly visible
• Logical tabbing order is maintained
• Keyboard shortcuts are consistent

Screen Reader Support

• Semantic HTML is used throughout components
• ARIA attributes are correctly implemented
• Form elements have proper labels and descriptions
• Dialogs announce their presence appropriately

Color and Contrast

• Color schemes meet WCAG 2.1 AA standards
• Text has sufficient contrast against backgrounds
• Information is not conveyed by color alone
• Focus states have adequate visibility

Responsive Design

• Content resizes appropriately for different zoom levels
• Layouts adapt to different screen sizes
• Touch targets are appropriately sized for mobile

Using Components Accessibly

Buttons and Links

// Good: Button with clear purpose
<Button>Save Changes</Button>

// Good: Icon button with accessible label
<Button variant="ghost" size="icon" aria-label="Settings">
  <Settings className="h-5 w-5" />
</Button>

// Good: Alternative approach with VisuallyHidden
<Button variant="ghost" size="icon">
  <VisuallyHidden>Settings</VisuallyHidden>
  <Settings className="h-5 w-5" />
</Button>

// Avoid: Icon-only button without accessible name
<Button variant="ghost" size="icon">
  <Settings className="h-5 w-5" />
</Button>

Forms

// Good: Properly labeled form controls
<FormField
  control={form.control}
  name="email"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input placeholder="email@example.com" {...field} />
      </FormControl>
      <FormDescription>
        We'll never share your email with anyone else.
      </FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>

// Avoid: Inputs without labels
<Input placeholder="Enter email" />

Images and Icons

// Good: Image with alt text
<img src="/image.jpg" alt="Description of the image" />

// Good: Decorative image marked as such
<img src="/decorative-pattern.jpg" alt="" aria-hidden="true" />

// Good: SVG icon with title for assistive tech
<svg aria-hidden="true" focusable="false">
  <title>Settings</title>
  <path d="..." />
</svg>

// Avoid: Image without alt text
<img src="/image.jpg" />

Dialog and Modals

// Good: Dialog with proper ARIA attributes
<Dialog>
  <DialogTrigger asChild>
    <Button>Open Settings</Button>
  </DialogTrigger>
  <DialogContent aria-describedby="dialog-description">
    <DialogHeader>
      <DialogTitle>Application Settings</DialogTitle>
      <DialogDescription id="dialog-description">
        Adjust your application preferences.
      </DialogDescription>
    </DialogHeader>
    {/* Dialog content */}
    <DialogFooter>
      <Button>Save Changes</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

Content Structure

// Good: Proper heading hierarchy
<Heading as="h1">Page Title</Heading>
<section>
  <Heading as="h2">Section Title</Heading>
  <p>Section content...</p>
  <Heading as="h3">Subsection Title</Heading>
  <p>Subsection content...</p>
</section>

// Avoid: Skipping heading levels
<h1>Page Title</h1>
<h3>Section Title</h3>

Accessibility Checklist

Use this checklist when implementing interfaces with the LOKE Design System:

Keyboard Navigation

• All interactive elements can be accessed using the Tab key
• Focus order is logical and follows content flow
• Focus is visible at all times with good contrast
• No keyboard traps exist (except in modals with proper handling)
• Custom widgets provide keyboard interaction (arrow keys, escape, etc.)

Screen Readers

• Proper heading structure is used (h1, h2, etc.)
• Images have appropriate alt text
• Form controls have associated labels
• ARIA landmarks are used appropriately
• Dynamic content changes are announced
• Status messages are conveyed to screen readers

Visual Design

• Text color has sufficient contrast against backgrounds
• Information is not conveyed by color alone
• UI is usable at 200% zoom
• Text can be resized without loss of functionality
• Content is readable in both light and dark modes

Content and Interactions

• Error messages are clear and suggest solutions
• Sufficient time is given for reading and interaction
• Motion and animations can be paused/reduced
• Instructions are clear and do not rely on sensory characteristics
• Link text is descriptive (no “click here” or “read more”)

Testing Accessibility

Automated Testing

Use automated tools as a first check:

• Lighthouse (in Chrome DevTools)
• axe DevTools (Chrome extension)

Manual Testing

Always supplement automated tests with manual testing:

1. Keyboard navigation: Navigate using only the keyboard
2. Screen reader testing: Test with VoiceOver (macOS), NVDA (Windows), or other screen readers
3. Zoom testing: Test at 200% zoom
4. Contrast checking: Verify text contrast meets WCAG AA standards
5. Reduced motion: Test with reduced motion settings enabled

Common Accessibility Issues

1) Missing Alternative Text

// Issue
<img src="/chart.png" />
// Fix
<img src="/chart.png" alt="Q3 Revenue Chart: 25% increase over previous quarter" />

2) Poor Color Contrast

// Issue
<Text className="text-gray-400">Low-contrast text</Text>
// Fix
<Text className="text-gray-600">Improved contrast text</Text>

3) Missing Form Labels

// Issue
<Input placeholder="Enter email" />
// Fix
<div>
  <Label htmlFor="email">Email</Label>
  <Input id="email" placeholder="Enter email" />
</div>

4) Non-descriptive Links

// Issue
<Link href="/privacy">Click here</Link>
// Fix
<Link href="/privacy">View Privacy Policy</Link>

5) Missing Focus Styles

/* Issue */
*:focus { outline: none; }
/* Fix - The design system provides appropriate focus styles by default
   Do not remove these styles */

Resources

• W3C Web Content Accessibility Guidelines (WCAG): https://www.w3.org/WAI/standards-guidelines/wcag/
• WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
• A11y Project Checklist: https://www.a11yproject.com/checklist/
• MDN Accessibility Documentation: https://developer.mozilla.org/en-US/docs/Web/Accessibility

Conclusion

Accessibility is everyone’s responsibility. By using the LOKE Design System components as intended and following the guidelines in this document, you’ll create interfaces that are accessible to all users. When in doubt, test with real assistive technologies and seek feedback from users with diverse abilities.