arilivigni/0_github_spark_workshop_info.md

## 0_github_spark_workshop_info.md

      
    Raw
  

              0_github_spark_workshop_info.md
            
          
    GitHub Spark Overview


GitHub Spark is an AI-powered application development and deployment platform that turns natural language ideas into full-stack intelligent apps in minutes.
This means faster time to production of new ideas, more of the right ideas shipped, and builders focused on solving business problems—not setup and wiring.
Advantages of using Spark


Accelerate Builder Productivity: Spark turns natural language into working full-stack apps in minutes, helping teams validate ideas early, ship the right things faster, and keep focus on business impact rather than setup
Secure Software Supply Chain: Built on GitHub and Azure, Spark provides enterprise-grade runtime, authentication, and future GHAS integrations—ensuring apps are secure from prototype through production
Broaden Who Builds: Spark unifies designers, PMs, data scientists, and developers in one shared space, breaking down silos so more people can contribute to shipping value
Product Requirements Document (PRD): Spark creates a PRD and as you iterate will update the PRD with some of the changes made to your app creation. Serves as a blueprint for a product, ensuring all stakeholders like designers, engineers, and marketers are aligned.

GitHub Models

Claude Sonnet 4.5 by default as capacity is reached drops back to sonnet 4.
GitHub Spark requirements and billing

Note
Public preview as of 12/01/2025

GitHub Copilot Plans

Currently GitHub Spark requires a Copilot Pro+ or Enterprise license (EMU support)
What are premium requests?

Some Copilot features use premium requests. Premium requests give you access to advanced models and additional AI features.
ex. Spark app creation
GitHub Spark billing

Each prompt consumes 4 premium requests, which draw from your plan's premium request allowance. If you have enabled premium requests over your plan's allowance, additional premium requests beyond your plan's included amount are billed at $0.04 USD per request, meaning that one prompt to Spark would cost $0.16.
Billing for Spark app creation
Self-paced GitHub Skills Exercise

Turn your thoughts into real web apps by simply describing them, no coding required!
The example Spark starter applications in this tutorial were develop in collaboration with real people doing their real jobs.
GitHub Skills Exercise: Idea to app with Spark

  
## 1_elevate-fit-tracker-app-prompt.md

      
    Raw
  

              1_elevate-fit-tracker-app-prompt.md
            
          
    🏋️ App Overview

Elevate Fit Tracker is a social workout tracker application that transforms fitness into an engaging, motivational competitive,
and educational experience. The app combines advanced workout logging with interactive anatomy education, AI-powered coaching, and comprehensive social features to create the ultimate fitness companion.

🎯 Core Features

1. Interactive Muscle Anatomy System


Visual Body Diagram: Interactive front and back human anatomy views
Clickable Muscle Groups: Select worked muscles by clicking on body parts
Smart Exercise Suggestions: Automatically recommends exercises based on selected muscles
Progress Visualization: Color-coded muscle training frequency and recovery status
Educational Component: Learn anatomy while logging workouts

2. AI-Powered Personal Coaches

Three distinct AI coaches with unique personalities and training approaches:
Each coach has motivational quotes in defined by their style of coaching below before workouts
🐤 Ducky (Beginner-Friendly Coach)

Patient and questioning approach for learning
Detailed explanations and gentle guidance
Perfect for newcomers to fitness
Use 🐤 for the Avatar

 Mona (Motivational Coach)

Energetic and encouraging with positive reinforcement
Uses emojis and celebrates every achievement
Fun, varied workouts with team challenges
Use  for the Avatar

 Copilot (Technical Coach)

Data-driven with optimization focus
Detailed analytics and progressive overload tracking
Systematic programming with performance metrics
Use  for the Avatar

3. Comprehensive User Profiles

Personal Dashboard:

Upload an avatar image
Detailed workout analytics with charts and graphs
Progress timeline with milestone tracking
Personal records (PRs) and achievement galleries
Customizable bio with fitness goals and quotes
Privacy controls (public, friends-only, private)

Social Discovery:

Click any avatar to view user profiles
Friend requests and workout challenges
Team invitations and direct messaging
Achievement showcasing and photo sharing

4. Smart Onboarding Experience

Multi-Step Setup:

