sci-figure-gen

name: sci-figure-gen description: > Generate publication-quality scientific figures (SVG) from paper text/drafts. Use this skill whenever the user wants to create a scientific diagram, figure, schematic, pathway diagram, experimental workflow, study design overview, or data visualization placeholder from manuscript text. Triggers include: "make figure X from my paper", "generate a diagram for this method section", "create a schematic of the workflow", "draw the pathway", or any request to turn scientific text into a visual figure. Also triggers when the user pastes paper content and asks for a specific figure number, or wants to visualize experimental designs, molecular pathways, or study architectures. Even if the user just says "figure 1" or "make me a diagram" in the context of scientific writing, use this skill. Also triggers for: "generate the figure legend", "recreate this figure" (image → JSON reverse mode), "use same style as fig X", or journal-specific formatting ("format for Nature/Cell").

Scientific Figure Generator

Turn manuscript text into publication-quality SVG figures through a structured JSON intermediate.

Think of it like reverse transcription: instead of image → JSON → image (like Vision-to-JSON), this is text → JSON → SVG. The JSON intermediate acts like a cDNA library — a structured, editable representation you can "amplify" into different visual outputs.

Workflow Overview

Forward Mode (default): Text → JSON → SVG

Paper text + figure request
        ↓
   [1] Parse & Plan — extract entities, relationships, layout intent
        ↓
   [2] Generate JSON — structured figure description (the "cDNA")
        ↓
   [3] Present JSON + Render SVG — show both, offer editing
        ↓
   [4] Edit Loop — user tweaks → update JSON → re-render SVG
        ↓
   [5] Final — save .json + .svg + optional legend text

Reverse Mode: Image → JSON → SVG

Existing figure image
        ↓
   [1] Analyze — identify elements, positions, colors, labels, flow
        ↓
   [2] Generate JSON — structured description of the original
        ↓
   [3] Present JSON + Render SVG — clean vector reconstruction
        ↓
   [4] Edit Loop — same as forward mode

Auxiliary features (available in both modes):

• Style config: style.json locks palette + typography across all figures in a paper
• Auto legend: generate figure legend text from JSON
• Journal presets: dimension/font constraints for specific journals (see references/journal-templates.md)

Step 1: Parse the Input

When the user provides paper text and a figure request:

1. Read the full text carefully. Identify the section(s) relevant to the requested figure.
2. Extract all entities (molecules, samples, groups, steps, conditions, measurements).
3. Map relationships (arrows, flows, groupings, hierarchies, temporal sequences).
4. Infer the figure type from context:

   • pathway: molecular/signaling pathways, gene regulation cascades, metabolic flows

   • flowchart: experimental protocols, sample processing, analytical pipelines

   • schematic: study design overviews, multi-arm trials, cohort structures

   • datavis_placeholder: charts/plots with labeled axes and placeholder data regions

   • illustrative: cartoon/BioRender-style figures with biological icons (sample tubes, organs, cells, molecules, instruments). These are the most common type in high-impact journals for overview/framework figures.

If ambiguous, ask the user which type fits best before proceeding.

Important: not every figure is a diagram. Many journal figures — especially "panel a" overview schematics — are illustrative, not abstract. They show cartoon representations of real objects: test tubes, tissue blocks, exosomes, DNA helices, sequencing machines, organs, cells. Think BioRender, Graphical Abstracts in Cell, or Nature Reviews figures. When the figure describes a biological or clinical workflow involving physical objects and samples, default to illustrative style unless the user explicitly asks for an abstract diagram.

Step 2: Generate the Figure JSON

Build a JSON object following the schema in references/json-schema.md. Read that file now if you haven't already.

Key principles for the JSON:

• Every visual element gets an explicit entry — no implicit/assumed elements
• Positions use a normalized coordinate system (0-1000 on both axes) so the figure is resolution-independent
• Colors follow a restricted palette suitable for colorblind readers (see palette section in schema)
• Text labels should be concise — abbreviations are fine if defined elsewhere in the paper
• Group related elements with explicit group_id references

The JSON is the "source of truth" — the SVG is just a rendering of it. If the user wants to change something, they change the JSON and re-render.

Step 3: Present the JSON and Enter the Edit Loop

Show the JSON to the user with a brief natural-language summary of what the figure contains. Then ask if they want to render or tweak.

Here's the structured description for Figure 2. It shows the miRNA extraction workflow as a 6-step flowchart, from urine collection through library prep to sequencing. The layout flows top-to-bottom with a branch at the QC step.

Want me to render this as SVG, or would you like to tweak anything first?

