Files
yoyos.sh/design
Johan Sandoval bf0d1efa2c
Mirror to Gitea / mirror (push) Skipped
Penpot design workflow: baseline export, importer plugin, tokens
- 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
2026-10-08 19:40:41 +00:00
..

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 https://design.penpot.app 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
    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: http://localhost:4402/preview.html.
  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: <page> — mobile 390, etc.
  2. 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.
  3. Add design/handoff/<short-name>/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