oleg-lukasonokandClaude Fable 5
99f1fd07e3
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>
97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
# 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).
|