# draw.io / mxGraph authoring gotchas Encoding and alignment rules that apply whenever this skill **writes or edits mxCell XML directly** — i.e. during surgical relabels (step 4), when adding cards/edges next to template cells, and in `render_semantic.py`-derived output. Violations are silent at write time and only visible when the user opens the file: blank icons, "duplicate id" rejections, or connectors cutting through artwork. `validate.py` mechanically checks §§1–2 and the structural parts of §7. Scaffolded SAP templates already satisfy all of this — these rules matter for the cells **you** add or change. ## 1. Embedded-image data URIs must OMIT `;base64` draw.io style strings are `;`-delimited key=value lists. A standard data URI (`data:image/svg+xml;base64,PHN2...`) contains a `;` — draw.io truncates the `image=` value at that semicolon and starts parsing `base64,PHN2...` as a new style key. Result: every icon renders blank, with no error. - **Correct (draw.io style):** `image=data:image/svg+xml,PHN2Zy8+;` (payload IS still base64-encoded; only the `;base64` marker is dropped — draw.io's own convention, and what the bundled SAP libraries ship.) - **Incorrect:** `image=data:image/svg+xml;base64,PHN2Zy8+;` - Plain SVG/HTML is the opposite: an `` **requires** the standard `;base64` form. If you generate both a `.drawio` and an SVG preview from the same data, the two encodings must differ. `extract_icon.py` / `extract_asset.py` emit the correct form — this rule bites only when embedding a third-party logo or UI5 icon-font SVG by hand. ## 2. Root-cell skeleton and reserved ids Every diagram page must begin with a **parentless root cell**, then a **layer cell parented to it**, before any content: ```xml ``` `0`/`1` are mxGraph's defaults, but the SAP corpus frequently uses namespaced equivalents (`-0`, `-1`) — the *structure* is what matters, and `validate.py` checks it. Two failure modes for hand-authored pages: - Omitting the two root cells entirely → draw.io rejects the file. - A content cell reusing the page's root/layer id (easy when deriving ids from numeric counters, colliding with literal `0`/`1`) → "duplicate id", whole file rejected. Namespace generated ids (`n-`, `edge-3`, `pill-2`). Ids must be unique within a page; each `` page has its own id space. ## 3. Z-order is document order Later cells render on top. Emit **edges before vertices** so connectors sit behind nodes/icons (SAP's files do this; they never rely on opaque icon backings). draw.io resolves an edge's `source`/`target` by id even when those cells are declared later — forward references are fine. When inserting new cards into a template, insert them **after** the edges that touch them. ## 4. Connectors must attach to facing connection points Without fixed connection points, draw.io anchors edges center-to-center and a line can cut straight through nodes that sit between endpoints. Give every added edge directional exit/entry on the border side facing the counterpart: ``` exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0; ``` (source's right edge → target's left edge, for a left-to-right flow; use Y 0/1 with X 0.5 for vertical). Combine with `edgeStyle=orthogonalEdgeStyle; rounded=0;orthogonalLoop=1;jettySize=auto;` so the router runs segments through the gaps between columns. Z-order alone is never the fix for edges crossing icons. This complements the center-alignment rule in `shapes-and-edges.md`: aligned centers make the edge *straight*; facing anchors make it *dock* on the correct sides. ## 5. Explicit waypoints To force a route (e.g. through a routing channel between zones), put bend points inside the edge geometry — intermediate points only; endpoints come from the cells: ```xml ``` Keep waypoint coordinates on the 10-px grid like everything else. ## 6. Image aspect ratio & inscription `imageAspect=1` preserves proportions (`0` stretches to the cell box — wide wordmark logos become distorted). The SAP corpus itself uses `imageAspect=0` on cells whose geometry was hand-sized to the artwork, so this is **not** a validator check — it's a rule for logos *you* embed, where the cell box rarely matches the source aspect exactly. In SVG the equivalent is `preserveAspectRatio="xMidYMid meet"`. Square logos placed on a circular tile must be inscribed: icon side ≤ tile diameter / √2, or the corners poke past the circle (e.g. a 52-px tile fits at most a ~36-px square icon). ## 7. Structure & page setup - Skeleton: `` + the two reserved cells, then content. Emit uncompressed XML — never the base64-deflate `` payload form. - Every vertex needs `vertex="1"` + ``; every edge `edge="1"` + resolvable `source`/`target` (or explicit `sourcePoint`/`targetPoint` for floating edges); every cell (except `0`) a valid `parent`. - Children of a container (`container=1` or any parented vertex) use coordinates **relative to the parent**, not the canvas. When re-parenting an icon into a card (the "tucked inside a card" pattern), convert its x/y to card-local values. - Escape XML in labels/attrs: `&` `<` `>` → `&` `<` `>`; `html=1` when the label carries HTML. ## 8. Edge routing extras seen in the SAP corpus - `entityRelationEdgeStyle` — perpendicular jetty stubs; SAP uses it for *indirect* flows where orthogonal elbows would read as a direct chain. - `targetPerimeterSpacing=15` — leaves a visual gap before the target border so arrowheads don't kiss the stroke. - `jumpStyle=none` — edge crossings drawn flat, no hop arcs. Don't enable jumps; SAP's published files never use them.