If the user says "just do it" or "looks good" — proceed to SVG rendering (Step 4).

The Iterative Edit Loop (Core Mechanic)

The JSON is the single source of truth. Always.

Think of the JSON like source code and the SVG like a compiled binary. You never hand-edit the binary — you change the source, then recompile. This is what makes figures reproducible and iteratively refinable.

The loop works like this:

          ┌─────────────────────────────────┐
          │                                 │
          ▼                                 │
  [JSON] ──→ [Render SVG] ──→ [User reviews]│
                                  │         │
                          "change X"        │
                                  │         │
                          [Update JSON] ────┘
                                  │
                          (repeat until happy)
                                  │
                          "looks good" ──→ [Final SVG saved]

When the user requests a change:

1. Acknowledge what they want changed in plain language
2. Modify the JSON first — show the specific diff (what changed). Don't regenerate the whole JSON, just show the updated section so the user can track what moved.
3. Re-render the SVG from the updated JSON
4. Present the new SVG and ask if they want further tweaks

Important rules for the edit loop:

• NEVER edit the SVG directly. Every visual change must flow through the JSON. No exceptions. This is what keeps things reproducible.
• Keep a mental model of the current JSON state throughout the conversation. If the conversation is long, re-read the last JSON version before making changes.
• When showing JSON diffs, be precise: "I changed node_qc.fill from #56B4E9 to #E69F00 and added a new connector conn_qc_to_fail."
• If a user's request is ambiguous (e.g., "make it more spread out"), translate it into concrete JSON changes and confirm before rendering: "I'll increase spacing between all elements by 40px — that means bumping the y-coordinates of nodes 3-6 down. Sound right?"
• If the user pastes back a modified JSON, accept it as the new source of truth and render from that.

What users commonly want to tweak:

• Layout/spacing ("move X to the left", "more space between steps")
• Colors ("make the QC step orange", "use blue for all sequencing nodes")
• Labels ("rename this to ...", "add sample size n=50")
• Structure ("add a branch here", "remove this step", "split into two panels")
• Connectors ("this should be a dashed arrow", "add an inhibition bar")
• Grouping ("group these steps under 'Sample Prep'")

For each of these, the fix is always: update JSON → re-render SVG.

Step 4: Render the SVG

Generate a clean, publication-quality SVG from the current JSON state. The aesthetic target is Nature/Cell style — think clean lines, restrained colors, generous whitespace, and legibility above all else.

SVG Design Rules

Typography (print-first): Figures get shrunk to journal column widths (often 89mm). Text that looks fine at 800px on screen becomes illegible at print. Design for the smallest expected output size.

• Primary font: Arial or Helvetica (universal availability in journals)
• Main labels: 12-13pt bold — these MUST be readable at single-column width
• Sublabels / annotations: 10-11pt — still readable when printed
• Fine print (axis ticks, method notes): 9pt minimum — below this, don't bother
• NEVER go below 8pt for any text element. If it can't be said in 8pt+, it doesn't belong in the figure — put it in the legend instead.
• All text must be actual SVG <text> elements (not paths) so they remain editable
• When in doubt, make text bigger. Nobody ever complained about readable labels.

Information Density: Figures in high-impact journals are packed. Don't waste space.

• Minimize dead whitespace — every cm² should carry information or aid readability
• Prefer compact layouts: elements closer together with just enough breathing room (15-20px gaps, not 40px)
• Use sublabels and annotations aggressively — they add context without extra boxes
• Group backgrounds should be subtle enough to not eat visual space
• Legends can be tight and small but still 9pt+ text
• If a figure feels "airy" or has large empty zones, compress it. The user will be printing this at 89mm wide — every pixel counts.
• Balance: dense but not cluttered. If elements start overlapping or labels collide, that's too far — split into panels instead.

Colors — Soft but Lively Palette: Use these as your default working palette. Derived from Wong 2011 (Nature Methods), desaturated for elegance but with just enough color to feel alive. The vibe: pastel with a pulse — not washed-out, not screaming.

• Near Black: #2D2D2D (text, primary outlines)
• Dark Gray: #5A5A5A (secondary text, sublabels)
• Soft Orange: #E6B47C
• Soft Blue: #90BCDF
• Soft Teal: #70BAA6
• Soft Yellow: #F1DF8E
• Muted Blue: #7499C1
• Soft Vermillion: #D29583
• Soft Mauve: #C499BA
• Light Gray: #EDEDED (group backgrounds, subtle fills)
• White: #FFFFFF (canvas)