Coach selection with personality previews
Weekly workout schedule preferences
Fitness goals (lose fat, build muscle, endurance, strength, etc.)
Experience level assessment
Equipment availability and physical limitations
Personalized workout plan generation

5. Team Creation & Management


Create and join fitness teams with invite codes
Team-specific challenges and group workouts
Collective goal tracking and progress dashboards
Team communication with chat and motivation messages
Role-based permissions (captains and members)

6. Competitive Leaderboard System


Multi-tiered rankings (weekly, monthly, all-time)
Multiple categories (frequency, intensity, goal achievement)
Achievement badges and milestone rewards
Head-to-head challenges with custom rewards
Seasonal competitions with special recognition

7. Personalized Workout Engine

Intelligent Recommendations:

AI-powered workout plans based on goals and preferences
Coach-specific programming styles
Dynamic difficulty scaling based on progress
Exercise substitutions for equipment limitations
Recovery integration with rest day suggestions

Adaptive Features:

Progressive overload tracking
Goal-specific metrics and success measurements
Weekly program generation with balanced splits
Real-time workout guidance and form tips


🎨 Design & User Experience

Visual Design


Modern Aesthetic: Glassmorphic design with vibrant color palette
Color Scheme: Electric blues, energizing oranges, success greens
Animations: Smooth micro-interactions and achievement celebrations
Mobile-First: Responsive design optimized for on-the-go usage
Accessibility: Text labels, voice-over support, and inclusive design

User Interface


Bottom Tab Navigation: Easy thumb-friendly access to core functions
Interactive Elements: Satisfying touch feedback and visual responses
Progress Indicators: Animated rings, charts, and completion bars
Quick Actions: Swipe gestures and long-press context menus


📊 Data & Analytics

Workout Tracking


Detailed Logging: Sets, reps, weights, and workout duration
Photo Integration: Progress photos and exercise form reference
GPS Tracking: Outdoor activities with route mapping
Calorie Calculations: Automatic burn estimates with intensity scoring

Progress Analytics


Visual Charts: Weekly/monthly progress with trend analysis
Muscle Balance: Training frequency distribution across body parts
Goal Tracking: Progress toward specific fitness objectives
Performance Metrics: Strength gains, endurance improvements, consistency

Social Data


Activity Feeds: Team member workouts and achievements
Engagement Stats: Likes, comments, and encouragement tracking
Challenge Results: Competition rankings and performance comparisons
Export Options: Personal data export and workout report generation


🔧 Technical Features

Data Management


Persistent Storage: All profiles, workouts, and team information
Real-Time Sync: Live updates for leaderboards and team activities
Offline Capability: Log workouts without internet connection
Cloud Backup: Secure data protection and device synchronization

Security & Privacy


User Authentication: Secure login with GitHub integration
Privacy Controls: Granular visibility settings for all data
Data Protection: Encryption and secure API communications
Content Moderation: Community guidelines and reporting systems

Integration Capabilities


Wearable Devices: Fitness tracker and smartwatch connectivity
Social Sharing: Export summaries for external social media
Calendar Sync: Workout scheduling with calendar applications
Third-Party Apps: Integration with popular fitness ecosystems


🏆 Gamification Elements

Achievement System


Milestone Badges: Workout streaks, goal achievements, social engagement
Progress Rewards: Unlockable themes, avatar customizations, features
Social Recognition: Team contributions, leadership, mentorship badges
Seasonal Events: Special competitions with limited-time rewards

Motivation Features


Streak Tracking: Daily workout consistency with fire emoji animations
Celebration Animations: Achievement unlocks with visual fanfare
Progress Sharing: Automated milestone announcements to teams
Encouragement System: Peer support through likes and comments


🎯 Target Audience

Primary Users


Fitness Enthusiasts: Regular gym-goers seeking better tracking and community
Beginners: New to fitness wanting guidance and education
Team Athletes: Group training and competitive elements
Social Fitness: Community-oriented individuals seeking workout partners

Use Cases


Personal Training: Individual workout planning and progress tracking
Group Fitness: Team challenges and collective goal achievement
Education: Learning proper form and exercise science
Motivation: Social accountability and competitive elements
Progress Documentation: Long-term fitness journey tracking


🚀 Key Differentiators


