Skip to content

README.md

Latest commit

 

History

History
91 lines (63 loc) · 3.89 KB

README.md

File metadata and controls

91 lines (63 loc) · 3.89 KB
Raw

🚀 PhonixQuest: Interactive Phonics Explorer

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.

✨ What is PhonixQuest?

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.

🌟 Key Features

  • 🗺️ 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.

🛠️ Tech Stack

🚀 Getting Started

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

Prerequisites

  • 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)

Installation

  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).

🛡️ Agent Knowledge & Skills

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.

🚢 Deployment

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.

📄 License

This project is private and for educational purposes.

Made with ❤️ for the next generation of readers.