# Design workflow (Penpot) You design in Penpot; the code follows the design. This folder is the hand-off point. ``` design/ baseline/ the current site captured as layers (re-generated, don't edit) tokens.json colours + fonts from src/styles/tokens.css, importable into Penpot handoff/ YOUR exports go here (one folder per change) ``` ## One-time setup 1. **Penpot**: either use the free cloud at or self-host it on Coolify (New Resource → Services → search "Penpot"). It runs in Firefox/Chromium on NixOS. 2. **Import the current site as editable boards** ```bash python3 tools/penpot/serve.py # leave running ``` In Penpot, open a new file → Plugins (`Ctrl+Alt+P`) → paste `http://localhost:4402/manifest.json` → Install → open **yoyos.sh baseline importer**, pick boards (phone row on top, desktop row below) → Import. Every text is real editable text in the site's fonts; boxes are rectangles; photos and decorative stickers are images. Each page section is its own group. Preview what will be imported first: . 3. **Import tokens**: Penpot → Tokens panel → Import → `design/tokens.json`. Use these colours/fonts when designing so they map 1:1 to the CSS. ## Every time you change the design 1. Work in Penpot. Keep board names like `home — mobile 390` / `home — desktop 1440` (phone 390 px wide, desktop 1440 px). New pages: ` — mobile 390`, etc. 2. Export the boards you changed (select board → Export → **PNG 2x** *and* **SVG**) into `design/handoff//`, e.g. `design/handoff/2026-10-new-home/home-mobile.png`. 3. Add `design/handoff//notes.md` with anything the picture can't show: hover/animation ideas, links, which parts are placeholders, what's must-match vs. vibe. 4. Push (or just drop the files into the chat) and ask: *"Implement design/handoff/2026-10-new-home"*. The SVG export carries exact positions, sizes, colours and font settings, so values are taken from the file instead of eyeballed; the PNG shows intent. ## What happens on the code side 1. The design is implemented mobile-first (phone board first, desktop as the wider layout). 2. New colours/fonts go into `src/styles/tokens.css`; `npm run design:tokens` updates `design/tokens.json` so Penpot stays in sync. 3. `npm run design:capture` re-captures the built site; its screenshots are compared against your PNGs side by side, and differences are fixed before pushing. 4. The refreshed `design/baseline/` can be re-imported into Penpot as the new starting point. ## Commands | Command | What it does | |---|---| | `npm run design:serve` | Serve the Penpot plugin + baseline on :4402 | | `npm run design:capture` | Build, start the site and capture all pages (phone + desktop) | | `npm run design:tokens` | Regenerate `design/tokens.json` from the CSS tokens |