Educational Anatomy Integration: Learn body parts while working out
Personality-Driven AI Coaches: Three distinct coaching styles for different preferences
Visual Muscle Selection: Click body parts instead of searching exercise lists
Comprehensive Social Features: Full profile system with privacy controls
Gamified Experience: Achievement system that makes fitness engaging
Team-Centric Design: Built for group fitness and social accountability
Mobile-Optimized: Designed specifically for smartphone usage in gyms


📱 App Flow Summary


Onboarding: Choose coach → Set schedule → Define goals → Get personalized plan
Daily Usage: Log workout → Select muscles → Track progress → Engage with team
Social Discovery: View profiles → Send challenges → Join teams → Celebrate achievements
Long-term Engagement: Track progress → Unlock achievements → Compete in leaderboards → Build fitness community

FitTrack Pro transforms traditional workout tracking into an engaging, educational, and social fitness ecosystem that motivates users to maintain consistent exercise routines while building meaningful connections with like-minded fitness enthusiasts.

  
## spark-prd-example.md

      
    Raw
  

              spark-prd-example.md
            
          
    Elevate Fit Tracker - Product Requirements Document

A social workout tracking application that transforms fitness into an engaging, educational, and competitive experience through interactive muscle anatomy, AI coaching, and comprehensive social features.
Architecture Diagram


      graph TB
    subgraph "User Interface Layer"
        A[App.tsx<br/>Root Component] --> B[Onboarding.tsx]
        A --> C[MainApp.tsx]
        
        C --> D1[WorkoutTab]
        C --> D2[TeamsTab]
        C --> D3[LeaderboardTab]
        C --> D4[ProfileTab]
        
        D1 --> E1[MuscleSelector]
        D1 --> E2[WorkoutLogger]
    end
    
    subgraph "State Management"
        F1[useKV Hook<br/>Persistent State]
        F2[useState<br/>Temporary State]
        
        A -.->|currentUser| F1
        D1 -.->|workouts| F1
        D2 -.->|teams| F1
        D3 -.->|leaderboard| F1
        D4 -.->|profile| F1
        
        E2 -.->|exercise sets| F2
        B -.->|onboarding steps| F2
    end
    
    subgraph "Data Layer"
        G1[spark.kv API<br/>Key-Value Store]
        G2[spark.user API<br/>User Info]
        G3[spark.llm API<br/>AI Coach]
        
        F1 <-->|read/write| G1
        A -->|fetch user| G2
        D1 -->|coach advice| G3
        D4 -->|workout plans| G3
    end
    
    subgraph "Type System"
        H1[types.ts]
        H2[UserProfile]
        H3[Workout]
        H4[Team]
        H5[Exercise]
        H6[Coach]
        
        H1 --> H2
        H1 --> H3
        H1 --> H4
        H1 --> H5
        H1 --> H6
    end
    
    subgraph "Data Constants"
        I1[data.ts]
        I2[COACHES]
        I3[MUSCLE_GROUPS]
        I4[EXERCISES]
        I5[FITNESS_GOALS]
        
        I1 --> I2
        I1 --> I3
        I1 --> I4
        I1 --> I5
        
        E1 -.->|muscle options| I3
        E2 -.->|exercise list| I4
        B -.->|coach profiles| I2
    end
    
    subgraph "UI Components"
        J1[shadcn/ui<br/>Component Library]
        J2[Button]
        J3[Card]
        J4[Dialog]
        J5[Input]
        J6[Badge]
        
        J1 --> J2
        J1 --> J3
        J1 --> J4
        J1 --> J5
        J1 --> J6
        
        B -.->|uses| J1
        C -.->|uses| J1
        E2 -.->|uses| J1
    end
    
    subgraph "Utilities"
        K1[utils.ts<br/>cn helper]
        K2[Phosphor Icons]
        K3[Framer Motion]
        K4[Sonner Toasts]
        
        J1 -.->|styling| K1
        C -.->|icons| K2
        B -.->|animations| K3
        E2 -.->|notifications| K4
    end
    
    style A fill:#60a5fa,stroke:#2563eb,color:#fff
    style C fill:#60a5fa,stroke:#2563eb,color:#fff
    style F1 fill:#a855f7,stroke:#7e22ce,color:#fff
    style G1 fill:#ec4899,stroke:#be185d,color:#fff
    style G2 fill:#ec4899,stroke:#be185d,color:#fff
    style G3 fill:#ec4899,stroke:#be185d,color:#fff
    style H1 fill:#10b981,stroke:#059669,color:#fff
    style I1 fill:#f59e0b,stroke:#d97706,color:#fff
    style J1 fill:#8b5cf6,stroke:#6d28d9,color:#fff

    
      Loading

  
