penpot-design-to-code-review

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

---
name: penpot-design-to-code-review
description: "Review a Penpot design against its implemented code (a source component or Storybook story) and emit a structured DRIFT report. Use when an engineer needs to confirm the build matches the design: extract HTML/CSS from a selection, map its tokens/structure/states to the code component, diff them, and list what each side is missing with severity and a reconciliation. Degrades gracefully to a design-system-token check when no code source is supplied. Triggers: 'design to code review', 'does my code match the design', 'design code parity', 'compare Penpot to my component', 'check this against Storybook', 'extract HTML/CSS from this selection', 'find design drift', 'design implementation diff'."
disable-model-invocation: false
version: 0.2.1
audiences: [design-engineer]
mode-default: suggest
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
---

# penpot-design-to-code-review — Close the design↔code bridge in the READ direction

## 1. Title + How it works
This skill reads a Penpot selection and compares it to the engineer's implemented code, then reports the drift. 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`). It reads tokens with `penpotUtils.tokenOverview`, extracts the design's HTML/CSS with `penpot.generateMarkup(shapes, opts)` and `penpot.generateStyle(shapes, opts)` (both invoked **through** `execute_code`), and produces a visual for side-by-side comparison with the separate `export_shape` tool. This skill is **read-only on the canvas** by default (`mode: suggest`) — it never mutates the design; it emits a report and, only on explicit request, proposes reconciliation steps. The code side (a React/Vue/etc. component file, or a rendered Storybook story / its DOM+CSS) is **supplied by the user or by another MCP** (filesystem, Storybook, a browser tool). If no code source is available, the skill degrades gracefully and compares the selection against the design-system tokens instead.

---

## 2. The One Rule That Matters Most

**Never one-shot a review, and never mutate during one.** Extract → normalize → map → diff → report, one logical `execute_code` call per step, with a read or `export_shape` between phases. A drift report that was assembled in a single blast is unverifiable and almost always wrong about token names. This is a `suggest`-mode skill: the canvas is not touched. The only thing you produce is a structured DRIFT report; reconciliation edits, if requested, are handed off to a write-capable skill (`penpot-foundations` for token work, `penpot-rename-layers`, or `penpot-build-from-code` for structural rebuilds) under their own checkpoints.

---

## 3. Penpot MCP Tool Reference

Full surface: see `shared/penpot-mcp-tool-reference.md`. The calls this skill leans on:

| Need | Call (inside `execute_code` unless noted) |
|------|-------------------------------------------|
| Resolve the selection | `penpot.selection` (array of shapes) |
| Read the object tree of the selection | `penpotUtils.shapeStructure(shape, maxDepth)` |
| Read active tokens (names → resolved values) | `penpotUtils.tokenOverview()` |
| Find a token referenced by a raw value | `penpotUtils.findTokensByName(name)` / `findTokenByName(name)` |
| Generate the design's HTML | `penpot.generateMarkup(shapes, opts)` |
| Generate the design's CSS | `penpot.generateStyle(shapes, opts)` |
| Inspect a shape's bound tokens | `shape.tokens` (map of property → token) |
| Inspect raw style values | `shape.fills`, `shape.strokes`, `shape.shadows`, `shape.borderRadius`, geometry via `shape.width`/`height`/`bounds` |
| Produce a comparison image | `export_shape` (**separate MCP tool**, not JS) — one call per state board