`, `` — block/inline containers - `` — font attributes (face, size, color) - ``, ``, `

`, `	` — tables - ` `, ` `, ` ` — lists - ` ` — horizontal rule - `` — inline images (with src attribute) - `` — links (href attribute) - `_{`, `^{` — subscript/superscript ### HTML in Attributes HTML in the `value` attribute must be XML-escaped: - `<` → `<` - `>` → `>` - `&` → `&` - `"` → `"` Example: ```xml ``` ### Common HTML Patterns Bold title with description: ``` <b>Title</b><br>Description text ``` UML class box (within table container): ``` <p style="margin:0px;margin-top:4px;text-align:center;"><b>ClassName</b></p> <hr size="1"/> <p style="margin:0px;margin-left:4px;">+ field: Type</p> <hr size="1"/> <p style="margin:0px;margin-left:4px;">+ method(): ReturnType</p> ``` Colored text: ``` <font color="#FF0000">Red text</font> ``` --- ## 10. Layers Layers are additional mxCell elements with `parent="0"`: ```xml ``` To hide a layer: add `visible="0"` to the layer cell. --- ## 11. Groups and Containers A group/container is a vertex that other cells reference as their parent: ```xml ``` Key points: - Child coordinates are relative to the parent container - Use `style="group;"` for invisible containers - Use `style="swimlane;startSize=30;"` for containers with a visible header - Add `container=1;` to any style to make it act as a container - `collapsible=0;` prevents the collapse/expand button ### Collapsible Containers and Alternate Bounds When a container (e.g. swimlane) is collapsible, draw.io stores alternate bounds in an `mxRectangle` child element inside `mxGeometry`. When the container is collapsed/expanded, the geometry swaps between the normal and alternate bounds: ```xml ``` The `alternateBounds` typically has the same x/y but a smaller height (just the header). AI generators generally do not need to produce `mxRectangle` elements — draw.io adds them automatically when the user collapses a container. --- ## 12. Edge Geometry and Labels ### Basic Connected Edge ```xml ``` ### Edge with Waypoints ```xml ``` ### Edge with Label Edge labels are usually encoded in the edge cell's `value`. The label position is controlled by the geometry: ```xml ``` - `x` on geometry: position along edge (-1 to 1, where 0 = center, -1 = near source, 1 = near target) - `y` on geometry: perpendicular offset in pixels ### Unconnected Edge (Floating) ```xml ``` --- ## 13. Complete Examples ### Example 1: Simple Flowchart ```xml ``` ### Example 2: UML Class Diagram ```xml ``` ### Example 3: Network Diagram with Groups ```xml ``` ### Example 4: Custom Metadata with UserObject ```xml ``` --- ## 14. Additional mxGraphModel Attributes These optional attributes on `` are less commonly used but appear in real-world files: \| Attribute \| Values \| Description \| \|---\|---\|---\| \| `adaptiveColors` \| `auto`, `simple`, `none`, `default` \| Controls color adaptation for light/dark mode viewing \| adaptiveColors example: ```xml ``` AI generators typically do not need to set this attribute. --- ## 15. Validation Checklist for AI-Generated Files Use this checklist to verify generated draw.io files: 1. Valid XML: File is well-formed XML with proper escaping 2. Root element: `` as root, contains at least one `` 3. Diagram IDs: Each diagram has a unique `id` attribute 4. Structural cells: Root contains `` and `` 5. Unique IDs: All cell IDs are unique within the diagram 6. Parent references: Every cell (except id="0") has a valid `parent` referencing an existing cell 7. Type flags: Each content cell has either `vertex="1"` or `edge="1"` (not both) 8. Edge references: Edge `source` and `target` reference existing vertex IDs 9. Geometry: Vertices have mxGeometry with x, y, width, height; edges have `relative="1"` 10. Style format: Style strings use `key=value;` format, valid keys and values 11. Perimeter match: Non-rectangular shapes have matching perimeter in style 12. HTML escaping: HTML in `value` attributes is properly XML-escaped 13. Coordinate system: x increases right, y increases down, no negative dimensions 14. Group hierarchy: Children of groups have coordinates relative to the group}}

`, `

` — tables - `

` — lists - `
` — horizontal rule - `` — inline images (with src attribute) - `` — links (href attribute) - `_{`, `^{` — subscript/superscript

### HTML in Attributes

HTML in the `value` attribute must be **XML-escaped**:
- `<` → `<`
- `>` → `>`
- `&` → `&`
- `"` → `"`

Example:
```xml

```

### Common HTML Patterns

**Bold title with description:**
```
Title Description text
```

**UML class box (within table container):**
```
ClassName
<hr size="1"/>
+ field: Type
<hr size="1"/>
+ method(): ReturnType
```

**Colored text:**
```
Red text
```

---

## 10. Layers

Layers are additional mxCell elements with `parent="0"`:

```xml

```

To hide a layer: add `visible="0"` to the layer cell.

---

## 11. Groups and Containers

A group/container is a vertex that other cells reference as their parent:

```xml

```

**Key points:**
- Child coordinates are **relative to the parent container**
- Use `style="group;"` for invisible containers
- Use `style="swimlane;startSize=30;"` for containers with a visible header
- Add `container=1;` to any style to make it act as a container
- `collapsible=0;` prevents the collapse/expand button

### Collapsible Containers and Alternate Bounds

When a container (e.g. swimlane) is collapsible, draw.io stores alternate bounds
in an `mxRectangle` child element inside `mxGeometry`. When the container is
collapsed/expanded, the geometry swaps between the normal and alternate bounds:

```xml

```

The `alternateBounds` typically has the same x/y but a smaller height (just the header).
AI generators generally do not need to produce `mxRectangle` elements — draw.io adds
them automatically when the user collapses a container.

---

## 12. Edge Geometry and Labels

### Basic Connected Edge

```xml

```

### Edge with Waypoints

```xml

```

### Edge with Label

Edge labels are usually encoded in the edge cell's `value`. The label position is controlled by the geometry:

```xml

```

- `x` on geometry: position along edge (-1 to 1, where 0 = center, -1 = near source, 1 = near target)
- `y` on geometry: perpendicular offset in pixels

### Unconnected Edge (Floating)

```xml

```

---

## 13. Complete Examples

### Example 1: Simple Flowchart

```xml

```

### Example 2: UML Class Diagram

```xml

```

### Example 3: Network Diagram with Groups

```xml

```

### Example 4: Custom Metadata with UserObject

```xml

```

---

## 14. Additional mxGraphModel Attributes

These optional attributes on `` are less commonly used but appear
in real-world files:

| Attribute | Values | Description |
|---|---|---|
| `adaptiveColors` | `auto`, `simple`, `none`, `default` | Controls color adaptation for light/dark mode viewing |

**adaptiveColors** example:
```xml

```

AI generators typically do not need to set this attribute.

---

## 15. Validation Checklist for AI-Generated Files

Use this checklist to verify generated draw.io files:

1. **Valid XML**: File is well-formed XML with proper escaping
2. **Root element**: `` as root, contains at least one ``
3. **Diagram IDs**: Each diagram has a unique `id` attribute
4. **Structural cells**: Root contains `` and ``
5. **Unique IDs**: All cell IDs are unique within the diagram
6. **Parent references**: Every cell (except id="0") has a valid `parent` referencing an existing cell
7. **Type flags**: Each content cell has either `vertex="1"` or `edge="1"` (not both)
8. **Edge references**: Edge `source` and `target` reference existing vertex IDs
9. **Geometry**: Vertices have mxGeometry with x, y, width, height; edges have `relative="1"`
10. **Style format**: Style strings use `key=value;` format, valid keys and values
11. **Perimeter match**: Non-rectangular shapes have matching perimeter in style
12. **HTML escaping**: HTML in `value` attributes is properly XML-escaped
13. **Coordinate system**: x increases right, y increases down, no negative dimensions
14. **Group hierarchy**: Children of groups have coordinates relative to the group}}