penpot-build-from-code

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: penpot-build-from-code
description: "Translate an existing application page, view, or component code into a Penpot screen that is bound to the existing design system — mapping code styles onto semantic tokens and reusing library components instead of raw shapes. Use when the user has real code/markup and wants it reconstructed in Penpot, section by section, on-system. Triggers: 'build this in Penpot from code', 'turn this React/HTML/CSS into a Penpot screen', 'recreate this view in Penpot', 'port this page to Penpot', 'translate this component to Penpot bound to our tokens', 'code to Penpot'."
disable-model-invocation: false
version: 0.3.0
audiences: [design-engineer, product-designer]
mode-default: review
requires:
  - shared/penpot-mcp-tool-reference.md
  - shared/plugin-api-gotchas.md
  - shared/tokens-schema.json
  - shared/naming-conventions.md
  - shared/state-management.md
  - shared/modes-and-policies.md
  - shared/visual-self-review.md
  - shared/design-quality.md
  - shared/visual-effects.md
---

# Build From Code — Translate App Code into an On-System Penpot Screen

## 1. Title + How it works
This skill takes an existing application artifact — JSX/TSX, HTML, Vue/Svelte templates, CSS/Tailwind, or a styled-components tree — and reconstructs it as an **editable, system-bound** Penpot screen. Every mutation goes through `execute_code`; validate visually with `export_shape`; read structure with `penpotUtils.shapeStructure` (full tool surface: `shared/penpot-mcp-tool-reference.md`). The core move is **discover first** (Phase 0 enumerates the existing tokens and components you must map onto), then transform the code **incrementally, section by section**, mapping each CSS/style value to a semantic token and each repeated UI part to an existing library component — never hardcoding hex or off-grid spacing, never reinventing a component as a raw box.

## 2. The One Rule That Matters Most
**Never one-shot a screen, and never hardcode a value that a token already expresses.** Build the screen one section at a time (one logical `execute_code` step per call), and before you write any fill/spacing/radius/type, resolve it against the discovered token set. A code-derived `#0066FF` is not a fill — it is a lookup into the design system. If no token matches, you **propose** one and stop; you do not invent it. Translating an entire page in a single call, or pasting raw computed CSS onto shapes, is the failure mode this skill exists to prevent.

## 3. Penpot MCP Tool Reference
Full surface: `shared/penpot-mcp-tool-reference.md`. The calls this skill leans on:
- **Discovery (read-only):** `penpotUtils.tokenOverview()`, `penpot.library.local` (components, tokens), `penpotUtils.shapeStructure(shape, depth)`, `penpotUtils.findShape/findShapes`.
- **Screen scaffold:** `penpot.createBoard()`, `board.addFlexLayout()`, `penpotUtils.addFlexLayout(container, dir)`.
- **Section build:** `penpot.createRectangle/createText/createEllipse/createPath`, `component.instance()`, `container.appendChild(child)`, `child.layoutChild`.
- **Token binding:** `shape.applyToken(token, properties[])`, `token.resolvedValue`, `penpotUtils.findTokenByName`.
- **Validation:** `export_shape` (separate tool call) and a `shapeStructure` read.

## 4. Plugin API Essentials
The gotchas that bite this skill, as one-liners — full text in `shared/plugin-api-gotchas.md`:
- **#1 Immutable style arrays** — assign a brand-new `fills`/`strokes` array; never mutate `fills[0]`.
- **#2 Token application is async (~100 ms)** — apply in one `execute_code` call, verify `resolvedValue` in a **later** call.
- **#3 `resize()` forces text `growType: 'fixed'`** — set `growType = 'auto-width'`/`'auto-height'` after resizing text you want to flow.
- **#4 Flex/grid overrides child x/y** — position children by append order + gap/padding/align/justify; opt out only with `child.layoutChild.absolute = true`.
- **#5 `width`/`height` and `parentX`/`parentY` are read-only** — use `shape.resize(