Architecture Overview

Application Flow:

Entry Point: App.tsx initializes user via spark.user() API and manages authentication state
Routing Logic: Conditionally renders Onboarding for new users or MainApp for returning users
Tab Navigation: MainApp provides bottom navigation between four primary views
State Persistence: Uses useKV hook for data that persists across sessions (workouts, teams, profiles)
Temporary State: Uses useState for UI-only state (form inputs, dialog visibility)
AI Integration: Leverages spark.llm API for coach personality and workout plan generation
Type Safety: TypeScript types defined in types.ts ensure data consistency
Component Reusability: shadcn/ui components provide consistent, accessible UI patterns

Experience Qualities:

Empowering - Users feel in control of their fitness journey with personalized coaching, visual progress tracking, and clear goal achievement paths
Social - Build community through team challenges, profile discovery, leaderboards, and motivational peer interactions that drive accountability
Educational - Learn anatomy and exercise science through interactive muscle selection, form guidance, and coach-specific training philosophies

Complexity Level: Complex Application (advanced functionality, accounts)

Requires multi-user profiles with authentication, persistent workout data, team management, real-time leaderboards, AI coach integration, social interactions, and comprehensive analytics dashboards

Essential Features

1. Interactive Muscle Anatomy System


Functionality: Visual front/back body diagrams with clickable muscle groups that highlight on selection, recommend exercises, and track training frequency
Purpose: Simplifies workout logging by visual selection instead of text search while educating users on anatomy
Trigger: User navigates to "Log Workout" tab or clicks "Start Workout" button
Progression: View body diagram → Click target muscle groups → System highlights selections → Displays recommended exercises → User selects exercises → Logs sets/reps/weight → Saves workout
Success Criteria: Users can select 3+ muscle groups within 10 seconds, exercise recommendations appear instantly, workout saves with muscle data

2. AI-Powered Coach Selection


Functionality: Three distinct AI coaches (Ducky, Mona, Copilot) with unique personalities provide workout plans, motivational quotes, and training guidance
Purpose: Personalized coaching experience that matches user preferences and experience levels
Trigger: First-time user completes onboarding or existing user changes coach in settings
Progression: View coach profiles → Preview coaching styles → Select preferred coach → Receive welcome message → Get personalized workout plan → Interact with coach during workouts
Success Criteria: Coach personality reflects in all interactions, generates contextual advice, adapts recommendations based on progress

3. Comprehensive User Profiles


Functionality: Personal dashboard with avatar upload, workout analytics, progress charts, PRs, achievements, bio, and privacy controls
Purpose: Track individual progress, showcase achievements, and enable social discovery
Trigger: User clicks profile icon or another user's avatar
Progression: Navigate to profile → View stats/achievements → Upload avatar → Edit bio/goals → Adjust privacy settings → Share profile link
Success Criteria: All workout data visualized with charts, privacy controls functional, clickable avatars throughout app navigate to profiles

4. Smart Onboarding Experience


Functionality: Multi-step wizard collecting coach preference, schedule, goals, experience level, equipment, and limitations
Purpose: Generate personalized workout plans and optimize user experience from day one
Trigger: New user first opens app after authentication
Progression: Welcome screen → Coach selection → Weekly schedule input → Fitness goals selection → Experience assessment → Equipment availability → Physical limitations → Generate plan → Enter app
Success Criteria: Onboarding completes in under 3 minutes, generates relevant workout plan, can be skipped/resumed later

5. Team Creation & Management


Functionality: Create/join teams with invite codes, team challenges, group workouts, chat, and collective progress tracking
Purpose: Build accountability and motivation through social fitness communities
Trigger: User clicks "Teams" tab and selects "Create Team" or "Join Team"
Progression: Create team → Set team name/description → Generate invite code → Share code → Members join → Post group workouts → Track collective goals → Celebrate milestones
Success Criteria: Teams persist data, invite codes work reliably, members see real-time updates, chat enables communication

