Drawio Impl Swimlanes

Draw.io Swimlane Implementation

Purpose

This skill enables correct generation of swimlane diagrams, cross-functional flowcharts, and pool/lane layouts in Draw.io mxGraph XML. It enforces the container-relative coordinate system and prevents the most common AI mistake: placing child shapes at absolute page coordinates instead of container-relative coordinates.

Critical Rules (Memorize These)

1. ALWAYS set container=1 in every swimlane and pool style — Without it, child shapes will NOT move with the lane when repositioned.
2. ALWAYS use container-relative coordinates for children — A child at x="40" y="35" is 40px from the lane's left edge and 35px from the lane's top edge (below the header). NEVER use absolute page coordinates.
3. ALWAYS set parent to the container ID for child shapes — A shape inside "lane1" MUST have parent="lane1". NEVER set parent="1" for shapes that belong inside a container.
4. ALWAYS set cross-lane edge parent to the common ancestor — When an edge connects shapes in different lanes, set the edge's parent to the pool (the shared ancestor). NEVER set it to one of the individual lanes.
5. ALWAYS include collapsible=0 on lanes — Without it, users can accidentally collapse lanes in the editor, hiding all contents.
6. NEVER use absolute page coordinates for shapes inside a container — This is the #1 swimlane mistake. Shapes will render at the wrong position and will NOT move with their parent lane.

Container Hierarchy

Swimlane diagrams use a strict parent-child hierarchy:

Root (id="1")
  Pool (container=1, parent="1")           = startSize to avoid overlap.

## Lane Geometry Rules

### Pool Positioning

The pool uses absolute page coordinates:

```xml

  

Lane Positioning

Lanes use coordinates relative to the pool. The first lane starts at y=startSize (below the pool header):

Width rule: ALWAYS set lane width equal to pool width. Lanes span the full width of the pool.

Height rule: The sum of all lane heights plus the pool header startSize MUST equal the pool height:

• Pool height = startSize + lane1.height + lane2.height + ...

Child Shape Positioning

Shapes inside lanes use coordinates relative to the lane's top-left corner:

Place children with y >= startSize of the lane to avoid overlapping the lane header.

Cross-Lane Connections

Edges that connect shapes in different lanes MUST use the pool as their parent:

Edges that connect shapes within the SAME lane MAY use either the lane or the pool as parent. For consistency, ALWAYS use the pool as edge parent.

Nested Lanes

Lanes can contain sub-lanes for finer granularity:

Rule: Sub-lane coordinates are relative to the parent lane. Sub-lane widths MUST equal the parent lane width.

Auto-Expand Behavior

When container=1 is set, Draw.io auto-expands the container if a child shape extends beyond its boundaries. To prevent unwanted expansion:

• ALWAYS size the pool and lanes large enough to contain all children.
• Add resizable=1 to allow manual resizing in the editor.
• Add recursiveResize=0 on the pool to prevent child lanes from auto-resizing when the pool resizes.

Complete Example: 3-Lane Order Processing

This example demonstrates:

• 3 lanes (Sales, Warehouse, Finance) inside one pool
• 7 shapes across 3 lanes with container-relative coordinates
• Cross-lane connections with parent="pool1"
• Decision diamond with labeled Yes/No branches
• Document shape for invoice generation
• Consistent left-to-right flow within horizontal lanes

Checklist: Before Outputting a Swimlane Diagram

1. Every pool and lane has container=1 in its style.
2. Every lane has collapsible=0 in its style.
3. Every child shape has parent set to its containing lane ID.
4. Every child shape uses coordinates relative to its lane (NOT absolute page coordinates).
5. Every cross-lane edge has parent set to the pool (common ancestor).
6. Lane widths equal the pool width.
7. Pool height = startSize + sum of all lane heights.
8. Child shapes have y >= startSize of their lane to avoid header overlap.
9. Both structural cells (id="0" and id="1") are present.
10. All cell IDs are unique.
11. All edges have valid source and target attributes.

Cross-References

• XML fundamentals: See drawio-core-xml-format for file structure and structural cells.
• Style syntax: See drawio-syntax-styles for the complete style property reference.
• Connection details: See drawio-syntax-connections for edge routing and waypoints.
• Geometry: See drawio-core-geometry for coordinate system and positioning.
• Flowchart shapes: See drawio-impl-flowcharts for ISO 5807 shapes used inside lanes.

Reference Links

• [Complete Reference](references/methods.md)
• [Working Examples](references/examples.md)
• [Anti-Patterns](references/anti-patterns.md)

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
• Source: Impertio-Studio/Draw.io-Claude-Skill-Package
• License: MIT

Install and usage instructions live in the source repository linked above.