Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (83 loc) · 5.11 KB

CLAUDE.md

File metadata and controls

113 lines (83 loc) · 5.11 KB
Raw

NounsAndVerbs — Project Notes for Claude

What this is

Two educational HTML games built for Christian, a 2nd grader in California, to practise distinguishing nouns (things) from verbs (actions). Commissioned by his mother Liesl who monitors progress via a PIN-protected parent dashboard.

Live URL

https://veriqai.github.io/NounsAndVerbs/

GitHub repo: https://github.com/VeriQAi/NounsAndVerbs
Local files: C:\Users\aknoesen\Documents\Christian\ChristianVerbAndNoun\

Files

index.html                  — landing page, links to both games
sports-word-champ.html      — sports-themed game (baseball, basketball, soccer)
ninja-word-master.html      — ninja-themed game (generic — NOT Ninjago branded, see below)
instructions-for-parent.html — parent setup guide (includes live URLs)
VeriQAI.png                 — logo, referenced by all HTML files
README.md                   — public-facing repo description
CLAUDE.md                   — this file

Deployment

  • Hosted on GitHub Pages from the main branch root
  • No build step — push HTML/PNG files directly, Pages serves them
  • Git remote is https://github.com/VeriQAi/NounsAndVerbs.git
  • Credentials: push as a user with write access to the VeriQAi GitHub org

To deploy a change:

cd "C:/Users/aknoesen/Documents/Christian/ChristianVerbAndNoun"
git add <files>
git commit -m "description"
git push

Tech stack

  • Pure HTML/CSS/JS — no framework, no build tool, no dependencies
  • localStorage for all persistence (scores, sessions, PIN) — data never leaves the device
  • Works offline once loaded; designed for iPad + Safari
  • "Add to Home Screen" support via apple-mobile-web-app-* meta tags

Game mechanics

  • 10 words per round: 5 nouns + 5 verbs, shuffled
  • Each word shown with a context sentence — the target word highlighted in blue/underlined
  • Two big tap buttons: THING (noun) and ACTION (verb)
  • Correct: green flash + praise phrase; Wrong: red shake + correct answer shown
  • Streak counter fires at 3+ consecutive correct
  • Stars: 1 (≥5/10), 2 (≥7/10), 3 (≥9/10); cumulative total on home screen
  • Round selection avoids the same word appearing as both noun and verb in one round

Word bank design — important

Many sports/ninja words are dual-use (can be noun or verb). The app handles this by storing two separate entries for each such word — one noun, one verb — each with a different context sentence that makes the correct answer unambiguous. The deduplication filter keyed on word + type (not just word) preserves these pairs.

Example:

{ word:'score', type:'verb', sentence:'He wants to score a goal for his team.' }
{ word:'score', type:'noun', sentence:'The score is two to one at halftime.' }

When adding new words, always check whether the word is dual-use and if so, add both entries with disambiguating sentences.

Parent dashboard

  • Accessed via small "Parent View" link at bottom of welcome/round-end screens
  • PIN-protected — 4-digit PIN set on first use, stored in localStorage
  • Each game has its own independent PIN and progress storage
    • Sports: localStorage keys swc_sessions_v1, swc_pin, swc_stars
    • Ninja: localStorage keys nwm_sessions_v1, nwm_pin, nwm_stars
  • Dashboard shows: sessions played, total stars, avg accuracy, last session, noun vs verb accuracy bars, most-missed words, session history with trend indicator
  • Trend message appears after 4+ sessions (compares first half vs second half accuracy)

Copyright — important

The ninja game was originally Ninjago-themed. All Ninjago/LEGO IP was removed when the repo was made public. Do not re-introduce:

  • Character names: Kai, Jay, Cole, Zane, Lloyd, Nya, Master Wu
  • The word "Ninjago" (city, world, or show name)
  • The term "spinjitzu" (LEGO trademark)
  • "Serpentine" as a Ninjago faction name

The game is now a generic ninja world theme. Replacement vocabulary used: shadow warrior, the sensei, the master, the dark lord, their village, their world, the spinning art, the ancient power.

Target users

Person Role Device
Christian Player (2nd grade) iPad (Safari)
Liesl Parent, monitors progress Mac Air (receives links)

Liesl accesses via URL — no file transfer needed. She adds each game to iPad home screen via Safari Share → Add to Home Screen.

Design principles established in this project

  • THING / ACTION labels preferred over Noun / Verb for 2nd grade comprehension
  • Context sentences are mandatory — isolated words are ambiguous for dual-use vocabulary
  • No timer, no pressure — one word at a time
  • Feedback is immediate and visual (card colour + animation)
  • Parent dashboard is separate from the kid experience and PIN-gated
  • Data stays on device — privacy is a stated requirement from the client

Possible future enhancements discussed (not built)

  • Additional themes (e.g. Minecraft, dinosaurs, space)
  • Difficulty tiers (easy words → harder words as accuracy improves)
  • Audio feedback (cheer sounds, wrong-answer buzz)
  • Sentence-mode: show a full sentence, tap the noun or verb within it