Modern Graphics Generator

Build hero slides, insight cards, and diagrams from one CLI with clarity-first defaults.

What You Can Build

Insight Card	Key Insight Quote	Insight Story

Hero	Triptych Hero	Open Canvas Hero

Cycle Diagram	Timeline Diagram	Slide Cards

Equation (Dark)	Equation (Apple)

Line Chart	Bar Chart	Grouped Bar

Horizontal Bar	Stacked Bar	Grouped Stacked Bar

Stacked Area	Pie	Donut

Sankey	Cohort Retention Heatmap

Canonical showcase assets live in examples/output/showcase/.

Quick Switch (Jobs To Be Done)

• Use the package
• Make graphics
• Build a custom theme (font/colors)
• Build a super custom hero
• Call the CLI directly

First Commands (Most Common Jobs)

Make graphics (about 3 minutes)

modern-graphics create \
  --layout hero \
  --headline "Execution scales. Judgment does not." \
  --png \
  --output ./output/hero.png

Expected output: ./output/hero.png.

Build a custom theme (about 8 minutes)

python examples/custom_template.py

Expected output: dark_cycle_example.html.

Start Here

Option A: Docker (no local install)

./generate hero --headline "Execution scales. Judgment does not."
# ✓ ./output/hero.png

The wrapper auto-builds the Docker image on first run, defaults to PNG, and writes to ./output/.

# HTML instead of PNG
./generate hero --headline "My title" --html

# Custom filename
./generate hero --headline "My title" -o my-hero

# Custom output directory
OUTPUT_DIR=~/Desktop ./generate hero --headline "My title"

Make targets (for more control):

Target	What it does
make build	Build the Docker image
make run ARGS='...'	Run any modern-graphics CLI command
make test	Run the smoke-test suite inside the container
make shell	Drop into an interactive bash shell in the container
make gallery	Generate a static gallery site in site/
make site	Serve interactive gallery at http://localhost:8484
make help	Print available targets

Where do files go? Generated files land on your local disk at ./output/, not inside Docker. The container mounts your host directory, writes the file, and exits — the 2.75GB image stays the same size no matter how many graphics you generate. To reclaim space from stale build layers: docker image prune.

Browse the Gallery

See all available layouts and themes visually:

make gallery        # generate static site
open site/index.html  # browse layouts and themes offline

Or serve the interactive version with live graphic generation:

make site           # starts at http://localhost:8484

The interactive gallery lets you pick a layout, fill in content, choose a theme, and generate graphics in-browser. Each result includes copyable CLI and MCP commands.

Option B: MCP Server (AI-assisted)

Let Claude or other AI clients generate graphics for you via tool calls:

pip install modern-graphics-generator[mcp]

Configure in Claude Code (.mcp.json), then ask: "make me a comparison graphic of manual vs automated."

See MCP Server Guide for full setup.

Option C: pip install

Install dependencies once:

pip install playwright pillow python-dotenv
playwright install chromium

Generate a first PNG:

modern-graphics create \
  --layout hero \
  --headline "Execution scales. Judgment does not." \
  --png \
  --output ./output/hero.png

Expected output: ./output/hero.png.

Defaults (good for most first runs):

• theme=corporate
• density=clarity
• crop-mode=safe
• padding-mode=minimal

Choose Your Path

Use the package (2 minutes)

• Start here: docs/QUICKSTART.md
• API surface: docs/API.md

Make graphics (3 minutes)

• Runnable examples: examples/README.md
• Diagram/layout catalog: docs/DIAGRAM_TYPES.md
• Curated tracked outputs: examples/output/showcase/

Build a custom theme (font/colors) (8 minutes)

• Theme and template customization: docs/CUSTOM_THEMES.md
• Export/crop/padding tuning: docs/EXPORT.md

Build a super custom hero (10 minutes)

• Hero composition patterns: docs/HERO_SLIDES.md
• Mermaid and SVG embedding: docs/MERMAID.md
• SVG.js and freeform extension: docs/SVG_COMPOSITION.md

Call the CLI directly (5 minutes)

• Canonical command + recipes: docs/CREATE_COMMAND.md
• Migration from legacy commands: docs/MIGRATION.md
• Deprecation policy: docs/DEPRECATION_POLICY.md

Full docs map: docs/README.md

Data Charts

Eleven chart layouts render quantitative data. Built on Chart.js (vendored locally — no network required for PNG export) plus a pure HTML/CSS cohort heatmap. All respect the active theme.

Layout	Required args	Use for
line-chart	--labels, --series-json	trends over time, multi-series
bar-chart	--labels, --values	single-series category comparison
grouped-bar-chart	--labels, --series-json	multi-series side-by-side
horizontal-bar-chart	--labels, --values	ranked categories
stacked-bar-chart	--labels, --series-json	composition per category
grouped-stacked-bar-chart	--labels, --series-json (with "stack")	two stacks side-by-side per x label
stacked-area-chart	--labels, --series-json	composition over time
pie-chart / donut-chart	--labels, --values	parts-of-a-whole
sankey-chart	--links-json	flows, funnels, allocations
cohort-chart	--cohorts-json	Mixpanel-style retention heatmap

Optional on every chart: --title, --subtitle, --x-label, --y-label, --no-legend, --theme. JSON args accept inline strings or @path/to/file.json.

# Simple bar chart
modern-graphics create --layout bar-chart \
  --labels "North,South,East,West" --values "42,58,71,34" \
  --title "Units shipped" --y-label "Units (thousands)" \
  --output bar.png --png

# Multi-series line chart
modern-graphics create --layout line-chart \
  --labels "Q1,Q2,Q3,Q4" \
  --series-json '[{"name":"2024","values":[42,58,71,88]},{"name":"2025","values":[60,75,95,118]}]' \
  --title "Revenue growth" --y-label "Revenue (\$M)" \
  --output line.png --png

# Sankey flow
modern-graphics create --layout sankey-chart \
  --links-json '[{"from":"Visit","to":"Trial","value":80},{"from":"Trial","to":"Paid","value":35}]' \
  --title "Funnel flow" --output sankey.png --png

# Cohort retention heatmap (large data — use @file)
modern-graphics create --layout cohort-chart \
  --cohorts-json @cohorts.json \
  --title "Weekly retention" --output cohort.png --png

Runnable examples for every chart live in examples/chart_*.py. The same layouts are available via MCP (generate_graphic) and the web gallery.

Text Rendering Mode

Use Pretext when you care about deterministic SVG text layout and quote-heavy typography.

• Enable with --text-render pretext on modern-graphics create.
• Best fit: open hero quote/insight callouts (italic quote text) and story slides with hero mini-tiles.
• Recent refinements:
  • Open hero insight quote text no longer overlaps the quote icon lane.
  • Story mini-tile text uses refined reserved foreignObject bands to avoid clipping in Pretext mode.

modern-graphics create \
  --layout hero \
  --headline "Execution scales. Judgment does not." \
  --text-render pretext \
  --png \
  --output ./output/hero-pretext.png

Visual comparison:

python3 examples/pretext_mini_tile_refinement_demo.py

Contributing

• Contribution guide: docs/CONTRIBUTING.md
• Historical plans and notes: docs/archive/

Acknowledgments

• @chenglou/pretext — pixel-perfect text measurement and layout by Cheng Lou, used for optional SVG text rendering (--text-render pretext)

License

MIT License.