# Drawio Syntax Cells > > - **Type:** Skill - **Install:** `agentstack add skill-impertio-studio-draw-io-claude-skill-package-drawio-syntax-cells` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio) - **Source:** https://github.com/Impertio-Studio/Draw.io-Claude-Skill-Package/tree/main/skills/source/drawio-syntax/drawio-syntax-cells ## Install ```sh agentstack add skill-impertio-studio-draw-io-claude-skill-package-drawio-syntax-cells ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Draw.io Syntax: Cells ## Purpose This skill teaches how to create and configure every type of mxCell in Draw.io XML: vertex cells (shapes, images, containers), edge cells (connectors), UserObject/object wrappers for metadata, HTML labels, placeholder variables, groups, and container nesting. ## Critical Rules (Memorize These) 1. **ALWAYS set `vertex="1"` on shapes.** Without it, the cell is invisible. 2. **ALWAYS set `edge="1"` on connectors.** Without it, the cell renders as a shape, not a line. 3. **NEVER set both `vertex="1"` and `edge="1"` on the same cell.** 4. **NEVER omit the `parent` attribute** on any cell except `id="0"`. 5. **ALWAYS use `` wrapper** when attaching custom metadata properties. 6. **ALWAYS XML-escape HTML** in `value` attributes: `` to `>`, `&` to `&`, `"` to `"`. 7. **ALWAYS include `html=1` in style** when labels contain HTML markup. 8. **ALWAYS include `whiteSpace=wrap` in style** on vertex cells with text labels. ## Decision Tree: What Type of Cell? ``` Is this a shape, box, icon, image, or container? YES --> vertex="1" (Section 1) Does it hold child cells? YES --> Add container="1" to style (Section 5) NO --> Standard vertex Is this a line, arrow, or connector? YES --> edge="1" (Section 2) Does this cell need custom metadata properties? YES --> Wrap in (Section 3) NO --> Use plain Does the label contain HTML formatting? YES --> XML-escape the HTML, add html=1 to style (Section 4) NO --> Use plain text in value attribute ``` --- ## 1. Vertex Cells (Shapes) A vertex cell represents any shape: rectangle, circle, diamond, image, icon, or container. ### Minimal Vertex ```xml ``` ### Required Attributes for Every Vertex | Attribute | Value | Rule | |-----------|-------|------| | `id` | Unique string | ALWAYS unique across entire file | | `vertex` | `"1"` | ALWAYS set to `"1"` — NEVER omit | | `parent` | Cell ID | ALWAYS `"1"` (default layer) or a container/layer ID | | `style` | Style string | ALWAYS include `html=1;whiteSpace=wrap;` | ### Optional Vertex Attributes | Attribute | Values | Purpose | |-----------|--------|---------| | `value` | String | Display text (plain or XML-escaped HTML) | | `connectable` | `"0"` / `"1"` | `"0"` disables connections. Default: `"1"` | | `visible` | `"0"` / `"1"` | `"0"` hides cell. Default: `"1"` | | `collapsed` | `"0"` / `"1"` | `"1"` collapses a container. Default: `"0"` | ### Vertex Geometry ALWAYS include `` with `as="geometry"` as a child of the vertex mxCell: ```xml ``` | Attribute | Meaning | |-----------|---------| | `x` | Horizontal position of top-left corner (pixels from canvas origin) | | `y` | Vertical position of top-left corner (0,0 = top-left; y increases downward) | | `width` | Shape width in pixels | | `height` | Shape height in pixels | **Inside a group/container:** `x` and `y` are RELATIVE to the parent's top-left corner, NOT the canvas origin. --- ## 2. Edge Cells (Connectors) An edge cell represents a line or arrow connecting two vertices. ### Minimal Edge ```xml ``` ### Required Attributes for Every Edge | Attribute | Value | Rule | |-----------|-------|------| | `id` | Unique string | ALWAYS unique across entire file | | `edge` | `"1"` | ALWAYS set to `"1"` — NEVER omit | | `parent` | Cell ID | ALWAYS `"1"` (default layer) or a layer/container ID | ### Edge Connection Attributes | Attribute | Required | Purpose | |-----------|----------|---------| | `source` | Recommended | ID of the source vertex. MUST reference an existing vertex. | | `target` | Recommended | ID of the target vertex. MUST reference an existing vertex. | ### Decision Tree: Connected vs Floating Edge ``` Does the edge connect to existing shapes? YES --> Set source="" and target="" Do both vertices exist in the diagram? YES --> Valid connected edge NO --> INVALID — will produce broken connector NO --> Use sourcePoint/targetPoint in geometry (floating edge) ``` ### Floating Edge (No source/target) When an edge is NOT connected to any vertex, define terminal points: ```xml ``` ### Edge Geometry Edge geometry ALWAYS uses `relative="1"`: ```xml ``` For label positioning on edges: | Attribute | Range | Meaning | |-----------|-------|---------| | `x` | `-1` to `1` | Position along edge: `-1` = source, `0` = center, `1` = target | | `y` | Pixel value | Perpendicular offset from edge path | ### Edge with Label Offset ```xml ``` ### Edge with Waypoints ```xml ``` Waypoints are absolute canvas coordinates contained in ``. --- ## 3. UserObject / object Wrapper (Custom Metadata) To attach custom key-value properties to any cell, wrap the `` in an `` element. The tags `` and `` are functionally identical. ### Decision Tree: Plain mxCell vs object Wrapper ``` Does the cell need ONLY a text label? YES --> Use plain Does the cell need a tooltip, hyperlink, or custom properties? YES --> Use wrapper Does the cell use %placeholder% substitution? YES --> Use wrapper with placeholders="1" ``` ### object Wrapper Structure ```xml ``` ### Attribute Migration Rules When using `` wrapper: - `id` attribute ALWAYS moves from mxCell to `` - `label` attribute on `` replaces `value` on mxCell - Inner `` NEVER has `id` or `value` attributes - Inner `` ALWAYS retains `vertex`/`edge`, `parent` (for edges: `source`, `target`), and `style` **EXCEPTION:** The `parent` attribute stays on the inner ``, NOT on ``. ### Reserved object Attributes | Attribute | Purpose | |-----------|---------| | `id` | Unique identifier (REQUIRED) | | `label` | Display text (replaces mxCell value) | | `tooltip` | Hover text shown in the editor | | `link` | URL or internal page link (`data:page/id,`) | | `placeholders` | `"1"` to enable `%variable%` substitution | | `tags` | Comma-separated tags for search/filter | ### Custom Attributes Any additional attribute on `` becomes a custom property visible in Draw.io's Edit Data dialog (Ctrl+M): ```xml ``` ### object Wrapper for Edges Edges with metadata use the same pattern: ```xml ``` --- ## 4. HTML Labels Draw.io supports rich HTML content in cell labels when the style includes `html=1`. ### Enabling HTML Labels Two requirements MUST be met: 1. `html=1` MUST be in the style string 2. ALL HTML in the `value` attribute MUST be XML-escaped ### XML Escaping Rules | Character | Escape Sequence | Example | |-----------|----------------|---------| | `` | `>` | (see above) | | `&` | `&` | `AT&T` | | `"` | `"` | `style="color:red"` | ### HTML Label Example ```xml ``` ### Supported HTML Tags - **Text formatting:** ``, ``, ``, ``, ``, ``, `` - **Block elements:** ``, ``, `` - **Lists:** ``, ``, `` - **Tables:** ``, ``, ``, `` - **Spans:** `` with inline styles - **Font:** `` with `color`, `face`, `size` - **Links:** `` ### Inline CSS in HTML Labels Use `style` attribute on HTML elements (XML-escaped): ```xml value="<div style="text-align:left;font-size:14px;"><b>Title</b><br><span style="color:#999;">Subtitle</span></div>" ``` --- ## 5. Groups and Containers ### Container Cell A container is a vertex whose style includes `container="1"`. Child cells set their `parent` to the container's ID. ```xml ``` ### Group Cell A group uses `style="group"` and acts as an invisible bounding box: ```xml ``` ### Container vs Group Decision Tree ``` Do you need a visible box around the children? YES --> Use container=1 in style with a value/label NO --> Use style="group" (invisible bounding box) Should children move when the parent moves? YES --> Both containers and groups provide this Should the container be collapsible? YES --> Use swimlane style (container with title bar) ``` ### Collapsible Container (Swimlane) ```xml ``` When `collapsed="1"`, the cell renders at the `alternateBounds` size (160x30). When expanded, it renders at the normal size (300x200). ### Coordinate Rules for Children - Child coordinates are ALWAYS RELATIVE to the parent's top-left corner - `x="0" y="0"` inside a container means the container's own top-left - For swimlanes: account for the title bar height (typically 26-30px) --- ## 6. Placeholders (%variable% Syntax) Placeholders enable dynamic text substitution in labels and tooltips. ### Enabling Placeholders Set `placeholders="1"` on the `` wrapper: ```xml ``` Renders as: "Server: web-01 (10.0.1.10)" ### Variable Resolution Order Draw.io resolves `%placeholder%` by walking UP the containment hierarchy. First match wins: 1. Cell-level properties (attributes on ``) 2. Parent container properties 3. Ancestor containers (upward through nesting) 4. Layer-level properties 5. Root cell (id="0") properties 6. File-level variables (`vars` on ``) If no match is found, the placeholder renders as blank text. ### Predefined Placeholders | Placeholder | Value | |-------------|-------| | `%id%` | Cell ID | | `%width%` | Cell width in pixels | | `%height%` | Cell height in pixels | | `%date%` | Current date | | `%time%` | Current time | | `%timestamp%` | Full timestamp | | `%page%` | Current page name | | `%pagenumber%` | Current page number | | `%pagecount%` | Total page count | | `%filename%` | File name | ### Escaping Literal Percent Signs Use `%%` to display a literal `%`: ``` Battery: 80%% charged --> renders as "Battery: 80% charged" ``` --- ## 7. Layer Cells Layers are mxCell elements with `parent="0"`. The default layer is `id="1"`. ### Adding a Second Layer ```xml ``` Content cells reference the layer by setting `parent` to the layer's ID: ```xml ``` ### Layer Visibility ```xml ``` ### Layer Order XML document order determines stacking: earlier layers render BEHIND later layers. --- ## 8. Validation Checklist Before delivering any diagram, verify: - [ ] Every shape has `vertex="1"` - [ ] Every connector has `edge="1"` - [ ] No cell has both `vertex="1"` and `edge="1"` - [ ] Every cell (except id="0") has a valid `parent` attribute - [ ] Every edge `source`/`target` references an existing vertex ID - [ ] All HTML in `value` attributes is XML-escaped - [ ] `html=1` is present in style when labels contain HTML - [ ] `whiteSpace=wrap` is present in style for vertices with text - [ ] All cell IDs are unique across the entire file - [ ] Container children use coordinates relative to the parent - [ ] `` wrappers have `id` and `label`; inner mxCell has neither `id` nor `value` ## References - [references/methods.md](references/methods.md) — Complete attribute reference for all cell types - [references/examples.md](references/examples.md) — Working XML examples for every cell pattern - [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do, with explanations ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Impertio-Studio](https://github.com/Impertio-Studio) - **Source:** [Impertio-Studio/Draw.io-Claude-Skill-Package](https://github.com/Impertio-Studio/Draw.io-Claude-Skill-Package) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-draw-io-claude-skill-package-drawio-syntax-cells - Seller: https://agentstack.voostack.com/s/impertio-studio - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.