visual-design-system

What this skill does

# Visual Design System

**Purpose:** Publication-grade design tokens and utilities for Nature/JACC/NEJM quality graphics.

**Status:** Phase 3.1 In Progress - Manim Animations

---

## Which Tool Should I Use?

Use this decision table to pick the right backend before writing any code:

| Task | Best Tool | Output |
|------|-----------|--------|
| Publication figure (bar, line, forest plot) | **Plotly** or **drawsvg** | PNG (300 DPI) |
| Infographic card / social slide | **Satori** or **Component Library** | PNG, SVG |
| Medical diagram (heart, ECG, flowchart) | **drawsvg** | PNG, SVG |
| Clinical trial / drug mechanism template | **SVG Templates** | PNG, SVG |
| Treatment pathway / CONSORT / PRISMA | **Architecture Diagrams** | PNG |
| Animated mechanism / Kaplan-Meier / ECG | **Manim** | MP4 |
| Any of the above with a unified Python API | **Component Library** | PNG, SVG, HTML |

**Quick rule:** if it's a static publication figure → Plotly/drawsvg; if it's a polished card or social asset → Satori/Component; if it needs motion → Manim.

---

## Publication Figure Workflow (Create → Validate → Export)

For any publication-grade output, follow this validated sequence:

```python
from skills.cardiology.visual_design_system.tokens import (
    get_color, get_accessible_pair, validate_contrast, get_contrast_ratio
)
from cardiology_visual_system.scripts.plotly_charts import create_comparison_bars, save_chart

# 1. Create the figure using token colors
treatment, control = get_accessible_pair("treatment_control")
fig = create_comparison_bars(
    categories=["Primary", "Secondary"],
    group1_values=[12.3, 8.5],
    group2_values=[18.7, 14.2],
    group1_name="Treatment",
    group2_name="Placebo",
    title="Clinical Trial Results"
)

# 2. Validate contrast before export
if not validate_contrast(treatment, "#ffffff"):
    ratio = get_contrast_ratio(treatment, "#ffffff")
    # Fix: swap to a pre-validated pair
    treatment, control = get_accessible_pair("benefit_risk")

# 3. Validate DPI / scale — always use scale=4 for 300 DPI
# fig.write_image("results.png", scale=4)  # direct Plotly
save_chart(fig, "results.png")            # auto 300 DPI (scale=4)
```

**If validation fails:**

| Problem | Cause | Fix |
|---------|-------|-----|
| `validate_contrast` returns `False` | Ratio < 4.5:1 | Swap to a pre-validated pair via `get_accessible_pair()` |
| Render produces no output | Missing dependency | Run `pip install drawsvg cairosvg` or `pip install diagrams` |
| Manim scene not found | Not in catalog | Run `python scripts/render_manim.py --list` and check `scene_catalog.json` |
| 300 DPI export looks blurry | Wrong scale | Use `scale=4` in `fig.write_image()` or `save_chart(fig, path)` |
| Font not applied | System font missing | Tokens fall back to Arial; check `tokens.get_font_family("primary")` |

---

## Quick Start

```python
from skills.cardiology.visual_design_system.tokens import (
    get_tokens,
    get_color,
    get_accessible_pair,
    validate_contrast,
)

# Get a specific color
navy = get_color("primary.navy")  # "#1e3a5f"

# Get a colorblind-safe pair for treatment vs control
treatment, control = get_accessible_pair("treatment_control")

# Validate accessibility
is_safe = validate_contrast("#1e3a5f", "#ffffff")  # True (9.2:1 ratio)

# Get full tokens object
tokens = get_tokens()
palette = tokens.get_color_palette("categorical")  # 7 colorblind-safe colors
```

---

## Design Philosophy

This system enforces **Nature journal standards** for all visual output:

| Standard | Requirement | How We Enforce |
|----------|-------------|----------------|
| **Fonts** | Helvetica/Arial only | Token system + validation |
| **Font sizes** | 5-8pt for figures | Pre-defined size scale |
| **Contrast** | WCAG AA (4.5:1 min) | Automated validation |
| **Colorblind** | No red-green only | Paul Tol palettes |
| **Resolution** | 300 DPI minimum | Export presets |
| **Shadows** | None in figures | Disabled by default |

---

## Token Categories (Overview)

Full token reference: `references/color_palettes.md` and `references/nature_guidelines.md`.

### Colors

