--- name: ci-mockup-figure description: Create space-efficient figures for papers and proposals. HTML mockups for systems, dashboards, and timelines; TikZ or skia-canvas for abstract diagrams with arrow routing. Covers tool selection, design, capture, and LaTeX insertion. The primary goal is maximizing information per page — every figure must earn its space. --- # 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 CSS layout for arrow positioning will struggle. ### What fails in HTML/CSS for abstract diagrams | Problem | Why | |---|---| | Curved arrows between components | Requires absolute-positioned SVG overlay that fights CSS layout | | External screenshots as hero images | Multi-panel screenshots break `object-fit: cover` and explode containers | | Card grid layout | Reads as a product dashboard, not a research diagram | | Print fidelity | Browser print rescales unpredictably for non-page layouts | | Emoji/icons for decoration | Instantly makes the figure look unprofessional | ### Recommended tools (ranked by context) | Context | Tool | Why | |---|---|---| | LaTeX paper, arrow-heavy | **TikZ** | Node anchoring (`node.south`, `node.east`) handles arrow routing natively. Font/style consistency with the paper is free. Academic gold standard. | | Programmatic iteration needed | **skia-canvas** (Node.js) | Same Canvas API as HTML but headless, with direct PDF/SVG vector export. Edit coordinates in `.mjs`, run `node script.mjs`, get PDF. No browser, no capture, no pdfcrop. | | Final hand-polish needed | **Illustrator ExtendScript** (`.jsx`) | Generate programmatically, then hand-adjust. Best for figures that need to look "designed." Requires Illustrator. | | Python-only environment | **drawsvg** (`pip install drawsvg`) | SVG-first imperative drawing. For PDF, convert the output SVG externally (e.g., Inkscape CLI or `cairosvg`, which needs the Cairo C library and is tricky on Windows). | **Not recommended:** D2 (auto layout too unpredictable for precise academic figures), Graphviz (limited custom styling), matplotlib (designed for data plots, not diagrams). ### skia-canvas workflow A parallel capture path to the HTML workflow, for abstract figures: ```bash npm install skia-canvas # edit generate-figure.mjs (Canvas API: ctx.roundRect, ctx.fillText, ctx.lineTo) node generate-figure.mjs # outputs figure.pdf (vector), figure.svg, figure.png # use figure.pdf directly in \includegraphics — no pdfcrop needed ``` Script structure pattern: ``` gen_overview.mjs ├── helpers: roundRect(), text(), drawArrow(), drawImage() ├── layout constants: W, H, panel positions, gap sizes ├── draw(): │ ├── header bar (title + thumbnails) │ ├── component panels (frame + internal diagram + footer) │ ├── inter-component arrows with labeled handoffs │ └── bottom strip (use cases + running example) └── export: PDF + PNG preview ``` Adjust coordinates, rerun, get new PDF instantly. No browser, no print quirks. ### Design principles for abstract/architecture figures 1. **No external screenshots in component panels.** Draw diagrams programmatically (nodes, edges, flow stages). Screenshots are not made for your figure's aspect ratio and will break. 2. **Real images only in grounding areas** (use case strips, running example ribbons) where they are decorative context, not structural elements. 3. **Horizontal layout for pipeline figures** (T1 -> T2 -> T3 left-to-right). Vertical stacking wastes landscape width. 4. **Minimal elements per panel**: badge, title, one diagram, short description, one output line. 5. **Light tint fills** (`rgba(..., 0.06-0.08)`), thick top-border accent per component. No saturated card backgrounds, no shadows, no pills/chips. 6. **Inter-component arrows with labeled handoffs** (e.g., "Asset Graph", "Discovery Trace") as explicit connectors, not just whitespace. 7. **Professional typography**: system sans-serif (Segoe UI, Arial) or serif (Georgia). Never playful fonts. No emoji. ## Space Budget (decide first) Before designing anything, decide the figure budget for the document. The table below uses LaTeX environments as examples; adapt to the target format. | Figure type | Space cost | When to use | |---|---|---| | `wrapfigure{r}{0.55\textwidth}` | ~55% column width, text wraps beside | **Best default** for system mockups — gives prose enough room | | `wrapfigure{r}{0.46\textwidth}` 2x2 grid | ~46% column width, 4 images in compact grid | Motivation figures with matched-ratio panels | | `figure[t]` full-width | Full column, ~3-4cm height for landscape | Timelines, overview diagrams, or mockups with small text | | `subfloat` 1x4 row in `figure[t]` | Full column, ~3cm height | Cross-domain motivation (all same aspect ratio) | **Lesson learned: 0.68\textwidth is too wide for most wrapfigures.** At 0.68, the remaining text column is too narrow for comfortable reading and the prose wraps through multiple paragraphs. Default to **0.55–0.56\textwidth** for system mockups. Use 0.68 only for simple figures with large text. **Rule of thumb for page-limited documents (e.g., 15-page proposal):** - 3 main figures as wrapfigures = ~1.5 pages of figure space - 1 overview figure + 1 motivation figure = ~1 page - Total figure budget: ~2.5 pages out of 15 (17%) — leave 83% for text **Horizontal layout is mandatory.** Vertical/portrait screenshots waste 50%+ of their space on a landscape-format page. Design the mockup for wide capture from the start. ## Phase 1: Design the Mockup ### 1a. Split complex interfaces into separate figures Do not cram multiple interfaces into one figure. If a system has a coordinator-facing view and a citizen-facing view, build both in one HTML file but capture them as **separate screenshots**, each inserted at its own relevant subtask in the LaTeX. Add **view-switching buttons** (e.g., COORDINATOR / CITIZEN / BOTH) to the toolbar so the user can toggle views and capture each at full width. Each view mode should have its own CSS that expands sidebars, scales up fonts, and adjusts proportions for the full-width layout. ### 1b. Identify the views Each major thrust or component gets its own view. Typically 3-4 views: - A dashboard/overview showing the full pipeline - One view per thrust showing that thrust's specific interface ### 1c. Choose per-thrust visual identity Each thrust needs a distinct color palette with **three tones** (solid, mid, light) so bars, cards, and legends are consistent: ```css --t1: #0d9488; --t1-mid: #5eead4; --t1-light: #ccfbf1; --t2: #2563eb; --t2-mid: #93c5fd; --t2-light: #dbeafe; ``` Use the light tone for activity bars with a solid-tone border, the solid tone for milestone/completion bars, and the mid tone sparingly for hover states. **Legend swatches must match the actual bar appearance** — if bars are light with colored borders, show that in the legend, not a solid fill. ### 1d. Embed real public-domain imagery Use real, public-domain scientific imagery as **low-opacity backgrounds** to add geographic or domain credibility without overwhelming the schematic: - NASA Earth Observatory for satellite/geoscience imagery - NOAA for climate/ocean data products - USGS for terrain/hazard data Embed as CSS background with `opacity: 0.15–0.20` and `filter: saturate(0.6)`. Add a small attribution credit (e.g., "Imagery: NASA/USGS Landsat 9, Jan 14 2025") in the corner. Download locally to `figure-src/assets/` for offline reliability. ### 1e. Choose icons Use Lucide (ISC license) or similar SVG icon library. Define icons as an SVG sprite block at the top of the HTML so they are referenced once and used everywhere via ``. Inline SVG icons in panel headers add polish with zero external dependencies. ## Phase 2: Build the Mockup ### Technical requirements - Single self-contained HTML file per figure type (system mockup and timeline should be separate files, not crammed into one) - Embedded CSS and JavaScript - System fonts preferred for offline reliability; Google Fonts acceptable only with explicit fallback stacks (e.g., Georgia, system-ui, Consolas) - Dark sidebar + light main area, or similar professional layout - Responsive to container size changes (for print/screenshot) ### Key features to include - **View switching** via toolbar buttons (not sidebar — saves horizontal space) - **Screenshot mode** (`CAPTURE` button): hides toolbar and any titles that duplicate the LaTeX caption, tightens spacing, scales up fonts for legibility - **Print CSS** (`@media print`): hides chrome, preserves background colors, forces landscape orientation, allows text wrapping in bars - **Dynamic rendering** (graphs, DAGs): use percentage-based CSS positioning, not absolute pixels, so nodes survive container resize during print ### Visual polish checklist Raw mockups that look like "developer prototypes" undermine credibility. These details make the difference: - **Depth**: subtle box-shadows on cards, layered backgrounds (`linear-gradient` on surfaces) - **Cards**: rounded corners, colored left-border accent for action/alert cards - **Typography hierarchy**: bold subtask numbers in bar labels, monospace for metrics and audit trails, proper weight differentiation - **SVG glow filters** on key nodes (assembly points, critical indicators) - **Progress bars** alongside metric values (not just numbers) - **Status indicators**: colored dots, pulse animations for live status ### Per-thrust layout patterns Vary the layout between thrusts for visual interest: - **Thrust A**: Info panels left | Interactive canvas right - **Thrust B**: Search+results left | Explanation cards right (both info-dense) - **Thrust C**: Canvas left | Timeline+cards right (flipped from A) ### Common pitfalls - Dynamic graph nodes positioned with `px` values break during print — use `%` - `wrapfigure` in LaTeX needs text below it to wrap — place before a long paragraph, never at section end - Large hero images waste space in wide mode — integrate as panel backgrounds at low opacity instead of giving them a full column - Screenshots are vertical by default — must design horizontal layout explicitly - **Wrap-environment collisions**: never place a `wrapfigure` immediately before a `wraptable` or another `wrapfigure` — LaTeX emits collision warnings and forces floats out of position. Separate them with at least one full paragraph of unwrapped text, or convert one to a `figure[t]`/`table[t]` - **`white-space: nowrap` truncates text in print** — bar labels and tags must allow wrapping. Always test the print preview (`Ctrl+P`) before capturing. Remove `nowrap`, add `line-height: 1.2`, and increase row height to accommodate wrapped text. - **Capture mode should hide the HTML title/header** — the LaTeX caption provides the title. Duplicating it in the screenshot wastes vertical space. ## Phase 2b: Timeline / Gantt Figures For work plan timeline figures, use a standalone HTML file with CSS grid. ### Design principles - **CSS grid** with quarter-columns: `grid-template-columns: repeat(16, 1fr)` for a 4-year / 16-quarter layout - **Phase bars spanning multiple quarters** — not one bar per quarter. Use `grid-column: N / M` to span consecutive phases as single continuous blocks. - **Stagger start times** to show dependencies. Not all thrusts start Q1. If Thrust 2 depends on Thrust 1 outputs, start Thrust 2's bar in Q2 or Q3. - **Subtask numbers in bar labels** (e.g., "**1.1** WRF-SFIRE calibration") so reviewers can cross-reference to the thrust text. - **Milestone diamonds** at delivery points; solid-fill bars for milestone quarters, bordered-light bars for activity phases. - **Integration row** at the bottom with dark-pill milestone markers spanning across all thrusts (M1: Component demos, M2: End-to-end pipeline, etc.). - **Legend** must match actual bar appearance (light + border for activity, solid for milestone, diamond for marker, dark pill for integration). ### Timeline capture - Click CAPTURE → `Ctrl+P` → Destination: Save as PDF → Layout: **Landscape** → Margins: None → Save. - Insert as `figure[t]` full-width (timelines need the detail). ## Phase 3: Review with Codex Use the `implement-review` skill to send the staged figure to Codex for review. Key review points (apply to both HTML and abstract paths): 1. **Scientific accuracy** — are dataset names, diagnostics, and workflow steps plausible for the target domain? 2. **Visual differentiation** — do the component views look distinct? 3. **Legibility at print size** — will fonts survive at `0.55\textwidth`? 4. **Branch coverage** — if the system has multiple modes (e.g., zero-vehicle vs HV-owning), does the caption explicitly label which branch is shown? 5. **Figure cross-references** — every figure must have a `Figure~\ref{}` callout in the prose. Figures without cross-references feel decorative. Additional review points for the **abstract path**: 6. **Arrow routing** — do all arrows connect at correct node anchors? No floating or misaligned endpoints. 7. **No dashboard aesthetic** — the figure should read as a research diagram, not a product UI. 8. **Vector output** — PDF/SVG output is vector, not rasterized. Iterate based on feedback. Typical: 2-3 rounds. ## Phase 4: HTML Capture and Insert ### Capture workflow 1. Open the mockup in Chrome 2. Click the view button for the target thrust (e.g., COORDINATOR) 3. Click `CAPTURE` to hide toolbar and titles 4. `Ctrl+P` → Save as PDF (landscape, no margins) for **vector output**, or take a screenshot for PNG 5. Save as `figure/thrustN.pdf` (or `.png`) **Prefer PDF** — text and SVG elements stay vector (sharp at any zoom). Only the embedded satellite imagery stays raster. Drop the file extension in `\includegraphics` so LaTeX auto-selects the best available format: ```latex \includegraphics[width=0.55\textwidth]{figure/thrust4-coord} ``` ### Trim white margins with `pdfcrop` Browser-exported PDFs have full-page white margins that waste space in LaTeX. Use `pdfcrop` (bundled with TeX Live) to trim to the content bounding box. ```bash pdfcrop figure/timeline.pdf figure/timeline-trimmed.pdf pdfcrop --margins 4 figure/thrust1.pdf figure/thrust1-trimmed.pdf ``` **Always keep the original and write to a separate `-trimmed` file.** This preserves the full-page source for re-trimming with different margins later. Use the trimmed file in `\includegraphics`. - `pdfcrop` uses Ghostscript for bounding box detection, which is reliable for both vector and raster content. - Default padding is 0 bp. Use `--margins N` to add N bp on all sides (2-4 is typical for proposal figures). - Do not attempt pixel-based or metadata-based trimming with PyMuPDF or similar — these methods frequently misdetect content bounds on browser-exported PDFs. ### LaTeX insertion Default to `wrapfigure` at **0.55–0.56\textwidth**: ```latex \begin{wrapfigure}{r}{0.56\textwidth} \vspace{-1.2em} \centering \includegraphics[width=0.55\textwidth]{figure/thrust1} \caption{\textbf{Thrust 1 title.} Brief description of what the screenshot shows, referencing left and right panels. If the system has multiple modes, state which mode is shown (e.g., ``zero-vehicle branch; the HV-owning branch provides departure/route guidance'').} \label{fig:thrust1} \vspace{-1.4em} \end{wrapfigure} ``` Place the `wrapfigure` before a paragraph with 10+ lines of text below it. Never place at the end of a section. For timelines, use full-width `figure[t]`: ```latex \begin{figure}[t] \centering \includegraphics[width=\textwidth]{figure/timeline} \caption{\textbf{Four-year work plan and integration timeline.} Colored bars show per-thrust activities by quarter; diamonds mark milestones; bottom row shows integration checkpoints (M1--M4).} \label{fig:timeline} \vspace{-1em} \end{figure} ``` ### Motivation figure For a cross-domain motivation figure (e.g., "spatio-temporal data spans multiple national-priority domains"): 1. Source 3-4 images from federal agencies (NASA, NOAA, USGS, USDA) 2. Ensure all images have the same aspect ratio (e.g., all 3:2 from NASA Earth Observatory) 3. Use `\subfloat` with `height=` for equal-height tiling 4. Cite data sources with `@misc` bib entries using institutional authors 5. Reference each panel in the opening paragraph prose ## Output Checklist ### HTML mockup path - [ ] HTML mockup(s) in `figure-src/` with all assets in `figure-src/assets/` - [ ] Separate HTML files for system mockup vs timeline (not combined) - [ ] View-switching buttons for multi-interface systems - [ ] Print preview tested — text wraps, no truncation, landscape orientation - [ ] Screenshot PNG/PDF files in `figure/` (originals kept, trimmed copies via `pdfcrop`) ### Abstract figure path - [ ] Generation script (`.mjs` for skia-canvas, `.tex` for TikZ, `.jsx` for Illustrator) in `figure-src/` - [ ] Vector output (PDF/SVG) in `figure/` — no browser capture needed - [ ] Arrow endpoints anchored to correct node edges, no drift - [ ] No dashboard aesthetic (no card shadows, no pills/chips, no emoji) - [ ] Professional typography (system sans-serif or serif, no playful fonts) ### Both paths - [ ] `wrapfigure` (0.55–0.56) or `figure[t]` environments in tex files - [ ] `Figure~\ref{}` callouts in the prose for every figure - [ ] Captions describing visible content with explicit branch/mode labeling - [ ] Legend swatches match actual bar/card colors in the figure - [ ] Bib entries for any cited data products (NASA, USGS, etc.) - [ ] Codex review passed (scientific accuracy, legibility, differentiation)