oubakiou

Posted on Jun 30

Rendering Charts Beyond Mermaid's Reach with Vega-Lite and Embedding Them in Markdown (via LLM Skills)

#ai #datascience #llm #showdev

AI agents like Claude Code and Codex can write code, polish documentation, and automate complex tasks. But ask them to "make a scatter plot of this data" or "show the trend as a heatmap," and they hit a wall. Mermaid tops out at basic bar charts and pie charts — statistical visualization is outside its scope.

dataviz-svg is a skill built to fill that gap. It generates SVG charts from Vega-Lite declarative JSON specs and embeds them directly into Markdown documents.

Where Mermaid Falls Short

Mermaid is a great tool, but it excels in a different domain.

Mermaid's strengths	dataviz-svg's strengths
Flowcharts, sequence diagrams, ER diagrams	Scatter plots, heatmaps, histograms
State diagrams, Gantt charts	Box plots, area charts, bubble charts
Simple bar charts with a few data points	Charts with 20+ data points
Structural diagrams in general	Multi-axis encoding (x, y, color, size)

In short: Mermaid is for structural diagrams, dataviz-svg is for data-driven statistical visualization. When an agent can use both, the expressiveness of its documentation output improves dramatically.

Supported Chart Types

An example actually generated from the skill

dataviz-svg inherits the full expressiveness of Vega-Lite, so the range of supported charts is broad. Check out the official Vega-Lite gallery to see what's possible at a glance.

Bar charts — vertical, horizontal, grouped, stacked (including 100% stacked)
Line charts — single series, multi-series (with strokeDash for print-friendly output)
Scatter plots — basic scatter, bubble charts (size + color + log scale)
Area charts — stacked area, streamgraph
Heatmaps — 2D grid with overlaid text layers
Histograms — distribution via binning
Box plots — quartile display
Pie / Donut charts — donut variant via innerRadius
Layered charts — line + point + text label overlays
Facet / Concatenation — small multiples, horizontal/vertical multi-chart layouts

How It Works

Tech Stack

The core of dataviz-svg is simple. Vega-Lite and Vega are bundled into a single ESM file (~1.6 MB) with Vite, so it runs on Node.js alone.

Vega-Lite JSON spec
    ↓ compile()
Vega spec
    ↓ Vega runtime
SVG string
    ↓ writeFileSync
output.svg

No native dependencies like canvas or puppeteer. No additional npm install needed. The bundle ships with the skill, so it works right after installation.

Execution Flow from the Agent's Perspective

When an agent uses this skill, it follows 5 steps:

Understand data and visualization requirements — identify the input data (inline values / CSV / JSON), chart type, and axis/color mappings
Create a Vega-Lite JSON spec — write the spec as a JSON file, referencing the bundled pattern collection
Render the SVG — run render-svg.sh to generate the SVG
Embed in Markdown — reference with ![Chart Title](./assets/chart.svg)
Review and adjust — inspect the SVG, tweak label angles or color scales, and re-render

From the user's perspective, you just say "turn this data into a heatmap" and the agent handles everything — spec creation, rendering, and document embedding — end to end.

Example: Visualizing Sales Data

For example, to create a bar chart of quarterly sales data, the agent generates a Vega-Lite spec like this:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "width": 400,
  "height": 300,
  "background": "white",
  "data": {
    "values": [
      { "quarter": "Q1", "sales": 120 },
      { "quarter": "Q2", "sales": 185 },
      { "quarter": "Q3", "sales": 210 },
      { "quarter": "Q4", "sales": 165 }
    ]
  },
  "mark": "bar",
  "encoding": {
    "x": { "field": "quarter", "type": "ordinal" },
    "y": { "field": "sales", "type": "quantitative" },
    "color": { "field": "quarter", "type": "nominal" }
  }
}

Pass this to render-svg.sh and an SVG is generated — no browser required.

Design Trade-offs

Practicality comes first. Here are the deliberate trade-offs:

SVG only: No PNG/PDF support. Eliminating native dependencies (canvas / sharp) means zero setup friction
Static output only: Vega-Lite's interactive features (hover, zoom, selection) don't carry over to SVG
No font embedding: Relies on system fonts. sans-serif is the safest choice
No canvas package: Text bounding box calculations are approximate, which may cause slight misalignment with long CJK (e.g., Japanese) labels

These are intentional. The top priority is "works immediately in any environment, with no extra installation."

Installation

# For Claude Code
gh skill install oubakiou/skills dataviz-svg --agent claude-code --scope project

# For Codex
gh skill install oubakiou/skills dataviz-svg --agent codex --scope project

The only prerequisite is Node.js 18 or later. Vega and Vega-Lite are bundled, so no separate installation is needed.

Summary

dataviz-svg is laser-focused on one thing: giving AI agents the ability to create data visualizations.

Generates statistical charts that Mermaid can't handle, powered by Vega-Lite
No browser, no extra dependencies — just Node.js
The agent handles the entire pipeline: spec creation, rendering, and document embedding

"Turn this data into a chart." — With that single request, the agent picks the right chart type, generates it, and embeds it in your document. Naturally integrating data visualization into the AI agent workflow — that's what dataviz-svg is for.

DEV Community