# M011: Interaction Polish, Navigation & Accessibility

**Gathered:** 2026-03-31
**Status:** Ready for planning

## Project Description

Chrysopedia is a music production knowledge base with a React/TypeScript frontend, FastAPI backend, and Docker Compose deployment on ub01. The UI/UX assessment (March 31, 2026) identified 16 findings — 12 were approved for implementation, 4 denied. This milestone addresses the approved findings.

## Why This Milestone

The assessment found the site "functionally competent but emotionally flat" — adequate for expert users who know what they want, but lacking the interaction polish, discovery mechanisms, and accessibility compliance that would make it engaging and professional. The approved scope targets three themes: visual delight (hover animations, staggered entrances, featured technique redesign, random discovery), usability (topics collapse, global search, mobile hamburger, creator stats, tag overflow, empty subtopics), and accessibility (heading hierarchy, skip link, contrast, page titles).

## User-Visible Outcome

### When this milestone is complete, the user can:

- See cards animate on hover and stagger in on page load across all listing pages
- Click "Random Technique" to discover a random technique page
- Browse Topics page with collapsed categories that expand smoothly on click
- Search from any page via a compact nav search bar or Cmd+K shortcut
- Navigate on mobile via a hamburger menu with proper touch targets
- See creator topic distribution as colored pills instead of run-on text
- See clean cards with max 4 tags and "+N more" overflow
- Navigate with proper heading hierarchy, skip link, and WCAG AA contrast

### Entry point / environment

- Entry point: http://ub01:8096 (or http://chrysopedia.com)
- Environment: Docker Compose on ub01
- Live dependencies involved: PostgreSQL (random technique endpoint), existing API

## Completion Class

- Contract complete means: frontend builds with 0 errors, all visual changes render correctly
- Integration complete means: random technique endpoint returns valid data, global search navigates correctly
- Operational complete means: deployed to ub01 and verified in browser

## Final Integrated Acceptance

To call this milestone complete, we must prove:

- Cards animate on hover and stagger entrance on all listing pages
- Random technique button navigates to a real technique page
- Topics page loads collapsed and expands with animation
- Global search works from non-home pages with Cmd+K shortcut
- Mobile hamburger menu works at narrow viewports
- Lighthouse accessibility score improved (heading hierarchy, contrast, skip link, titles)

## Risks and Unknowns

- CSS animation performance on lower-end devices — keep transforms GPU-composited (transform, opacity only)
- Global search in nav may conflict with existing SearchAutocomplete component sizing — need compact variant
- Mobile hamburger state management — need to close on navigation and outside click

## Existing Codebase / Prior Art

- `frontend/src/App.css` — 3800+ lines, all styles including existing `pageEnter` animation, CSS custom properties for colors
- `frontend/src/App.tsx` — App shell with header nav, routes. Nav H1 on line 20 needs semantic fix
- `frontend/src/components/SearchAutocomplete.tsx` — Existing component with `heroSize` prop, has inline and hero modes
- `frontend/src/pages/TopicsBrowse.tsx` — Already has expand/collapse state via `useState<Set>`, defaults to all-expanded
- `frontend/src/pages/CreatorDetail.tsx` — Stats rendered as text string, needs pill component
- `frontend/src/pages/Home.tsx` — Featured technique section, random technique button target
- `frontend/src/utils/catSlug.ts` — Shared category slug utility for color mapping
- `backend/routers/techniques.py` — Already has `ORDER BY func.random()` for technique listing

> See `.gsd/DECISIONS.md` for all architectural and pattern decisions.

## Relevant Requirements

- R016–R028 — All new requirements for this milestone (see REQUIREMENTS.md)
- R015 — Global search in nav supports 30-second retrieval target

## Scope

### In Scope

- Card hover animations (scale + shadow + transition) on all card types
- Staggered entrance animations on card grids
- Featured technique visual redesign (glow/gradient border)
- Random technique button + backend endpoint
- Topics page default-collapsed with expand/collapse animation
- Creator stats as topic-colored pills
- Tag overflow limit (4 + "+N more")
- Empty subtopic handling ("Coming soon" or hide)
- Compact search bar in nav (all non-home pages)
- Cmd+K keyboard shortcut for search focus
- Mobile hamburger menu (<768px)
- Heading hierarchy fix (single H1 per page)
- Skip-to-content link
- Text contrast increase to WCAG AA
- Page-specific document titles per route

### Out of Scope / Non-Goals

- Beginner learning paths (F01 — denied)
- YouTube deep links on key moments (F02 — denied)
- Hide admin dropdown (F03 — denied)
- CTA label changes (F15 — denied)
- Audio/sound design elements
- Embedded video players
- User accounts or personalization

## Technical Constraints

- CSS animations must use GPU-composited properties (transform, opacity) for performance
- SearchAutocomplete component must support a new compact/nav mode without breaking existing hero/inline modes
- Mobile hamburger must close on route change (React Router navigation)
- All changes must build cleanly with TypeScript strict mode

## Integration Points

- Backend API — new `GET /api/v1/techniques/random` endpoint for random technique discovery
- Existing CSS custom property system — `--color-badge-cat-*` properties for topic colors on creator stats

## Open Questions

- None — scope is well-defined from assessment triage
