penpot-design-md

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-md
description: "Extract a DESIGN.md design-documentation file from a Penpot file: a portable markdown spec (YAML frontmatter with colors/typography/rounded/spacing/components token maps + prose sections: Overview, Colors, Typography, Layout, Shapes, Components, Do's & Don'ts, Iteration Guide, Known Gaps) in the design-md format, grounded in the file's real tokens, library assets, and sampled component styles — never invented. Read-only on the canvas; writes one local markdown file. Triggers: 'generate DESIGN.md', 'create a design.md', 'document the design system as markdown', 'export design guidelines', 'extract design documentation', 'design system spec file', 'make a style guide file from this design'."
disable-model-invocation: false
version: 0.2.1
audiences: [design-system, design-engineer, product-designer]
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
  - shared/visual-self-review.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):

| Need | Call (inside `execute_code` unless noted) |
|------|-------------------------------------------|
| Pages inventory | `penpotUtils.getPages()`, `penpotUtils.getPageByName(name)` |
| Token sets, themes, tokens | `penpot.library.local.tokens` → `sets[]`, `themes[]`, `set.tokens[]` (`name`, `type`, `value`, `resolvedValue`) |
| Library assets | `penpot.library.local` → `components[]`, `colors[]`, `typographies[]` |
| Component style sampling | `component.mainInstance()` then walk children: `fills`, `strokes`, `borderRadius*`, `flex` (padding/gap), text `fontFamily/fontSize/fontWeight/lineHeight/letterSpacing`, `shape.tokens` |
| Structure of a page/board | `penpotUtils.shapeStructure(shape, depth)` |
| Visual grounding | `export_shape` (**separate MCP tool**) on the cover, key component boards, and 1–2 representative screens |

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 attem