Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dicklesworthstone/letter_learning_game


https://github.com/dicklesworthstone/letter_learning_game

Last synced: 28 days ago
JSON representation

Awesome Lists containing this project

README 

          
# Learn Your Letters!



An accessible, single‑file educational game that helps young children learn the alphabet through sound, visuals, and drawing. The entire app lives in one `index.html` and runs in any modern browser.



This README reflects the current code precisely. If something is listed here, it exists in `index.html`; if it is not in the code, it is not claimed here.



## What It Is

- Single‑file app: everything is implemented in `index.html`.

- Three core modes: Find Letters (identify), Word Builder (spell), and Tracing Practice (draw).

- Child‑friendly UI, big touch targets, optional phonics flow, and gentle animations.

- Data is stored locally in the browser via `localStorage` (no backend).



## Major Features



### Modes

- Find Letters

  - Presents 4 large letter tiles (same case as the target).

  - Speaker button plays the target letter (via SpeechSynthesis API).

  - Adaptive selection favors letters that need practice and avoids recent repeats.

  - Optional phonics follow‑up (3‑second countdown, then letter sound and anchor word/emoji). Can be skipped.

  - Scoring: base points plus a time bonus, with a per‑round cap. Wrong answers/timeouts deduct points.

- Word Builder

  - Presents a target word with empty slots and a small bank of letter tiles.

  - Speaker button plays the target word (via SpeechSynthesis API).

  - Build the word by tapping/clicking letter tiles to fill slots left‑to‑right.

  - Adaptive difficulty with easy/medium/hard word pools: 3‑letter CVC → 4‑letter → 4–5‑letter words; shows a difficulty badge and adjusts up/down based on consecutive correct/incorrect attempts. Letter case follows the Letters setting (lowercase/uppercase/mixed).

  - Letter bank includes decoy letters and matches the word’s case; bank size is at least 5 or `word length + 3`.

  - Scoring: +20 for a correct word; −5 for an incorrect attempt; advances to the next word automatically.

  - Controls: Hear Word, New Word.

- Tracing Practice

  - Responsive canvas sized to fit the screen (typically 260–560px square).

  - Optional letter formation overlay (Show/Hide How to Write).

  - Recognition: classical similarity (cloud matching + IoU checks) with optional deep similarity (MobileNet via TensorFlow.js if available).

  - Letter‑specific helpers (dot detection for i/j, crossbar detection for t/f/E/F/H).

  - Idle hint: after a short delay, a faint letter guide fades in (disabled as soon as the child starts tracing).



### Adaptive Difficulty

- Tracks per‑letter performance: correct, total attempts, response times, and a small spaced‑review state.

- Builds an adaptive selection pool that up‑weights letters with low success rates and down‑weights recent letters.

- Temporary “shape similarity” bias after an error (e.g., b/d/p/q) to reinforce tricky distinctions.

- Difficulty indicator (1–5 bars) reflects overall performance; it is a visual indicator only (timing is not directly tied to the indicator).



### Timing and Feedback

- Timer On/Off (per setting). When on, a countdown bar and verbal countdown for the last 3 seconds.

- Timeouts count as incorrect, with appropriate feedback and scoring.

- Feedback banner for success/error, plus subtle wrong‑answer flash to keep kids oriented.



### Celebrations

- Default celebration uses themed emoji confetti and letter‑specific animations (e.g., rockets, balloons, etc.).

- Celebration type is stored in save data; there is currently no UI for changing the celebration theme in Settings.



### Visual Themes

- Classic: clean letters.

- Animals: shows letter associations (icon + word) near the correct option.

- Colors: highlights vowels vs consonants.



### Phonics Flow (optional)

- After a correct answer, optionally enters phonics phase:

  - 3‑second on‑screen countdown.

  - Speaks the phonetic sound 3 times and optionally “as in ”.

  - Shows an on‑screen emoji for some anchor words.

  - Echo practice: if Voice Recording is enabled and permitted, listens briefly for the child’s voice; otherwise shows a repeat button.

- The phonics phase can be skipped at any time.



### Mini‑games (automatic short breaks)

- Letter Rain: move the basket to catch the target letter; score feedback.

- Memory Match: flip pairs of matching letters in a 4×4 grid with a timer.

- Mini‑games are occasionally offered between questions in Find Letters and Word Builder modes.



### Achievements

Defined achievements (unlocked/persisted locally):

- First Steps: first correct answer.

- Streak 5, Streak 10: consecutive correct answers.

- Speed Demon: 10 answers under 2 seconds (defined but not currently incremented in code).

- Perfect Round: complete a round with no mistakes.

- Letter Master: master all 26 letters.

- Score milestones: 100, 500, 1000 points.

- Play time: 10 minutes, 30 minutes total.

- Rounds: complete 5 rounds.



Badge counter appears on the trophy button and is visible once you earn at least one achievement.



### Round System

- 15 questions per round.

- Round summary modal shows: average time, accuracy, points gained, and “problem letters” (letters with 2+ errors this round).