The overall feel should be: cohesive and calm, but each color is clearly distinguishable. If you squint, you see gentle contrast — not a flat gray wash. Never rely on color alone to convey meaning — always pair with shape, pattern, or label.

Layout:

• Minimum margin: 25px on all sides (tight but clean)
• Element spacing: 15-20px between nodes — close enough to feel cohesive, enough to not collide
• Arrow/connector style: straight or single-bend orthogonal lines, arrowhead at end
• For flowcharts: prefer top-to-bottom or left-to-right flow
• For pathways: use biological convention (membrane horizontal, signaling cascades vertical)
• For schematics: spatial grouping with labeled bounding boxes
• Pack elements. If there's a big empty zone, something is wrong — either add information or shrink the canvas.

Shapes by convention:

• Rectangles with rounded corners (rx=5): process steps, experimental procedures
• Ellipses: start/end points, biological entities (genes, proteins)
• Diamonds: decision points, branch conditions
• Dashed borders: optional steps, hypothetical elements
• Double borders: key results or outputs
• Hexagons: external inputs (reagents, kits, instruments)

Connectors:

• Solid arrows: direct flow / causation / activation
• Dashed arrows: indirect effect / hypothetical
• Flat-head (inhibition bar): inhibition / blocking
• Bidirectional arrows: reversible reactions / feedback

Figure dimensions:

• Default canvas: 800×600 for landscape, 600×800 for portrait
• Single-column journal width equivalent: ~800px wide
• Always include a thin border rectangle around the entire figure

SVG Output

Generate the SVG as a .svg file. The file should:

• Have a proper viewBox attribute for scalability
• Use <defs> for reusable arrowhead markers
• Group related elements with <g> tags and descriptive id attributes
• Include a <title> element with the figure caption
• Be self-contained (no external references)

Save the SVG to the outputs directory and present it to the user.

Figure-Type-Specific Guidelines

Illustrative (BioRender-style)

These are cartoon figures showing real biological objects. The goal is to be visually engaging while remaining scientifically accurate. Think Nature Reviews, Cell Graphical Abstracts.

Common visual elements to draw as SVG illustrations:

• Sample tubes (urine: amber/yellow, blood: red, with cap and label)
• Tissue blocks (FFPE: pink rectangle with cross-section texture)
• Exosomes/EVs (small circles with lipid bilayer double-line border)
• miRNA molecules (hairpin loop shapes)
• DNA helix (simplified double helix or stylized strand)
• Organs (simplified cartoon kidney, prostate, bladder outlines)
• Sequencing instruments (simplified box with screen)
• Cells (circular with nucleus, optional membrane proteins)
• Antibodies (Y-shaped)
• Immune cells (T-cell, macrophage silhouettes)

Style guidelines for illustrative figures:

• Use soft, rounded shapes — nothing should look sharp or mechanical
• Slight gradients or subtle shading are OK to give depth (unlike pure diagrams)
• Scale doesn't need to be realistic — a miRNA can be shown large enough to label
• Use consistent stroke width (1-1.5px) across all illustrated elements
• Group related illustrations with light background boxes
• Flow direction should still be clear (arrows connecting illustration groups)
• Labels go outside or below illustrations, connected with thin leader lines if needed
• Keep the overall palette desaturated and cohesive

When to use illustrative vs. diagram:

• If the figure shows a conceptual workflow involving physical objects → illustrative
• If the figure shows abstract data relationships, statistics, or algorithmic logic → diagram
• When in doubt, ask the user: "Do you want this more cartoony/illustrative or more abstract/diagrammatic?"

Pathways

• Represent proteins/genes as rounded rectangles with gene name inside
• Use standard notation: P in circle for phosphorylation, Ub for ubiquitination
• Membrane represented as a double horizontal line
• Nucleus as a large dashed ellipse
• Receptors span the membrane line
• Cascade flows generally top-to-bottom (extracellular → membrane → cytoplasm → nucleus)

Flowcharts

• Each step gets a numbered box
• Sample counts (n=X) shown in small text below step labels
• Time durations shown on connector arrows
• QC/validation steps shown as diamonds branching to "pass" and "fail" paths
• Technical parameters in smaller italic text inside or below boxes

Schematics (Study Design)

• Patient/sample groups as large labeled containers
• Randomization shown as a branching node
• Timeline flows left-to-right
• Intervention arms as parallel tracks
• Collection timepoints as vertical dashed lines crossing all arms
• Sample sizes prominently displayed

Data Visualization Placeholders