6. Competitive Leaderboard System


Functionality: Multi-tiered rankings (weekly/monthly/all-time) across categories like workout frequency, intensity, and goal achievement
Purpose: Gamify fitness through friendly competition and public recognition
Trigger: User navigates to "Leaderboard" tab
Progression: View current rankings → Filter by timeframe/category → See personal position → Click users to view profiles → Send workout challenges → Track competition progress
Success Criteria: Rankings update in real-time, accurate scoring, multiple filtering options, clickable user entries

7. Personalized Workout Engine


Functionality: AI generates workout plans based on goals, equipment, coach style, and progress with dynamic difficulty scaling
Purpose: Eliminate workout planning paralysis and ensure progressive overload
Trigger: User completes onboarding or requests new plan in settings
Progression: System analyzes user data → Coach generates weekly program → User views upcoming workouts → Completes workout → System adjusts difficulty → Regenerates next week's plan
Success Criteria: Plans include 3-6 workouts per week, exercises match equipment availability, difficulty increases progressively

8. Workout Logging & Tracking


Functionality: Record exercises with sets, reps, weight, duration, and photos; track workout completion; calculate calories
Purpose: Comprehensive workout documentation for progress analysis
Trigger: User selects "Log Workout" and begins entering data
Progression: Start workout → Select muscles → Choose exercises → Log each set → Add notes/photos → Complete workout → View summary → Share to team feed
Success Criteria: Can log complete workout in under 60 seconds, data persists, displays in profile analytics

Edge Case Handling


No Internet Connection: Queue workout logs locally, sync when connection restored, show offline indicator
Incomplete Onboarding: Save progress, allow skip with defaults, prompt completion from profile
Empty States: Show motivational prompts and CTAs for teams, workouts, and friends when none exist
Invalid Invite Codes: Display clear error message with retry option and team discovery alternatives
Privacy Conflicts: When viewing private profiles, show limited info with option to send friend request
No Available Exercises: When selected muscles have no matching exercises for equipment, suggest alternatives
Duplicate Team Names: Append unique ID suffix, show warning, suggest alternative names
Coach Switch Mid-Program: Confirm action, regenerate plan in new coach's style, preserve workout history
Overtraining Detection: If user logs excessive daily workouts, coach recommends rest day
Data Export Limits: Implement pagination for large history exports, provide CSV and JSON formats

Design Direction

The design should evoke energy, empowerment, and community through bold athletic aesthetics. Users should feel motivated and confident, with clear visual feedback celebrating every achievement. The interface balances high-energy competition elements with calming educational anatomy visualization.
Color Selection

An energizing athletic color scheme that balances motivation with usability and clear hierarchy.

Primary Color: Electric Blue (oklch(0.55 0.24 255)) - Represents energy, trust, and athletic performance; used for CTAs and active states
Secondary Colors:

Deep Charcoal (oklch(0.25 0.01 270)) - Professional background providing contrast
Slate Gray (oklch(0.35 0.02 265)) - Card backgrounds and secondary surfaces


Accent Color: Energizing Orange (oklch(0.68 0.19 45)) - Highlights achievements, streaks, and motivational elements
Success Green: Vibrant Green (oklch(0.65 0.20 145)) - Completed workouts and goals
Foreground/Background Pairings:

Primary Blue: White text (oklch(0.99 0 0)) - Ratio 7.2:1 ✓
Deep Charcoal: White text (oklch(0.99 0 0)) - Ratio 12.1:1 ✓
Slate Gray: White text (oklch(0.99 0 0)) - Ratio 8.4:1 ✓
Accent Orange: Deep Charcoal text (oklch(0.25 0.01 270)) - Ratio 5.8:1 ✓
Success Green: White text (oklch(0.99 0 0)) - Ratio 6.1:1 ✓


Font Selection

Typography should feel athletic yet approachable, with strong hierarchy conveying confidence and clarity for quick readability during workouts.


Primary Font: Space Grotesk - Modern, geometric sans-serif with athletic character for headings and emphasis


Secondary Font: Inter - Clean, highly legible for body text and data with excellent number rendering


