--- /dev/null
+# 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
