173 lines
7.0 KiB
Markdown
173 lines
7.0 KiB
Markdown
# Math Tasks Generator
|
||
|
||
Printable math worksheet generator (A4 PDF) for children aged 7–9. Claude Code-driven workflow: user describes a task idea → Claude generates JSON config → creates HTML pages with Tailwind CSS → converts to PDF via Puppeteer.
|
||
|
||
**No template engine.** Claude Code generates fresh HTML pages directly from JSON task configs each time.
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
npm run build:css # Build Tailwind CSS (minified)
|
||
npm run build:css:watch # Watch mode for CSS
|
||
npm run preview # Serve HTML at localhost:3000
|
||
npm run dev # CSS watch + preview server (concurrent)
|
||
npm run pdf -- <file> # Convert HTML file to PDF
|
||
```
|
||
|
||
Generate problems from a task config:
|
||
```bash
|
||
node src/scripts/generate-problems.mjs tasks/<task>.json
|
||
```
|
||
|
||
Generate images via Banatie API:
|
||
```bash
|
||
node src/scripts/banatie.mjs --type background --prompt "forest theme" --output assets/backgrounds/forest.png
|
||
node src/scripts/banatie.mjs --type icon --prompt "golden star" --output assets/icons/stars/star1.png
|
||
```
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
src/
|
||
styles/main.css — Tailwind source with A4/print styles
|
||
templates/space-base.html — Base template (reference example, see below)
|
||
scripts/
|
||
generate-pdf.mjs — HTML → PDF via Puppeteer
|
||
generate-problems.mjs — JSON task → concrete problem list
|
||
banatie.mjs — Banatie API client for image generation
|
||
tasks/ — JSON task definition files
|
||
assets/
|
||
hero-images/ — spaceship1-6.jpeg (header hero images)
|
||
footers/ — planet1-6.jpeg (footer panorama images)
|
||
icons/pack1/ — minerals1-6 + plants1-6, 16 variants each ({name}-{row}-{col}.png)
|
||
backgrounds/ — large background images per theme (~1200x1700px)
|
||
output/
|
||
html/ — generated HTML (gitignored)
|
||
pdf/ — generated PDFs (gitignored)
|
||
css/ — built Tailwind CSS (gitignored)
|
||
```
|
||
|
||
## JSON Task Format
|
||
|
||
Each task is a JSON file in `tasks/` with this structure:
|
||
|
||
```json
|
||
{
|
||
"id": "multiply-2-3",
|
||
"title": "Умножение на 2 и 3",
|
||
"description": "Worksheet for practicing multiplication by 2 and 3",
|
||
"template": "{a} × {b} = ___",
|
||
"variables": {
|
||
"a": { "type": "range", "min": 1, "max": 10 },
|
||
"b": { "type": "set", "values": [2, 3] }
|
||
},
|
||
"problemCount": 20,
|
||
"layout": {
|
||
"columns": 2,
|
||
"problemsPerPage": 20
|
||
},
|
||
"labels": {
|
||
"title": "Умножение",
|
||
"subtitle": "Реши примеры",
|
||
"name": "Имя: _______________",
|
||
"date": "Дата: _______________"
|
||
},
|
||
"theme": {
|
||
"background": "assets/backgrounds/forest.png",
|
||
"icons": "assets/icons/stars/",
|
||
"iconReward": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### Fields
|
||
|
||
- **template** — problem template with `{variable}` placeholders
|
||
- **variables** — each variable is either `range` (min/max) or `set` (explicit values)
|
||
- **problemCount** — how many problems to generate
|
||
- **layout.columns** — 1 or 2 column layout
|
||
- **layout.problemsPerPage** — max problems per A4 page
|
||
- **labels** — all visible text (no hardcoded language)
|
||
- **theme.background** — path to background image
|
||
- **theme.icons** — path to icon directory (for collectible rewards)
|
||
- **theme.iconReward** — show an icon every N problems solved
|
||
|
||
## Space Base Template
|
||
|
||
Reference example: `src/templates/space-base.html`
|
||
|
||
This is the base visual design for all space-themed worksheets. When generating a new worksheet, use this file as the source of truth for layout, styling, and structure. **Read it first**, then produce a new HTML with these variations:
|
||
|
||
### What to vary per worksheet
|
||
|
||
1. **Hero image** — pick one from `assets/hero-images/spaceship{1-6}.jpeg`
|
||
2. **Footer image** — pick one from `assets/footers/planet{1-6}.jpeg`
|
||
3. **Hero position** — set CSS variable `--hero-direction: row` (hero left) or `row-reverse` (hero right)
|
||
4. **Problem icons** — randomly pick from `assets/icons/pack1/` (minerals and plants, any variant `{name}-{row}-{col}.png`)
|
||
5. **Problem alignment** — for each problem card, randomly assign `justify-start`, `justify-center`, or `justify-end` within its grid column. No repeating patterns — should look chaotic/scattered
|
||
6. **Title, subtitle, footer text** — set from the task description
|
||
7. **Problems** — generate from the task config (template like `{a} × {b} + {c}`, variable ranges/sets, etc.)
|
||
|
||
### Layout structure (do not change)
|
||
|
||
- Page: `w-[210mm] h-[297mm]` white container
|
||
- Footer: absolute bottom, `h-[80mm]`, with white-to-transparent fade on top
|
||
- Footer bubble: absolute `bottom-[12mm]`, pill-shaped with semi-transparent white bg
|
||
- Content area: `px-[12mm] pt-[8mm] pb-[65mm]` flex column
|
||
- Header: hero image `w-[48%]` + title block centered
|
||
- Problems: `grid grid-cols-2 gap-x-3 gap-y-[8px]` — 20 problems total
|
||
- Each problem: pill card with 44px icon + `text-[1.2rem]` expression + `w-16` answer underline
|
||
- Font: Nunito via Google Fonts
|
||
- Uses Tailwind CDN (`<script src="https://cdn.tailwindcss.com">`)
|
||
|
||
### Color palette (do not change)
|
||
|
||
| Element | Hex |
|
||
|---------|-----|
|
||
| Title text | `text-indigo-950` (#1e1b4b) |
|
||
| Subtitle | `text-indigo-400` (#6366f1) |
|
||
| Card border | `border-indigo-100` (#e0e7ff) |
|
||
| Answer underline | `border-indigo-300` (#a5b4fc) |
|
||
| Card bg gradient | `from-white to-indigo-50/40` |
|
||
| Footer bubble border | `border-indigo-200` |
|
||
|
||
## HTML Generation Guidelines
|
||
|
||
When generating HTML worksheets:
|
||
|
||
- **Always read** `src/templates/space-base.html` first and use it as the structural reference
|
||
- **Page size:** A4 = 210mm × 297mm
|
||
- **CSS:** Uses Tailwind CDN in the HTML `<script>` tag (not the compiled CSS file)
|
||
- **Page breaks:** Use `break-after: page` between pages
|
||
- **Icons:** 44×44px inline images from `assets/icons/pack1/` next to each problem
|
||
- **Fonts:** Nunito from Google Fonts via `<link>`
|
||
- **Images in PDF:** Use local file paths (not URLs). Puppeteer resolves `file://` protocol
|
||
- **Embed images** as base64 data URIs when possible for reliable PDF rendering
|
||
|
||
## Banatie API
|
||
|
||
REST API for generating images.
|
||
|
||
- **Backgrounds:** ~1200×1700px, themed illustrations (forest, space, ocean, etc.)
|
||
- **Icons:** 128×128px, transparent PNG, simple collectible items (stars, gems, animals)
|
||
|
||
Configuration is in `src/scripts/banatie.mjs`. Set the `BANATIE_API_KEY` environment variable for authentication.
|
||
|
||
## PDF Generation
|
||
|
||
Puppeteer settings for A4 worksheets:
|
||
- Format: A4
|
||
- `printBackground: true` (required for background images)
|
||
- Margins: zero (CSS handles margins)
|
||
- `preferCSSPageSize: true`
|
||
|
||
## Workflow
|
||
|
||
1. User describes the math task idea to Claude
|
||
2. Claude creates/updates a JSON config in `tasks/`
|
||
3. Claude runs `node src/scripts/generate-problems.mjs tasks/<task>.json` to get concrete problems
|
||
4. Claude generates HTML file(s) in `output/html/` using the problems and Tailwind classes
|
||
5. Run `npm run build:css` to compile CSS
|
||
6. Run `npm run pdf -- output/html/<file>.html` to create PDF
|
||
7. Preview with `npm run preview` at localhost:3000
|