---
name: documentation
description: This skill will help to document designs for Dev, BA, and Design purposes.
---

# Document Frame

Analyze the selected frame and produce on-canvas documentation that serves three
audiences: **Developers** (implementation specs), **Business Analysts** (content
and logic), and **Designers** (design decisions and patterns).

The output has two parts:

1. **Section panels** — individual documentation panels arranged in a horizontal
row above the frame
2. **Annotation callouts** — notes split between left and right sides of the frame based on target position, connected by lines to specific elements

## Running this with Claude and the Figma MCP

Written for Figma's built-in agent, adapted for Claude (Claude Code, Claude Desktop or claude.ai) connected to the official Figma MCP server.

- **Get the file.** If you don't have a Figma link, ask for one. The file key is the segment after `/design/`; a `node-id=1-2` parameter means node `1:2`.
- **Start a session.** Call `create_session` with the file key before any other Figma tool, and pass the returned session ID on every later call.
- **Read before writing.** `get_metadata` shows the structure and the user's current selection, `get_variable_defs` lists the variables on a node, `search_design_system` finds published components, variables and styles, and `get_screenshot` shows what's on the canvas.
- **Write with `use_figma`.** It runs Plugin API JavaScript in the file. Load the `figma-use` skill first (plus `figma-generate-library` when you create variables, styles or components) and list them in `skillNames`. Scripts use top-level `await` and `return` everything they create: nothing persists between calls, so pass node and variable IDs forward as string literals. Colors are 0–1, not 0–255. Switch pages with `await figma.setCurrentPageAsync(page)`, at most once per call; for multi-page work, run one call per page in parallel. `figma.notify()` isn't available.
- **Ask, then wait.** Wherever a step says to ask the user, ask in chat (in Claude Code, use the AskUserQuestion tool) and wait for the answer before building.
- **Clear helper fills.** `figma.createAutoLayout()` frames start with a white fill. Set `fills = []` on rows and wrappers that should be transparent, or they show up as white bars (most visibly in dark-mode previews).
- **Check the result.** After a build step, take one screenshot (`await node.screenshot()` inside `use_figma`, or `get_screenshot`) and fix only what's wrong.

## Steps

### 1. Ask which sections to include

Before generating, ask the user which sections to include. Present these options
with brief descriptions:

- **Overview** — Frame name, purpose, dimensions, and key feature summary
- **Scroll & Viewport** — Fixed vs. scrollable regions, container sizes,
overflow, scroll implementation
- **Content Inventory** — Field-by-field tables with source, required status,
state, and data source legend (for BAs)
- **Layout Spec** — Nested structure diagram with auto-layout properties,
spacing, and scroll labels (for Devs)
- **Visual Spec** — Typography table, color palette table, spacing values (for
Devs & Designers)
- **Components & Notes** — Component instances, design patterns, and
implementation gotchas (for Designers & Devs)
- **Usage Guidelines** — When to use this component, common use cases,
do's and don'ts, and accessibility considerations (for all audiences)

Offer "All sections" as a default option. Proceed with only the selected
sections.

### 1b. Gather usage context (if Usage Guidelines selected)

If the user selected Usage Guidelines, ask them the following before proceeding:

"To write accurate usage guidelines, I need a bit of context:
- What is this component's primary purpose?
- When should someone use this vs. an alternative? (e.g. accordion vs. tabs, card vs. list)
- Are there any known anti-patterns, restrictions, or accessibility requirements?"

Use their answers to populate the Usage Guidelines panel. If the user
skips or says "figure it out", infer reasonable guidelines from the
component's structure, variant properties, and naming conventions.

### 2. Inspect the selected frame

Use a read-only `use_figma` script (Plugin API) to traverse the selected frame's full layer tree; get the selected frame's ID from `get_metadata`. Collect:

- **Hierarchy**: Node names, types, nesting depth, and parent-child
relationships
- **Layout**: Auto-layout direction, spacing, padding, alignment, sizing modes
(fixed, hug, fill), constraints, and wrap behavior
- **Typography**: Font families, weights, sizes, line heights, letter spacing,
text alignment, and text content
- **Colors & Fills**: All fill colors (hex + opacity), gradients, and image
fills — note which are bound to variables or styles
- **Strokes & Effects**: Border weight, color, alignment; shadows, blurs, and
any other effects
- **Corner Radius**: Uniform or per-corner values, smoothing
- **Dimensions**: Width, height, and whether fixed or responsive
- **Component Usage**: Which nodes are instances, their source component names,
and any overridden properties
- **Variables & Styles**: Any bound variables or applied styles, with their
names and values
- **Images**: Image fills, scale modes, and aspect ratios
- **Scroll Behavior**: Identify scrollbar instances or content overflow.
Determine fixed vs. scrollable regions by comparing container dimensions to
content dimensions
- **Color Palette**: Catalog unique colors — these inform the documentation's
own styling (see step 3)

### 3. Create section panels

Each selected section becomes its own panel. Arrange all panels in a
**horizontal row above the frame**, bottom-aligned, with ~16px gaps between
panels and ~40px gap above the frame.

