Dobble / Spot-It Deck Generator

Browser-only React + TypeScript app that builds mathematically valid Dobble/Spot-It decks (finite projective planes of prime order). Upload your own PNG symbols, generate random layouts, tweak placements by dragging on the preview canvas, then export PNGs, a PDF, or JSON metadata.

Example symbols for quick tries live in ./examples (enough for order 2 or 3).

Prerequisites

• Node.js 18+ and npm (or pnpm/yarn if you prefer)
• A modern browser

Quick install & run

# Linux / macOS (npm)
npm install
npm run dev
# open the shown localhost URL

# Windows (PowerShell, npm)
npm install
npm run dev
# open the shown localhost URL

If you want a one-liner helper, use the install scripts below.

Linux/macOS helper script

./install.sh

This installs dependencies and starts the dev server.

Windows helper script (PowerShell)

.\install.bat

This installs dependencies and starts the dev server.

Step-by-step: Linux

1. Install Node.js 18+ (via your package manager or https://nodejs.org/).
2. Clone the repo and cd into it.
3. npm install
4. npm run dev
5. Open the printed localhost URL in your browser.

Step-by-step: Windows

1. Install Node.js 18+ from https://nodejs.org/.
2. Open PowerShell or Command Prompt.
3. Navigate to the repo folder.
4. npm install
5. npm run dev
6. Open the printed localhost URL in your browser.

Usage guide

1. Pick order q (2, 3, 5, 7, or 11). Derived counts are shown.
2. Upload images: at least q^2 + q + 1 PNGs. Extras are ignored for now. Example assets: ./examples (enough for order 2 or 3).
3. Layout settings: adjust card size, scales, margins, overlap, circle/square, border, optional seed.
4. Generate layouts: creates a randomized layout per card (centered distribution to reduce lopsided cards).
5. Preview: scrub through cards; drag symbols directly on the canvas to fine-tune placements; regenerate one or all cards if desired.
6. Export:
   • PNGs ZIP (one file per card)
   • PDF (1-per-page or 2×2 grid toggle)
   • JSON metadata (symbols + placements)

Notes:

• Changing the order resets layouts and requires enough images for the new size.
• Layout generation enforces the mathematical property: each pair of cards shares exactly one symbol.
• Drag edits persist in exports.

Scripts

• npm run dev – start dev server
• npm run build – production build
• npm run preview – preview production build locally
• npm run typecheck – TypeScript project check