Images
Drag an image file onto the doc or paste one from your clipboard to insert it. Standalone images with no explicit width render at most about 480px tall, based on their intrinsic dimensions, and scaled-down images are centered so smaller screenshots do not hug the left edge. Existing docs get this cap automatically; nothing needs to be rewritten. Click an image to open it in a lightbox for the full-size view. Click below an image to add or edit its caption. Drag a corner handle to resize a standalone image. Click an image to select it; press Backspace to delete the selected image. Two or more image lines with no blank line between them render side by side as one grid, with up to three equal-width cells per row before wrapping. This uses normal markdown image syntax, so the same lines stay portable and render as stacked images on GitHub.https://www.figma.com/api/mcp/asset/..., it can call upload_media with url to let the server fetch and store the image. That returns a mediaId, which the agent then passes to insert_media with the target line and optional alt text.
If the agent has raw image bytes instead, it can use the signed-URL flow: call upload_media with mimeType, PUT the bytes to the returned uploadUrl, then call insert_media with the same mediaId.
insert_media also accepts an optional displayWidth integer from 120 to 2000. It sets the rendered width in pixels for a standalone image and writes the same w URI parameter that the editor’s drag-resize handle writes, such as . displayWidth is ignored for images inside a grid, where cells are equal-width; omit it when you want the default height cap.
To build a browsable layout, call insert_media at successive afterLine values so the image lines land adjacent and form a grid. Use displayWidth when you want one standalone image at a specific size.
Mermaid diagrams
Fenced```mermaid code blocks render as live diagrams inline. They include zoom and expand controls, and their styling is theme-aware so diagrams match light and dark mode.
HTML widgets
Fenced```html-ref code blocks render as sandboxed, interactive HTML. They are useful for wireframes, dashboards, and prototypes right inside the plan.
Individual DOM nodes inside an HTML widget can be commented on directly, so reviewers can leave feedback on the exact part of a prototype or visualization they mean.
Collapse blocks
Use collapse blocks for long detail sections, like big file lists, that should default to collapsed.:::collapse opens the block. Everything between :::collapse and the bare ::: is the header region: it is always visible, editable markdown, and should usually start with a heading like ## Files — 12 files, 4 directories.
Everything between the bare ::: and :::end is the body region. It is appended below the header when expanded and hidden when collapsed.
A collapse block must close with :::end or it renders as plain text.
Agents write Mermaid diagrams, HTML widgets, and collapse blocks automatically when they are relevant, such as auto-collapsing long file lists. Ask Ref for a wireframe/diagram to discover widgets.