refactor: code quality cleanup — remove any types, add logger, rename Kine to Tabata

- Phase 0: Rename all Kine references to Tabata (types, files, imports, i18n, analytics events) - Phase 1: Add test coverage for tabataProgramStore, workoutProgramStore, and color utils (47 tests) - Phase 2: Remove all `any` types from production code with proper typed replacements - Phase 3: Replace ~60 raw console.* calls with __DEV__-gated logger utility - Phase 4: Verify .DS_Store housekeeping (already clean) 0 TypeScript errors, 583/583 tests passing.
2026-04-17 18:56:24 +02:00
parent e0e02c4550
commit 791f432334
176 changed files with 16508 additions and 2305 deletions
--- a/docs/ui-feature-brief.md
+++ b/docs/ui-feature-brief.md
@@ -0,0 +1,486 @@
+# TabataFit — UI Feature Brief
+
+> Generated for Google Stitch design handoff.
+> Covers all end-user screens, interactions, states, and navigation flows.
+
+---
+
+## App Overview
+
+**TabataFit** is a mobile fitness app ("Apple Fitness+ for Tabata") built with React Native / Expo. It delivers guided Tabata HIIT workouts with video, voice coaching, music, and Apple Watch heart-rate sync.
+
+### Design System
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| Background | `#000000` | Pure black base |
+| Surface | `#1C1C1E` | Cards, sheets |
+| Brand | `#FF6B35` | Flame orange — primary accent |
+| Rest | `#5AC8FA` | Ice blue — rest phases |
+| Success | `#30D158` | Energy green — completion |
+| Prep phase | `#FF9500` | Orange-yellow |
+| Work phase | `#FF6B35` | Flame orange |
+| Rest phase | `#5AC8FA` | Ice blue |
+| Complete phase | `#30D158` | Green |
+
+- Supports **dark and light mode**
+- Multi-language (i18n)
+- Haptic feedback throughout
+
+---
+
+## Navigation Structure
+
+```
+Root Stack
+├── Onboarding (6-step flow)
+├── (tabs)
+│   ├── Home          — index
+│   ├── Explore       — browse workouts
+│   ├── Activity      — stats & history
+│   └── Profile       — settings & account
+├── workout/[id]      — Workout detail (push)
+├── program/[id]      — Program detail (push)
+├── collection/[id]   — Collection detail (push)
+├── player/[id]       — Workout player (push, full-screen)
+├── complete/[id]     — Post-workout celebration (push)
+├── paywall           — Premium upsell (modal)
+├── explore-filters   — Filter sheet (form sheet modal)
+└── privacy           — Privacy policy (push)
+```
+
+**Tab bar**: 4 tabs — Home, Explore, Activity, Profile. SF Symbol icons. Badge support.
+
+---
+
+## 1. Onboarding Flow
+
+A 6-screen linear funnel shown on first launch. Progress dots at top. Skip available on some steps.
+
+### 1.1 Problem Screen
+- **Purpose**: Motivational hook about time constraints
+- **Elements**: Headline text, subtitle, illustration
+- **CTA**: Continue
+
+### 1.2 Empathy Screen
+- **Purpose**: User selects fitness barriers to build rapport
+- **Elements**: Grid of 4 selectable cards — "No time", "Low motivation", "No knowledge", "No gym"
+- **Interaction**: Tap to select, max 2 selections, visual highlight on selected
+- **CTA**: Continue (enabled after 1+ selection)
+
+### 1.3 Solution Screen
+- **Purpose**: Show Tabata's effectiveness
+- **Elements**: Animated comparison bar chart (Tabata vs traditional cardio calorie burn)
+- **CTA**: Continue
+
+### 1.4 Wow Screen
+- **Purpose**: Reveal key app features
+- **Elements**: 4 feature cards with staggered entrance animations — Timer, Exercises, Voice Coaching, Progress Tracking
+- **CTA**: Continue
+
+### 1.5 Personalization Screen
+- **Purpose**: Collect user preferences to personalize experience
+- **Inputs**:
+  - Name (text input)
+  - Fitness level: Beginner / Intermediate / Advanced (single select chips)
+  - Goal: Weight Loss / Cardio / Strength / Wellness (single select chips)
+  - Weekly frequency: 2x / 3x / 5x per week (single select chips)
+- **CTA**: Continue (enabled when all fields filled)
+
+### 1.6 Paywall Screen (Onboarding variant)
+- **Purpose**: Premium conversion at end of onboarding
+- **Elements**: Premium features list, yearly/monthly plan toggle with real prices from RevenueCat
+- **CTAs**: Subscribe, Restore Purchases, Skip (close button)
+- **States**: Loading prices, purchase in progress, error
+
+---
+
+## 2. Home Tab
+
+Personalized dashboard and primary entry point.
+
+### Elements
+- **Greeting header**: Time-based ("Good morning/afternoon/evening") + user's name + animated mascot
+- **Streak badge**: Current streak count with flame icon
+- **Quick stats row**: 3 stat pills — Current streak, This week (workouts), Total minutes
+- **Assessment card**: Feature-flagged (currently OFF) — fitness assessment prompt
+- **Program cards**: 3 horizontal cards (Upper Body, Lower Body, Full Body)
+  - Each shows: icon, title, progress bar (% complete), status badge (Not Started / In Progress / Completed)
+  - CTA per card: Start / Continue / Restart (depends on state)
+- **Switch program button**: Opens program selection
+
+### Navigation
+- Tap program card → `program/[id]`
+- Tap "Start" on program → `player/[id]` (first workout)
+- Tap "Continue" → `player/[id]` (next incomplete workout)
+
+### States
+- **New user**: 0 stats, no streak, programs at 0%
+- **Returning user**: Populated stats, active streak, program progress
+
+---
+
+## 3. Explore Tab
+
+Browse, search, and filter the full workout catalog.
+
+### Elements
+- **Search bar**: Search by workout title, trainer name, exercise name, category. Real-time filtering.
+- **Featured collection**: Hero card at top with image, title, workout count. Tap → `collection/[id]`
+- **Trainer avatars**: Horizontal scroll of circular trainer photos. Tap to filter workouts by trainer.
+- **Collections carousel**: Horizontal scroll of collection cards. Tap → `collection/[id]`
+- **Recommended For You**: Horizontal workout card list, personalized based on workout history
+- **Featured workouts**: Grid of highlighted workouts
+- **All Workouts section**:
+  - Category filter pills: All, Full Body, Upper Body, Lower Body, Core, Cardio
+  - Filter button → opens `explore-filters` sheet
+  - Active filter indicator + clear filters button
+  - 2-column workout card grid
+
+### Workout Card
+- Thumbnail image
+- Duration badge overlay
+- Title, trainer name, level indicator
+- Lock icon if premium-only and user is free tier
+
+### Navigation
+- Tap workout card → `workout/[id]`
+- Tap collection → `collection/[id]`
+- Tap trainer avatar → filters workout list by that trainer
+- Tap filter button → `explore-filters` (form sheet modal)
+
+### States
+- **Loading**: Skeleton placeholders for cards
+- **Error**: Error message with Retry button
+- **Empty search**: "No workouts found" message
+- **Filtered**: Active filter chips shown, clear all button
+
+---
+
+## 4. Activity Tab
+
+Workout history, statistics, and achievements.
+
+### Elements
+- **Streak banner**: Current streak + longest streak (flame icons)
+- **Stats grid** (2x2): Each stat in a card with circular progress ring
+  - Total workouts (ring fills toward goal)
+  - Total minutes
+  - Total calories
+  - Best streak
+- **Weekly bar chart**: Sun–Sat, each bar filled if a workout was completed that day, current day highlighted
+- **Recent workouts list**: Last 5 workouts
+  - Each row: workout title, relative time ("2h ago"), duration, calories
+  - Tap → `workout/[id]`
+- **Achievements grid**: 4 achievement badges displayed
+  - Types: workouts milestone, streak milestone, minutes milestone, calories milestone
+  - States: locked (greyed out) / unlocked (colored with checkmark)
+
+### States
+- **Empty**: No workouts yet — motivational message + "Start Your First Workout" CTA → `explore`
+- **Populated**: All sections visible with data
+
+---
+
+## 5. Profile Tab
+
+User settings, account management, and app info.
+
+### Elements
+- **User header**: Avatar circle with initial, display name, plan label ("Free" or "TabataFit+")
+- **Stats row**: 3 inline stats — workouts count, streak, calories
+- **Upgrade CTA** (free users only): Gradient button → `paywall`
+
+#### Workout Settings Section
+- Haptic feedback toggle
+- Sound effects toggle
+- Voice coaching toggle
+
+#### Notifications Section
+- Daily reminders toggle
+- Reminder time display (when enabled)
+
+#### Personalization Section (premium only)
+- Sync status indicator
+
+#### About Section
+- Version number
+- Rate App → opens App Store rating prompt
+- Contact Us → opens email compose
+- FAQ → opens external web link
+- Privacy Policy → `privacy` screen
+
+#### Account Section (premium only)
+- Restore Purchases → triggers RevenueCat restore
+
+#### Danger Zone
+- Sign Out button
+- Data deletion: triggers confirmation modal
+
+### Data Deletion Modal
+- Warning text explaining data loss
+- Cancel / Delete buttons
+- Delete is destructive (red)
+
+---
+
+## 6. Workout Detail Screen
+
+Pre-workout information screen. Reached by tapping any workout card.
+
+**Route**: `workout/[id]`
+
+### Elements
+- **Header**: Thumbnail or video preview, back button, heart/save button (toggle)
+- **Title**: Workout name
+- **Trainer**: Trainer name (colored text)
+- **Metadata row**: Duration (minutes), Calories estimate, Level badge (Beginner/Intermediate/Advanced)
+- **Equipment list**: Icons + labels for required equipment (or "No equipment")
+- **Timing card**: Prep time, Work time, Rest time, Rounds — displayed in a structured card
+- **Exercise list**: Ordered list of exercises with individual durations
+- **Repeat rounds indicator**: Shows if rounds repeat the exercise sequence
+- **Music vibe label**: Genre/mood of the workout soundtrack
+
+### CTAs
+- **Start Workout** → `player/[id]` (if unlocked or user is premium)
+- **Unlock with TabataFit+** → `paywall` (if locked and user is free tier)
+
+### Header Actions
+- **Back**: Navigate back
+- **Save/Unsave**: Heart icon toggle — saves workout to favorites
+
+### States
+- **Loading**: Skeleton layout
+- **Unlocked**: Full detail visible, "Start Workout" CTA
+- **Locked**: Full detail visible but "Unlock with TabataFit+" CTA replaces start button
+
+---
+
+## 7. Program Detail Screen
+
+Multi-week training program overview with per-week workout breakdown.
+
+**Route**: `program/[id]`
+
+### Elements
+- **Header**: Program icon, title, subtitle (e.g., "4 weeks · 12 workouts")
+- **Description**: Program summary text
+- **Stats card**: 3 stats — Weeks, Workouts, Total Minutes
+- **Tags**: Equipment required (e.g., Dumbbells, Mat) + Equipment optional + Focus areas (e.g., Arms, Core)
+- **Progress bar** (if started): Percentage complete with label
+- **Training plan**: Expandable week sections
+  - Each week shows its workouts in order
+  - Workout rows show: title, duration, completion checkmark (if done)
+  - Current week has a "Current" badge
+  - Future weeks may show lock icons (progressive unlock)
+
+### CTAs
+- **Start Program** (not started) → `player/[id]` (first workout)
+- **Continue Training** (in progress) → `player/[id]` (next incomplete workout)
+- **Restart** (completed) → resets progress, starts from week 1
+
+### States
+- **Not Started**: 0% progress, all weeks shown, "Start Program" CTA
+- **In Progress**: Progress bar filled, completed workouts checked, "Continue Training" CTA
+- **Completed**: 100% progress, all checked, "Restart" CTA
+
+---
+
+## 8. Collection Detail Screen
+
+A curated group of workouts.
+
+**Route**: `collection/[id]`
+
+### Elements
+- **Header**: Collection title, description, workout count
+- **Workout list**: Vertical list of workout cards in the collection
+  - Each card: thumbnail, title, trainer, duration, level
+  - Lock icon for premium-gated workouts
+
+### Navigation
+- Tap workout → `workout/[id]`
+- Back button → previous screen
+
+---
+
+## 9. Player Screen
+
+Full-screen workout execution with timer, video, audio, and Watch sync.
+
+**Route**: `player/[id]`
+
+### Layout
+- **Full-screen dark mode** — no tab bar, no status bar chrome
+- **Background**: Workout video (HLS streaming) or gradient fallback
+- **Phase-colored tint**: Background overlay changes color per phase (prep=orange, work=flame, rest=blue, complete=green)
+
+### Timer Section
+- **Timer ring**: Large circular progress indicator, fills as phase progresses
+- **Phase label**: PREP / WORK / REST / COMPLETE (color-coded)
+- **Countdown**: Large MM:SS timer (uses tabular-nums for alignment)
+- **Round indicator**: "Round 3 of 8" text
+
+### Exercise Info
+- **Current exercise name**: Large text
+- **Next exercise preview**: Smaller text ("Up next: Burpees")
+- **Coach encouragement**: Motivational text overlays (e.g., "Keep going!", "Almost there!")
+
+### Controls
+- **Start**: Begins the workout (shown before first start)
+- **Pause / Resume**: Toggle button during workout
+- **Stop**: Ends workout early (confirmation prompt)
+- **Skip**: Skip to next phase
+
+### Stats Overlay
+- **Calories**: Running calorie count
+- **Heart rate**: BPM from Apple Watch (if connected)
+- **Rounds**: Current / total
+
+### Burn Bar
+- Horizontal bar comparing user's current calorie burn vs. average for this workout
+- Updates in real-time
+
+### Now Playing Pill
+- Shows current music track name
+- Skip track button
+
+### Audio & Haptics
+- **Sound effects**: Phase start chime, 3-2-1 countdown beeps, workout complete fanfare
+- **Haptic feedback**: Phase transitions, countdown ticks, button presses
+- **Voice coaching**: Audio cues for exercises and encouragement
+- **Screen stays awake** (useKeepAwake)
+
+### Apple Watch Integration
+- Sends: workout state (phase, timer, exercise)
+- Receives: play/pause, skip, stop commands, heart rate data
+
+### Completion State
+- Timer ring shows 100%
+- Phase label: COMPLETE
+- Summary: Rounds completed, calories burned, total minutes
+- **Done** CTA → `complete/[id]`
+
+### States
+- **Ready**: Before starting — shows workout info, Start CTA
+- **Active**: Timer running, video playing, stats updating
+- **Paused**: Timer frozen, controls show Resume
+- **Complete**: Summary shown, Done CTA
+
+---
+
+## 10. Workout Complete Screen
+
+Post-workout celebration and next steps.
+
+**Route**: `complete/[id]`
+
+### Elements
+- **Celebration animation**: Concentric emoji rings spinning (fire, muscle, lightning emojis)
+- **Stats grid**: 3 stats — Calories, Minutes, 100% completion
+- **Burn bar result**: Percentile comparison ("You burned more than 73% of users")
+- **Streak display**: Current streak count + subtitle ("Keep it going!")
+- **Share button**: Opens native share sheet with workout summary
+- **Recommended next workouts**: 3 horizontal workout cards
+  - Tap → `workout/[id]`
+- **Back to Home** CTA → navigates to Home tab
+
+### Sync Consent Modal
+- Appears after first workout for premium users
+- Prompts to enable cross-device data sync
+- Accept / Decline buttons
+
+---
+
+## 11. Paywall Screen
+
+Premium subscription purchase flow.
+
+**Route**: `paywall` (presented as modal)
+
+### Elements
+- **Header**: "TabataFit+" branding
+- **Features grid**: 6 premium feature cards with icons
+  - Music during workouts
+  - Unlimited workouts
+  - Detailed stats
+  - Calorie tracking
+  - Smart reminders
+  - No ads
+- **Plan selection**: Two radio-style options
+  - Yearly: Price/year + "Save 50%" badge (highlighted as best value)
+  - Monthly: Price/month
+  - Prices fetched live from RevenueCat
+- **Subscribe CTA**: Gradient button, shows selected plan price
+- **Restore purchases**: Text link below CTA
+- **Terms**: Privacy policy + terms of service links
+- **Close button**: X in top corner to dismiss
+
+### States
+- **Loading**: Skeleton while fetching prices from RevenueCat
+- **Ready**: Plans displayed with real prices
+- **Purchasing**: Loading spinner on CTA, inputs disabled
+- **Error**: Error message with retry
+- **Success**: Dismisses modal, unlocks premium features
+
+---
+
+## 12. Explore Filters Sheet
+
+Filter modal for the Explore tab workout grid.
+
+**Route**: `explore-filters` (form sheet modal with grabber)
+
+### Elements
+- **Level filter chips**: All / Beginner / Intermediate / Advanced (single select)
+- **Equipment filter chips**: All / None / Dumbbells / Band / Mat (dynamic from data, single select)
+- **Apply**: Dismiss sheet, filters persist in shared store
+- **Clear**: Reset all filters to "All"
+
+---
+
+## 13. Privacy Policy Screen
+
+Static content screen.
+
+**Route**: `privacy`
+
+### Elements
+- Privacy policy text content
+- Back navigation
+
+---
+
+## Cross-Cutting Features
+
+### Premium Gating
+- Free users see all workouts but some are locked (lock icon overlay)
+- Tapping a locked workout's "Start" CTA redirects to `paywall`
+- Premium users have full access to all workouts, stats sync, and personalization
+
+### Internationalization (i18n)
+- All user-facing strings are translated via i18n system
+- Multi-language support throughout
+
+### Haptic Feedback
+- Configurable via Profile settings toggle
+- Triggered on: button presses, phase changes, countdown ticks, achievements
+
+### Analytics (PostHog)
+- Events tracked across all screens: screen views, button taps, workout starts/completions, purchases, onboarding steps
+
+### Dark / Light Mode
+- Full theme support — colors adapt to system appearance
+- Player screen is always dark mode regardless of system setting
+
+### Loading & Error States
+- Skeleton placeholders during data fetches
+- Error states with descriptive message + Retry button
+- Empty states with motivational messaging + CTAs
+
+### Animations
+- Onboarding: staggered card reveals, animated charts
+- Home: mascot animation
+- Player: timer ring fill, phase color transitions
+- Complete: spinning emoji celebration rings
+- Navigation: standard iOS push/pop + modal presentations