Chart judgment for people and agents
Most bad charts
are decided before
the code is written.
Not ugly — wrong: a defensible-looking answer to a question nobody asked, or an honest-looking answer the data can't support. vizier moves that decision onto something documented. It picks the chart form from the reader's question, runs the checks a graphics desk would run before publishing, and judges what a finished chart got wrong.
$ vizier recommend-form "how a budget splits, across five districts" --n-series 5 → stacked-bar when NOT to use: reader must compare a middle segment reach for instead: grouped-bar, small-multiples $ vizier guide "per-pupil spending vs state average" → Fair comparison · Unit and denominator · Counter-reading · Money basis
Install
The primary way to use vizier is as a plugin for your coding agent, where it fires before a chart gets built. Two skills — one that decides a chart, one that critiques one — plus vizier's MCP server, so the same answers are available as tools.
# in Claude Code /plugin marketplace add lyra-forge/marketplace /plugin install vizier@lyra-forge
The skills drive the vizier CLI, which installs separately
— the PyPI distribution is datavizier (the bare name was
taken; the import package and command are both vizier):
$ uv tool install datavizier # or: pip install datavizier $ vizier doctor # what's live, what's missing, and how to fix it
Start a new session and ask for a chart. Python 3.12+. Nothing in the core needs a key, a network call, or a proprietary dependency.
Or use it directly
$ vizier recommend-form "composition of a total over time" --n-series 5 $ vizier patterns show stacked-area # when to use, when NOT, mistakes, checklist $ vizier guide "district budget module with a per-pupil trend" $ vizier analyze chart.svg # structural + color checks on what you built $ vizier critique chart.png # corpus-backed review (optional extra + key)
Any MCP client
$ claude mcp add vizier -- vizier mcp
Cursor, Claude Desktop, or a charting tool of your own can call the same decisions rather than re-deriving them. Setup and troubleshooting: docs/mcp-setup.md.
What it decides
Everything below is deterministic — no LLM, no keys, no network. It answers the parts of a chart that are actually decidable, and refuses the ones that aren't honest.
Which form answers the reader's question
Describe the comparison and the data shape; get the form that fits
— with its when_not_to_use list and the alternatives
that name your situation. 43 patterns across the nine
FT Visual Vocabulary families, each with the mistakes
people actually make and a reading checklist. The alternatives are
where the judgment is: two forms that disagree on the same data are
telling you what the data is.
The questions a graphics desk asks before publishing
vizier guide returns the honesty checks for the job at
hand: what benchmark makes this number interpretable, percent
of what and dollars per whom, what the most likely
wrong reading is and where you're blocking it, whether the money is
nominal or adjusted. Answer them in the chart and caption — an
acknowledged gap is honest, a silent one is the defect.
Whether the chart you built says what you meant
Point vizier analyze at a rendered SVG or HTML and get
the structural checks plus the palette it actually renders
— data color separated from axis and grid chrome. It reads what the
library did, not what you intended.
What a corpus of critics would say about it
vizier critique <image> retrieves the form's
reading checklist and relevant critical writing — award commentary,
structural critique, practitioner walkthroughs — then synthesizes a
review that cites prior art instead of asserting taste. The one path
that uses an LLM, and the one that's optional.
Color, once, and then stop thinking about it
The last five percent of a good chart and the first ninety percent
of most chart advice. suggest-palette and
suggest-ramp return categorical palettes and ordinal
ramps that have already cleared colorblind separation, contrast, and
lightness checks, so there's nothing left to eyeball;
validate checks one you were handed. An unsatisfiable
request errors rather than returning something that fails. Then go
back to the two rules that matter more than any hue: ordered color
for ordered data, and never let color carry meaning alone.
Built to be called, not read
A plugin, an MCP server, and a CLI over the same library, so an agent or a charting tool asks vizier for the decision instead of re-deriving it from a half-remembered rule. The core installs with no keys and no heavyweight dependencies; retrieval and LLM critique are opt-in extras.
The chart-forms guide
43 forms, nine families, live demos
Most chart catalogs sort by what a chart looks like. This one
sorts by the question your reader is asking — what moves, how does it
split, what's the order — and lands on the form that answers it. Every
pattern carries when it earns its place, when to reach for something
else, the mistakes even good people make, and a live demo you can
drive. Generated from the same data vizier answers
recommend-form with.
Propose and judge, from one set of thresholds
vizier started as a critic and grew a generator, and they're colocated on purpose: the thresholds that let it suggest a form are the thresholds it critiques against. What it proposes is what it would pass. Held apart, the two can be pointed at each other — a generator proposes, the critic pushes back.
Give me one that's right
Form recommendation against a documented library, the journalism checks for the job, and validated color — every suggestion checked before it's returned. A request that can't be satisfied honestly errors instead of returning something that fails.
Is this one right?
Structural and color checks straight from the artifact, the form's reading checklist answered against the chart, and retrieval-augmented judgment against a corpus of critical writing — with prior art cited.
The critique path routes LLM calls through
somm, a
self-hosted gateway on PyPI; supply a key in .env, or swap
in any client by adapting one small module. Measured lift: folding the
computable findings into a critique moved alignment from 2 to 5 on the
focused color A/B under evals/.
vizier & artoo
vizier decides and judges the chart. artoo builds and ships the page it lives on — a self-contained HTML mini-site that carries the research behind the presentation, with provenance and deployment. They meet at the artifact: artoo owns packaging and publication, vizier owns whether the graphic on the page earns its place. The chart-forms guide linked above is an artoo artifact.
More generally, vizier is built to be asked. Any renderer or generator can call it for the form and the color instead of re-deriving them, and the same thresholds serve both directions — see PRINCIPLES.md.
Status
v0.3.0 · MIT licensed. What the corpus draws on, and the philosophy behind distilling broad expert taste into a determination, are in INFLUENCES.md; the house posture on charts is in PRINCIPLES.md.