---
name: miro-layout
description: Use when arranging or updating many Miro board items with frames, cards, lanes, arrows, or layout DSL.
---

<!-- markdownlint-disable -->

# Miro Layout

Use Miro layout tools when the user wants a board, frame, workspace, service
blueprint, architecture map, roadmap, or any multi-item visual structure.

## Principles

- Preserve the board URL and target item URL exactly. A URL with
  `moveToWidget` or `focusWidget` scopes placement to that frame or item.
- Use `layout_get_dsl` before the first `layout_create` call in a conversation.
- Prefer `layout_create` for frames, text, shapes, lanes, cards, and large arrow
  rows.
- Use `layout_read` before targeted updates. Use `layout_update` with exact
  find-and-replace text.
- Do not create a new board unless the user explicitly asked for one or
  confirmed it.
- Keep one question per frame. Use frame titles as reading order.
- Leave generous whitespace. Miro table and diagram geometry can be harder to
  predict than shape geometry.

## Layout Workflow

1. Identify the board URL. If missing and creating a new board is not clearly
   requested, ask for the URL.
2. Identify whether the target is the whole board or a specific frame/item.
3. Read existing structure with `context_explore`, `board_list_items`, or
   `layout_read` when updating an existing board.
4. Design frames first. Choose stable frame titles and coordinates before
   adding child items.
5. Create or update in small batches. Put related items in the same frame.
6. Verify with `board_list_items` and, for critical frames, scoped
   `layout_read`.

## Spacing Defaults

- Start large top-level frames at least 600 px apart.
- Keep 80-160 px inner padding inside frames.
- Keep 120-220 px between cards in a row.
- Keep table-only and diagram-only frames separate from dense card frames.
- If text is likely to wrap, make the shape wider instead of shrinking the
  whole frame.

## When To Use Other Tools

- Use `diagram_create` only when a compact connector diagram communicates the
  workflow better than shapes.
- Use `table_create` for typed decision, verification, task, or risk tables.
- Use `doc_create` for long Markdown content that should live on the board.