START HERE — Goldilocks Talking Book
This file has two parts.
**Part 1** = commands you type in the terminal.
**Part 2** = one long message you paste into Claude Code.
Do Part 1 first. Then Part 2.
---
PART 1 — Make the folder and open Claude Code
Open Terminal. Copy these lines one at a time.
Step 1. Make the folder
```bash
mkdir -p ~/Projects/talking-books/goldilocks
cd ~/Projects/talking-books/goldilocks
```
Step 2. Make a folder for reference files
```bash
mkdir -p reference
```
Step 3. Move two files into `reference`
Put these two files inside the `reference` folder:
1. `goldilocks-talking-book.html` — the demo I built you
2. `Year_1-Goldilocks_and_The_Three_Bears.pdf` — the original book
You can drag and drop them in Finder.
Or use this command (change the path if your files are elsewhere):
```bash
cp ~/Downloads/goldilocks-talking-book.html reference/
cp ~/Downloads/Year_1-Goldilocks_and_The_Three_Bears.pdf reference/
```
Step 4. Check they arrived
```bash
ls reference
```
You should see both files listed.
Step 5. Start Claude Code
```bash
claude
```
---
PART 2 — Paste this into Claude Code
Copy everything inside the box below. Paste it as your first message.
---
> **BEGIN PASTE**
I am building a production web app. You are the engineer. I am not technical, so explain choices in plain words and do not assume I know the jargon.
What we are building
An interactive digital talking book of **Goldilocks and the Three Bears**, a Year 1 English workbook aligned to the National Curriculum in England. It was written and designed by Wajiha Aamir. It has 73 numbered teaching pages.
Children will use it on a tablet. They listen, read along, and tap things.
This is the first of a series. **Little Red Riding Hood (Year 2) comes next.** So build an engine, not a one-off.
Read these first
In the `reference` folder there are two files.
1. `goldilocks-talking-book.html` — **This is the visual and behavioural target.** Open it and read all of it. It is a single-file working prototype of the entire book. Every page, every activity, every character is already designed in there. Do not redesign it. Port it.
2. `Year_1-Goldilocks_and_The_Three_Bears.pdf` — the original 79-page book. Use it to check story text, vocabulary and task wording.
Read the HTML file completely before you write any code. It is about 1,350 lines. It is the spec.
The stack
- Next.js (App Router) + TypeScript
- Tailwind CSS
- Supabase for progress data
- Deploy on Vercel
- GitHub for the repo
Hard rules
1. **The book is data, not code.** Every page is an entry in a typed data file. Page templates are reusable React components. Adding a new book must mean writing a new data file, not new components.
2. **Never break Read With Me.** Each word is its own span. Words highlight in time with the audio. This is the single most important feature. Test it on every story page.
3. **Audio is pre-recorded MP3 files, with browser speech as a fallback.** I have an ElevenLabs account. Build a script that reads the narration lines from the data files and generates the MP3s in one batch. Never rename an audio file id once it is generated.
4. **Offline first.** Ship it as a PWA with a service worker. After the first load it must work with no internet, audio included.
5. **Original artwork only.** All characters and props are inline SVG, copied from the prototype. The printed book's illustrations belong to the illustrator and are not used.
6. **British English everywhere.** cosy, colourful, favourite, apologise, recognise.
7. **Tablet first.** Design for a landscape iPad. It must also work on a phone and a laptop.
8. **No login for children.** Progress saves to the device first. Supabase sync is optional and anonymous.
The characters
- **Ollie the Wise Old Owl** — the guide and narrator. He is in the original book on pages 66 to 67. He appears on every page.
- Goldilocks, Papa Bear, Mama Bear, Baby Bear, Grandma.
Every character has: gradient shading, eyes that follow the pointer, a blink loop, a mouth that moves while speaking, and a breathing idle.
The page templates
Take these from the prototype exactly:
- `story` — scene art, narration with Read With Me, tappable vocabulary
- `teach` — cards you tap to hear
- `predict` — make a prediction, saved and shown again later
- `recall` — star confidence check
- `task` — four level tabs, word bank, sentence starters, punctuation checklist
- `pickThree` — porridge, chairs, beds
- `sort` — two-bucket sorting
- `voices` — the three bears, three different pitches
- `wordIndex` — A to Z explorer
- `award` — certificate with the child's name
Build it in this order
Stop after each phase and show me. Do not run ahead.
**Phase 1 — Skeleton.** Next.js app, Tailwind, folder structure, empty page templates, one working story page with Read With Me. Nothing else.
**Phase 2 — Full data.** All 73 pages entered as data. Every template working. This is the big one.
**Phase 3 — Audio.** The ElevenLabs generation script and the audio player.
**Phase 4 — Offline.** PWA, service worker, install prompt.
**Phase 5 — Progress.** Supabase, teacher dashboard.
Before you write anything
Do these three things:
1. Read both reference files.
2. Write a `CLAUDE.md` file in the repo root containing the hard rules above, so future sessions keep to them.
3. Show me the folder structure you plan and the TypeScript type for a page. Wait for me to say yes.
Then start Phase 1.
> **END PASTE**
---
What to expect
Claude Code will read the files. That takes a minute.
Then it will show you a plan. Read it. Say yes, or ask it to change something.
Then it starts building.
**Say "stop" any time.** You are the boss of the session.
---
Useful commands later
Run the app on your machine:
```bash
npm run dev
```
Then open `http://localhost:3000` in your browser.
Save your work to GitHub:
```bash
git add .
git commit -m "what changed"
git push
```