Terminal
Terminal/Skill
Adds a hideable annotation layer beside a Penpot design, with a context card, numbered pins and notes for developers at handoff.
By Penpot
Works with
npx skills add penpot/penpot-ai-kit --skill penpot-document-handoffpenpot-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.
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.
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.
Gotcha numbers refer to shared/plugin-api-gotchas.md.
shapeStructure; resolve pin anchor points from
child bounds (absolute x/y/width/height). Never call resize/reparent/detach/remove on it.column-reverse, matching the reference system); compose
with append order + gaps + padding, never absolute x/y inside a card.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).growType to auto-width/auto-height after any resize() (which
forces fixed); sleep ~100 ms before reading back textBounds.resolvedValue in a LATER call.createBoard() ships fills = [{ fillColor: "#FFFFFF", fillOpacity: 1 }]. Left in place, a
structural wrapper's square white corners poke out behind the rounded card it wraps, and any board
keeping the literal white is off-system (never themes). Fill policy: note/context cards and
tooltips are genuine surfaces → bind their bg to color.annotation.surface (never a literal);
inner section boards and wrappers are structural → clear with board.fills = [].penpot.fonts.all.find(f => f.name === "Work Sans") || null with a null-guard;
findByName is a substring search. If the font is absent, keep the default and report font-fallback.group() them under one named group; hiding =
group.hidden = true. Verify group() / grouping signature with penpot_api_info before relying on it.Restate the request before mutating. Act as a senior design-systems / handoff specialist who never annotates on top of the work and never hardcodes the annotation palette.
annotation.* tokens if missing — human approves);
pins numbered contiguously and matched 1:1 to notes; everything inside the hideable group.Visual self-review (mandatory): before every ✋ checkpoint that shows visual work, run the export → look → fix loop from
shared/visual-self-review.md— export the unit you just built, inspect the image yourself against the checklist, fix visible defects (max 2 iterations), and present that same export with any remaining defects named.
Phase 0 — Discovery (read-only). high_level_overview; resolve the target design
(penpot.selection or a named board) and copy its id into storage.dh; read its structure
(scripts/locateDesign pattern, depth 2–3) to enumerate pinnable regions; inventory the annotation kit
scripts/setupAnnotationKit.js in dryRun). ✋ Checkpoint: confirm the design + whether
a kit exists or must be created.Phase 1 — Handoff brief. Collect/confirm the context-card content and the pin list (region →
observation → optional recommendation). Use references/02-handoff-brief.md / prompts/handoff-brief.md.
✋ Checkpoint: approve the brief + pin list before any drawing.
Phase 2 — Ensure the annotation kit. If the kit components + annotation.* tokens exist, reuse
them. If not, propose the minimal kit (Critique Card, Chip Note, Pointer S/L, Tooltip) + tokens
(color.annotation.accent, color.annotation.surface, color.annotation.on-accent,
color.annotation.body, font.annotation.title|body|label) per references/04-component-and-tokens.md,
and create it only after approval (scripts/setupAnnotationKit.js). ✋ Checkpoint: approve kit +
token names/values/tier.
Phase 3 — Context card. Build/instance the Critique Card, fill it from the brief, place it to the
left of the design (scripts/buildContextCard.js). ✋ Checkpoint: export_shape the card.
Phase 4 — Pins + notes (one per call). For each region: place a numbered Pointer/L pin anchored to
the region on the design, and a matching Chip Note in the right column with the same number
(scripts/placePinAndNote.js). Optionally add a Tooltip for a transient state
(scripts/addTooltipCallout.js). One annotation per execute_code call. ✋ Checkpoint:
export_shape after each (or each small batch).
Phase 5 — Wrap & audit. Group every annotation shape under one hideable group named
Hide this to quit notes; run the self-audit (scripts/finalizeHandoff.js): design untouched, pin↔note
parity, contiguous numbering, tokens bound, 3-column order. A non-empty violations fails the gate —
fix before reporting done. Report.
execute_code call. Context card, then each pin+note individually. Never
one-shot the whole layer.#1A88E0/#E4F3FF.column-reverse like the reference), not
absolute-positioned text or plain Groups.The annotation layer is three columns around the untouched design:
[ Critique Card ] [ the design (read-only) ] [ Chip Note #1 ]
#US · title ┌─────────┐ number+TITLE
State/Copy/Platform │ ① ② ③ │ ← Pointer/L pins Observation
status pill │ UI… │ on the regions Recommendation?
HMW goal └─────────┘ [ Chip Note #2 ] …
links · designers (+ Tooltip/Top|Bottom for
context transient states)
feedback wanted
feedback NOT wanted
All of it (cards + pins + tooltips) is wrapped in one group: Hide this to quit notes.
Component kit + token taxonomy: references/01-annotation-anatomy.md, references/04-component-and-tokens.md.
Default review (shared/modes-and-policies.md). Creating geometry, components, or tokens always
requires a checkpoint. Safe-set items this skill may auto-apply: adding documentation metadata
(plugin-data tags) and renaming an auto-named annotation layer it just created. Never auto-fix:
creating the kit components, creating annotation.* tokens, and (always) any change to the design being
documented. Fill policy: note/context cards are genuine surfaces → bind their bg to
color.annotation.surface; inner section boards are structural → fills = [].
Ledger under RUN_ID (shared/state-management.md), in storage.dh + an in-file breadcrumb:
phase, designBoardId, kit:{critiqueCardId,chipNoteId,pointerSId,pointerLId,tooltipId,created},
tokens:{accent,surface,...}, contextCardId, notesColumnX, groupId,
pins:[{n,regionId,pinId,noteId}], pinCounter. On resume: re-read the ledger, re-derive reality with
a structure read (the group + pins), and continue from pinCounter.
| After phase | Artifacts shown | What we ask |
|---|---|---|
| 0 discovery | design summary + pinnable regions + kit/token presence | Confirm target + kit plan? |
| 1 brief | context-card content + numbered pin list | Approve brief + pins? |
| 2 kit | proposed components + token names/values/tier (only if creating) | Approve kit + tokens? |
| 3 context card | export_shape of the card | Approve content/placement? |
| each pin+note | export_shape of the region + note | Approve / adjust? |
| 5 wrap & audit | hideable group + audit result | Approve handoff / iterate? |
shared/naming-conventions.md. Components PascalCase (Critique Card, Chip Note, Pointer,
Tooltip — keep the reference system's names if reusing). Tokens dot-notation under an annotation
set (color.annotation.accent, font.annotation.label). Layers kebab-case/semantic
(context-card, note-card, pin, annotations); the hideable group keeps the recognizable name
Hide this to quit notes. Pin labels are the integer index.
| Excuse the LLM makes | Why it's wrong | Deterministic countermeasure that halts the flow |
|---|---|---|
| "I'll just drop the note text on top of the design / recolor a layer to highlight it." | That mutates the deliverable; handoff annotations must be removable and non-destructive. | Stop. Add a sibling annotation shape in the notes column or a Pointer pin overlay; never edit an original shape. The Phase 5 audit fails if the design changed. |
"I'll create all the pins and notes in one execute_code to save calls." | One-shot output is unauditable and de-syncs pin↔note numbering. | One annotation per call; checkpoint with export_shape; advance storage.dh.pinCounter each time. |
"The accent blue is just decoration — hardcode #1A88E0." | Off-system values fail governance and won't theme/rebrand. | Bind to color.annotation.accent; if it doesn't exist, propose it (name/value/tier) for approval. |
| "This note doesn't really need a pin — it's general." | Orphan notes break the number→region reading model reviewers rely on. | Every Chip Note gets a Pointer pin on a concrete region; if it's truly global, it belongs in the context card, not a note. |
| "A plain text block is faster than instancing the Chip Note component." | Raw text drifts from the system and won't restyle with the kit. | Instance the kit component; if the kit is missing, create it once (under review) and reuse. |
| "I'll renumber notes later; order doesn't matter yet." | Gaps/dupes in numbering silently corrupt the handoff. | Keep numbering contiguous and matched at every step; the audit rejects gaps/dupes. |
| "I'll skip the hideable group; the layers are tidy enough." | Without one toggle, reviewers can't get back to the clean design. | Wrap all annotation shapes under the single Hide this to quit notes group before reporting done. |
// Phase 0 — lock the target design + enumerate pinnable regions (READ-ONLY)
const design = penpot.selection[0] || penpotUtils.findShape(s => s.name === "REPLACE-ME-board");
if (!design) return { error: "Select the design board to document, or pass its name." };
storage.dh = Object.assign(storage.dh || {}, { designBoardId: design.id });
const regions = (design.children || []).map(c => ({
id: c.id, name: c.name, type: c.type,
x: Math.round(c.x), y: Math.round(c.y), w: Math.round(c.width), h: Math.round(c.height)
}));
return { design: { id: design.id, name: design.name, x: Math.round(design.x), y: Math.round(design.y),
w: Math.round(design.width), h: Math.round(design.height) }, regionCount: regions.length, regions };
// Reference palette/typography of the annotation system (verified from the example file).
// Use these as the VALUES when proposing annotation.* tokens — do NOT paint them raw on shapes.
return {
color: { accent: "#1A88E0", surface: "#E4F3FF", onAccent: "#FFFFFF", body: "#000000" },
type: { family: "Work Sans",
label: { size: 12, weight: 500, case: "uppercase", fill: "accent" },
body: { size: 14, weight: 400, fill: "body" },
title: { size: 24, weight: 400, fill: "body" } },
card: { bg: "surface", padding: [24,12,24,12], flexDir: "column-reverse", sectionGap: 24, labelGap: 4 },
pin: { L: 40, S: 24, radius: 9999, bg: "accent", number: "onAccent" }
};
penpot_api_info('Board'), penpot_api_info('LibraryComponent'), penpot_api_info('Text'),
penpot_api_info('Context','group') — verify the grouping signature before wrapping.shared/penpot-mcp-tool-reference.md (tool surface), shared/plugin-api-gotchas.md (#11 fill
policy; async tokens; resize→growType), shared/tokens-schema.json (token type spellings).| File | Loaded when | Contents |
|---|---|---|
references/01-annotation-anatomy.md | Phases 2–4 | The reverse-engineered system: Critique Card sections, Chip Note structure, Pointer S/L, Tooltip, palette/type, the hideable group. |
references/02-handoff-brief.md | Phase 1 | How to elicit/structure the context-card content and the pin list. |
references/03-layout-placement.md | Phases 3–4 | 3-column geometry, pin anchoring math, note stacking, spacing rhythm. |
references/04-component-and-tokens.md | Phase 2 | Find-or-create the annotation component kit + the annotation.* token proposals. |
references/05-anti-rationalization.md | any phase | Extended failure-mode catalogue with countermeasures. |
references/06-error-recovery.md | on failure | Recovery for missing kit, broken numbering, accidental design edits, group/ungroup issues. |
execute_code templates)| File | Phase | Purpose |
|---|---|---|
scripts/setupAnnotationKit.js | 0/2 | Inventory the kit + tokens; in non-dryRun, create the minimal kit + propose tokens. |
scripts/buildContextCard.js | 3 | Build/instance the Critique Card and fill it from the brief. |
scripts/placePinAndNote.js | 4 | Add ONE numbered pin on a region + its matching Chip Note. |
scripts/addTooltipCallout.js | 4 | Add an optional Tooltip callout for a transient/hover state. |
scripts/finalizeHandoff.js | 5 | Wrap annotations in the hideable group and run the parity/untouched/token audit. |
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.