HabitQuest - Gamified Habit Tracker

🎮 Level Up Your Life Through Habits 🎮

A beautifully designed React Native habit tracker with RPG-style gamification and native platform integration

✨ Features

🎯 Core Habit Tracking

• Flexible Scheduling: Daily, weekly, monthly, or custom frequency patterns
• Positive & Negative Habits: Track both habits you want to build and behaviors to avoid
• Smart Reminders: Optional notification system to maintain consistency
• Multi-count Tracking: Support for habits that can be completed multiple times per day

🎮 Gamification System

• XP & Leveling: Earn experience points for every completed habit
• Tier System: Progress through Bronze → Silver → Gold → Platinum → Diamond tiers
• Streak Tracking: Visual fire indicators showing consecutive completion days
• Achievement System: Unlock badges for milestones like "7-day streak" or "100 habits completed"
• Virtual Currency: Earn coins to unlock future avatar customizations and themes
• Daily Challenges: Bonus XP opportunities with specific daily goals

📊 Progress & Analytics

• Visual Progress Bars: See your advancement toward the next level
• Weekly Activity Charts: Bar charts showing habit completion patterns
• Habit Performance: Individual completion rates for each habit
• Stats Dashboard: Track total completions, longest streaks, and coins earned

🎨 Native Design

• Platform-Native Tabs: Uses iOS's native tab bar and Android's Material tabs
• Adaptive Theme: Automatically switches between light and dark mode based on system preference
• SF Symbols on iOS: Native iOS icons for authentic feel
• Material Icons on Android: Consistent Material Design across Android
• Dynamic Colors: Full support for iOS Dynamic Colors and Android theme colors

📱 Screenshots

Main Screens

• Today: Daily overview with habit checklist, challenges, and progress percentage
• Habits: Manage all habits with filtering by type (positive/negative)
• Progress: Detailed statistics with XP visualization and performance charts
• Achievements: Browse unlocked and locked achievements with progress tracking
• Profile: User level, tier badge, avatar customization, and settings

🛠️ Tech Stack

• Framework: Expo ~54.0
• Language: TypeScript 5.9
• Navigation: Expo Router 6.0 with file-based routing + Native Tabs
• UI Components: React Native with platform-specific icons
• Theme System: Dynamic light/dark mode following system preference
• State Management: React hooks (useState, useEffect)
• Date Handling: date-fns 4.1
• Storage: AsyncStorage (ready for local data persistence)

🎨 Theme System

The app features a comprehensive theme system that automatically adapts to the system's appearance:

Light Mode

• Clean white backgrounds with subtle gray cards
• Black/dark gray text for optimal readability
• Vibrant indigo primary color (#6366F1)
• Warm gold for XP and rewards
• Fresh colors for success, warning, and error states

Dark Mode

• True black background (#000000) for OLED efficiency
• Pure white text for maximum contrast
• Softer indigo primary color (#818CF8)
• Maintains tier colors with slight adjustments
• Reduced opacity for better dark mode experience

Theme Colors

All colors are defined in constants/Colors.ts with semantic naming:

• Core: background, foreground, card, primary, secondary
• Status: success, warning, destructive, info
• Gamification: xp, streak, bronze, silver, gold, platinum, diamond

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• Expo CLI
• iOS Simulator (Mac) or Android Emulator

Installation

# Clone the repository
git clone https://github.com/PrimeCodeWhisperer/habitquest-native.git
cd habitquest-native

# Install dependencies
npm install

# Start the development server
npm start

Running the App

# iOS
npm run ios

# Android
npm run android

# Web (experimental)
npm run web

💾 Current Implementation

Mock Data

The app currently uses comprehensive mock data including:

• 6 sample habits with various frequencies and types
• 30 days of historical completion data
• 6 achievements (4 unlocked, 2 in progress)
• 2 daily challenges
• User progress at Level 12, Silver tier

No Backend Required (Yet)

This version is fully functional with mock data. Backend integration points are prepared but not implemented, allowing you to:

• Test all UI flows and interactions
• Explore the gamification mechanics
• Evaluate the user experience
• Connect to your preferred backend solution later

📝 Project Structure

habitquest-native/
├── app/
│   ├── (tabs)/          # Tab-based navigation screens
│   │   ├── index.tsx    # Today screen
│   │   ├── habits.tsx   # Habits management
│   │   ├── progress.tsx # Progress & stats
│   │   ├── achievements.tsx
│   │   └── profile.tsx  # User profile
│   └── _layout.tsx    # Root layout
├── types/
│   └── index.ts       # TypeScript type definitions
├── data/
│   └── mockData.ts    # Mock data for development
├── constants/
│   └── Colors.ts      # Theme color definitions
├── hooks/
│   ├── useColorScheme.ts  # System theme detection
│   └── useThemeColor.ts   # Theme color hook
├── utils/
│   └── storage.ts     # AsyncStorage utilities
├── assets/           # Images and fonts
├── package.json
└── tsconfig.json

🛣️ Roadmap

Phase 1: Current (MVP)

• Core UI/UX with 5 main screens
• Native platform tabs (iOS & Android)
• Dynamic light/dark theme system
• Mock data implementation
• Gamification mechanics (XP, levels, tiers)
• Streak tracking
• Achievement system
• Daily challenges

Phase 2: Data Persistence

• AsyncStorage integration for local data
• Habit CRUD operations (Create, Read, Update, Delete)
• Completion history tracking
• Settings persistence

Phase 3: Enhanced Features

• Push notifications for reminders
• Custom habit icons and colors
• Habit notes and journaling
• Calendar view with heat map
• Habit templates library

Phase 4: Gamification Expansion

• Avatar customization shop
• Unlockable themes
• Weekly/monthly challenges
• Leaderboards (optional social features)
• Bonus XP events

Phase 5: Backend Integration

• User authentication
• Cloud sync across devices
• Data backup and restore
• Analytics and insights

🎨 Design Philosophy

HabitQuest combines proven habit-tracking principles with engaging game mechanics:

• Loss Aversion: Streaks create motivation to maintain consistency
• Variable Rewards: Occasional bonus XP and achievements provide excitement
• Progress Visualization: Multiple ways to see growth (levels, charts, percentages)
• Clear Goals: Specific targets for leveling up and achievements
• Positive Reinforcement: Celebrations for completions and milestones
• Native Experience: Platform-specific UI elements for familiar interactions

👥 Contributing

Contributions are welcome! This is a learning project, so feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

📝 License

MIT License - feel free to use this project for learning or as a starting point for your own habit tracker.

🚀 Inspiration

Built following best practices from successful habit trackers like:

• Habitica (gamification elements)
• Streaks (minimalist design)
• Productive (flexible scheduling)
• Fabulous (progress visualization)

And following native iOS and Android design guidelines for authentic platform experience.

---

Built with ❤️ using Expo and React Native

Supports both iOS and Android with native platform integration

Start your habit journey today! 🌟