Typographic Hierarchy:

H1 (Coach Names, Section Titles): Space Grotesk Bold/32px/tight (-0.02em) letter spacing
H2 (Workout Names, Team Titles): Space Grotesk Semibold/24px/tight letter spacing
H3 (Exercise Names): Space Grotesk Medium/20px/normal letter spacing
Body (Descriptions, Stats): Inter Regular/16px/relaxed (1.6) line height
Small (Labels, Metadata): Inter Medium/14px/normal line height
Caption (Timestamps, Secondary Info): Inter Regular/12px/uppercase/wide (0.05em) letter spacing


Animations

Animations should celebrate achievements and provide satisfying feedback, with energetic celebration moments balanced by smooth, functional micro-interactions during workout logging.

Achievement unlocks: Confetti burst with scale-up animation (500ms)
Workout completion: Success checkmark with elastic bounce (400ms)
Muscle selection: Smooth highlight fade-in with haptic feedback (150ms)
Tab navigation: Slide transition with fade (250ms)
Leaderboard updates: Smooth position changes with highlight flash (300ms)
Coach messages: Slide-in from bottom with gentle spring (350ms)
Progress rings: Animated stroke-dashoffset on value change (600ms ease-out)
Card interactions: Subtle lift on hover with shadow increase (200ms)

Component Selection


Components:

Tabs: Bottom navigation with icons for primary app sections (Workout, Teams, Leaderboard, Profile)
Card: Workout entries, team displays, leaderboard items with custom Tailwind shadow-xl and border-l-4 accent
Avatar: User profile images with fallback initials, size variants (sm/md/lg/xl)
Dialog: Onboarding steps, coach selection, workout completion confirmation with backdrop-blur
Progress: Circular progress rings for workout completion, linear bars for set progress
Button: Primary (electric blue), Secondary (slate), Destructive (red), Ghost for icon actions
Input/Textarea: Exercise notes, team chat, profile bio with focus:ring-primary
Select: Coach selection, muscle group filters, timeframe pickers
Badge: Achievement indicators, muscle group tags with rounded-full and vibrant backgrounds
Accordion: Exercise details, FAQ sections, privacy settings
Separator: Visual dividers between workout sections with decorative gradient variant


Customizations:

Interactive Body Diagram: Custom SVG component with clickable path elements and hover states
Circular Progress Rings: Custom canvas/SVG with animated strokes and percentage labels
Team Activity Feed: Custom timeline component with user avatars and workout summaries
Coach Avatar Cards: Specialized cards with personality indicators and emoji avatars
Leaderboard Rankings: Custom list with position indicators, medals for top 3, and sparkle animations


States:

Buttons: Default subtle gradient, hover lift + glow, active press down, disabled reduced opacity
Inputs: Default border-slate, focus ring-primary with border-primary, error ring-destructive
Muscle Groups: Default outlined, hover scale + glow, selected filled with accent color, disabled grayscale
Cards: Default elevated shadow, hover increased shadow + border glow, selected border-primary


Icon Selection:

Workout/Exercise: Barbell, Dumbbell icons from Phosphor
Teams: Users, UsersThree for groups
Leaderboard: Trophy, Medal, Crown for rankings
Profile: User, UserCircle for avatars
Progress: ChartLine, TrendUp for analytics
Completion: CheckCircle, Fire for streaks
Navigation: House, Calendar, Chat, Gear
Actions: Plus, PencilSimple, TrashSimple, Share


Spacing:

Page padding: p-4 (16px) mobile, p-6 (24px) tablet+
Card gap: gap-4 in grids, gap-6 between major sections
Form elements: gap-2 for label/input pairs
List items: py-3 px-4 for touch-friendly tap targets
Section margins: mb-8 between major sections, mb-4 within sections


Mobile:

Bottom tab bar: fixed position with safe-area-inset-bottom padding
Single column layouts with full-width cards
Muscle diagram: Optimized for portrait, scrollable horizontally if needed
Touch targets: minimum 44px height for all interactive elements
Sticky headers on scroll for context retention
Collapsible sections (accordion) for dense information
Swipe gestures for quick actions (delete workout, mark complete)
Modal dialogs slide up from bottom instead of center
Reduced motion preference respected for accessibility
No results found