Penpot design workflow: baseline export, importer plugin, tokens
Mirror to Gitea / mirror (push) Skipped
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
This commit is contained in:
263 files changed
+1054
-1
No files matched your search
@@ -0,0 +1,58 @@
|
||||
# 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**
|
||||
```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: <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 |
|
||||
Reference in new issue
Block a user