diagrams-drawio/references/negative-space-diagram.md

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:

<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:

cd <skill>/scripts && task validate -- --file="<path-to-negative-space.drawio>"

Expected: valid: true. The diagram will have 0 edges (only vertex rectangles).