🐝 Spelling Bee Practice App — CBE Second Grade

An interactive spelling bee practice app built for second-grade students at CBE.
Designed to help kids hear a word spoken aloud, listen to its letter-by-letter spelling, and track which words need more practice.

---

✨ Features

• 🔤 Displays one word at a time in a large, readable font
• 🔊 Speaks the full word aloud, then spells it letter by letter
• 🌟 Visual letter-by-letter highlight as the word is spelled out
• 📌 Mark words as "needs practice" for focused review sessions
• 🎯 Two modes: All Words and My Practice List
• 💾 Progress is saved locally in the browser (no account needed)
• 📱 Works on desktop and tablet (touch-friendly)
• ✈️ Fully offline-capable after first load (no internet required)

---

🚀 Getting Started

Prerequisites

• Node.js v20 LTS or later
• npm v9+

Install & Run

git clone https://github.com/your-org/spelling-bee.git
cd spelling-bee
npm install
npm run dev

Open http://localhost:5173 in your browser.

Build for Production

npm run build
# Output is in /dist — deploy to any static host (GitHub Pages, Netlify, Vercel, etc.)

---

🚀 Deploy to Vercel

Option A — Vercel CLI (recommended for first deploy)

npm install -g vercel
vercel login          # follow the browser prompt
vercel                # deploy preview from local machine
vercel --prod         # promote to production

Vercel auto-detects Vite. No extra config needed for a first deploy.

Option B — GitHub + Vercel Dashboard (recommended for ongoing CD)

1. Push the repo to GitHub
2. Go to vercel.com/new → Import Git Repository
3. Select your repo
4. Vercel auto-fills the build settings:
   • Framework Preset: Vite
   • Build Command: npm run build
   • Output Directory: dist
5. Click Deploy

Every push to main triggers a new production deploy automatically.
Every pull request gets its own preview URL.

Option C — vercel.json (if you need custom config)

Add a vercel.json at the project root:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "vite"
}

This is only needed if the auto-detection ever misses. For this project it is optional.

---

🗂 Project Structure

spelling-bee/
├── public/
├── src/
│   ├── components/
│   │   ├── WordCard.jsx          # Large word display + letter highlight
│   │   ├── SpeechControls.jsx    # "Hear Word" and "Hear Spelling" buttons
│   │   ├── NavigationBar.jsx     # Next / Previous / Mode toggle
│   │   └── ProgressBadge.jsx     # Struggling word count indicator
│   ├── hooks/
│   │   ├── useSpeech.js          # Web Speech API logic
│   │   └── useProgress.js        # localStorage persistence
│   ├── data/
│   │   └── words.js              # All 112 words from the PDF
│   ├── App.jsx
│   ├── main.jsx
│   └── index.css
├── SPEC.md
├── ARCHITECTURE.md
├── CLAUDE.md
└── README.md

---

🧠 Speech Engine

This app uses the Web Speech API (speechSynthesis), built into all modern browsers.
No external API calls. No keys. No cost. Works offline.

• The full word is read in a natural English voice
• Each letter is then spoken individually with a short pause between letters
• Letters are highlighted in the UI in sync with the audio

---

📦 Tech Stack

Layer	Choice	Reason
Framework	React 18 + Vite	Fast, modern, easy to deploy as static site
Styling	CSS Modules	Scoped, no build complexity
Speech	Web Speech API	Built-in, offline, no AI/API needed
Storage	localStorage	Simple persistence, no backend required
Deployment	Static (dist/)	GitHub Pages / Netlify / Vercel