diff options
Diffstat (limited to 'docs/superpowers/specs')
| -rw-r--r-- | docs/superpowers/specs/2026-04-16-week5-animations-a11y-design.md | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-04-16-week5-animations-a11y-design.md b/docs/superpowers/specs/2026-04-16-week5-animations-a11y-design.md new file mode 100644 index 0000000..2e91d86 --- /dev/null +++ b/docs/superpowers/specs/2026-04-16-week5-animations-a11y-design.md @@ -0,0 +1,293 @@ +# 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 |