Skip to content

Commit d77dfca

Browse files
SriSatyaLokeshSriSatyaLokesh
committed
instructions for draw.io files
1 parent 02419b9 commit d77dfca

1 file changed

Lines changed: 144 additions & 0 deletions

File tree

‎instructions/draw-io.instructions.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
---
2+
description: "Use when creating, editing, or reviewing draw.io diagrams and mxGraph XML in .drawio, .drawio.svg, or .drawio.png files."
3+
applyTo: "**/*.drawio,**/*.drawio.svg,**/*.drawio.png"
4+
---
5+
6+
# draw.io Diagram Standards
7+
8+
> **Skill**: Load `.github/skills/draw-io-diagram-generator/SKILL.md` for full workflow, XML recipes, and troubleshooting before generating or editing any `.drawio` file.
9+
10+
---
11+
12+
## Required Workflow
13+
14+
Follow these steps for every draw.io task:
15+
16+
1. **Identify** the diagram type (flowchart / architecture / sequence / ER / UML / network / BPMN)
17+
2. **Select** the matching template from `.github/skills/draw-io-diagram-generator/templates/` and adapt it, or start from the minimal skeleton
18+
3. **Plan** the layout on paper before writing XML — define tiers, actors, or entities first
19+
4. **Generate** valid mxGraph XML following the rules below
20+
5. **Validate** using `python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <file>`
21+
6. **Confirm** the file renders by opening it in VS Code with the draw.io extension (`hediet.vscode-drawio`)
22+
23+
---
24+
25+
## XML Structure Rules (Non-Negotiable)
26+
27+
```xml
28+
<!-- Set modified to the current ISO 8601 timestamp when generating a new file -->
29+
<mxfile host="Electron" modified="" version="26.0.0">
30+
<diagram id="unique-id" name="Page Name">
31+
<mxGraphModel ...>
32+
<root>
33+
<mxCell id="0" /> <!-- REQUIRED: always first -->
34+
<mxCell id="1" parent="0" /> <!-- REQUIRED: always second -->
35+
<!-- all other cells go here -->
36+
</root>
37+
</mxGraphModel>
38+
</diagram>
39+
</mxfile>
40+
```
41+
42+
- `id="0"` and `id="1"` **must** be present and must be the first two cells — no exceptions
43+
- Every cell `id` must be **unique** within the diagram
44+
- Every vertex (`vertex="1"`) must have a child `<mxGeometry x y width height as="geometry">`
45+
- 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
46+
- Every cell except id=0 must have `parent` pointing to an existing id
47+
- Children of a container (swimlane) use **coordinates relative to their parent**, not the canvas
48+
49+
---
50+
51+
## Mandatory Style Conventions
52+
53+
### Semantic Color Palette — Use consistently across the project
54+
55+
| Role | fillColor | strokeColor |
56+
|---|---|---|
57+
| Primary / Info (default) | `#dae8fc` | `#6c8ebf` |
58+
| Success / Start / Positive | `#d5e8d4` | `#82b366` |
59+
| Warning / Decision | `#fff2cc` | `#d6b656` |
60+
| Error / End / Danger | `#f8cecc` | `#b85450` |
61+
| Neutral / Interface | `#f5f5f5` | `#666666` |
62+
| External / Partner | `#e1d5e7` | `#9673a6` |
63+
64+
### Always include on vertex shapes
65+
66+
```
67+
whiteSpace=wrap;html=1;
68+
```
69+
70+
### Use `html=1` whenever a label contains HTML tags (`<b>`, `<i>`, `<br>`)
71+
72+
### Standard connectors
73+
74+
```
75+
edgeStyle=orthogonalEdgeStyle;html=1;
76+
```
77+
78+
---
79+
80+
## Diagram-Type Quick Reference
81+
82+
| Type | Container | Key shapes | Connector style |
83+
|---|---|---|---|
84+
| Flowchart | None | `ellipse` (start/end), `rounded=1` (process), `rhombus` (decision) | `orthogonalEdgeStyle` |
85+
| Architecture | `swimlane` per tier | `rounded=1` services, cloud/DB shapes | `orthogonalEdgeStyle` with labels |
86+
| Sequence | None | `mxgraph.uml.actor`, dashed lifeline edges | `endArrow=block` (sync), `endArrow=open;dashed=1` (return) |
87+
| ER Diagram | `shape=table;childLayout=tableLayout` | `shape=tableRow`, `shape=partialRectangle` | `entityRelationEdgeStyle;endArrow=ERmany;startArrow=ERone` |
88+
| UML Class | `swimlane` per class | text rows for attributes/methods | `endArrow=block;endFill=0` (inherit), `dashed=1` (realize) |
89+
90+
---
91+
92+
## Layout Best Practices
93+
94+
- Align all coordinates to the **10 px grid** (values divisible by 10)
95+
- **Horizontal**: 40–60 px gap between same-row shapes
96+
- **Vertical**: 80–120 px gap between tier rows
97+
- Standard shape size: `120 × 60` px (process), `200 × 100` px (decision diamond)
98+
- Default canvas: A4 landscape `1169 × 827` px
99+
- Maximum **40 cells per page** — split into multiple pages for larger diagrams
100+
- Add a **title text cell** at top of every page:
101+
```
102+
style="text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1;align=center;"
103+
```
104+
105+
---
106+
107+
## File and Naming Conventions
108+
109+
- Extension: `.drawio` for version-controlled diagrams, `.drawio.svg` for files embedded in Markdown
110+
- Naming: `kebab-case` — e.g. `order-flow.drawio`, `database-schema.drawio`
111+
- Location: `docs/` or `architecture/` alongside the code they document
112+
- Multi-page: use one `<diagram>` element per logical view within the same `<mxfile>`
113+
114+
---
115+
116+
## Validation Checklist (run before every commit)
117+
118+
- [ ] `<mxCell id="0" />` and `<mxCell id="1" parent="0" />` are the first two cells
119+
- [ ] All cell ids are unique within their diagram
120+
- [ ] All edge `source`/`target` ids resolve to existing vertices
121+
- [ ] All vertex cells have `<mxGeometry as="geometry">`
122+
- [ ] All cells (except id=0) have a valid `parent`
123+
- [ ] XML is well-formed — no unclosed tags, no bare `&`, `<`, `>` in attribute values
124+
- [ ] Semantic color palette used consistently
125+
- [ ] Title cell present on every page
126+
127+
```bash
128+
# Run automated validation
129+
python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <file.drawio>
130+
```
131+
132+
---
133+
134+
## Reference Files
135+
136+
| File | Use For |
137+
|---|---|
138+
| `.github/skills/draw-io-diagram-generator/SKILL.md` | Full agent workflow, recipes, troubleshooting |
139+
| `.github/skills/draw-io-diagram-generator/references/drawio-xml-schema.md` | Complete mxCell attribute reference |
140+
| `.github/skills/draw-io-diagram-generator/references/style-reference.md` | All style keys, shape names, edge types |
141+
| `.github/skills/draw-io-diagram-generator/references/shape-libraries.md` | Shape library catalog with style strings |
142+
| `.github/skills/draw-io-diagram-generator/templates/` | Ready-to-use `.drawio` templates per diagram type |
143+
| `.github/skills/draw-io-diagram-generator/scripts/validate-drawio.py` | XML structure validator |
144+
| `.github/skills/draw-io-diagram-generator/scripts/add-shape.py` | CLI: add a shape to an existing diagram |

0 commit comments

Comments
 (0)