medsci-skills 4.1.0

package/skills/make-figures/references/figure_specs.md

@@ -0,0 +1,291 @@
+# Figure Specifications Reference
+
+## Journal Dimension Requirements
+
+| Journal | Single Column | 1.5 Column | Double Column | Full Page | Max Height |
+|---------|--------------|------------|---------------|-----------|------------|
+| AJR | 3.3 in (84 mm) | 5.0 in (127 mm) | 6.83 in (174 mm) | 6.83 x 9.19 in | 9.19 in |
+| Radiology | 3.37 in (85.6 mm) | 5.04 in (128 mm) | 6.83 in (173.5 mm) | 6.83 x 9.19 in | 9.19 in |
+| Radiology: AI | 3.37 in (85.6 mm) | 5.04 in (128 mm) | 6.83 in (173.5 mm) | 6.83 x 9.19 in | 9.19 in |
+| European Radiology | 3.35 in (85 mm) | -- | 6.85 in (174 mm) | 6.85 x 9.13 in | 9.13 in |
+| KJR | 3.27 in (83 mm) | -- | 6.89 in (175 mm) | 6.89 x 9.21 in | 9.21 in |
+| **Default** | **3.5 in (88 mm)** | **5.0 in (127 mm)** | **7.0 in (178 mm)** | **7.0 x 9.5 in** | **9.5 in** |
+
+### Notes
+
+- Dimensions are the maximum printable area; figures should not exceed these.
+- When in doubt, use single-column width (3.5 in) for simple plots and double-column (7.0 in) for complex or multi-panel figures.
+- Height is flexible but should not exceed the max height listed above.
+
+---
+
+## DPI Requirements
+
+| Content Type | Minimum DPI | Recommended DPI | Notes |
+|-------------|-------------|-----------------|-------|
+| Line art (diagrams, flow charts) | 600 | 1200 | Vector PDF preferred |
+| Halftone (photographs, medical images) | 300 | 300 | TIFF or PNG |
+| Combination (line art + halftone) | 600 | 600 | |
+| Color figures | 300 | 300 | |
+| Review/presentation | 150 | 300 | PNG acceptable |
+
+---
+
+## File Format Requirements by Journal
+
+| Journal | Preferred Format | Accepted Formats | Notes |
+|---------|-----------------|------------------|-------|
+| AJR | TIFF | TIFF, EPS, PDF, JPEG | TIFF LZW compression; JPEG only for photos |
+| Radiology | TIFF | TIFF, EPS, PDF, PNG | EPS for vector; TIFF for raster |
+| Radiology: AI | PDF | PDF, TIFF, EPS, PNG | PDF preferred for vector graphics |
+| European Radiology | TIFF | TIFF, EPS, PDF | EPS or PDF for line art |
+| KJR | TIFF | TIFF, JPEG, PPT | PPT accepted but not recommended |
+| **Default** | **PDF + PNG** | PDF (vector), PNG (raster) | Always produce both |
+
+---
+
+## Color Palettes
+
+### Wong Colorblind-Safe Palette (Default)
+
+| Index | Name | Hex | Use |
+|-------|------|-----|-----|
+| 0 | Black | `#000000` | Text, axes, reference lines |
+| 1 | Orange | `#E69F00` | Primary category 1 |
+| 2 | Sky Blue | `#56B4E9` | Primary category 2 |
+| 3 | Bluish Green | `#009E73` | Primary category 3 |
+| 4 | Yellow | `#F0E442` | Highlight (use sparingly) |
+| 5 | Blue | `#0072B2` | Primary model/group |
+| 6 | Vermillion | `#D55E00` | Secondary model/group |
+| 7 | Reddish Purple | `#CC79A7` | Tertiary model/group |
+
+```python
+WONG = ['#000000', '#E69F00', '#56B4E9', '#009E73',
+        '#F0E442', '#0072B2', '#D55E00', '#CC79A7']
+```
+
+### Sequential Palettes (Heatmaps)
+
+| Use Case | Matplotlib Colormap | Direction |
+|----------|-------------------|-----------|
+| Positive values only | `Blues`, `Greens`, `Oranges` | Light to dark |
+| Diverging (centered at 0) | `coolwarm`, `RdBu_r` | Negative=blue, positive=red |
+| Correlation matrix | `coolwarm` | -1 to +1 centered |
+| Agreement matrix | `YlOrRd` | Low=yellow, high=red |
+| Confusion matrix | `Blues` | Low=white, high=blue |
+| p-value heatmap | `Reds_r` | Significant=dark |
+
+### Rules
+
+- Never rely on color alone; combine with line style, marker shape, or hatching.
+- Test figures in grayscale to ensure readability.
+- Avoid pure red (#FF0000) and pure green (#00FF00) adjacent to each other.
+
+---
+
+## Font Size Table
+
+| Element | Size (pt) | Weight | Font Family |
+|---------|-----------|--------|-------------|
+| Figure title (rare, prefer caption) | 10 | Bold | Arial / Helvetica |
+| Axis label | 9 | Regular | Arial / Helvetica |
+| Tick label | 8 | Regular | Arial / Helvetica |
+| Legend text | 8 | Regular | Arial / Helvetica |
+| Annotation text | 8 | Regular | Arial / Helvetica |
+| Panel label (A, B, C) | 12 | Bold | Arial / Helvetica |
+| Inset text | 7 | Regular | Arial / Helvetica |
+| Table text (in figure) | 7-8 | Regular | Arial / Helvetica |
+
+### Rules
+
+- Minimum readable size after print: 6 pt.
+- All text in figures must be embedded (not rasterized) for vector formats.
+- Use `plt.rcParams['font.family'] = 'sans-serif'` and `plt.rcParams['font.sans-serif'] = ['Arial', 'Helvetica']`.
+
+---
+
+## Common Figure Layouts
+
+### Single Panel
+
+```
++-----------+
+|           |
+|   Plot    |
+|           |
++-----------+
+```
+- Width: single column (3.5 in) or double column (7.0 in)
+- Height: proportional, typically 1:1 or 4:3 aspect ratio
+- Use: ROC curve, calibration plot, KM curve, Bland-Altman
+
+### 2-Panel Horizontal
+
+```
++-----+-----+
+|  A  |  B  |
++-----+-----+
+```
+- Width: double column (7.0 in), each panel ~3.3 in
+- Height: 3.0-3.5 in
+- Use: comparing two related plots (e.g., ROC for two endpoints)
+
+### 2-Panel Vertical
+
+```
++-----+
+|  A  |
++-----+
+|  B  |
++-----+
+```
+- Width: single column (3.5 in)
+- Height: 6.0-7.0 in
+- Use: same variable, different conditions (e.g., training vs test set)
+
+### 2x2 Grid
+
+```
++-----+-----+
+|  A  |  B  |
++-----+-----+
+|  C  |  D  |
++-----+-----+
+```
+- Width: double column (7.0 in), each panel ~3.3 in
+- Height: 6.0-7.0 in
+- Use: four related analyses (e.g., subgroup comparisons)
+
+### 3-Panel Horizontal
+
+```
++---+---+---+
+| A | B | C |
++---+---+---+
+```
+- Width: double column (7.0 in), each panel ~2.1 in
+- Height: 2.5-3.0 in
+- Use: three conditions or progressive stages
+
+### Unequal Panels (GridSpec)
+
+```
++---------+----+
+|         | B  |
+|    A    +----+
+|         | C  |
++---------+----+
+```
+- Use `matplotlib.gridspec.GridSpec` for custom layouts
+- Use: main result (A) with supporting details (B, C)
+
+---
+
+## Caption Writing Guidelines
+
+### Structure
+
+1. **Sentence 1**: What the figure shows -- figure type and key finding.
+2. **Sentences 2-3**: Define symbols, abbreviations, colors, and line styles.
+3. **Sentence 3-4**: State sample sizes, statistical tests, significance levels.
+4. **Final sentence**: Interpretation aid (if not self-evident from the plot).
+
+### Format
+
+```
+Figure {N}. {Description starting with capital letter, ending with period.}
+```
+
+- No bold title. No title case (except proper nouns and abbreviations).
+- Use sentence case throughout.
+- Spell out abbreviations on first use in the caption.
+
+### Multi-Panel Captions
+
+```
+Figure {N}. {Overall description.} (A) {Panel A description.} (B) {Panel B description.}
+```
+
+### Examples
+
+**ROC Curve:**
+> Figure 2. Receiver operating characteristic curves for the multi-agent validation pipeline. The area under the curve was 0.92 (95% CI: 0.89-0.95) for the full pipeline and 0.84 (95% CI: 0.80-0.88) for the single-agent baseline (DeLong test, p = 0.003). The dashed diagonal line represents chance performance (AUC = 0.5). AUC = area under the curve, CI = confidence interval.
+
+**Flow Diagram:**
+> Figure 1. Study flow diagram following the Standards for Reporting Diagnostic Accuracy Studies (STARD) 2015 guidelines. Numbers in each box represent the count of Anki flashcards at each stage of the validation pipeline.
+
+**Multi-Panel:**
+> Figure 3. Agreement analysis between human reviewers and the multi-agent pipeline. (A) Bland-Altman plot showing the difference in quality scores between reviewer 1 and the pipeline against their mean. Horizontal dashed lines indicate the mean difference and 95% limits of agreement. (B) Scatter plot of reviewer 1 versus pipeline scores with the line of identity (dashed).
+
+---
+
+## Figure Numbering Conventions
+
+- Number figures sequentially as they appear in the text (Figure 1, Figure 2, ...).
+- Supplemental figures: Figure S1, Figure S2, ...
+- Reference every figure at least once in the main text.
+- Place figures after first mention (or at end, per journal preference).
+- Do not include a figure title inside the plot area; use the caption below instead.
+
+---
+
+## Flow Diagram Tool Selection (STROBE / CONSORT / PRISMA / STARD)
+
+All reporting-guideline flow diagrams use a single canonical pipeline: `scripts/generate_flow_diagram.R` (DiagrammeR DOT → DiagrammeRsvg → rsvg).
+
+### Why this stack
+
+| Requirement | Requirement detail | DiagrammeR + rsvg |
+|---|---|---|
+| Vector PDF (editable, journal-grade) | Radiology/NEJM/Eur Radiol require EPS/AI/PDF | **True vector via `rsvg_pdf()`** |
+| 300 / 600 / 1200 dpi PNG | RSNA line-art = 1200 dpi; Eur Radiol = 300–1000 | **Arbitrary DPI via `rsvg_png(width=...)`** |
+| Arial font embedded | AMA/RSNA style | `fontname="Arial"` enforced in DOT header |
+| Single-color monochrome outline | BMJ/Annals IM convention | `color=black, fillcolor=white, style=filled` |
+| Auto-overlap resolution | Labels change size; manual coords fail | Graphviz `dot` hierarchical engine |
+| 4 reporting guidelines in one tool | Avoid stack sprawl | Generic DOT template switch |
+
+### Why not the obvious alternatives
+
+| Rejected tool | Reason |
+|---|---|
+| matplotlib `FancyBboxPatch` (manual coords) | Overlap on label change; DOCX embed distortion. Root cause of an STROBE Figure 1 rework. |
+| D2 + post-processing | Weak Arial enforcement; PNG needs 85% vertical compression hack; font-size must be manually set 20–24. Retained as legacy fallback only. |
+| R `consort` v1.2.2 | CONSORT/STROBE only; STARD/PRISMA not covered; box style parameters not officially exposed (requires gpar override). |
+| R `PRISMA2020` v1.1.1 | `PRISMA_save()` uses webshot → PDF rasterized; no DPI parameter. Not suitable for journal submission. |
+| Mermaid / PlantUML | Font control weak; hard to enforce Arial + monochrome outline. |
+
+### PRISMA 2020 compliance
+
+The generic DOT template in `generate_flow_diagram.R` implements the PRISMA 2020 structure (two identification streams, duplicates-removed box, title/abstract screening, full-text retrieval, full-text assessment, final inclusion) and can reproduce the official template shape. When a journal explicitly requires use of the PRISMA2020 R package or Shiny app for provenance, run that tool separately; the DiagrammeR pipeline is the default for all other submissions.
+
+### File outputs
+
+Every render emits three files at the same prefix:
+
+```
+<prefix>.pdf        true vector (journal submission, figure_manifest primary)
+<prefix>.png        300 dpi (2400 px wide; review copy, DOCX embed)
+<prefix>_600.png    600 dpi (4800 px wide; RSNA/Eur Radiol line-art)
+```
+
+### System dependency
+
+`brew install librsvg` (macOS; one-time). On Linux: `apt-get install librsvg2-bin`.
+
+## Central Illustration Dimensions
+
+Used by the JACC family and all journals that distinguish a Central Illustration from a Visual Abstract (Fuster V, Mann DL. *JACC.* 2019;74(22):2816–2820). See `references/jacc_central_illustration_principles.md`.
+
+| Spec | Value |
+|---|---|
+| PPTX slide size | 10 × 7.5 in (4:3 standard) |
+| Content figure area | ~4 × 4.2 in (top-center of slide) |
+| Citation textbox | 9.4 × 0.5 in at (0.4, 5.3) |
+| Content figure resolution | ≥ 600 DPI PNG; PDF vector preferred |
+| Font | Sans-serif (Arial or equivalent), ≥ 9 pt at print scale |
+| Color | Color allowed; figure should remain interpretable in grayscale |
+| Visual zones in content figure | 1–3 (enforced by `--type central-illustration`) |
+| Total label word count | ≤ 30 |
+| Numerical highlights | ≤ 4 |
+
+**Do not pre-render**: the red outer border and the blue "CENTRAL ILLUSTRATION:" header bar visible in published JACC issues are applied by JACC editorial after acceptance. Authors submit only the content figure and citation footer.

package/skills/make-figures/references/flow_diagram_lessons.md

@@ -0,0 +1,164 @@
+# Flow Diagram Production — Hard-Earned Lessons
+
+> **Triggered from**: SKILL.md Step 4b (Critic Loop). Read this file when
+> generating PRISMA / CONSORT / STARD / STROBE diagrams, especially before a
+> circulation round with senior co-authors.
+>
+> **Source**: Distilled from a multi-revision meta-analysis project where
+> Figure 1 (PRISMA flow) went through four major iterations before clearing
+> a senior reviewer round. Each lesson maps to a concrete failure mode.
+
+Flow diagrams look simple but consume disproportionate revision time. The
+underlying causes are rarely "wrong numbers" — they are template fidelity,
+PDF export fidelity, and version drift between the diagram and the
+manuscript. The five lessons below address each in turn.
+
+---
+
+## Lesson 1: Use the official template once a senior reviewer is in the loop
+
+**Failure mode**: Custom Graphviz / DiagrammeR layout offers more freedom
+(left-aligned bullets via `\l`, `penwidth=1.8` highlights on the analytic
+cohort, free positioning of side-boxes). Senior systematic-review reviewers,
+however, expect the **PRISMA 2020 standard layout** as published by the
+PRISMA Statement group. A custom layout reads as "the authors did not follow
+the guideline," even when every count is correct.
+
+**Resolution**:
+
+- Prototype freely with Graphviz / DiagrammeR for early drafts.
+- **Switch to an official template before circulation.** The R package
+  `PRISMA2020` (Haddaway et al.) renders the canonical layout from a CSV.
+  Equivalent canonical templates exist for CONSORT 2010, STARD 2015, and
+  STROBE.
+- If the official template lacks a feature you need (e.g., a third
+  exclusion sub-branch), prefer to fold the detail into the existing slots
+  rather than restructure.
+
+**Cross-link**: `critic_rubrics/flow_diagram.md` — "Official template
+fidelity" check.
+
+---
+
+## Lesson 2: PDF export — the VML fallback breaks under headless converters
+
+**Failure mode**: The official PRISMA 2020 docx contains VML (Vector Markup
+Language) fallback pairs that older Word versions render. When converted to
+PDF via headless LibreOffice (`soffice --headless --convert-to pdf`), the
+phase labels can shift by several pixels, columns misalign, and on some
+systems text reflows out of its box. The PDF looks "almost right" — the
+kind of bug that survives a quick visual scan.
+
+**Resolution by platform**:
+
+| Platform | Approach | Notes |
+|---|---|---|
+| **macOS** | AppleScript driving Microsoft Word for Mac | Deterministic native render; can be invoked headlessly via `osascript`. |
+| **Windows** | PowerShell / VBScript COM driving Word | `Word.Application` object → `.SaveAs2` with `wdFormatPDF`. |
+| **Linux / CI** | Office Online Server (paid), or commit a pre-rendered PDF produced on macOS / Windows | Headless LibreOffice is **not** safe for VML-heavy templates. |
+| Any platform (fallback) | Open in desktop Word → "Save As PDF" manually | Slow but always correct; document the manual step in the manifest. |
+
+**Verify visually**: After export, open the PDF and the source docx
+side-by-side. Compare phase-label positions, column widths, and the Y
+position of every numeric box. If anything has shifted, do not submit that
+PDF.
+
+---
+
+## Lesson 3: docx XML editing requires entity escape
+
+**Failure mode**: A docx file is a ZIP archive containing
+`word/document.xml`. Programmatic placeholder substitution (e.g., replacing
+`{{n_screened}}` with `1,234` plus a comment, or `{{study_title}}` with a
+title containing `&`) by raw `str.replace` produces invalid XML. Word then
+shows "We're sorry, we can't open the file because there's a problem with
+the contents." dialog on next open, or — worse — opens with a "repair"
+prompt that silently drops content.
+
+**Resolution**:
+
+- Use an entity-escaping helper before injecting any user-provided string.
+  Python: `xml.sax.saxutils.escape(value)`. JavaScript: `he.encode` or a
+  small regex (`& → &amp;`, `< → &lt;`, `> → &gt;`).
+- High-risk fields:
+  - Study titles containing `&` (`Smith & Jones, 2020`).
+  - Range strings containing `<` or `>` (`age <5 years`, `loss >50%`).
+  - Author lists with apostrophes (`O'Brien`).
+- After substitution, validate with `python -c "import zipfile,
+  xml.etree.ElementTree as E;
+  E.fromstring(zipfile.ZipFile('out.docx').read('word/document.xml'))"`.
+  An exception means the docx is broken.
+
+---
+
+## Lesson 4: VML fallback templates need sequential placeholder maps
+
+**Failure mode**: The official PRISMA 2020 docx duplicates each numeric box
+as a `<w:t>` pair: a primary text element plus a VML fallback. Branch
+ordering in XML DOM does **not** match rendering order — the "Other"
+identification branch and the "Database" branch are interleaved in the
+document, and the VML fallbacks appear elsewhere again. A naive
+"replace each placeholder with the next number" loop misaligns most boxes.
+
+**Resolution**:
+
+1. Dump every `<w:t>` in document order with a script
+   (`python -c "from docx import Document; ..."` or direct XML walk).
+2. Annotate each `<w:t>` with column / branch / role
+   (`identification.databases.records_n`, `identification.databases.records_n.fallback`).
+3. Build a static `VALUES` list with one entry per `<w:t>` slot, **with a
+   comment per slot** documenting what it represents.
+4. Validate by filling all slots with a sentinel value (e.g., `999`) and
+   visually checking that all 60+ boxes show `999` in the rendered PDF
+   before re-running with real data.
+
+This sentinel-render is cheap (one extra `999` pass) and catches mapping
+errors before they propagate into a circulation round.
+
+---
+
+## Lesson 5: Freeze figure versions alongside manuscript versions
+
+**Failure mode**: A reviewer asks about Figure 1 in revision round 2, but
+the figure file in `manuscript/figures/figure_1.pdf` was edited in place
+between rounds. The version visible in v3 of the manuscript no longer
+exists, and tracing what changed requires diffing PDFs (lossy and slow).
+
+**Resolution**:
+
+- Treat figures as part of the manuscript artifact — they freeze with each
+  manuscript version under the **`v_N` rule** (manuscript-versioning
+  protocol).
+- Maintain `figures/v{N}/` directories. Each contains the source script
+  (`generate_figure_1.R`), the input data CSV, and the rendered docx + PDF
+  pair.
+- An `INDEX.md` at `figures/INDEX.md` maps figure version ↔ manuscript
+  version, e.g.:
+  ```
+  | Manuscript | Figure 1 | Figure 2 | Figure 3 |
+  |---|---|---|---|
+  | v3 (circulated 2025-09-01) | figures/v3/figure_1.pdf | figures/v3/figure_2.pdf | figures/v2/figure_3.pdf |
+  | v4 (submitted 2025-10-15)  | figures/v4/figure_1.pdf | figures/v3/figure_2.pdf | figures/v3/figure_3.pdf |
+  ```
+- **Never edit `figures/v3/*.pdf` after circulation.** Branch to
+  `figures/v4/` and rebuild.
+
+---
+
+## When to use which approach
+
+| Stage | Tool | Output | Risk if you skip |
+|---|---|---|---|
+| Early draft | DiagrammeR + Graphviz custom | PNG, fast iteration | None — flexibility wins here |
+| Internal QC | R `PRISMA2020` package or equivalent | Official-template PNG / PDF | Custom layout will be flagged in circulation |
+| Circulation | Filled official-template docx + native-Word PDF (macOS AppleScript / Windows COM) | Frozen docx + PDF pair | Headless export drift; reviewer notices misaligned labels |
+| Submission | `figures/v_N/` frozen pair | Immutable docx + PDF | Edit-in-place breaks the manuscript-figure version map |
+
+---
+
+## Quick cross-references
+
+- `critic_rubrics/flow_diagram.md` — extended critic checklist (rounds T=1…3)
+- `design_principles.md` — communication-first design strategies
+- `figure_specs.md` — journal-specific dimensions and DPI
+- `exemplar_diagrams/{prisma,consort,stard,strobe}/` — reference layouts

package/skills/make-figures/references/jacc_central_illustration_principles.md

@@ -0,0 +1,91 @@
+# JACC Central Illustration — Principles & Layout Spec
+
+Distilled from Fuster V, Mann DL. **The Art and Challenge of Crafting a Central Illustration or Visual Abstract.** *J Am Coll Cardiol.* 2019;74(22):2816–2820. doi:10.1016/j.jacc.2019.10.035
+
+This document is the canonical reference when generating Central Illustrations for JACC, JACC: Asia, JACC: Cardiovascular Imaging, JACC: Heart Failure, JACC: Basic to Translational Science, JACC: CardioOncology, and JACC: Clinical Electrophysiology.
+
+## CI vs Visual Abstract — they are different artifacts
+
+| Aspect | Central Illustration | Visual Abstract |
+|---|---|---|
+| Purpose | Single key finding / take-home message | Methods + Results pictorial summary |
+| Where referenced in paper | End of Results / start of Discussion | Beginning of paper |
+| Methods content | **None** | Required |
+| Audience | Cardiovascular clinicians + readers of the journal issue | Broad including non-specialists / social media |
+| Used by | All JACC family journals + JACC: Asia | Originally JACC: Basic to Translational Science |
+| Text density | Minimal (graphical priority) | More allowed (methods labels) |
+| Bar graphs | OK if they capture entire message | Avoid — use ↑↓ arrows |
+| Default complexity | Simple (1–3 visual zones) | Simple (Q→M→R three blocks) |
+
+If a paper requires *both* a central illustration and a visual abstract (some JACC sister journals), they must convey complementary content; do not duplicate.
+
+## Five Fuster-Mann rules (must pass all)
+
+1. **Know the message.** Decide one finding the figure must convey. Do not stuff in the study design + multiple findings + take-homes — that "causes confusion and excess that does not inform the reader."
+2. **Convey graphically, not textually.** Even a simple Kaplan–Meier curve is acceptable if it captures the entire message. Bar graphs are tolerated if they earn their space.
+3. **Avoid using too much text.** Any text that can be replaced by an icon or arrow should be.
+4. **Avoid secondary messages.** If a viewer cannot state the main finding within 5 seconds of looking at the figure, the figure has too much.
+5. **Simplicity is superior.** Authors "truly struggle with the concept" early; default to fewer panels rather than more.
+
+## CI mode validation rules (enforced by `generate_visual_abstract.py --type central-illustration`)
+
+A submission rejects with a warning if any of the following holds:
+
+| Rule | Threshold | Rationale (Fuster-Mann) |
+|---|---|---|
+| `n_visual_zones` | ≤ 3 | "Simplicity is superior" |
+| `total_label_word_count` | ≤ 30 | "Avoid using too much text" |
+| `methods_terms_present` | none of: `cohort flow`, `inclusion`, `exclusion`, `study design`, `enrollment`, `randomized`, `sample size` | CI ≠ VA; methods belong in VA |
+| `numerical_data_points` | ≤ 4 | "Avoid incorporating secondary messages" |
+
+Override a single rule with `--allow rule=name` and a justification note recorded in the output PPTX speaker notes.
+
+## JACC PPTX layout (verified from official submission templates)
+
+Reference: 4 official JACC PPTX submission files (Figures 1–4 of Fuster-Mann editorial, doi:10.1016/j.jacc.2019.10.035). All four share an identical layout:
+
+| Slot | Type | Position (left, top) inches | Size (W × H) inches | Content |
+|---|---|---|---|---|
+| 1 | TEXT_BOX | (0.4, 5.3) | 9.4 × 0.5 | Citation: `"FirstAuthor et al. JACC YYYY; vol(issue):pages."` |
+| 2 | PICTURE | (3.0, 0.8) | 4.0 × 4.2 | **Author-provided content figure** (the only thing the author owns) |
+| 3 | TEXT_BOX | (0.4, 7.0) | 4.1 × 0.5 | Reserved (often empty in production templates) |
+| 4 | PICTURE | (7.3, 6.7) | 2.7 × 0.8 | JACC family logo (placeholder; supplied by editorial) |
+
+Slide size: **10 × 7.5 inches (4:3)**. Background white.
+
+The red border + the blue "CENTRAL ILLUSTRATION:" header bar visible in published JACC issues are **applied by the JACC editorial team after acceptance** — authors should not pre-render those elements in their submission.
+
+Authors submit:
+- Slot 1 (citation text)
+- Slot 2 (the content figure as PNG/TIFF, ≥600 DPI, content area ~4 × 4.2 in at print)
+
+Slots 3 and 4 stay as placeholders.
+
+## Author-provided content figure spec
+
+| Spec | Value |
+|---|---|
+| Aspect ratio | ~1:1 to slightly portrait (4 × 4.2 in) |
+| Print resolution | 600 DPI for PNG, vector preferred (PDF) |
+| Font | Sans-serif; minimum 9 pt at print scale |
+| Color | Allowed; high-contrast for grayscale fallback |
+| Visual zones | 1–3 (rule above) |
+| Total label words | ≤ 30 |
+| Numerical highlights | ≤ 4 |
+| Photographs | Allowed (Fuster-Mann Figure 4 example) |
+
+Reference good examples cited in the editorial:
+- *Moccetti F, et al. J Am Coll Cardiol. 2018;72(9):1015–26.* — heart anatomy + 3 concept boxes + vessel cross-section + brain image. Total ~20 words. (Fuster-Mann Figure 1)
+- *Brugada J, et al. J Am Coll Cardiol. 2018;72(9):1046–59.* — 3-column "Diagnosis / Pathophysiology / Management" grid with ECG, sequencing, defibrillator imagery. (Fuster-Mann Figure 2)
+
+## Common author mistakes (rejected examples)
+
+- Embedding the cohort flow / CONSORT-style diagram → that is a study Figure 1 or a Visual Abstract, never a Central Illustration.
+- Side-by-side forest plot + KM curve + heat map → too many secondary messages.
+- Text-heavy "Clinical takeaway" tile boxes summarizing multiple bullets → reduce to one icon-anchored sentence or move to Discussion narrative.
+- Multiple HR/CI/p-value annotations across rows → keep ≤ 4 numerical highlights total.
+- Methodology labels ("Inclusion criteria", "N=...") → CI must not look like Methods.
+
+## Adding a non-JACC cardiology CI template
+
+Other journals using a CI-style figure (Circulation family, EHJ, JAHA) tend to follow the same simplicity rules. For these, reuse the Fuster-Mann 5 rules above and the validation thresholds, but adjust the PPTX template to the journal's published submission size and citation footer pattern.

package/skills/make-figures/references/medical_illustration_sources.md

@@ -0,0 +1,98 @@
+# Medical Illustration Sources
+
+Reference for finding medical illustrations for visual abstracts, graphical abstracts, and
+manuscript figures. Consult this file when a standalone illustration (not a data plot) is needed.
+
+## Priority Order
+
+1. **Study's own figures** — ROC curve, flow diagram, representative images from the study.
+   Always preferred. No licensing issues. Most relevant to the paper.
+2. **Free illustration libraries** — Download and insert into the visual abstract template.
+3. **Manual drawing** — Simple shapes in Figma, PowerPoint, or Keynote.
+4. **AI generation** — Only if GEMINI_API_KEY is available. Use `generate_image.py --style medical`.
+
+---
+
+## Free Resources (CC BY or Public Domain)
+
+### Servier Medical Art (SMART)
+
+- **URL:** https://smart.servier.com/
+- **License:** CC BY 4.0 (attribution required)
+- **Assets:** 3000+ medical illustrations
+- **Categories:** Anatomy (11 systems), cellular biology, medical specialties, equipment
+- **Format:** PowerPoint (editable vectors), PNG
+- **Best for:** Organ systems, cells, molecules, medical devices, surgical instruments
+- **Attribution:** "Illustrations adapted from Servier Medical Art (https://smart.servier.com/),
+  licensed under CC BY 4.0"
+- **Access:** Browse categories on website. No API. Download slide sets per category.
+
+### NIAID Visual & Medical Arts (BioArt)
+
+- **URL:** https://bioart.niaid.nih.gov/
+- **License:** Public domain (US Government work — no attribution legally required, but recommended)
+- **Assets:** 2000+ illustrations
+- **Categories:** Viruses, bacteria, parasites, anatomy, cells, lab equipment, animals
+- **Format:** SVG, PNG, TIFF (high resolution)
+- **Best for:** Infectious disease, pathogens, immune cells, laboratory scenes
+- **Access:** Browse/search on website. No API.
+
+### BioIcons
+
+- **URL:** https://bioicons.com/
+- **License:** Various CC licenses (check per icon)
+- **Format:** SVG
+- **Best for:** Schematic diagrams, pathway illustrations, icons for flow diagrams
+
+### Reactome Icon Library
+
+- **URL:** https://reactome.org/icon-lib
+- **License:** CC BY 4.0
+- **Format:** SVG, PNG
+- **Best for:** Molecular pathways, biochemistry, cell signaling
+
+---
+
+## Paid Resources
+
+### BioRender
+
+- **URL:** https://biorender.com/
+- **License:** Subscription (academic plans available, ~$99/year student)
+- **Best for:** Professional graphical abstracts, pathway diagrams, figure panels
+- **Note:** Industry standard. Output must include BioRender watermark on free tier.
+  Academic publications require paid license for copyright clearance.
+
+### Medi-Sketch
+
+- **URL:** https://www.medi-sketch.com/
+- **License:** Per-illustration purchase
+- **Best for:** High-quality Korean medical illustrations, graphical abstract commissions
+- **Note:** Korean marketplace connecting researchers with professional medical illustrators
+
+---
+
+## Keyword → Source Mapping
+
+| Need | Recommended Source |
+|------|--------------------|
+| Organ anatomy (heart, lung, brain, kidney) | Servier Medical Art |
+| Cell biology (membrane, organelles, DNA) | Servier Medical Art |
+| Infectious agents (virus, bacteria) | NIAID BioArt |
+| Lab equipment (microscope, pipette, scanner) | NIAID BioArt or Servier |
+| CT/MRI scanner illustration | Servier Medical Art |
+| Molecular pathway | Reactome or BioRender |
+| Schematic flow icons | BioIcons |
+| Custom professional illustration | Medi-Sketch or BioRender |
+
+---
+
+## Usage Notes
+
+- **Editable vectors preferred.** Servier provides PowerPoint files with ungroupable vector shapes.
+  Extract individual elements and recolor to match your visual abstract palette.
+- **Resolution check.** Ensure downloaded PNGs are ≥300 DPI for print. SVGs scale infinitely.
+- **Consistency.** Within one visual abstract, use illustrations from the same source to maintain
+  visual coherence (mixing Servier flat style with NIAID 3D renders looks inconsistent).
+- **AI generation warning.** See the AI-Generated Figure Warning section in SKILL.md.
+  AI-generated medical illustrations are recognizable to reviewers. Use sparingly and customize.