> ## Documentation Index
> Fetch the complete documentation index at: https://opencanvas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# create_artboard: Add a Canvas Artboard

> Create a named artboard frame on the DesignJS spatial canvas at a specified size and position, returning the new artboard's ID and coordinates.

The `create_artboard` tool creates a new artboard — a named, bounded frame — on the DesignJS spatial canvas. Artboards are the primary way to organize multiple design screens or states on the same canvas. Each artboard has an explicit width and height, and you can place it at any X/Y position in canvas world coordinates. If you omit the position, the artboard is placed automatically to avoid overlapping existing frames.

When you're creating several artboards programmatically, use `find_placement` first to get non-overlapping coordinates, then pass those coordinates to `create_artboard`. The returned `ArtboardData` object includes the artboard's ID, which you can pass to `get_tree`, `get_screenshot`, or `get_html` to scope those tools to the new frame.

## Parameters

<ParamField path="width" type="number" required>
  The width of the artboard in pixels. Must be a positive number.
</ParamField>

<ParamField path="height" type="number" required>
  The height of the artboard in pixels. Must be a positive number.
</ParamField>

<ParamField path="name" type="string">
  A display name for the artboard shown in the editor. Defaults to `"Artboard N"` where N is the next available number.
</ParamField>

<ParamField path="x" type="number">
  The X position of the artboard in canvas world coordinates. If omitted, the canvas places the artboard automatically to the right of existing artboards with an 80px gap.
</ParamField>

<ParamField path="y" type="number">
  The Y position of the artboard in canvas world coordinates. Defaults to `0` if omitted (when `x` is also omitted, the auto-placement logic determines both X and Y).
</ParamField>

## Response

<ResponseField name="artboard" type="object" required>
  The newly created artboard's data.

  <Expandable title="ArtboardData properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the artboard. Use this with `get_tree`, `get_screenshot`, `get_html`, and `get_css` to scope those tools to this artboard.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      The display name of the artboard.
    </ResponseField>

    <ResponseField name="x" type="number" required>
      The final X position in canvas world coordinates.
    </ResponseField>

    <ResponseField name="y" type="number" required>
      The final Y position in canvas world coordinates.
    </ResponseField>

    <ResponseField name="width" type="number" required>
      The width of the artboard in pixels.
    </ResponseField>

    <ResponseField name="height" type="number" required>
      The height of the artboard in pixels.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```json request — desktop artboard with auto-placement theme={null}
  {
    "method": "tools/call",
    "params": {
      "name": "create_artboard",
      "arguments": {
        "name": "Desktop – Home",
        "width": 1440,
        "height": 900
      }
    }
  }
  ```

  ```json request — mobile artboard at explicit position theme={null}
  {
    "method": "tools/call",
    "params": {
      "name": "create_artboard",
      "arguments": {
        "name": "Mobile – Home",
        "width": 390,
        "height": 844,
        "x": 1600,
        "y": 0
      }
    }
  }
  ```
</CodeGroup>

```json response theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "{\"artboard\": {\"id\": \"artboard-003\", \"name\": \"Desktop – Home\", \"x\": 1680, \"y\": 0, \"width\": 1440, \"height\": 900}}"
    }
  ]
}
```

<Tip>
  When creating multiple artboards in sequence, call `find_placement` with the intended dimensions before each `create_artboard` call to get coordinates that don't overlap any existing frames.
</Tip>

<Note>
  Common artboard sizes: desktop (1440×900), laptop (1280×800), tablet (768×1024), mobile (390×844 for iPhone 14, 360×800 for Android). Use consistent sizes to make responsive design comparisons easier in the editor.
</Note>