Instruction file imported from techriderscommunity/platform-tech-riders (.github/instructions/mcpee-boost-mcpee-cloud--instructions-draw-io-instructions-md-ae3d865d.instructions.md). Copyright stays with the author.

draw.io Diagram Standards

Skill: Load .github/skills/draw-io/SKILL.md for full workflow, XML recipes, and troubleshooting before generating or editing any .drawio file.

Required Workflow

Follow these steps for every draw.io task:

1. Identify the diagram type (flowchart / architecture / sequence / ER / UML / network / BPMN)
2. Select the matching template from .github/skills/draw-io/templates/ and adapt it, or start from the minimal skeleton
3. Plan the layout on paper before writing XML — define tiers, actors, or entities first
4. Generate valid mxGraph XML following the rules below
5. Validate using python .github/skills/draw-io/scripts/validate-drawio.py <file>
6. Confirm the file renders by opening it in VS Code with the draw.io extension (hediet.vscode-drawio)

XML Structure Rules (Non-Negotiable)

<!-- Set modified to the current ISO 8601 timestamp when generating a new file -->
<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="unique-id" name="Page Name">
    <mxGraphModel ...>
      <root>
        <mxCell id="0" />                          <!-- REQUIRED: always first -->
        <mxCell id="1" parent="0" />               <!-- REQUIRED: always second -->
        <!-- all other cells go here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

• id="0" and id="1" must be present and must be the first two cells — no exceptions
• Every cell id must be unique within the diagram
• Every vertex (vertex="1") must have a child <mxGeometry x y width height as="geometry">
• Every edge (edge="1") must have source/target pointing to existing vertex ids — exception: floating edges (sequence diagram lifelines) use <mxPoint as="sourcePoint"> and <mxPoint as="targetPoint"> inside <mxGeometry> instead of source/target attributes
• Every cell except id=0 must have parent pointing to an existing id
• Children of a container (swimlane) use coordinates relative to their parent, not the canvas

Mandatory Style Conventions

Semantic Color Palette — Use consistently across the project

Always include on vertex shapes

whiteSpace=wrap;html=1;

Use html=1 whenever a label contains HTML tags (<b>, <i>, <br>)

Standard connectors

edgeStyle=orthogonalEdgeStyle;html=1;

Diagram-Type Quick Reference

Layout Best Practices

• Align all coordinates to the 10 px grid (values divisible by 10)
• Horizontal: 40–60 px gap between same-row shapes
• Vertical: 80–120 px gap between tier rows
• Standard shape size: 120 × 60 px (process), 200 × 100 px (decision diamond)
• Default canvas: A4 landscape 1169 × 827 px
• Maximum 40 cells per page — split into multiple pages for larger diagrams
• Add a title text cell at top of every page:

  style="text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1;align=center;"
  

File and Naming Conventions

• Extension: .drawio for version-controlled diagrams, .drawio.svg for files embedded in Markdown
• Naming: kebab-case — e.g. order-flow.drawio, database-schema.drawio
• Location: docs/ or architecture/ alongside the code they document
• Multi-page: use one <diagram> element per logical view within the same <mxfile>

Validation Checklist (run before every commit)

• <mxCell id="0" /> and <mxCell id="1" parent="0" /> are the first two cells
• All cell ids are unique within their diagram
• All edge source/target ids resolve to existing vertices
• All vertex cells have <mxGeometry as="geometry">
• All cells (except id=0) have a valid parent
• XML is well-formed — no unclosed tags, no bare &, <, > in attribute values
• Semantic color palette used consistently
• Title cell present on every page

# Run automated validation
python .github/skills/draw-io/scripts/validate-drawio.py <file.drawio>

Reference Files