# 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
cd <skill>/scripts && task validate -- --file="<path-to-negative-space.drawio>"
```

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