• Draw axes with proper labels and units
• Show placeholder data regions (shaded areas, dummy bars, trend lines)
• Include legend box
• Mark where statistical annotations would go (e.g., bracket with "***")
• Use appropriate chart type: bar for comparisons, line for time series, heatmap grid for multi-variable, scatter for correlations, box plots for distributions

Servier Medical Art Icons (Optional)

Servier Medical Art is a free library of 3000+ biomedical illustrations licensed under CC BY 4.0. These are professional-grade SVG icons of organs, cells, molecules, instruments, pathways — basically everything you'd find in BioRender but free.

When to offer: At the start of an illustrative figure, ask the user:

I can draw simplified cartoon icons (built-in), or if you want higher-fidelity biomedical illustrations, I can reference Servier Medical Art icons. Which do you prefer?

How to use Servier icons:

1. The icons are available at https://smart.servier.com/ organized by category (anatomy, biology, chemistry, medical devices, etc.)
2. When the user opts for Servier icons, note in the JSON which elements should use them:

{
  "id": "illus_kidney",
  "type": "illustration",
  "illustration_type": "kidney",
  "servier_icon": {
    "use": true,
    "category": "anatomy/urinary_system",
    "icon_name": "kidney",
    "notes": "Use the simplified cross-section view"
  }
}

3. Since Claude cannot fetch external SVGs at runtime, the workflow is:

   • Claude generates the figure with built-in simplified icons as placeholders
   • The JSON marks which elements should be swapped with Servier icons
   • The user downloads the specific Servier SVGs from smart.servier.com
   • The user (or a follow-up Claude session) swaps the placeholders with the real Servier paths

4. To help the user find the right icons, provide direct category links:

   • Anatomy: https://smart.servier.com/category/anatomy/
   • Cellular biology: https://smart.servier.com/category/cellular-biology/
   • Molecular biology: https://smart.servier.com/category/molecular-biology/
   • Medical devices: https://smart.servier.com/category/medical-devices/
   • Chemistry: https://smart.servier.com/category/chemistry/

Important:

• Always credit Servier in the figure or paper: "Icons adapted from Servier Medical Art (smart.servier.com), licensed under CC BY 4.0"
• The built-in cartoon icons are always the fallback — Servier is an enhancement, not a requirement
• If the user uploads Servier SVG files directly, Claude can extract the path data and embed it into the figure

Edge Cases and Tips

• If the paper text is ambiguous about what goes in a figure, generate the JSON with your best interpretation and flag uncertain elements with "confidence": "low" in the JSON. Tell the user what you assumed.
• For very complex figures (>20 elements), suggest splitting into panels (a, b, c) with a multi-panel layout.
• If the user provides a rough sketch or describes the layout verbally, prioritize their spatial intent over biological convention.
• The JSON is meant to be human-readable. Use descriptive IDs like "node_urine_collection" not "n1".
• Print readability check: Before finalizing, mentally shrink the figure to 89mm wide. Would all text still be legible? If any label would be below ~1.5mm actual height at print, bump it up. This is the single most common rejection reason for figures.
• Pack it tight: A common mistake is making figures too spacious. Journal space is expensive — reviewers and editors appreciate dense, information-rich figures. White space should serve readability, not fill a canvas.

State Management Across Turns

The JSON evolves over the conversation. To keep things sane:

• After each edit, mentally note the current JSON version. If the conversation gets long (5+ edit rounds), re-output the full JSON so both you and the user have a clean checkpoint.
• When the user says "done" or "final version", save both the final JSON and the final SVG. The JSON should be saved as a .json file alongside the SVG so the user can re-edit later in a new conversation.
• If a user starts a new conversation and pastes in a previously generated JSON, treat it as a fresh Step 3 — skip text parsing entirely and go straight into the edit loop or SVG rendering.
• Always name output files descriptively: fig2_mirna_workflow.json and fig2_mirna_workflow.svg, not output.svg.

Paper-Wide Style Config

When working on multiple figures for the same paper, consistency is everything. You don't want Fig 2 in soft blue and Fig 5 in a slightly different soft blue.

On the first figure of a paper, generate a style.json alongside the figure JSON. This locks:

{
  "style_id": "baba_2026_urological",
  "palette": {
    "primary": "#9DC3E6",
    "secondary": "#7DBCAB",
    "accent": "#E8BF8B",
    "alert": "#D49E8D",
    "emphasis": "#F2E5A0",
    "muted": "#7B9EC4",
    "supplementary": "#C9A3BF",
    "background": "#EDEDED",
    "text": "#2D2D2D",
    "subtext": "#5A5A5A"
  },
  "typography": {
    "font": "Arial",
    "title_size": 14,
    "label_size": 12,
    "sublabel_size": 10,
    "annotation_size": 9,
    "absolute_minimum": 8
  },
  "stroke": {
    "default_width": 1,
    "emphasis_width": 1.5,
    "color": "#2D2D2D"
  },
  "illustration_style": {
    "gradient": true,
    "opacity_range": [0.3, 0.8],
    "corner_radius": 5
  },
  "journal_template": null
}

