tabatago/docs/ui-feature-brief.md

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