path: root/docs/superpowers/specs/2026-04-16-week5-animations-a11y-design.md

# Week 5 Design Spec: Animations & Focused A11y Audit

**Date:** 2026-04-16  
**Project:** danix.xyz Hacker Theme (Hugo)  
**Status:** Ready for Implementation  
**Scope:** Week 5 of 6-week build (67% complete)

---

## 1. Animation Strategy

### 1.1 Scope & Philosophy

Week 5 enhances existing components with **subtle, professional entrance animations and micro-interactions**. We follow the Slackware philosophy: clean, essential, no bloat.

**What we animate:**
- Page load animations: Fade-in + subtle slide-up (200-300ms) for cards, lists, form elements
- Interactive animations: Hover/focus states on buttons, links, form inputs (smooth transitions)
- Modal/toast animations: Refine existing `modalSlideUp`, enhance toast entrance/exit
- Micro-interactions: Button presses, form field focus, checkbox/radio selection feedback

**What we don't animate:**
- Page-to-page transitions (use Hugo's standard page reloads, not JavaScript-driven SPA)
- Unnecessary motion (avoid animations that distract from content)
- Animations that conflict with prefers-reduced-motion preference

### 1.2 Animation Types & Timing

All animations use **GPU-accelerated properties** (`transform`, `opacity`) for smooth 60fps performance.

| Animation | Trigger | Duration | Easing | Motion-Safe |
|-----------|---------|----------|--------|-------------|
| Fade-in | Page load | 300ms | ease-out | Instant opacity to 1 |
| Slide-up | Page load | 300ms | ease-out | No transform |
| Modal enter | User interaction | 300ms | ease-out | Instant, no animation |
| Toast enter | Notification | 200ms | ease-out | Instant opacity |
| Toast exit | Auto-dismiss | 200ms | ease-in | Instant opacity |
| Button hover | Hover state | 150ms | ease-out | Instant color change |
| Focus indicator | Tab focus | 100ms | ease-out | Instant visibility |
| Spinner | Loading state | 600ms linear | linear | No animation, show static icon |

### 1.3 Motion Safety (prefers-reduced-motion)

All animations have motion-safe equivalents. When `prefers-reduced-motion: reduce`:

```css
@media (prefers-reduced-motion: reduce) {
  /* Remove all animations, use instant state changes */
  animation: none !important;
  transition: none !important;
}
```

Apply to: `*, *::before, *::after` or scoped to animation classes.

### 1.4 Implementation Approach

**CSS Keyframes** — Define all animations in `main.css`:
- `@keyframes fadeIn` — opacity 0 → 1
- `@keyframes slideUp` — translateY(20px) + opacity 0 → translateY(0) + opacity 1
- `@keyframes modalSlideUp` — refine existing (already partial)
- `@keyframes spin` — refine existing (already partial)

**CSS Classes** — Create utility classes for easy reuse:
- `.animate-fade-in` — apply fadeIn to any element
- `.animate-slide-up` — apply slideUp to any element
- `.animate-spin-loader` — apply spin (modal spinners)

**Inline Data Attributes** — Use Alpine.js for conditional animations:
```html
<div x-show="isVisible" x-transition="fadeIn 300ms" class="card">
```

**Hover/Focus States** — Use CSS `:hover` and `:focus-visible` for interactive elements.

---

## 2. Focused Accessibility Audit

### 2.1 Audit Scope

Three focused areas, aligned with WCAG 2.1 AA requirements:

1. **Focus Management** — Visible indicators, logical tab order, focus traps in modals
2. **Keyboard Navigation** — All interactive elements reachable via keyboard
3. **Screen Reader Basics** — ARIA labels, semantic HTML, modal announcements

We skip: advanced ARIA patterns, full screen reader testing on all components, skip-to-content links (lower priority for this phase).

### 2.2 Focus Management

**Requirement:** Every interactive element must have a visible, high-contrast focus indicator.

**Implementation:**
- Define a focus style globally:
  ```css
  :focus-visible {
    outline: 2px solid var(--accent-color);
    outline-offset: 2px;
  }
  ```
- Test on buttons, links, form inputs, modals, menu items
- Verify outline contrast meets WCAG AA (4.5:1 min)
- Ensure outline is visible in both light and dark modes

**Focus Order:**
- Verify tab order follows visual/logical flow (top-to-bottom, left-to-right)
- No hidden elements receiving focus
- No keyboard traps (users can Tab out of any element)

**Modal Focus Trap:**
- When modal opens, focus moves to first focusable element inside modal
- Tab wraps around modal elements (last element → first element)
- When modal closes (Escape or confirm button), focus returns to trigger element

### 2.3 Keyboard Navigation

**Requirement:** All interactive elements must be reachable and usable via keyboard alone.

**Elements to test:**
- Buttons — Tab to focus, Enter/Space to activate
- Links — Tab to focus, Enter to navigate
- Form inputs (text, email, password, number) — Tab to focus, type to enter data
- Textareas — Tab to focus, type, Enter works (not form submit)
- Select dropdowns — Tab to focus, Arrow keys to navigate options, Enter to select
- Checkboxes — Tab to focus, Space to toggle
- Radio buttons — Tab to group, Arrow keys to navigate options, Space to select
- Modals — Tab within modal, Escape to close, focus trap active
- Hamburger menu — Tab through menu items, Escape to close overlay
- Spinners — Not interactive (loading indicator), no keyboard requirement

**Key Bindings:**
- `Tab` — Move to next focusable element
- `Shift+Tab` — Move to previous focusable element
- `Enter` — Activate button, submit form, open dropdown
- `Escape` — Close modal, close overlay, close dropdown
- `Arrow Up/Down` — Navigate select options, radio buttons, menu items
- `Space` — Toggle checkbox, activate button (secondary), select radio option

### 2.4 Screen Reader Basics (Spot-Check)

**Requirement:** Components are announced correctly by screen readers (VoiceOver, NVDA).

**ARIA Labels:**
- Icon-only buttons must have `aria-label`:
  ```html
  <button aria-label="Toggle dark mode">🌙</button>
  ```
- Modals must have `role="dialog"` and `aria-labelledby`:
  ```html
  <div role="dialog" aria-labelledby="modal-title">
    <h2 id="modal-title">Confirm Action</h2>
  </div>
  ```
- Form labels must be associated with inputs via `<label for="">`:
  ```html
  <label for="email">Email:</label>
  <input id="email" type="email">
  ```

**Semantic HTML:**
- Use `<button>` for buttons (not `<div>` with click handlers)
- Use `<a>` for links (not `<button>` as link)
- Use `<form>` for forms, `<fieldset>` for grouped inputs
- Use proper heading hierarchy (`<h1>`, `<h2>`, etc.)

**Modal Announcements:**
- Modal should announce its purpose: "Confirm delete (modal)"
- Use `aria-modal="true"` to indicate modal state
- Use `aria-hidden="true"` for backdrop/overlay

---

## 3. Deliverables & Testing

### 3.1 Code Changes

**Main CSS file** (`themes/danix-xyz-hacker/assets/css/main.css`):
- Add `@keyframes fadeIn`, `slideUp`, refine `modalSlideUp`, `spin`
- Add `.animate-fade-in`, `.animate-slide-up`, `.animate-spin-loader` classes
- Add `:focus-visible` styles
- Add hover/focus transitions for buttons, links, form inputs
- Ensure all animations respect `prefers-reduced-motion`

**HTML Templates**:
- `form-components.html` — Add ARIA labels to icon buttons, enhance focus indicators
- `hamburger-menu.html` — Ensure focus trap, Escape closes, proper ARIA roles
- `header.html` — Add focus styles to logo and menu trigger
- Other partials — Add `aria-label` to icon-only buttons, ensure semantic HTML

**No new files** — Keep it simple, build on existing structure.

### 3.2 Documentation

**WEEK5-IMPLEMENTATION.md** (600+ lines):
- Animation implementation guide (keyframes, classes, usage)
- Focus management patterns (focus styles, trap implementation)
- Keyboard navigation checklist (all interactive elements)
- Screen reader integration (ARIA labels, semantic HTML)
- Code examples for each pattern
- Performance notes (GPU acceleration, animation timing)

**WEEK5-TESTING.md** (600+ lines):
- 60+ test cases covering:
  - Animation timing (200-300ms, prefers-reduced-motion)
  - Focus indicators (visible, high contrast, both themes)
  - Keyboard navigation (all interactive elements, tab order)
  - Screen reader spot-checks (buttons, modals, forms)
  - Responsive breakpoints (320px, 768px, 1060px+)
  - Dark/light mode verification
  - Browser compatibility (Chrome, Firefox, Safari)
  - Performance (60fps, no jank)
- Test methodology (manual keyboard testing, screen reader commands)

**A11Y-AUDIT-REPORT.md** (300+ lines):
- Summary of audit findings
- Components verified
- Any issues found and fixed
- Compliance statement (WCAG 2.1 AA)
- Recommendations for Week 6

### 3.3 Success Criteria

✓ All animations smooth (200-300ms), respect prefers-reduced-motion  
✓ All interactive elements have visible `:focus-visible` indicators  
✓ Tab order is logical across all pages  
✓ Modals have focus trap + Escape closes  
✓ No keyboard traps (hamburger menu, dropdowns, modals, etc.)  
✓ Icon-only buttons have `aria-label`  
✓ Modal has `role="dialog"` and proper ARIA labels  
✓ Form inputs have associated `<label>` elements  
✓ Semantic HTML used throughout (no `<div>` as buttons)  
✓ 60+ tests passing (animations, keyboard nav, focus, screen reader basics)  
✓ No regressions from Weeks 1-4  
✓ CSS build time under 250ms  
✓ 60fps animations verified (no stuttering)  

---

## 4. Timeline & Effort

**Estimated Duration:** 6-8 hours

| Task | Hours | Notes |
|------|-------|-------|
| Animation implementation | 2-3 | Keyframes, classes, testing |
| Focus management | 1-2 | Focus styles, tab order, traps |
| Keyboard navigation | 1-2 | Testing all interactive elements |
| Screen reader integration | 1 | ARIA labels, semantic HTML |
| Testing & optimization | 1-2 | Full test suite, performance tuning |
| Documentation | 1-2 | Implementation guide, test report |

**Branch:** `week-5-animations`  
**Master Integration:** End of week (after all tests pass)

---

## 5. Key Files

| File | Purpose | Change |
|------|---------|--------|
| `themes/danix-xyz-hacker/assets/css/main.css` | Core styles | +200-300 lines (animations, focus) |
| `themes/danix-xyz-hacker/layouts/partials/form-components.html` | Form UI | +ARIA labels, focus styles |
| `themes/danix-xyz-hacker/layouts/partials/hamburger-menu.html` | Navigation | Focus trap, ARIA roles |
| `WEEK5-IMPLEMENTATION.md` | Guide | NEW (600+ lines) |
| `WEEK5-TESTING.md` | Test suite | NEW (600+ lines) |
| `A11Y-AUDIT-REPORT.md` | Audit summary | NEW (300+ lines) |

---

## 6. Assumptions & Constraints

- **No SPA transitions** — Hugo standard page reloads, animations apply to content on the page
- **Subtle animations only** — 200-300ms, fade-in + slide-up, no complex choreography
- **WCAG 2.1 AA target** — Not AAA (larger font sizes, extra color contrast), focused audit scope
- **Keyboard-first testing** — Manual testing, not automated tools
- **No new dependencies** — Alpine.js + vanilla CSS/JS only
- **Existing components preserved** — Enhance, don't refactor Week 1-4 work

---

## 7. References

- CLAUDE.md — Project instructions & Slackware philosophy
- WEEK4-IMPLEMENTATION.md — Component baseline
- WEEK4-TESTING.md — Testing patterns
- WCAG 2.1 AA Guidelines — https://www.w3.org/WAI/WCAG21/quickref/
- MDN: prefers-reduced-motion — https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion
- MDN: :focus-visible — https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible

---

**Status:** ✅ Design approved, ready for implementation planning