CI Mockup Figure

CI Mockup Figure

Overview

For Yue Zhao's paper and proposal figures, understanding and imitating the confirmed gallery references is the top design priority. Before layout or styling, resolve editable-figure and follow its references/gallery/index.md#required-preference-first-design. Inspect images and feedback, state the reference-to-design mapping, implement it, and compare the rendered output against those images. Revise unmet preference requirements before delivery. Current task instructions, scientific correctness, required output constraints, and an established document palette or figure-series identity govern; generic density, color, and icon defaults below must yield to confirmed preferences. For another user, use that user's confirmed preferences.

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. Three 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.
• README / Markdown hero path (README / Markdown Target section): same HTML build phase, but capture via headless Chrome to a PNG and embed it as a Markdown image referencing assets/fig.png. Requires larger type, higher content density, and one dominant focal element -- the viewer scales the image down to column width.
• 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.

For paper and proposal explanatory figures, especially overviews and Figure 1, resolve editable-figure through the normal skill lookup and read its references/gallery/index.md and relevant images and feedback. Apply selected preference dimensions in the design brief and implementation, preserving meaningful technical detail and domain imagery when liked. Use its durable update procedure for new feedback. For these figures, confirmed preferences override conflicting defaults below for the affected dimension. This includes the pre-flight color rule, light-tint fills, minimal panel elements, and low-opacity or desaturated domain imagery. Preserve the requested HTML, TikZ, or other output format.

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.

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 mockups vs PowerPoint (for timelines)

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

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

Recommended tools (ranked by context)

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:

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: Helvetica or Arial (Nature journal convention). Serif (Georgia) for text-heavy insets. Never Segoe UI, Inter, or geometric narrow variants -- those read as AI-startup product. No emoji.

Avoid the AI-startup look. Segoe UI or Inter combined with an indigo-violet-and-amber palette reads as a product dashboard, not a research figure. For scientific figures:

• Font: Helvetica or Arial
• Palette: NPG / ggsci convention -- coral #E64B35, slate-blue #3C5488, teal #00A087, salmon #F39B7F
• Avoid: indigo or violet as a primary color; gradient bars; pill buttons; heavy drop shadows

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.

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.

README-hero figures

README and documentation hero figures differ from paper figures. Markdown viewers scale the PNG to the content column (roughly 700-900 px on GitHub), so design for the scaled-down view:

• Type larger than in a paper figure. Labels legible at 0.55\textwidth will be too small in a 700 px GitHub column. Increase all font sizes by at least 1.5x relative to a paper figure.
• Fill the frame. Target >80% content fill. Large empty margins waste limited column area.
• One dominant focal element. A large keystone number, score, or pipeline diagram -- something readable in under two seconds at thumbnail size.
• Capture with headless Chrome (see README / Markdown Target section); no pdfcrop, no LaTeX environment.

Pre-flight Checklist

Before the first render, verify all of the following:

• Flat fills only. No gradients on bars, panels, or backgrounds.
• No drop shadows.
• No pill-shaped buttons; border-radius <= 4 px on any container.
• Hairline borders (1px solid) are fine. Decorative glows and gradient borders are not.
• Font is Helvetica or Arial. Not Segoe UI, Inter, or geometric narrow variants.
• Color is reserved for data differentiation. Cut decorative or structural color.
• No indigo or violet primary (reads as AI-startup palette).

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:

--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 <svg><use href="#icon-name"/></svg>. 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)