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, numbered pins on the UI regions, matching 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. 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.