Terminal
Terminal/Skill
Compares a Penpot selection with its code component or Storybook story and reports drift in tokens, spacing, type and states.
By Penpot
Works with
npx skills add penpot/penpot-ai-kit --skill penpot-design-to-code-reviewThis 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.
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.
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 |
Verify any unfamiliar signature with penpot_api_info (e.g. penpot_api_info("Page", "generateMarkup"), penpot_api_info("Shape", "tokens")) before relying on it.
Gotcha numbers refer to shared/plugin-api-gotchas.md. What bites this skill:
generateMarkup / generateStyle take an array of shapes, not a single shape, and accept an opts object. Confirm the exact opts keys with penpot_api_info("Penpot", "generateMarkup") / ("Penpot", "generateStyle") before passing options — guessing option names silently produces default output and you will wrongly conclude "no drift". Pass penpot.selection (already an array) directly.shape.fills[0].fillColor); never attempt to "fix" a fill here — this skill does not mutate.width/height/parentX/parentY are read-only — read geometry for the diff; no resize()/setParentXY() here.shape.tokens is the authoritative map of which design tokens are bound to which properties. Prefer it over guessing tokens from raw hex. A raw value with no bound token is itself a drift finding ("design uses a hardcoded value, not a token").generateStyle emits the design's notion of CSS — it does not know your code's class names or variables. Treat its output as the design's intent, then normalize both sides (see references/04) before diffing. Do not string-compare raw CSS.generateMarkup/generateStyle return something unexpected, the first hypothesis is a wrong opts key or a non-array argument — re-check with penpot_api_info, not a retry with a different guess.Before extracting anything, restate the request as a contract. Act as a senior design-engineer who treats the design file as the spec of record and never accepts a hardcoded value where a token exists.
<Button variant=primary size=md> in src/Button.tsx matches the Penpot selection, including hover/disabled states." Not "review the design."tokenOverview()), and which tier semantic tokens should resolve to.match / drift / code-only / design-only;high_level_overview (once per session).execute_code: resolve penpot.selection; if empty, stop and ask the user to select the component/board. Return ids, names, types, count.execute_code: penpotUtils.shapeStructure(sel[0], 4) for each top-level selected shape — capture the tree (names, types, nesting).execute_code: penpotUtils.tokenOverview() — capture token sets, names, resolved values.scripts/extractMarkupStyle.js — one execute_code call that runs penpot.generateMarkup(sel, opts), penpot.generateStyle(sel, opts), walks shape.tokens for each node, and returns { markup, style, perNode:[{id,name,type,tokens,rawFills,rawSpacing,radius,typography}] }.scripts/exportForCompare.js to gather the shape id, bounds, and metadata; then call the export_shape MCP tool with 'selection' (or the captured id), format: png. For multi-state components, export each state board separately. Ask the engineer for a screenshot of the rendered code/story (or capture it via a browser MCP if available).references/02.designNode → codeElement, designToken → codeVar, designState → codeState. If the code is a Storybook story, derive states from the story's args/controls (see references/03). If no code source: map design tokens to the design-system token set only and skip the code column (graceful degradation).references/04, assemble with scripts/generateDriftReport.js (structured output), classify each finding (match/drift/code-only/design-only), assign severity, and suggest a reconciliation for each non-match. Cite the WCAG number for any contrast-impacting color drift.references/04.Minor design-hygiene drift ("value not tokenized").shape.tokens first; only fall back to matching raw hex against tokenOverview() when no token is bound.execute_code per logical step, sequential, with a checkpoint between phases. Never batch extraction + mapping + diff.generateMarkup/generateStyle opts with penpot_api_info before passing options.The DRIFT report schema (what generateDriftReport.js returns and what you render):
{
runId, scope, codeSource: "file" | "storybook" | "none",
authoritative: { visual: "design", behavior: "code", ... },
summary: { match, drift, codeOnly, designOnly, critical, major, minor },
findings: [
{
id, // stable, e.g. "drift-color-01"
dimension: "color" | "spacing" | "typography" | "radius" | "structure" | "state",
designNode, codeElement, // either may be null
designValue, codeValue, // normalized
token, // bound design token name or null
status: "match" | "drift" | "design-only" | "code-only",
delta, // px delta, hex delta, contrast delta, etc.
grid4px, // boolean | null (spacing only)
wcag, // criterion string if contrast-impacting, else null
severity: "Critical" | "Major" | "Minor",
reconciliation // concrete, one-line suggested fix + which side to change
}
],
stateMatrix: { design: [...], code: [...], cells: [{ state, design: bool, code: bool }] }
}
This shape is formalized in shared/report-schemas/drift-report.schema.json; include the derived top-level drift count (= summary.drift + summary.designOnly + summary.codeOnly), which the code-to-penpot-sync workflow branches on.
Severity rubric:
| Severity | Definition |
|---|---|
| Critical | Functional/accessibility-affecting parity break: a state exists in design but not code (or vice versa) for an interactive element; a color drift drops contrast below WCAG 1.4.3 AA (4.5:1 / 3:1). |
| Major | Visible visual mismatch users will notice: wrong semantic token bound, spacing off by ≥ 8px, type size/weight mismatch, missing structural element (icon, label). |
| Minor | Hygiene / sub-perceptual: value not tokenized though it matches, ≤ 4px spacing delta, ordering/naming differences, optional decorative drift. |
Dimensions diffed: token usage (which token, bound vs hardcoded), structure (node tree vs DOM tree), spacing (padding/gap/margin on the 4px grid), typography (family/size/weight/line-height/letter-spacing), radius/border, and state coverage.
See shared/modes-and-policies.md. This skill is suggest by default and stays there — it is an audit. It auto-applies nothing to the canvas. There is no safe-set for this skill because it performs no mutations; the "output" is the report. If the user asks to fix drift, the skill explicitly hands off: token swaps → penpot-foundations (apply-with-review), layer naming → penpot-rename-layers, structural/geometry changes → penpot-build-from-code. Each reconciliation is presented as a proposal with the source-of-truth side named; nothing is changed without that downstream skill's checkpoint.
See shared/state-management.md. RUN_ID slug example: d2c-2026-06-05-a. Ledger keys written via storage (this skill is read-only on the canvas, so it does not write setSharedPluginData unless the user opts into persisting the report):
storage.run.scope — resolved selection ids/names.storage.run.tokens — cached tokenOverview() result.storage.run.extracted — { markup, style, perNode } from Phase 1.storage.run.mapping — the design↔code mapping table from Phase 3.storage.run.report — the final DRIFT report object.Resume: re-read storage.run; if absent (new session), re-run Phase 0 discovery and re-derive from shapeStructure + tokenOverview rather than trusting a stale report. Optionally mirror the report to setSharedPluginData(NS, "${RUN_ID}.driftReport", JSON.stringify(report)) only if the user wants it persisted in-file for handoff.
| After phase | Artifacts shown | What we ask |
|---|---|---|
| 0 Discovery | Structure summary, token inventory, identified code source | "Confirm scope + which side is authoritative for which dimension." |
| 1 Extract | Trimmed markup + style, per-node token map | "Does this match what you expect the design to declare?" |
| 2 Visual | export_shape PNG(s) paired with code render(s) | "Flag any obvious visual deltas to prioritize." |
| 3 Mapping | design↔code mapping table | "Correct any mis-mapped node/token/state." |
| 4 Report | Full DRIFT report (summary + findings + state matrix) | "Approve. Want reconciliation handed off to a write skill?" |
See shared/naming-conventions.md. This skill reads names; it relies on them being semantic (button, label, icon, h1–h6) to map design nodes to DOM elements. Auto-generated names (Rectangle 12, Board) degrade mapping quality — if the selection is full of them, recommend running penpot-rename-layers first and note reduced structural-diff confidence in the report. Tokens are matched against the dot-notation taxonomy in shared/tokens-schema.json; token type strings are the exact Penpot spellings (color, spacing, borderRadius, fontSizes, etc.). Code variables (CSS custom props, JS theme keys) are normalized to that dot-notation before mapping (e.g. --color-action-primary-bg ↔ color.action.primary.bg).
| Excuse the LLM makes | Why it's wrong | Deterministic countermeasure |
|---|---|---|
| "The CSS strings differ, so it's drift." | generateStyle emits 16px, code emits 1rem; #FFF vs #ffffff; shorthand vs longhand. Raw-string diff yields garbage findings. | Normalize both sides first (units→px, colors→lowercase 6-digit hex, expand shorthand, sort props). Diff the normalized maps only. |
| "Hex matches the code, so this property passes." | A matching hex with no bound token still breaks theming and governance — it silently won't switch in dark mode. | Read shape.tokens. If no token is bound, emit a Minor "value not tokenized" finding even when the hex matches. |
| "No Storybook/code was given, so I can't review." | The skill is required to degrade gracefully. | Switch to design-system-token mode: diff the selection against tokenOverview(), mark codeSource: "none" in the report header, and report only design-side findings. |
| "generateStyle came back nearly empty — design has barely any styling." | Far more likely you passed a single shape instead of the array, or a wrong opts key. | Re-check: pass penpot.selection (an array); verify opts with penpot_api_info. Re-extract before concluding "no drift." |
| "I'll just fix the token mismatch in Penpot while I'm here." | This is a suggest-mode read-only skill; mutating breaks the contract and skips the downstream checkpoint. | Do not mutate. Emit the reconciliation as a proposal and hand off to penpot-foundations/penpot-build-from-code. |
| "Spacing is 18px in both, so it matches — pass." | 18 is off the 4px grid; matching code does not make it correct. | Flag any non-multiple-of-4 spacing as a finding (grid4px:false) regardless of code agreement; suggest the nearest grid token. |
Resolve and summarize the selection (Phase 0):
const sel = penpot.selection || [];
return sel.length === 0
? { empty: true, hint: "Select the component/board to review, then re-run." }
: { count: sel.length, items: sel.map(s => ({ id: s.id, name: s.name, type: s.type })) };
Read which tokens are bound on a node vs raw values (Phase 1):
const s = penpotUtils.findShapeById("REPLACE-ME-shape-id");
const tokens = s.tokens ? Object.fromEntries(Object.entries(s.tokens)) : {};
const fill = Array.isArray(s.fills) && s.fills[0] ? s.fills[0].fillColor : null;
return { id: s.id, name: s.name, boundTokens: tokens, rawFillColor: fill, radius: s.borderRadius ?? null };
Match a raw hex to an existing token when nothing is bound (Phase 4 fallback):
const overview = penpotUtils.tokenOverview();
const target = "REPLACE-ME-#0066ff".toLowerCase();
// scan resolved color tokens for an exact value match
const hit = (overview.tokens || []).find(t =>
t.type === "color" && String(t.resolvedValue).toLowerCase() === target);
return { rawValue: target, suggestedToken: hit ? hit.name : null };
penpot_api_info("Penpot", "generateMarkup") and ("Penpot", "generateStyle") — confirm opts keys before Phase 1.penpot_api_info("Shape", "tokens") — confirm the bound-token map shape.penpot_api_info("Page", "shapeStructure") / penpotUtils — structure read.shared/penpot-mcp-tool-reference.md — the tool surface and globals.shared/plugin-api-gotchas.md — immutable arrays, async tokens, read-only geometry.shared/tokens-schema.json — token type strings, tiers, 4px grid rule.| File | Read during | Covers |
|---|---|---|
references/01-extract-markup-style.md | Phase 1 | generateMarkup/generateStyle usage, opts, reading shape.tokens and raw values, building the per-node map |
references/02-mapping-to-source.md | Phase 3 | Parsing the supplied component code, mapping design nodes→DOM, tokens→CSS vars/theme keys, states→props/classes |
references/03-storybook-compare.md | Phase 3 (Storybook case) | Deriving states from story args/controls, capturing rendered DOM+CSS, graceful degradation when only a URL is given |
references/04-drift-report.md | Phase 4 | Normalization rules, the diff algorithm, severity rubric, report rendering, reconciliation phrasing |
execute_code call; replace placeholders)| Script | Use for |
|---|---|
scripts/extractMarkupStyle.js | Phase 1 — generateMarkup + generateStyle + per-node token/raw-value map for the selection |
scripts/exportForCompare.js | Phase 2 — gather shape id(s), bounds, and metadata so the caller can invoke the export_shape MCP tool |
scripts/generateDriftReport.js | Phase 4 — assemble the structured DRIFT report from extracted design data + the mapped code data |
Doctrine paths. shared/… and policies/… resolve inside this bundle in native installs (vendored by the installer); in a Claude Code plugin install they live at the plugin root — ${CLAUDE_PLUGIN_ROOT}/shared/…, two directories up from this file.