ci-mockup-figure

# CI Mockup Figure

## Overview

The goal is **space-efficient, information-dense figures** that communicate
a system's design, a method's pipeline, or an architectural flowchart in
minimal page area. Two paths depending on figure type:

- **HTML mockup path** (Phases 1-4 below): for UI mockups, dashboards,
  timelines, and any figure where content is rectangular with no cross-node
  arrows. Build interactive HTML, capture screenshots, insert into LaTeX.
- **Abstract figure path** (Abstract Figure Toolchain section): for
  architecture overviews, dependency topologies, and any figure needing
  arrow routing between non-adjacent nodes. Use TikZ, skia-canvas, or
  Illustrator ExtendScript.

Every figure must pass the space test: does this figure communicate more per
square inch than the text it displaces? If a full-width figure takes half a
page but only says "A → B → C → D", it fails. A wrapfigure showing an
interactive prototype with search results, graph nodes, and real data labels
passes because it communicates system design, data model, and UX simultaneously.

This skill works for any document where figures need to communicate design
or methodology credibly: research papers (method overview, architecture
diagrams, pipeline flowcharts), proposals (NSF, NIH, DOE, etc.), technical
reports, or demo writeups. It is especially effective when the figure needs
to show multi-component structure, data flow, or step-by-step methodology
and reviewers evaluate whether the design is credible and well-conceived.

### HTML mockups vs TikZ/LaTeX diagrams

HTML and TikZ each have a clear strength. The deciding factor is **whether
the figure needs arrow routing between non-adjacent nodes**.

| | HTML mockup | TikZ |
|---|---|---|
| Visual polish | Modern CSS, shadows, gradients, rounded cards | Flat, academic-looking boxes |
| Iteration speed | Change CSS and refresh | Recompile LaTeX, debug positioning |
| Layout control | Flexbox/grid, responsive | Manual coordinate math |
| Color/font variety | Full CSS + web fonts | Limited, verbose color defs |
| Interactivity | View switching, capture mode | Static only |
| **Arrow routing** | **Breaks on cross-row/non-adjacent nodes** | **Node anchoring solves this natively** |
| Font matching | Separate from LaTeX | Perfect match with document body |

**Prefer HTML** for system mockups, dashboards, Gantt/timeline figures, and
any figure where the content is inherently rectangular and flows naturally
(no cross-node arrows needed).

**Prefer TikZ** for abstract framework diagrams, dependency topologies, and
architecture overviews where arrows must route between non-adjacent nodes
(L-shaped, curved, crossing rows). TikZ node anchoring (`node.south`,
`node.east`) handles this natively. Also prefer TikZ for small inline
diagrams that must live inside the LaTeX source or when exact font matching
is critical.

**Prefer skia-canvas** (Node.js) when you need the arrow-routing control of
TikZ but want faster iteration (edit `.mjs`, run, get PDF) and richer
visual styling than TikZ provides.

### HTML mockups vs AI image generation

HTML mockups are strictly better than AI-generated images for system and
method figures. AI image generation is acceptable only for artistic/conceptual
overview diagrams.

| | HTML mockup | AI image generation |
|---|---|---|
| Text legibility | Pixel-perfect, real fonts | Often garbled or blurry |
| Data accuracy | Every number/label controlled | Hallucinated values |
| Iteration speed | Change CSS and refresh | Re-prompt and hope |
| Consistency | Same palette across figures | Each generation varies |
| Print quality | Vector PDF via browser print | Always raster |
| Reviewer trust | Looks like a system you could build | Looks like a concept sketch |

### HTML mockups vs PowerPoint (for timelines)

HTML is also better than PPTX for Gantt/timeline figures:

| | HTML | PowerPoint |
|---|---|---|
| Alignment | CSS grid, pixel-perfect | Manual drag |
| Edits | Change one label, everything reflows | Reposition every box |
| Color consistency | CSS variables, one source of truth | Manual color matching |
| Capture | Browser Print → PDF (vector) | Export PDF (often wrong margins) |

## When to Use

- The document describes a multi-component system or multi-step methodology
  (e.g., "representation layer + discovery service + workflow engine", or
  "data collection → feature extraction → model training → evaluation")
- Abstract pipeline diagrams feel generic and do not differentiate the work
- The figure needs to show architectural structure, data flow, or method
  pipeline with real labels, not just boxes and arrows
- Collaborators need something interactive to react to and iterate on
- The document has a page limit and figures need to be space-efficient
- A timeline/Gantt figure is needed for the work plan or project overview

### When NOT to Use (either path)

- **Experimental result figures** (plots, charts, tables, ablation curves) --
  use Python (matplotlib, seaborn, plotly) or LaTeX (pgfplots, tikz) instead.
  This skill is for system/method diagrams, not data visualization.

### When to Use the Abstract Path Instead of HTML

- **Abstract framework diagrams with cross-node arrow routing** --
  dependency topologies, architecture overviews with curved arrows between
  non-adjacent nodes, box-and-arrow conceptual figures. HTML/CSS fails at
  arrow routing: JS-positioned SVG arrows drift and misalign, CSS
  pseudo-element arrows work only for simple adjacent connections, and card
  grid layouts read as a product dashboard, not a research diagram. Use the
  Abstract Figure Toolchain section below.

## Abstract Figure Toolchain

When the figure is NOT a UI mockup, dashboard, or timeline (i.e., it needs
arrows between nodes, dependency edges, or architectural flow), HTML/CSS is
the wrong tool. The core problem: **arrow routing is the bottleneck**, not
box/text rendering. Any tool with node-anchor-based arrow endpoints works;
any tool relying on CS