# CLAUDE.md — Interactive Activities 2026

Vanilla HTML/CSS/JS redesign of 8 interactive activity formats. No build step, no
framework. These files ship close to production. **We are in Phase 3: refining
each activity's design.** When I ask to refine an activity, change only that
activity's file unless I say otherwise.

## Golden rules
- **`global.css` is the single shared file.** A `TOKENS` block at the top
  (colors, spacing, type, radius, shadows, buttons, grade palettes) — a rebrand
  edits values HERE. Below it: shared components (buttons, modals, top bar,
  toolbar, toast, states) + grade themes. Use tokens/aliases; **do not hardcode**
  colors/spacing/type — find the closest token.
- **Each activity is self-contained.** `activities/<name>/index.html` links
  `../../global.css` and holds only its own cards/mechanic CSS + its own `<script>`.
  There is **no `core.js`** and no shared JS — logic is duplicated per file by design.
- **Vanilla only.** No React/Vue/Tailwind, no bundler. Animations are plain CSS/JS
  (no GSAP). Icons are Font Awesome (loaded via `global.css`).
- **Matching is the visual standard.** Dotted background on all activities (it's in
  `global.css` `body`). Match the Matching activity's look/feel.

## Frozen contract — never change
- The content-service fetch and the payload field names
  (`configuration.items[...]`, `isAutoCheck`, category titles, `answers[].isCorrect`,
  flashcard front/back fields, etc.).
- The match/answer logic (e.g. Matching/Sorting `data-*` category/zone rules).
- The parent `postMessage` events: `VcwProgressTrack` and `vcwActivityHasFinished`.
- **Reuse Cloudinary image URLs** straight from the payload; don't swap or host new.

## Accessibility bar (preserve on every change)
Keyboard-operable (drag has a select-then-place alternative), ARIA labels/roles,
visible focus rings, WCAG AA contrast, modal focus trap. The Matching activity is
the reference — don't regress it.

## Grade theming
`body.grade-lower` / `body.grade-upper` / `body.grade-mh` recolor **only the top
bar** to that grade's Main color. The grade dropdown + the whole prototype toolbar
(the `.proto-bar`) are **review-only and get deleted at handoff** — don't build
features into them.

## Running & checking
- Serve over http: `python3 -m http.server` in this folder, then open
  `http://localhost:8000/activities/<name>/index.html?id=<activityId>`.
  A bare `file://` open (and the Slack HTML preview) blocks the live data fetch.
- TTS uses the browser voice as a placeholder; production will use ElevenLabs.

## Status (built — first drafts, being refined)
matching, sorting, q-and-a, spinner, fill-in-the-blanks, dice-roller,
multiple-choice, flashcards. Matching, Sorting, Fill-in-Blanks have `isAutoCheck`
correction modes; Multiple Choice scores via `isCorrect`; Q&A / Spinner / Dice /
Flashcards are non-scored (finish on Done / last card — a trigger still being
confirmed).

## Where to look
- `docs/colors-and-buttons.md` — exact token values (colors, buttons, grade palettes).
- `docs/Phase 1 Recon - 7 Formats.md` — each format's payload shape + mechanic.
- `docs/Execution Plan.md`, `README.md` — architecture + how it's organized.