penpot-document-handoff

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

---
name: penpot-document-handoff
description: "Document a Penpot design for handoff with a hideable annotation layer BESIDE the design (never on top of it): a context card (goal, business rules, links, status), numbered pins on the UI, matching observation/recommendation notes, optional tooltips. Reuses or proposes an annotation component kit + tokens. NOT for auditing (penpot-audit-*) or renaming layers (penpot-rename-layers). Triggers: 'document this design', 'annotate this screen', 'prepare this for handoff', 'add observation notes', 'create a critique card', 'spec this screen for handoff'."
disable-model-invocation: false
version: 0.2.1
audiences: [product-designer, design-engineer, design-system]
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
---

# penpot-document-handoff — design → annotated handoff

## 1. Title + How it works
`penpot-document-handoff` turns a finished (or in-progress) design into a self-explaining handoff:
a **context card** to its left (the "How might we" goal, business rules, links, designer(s), status,
feedback wanted / not wanted), **numbered pins** on the UI regions, **matching observation /
recommendation note cards** to its right, and optional **tooltips** for transient states — every
annotation living in one **hideable group** so reviewers can toggle back to the clean design with one
click. It reuses an existing annotation component kit + `annotation.*` tokens when present and proposes
a minimal one (human-approved) when missing. 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 first discovers the target
design + any existing annotation component kit and tokens, then builds the annotation layer
**incrementally — one annotation per call** — strictly as a **sibling layer**, never editing the
design itself.

## 2. The One Rule That Matters Most
**Annotate beside, never on top — and one annotation per call.** The design being documented is
read-only: you add a separate, hideable annotation layer next to it and you never move, restyle, or
restructure a single shape of the original. Build the context card, then add pins+notes one at a time,
checkpointing as you go. Generating the whole annotation set in one `execute_code` call is a failure
mode.

## 3. Penpot MCP Tool Reference
Full surface: `shared/penpot-mcp-tool-reference.md`. Key calls this skill leans on:
`penpotUtils.shapeStructure` / `findShape` / `findShapes` (locate the design + kit components);
`penpot.library.local.components` + `comp.instance()` (reuse the annotation kit); `penpot.createBoard()`
/ `addFlexLayout()` (build the kit if missing); `penpot.group()` (the hideable wrapper — verify with
`penpot_api_info`); `shape.applyToken` (bind accent/surface/type); `export_shape('selection'|<id>)` at
every checkpoint.

## 4. Plugin API Essentials
Gotcha numbers refer to `shared/plugin-api-gotchas.md`.
- The design is **read-only input**. Read it with `shapeStructure`; resolve pin anchor points from
  child `bounds` (absolute x/y/width/height). Never call `resize`/reparent/`detach`/`remove` on it.
- Annotation cards are **Boards with flex** (`column-reverse`, matching the reference system); compose
  with append order + gaps + padding, never absolute x/y inside a card.
- Pins and the context card sit at **absolute** page positions (they are not inside the design's
  layout) — set `x`/`y` directly, or `layoutChild.absolute = true` if parented into a layout board
  (**#14**: absolute children use PAGE coordinates, and boards clip at their edges).
- **#3 text auto-sizing** — set `growType` to `auto-width`/`auto-height` after any `resize()` (which
  forces `fixed`); sleep ~100 ms before read