visual-mockup

Announce: "I'll create a mockup so you can see the layout before I code the real diagram."

Why This Exists

Diagram code (CeTZ, Fletcher, TikZ) is slow to iterate on — you write coordinates, compile, discover the layout is wrong, rewrite. A 30-second sketch lets the user see and approve the spatial layout before any real code gets written. This saves 3-5 compile-fix cycles on complex diagrams.

When to Use

• Before coding a new diagram with 4+ nodes, regions, or non-trivial arrow routing
• Before coding a CeTZ chart where the data shape matters (stock prices, timelines)
• When the user describes a layout change and you want to confirm before implementing
• When an ASCII sketch isn't enough to convey spatial relationships (overlapping regions, diagonal arrows, nested containers)
• When you and the user are iterating on where things should go

You don't need this for simple diagrams (2-3 nodes in a line). Use your judgment — if the layout is obvious, skip the mockup and go straight to code.

Choosing a Mode

Mode	When	Output
Interactive (default for node diagrams)	Fletcher diagrams, 4+ nodes, precise positioning	Drag-and-drop HTML → Fletcher JSON
Matplotlib (for charts/plots)	CeTZ charts, stock prices, timelines, data series	Static PNG → iterate data → translate to CeTZ

Default to interactive for node-edge diagrams. Use matplotlib for anything with axes, data series, or time-based plots.

---

Interactive Mockup (Fletcher Diagrams)

1. Gather the Layout

From conversation context or the user's request, identify:

• Nodes: labeled boxes with approximate positions
• Edges: arrows between nodes, with labels and directionality
• Regions: background containers grouping nodes (dashed borders, light fills)
• Constraints: "X must be above Y", "no crossing arrows", "these two side by side"

2. Generate the Interactive HTML

Write the layout as JSON and run the generator:

cat > /tmp/layout.json << 'LAYOUT'
{
  "title": "Diagram Name",
  "nodes": [
    {"id": "n1", "label": "Issuer", "x": 200, "y": 100, "color": "#89b4fa"},
    {"id": "n2", "label": "Buyer", "x": 200, "y": 300, "color": "#a6e3a1"}
  ],
  "edges": [
    {"from": "n1", "to": "n2", "label": "§11 claim"}
  ],
  "regions": [
    {"id": "r1", "label": "Primary Market", "x": 140, "y": 60, "w": 250, "h": 280, "color": "#89b4fa"}
  ]
}
LAYOUT
uv run python3 ${SKILL_DIR}/scripts/interactive_mockup.py /tmp/layout.json --open

${SKILL_DIR} resolves to this skill's base directory (e.g., skills/visual-mockup).

The browser opens with a Catppuccin-themed drag-and-drop canvas:

• Drag nodes and regions to reposition
• Drag edge labels to offset from midpoint; R / Shift+R to rotate 15 degrees
• Double-click any element to rename its label
• "+ Node" / "+ Edge" / "+ Region" buttons to add elements
• Delete/Backspace to remove selected element
• Bottom-right handle on regions to resize
• "Export as" dropdown: Fletcher (grid coords, y-down) or Raw pixels
• "Copy Layout JSON" button copies transformed positions to clipboard

Best for Fletcher diagrams. The exported grid coords drop directly into node((x, y), ...) calls. CeTZ diagrams require manual arrow routing that the mockup can't capture — use matplotlib mode for CeTZ instead.

3. Get the Layout Back

Tell the user: "Drag nodes where you want them, select Fletcher in the Export dropdown, then click Copy Layout JSON and paste it here."

The user pastes JSON with Fletcher grid coordinates. Use these positions directly in node((x, y), ...) calls — no coordinate transform needed.

4. Iterate if Needed

If the user wants further changes, regenerate with updated JSON and --open again. When approved, proceed to real diagram code.

---

Matplotlib Mockup (CeTZ Charts & Simple Layouts)

1. Gather the Data

Identify the chart's data series, axes, annotations, and shaded regions. For node diagrams, identify nodes, edges, regions.

2. Generate the Mockup

Write a Python script that uses matplotlib/seaborn to sketch the visual:

For charts/plots:

• Plot data series with appropriate line styles
• Add shaded regions (class periods, lookback windows, etc.)
• Add annotations (damage brackets, labels, axis markers)
• Match the target palette if known

For node diagrams:

• matplotlib.patches.FancyBboxPatch with rounded corners for nodes
• ax.annotate with arrowprops for edges
• Low-alpha patches with dashed borders for regions

Output to /tmp/visual-mockup.png at 150 DPI, then open it:

plt.savefig('/tmp/visual-mockup.png', dpi=150, bbox_inches='tight')

open /tmp/visual-mockup.png

3. Iterate with the User

Show the mockup and ask if the data shape / layout is right. This is where the value lives — catching problems like "the stock price doesn't bounce back" or "the damage bracket is in the wrong place" takes seconds in matplotlib vs. minutes in CeTZ compile cycles.

When approved, translate to CeTZ. For charts, the data arrays transfer directly — matplotlib and CeTZ use the same coordinate space, just different syntax.

Style Guide (Matplotlib Mode)

• figsize=(12, 6) for side-by-side, (8, 6) for single diagrams
• boxstyle="round,pad=0.1" for nodes
• Use color to distinguish categories (red for danger/fraud, blue for normal flow)
• ax.set_aspect('equal') and ax.axis('off') for node diagrams

---

Red Flags — STOP If You Catch Yourself:

Action	Why Wrong	Do Instead
Spending 10+ minutes polishing the mockup	The user is waiting for a sketch, not a deliverable. Polishing a mockup is anti-helpful — it delays the real diagram.	Get it "good enough to discuss" and open it. 2 minutes max.
Adding data, formulas, or precise styling	You're building the real diagram in the wrong tool. The mockup exists to be thrown away.	Boxes, arrows, labels, data shape. That's it.
Skipping the mockup because "I know the layout"	You thought that about Morrison too. The user saw crossing arrows you didn't. Skipping creates 3+ failed compile-fix cycles — that's not faster, it's slower.	If 4+ nodes, sketch it. 30 seconds vs. 3 failed compiles.
Going straight to CeTZ for a chart	You can't see data shape problems until you compile. Editing CeTZ data arrays blind wastes the user's time on compile-squint-edit cycles.	Mockup in matplotlib first — iterate on data with the user, then translate.
Editing CeTZ data arrays "real quick" without mockup	You're gambling that you'll guess the right data shape. The value-line incident: "just shift the prices down" produced a chart that told the wrong story for weeks.	30-second matplotlib plot catches data shape errors the user can see instantly.

What This Skill is NOT

• Not a render-verify loop (use visual-verify for that)
• Not a replacement for the actual diagram code
• Not for standalone data visualization (use ds workflow for charts/plots)
• Not for pixel-perfect output — it's a spatial sketch for layout approval