Penpot Design Md

penpot-design-md — Extract a DESIGN.md spec from a Penpot file

1. Title + How it works

This skill turns a Penpot file into a DESIGN.md: a single, portable markdown document that lets any human or LLM reproduce the design system without opening Penpot — YAML frontmatter carrying the token maps (colors, typography, rounded, spacing, components) plus prose sections that explain how the system behaves (Overview, per-domain sections, Do's & Don'ts, Iteration Guide, Known Gaps). 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) — but this skill performs no canvas mutation at all: it only reads (tokens, library assets, sampled component styles, exported images) and writes one local markdown file on the agent's filesystem. It is multimodal by design: the aesthetic prose (frontmatter description, Overview, Do's & Don'ts) must be written after looking at real exports, not from token names alone.

2. The One Rule That Matters Most

Every value in the DESIGN.md must be traceable to something you read or saw in the file — never invented, never "typical". A hex that appears in colors: was read from a token, a library color, or a sampled shape fill. A padding in components: was read from a real component's layout. A "Don't" was observed (the file never does it), not imagined. When something cannot be extracted, it goes in Known Gaps — an honest gap beats a plausible fabrication, because downstream agents will build from this file.

3. Penpot MCP Tool Reference

Full surface: shared/penpot-mcp-tool-reference.md. The calls this skill leans on (all read-only):

Verify any unfamiliar signature with penpot_api_info before relying on it.

4. Plugin API Essentials

The gotchas that bite this skill (full list: shared/plugin-api-gotchas.md):

