Design Annotations

Design Annotations

Add, reposition, or improve dev note components next to design screens in Figma. Works with design system components or a default note template. Chains from design-organize but also works standalone.

> Validation principle: Every use_figma write step must be followed by a get_screenshot check. Do not stack writes without visual verification.

Quick Reference

| Step | What | |------|------| | 0 | Prerequisites — Figma MCP required | | 1 | Ask preferences: which screens, format, content | | 2 | Read container, classify children, find existing labels | | 3 | Version safety | | 4 | Determine note width → reposition screens/labels → place notes | | 5 | Validate and present result |

Step 0: Prerequisites

1. Figma MCP server — check if mcp__figma__use_figma tool is available. If not, tell the user to install it and restart.

1. figma-use skill — load figma:figma-use via the Skill tool before any use_figma call.

1. Figma Section gotchas — these are critical and cause silent failures:

• Page discovery: getNodeById() works cross-page — it will find nodes on ANY loaded page, giving false positives. Use figma.currentPage.findOne(n => n.id === "") instead, which only returns nodes that actually live on the current page.
• Page-level TEXT: Figma stores TEXT nodes placed inside SECTIONs as page-level children — they won't appear in section.children. Scan figma.currentPage.children for TEXT nodes whose absoluteBoundingBox falls within the section bounds. These are existing labels. Their x/y are canvas-absolute — use section.absoluteBoundingBox to convert.
• Overlapping children: SECTION nodes may silently discard children that overlap existing frames between script executions. Position new nodes to avoid overlaps.
• Stop on repeated failure: If the same operation fails twice, STOP and read back children before retrying.

Step 1: Ask Preferences

Extract fileKey and nodeId from the user's Figma URL (convert - to : in nodeId).

Detect intent from the message — "add dev notes" vs "improve copy" vs ambiguous. Then always confirm preferences before proceeding (skip only what the user already specified):

> Which screens get dev notes? > - A) All screens > - B) Let me pick (I'll list them) > > Format: > - A) Use a design system component (I'll search for it) > - B) Use a default note template > > Content: > - A) Pre-fill with AI-generated descriptions > - B) Leave empty for manual editing

For "improve copy" intent, skip format/screen questions — go straight to Step 2 → Path C.

Step 2: Read Container and Classify Children

Use a single use_figma call to find the correct page and classify all children:

1. Page discovery: Iterate all pages, switch to each, use figma.currentPage.findOne(n => n.id === "") to find the page that owns the node. Do NOT use getNodeById() — it returns nodes cross-page. Mention which page you found (e.g., "Working on page [page name]") so the user can catch wrong-page issues early.

1. Classify section children: screens (everything visible that isn't a label or note), labels (TEXT nodes), notes (INSTANCE ≤ 450px or FRAME named "Dev Note" ≤ 450px).

1. Scan page-level TEXT: Check figma.currentPage.children for TEXT nodes within the section's absoluteBoundingBox. Flag these as pageLevel: true (canvas-absolute coords).

1. Validation: If design-organize was used (expect labels) but 0 labels found — you're on the wrong page. Re-run discovery.

1. If user chose "let me pick": List screens with names and dimensions for selection.

Store one FRAME screen ID as `` for subsequent page-switch preambles.

Step 3: Version Safety

Ask the user to save a named version in Figma before proceeding. Wait for confirmation.

Step 4: Determine Width → Reposition → Place Notes

This is the core step. The order is critical — reposition BEFORE placing notes to prevent overlaps.

4a: Determine note width

• Component path: Search design system → import → list all variants, ask user which one (don't auto-pick default). Create ONE test instance, confirm dimensions. Record noteWidth.
• Default template: noteWidth = 400px.
• Improve copy (Path C): Skip to 4d.

4b: Reposition screens and labels

Widen gaps between screens to fit notes. For each screen left-to-right:

• Screens WITH notes: gap = screen.width + 50 (noteGap) + noteWidth + 200 (nextScreenGap)
• Screens WITHOUT notes: gap = screen.width + 200 (standard gap)

Move each screen's label to follow it. Page-level labels need canvas-absolute coordinates: sectionAbsBounds.x + screenRelativeX.

Verify with get_screenshot that gaps are visible.

4c: Place notes

For each selected screen, place a note at screen.x + screen.width + 50, screen.y.

Component notes: Import chosen variant, createInstance() per screen, append to container.

Default template notes: Create template frame (400px wide, auto-height, vertical layout, "Dev Note" name, Inter fonts, warm fill {1, 0.98, 0.94}), clone per screen, remove template. Must run in a single use_figma call (template reference doesn't persist).

Verify with get_screenshot.

4d: Improve existing copy (Path C)

1. Read all existing notes via use_figma — walk each note's children to extract text nodes with their IDs and content
2. Match notes to screens by x-proximity (note.x near screen.x + screen.width)
3. Screenshot each screen for visual context
4. Generate improved copy — focus on what devs need: component behavior, state, data sources, interactions
5. Present suggestions in a table for confirmation:

> | Screen | Current | Suggested | > |--------|---------|-----------| > | Dashboard | "Add notes here..." | "Main dashboard. Stats row: real-time metrics..." |

1. Bulk-update confirmed notes in one use_figma call — load each text node's exact font before changing .characters

Step 5: Validate and Present

Screenshot the section. Verify notes are positioned correctly, not overlapping, readable.

> Done. Added/updated X dev notes across Y screens. > > Want to adjust anything? > > Next step: Want me to optimize these screens for MCP? (I can invoke mcp-optimize)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shub-rajput
• Source: shub-rajput/design-superskills
• License: MIT

Install and usage instructions live in the source repository linked above.