Use a fixed panel width of ~300px. Keep content compact — use smaller font sizes
(9–11px), abbreviate where clear, and prefer bullet lists and small tables over
paragraph text to minimize vertical height.

#### Deriving documentation colors from the design

The panels and callouts should feel like they belong alongside the frame.
**Derive the color scheme from the frame's own palette**:

- **Panel background**: Use the frame's darkest background color or a near shade
- **Panel border/dividers**: Pull from the frame's border or separator colors
- **Heading text**: Match the frame's primary text color
- **Body text**: Match the frame's secondary or muted text color
- **Accent color** (section labels, callout borders, connector lines): Use the
frame's brand or accent color (e.g., primary button, link, or brand highlight).
Use the **same accent color everywhere** — panels and callouts, left and right
- **Table headers**: Use a tinted version of the panel background

If the frame uses a light theme, adapt accordingly — panels should be visually
distinct but use colors from the same family.

#### Layout and sizing rules

Use auto-layout for every frame. **All frames must use "hug contents" sizing
(primaryAxisSizingMode = 'AUTO') for their height.** This includes:

- Each panel
- Section header containers
- Table rows
- Any wrapper frames

When creating auto-layout frames, call `resize(width, anyHeight)` BEFORE setting
`primaryAxisSizingMode = 'AUTO'` to avoid overriding the auto behavior.

#### Section content guidelines

**Overview**: Frame name (large, bold), one-sentence summary, dimensions, then a
short bullet list of key features. Keep it scannable — no paragraphs.

**Scroll & Viewport**: Two sub-sections — "Fixed Regions" as a bullet list and
"Scrollable Region" as compact key-value pairs (visible size, content size,
overflow, implementation). End with scroll content order as bullets.

**Content Inventory**: Field tables with columns for name, source, required, and
state. Use abbreviated source names (e.g., "Legacy" not "From the legacy system"). Include
a compact data source legend and brief address notes.

**Layout Spec**: ASCII tree structure with [FIXED] / [SCROLL] labels. Key
properties as bullets (fill, radius, padding, gaps). Navigation details as
bullets.

**Visual Spec**: Typography and color palette as compact tables. Spacing as
short bullets with inline separators (e.g., "Section: 24px • Row: 16px").

**Components & Notes**: Component list as bullets with variant info. Patterns as
bullets. Implementation notes as bullets — no headers needed, just direct
callouts.

**Usage Guidelines**: Three sub-sections — "When to Use" as a bullet list of
ideal scenarios (3–5 bullets), "When NOT to Use" as a bullet list of
anti-patterns or better alternatives (3–5 bullets), and "Accessibility" as
compact notes on keyboard interaction, ARIA roles, and screen reader behavior.
Infer accessibility notes from the component structure (e.g. expandable content →
aria-expanded, checkbox → aria-checked, togglable list → role="group"). If the
user provided context in step 1b, use it verbatim for the use/don't-use bullets.
If not, infer reasonable guidelines from component naming, variants, and structure.

### 4. Add annotation callouts — split left and right

Identify elements that benefit from direct annotation:

- **Interactive elements**: Buttons, CTAs — what they do
- **Dynamic content**: Data-populated fields — source or field name
- **Navigation**: Where elements lead
- **States / conditions**: Show/hide logic, toggles
- **Fixed vs scroll**: Which regions are static
- **Non-obvious patterns**: Anything easily misinterpreted

#### Splitting callouts left vs. right

Calculate the **horizontal center** of the frame (`frameX + frameWidth / 2`).
For each target element, find its center X:

- Target center in **left half** → callout on the **left** (20px gap from frame's left edge, callout extends leftward)
- Target center in **right half** → callout on the **right** (20px gap from frame's right edge, callout extends rightward)

Use the **same accent color** for all callouts on both sides.

#### Positioning and sizing

1. **Use hug sizing.** Call `resize(width, anyHeight)` first, then
`primaryAxisSizingMode = 'AUTO'`, `counterAxisSizingMode = 'FIXED'`.

2. **Sort callouts by target Y to prevent line crossings.** For each side
(left and right), collect all callout–target pairs and sort them by the
target element's vertical center Y, top to bottom. Assign callout positions
in that same sorted order, so the topmost callout points to the topmost
target, the next callout points to the next target, and so on. This
guarantees connector lines never intersect — both callout Y and target Y
increase monotonically.

3. **Place each callout near its target.** The ideal callout Y aligns with
its target's vertical center. If that would overlap the previous callout,
push it down so there is at least a **12px gap** below the previous
callout's bottom edge. Never push a callout *above* its ideal Y to fill
a gap — only push down.

4. Style: dark background, accent border, bold label (10px), muted
description (10px).

5. **Connector lines**: Dashed stroke (4,3 pattern) at ~35% opacity from
callout edge to target edge. Small filled dot at target end. Left callouts
connect right-edge → target left-edge. Right callouts connect left-edge →
target right-edge.

Group all callouts and lines as "Annotations".

### 5. Final organization

Group all panels and annotations inside a top-level group named "Documentation —
[Frame Name]".