### Streaks

- Tracks daily play streaks (based on calendar days).

- Milestone modal for common streak thresholds (3, 7, 14, 30, 50, 100) with a 4‑week calendar view.

- Shows a compact streak banner (hidden until the streak is at least 2 days).



### Multiplayer (Profiles)

- Add players with an emoji avatar and a name.

- Per‑player: scores, rounds, best streak, letter performance, achievements, mastered letters, and celebration type.

- Player data is saved to `localStorage` and can be switched from the top player selector.



### Parent/Teacher Dashboard

- Open by long‑pressing (about 2s) or double‑clicking the gear button.

- Sections:

  - Player Progress cards (score, accuracy, letters mastered, best streak).

  - Letter Performance Heatmap (A–Z color‑coded by success rate, with per‑cell tooltip).

  - Insights (simple, rule‑based suggestions based on performance and timing).

  - Recommendations (practical activity suggestions + time‑of‑day hints).

- Dashboard and other overlays trap keyboard focus and prevent background scrolling while open.



### Settings

- Basic

  - Timer: On/Off

  - Letters: lowercase/uppercase/mixed

  - Phonics: On/Off

  - Sound: On/Off

  - Word Builder: On/Off

- Visual Theme: Classic / Animals / Colors

- Advanced

  - Voice Recording: On/Off (for phonics echo + practice tools)

  - Focus Mode: simplifies the UI and disables the timer while active

  - High Contrast: increases contrast

  - Reduce Motion: minimizes animations

  - Quick entry to Parent Dashboard



## Scoring (as implemented)

- Correct answer: `base + timeBonus`, then capped so total points gained in a round do not exceed 50.

  - Base = `10 + (difficultyLevel * 5)`

  - Time bonus decreases with response time, up to about +30 for very fast answers

- Wrong answer: −10 points and resets correct streak; briefly highlights the correct tile.

- Timeout: −10 points and counts as an incorrect attempt.



## Persistence

Saved in `localStorage`:

- Overall game data: `letterLearningGameData` (score, rounds, achievements, per‑letter performance, streaks, settings, etc.).

- Players list (for multiplayer): `letterLearningPlayers` (per‑player state; Sets are serialized as arrays).



## Accessibility

- Big touch targets and large typography.

- Focus Mode that reduces UI complexity and disables timers.

- High Contrast and Reduce Motion toggles.

- ARIA attributes on interactive elements and focus traps for modals.



## Technology

- Single HTML file: `index.html` (HTML, CSS, and vanilla JS).

- External libraries loaded via CDN:

  - TailwindCSS (utilities)

  - GSAP 3.12.x (animations; with requestAnimationFrame fallback)

  - Animate.css 4.x (occasional effects)

  - TensorFlow.js and MobileNet (optional; used only when available for deeper tracing similarity)

- SpeechSynthesis API for voice prompts with an English‑voice priority list.

- Optional Google Analytics tag is included in the HTML head (basic usage analytics).



Note: Because libraries are loaded from CDNs, an internet connection is required on first load. Microphone features require HTTPS (or `localhost`).



## Design Tokens (excerpt)

Core CSS variables used in the app:



```

:root {

  --primary: #6366F1;

  --primary-dark: #4F46E5;

  --secondary: #EC4899;

  --secondary-dark: #DB2777;

  --success: #10B981;

  --warning: #F59E0B;

  --error: #EF4444;

  --gray-50: #F9FAFB;

  --gray-100: #F3F4F6;

  --gray-200: #E5E7EB;

  --gray-300: #D1D5DB;

  --gray-400: #9CA3AF;

  --gray-500: #6B7280;

  --gray-600: #4B5563;

  --gray-700: #374151;

  --gray-800: #1F2937;

  --gray-900: #111827;

}

```



## Deployment

- Static hosting: upload the single `index.html` to any static host (e.g., GitHub Pages, Cloudflare Pages, Netlify, S3/CloudFront).

- Ensure the site is served over HTTPS to enable microphone features.



## Device Support

- Modern desktop and mobile browsers with ES6, Flexbox/Grid, and SpeechSynthesis support.

- Touch input is fully supported; mouse and keyboard interactions also work.



## Privacy

- No backend or account system; all progress and settings stay in the browser (`localStorage`).

- A Google Analytics tag is present for basic usage analytics. If you prefer not to use analytics, remove the GA `` tag block at the top of `index.html` before deploying.



## Known Notes

- The “Speed Demon” achievement is defined but is not currently incremented by gameplay logic.

- Celebration type is saved/restored, but there is no Settings UI to change it yet (default is fireworks).

- Optional deep similarity for tracing (TensorFlow.js + MobileNet) is used only when those libraries are available.



## Contributing

Issues and pull requests are welcome. Useful areas include:

- Hooking up the speed‑based achievement tracking.

- Exposing celebration theme selection in Settings.

- Additional mini‑games or letter formation guides.

- Accessibility refinements and performance tuning.



## Credits

Created by Jeffrey Emanuel. Made freely available for families and classrooms.