# Amevia Accessibility Guidelines

## Commitment

Amevia is designed to be usable by everyone. Accessibility is a brand requirement, not an afterthought. All interfaces, marketing materials, and the chat widget must meet WCAG 2.1 Level AA as a minimum target.

## Color contrast

### Requirements

- **Normal text:** minimum 4.5:1 contrast ratio against background
- **Large text** (18px+ regular or 14px+ bold): minimum 3:1
- **UI components and graphics:** minimum 3:1 against adjacent colors
- **Focus indicators:** clearly visible against all backgrounds

### Verified pairs (light mode)

| Foreground | Background | Ratio | Pass |
|------------|-----------|-------|------|
| `#0F172A` (text-primary) | `#FFFFFF` | 16.1:1 | AA, AAA |
| `#0F172A` (text-primary) | `#F6F8FC` (page) | 15.2:1 | AA, AAA |
| `#64748B` (text-secondary) | `#FFFFFF` | 4.6:1 | AA |
| `#2563EB` (link) | `#FFFFFF` | 4.6:1 | AA |
| `#FFFFFF` | `#071126` (navy) | 16.8:1 | AA, AAA |
| `#059669` (success) | `#FFFFFF` | 4.5:1 | AA |
| `#DC2626` (error) | `#FFFFFF` | 4.6:1 | AA |

### Dark mode

- Primary text `#F1F5F9` on `#071126`: 14.5:1
- Secondary text `#94A3B8` on `#0A1430`: 5.8:1
- Links `#60A5FA` on `#0A1430`: 5.2:1

### Rules

- Never rely on color alone to convey meaning — pair with icons, text, or patterns
- Brand gradient colors are decorative; do not use gradient mid-tones for body text
- Test new color combinations before adding to the palette

## Focus states

- All interactive elements must have a visible `:focus-visible` indicator
- Focus ring: 2px solid `var(--border-focus)` with 2px offset
- Focus ring token: `--focus-ring`
- Never remove focus outlines without providing an equivalent visible indicator
- Tab order must follow logical reading order

## Keyboard navigation

- All interactive elements reachable via Tab
- Modals trap focus while open and return focus on close
- Escape closes modals, dropdowns, and the chat widget
- Skip link provided at page top: "Skip to content"
- Chat widget launcher and input field are keyboard accessible
- Dropdown menus support arrow key navigation

## Reduced motion

```css
@media (prefers-reduced-motion: reduce) {
  /* Disable animations and transitions */
}
```

- Motion tokens set to 0ms when reduced motion is preferred
- Scroll behavior falls back to instant
- Typing indicators show static dots instead of animation
- Page transitions are disabled

## Touch targets

- Minimum touch target size: **44 × 44 px**
- Token: `--touch-target: 2.75rem`
- Apply to buttons, links, toggles, chat launcher, and navigation items
- Adequate spacing between adjacent targets (minimum 8px)

## Readable type sizes

- Body text minimum: **16px (1rem)**
- Small text minimum: **12px (0.75rem)** — use sparingly, never for critical content
- Line height minimum: 1.4 for body text
- Line length: 65–75 characters maximum for paragraphs

## Accessible error messages

- Errors must be specific and actionable
- Associate error messages with form fields via `aria-describedby`
- Use `aria-invalid="true"` on fields with errors
- Do not rely on red color alone — include text and icon

**Good:** "Enter a valid email address."  
**Bad:** "Invalid input."

## Meaningful button labels

- Buttons describe the action: "Save changes", "Connect website", "Send message"
- Avoid generic labels: "Click here", "Submit", "OK"
- Icon-only buttons require `aria-label`
- Loading buttons: `aria-busy="true"` with status text for screen readers

## Chat widget accessibility

- Launcher button: `aria-label="Open Amevia chat"`
- Chat panel: `role="dialog"` with `aria-label="Amevia chat"`
- Messages: `role="log"` with `aria-live="polite"` for new messages
- Typing indicator: `aria-label="Amevia is typing"`
- Close button: `aria-label="Close chat"`
- Suggested questions: standard button elements, not divs
- Product cards: semantic links or buttons with descriptive labels

## Images and media

- All meaningful images have descriptive `alt` text
- Decorative images: `alt=""` or `aria-hidden="true"`
- Logo SVGs include `<title>` elements
- Icons paired with visible text when possible; otherwise `aria-label`

## Forms

- Every input has a visible `<label>` or `aria-label`
- Required fields marked with text, not color alone
- Placeholder text is supplementary, not a replacement for labels
- Autocomplete attributes used where appropriate

## Semantic HTML

- Use proper heading hierarchy (h1 → h2 → h3, no skipping)
- Use `<nav>`, `<main>`, `<section>`, `<article>`, `<footer>` landmarks
- Tables use `<thead>`, `<tbody>`, `<th scope="">` for data tables
- Lists use `<ul>`/`<ol>`, not styled divs

## Testing checklist

- [ ] Keyboard-only navigation through all interactive elements
- [ ] Screen reader test (VoiceOver or NVDA) on key flows
- [ ] Color contrast verification for all text/background pairs
- [ ] 200% zoom — content remains readable and functional
- [ ] Reduced motion preference respected
- [ ] Focus indicators visible on all interactive elements
- [ ] Error states announced to screen readers
- [ ] Chat widget fully keyboard and screen reader accessible

---

*Amevia is a product by Dioartis.*