From: Danilo M. Date: Thu, 16 Apr 2026 15:06:02 +0000 (+0200) Subject: docs: add Week 5 design spec (animations & a11y audit) X-Git-Tag: release_22042026-1342~179 X-Git-Url: https://git.danix.xyz/?a=commitdiff_plain;h=c57467f992d9d220406aabd887d848ce3bc43fbf;p=danix.xyz-2.git docs: add Week 5 design spec (animations & a11y audit) Design covers: - Subtle, professional entrance animations (fade-in, slide-up, 200-300ms) - Motion-safe alternatives (prefers-reduced-motion support) - Focused accessibility audit (focus management, keyboard nav, ARIA basics) - 60+ test cases covering animations, keyboard navigation, focus indicators - Success criteria: WCAG 2.1 AA compliance, 60fps performance - Deliverables: WEEK5-IMPLEMENTATION.md, WEEK5-TESTING.md, A11Y-AUDIT-REPORT.md Scope: No page transition animations (KISS), no advanced ARIA patterns, focused audit areas only. Co-Authored-By: Claude Haiku 4.5 --- 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 +
+``` + +**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 + + ``` +- Modals must have `role="dialog"` and `aria-labelledby`: + ```html +
+ +
+ ``` +- Form labels must be associated with inputs via `