Accessibility (WCAG 2.2 AA)

Core Principles

• Semantic HTML elements and ARIA landmarks
• Keyboard-first navigation with visible focus states
• Skip links for main content in layouts
• Inclusive, people-first language

Semantic HTML

<!-- Use semantic elements -->
<header>
    <nav aria-label="Main navigation">
        <a href="/dashboard">Dashboard</a>
        <a href="/projects">Projects</a>
    </nav>
</header>

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

<footer>...</footer>

Skip Links

<!-- At top of layout -->
<a href="#main-content" class="sr-only focus:not-sr-only focus:absolute ...">
    Skip to main content
</a>

Form Accessibility

Label Every Control

<!-- Visible label -->
<label for="email">Email address</label>
<input id="email" type="email" />

<!-- Or using aria-label for icon-only inputs -->
<input type="search" aria-label="Search events" />

Required Fields

<label for="name">Name <span aria-hidden="true">*</span></label>
<input id="name" required aria-required="true" />

Error Messages

<input
    id="email"
    aria-invalid={hasError}
    aria-describedby={hasError ? 'email-error' : undefined}
/>
{#if hasError}
    <p id="email-error" class="text-destructive">
        Please enter a valid email address
    </p>
{/if}

Validation Behavior

• On validation failure: focus first invalid input
• Never disable submit just to block validation
• Show inline errors linked via aria-describedby

Keyboard Navigation

Focus Order

<!-- Natural tab order follows DOM order -->
<button>First</button>
<button>Second</button>
<button>Third</button>

<!-- Remove from tab order when hidden -->
<div hidden>
    <button tabindex="-1">Hidden button</button>
</div>

Focus Management in Dialogs

// When dialog opens, focus first interactive element
$effect(() => {
    if (open) {
        dialogRef?.querySelector('input, button')?.focus();
    }
});

// When dialog closes, return focus to trigger
const triggerRef = document.activeElement;
// ... on close
triggerRef?.focus();

Keyboard Shortcuts

<button
    onkeydown={(e) => {
        if (e.key === 'Enter' || e.key === ' ') {
            e.preventDefault();
            handleClick();
        }
    }}
>
    Action
</button>

Images and Icons

Informative Images

<img src={user.avatar} alt={`Profile photo of ${user.name}`} />

Decorative Images

<img src="/decorative-pattern.svg" alt="" aria-hidden="true" />

Icon Buttons

<button aria-label="Delete event">
    <TrashIcon aria-hidden="true" />
</button>

Icons with Text

<button>
    <PlusIcon aria-hidden="true" />
    Add Event
</button>

ARIA Patterns

Live Regions

<!-- For dynamic updates (notifications, loading states) -->
<div aria-live="polite" aria-atomic="true">
    {#if loading}
        Loading events...
    {/if}
</div>

<!-- For urgent messages -->
<div role="alert">
    Error: Failed to save changes
</div>

Expandable Content

<button
    aria-expanded={isExpanded}
    aria-controls="panel-content"
>
    {isExpanded ? 'Collapse' : 'Expand'}
</button>
<div id="panel-content" hidden={!isExpanded}>
    Panel content
</div>

Tabs

<div role="tablist" aria-label="Event tabs">
    <button role="tab" aria-selected={activeTab === 'details'}>
        Details
    </button>
    <button role="tab" aria-selected={activeTab === 'stack'}>
        Stack Trace
    </button>
</div>
<div role="tabpanel" aria-labelledby="details-tab">
    Tab content
</div>

Color and Contrast

• Minimum contrast ratio: 4.5:1 for normal text
• 3:1 for large text and UI components
• Don't rely on color alone to convey information

<!-- ✅ Good: Icon + color + text -->
<span class="text-destructive">
    <AlertIcon aria-hidden="true" />
    Error: Invalid input
</span>

<!-- ❌ Bad: Color only -->
<span class="text-destructive">Invalid input</span>

Testing Accessibility

# Run axe-playwright audits in E2E tests
npm run test:e2e

// In Playwright tests
import AxeBuilder from '@axe-core/playwright';

test('page is accessible', async ({ page }) => {
    await page.goto('/dashboard');
    const results = await new AxeBuilder({ page }).analyze();
    expect(results.violations).toEqual([]);
});