A premium educational game helping kindergarten children learn sight words through narrative-driven gameplay
Features • Getting Started • Documentation • Tech Stack • Development
Sight Words Adventure transforms the traditionally tedious task of learning sight words into an engaging, story-driven experience. Children aged 4-6 help their favorite characters solve problems by building sentences, progressing through themed campaigns while mastering the Dolch Sight Words - the 133 most common words that make up 50-75% of children's books.
- Flashcards are boring - Kids need games, not drills
- Narrative creates meaning - Words become tools to solve problems
- AI enables infinite content - Never run out of fresh challenges
- Parents need visibility - Track progress without hovering
┌────────────────────────────────────────────────────────────────┐
│ 1. BRIEFING "The bridge is broken! Build words │
│ → Character intro to help Chase cross!" │
│ │
│ 2. ACTION PHASE ┌─────┬─────┬─────┬─────┬─────┐ │
│ → Build sentences │ The │ dog │ can │ run │ . │ │
│ → Get feedback └─────┴─────┴─────┴─────┴─────┘ │
│ │
│ 3. REWARD ⭐⭐⭐ "Paw-some! You saved the day!" │
│ → Stars earned │
│ → Story continues │
└────────────────────────────────────────────────────────────────┘
| Feature | Description |
|---|---|
| Sentence Builder | Tap or drag words to build sentences |
| Themed Adventures | Paw Patrol, Bluey, Marvel, and custom themes |
| Story Map | Progress through narrative campaigns |
| AI Validation | Flexible sentence checking (not strict matching) |
| Voice Feedback | Words speak when tapped, sentences read aloud |
| Hint System | Progressive hints without punishment |
| Unlockables | Avatars, stickers, and celebrations |
| Feature | Description |
|---|---|
| Progress Dashboard | Track word mastery and play time |
| AI Content Generator | Create custom missions from any topic |
| Library Management | Add words, review sentences |
| Multiple Profiles | Support for siblings |
| Parental Gate | Math problem keeps kids in game mode |
- "Premium Fun" - Feels like a real game, not educational software
- "Narrative First" - Learning unlocks the next part of the story
- "Infinite Content" - AI-assisted generation means fresh challenges
- "Encouragement Only" - No "Game Over", only "Try Again!"
- "Cloud-Powered" - LLM validation and on-demand TTS
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Next.js 16+ | App Router, Server Components |
| Language | TypeScript | Type safety (strict mode) |
| Database | Vercel Postgres | Relational data storage |
| ORM | Drizzle | Type-safe queries |
| State | Zustand | Client state management |
| Animation | Framer Motion | Smooth, declarative animations |
| Drag & Drop | dnd-kit | Accessible, touch-friendly |
| Audio | HTML5 Audio API | Native browser audio playback |
| AI/LLM | Vercel AI SDK | OpenAI/Gemini integration |
| TTS | OpenAI TTS | On-demand voice generation |
| Hosting | Vercel | Edge deployment, Blob storage |
- Node.js 20.9+
- npm 10+ (repo is standardized on npm + package-lock)
- Vercel account (for Postgres and Blob storage)
- OpenAI API key (for TTS and validation)
# Clone the repository
git clone https://github.com/wiseyoda/sight-words-game.git
cd sight-words-game
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env.local
# Edit .env.local (and .env for scripts) with your API keys
# Set up database
npm run db:push
npm run db:seed
# Start development server
npm run dev# .env.local / .env
SWG_POSTGRES_URL= # Direct Postgres connection string for Drizzle (postgres://...)
SWG_READ_WRITE_TOKEN= # Vercel Blob storage read/write token
OPENAI_API_KEY= # OpenAI API key for TTS and validationsight-words-game/
├── src/
│ ├── app/
│ │ ├── page.tsx # Home page
│ │ ├── play/ # Gameplay route
│ │ │ ├── page.tsx # Server component (loads data)
│ │ │ └── PlayClient.tsx # Client component (game UI)
│ │ └── api/
│ │ └── ai/
│ │ └── validate-sentence/ # AI validation endpoint
│ ├── components/
│ │ └── game/ # WordCard, Slot, SentenceBuilder
│ ├── lib/
│ │ └── db/ # Drizzle schema & queries
│ └── stores/ # Zustand state stores
├── scripts/ # Database utilities
├── requirements/ # Project documentation
└── public/ # Static assets
Comprehensive requirements documentation is available in the /requirements folder:
| Section | Description |
|---|---|
| Overview | Project purpose, audience, philosophy |
| Gameplay | Core mechanics, sentence builder, feedback |
| Themes | Paw Patrol, Bluey, Marvel, custom themes |
| Curriculum | Dolch word lists, mastery tracking |
| Progression | Story map, unlockables, rewards |
| UX Design | Design principles, layouts, accessibility |
| Admin Dashboard | Parent features, AI generators |
| Audio | TTS integration, sound design |
| Technical | Architecture, data models, APIs |
| Development | Roadmap, phase breakdowns |
| Phase | Focus | Status |
|---|---|---|
| 1 | Core Engine - Sentence builder, AI validation, TTS | ✅ Complete |
| 2 | Polish - Animations, story map, feedback system | ✅ Complete |
| 2.5 | Theme POC - Paw Patrol campaign validation | ✅ Complete |
| 3 | AI & Admin - Dashboard, content generators | ✅ Complete |
| 4 | Themes - Three launch themes, sound design | ⏳ Planned |
| 5 | Beyond - Mini-games, additional content | ⏳ Future |
- Project setup (Next.js, TypeScript, Tailwind)
- Database schema and seeding (49 words, 10 sentences)
- Sentence builder with tap-to-place
- Full drag-and-drop support (word bank ↔ slots ↔ reorder)
- AI validation via OpenAI (flexible, not strict)
- TTS audio for words (HTML5 Audio + OpenAI TTS)
- Sentence audio playback on correct submission
- "Hear my sentence" preview button
- Basic admin CRUD (words + sentences)
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint (needs initial Next.js config)
npm run typecheck # Run TypeScript checks
npm test # Run tests
npm run db:push # Push schema to database
npm run db:studio # Open Drizzle Studio
npm run db:seed # Seed with initial data| Decision | Choice | Rationale |
|---|---|---|
| Validation | AI-powered (LLM) | Flexible word order, semantic understanding |
| Input | Tap-to-place primary | More intuitive for young children |
| Audio | On-demand TTS | No manual recording, infinite words |
| Failure | Encouragement only | No "game over", preserve confidence |
| Offline | Not supported | Simplifies architecture, requires AI |
- iPad (any size)
- Android tablets 8"+
- Fire HD tablets
- Chrome 90+
- Safari 14+
- Firefox 88+
- Edge 90+
- iPhone (landscape mode required) - Added 2025-11-29
- Android phones 5.5"+ (landscape)
- Responsive UI scales for smaller screens
- Portrait orientation
- Legacy browsers
This is currently a private family project. The codebase uses licensed character IP (Paw Patrol, Bluey, Marvel) and is not intended for public distribution.
If the project is ever open-sourced, these themes would be replaced with original characters and full contribution guidelines would be provided.
Private Use Only
This project contains references to licensed intellectual property (Paw Patrol, Bluey, Marvel) and is intended exclusively for private, non-commercial family use. Not for distribution.
- Dolch Word List - The foundation of sight word curriculum
- Duolingo - Inspiration for gamification patterns
- Our kindergartener - The most important product tester
Built with love for curious young readers