Live Demo: https://alfredang.github.io/PhonixQuest/

PhonixQuest is a vibrant, interactive phonics learning platform designed to make learning to read fun and engaging for children. Combining modern web technologies with AI-powered feedback, PhonixQuest guides young learners through a series of "missions" to master letters, sounds, and word formation.

PhonixQuest transforms phonics education into an epic adventure. It covers everything from basic letter sounds to complex blending rules across five magical worlds:

• 📍 Level 1: Letters Land - Master the complete set of 44 English phonemes (Short Vowels, Consonants, Digraphs, and more).
• 📍 Level 2: Blend Bridge - Learn to slide sounds together (Blends like "ST").
• 📍 Level 3: Rule City - Discover secret phonics rules (like the Magic Silent E).
• 📍 Level 4: Rhythm Road - Practice sentence reading and intonation.
• 📍 Level 5: Story Kingdom - Read complete paragraphs and stories.

• 🗺️ Adventure Map: A gamified progression system where kids unlock new levels as they master sounds.
• 🎙️ AI Voice Feedback: Uses Google Gemini AI to listen to the child's pronunciation and provide encouraging, real-time feedback.
• 🎮 Interactive Games: "Pop the Phoneme," "Build the Word," and more to keep engagement high.
• 📈 Progress Tracking: Earn XP, collect stars, and maintain streaks to build a consistent learning habit.
• 🎨 Premium UI: A beautiful, responsive design built with Tailwind CSS 4 and Framer Motion for smooth, playful animations.

• Framework: React 19 + Vite
• AI Integration: Google Generative AI (Gemini)
• Styling: Tailwind CSS 4
• Animations: Framer Motion, Lottie React
• Icons: Lucide React

Follow these steps to set up PhonixQuest on your local machine for development.

• Node.js (Version 20 or later recommended)
• npm (usually comes with Node.js)
• A Google Gemini API Key (Get one for free at AI Studio)

1. Clone the repository:

   git clone https://github.com/alfredang/PhonixQuest.git
   cd PhonixQuest

2. Install dependencies:

   npm install

3. Configure Environment Variables: Create a .env.local file in the root directory and add your Gemini API key:

   VITE_GEMINI_API_KEY=your_gemini_api_key_here

4. Launch the Development Server:

   npm run dev

   The app will be available at http://localhost:3000 (or 3001 if 3000 is busy).

This project includes localized AI Agent skills to ensure consistent development and architectural patterns.

• 📍 Phonics Pedagogy: Standard logic for the 44 English phonemes.
• 📍 Premium UI Standards: Patterns for the dark-blue theme and side navigation.
• 📍 Gemini Integration: Best practices for real-time voice feedback.
• 📍 CI/CD Workflows: Automated deployment guides for static hosting.

These are stored in the .agent/skills and .claude/skills directories.

This project is set up to automatically deploy to GitHub Pages using GitHub Actions. Any push to the main branch will trigger a build and update the live site.

This project is private and for educational purposes.