create_item

Create a text item: kind "label" (text that wraps at size.width, or grows on one line when no size is given) or "sticky" (a sticky note with a colored background). Labels have no background by default - pass backgroundColor for a filled text box. To put text on a shape, create the shape, then a label without background on top of it. Without textColor a label's text is dark (#1F2937) or white (#FFFFFF), whichever contrasts better with its backgroundColor, or with the canvas when it has none - pass textColor when the label sits on a shape. Label auto-size (autoSize): "height" wraps at size.width and grows down - use it for running text of unknown length; "width" is one line that grows right at a fixed size.height; "both" is one line that grows freely (size is ignored); "none" is a fixed size.width x size.height box that clips text that does not fit - the user only sees a red overflow handle when they select the label. A sticky never auto-sizes. Without autoSize a label follows size: no size - one growing line; width only - wraps and grows down; width and height - fixed box. A sticky uses size (default 212x106) and clips longer text. Colors are hex strings only - "#RRGGBB" (e.g. "#3B82F6"), or "#AARRGGBB" for alpha (alpha first). rgb()/rgba(), hsl() and named colors are rejected. Returns the new item id. The result may carry warnings: [{itemId, code, message}] for text cut off by its box (TEXT_HEIGHT_TOO_SMALL), text running into other text (TEXT_OVERLAP), text that cannot be read on what is behind it (LOW_CONTRAST), text running past the shape it starts on (OUTSIDE_PARENT_SHAPE) and text a new shape hides (TEXT_COVERED). The write happened; fix what they name before reporting the work as done.

Tool name: create_item

Parameters

Parameter	Type	Required	Default	Description
`projectId`	`string`	Yes	—	Target project (map) id.
`kind`	`enum`	Yes	—	`"label"` or `"sticky"`. Any other value is rejected.
`text`	`string`	Yes	—	Plain text, where each line break starts a new line, or formatted text. See Text formatting.
`position`	`object`	No	`{ x: 0, y: 0 }`	World-coordinate position of the item's top-left, `{ x, y }`.
`size`	`object`	No	See below	Box `{ width, height? }` in world units, min `5` per dimension. `width` is required and sets the wrap width; `height` is optional.
`fontSize`	`number`	No	Theme default	Font size in points. Must be ≥ `1`.
`fontFamily`	`string`	No	Theme default	Font family name.
`textColor`	`string`	No	See below	Text color, hex e.g. `"#FFFFFF"`.
`backgroundColor`	`string`	No	Label: none; sticky: accent color	Background color, hex. A label without it is transparent.
`horizontalTextAlignment`	`enum`	No	`"Left"`	`"Left"`, `"Center"`, or `"Right"`.
`verticalTextAlignment`	`enum`	No	`"Top"`	`"Top"`, `"Center"`, or `"Bottom"`.
`parentId`	`string`	No	Project canvas	Container id to place the item under.
`autoSize`	`enum`	No	Derived from `size`	Label only: `"height"`, `"width"`, `"both"` or `"none"` — how the box follows its text. See Sizing.

Default colors

Kind	`backgroundColor` omitted	`textColor` omitted
`label`	Transparent (`"#00000000"`)	`"#1F2937"` (dark) or `"#FFFFFF"`, whichever contrasts better with the label's `backgroundColor` — or, when it has none, with the canvas background
`sticky`	The sticky accent color	Black

The canvas-based choice cannot see a shape under the label, so pass textColor when a label sits on a shape.

Returns

{ "created": true, "itemId": "11aa22bb-...", "kind": "sticky" }

When the new item leaves a layout problem on the board, the result also carries warnings. See Layout warnings.

Example

"Add a yellow sticky note that says 'Ship v2 by Friday'."

{
  "projectId": "a1b2c3d4-...",
  "kind": "sticky",
  "text": "Ship v2 by Friday",
  "position": { "x": 300, "y": 150 },
  "backgroundColor": "#FDE047",
  "textColor": "#1F2937"
}

Sizing

A label's autoSize says how its box follows the text:

`autoSize`	Behaviour	Needs
`"height"`	Wraps at `size.width` and grows downwards — use it for running text of unknown length	`size.width`
`"width"`	One line that grows to the right, at a fixed height	`size.height`
`"both"`	One line that grows freely; `size` is ignored	—
`"none"`	Fixed `size.width` x `size.height` box. Text that does not fit is clipped — the user only sees a red overflow handle when they select the label	`size.width` and `size.height`

A mode without the size it needs is rejected with an error that names the missing axis.

Without autoSize, the mode follows from size:

Kind	`size` omitted	`size.height` omitted	`size.height` given
`label`	`"both"` — one growing line	`"height"` — wraps at `width`, grows downwards	`"none"` — fixed box, clips overflow
`sticky`	212x106, clips longer text	Wraps at `width`, height falls back to `106`	Fixed box; text beyond it is clipped

A sticky never auto-sizes: autoSize is rejected on it, and text beyond its box is clipped.

Under the hood this sets the item's isAutoSizeWidth / isAutoSizeHeight flags — an axis only honours its size when the matching flag is false. get_project reports both flags, so you can check what an item ended up with. To change the mode later, use update_item_property with autoSize. See label items for the full rules.

Example: wrap a long label

"Add the press release text as a label 400 units wide."

{
  "projectId": "a1b2c3d4-...",
  "kind": "label",
  "text": "Die Bundesbildungsministerin ...",
  "position": { "x": 0, "y": 0 },
  "size": { "width": 400 }
}

The label wraps at 400 units and grows downwards for as much text as you give it.

Example: text on a shape

"Draw a blue box with 'Build' written on it."

Create the shape with create_shape, then a label on top of it without backgroundColor:

{
  "projectId": "a1b2c3d4-...",
  "kind": "label",
  "text": "Build",
  "position": { "x": 120, "y": 140 },
  "textColor": "#FFFFFF"
}

The shape stays fully visible behind the text. New items are drawn on top of existing ones, so create the label after the shape.

Text formatting

text is plain text or uses the few HTML tags every DEON client renders:

Write	For
a line break (`\n`) or `<br>`	a new line; an empty line stays a blank line
`<p>...</p>`	one line (paragraph)
`<b>` / `<strong>`, `<i>` / `<em>`, `<u>`	bold, italic, underline
`<span style="...">`	`font-weight` (`bold`, `normal` or `100`-`900`), `font-style: italic`, `text-decoration: underline`, `color` and `background-color` (`#RRGGBB`)
`<ul>` or `<ol>` with `<li>`	a bulleted or numbered list, not nested
`<a href="https://...">`	a link (`https://`, `http://`, `mailto:`, a path starting with `/` or an anchor starting with `#`)

The whole text has one fontSize and fontFamily. font-size or font-family on a span, headings (<h1>...), <div>, <img> and any other tag or style are rejected with an error that names them, so nothing is dropped or shown as raw tags. For a heading, use a separate label with a larger fontSize.

Text counts as markup only when it closes a tag it opens (<b>...</b>) or has a <br>. A tag that is only named, as in Map<A, B> or "use a <table>", is shown as written.

The text is stored in the form get_project returns as html, and that form is accepted as well. For example

{ "kind": "label", "text": "<b>Q3 goals</b>\nShip v2\nHire two engineers" }

is stored as

<html><body><p><span style="font-weight:700">Q3 goals</span></p><p>Ship v2</p><p>Hire two engineers</p></body></html>

Layout warnings

The write always happens, but when it leaves a layout problem the result carries warnings, one for each kind of problem:

{
  "created": true,
  "itemId": "11aa22bb-...",
  "kind": "label",
  "warnings": [
    {
      "itemId": "11aa22bb-...",
      "code": "TEXT_HEIGHT_TOO_SMALL",
      "message": "The text needs about 48 units of height at fontSize 22 (1 line) but the label is 40 high, so the rest is cut off. Set autoSize \"height\" to let the label grow with its text, or size.height to 49 or more."
    }
  ]
}

Code	Means
`TEXT_HEIGHT_TOO_SMALL`	A label or sticky with a fixed height is too low for its text, and the rest is cut off. The message gives the height the text needs.
`TEXT_OVERLAP`	The text runs into the text of another label or sticky in the same container by more than 2 units. A label without a background counts only where its text is; text placed on a filled label it fits inside is on a card, not an overlap.
`LOW_CONTRAST`	The text color has less than 3:1 contrast with what is behind the text: the label's own background, else the topmost item under its centre that hides what is behind it (a filled shape, a sticky, a filled label), else the canvas. Over a picture the check is skipped.
`OUTSIDE_PARENT_SHAPE`	The text starts on a shape but runs past its edge.
`TEXT_COVERED`	A new filled shape is drawn over text created before it, and hides it (`create_shape`, `create_items`).

create_item, create_items, create_shape, update_item_property and style_item return warnings. An update reports only what its change can affect: a new text color is checked for contrast, not for an overlap that was already there. The size of text is estimated from the label's font size, padding and width, so a warning means "check this" rather than proof. Fix what the warnings name before reporting the work as done.

To restyle the item later, use style_item; to change its text or move it, use update_item_property.

Parameters​

Default colors​

Returns​

Example​

Sizing​

Example: wrap a long label​

Example: text on a shape​

Text formatting​

Layout warnings​