# Research Summary: Workout UX Improvements

**Project:** Gravl — PPL Workout Tracker
**Synthesized:** 2026-02-15

## Key Findings

### Stack
- Keep existing React 18 + Vite + Express + PostgreSQL stack
- Add only: `react-hook-form` + `zod` + `@hookform/resolvers` (~38KB gzipped)
- Build custom stepper input component (no library needed)
- Do NOT add: UI frameworks, Redux, TanStack Query, Framer Motion
- CSS-only fix for touch targets: min 44px height, 16px font-size prevents iOS zoom

### Table Stakes (Must Ship)
- Input validation: no negative reps/weights, proper number constraints
- Weight unit display (kg suffix visible in input)
- Mobile-optimized input layout (larger touch targets)
- Add/remove sets per exercise
- Pre-fill last workout's values for reference

### Differentiators (Should Ship)
- Custom workout builder (pick exercises, save as template)
- Modify program workouts (fork to custom)
- Stepper inputs for rapid logging (+/- buttons)

### Watch Out For
1. **Don't break existing flow** — program workout logging must stay identical
2. **Don't modify shared program data** — fork to custom_workout for per-user changes
3. **Don't let scope creep** — "add set" ≠ "full program builder"
4. **Don't break mobile layout** — all new controls must fit 600px width
5. **Backward compat** — existing workout_logs must keep working with new schema

## Architecture Decision

**Dual data path:**
- Program workouts (existing, read-only) — unchanged
- Custom workouts (new) — user-created, flexible sets, stored in new tables

**New tables:** `custom_workouts`, `custom_workout_exercises`
**Enhanced:** `workout_logs` gets `source_type` column (default 'program')

## Suggested Build Order

1. Input UX fixes (validation, units, stepper, layout) — no backend changes
2. Flexible sets (local state + backend accepts variable set count)
3. Exercise list endpoint (GET /api/exercises for search)
4. Custom workout CRUD (new tables + endpoints)
5. Custom workout builder UI (frontend page)
6. Modify program workout (fork program → custom)

Each phase is independently shippable. Phase 1 delivers immediate UX value with zero risk.

## Research Files

- `STACK.md` — Technology recommendations and what to avoid
- `FEATURES.md` — Feature categorization (table stakes vs differentiators)
- `ARCHITECTURE.md` — Schema design, component structure, data flow
- `PITFALLS.md` — 7 critical pitfalls with prevention strategies