Times Table Tutor

A calm, anxiety-free web app for learning times tables through adaptive practice and a progressive scene reveal reward system.

Overview

This skill helps you work with the Times Table Tutor codebase - a ADHD-friendly educational web application that teaches multiplication facts through adaptive learning, strategy hints, and a progressive scene reveal reward system.

Tech Stack

Project Structure

```

src/

├── components/

│ ├── common/ # Button, Modal, ProgressBar, Navigation, Layout, Celebration, SettingsModal

│ ├── practice/ # ProblemDisplay, AnswerInput, HintPanel, MultipleChoice, NumberPad

│ ├── learn/ # FactCard, VisualExplainer

│ ├── progress/ # ProgressView, ProgressScene, MasteryGrid, ActivityCalendar, RevealSequence

│ └── garden/ # (legacy) GardenItem, GardenView

├── views/ # PracticeView, LearnView, ProgressViewPage

├── stores/ # Zustand stores (progress, progressView, garden, session, focusTables)

├── lib/ # Core logic (adaptive, strategies, rewards, sounds, storage)

├── hooks/ # useSound

└── types/ # TypeScript types

```

Instructions

When working with this codebase, follow these steps:

1. Development Setup

For local development:

```bash

bun install

bun run dev # Start frontend + API concurrently

```

Access points:

If ports are blocked:

```bash

bun run cleanup # Kill phantom processes, free ports

```

2. Database Operations

For local D1 database:

```bash

bun run db:migrate:local # Run migrations on local D1

```

For production deployment:

```bash

bun run db:migrate # Run migrations on production D1

```

First-time production setup:

1. Create D1 database: `bunx wrangler d1 create ttt-db`

2. Update `database_id` in `wrangler.toml` with the real ID

3. Run production migrations: `bun run db:migrate`

3. Key Application Concepts

**Three Modes + Settings:**

1. **Learn** - Visual introduction to facts (no wrong answers)

2. **Practice** - Adaptive problems with hints on mistakes

3. **Progress** - Scene reveal reward system with stats

4. **Settings** - Focus table selection (bottom nav)

**Scene Reveal Reward System** (`src/components/progress/`):

**Adaptive Learning** (`src/lib/adaptive.ts`):

**Strategy Hints** (`src/lib/strategies.ts`):

Nine strategies: visual_array, skip_counting, break_apart, use_neighbor, nines_trick, fives_trick, doubles, tens_trick, ones_zeros

4. State Management

**Key Zustand Stores:**

5. Styling with Tailwind v4

This project uses CSS-first configuration (not `tailwind.config.js`):

```css

/* src/index.css */

@import "tailwindcss";

@theme {

--color-garden-500: #22c55e;

--color-warm-500: #f59e0b;

}

```

Custom colors available: `garden-*` (greens), `warm-*` (yellows), `sky-*` (blues)

6. Design Principles

When making changes, adhere to these principles:

7. Building and Deployment

Build for production:

```bash

bun run build # Build for production

bun run lint # Run ESLint

```

The app deploys to Cloudflare Pages with D1 database backend.

Common Tasks

**Adding a new fact strategy:**

1. Edit `src/lib/strategies.ts`

2. Add strategy logic to `getStrategyHint()` function

3. Update `StrategyType` type in `src/types/index.ts`

**Modifying the scene reveal:**

1. Edit `src/components/progress/ProgressScene.tsx`

2. Adjust tier thresholds or visual elements

3. Update unlock logic in `src/lib/rewards.ts`

**Adding a new UI component:**

1. Place in appropriate `src/components/` subdirectory

2. Follow mobile-first design with 48px+ tap targets

3. Use custom Tailwind theme colors from `src/index.css`

**Database schema changes:**

1. Create migration in `migrations/` directory

2. Test locally with `bun run db:migrate:local`

3. Deploy to production with `bun run db:migrate`

Constraints