On all subsequent figures in the same conversation, reuse this style.json. If the user starts a new conversation for the same paper, they can paste it back in.

If the user says "use the same style as Fig 4a" or "match the previous figures", check for an existing style.json before generating.

Auto Figure Legend Generator

After generating the final SVG, offer to auto-generate the figure legend text from the JSON. The JSON already contains every element's label, sublabel, type, and relationships — so the legend writes itself.

How to generate:

1. Start with a one-sentence overview derived from figure_meta.caption
2. Walk through the figure left-to-right or top-to-bottom, describing what each major section shows
3. Define abbreviations on first use
4. Reference element labels and group labels from the JSON
5. End with a methods-style note if relevant (e.g., "Classifiers were trained using L2 logistic regression with nested cross-validation.")

Example output:

Fig. 4a. Schematic of the prediction framework for cancer-specific genomic alterations using urinary EV-derived miRNA profiles. Urine samples were collected and processed for EV-derived miRNA extraction (left). Sample-matched tumor tissue was analyzed by targeted sequencing using the PleSSision panel. Normalized miRNA expression profiles and genomic alteration status were integrated per patient for RCC (n = 87) and UC (n = 98) cohorts. L2-penalized logistic regression classifiers were trained per gene and per cancer type to predict driver mutation status: VHL, PBRM1, BAP1, and SETD2 for RCC; KDM6A, KMT2D, FGFR3, and TP53 for UC.

Present this to the user for editing — they know the clinical context better than Claude does. But the skeleton saves them 80% of the writing time.

Reverse Mode (Image → JSON)

If the user uploads an existing figure image instead of paper text, switch to reverse mode:

1. Analyze the image visually — identify all elements, their spatial positions, colors, shapes, text labels, connectors, and groupings
2. Generate a JSON that describes the figure using the same schema as forward mode
3. Present the JSON for review
4. On approval, re-render as SVG (which gives them a clean vector version of their raster figure)

When this is useful:

• Iterating on a figure from a previous paper
• Recreating a figure from a reference paper in a consistent style
• Converting a hand-drawn sketch or whiteboard photo into structured SVG
• Upgrading an old PowerPoint figure into publication quality

Important: This is about capturing the structure and layout, not pixel-perfect reproduction. The goal is to get the JSON right so the user can then iterate using the normal edit loop. Think of it like cloning a plasmid — you're getting the insert, not the exact methylation pattern.

If the image is too complex or ambiguous, flag uncertain elements with "confidence": "low" and ask the user to clarify.

Journal Template Presets

Different journals have different figure dimension and formatting requirements. Rather than auto-applying a template (which is risky — requirements change and context matters), ask the user at the start what journal they're targeting, then load the appropriate constraints.

How to ask:

Are you targeting a specific journal? I can set up figure dimensions and constraints to match their requirements. Otherwise I'll use sensible defaults (800×600 landscape).

Available presets (stored in references/journal-templates.md):

When a journal is selected:

• Set canvas dimensions to match the target column width (convert mm to px at 300 DPI)
• Enforce minimum font size
• Adjust element density so nothing looks cramped at print size
• Store the choice in style.json so all figures in the paper use the same template
• Remind the user which column size they're working with

Don't auto-apply. The user might want a single-column figure for one panel and double-column for another. Always confirm.

Read references/journal-templates.md for full specs if the user picks a specific journal.

Quick Reference: The Contract

1. User provides: paper text + figure request (OR a previously generated JSON)
2. Claude produces: structured JSON describing every visual element — ALWAYS
3. Claude renders: SVG from the JSON — ALWAYS delivered together with the JSON
4. User reviews: approves or requests changes
5. Claude updates: JSON first, always → then re-renders SVG
6. Repeat 4-5 until the user is satisfied
7. Final output: both .json and .svg files saved to outputs

CRITICAL: Never skip the JSON. Even if the user says "just make it" or "go straight to SVG", always produce and show the JSON first. The JSON IS the figure — the SVG is just a view of it. This applies to both diagram and illustrative figure types. No exceptions. If you render an SVG without showing the JSON, the entire edit loop breaks because there's no source of truth to modify.