• #1 style arrays — read fills[0].fillColor etc.; never attempt to write (this skill doesn't mutate).
• Variant reading is safe (#12 forbids mutation only) — read variants.properties, variantComponents()[].variantProps freely to document the variant axes.
• Library color duplicates — library.local.colors can hold several entries with the same short name (default, hover) belonging to different groups; disambiguate by color.path/group before mapping to semantic names, or fall back to value-based grouping.
• Text metrics live on the shape — fontSize is a string in some builds; normalize to px numbers when emitting typography:.
• mainInstance() of a heavy component can be slow — sample components one execute_code call per batch of ~5, not all in one blast.
• Verify unfamiliar signatures with penpot_api_info before use.

5. Token-Aware Brief Contract

Before extracting, restate the request. Act as a senior design-systems documentarian: your reader is another agent that will rebuild this system from your file alone.

• Context — which Penpot file/pages, what the product is, who consumes the DESIGN.md (humans, coding agents, both).
• Objective (single) — e.g. "Produce DESIGN.md for the Pencil design system covering tokens, type, shape language, and the Button/Input/Modal component families."
• Inputs — the file's token sets + themes, library components/colors/typographies, the pages to sample, the output path for the file.
• Constraints — scope (whole system vs. named components); which theme is canonical (light/dark) and how to document the other; format is the design-md contract (see references/02-designmd-format.md) — do not invent alternative section names.
• Acceptance Criteria (quantitative) —
  • every colors: entry has a hex read from the file, and its source (token/library color/sampled fill) is noted in the body or Known Gaps;
  • every typography: entry carries fontFamily/fontSize/fontWeight/lineHeight/letterSpacing read from a typography asset or a sampled text shape;
  • components: covers the agreed component list, each with values interpolated from {colors.*}/{typography.*}/{rounded.*} (no raw hex where a mapped color exists);
  • Overview and Do's & Don'ts cite only observed behavior; ≥1 export was actually looked at before writing them;
  • Known Gaps lists every domain that could not be extracted (responsive behavior, motion, elevation, …).

6. Mandatory Workflow

Visual grounding (mandatory): this skill's variant of shared/visual-self-review.md — you cannot write the description, Overview, or Do's & Don'ts before exporting and looking at the cover / key screens. Aesthetic prose written from token names alone is fabrication.

Phase 0 — Discovery (read-only)

• Goal: inventory what the file offers before deciding the extraction plan.
• Steps:
  1. high_level_overview (once per session).
  2. execute_code: run scripts/extractDesignData.js → pages, token sets (+ themes, active state), library components/colors/typographies, counts. Cache in storage.run.inventory.
  3. Decide with the user: scope (which components to document in depth), canonical theme, output path.
• Exit criterion: an inventory + an agreed scope and output path.
• ✋ Checkpoint: show the inventory summary and the proposed DESIGN.md scope (which sections will be rich, which will land in Known Gaps).

Phase 1 — Token & asset extraction

• Goal: the raw material for the frontmatter maps.
• Steps: execute_code per group: dump color tokens (name → resolvedValue, per theme where sets differ), dimension/spacing/radius tokens, typography assets, library colors (deduped by group/path). Derive the semantic mapping (canvas, surface-*, ink-*, primary, hairline, semantic-*) from token names/tiers where they exist; from library-color groups and usage sampling where they don't (see references/03-inference.md).
• Exit criterion: draft colors:, typography:, rounded:, spacing: maps with a source note per entry.
• ✋ Checkpoint: show the draft maps + anything unmapped. Confirm semantic names before they ossify into the doc.

Phase 2 — Component sampling

• Goal: the components: map + the Components body section.
• Steps: for each in-scope component (batches of ≤5 per execute_code): resolve mainInstance(), read background/text/border/radius/padding/typography and bound tokens; capture variant axes (variants.properties, variantProps) — states become separate entries (button-primary-hover, …). Interpolate values through the Phase 1 maps.
• Exit criterion: every in-scope component has a frontmatter entry + body bullets; unresolved values are flagged.
• ✋ Checkpoint: show 2–3 sample component entries for tone/format approval before doing the full list.

Phase 3 — Visual character pass

• Goal: the honest aesthetic prose.
• Steps: export_shape the cover and 1–3 representative boards/screens. Look at them. Write: frontmatter description (one dense paragraph: dominant surfaces, accent usage, type character, shape language, rhythm), Overview (+ Key Characteristics bullets), and Do's & Don'ts (only rules the file itself demonstrates or its token structure implies).
• Exit criterion: prose grounded in what was seen; each Don't traceable to an observation ("no pill buttons anywhere", "single accent hue").
• ✋ Checkpoint: show the exports next to the drafted prose.

Phase 4 — Assemble, self-review, write

• Goal: the deliverable.
• Steps: assemble per references/02-designmd-format.md (section order fixed); run the format self-check (frontmatter parses as YAML, every {ref} resolves to a frontmatter key, no raw hex in components: where a colors: entry exists, Known Gaps non-empty unless truly complete); write the file to the agreed path.
• Exit criterion: file written; self-check clean.
• ✋ Checkpoint: present the file (or its outline + key excerpts) for final approval.

7. Critical Rules

1. Read-only on the canvas. No shape, token, or library mutation — ever. The only write is the local markdown file.
2. No invented values. Every hex/px/weight is read from the file. Unknown → Known Gaps.
3. Interpolate, don't repeat. Body prose and components: reference {colors.x}/{typography.y}/{rounded.z}; raw values appear once, in the frontmatter maps.
4. Look before you describe. No aesthetic prose before at least one export_shape has been viewed (Phase 3).
5. Themes are explicit. If the file has light/dark sets, document the canonical theme in the maps and the other as a delta subsection — never silently mix values from both.
6. Dedupe library colors by group before semantic mapping; identical short names across groups are different colors.
7. Curate, then disclose. A 100+-token file is summarized into semantic groups — say what was collapsed ("107 Global tokens → 14 semantic colors; full set names in Known Gaps") — no silent truncation.
8. One extraction step per execute_code call; component sampling in batches of ≤5.
9. Variant axes are documentation gold — record Property=Value matrices for components that have them; reading them is safe.
10. The output must lint as the format — section order and frontmatter keys exactly per references/02-designmd-format.md.

8. Domain Architecture

The DESIGN.md contract (summary — full spec in references/02-designmd-format.md):

--- (YAML frontmatter)
version, name, description        # description = one dense aesthetic paragraph
colors:      { semantic-name: "#hex", ... }          # canvas/surface-*/ink-*/primary/hairline/semantic-*
typography:  { style-name: {fontFamily,fontSize,fontWeight,lineHeight,letterSpacing}, ... }
rounded:     { xs..pill: Npx }
spacing:     { xxs..section: Npx }
components:  { component-or-state: {backgroundColor,textColor,typography,rounded,padding,...}, ... }
---
## Overview                      # prose + **Key Characteristics** bullets
## Colors                        # Brand & Accent / Surface / Text / Semantic subsections, sources cited
## Typography                    # Font Family / Hierarchy / Principles / substitutes note
## Layout                        # Spacing System / Grid & Container / Whitespace Philosophy
## Elevation & Depth             # shadows/borders ladder (or "flat by design")
## Shapes                        # Border Radius Scale + shape language
## Components                    # per component: **`name`** + purpose + property bullets with {refs}
## Do's and Don'ts               # observed rules only
## Responsive Behavior           # only if derivable from the file; else Known Gaps
## Iteration Guide               # how a future agent should edit designs with this doc
## Known Gaps                    # everything not extractable — mandatory honesty section

Run ledger keys (see §10): inventory, maps, componentEntries, exportsViewed, gaps.

9. Modes & Policies

See shared/modes-and-policies.md. This skill is suggest and stays there: it never mutates the canvas, so there is no safe-set and nothing to auto-apply. The single side effect — writing the markdown file — happens at the Phase 4 checkpoint with the path the user approved in Phase 0. Overwriting an existing DESIGN.md requires explicit confirmation (show a diff summary first).

10. State Management

See shared/state-management.md. RUN_ID slug example: designmd-2026-07-09-a. Session cache in storage.run.* (inventory, maps, componentEntries, exports viewed, gaps). This skill is read-only, so it does not write setSharedPluginData unless the user asks to persist a pointer to the generated doc (designmd.lastGenerated = path + date). Resume: re-read storage.run; if gone, re-run Phase 0 (extraction is cheap and idempotent).

11. User Checkpoints

12. Naming Conventions

See shared/naming-conventions.md. Frontmatter keys are kebab-case semantic names in the design-md idiom (ink-muted, surface-2, display-xl, button-primary-hover) — map Penpot's dot-notation tokens onto them and record the mapping (color.text.muted → ink-muted) in the Colors section so the doc stays traceable back to the file. Component entries use the component's kebab-cased name plus -hover/-pressed/-disabled/-selected state suffixes derived from variant values.

13. Anti-Rationalization Table

14. Helper Code Snippets

Inventory (Phase 0 — or use scripts/extractDesignData.js):

const lib = penpot.library.local;
return {
  pages: penpotUtils.getPages().map(p => p.name),
  sets: (lib.tokens.sets || []).map(s => ({ name: s.name, active: s.active, count: (s.tokens||[]).length })),
  themes: (lib.tokens.themes || []).map(t => ({ group: t.group, name: t.name })),
  components: (lib.components || []).length, colors: (lib.colors || []).length,
  typographies: (lib.typographies || []).map(t => t.name)
};

Dump color tokens with resolution (Phase 1):

const out = [];
for (const s of penpot.library.local.tokens.sets || []) {
  if (!s.active) continue; // canonical theme only — dump inactive sets separately as the delta
  for (const t of s.tokens || []) if (t.type === "color")
    out.push({ set: s.name, name: t.name, value: t.value, resolved: String(t.resolvedValue) });
}
return { count: out.length, tokens: out };

Sample one component's style (Phase 2):

const comp = penpot.library.local.components.find(c => c.name === "REPLACE-ME");
const root = comp.mainInstance();
const texts = penpotUtils.findShapes(s => s.type === "text", root).slice(0, 3);
return {
  name: comp.name,
  bg: root.fills && root.fills[0] ? root.fills[0].fillColor : null,
  radius: root.borderRadius ?? null,
  padding: root.flex ? [root.flex.topPadding, root.flex.rightPadding, root.flex.bottomPadding, root.flex.leftPadding] : null,
  gap: root.flex ? [root.flex.rowGap, root.flex.columnGap] : null,
  boundTokens: root.tokens || {},
  text: texts.map(t => ({ family: t.fontFamily, size: t.fontSize, weight: t.fontWeight, lh: t.lineHeight, ls: t.letterSpacing, fill: t.fills && t.fills[0] && t.fills[0].fillColor })),
  variantAxes: comp.isVariant && comp.isVariant() ? comp.variantProps : null
};

15. Reference Resources

• penpot_api_info("TokenCatalog"), ("LibraryComponent", "mainInstance"), ("Variants"), ("LibraryTypography") — verify before Phase 1/2.
• shared/penpot-mcp-tool-reference.md (tool surface), shared/plugin-api-gotchas.md (traps), shared/tokens-schema.json (tiers, Penpot token type strings).
• The format's canonical skeleton: references/04-designmd-template.md (self-contained — no external corpus needed).

16. Supporting Files

References (progressive disclosure — load when that phase runs)

Scripts (paste into an execute_code call; replace placeholders)