```python
# Primary
get_color("primary.navy")    # "#1e3a5f"
get_color("primary.blue")    # "#2d6a9f"
get_color("primary.teal")    # "#48a9a6"

# Semantic
get_color("semantic.success")  # "#2e7d32"
get_color("semantic.warning")  # "#e65100"
get_color("semantic.danger")   # "#c62828"
get_color("semantic.neutral")  # "#546e7a"

# Colorblind-safe palettes
tokens.get_color_palette("categorical")      # 7 Paul Tol colors
tokens.get_color_palette("sequential_blue")  # 5-step blue ramp
tokens.get_color_palette("diverging")        # blue ← neutral → red

# Pre-validated accessible pairs
t, c    = get_accessible_pair("treatment_control")    # ('#0077bb', '#ee7733')
b, r    = get_accessible_pair("benefit_risk")         # ('#009988', '#cc3311')
i, p    = get_accessible_pair("intervention_placebo") # ('#0077bb', '#bbbbbb')

# Clinical outcome colors
tokens.get_clinical_color("mortality")           # "#b2182b"
tokens.get_clinical_color("hospitalization")     # "#ef8a62"
tokens.get_clinical_color("symptom_improvement") # "#67a9cf"

# Forest plot colors
colors = tokens.get_forest_plot_colors()
# keys: point_estimate, confidence_interval, null_line, summary_diamond,
#       heterogeneity_low, heterogeneity_moderate, heterogeneity_high
```

### Typography

```python
tokens.get_font_family("primary")   # "Helvetica, Arial, sans-serif"
tokens.get_font_family("monospace") # "Courier New, Courier, monospace"

# Figure elements (Nature 5-8pt standard)
tokens.get_font_size("figure_elements", "panel_label")  # 8pt
tokens.get_font_size("figure_elements", "axis_title")   # 7pt
tokens.get_font_size("figure_elements", "axis_tick")    # 6pt

# Infographic / social media
tokens.get_font_size("infographic_elements", "headline")   # 24pt
tokens.get_font_size("social_media", "carousel_stat")      # 48pt
```

### Spacing & Strokes

```python
# 4px base grid
tokens.get_spacing("xs")  # "4px"  |  tokens.get_spacing("sm")  # "8px"
tokens.get_spacing("md")  # "12px" |  tokens.get_spacing("lg")  # "16px"

tokens.get_stroke_width("hairline")  # "0.5px"
tokens.get_stroke_width("thin")      # "1px"
tokens.get_stroke_width("regular")   # "1.5px"
```

---

## Validation

### CLI

```bash
python scripts/token_validator.py                  # Full validation
python scripts/token_validator.py --contrast-report
python scripts/token_validator.py --json
```

### Programmatic

```python
from tokens.index import validate_contrast, get_contrast_ratio

validate_contrast("#1e3a5f", "#ffffff")              # True  (WCAG AA)
validate_contrast("#1e3a5f", "#ffffff", level="AAA") # True  (WCAG AAA)
get_contrast_ratio("#1e3a5f", "#ffffff")             # 9.2
```

---

## Plotly (Phase 1.4)

Standard publication charts with automatic token integration and 300 DPI export.

```python
from cardiology_visual_system.scripts.plotly_charts import (
    create_comparison_bars, save_chart,
)

fig = create_comparison_bars(
    categories=["Primary", "Secondary"],
    group1_values=[12.3, 8.5],
    group2_values=[18.7, 14.2],
    group1_name="Treatment",
    group2_name="Placebo",
    title="Clinical Trial Results"
)
save_chart(fig, "results.png")  # Auto 300 DPI (scale=4)
```

```bash
# CLI
cd skills/cardiology/cardiology-visual-system/scripts
python plotly_charts.py demo --quality-report
python plotly_charts.py demo --png --output-dir ../outputs
python plotly_charts.py bar -d data.csv -o chart.png
```

**Direct template usage:**
```python
from tokens.index import get_plotly_template
import plotly.io as pio

pio.templates["publication"] = get_plotly_template()
fig = px.bar(data, template="publication")
fig.write_image("chart.png", scale=4)
```

---

## Satori Infographic Pipeline (Phase 1.2)

Generates PNG/SVG infographic cards from structured data via a Node.js renderer.

**Templates:** `stat-card`, `comparison`, `process-flow`, `trial-summary`, `key-finding`

```bash
cd sato