Mirror to Gitea / mirror (push) Skipped
- tools/penpot/capture.mjs captures every page at 390 and 1440 px as editable layers (text, boxes, images) grouped by section - tools/penpot/plugin: Penpot plugin that rebuilds the captures as native boards; serve.py hosts it locally; preview.html shows the result - tools/penpot/tokens.mjs exports colours and fonts as design tokens - design/README.md documents the design -> hand-off -> code loop
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
- Penpot: either use the free cloud at https://design.penpot.app or self-host it on Coolify (New Resource → Services → search "Penpot"). It runs in Firefox/Chromium on NixOS.
- Import the current site as editable boards
In Penpot, open a new file → Plugins (
python3 tools/penpot/serve.py # leave runningCtrl+Alt+P) → pastehttp://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: http://localhost:4402/preview.html. - 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
- Work in Penpot. Keep board names like
home — mobile 390/home — desktop 1440(phone 390 px wide, desktop 1440 px). New pages:<page> — mobile 390, etc. - Export the boards you changed (select board → Export → PNG 2x and SVG) into
design/handoff/<short-name>/, e.g.design/handoff/2026-10-new-home/home-mobile.png. - Add
design/handoff/<short-name>/notes.mdwith anything the picture can't show: hover/animation ideas, links, which parts are placeholders, what's must-match vs. vibe. - 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
- The design is implemented mobile-first (phone board first, desktop as the wider layout).
- New colours/fonts go into
src/styles/tokens.css;npm run design:tokensupdatesdesign/tokens.jsonso Penpot stays in sync. npm run design:capturere-captures the built site; its screenshots are compared against your PNGs side by side, and differences are fixed before pushing.- 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 |