Add drawio-main skill (renamed from drawio-main-v1)

Draw.io diagram generation and analysis skill: mandatory layout and style rules, XML reference, negative-space companion diagrams, and the drawio-tools TypeScript CLI with 12 analysis/validation actions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-24 15:52:39 +03:00
parent 2b69cce629
commit 99f1fd07e3
33 changed files with 7044 additions and 1 deletions
@@ -0,0 +1,96 @@
+# Negative Space Diagram
+
+A negative space diagram is a companion diagram generated from `page-negative-space-summary` CLI output. It visualises where free routing corridors exist on the canvas — dark areas show where connectors can travel; blank (grid-visible) areas show where shapes sit.
+
+---
+
+## Core rule
+
+**Black rectangles only. Shape footprints are left completely empty.**
+
+- Place **only solid black rectangles** (`fillColor=#1a1a1a;strokeColor=none`) where free space exists
+- Where shapes are positioned, place **nothing** — leave those coordinates completely empty so the draw.io grid shows through
+- Do **NOT** draw white rectangles, outlines, ghost shapes, or any visual marker at shape positions
+- Do **NOT** add labels, annotations, or legend entries inside the main canvas area
+- **One color only: `#1a1a1a`** — no distinctions between inter-row gap bands and within-row free corridors; all free space is the same black
+
+The resulting diagram is a pure "ink = free space, blank = occupied" map.
+
+---
+
+## Construction steps
+
+1. Run `page-negative-space-summary` on the source diagram to get the free corridor data
+2. For each free corridor `{xMin, xMax, yMin, yMax}` from `freeCorridors` or `textAwareFreeCorridors`, place one black rectangle covering that exact area
+3. For inter-row gaps (y bands between shape rows), place a full-width black rectangle covering the entire gap band — same `#1a1a1a` color, no special treatment
+4. For shape footprint coordinates — place **nothing**; those cells remain blank (grid visible)
+5. Add a **border frame** — 4 black rectangles forming a closed frame around the entire diagram canvas (see Border frame rule below)
+6. A legend may appear **outside** the diagram canvas bounds (above or below) — it must not overlap any part of the canvas
+
+### Border frame rule
+
+Every negative space diagram **must** have a 4-rectangle black border frame surrounding the canvas area. The frame consists of:
+
+| Side | Position | Formula |
+|---|---|---|
+| Top | above diagram | `x = diagramXMin - frameThickness`, `y = diagramYMin - frameThickness`, `width = diagramWidth + 2×frameThickness`, `height = frameThickness` |
+| Bottom | below diagram | `x = diagramXMin - frameThickness`, `y = diagramYMax`, `width = diagramWidth + 2×frameThickness`, `height = frameThickness` |
+| Left | left of diagram | `x = diagramXMin - frameThickness`, `y = diagramYMin - frameThickness`, `width = frameThickness`, `height = diagramHeight + 2×frameThickness` |
+| Right | right of diagram | `x = diagramXMax`, `y = diagramYMin - frameThickness`, `width = frameThickness`, `height = diagramHeight + 2×frameThickness` |
+
+Where:
+- `frameThickness` = 40 pt (divisible by 40 — mandatory)
+- `diagramXMin`, `diagramXMax`, `diagramYMin`, `diagramYMax` — from the `page-negative-space-summary` output fields
+- `diagramWidth = diagramXMax - diagramXMin`
+- `diagramHeight = diagramYMax - diagramYMin`
+
+All four frame rectangles use `fillColor=#1a1a1a;strokeColor=none;` — same as all other free-space rectangles.
+
+**Example** for `diagramXMin=80, diagramXMax=1600, diagramYMin=40, diagramYMax=720, frameThickness=40`:
+
+```
+Top:    x=40,  y=0,   width=1600, height=40
+Bottom: x=40,  y=720, width=1600, height=40
+Left:   x=40,  y=0,   width=40,   height=760
+Right:  x=1600, y=0,  width=40,   height=760
+```
+
+Note: the left and right bars span the full height including top and bottom bars (height = diagramHeight + 2×frameThickness = 680 + 80 = 760) so corners are fully covered with no gaps.
+
+---
+
+## XML pattern
+
+All rectangles use the same style — no exceptions:
+
+```xml
+<mxCell id="free-r2-left" value="" style="shape=rectangle;fillColor=#1a1a1a;strokeColor=none;" vertex="1" parent="1">
+  <mxGeometry x="80" y="160" width="240" height="80" as="geometry"/>
+</mxCell>
+```
+
+Use the `textAwareFreeCorridors` field from `page-negative-space-summary` — it gives the pre-computed black rectangle list per row, already accounting for text regions inside shape bounding boxes.
+
+---
+
+## File naming
+
+Place the negative space diagram alongside the source diagram with a `-negative-space` suffix:
+
+```
+artifacts/
+├── buyer-purchase-journey.drawio
+└── buyer-purchase-journey-negative-space.drawio
+```
+
+---
+
+## Validation
+
+Validate with the standard `validate` action before finishing:
+
+```bash
+node dist/cli/commands.js --action validate --file <path-to-negative-space.drawio>
+```
+
+Expected: `valid: true`. The diagram will have 0 edges (only vertex rectangles).