7.0 KiB

Raw Blame History

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

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:

node src/scripts/generate-problems.mjs tasks/<task>.json

Generate images via Banatie API:

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:

{
  "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

Hero image — pick one from assets/hero-images/spaceship{1-6}.jpeg
Footer image — pick one from assets/footers/planet{1-6}.jpeg
Hero position — set CSS variable --hero-direction: row (hero left) or row-reverse (hero right)
Problem icons — randomly pick from assets/icons/pack1/ (minerals and plants, any variant {name}-{row}-{col}.png)
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
Title, subtitle, footer text — set from the task description
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

User describes the math task idea to Claude
Claude creates/updates a JSON config in tasks/
Claude runs node src/scripts/generate-problems.mjs tasks/<task>.json to get concrete problems
Claude generates HTML file(s) in output/html/ using the problems and Tailwind classes
Run npm run build:css to compile CSS
Run npm run pdf -- output/html/<file>.html to create PDF
Preview with npm run preview at localhost:3000

7.0 KiB Raw Blame History Unescape Escape