cv-site/doc/21-ACCESSIBILITY.md

# Accessibility Guide

> **WCAG 2.1 AA Compliance Documentation**
> Last Updated: December 2025

## Overview

This document describes the accessibility features implemented in the CV website to ensure WCAG 2.1 AA compliance and provide an inclusive user experience.

## Table of Contents

1. [Implemented Features](#implemented-features)
2. [Button Accessibility](#button-accessibility)
3. [Form Elements](#form-elements)
4. [Keyboard Navigation](#keyboard-navigation)
5. [Screen Reader Support](#screen-reader-support)
6. [CSS Compatibility](#css-compatibility)
7. [HTTP Headers](#http-headers)
8. [Testing](#testing)
9. [Checklist](#accessibility-checklist)

---

## Implemented Features

### Quick Summary

| Feature | Status | Notes |
|---------|--------|-------|
| Button aria-labels | ✅ Complete | All buttons have discernible text |
| Form labels | ✅ Complete | All inputs have aria-labelledby |
| Keyboard navigation | ✅ Complete | Tab, Enter, Escape support |
| Modal accessibility | ✅ Complete | Native `<dialog>` with close buttons |
| Color themes | ✅ Complete | Light/Dark/Auto modes |
| Screen reader | ✅ Complete | Live regions for announcements |
| CSS prefixes | ✅ Complete | Safari/WebKit compatibility |
| Security headers | ✅ Complete | X-Content-Type-Options, CSP |
| Cache headers | ✅ Complete | Static and dynamic routes |

---

## Button Accessibility

All interactive buttons include proper accessibility attributes:

### Fixed Action Buttons

Located in `templates/partials/widgets/`:

```html
<!-- Download PDF Button -->
<button id="download-button"
        aria-label="{{.UI.Widgets.Download.AriaLabel}}"
        data-tooltip="{{.UI.Widgets.Download.Tooltip}}">
    <iconify-icon icon="catppuccin:pdf"></iconify-icon>
</button>

<!-- Print-Friendly Button -->
<button id="print-friendly-button"
        aria-label="{{.UI.Widgets.Print.AriaLabel}}"
        data-tooltip="{{.UI.Widgets.Print.Tooltip}}">
    <iconify-icon icon="mdi:leaf"></iconify-icon>
</button>

<!-- Shortcuts Button -->
<button id="shortcuts-button"
        aria-label="{{.UI.Widgets.Shortcuts.AriaLabel}}"
        data-tooltip="{{.UI.Widgets.Shortcuts.Tooltip}}">
    <iconify-icon icon="mdi:keyboard-outline"></iconify-icon>
</button>
```

### Mobile Menu Buttons

Located in `templates/partials/navigation/hamburger-menu.html`:

```html
<!-- All menu action buttons have aria-labels -->
<button class="menu-action-btn menu-pdf-btn"
        aria-label="{{.UI.Widgets.ActionButtons.DownloadPdf}}">
    <iconify-icon icon="catppuccin:pdf"></iconify-icon>
    <span>{{.UI.Widgets.ActionButtons.DownloadPdf}}</span>
</button>
```

### Best Practices

1. **Icon-only buttons**: Always include `aria-label`
2. **Buttons with text**: Visible text serves as the accessible name
3. **Tooltips**: Use `data-tooltip` for visual hint, `aria-label` for screen readers

---

## Form Elements

All form inputs have proper label associations:

### Toggle Checkboxes

Desktop toggles in `templates/partials/navigation/view-controls.html`:

```html
<div class="selector-group" id="desktop-length-toggle">
    <label class="selector-label" id="length-toggle-label">
        {{.UI.ViewControls.Length}}:
    </label>
    <label class="icon-toggle">
        <input type="checkbox"
               id="lengthToggle"
               aria-labelledby="length-toggle-label"
               aria-describedby="length-toggle-desc">
        <span class="icon-toggle-slider">...</span>
        <span id="length-toggle-desc" class="sr-only">
            {{.UI.ViewControls.LengthDescription}}
        </span>
    </label>
</div>
```

Mobile toggles in `templates/partials/navigation/hamburger-menu.html`:

```html
<div class="menu-control-item" id="mobile-length-toggle">
    <label class="menu-control-label" id="menu-length-toggle-label">
        <iconify-icon icon="mdi:file-document-outline"></iconify-icon>
        <span>{{.UI.ViewControls.Length}}</span>
    </label>
    <label class="icon-toggle">
        <input type="checkbox"
               id="lengthToggleMenu"
               aria-labelledby="menu-length-toggle-label">
        <span class="icon-toggle-slider">...</span>
    </label>
</div>
```

### Contact Form

Located in `templates/partials/modals/contact-modal.html`:

```html
<div class="form-group">
    <label for="contact-email" class="form-label">
        {{.UI.ContactModal.Form.Email}}
        <span class="required-indicator">*</span>
    </label>
    <input type="email"
           id="contact-email"
           name="email"
           required
           aria-required="true"
           placeholder="{{.UI.ContactModal.Form.EmailPlaceholder}}">
</div>
```

### Labeling Strategies

| Strategy | When to Use |
|----------|-------------|
| `<label for="id">` | Standard form inputs |
| `aria-labelledby` | Complex widgets, toggles |
| `aria-describedby` | Additional context/descriptions |
| `aria-label` | When no visible label exists |

---

## Keyboard Navigation

### Supported Shortcuts

| Key | Action |
|-----|--------|
| `Tab` | Move focus to next element |
| `Shift+Tab` | Move focus to previous element |
| `Enter` / `Space` | Activate focused button/link |
| `Escape` | Close modals |
| `?` | Open shortcuts modal |
| `Ctrl/Cmd + K` | Open command palette |
| `Ctrl/Cmd + P` | Print friendly version |
| `Ctrl/Cmd + +/-/0` | Zoom controls |

### Focus Management

- All interactive elements are focusable
- Focus is trapped inside open modals
- Focus returns to trigger element when modal closes
- Skip links available for screen reader users

### Implementation

```html
<!-- Modal with keyboard support -->
<dialog id="shortcuts-modal" class="info-modal"
        _="on click call closeOnBackdrop(me, event)">
    <!-- Press Escape to close (native dialog behavior) -->
    <button class="info-modal-close"
            commandfor="shortcuts-modal"
            command="close"
            aria-label="{{.UI.ShortcutsModal.Close}}">
        <iconify-icon icon="mdi:close"></iconify-icon>
    </button>
</dialog>
```

---

## Screen Reader Support

### Live Regions

Announcements for dynamic content changes:

```html
<!-- Loading indicator -->
<span id="loading"
      role="status"
      aria-live="polite"
      aria-label="Loading">
    <span class="loader"></span>
</span>

<!-- PDF selection announcement -->
<div id="pdf-selection-announcement"
     class="sr-only"
     aria-live="polite"
     aria-atomic="true"></div>

<!-- Contact form response -->
<div id="contact-response"
     class="contact-response"
     role="status"
     aria-live="polite"></div>
```

### Screen Reader Only Text

```css
.sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
}
```

### ARIA Landmarks

```html
<!-- Navigation -->
<nav role="navigation" aria-label="CV sections">...</nav>
<div class="action-bar" role="navigation" aria-label="Language and export controls">...</div>

<!-- Zoom control -->
<div id="zoom-control" role="group" aria-label="{{.UI.Widgets.ZoomControl.GroupLabel}}">
    <input type="range"
           aria-label="{{.UI.Widgets.ZoomControl.SliderLabel}}"
           aria-valuemin="25"
           aria-valuemax="300"
           aria-valuenow="100"
           aria-valuetext="100%">
</div>
```

---

## CSS Compatibility

### Browser Prefixes

All CSS properties with limited browser support include vendor prefixes:

```css
/* User selection prevention */
.toggle-switch {
    -webkit-user-select: none; /* Safari */
    user-select: none;
}

/* Backdrop blur effect */
.zoom-control {
    backdrop-filter: blur(10px);
    -webkit-backdrop-filter: blur(10px); /* Safari */
}
```

### Files Updated

| File | Property Fixed |
|------|---------------|
| `_toggles.css` | `-webkit-user-select` |
| `_zoom-control.css` | `-webkit-user-select` |
| `_sidebar.css` | `-webkit-user-select` |
| `_cv-section.css` | `-webkit-user-select` |
| `_breakpoints.css` | `-webkit-user-select` |
| `_toasts.css` | `-webkit-backdrop-filter` (already present) |
| `_modals.css` | `-webkit-backdrop-filter` (already present) |

### Feature Detection

For backdrop-filter, use `@supports`:

```css
@supports (backdrop-filter: blur(20px)) or (-webkit-backdrop-filter: blur(20px)) {
    .blur-bar {
        backdrop-filter: blur(20px) saturate(180%);
        -webkit-backdrop-filter: blur(20px) saturate(180%);
    }
}
```

---

## HTTP Headers

### Security Headers

Implemented in `internal/middleware/security.go`:

```go
func SecurityHeaders(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Prevent MIME type sniffing
        w.Header().Set("X-Content-Type-Options", "nosniff")

        // Prevent clickjacking
        w.Header().Set("X-Frame-Options", "SAMEORIGIN")

        // XSS Protection
        w.Header().Set("X-XSS-Protection", "1; mode=block")

        // Referrer policy
        w.Header().Set("Referrer-Policy", "strict-origin-when-cross-origin")

        // Content Security Policy
        w.Header().Set("Content-Security-Policy", "...")

        // HSTS (production only)
        if os.Getenv("GO_ENV") == "production" {
            w.Header().Set("Strict-Transport-Security",
                "max-age=31536000; includeSubDomains; preload")
        }

        next.ServeHTTP(w, r)
    })
}
```

### Cache Control

**Static Files** (CSS, JS, images):
```go
// 1 hour dev, 1 day production
w.Header().Set("Cache-Control", "public, max-age=86400")
```

**Dynamic Routes** (HTML pages):
```go
// Production: 5 minutes with must-revalidate
w.Header().Set("Cache-Control", "public, max-age=300, must-revalidate")

// Development: no cache
w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")
```

---

## Testing

### Running Accessibility Tests

```bash
# Run accessibility test suite
bun run tests/mjs/60-accessibility.test.mjs

# Or with the test runner
cd tests && bun run run-all.mjs
```

### Test Coverage

The `60-accessibility.test.mjs` file tests:

1. **HTTP Security Headers** - X-Content-Type-Options, X-Frame-Options, CSP
2. **Cache-Control Headers** - Presence and correct values
3. **Buttons with Discernible Text** - All buttons have aria-label or visible text
4. **Form Elements with Labels** - All inputs have associated labels
5. **Toggle Checkboxes** - aria-labelledby with valid linked elements
6. **ARIA Landmarks** - Navigation, main, dialog elements
7. **Keyboard Navigation** - Focusable interactive elements
8. **Modal Accessibility** - Close buttons, aria attributes
9. **Color Theme Support** - Theme switcher availability
10. **Screen Reader Announcements** - Live regions for dynamic content

### Manual Testing

1. **Keyboard-only navigation**: Tab through all interactive elements
2. **Screen reader testing**: Use VoiceOver (macOS) or NVDA (Windows)
3. **High contrast mode**: Test visibility in Windows High Contrast
4. **Zoom testing**: Test at 200% browser zoom

---

## Accessibility Checklist

### Before Each Release

- [ ] Run `60-accessibility.test.mjs` - all tests pass
- [ ] Test keyboard navigation (Tab, Enter, Escape)
- [ ] Verify all buttons have aria-labels
- [ ] Check form inputs have labels
- [ ] Test with screen reader
- [ ] Verify modals trap focus
- [ ] Check color contrast ratios
- [ ] Test at 200% zoom

### WCAG 2.1 AA Requirements

| Criterion | Status | Implementation |
|-----------|--------|----------------|
| 1.1.1 Non-text Content | ✅ | Alt text, aria-labels |
| 1.3.1 Info and Relationships | ✅ | Semantic HTML, ARIA |
| 1.4.3 Contrast (Minimum) | ✅ | Theme system |
| 2.1.1 Keyboard | ✅ | Full keyboard support |
| 2.1.2 No Keyboard Trap | ✅ | Modal focus management |
| 2.4.1 Bypass Blocks | ✅ | Skip links, landmarks |
| 2.4.4 Link Purpose | ✅ | Descriptive link text |
| 2.4.6 Headings and Labels | ✅ | Semantic structure |
| 3.2.1 On Focus | ✅ | No unexpected changes |
| 4.1.2 Name, Role, Value | ✅ | ARIA attributes |

---

## Resources

- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
- [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
- [MDN Accessibility Guide](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
- [Can I Use - CSS Browser Support](https://caniuse.com/)

---

## Changelog

### December 2025

- Added aria-labels to menu action buttons (PDF, Print, Contact)
- Added aria-labelledby to all toggle checkboxes (desktop and mobile)
- Added -webkit-user-select prefix for Safari compatibility
- Added DynamicCacheControl middleware for HTML pages
- Created comprehensive accessibility test suite
- Created this documentation