zuzu draws charts and diagrams in pure Go. A caller gives it a declarative
spec, which says what to draw from which data, and zuzu writes the chart as
SVG or as an image.
The spec follows Vega and Vega-Lite. A spec written for
the Vega tools works with zuzu, as far as zuzu supports it. zuzu draws its
own design, at the quality of nivo and visx, with a light and a dark mode and
color schemes that swap. zuzu renders the SVG to an image with
okage, a pure Go port of resvg.
zuzu also reads the DOT language of Graphviz and the syntax of Mermaid, and
draws a diagram in the same look. Later, zuzu sends live charts to a web
browser, and draws the results of a query for usql.
Phases 0 to 7 of the plan are done. Phase 0, the repository, the tests of
the documents, CI, the corpus and the oracle, is done. The scene graph, the
themes, the SVG writer and the measurement of text with the bundled IBM Plex
Sans exist (phases 1 and 2). zuzu reads a Vega spec and draws it (phase 3).
On the 540 specs of the first target, its datasets, scales and marks match
those of vega.js for 99 percent of the specs. zuzu compiles a Vega-Lite spec
itself (phase 4), and its result matches for 98 percent of the 470
Vega-Lite specs. Phase 5 added the transforms of statistics, hierarchies,
maps, contours and labels, and the transforms and the scale of zuzu for
sankeys, chord diagrams, hex bins and trading days. Phase 6 added
raster, which draws a chart with okage directly, without SVG, and
Chart.Image. Phase 7 added the diagrams of DOT and Mermaid: a layered
layout of graphs, the flowchart and nine charts of Mermaid, and icons, with
four packs bundled. Since then zuzu also draws every other kind of
Mermaid 12.3: the sequence, state, class, ER, requirement, block,
swimlane, use case, agentflow, timeline, C4, venn, ishikawa, Cynefin,
event model, ZenUML, kanban, packet and railroad diagrams, the mindmap,
the architecture diagram, the gitGraph, the tree view and info. The
package text/emoji draws an emoji in color.
docs/DIAGRAMS.md lists what zuzu reads.
docs/PLAN.md holds the plan, its phases and the questions
that the maintainers have not answered.
chart, _, err := zuzu.Parse(src)
if err != nil {
return err
}
report, err := chart.SVG(ctx, w, zuzu.WithLoader(zuzu.FSLoader(os.DirFS("data"))))The first step was a survey of what other libraries do. Open
docs/survey/compare.html to see the same real
data drawn by zuzu and 14 other chart and diagram libraries, side by side, in
a light and a dark theme. docs/survey/README.md
says how to open it.
The second step was the look. Open
docs/targets/index.html to see 33 target charts,
from a line to a flowchart, in the light and the dark mode and in thirteen
color schemes. They came before any code. The script in docs/targets/ draws them,
and docs/targets/README.md says how to draw and
open them.
zuzu has four stages, and each stage hands the next one a value that can be written as JSON:
- A front end reads Vega, Vega-Lite, DOT or Mermaid, and produces a spec in the shape of a Vega spec.
- The runtime loads the data, runs the transforms and the expressions, builds the scales and lays out the axes and the legends.
- The result is a scene graph: a tree of shapes with their final positions, sizes and colors.
- A renderer writes the scene graph as SVG, draws it with okage, or later sends it to a browser.
The first target is static Vega, which is Vega without the events of a mouse
or a keyboard, and the Vega-Lite that compiles to it. The corpus of 579
Vega-Lite specs and 87 Vega specs from vegagoja, with the output
of vega.js for each, measures how far zuzu agrees with Vega.
| Document | What it holds |
|---|---|
docs/PLAN.md |
the plan, the architecture, the phases and the open questions |
docs/API.md |
the public API |
docs/EXPRESSIONS.md |
the expression language, and the choices for scripting beyond it |
docs/decisions/ |
every decision, one file each, with an index |
docs/BACKLOG.md |
the work that is known and not done |
docs/STYLE.md |
the rules and the tokens of the look, the modes and the color schemes |
docs/DIAGRAMS.md |
the parts of DOT and of Mermaid that zuzu reads |
docs/targets/ |
the target SVGs that show the look zuzu aims for |
docs/survey/ |
the survey of other libraries, and the page that compares them |
AGENTS.md |
the rules for a coding agent, which apply to a person too |
CONTRIBUTING.md |
how to change zuzu |
Read CONTRIBUTING.md first. A change to the design is a
decision first, and an open question goes to the maintainers.