Vois Data Visualization Skill

A chart is read by people and built by you. This skill makes the result right by construction: it picks the form from the viewer's job, assigns color by the job it does, builds the states most dashboards forget, and gives you something to check against.

It answers "what should this data look like, and is it honest and usable?" Page structure is vois-patterns, container components are vois-components, token values and motion are vois-tokens, and every word on the screen is righter.

Two modes. BUILD: you're creating a visualization or dashboard. REVIEW: you're evaluating or improving an existing one. The steps differ; the rules are the same.

BUILD: the order of work

1. Write the spec. One per visualization, following data/chart-spec.schema.json: the question it answers, the audience, the job, the form. If you can't write the question, the chart shouldn't exist [DV-PURPOSE-001].
2. Walk the decision tree (below, in full in references/decision-tree.md). Land on a result node and a form id from data/chart-catalog.json.
3. Check the spec: node scripts/check-spec.mjs spec.json. Fix every FAIL before you write code. --tree <job> lists the forms a job can reach.
4. Record the choice. If a vois_record_component_choice tool is available, call it with job (the viewer's question), componentName (such as ChartContainer + LineChart), alternativesConsidered (other forms from the tree) and reasoning (the tree result id, e.g. CHART-R-LINE-MULTI). If nothing in the tree fits and vois_report_pattern_gap is available, call it with the closest result as attemptedFallback; otherwise say so in your answer.
5. Get tokens. Get the chart roles in references/implementation.md from the workspace tokens (vois_get_tokens if available). Never write a color value, and never invent a missing role: report the gap.
6. Build from one typed config [DV-SUSTAIN-001], following references/implementation.md. Build the dashboard from DASH-* templates and pieces (references/dashboard-patterns.md).
7. Build the states: skeleton, four kinds of empty, error, refetch, partial [DV-STATE-001] through [DV-STATE-007]. Copy goes through righter.
8. Check the code: node scripts/detect.mjs <files>. Then look at it at 320, 640 and 1280px, light and dark, with a keyboard.
9. Record usage (optional): if vois_record_rule_usage is available, call it with the DV-* ids you applied (violated or ambiguous where they weren't met). These calls are telemetry; if one is missing or errors, carry on.

REVIEW: the order of work

Follow references/review-protocol.md: inventory, infer each job, check the form against the tree, run the mechanical checks, run the judgment checks in triage order, check the page as a whole, propose the upgrade, report in data/review-output.schema.json. data/review-checklist.json has a symptom to fix playbook for the 20 most common problems. Don't flag what passes, and list what you couldn't check.

Decision tree, at a glance

Start with the viewer's job, not the chart. Full tree with every branch: references/decision-tree.md and data/decision-tree.json.

Then run the gates on the result: audience, simpler form, series count, scale, table twin, volume.

Quick reference

Which dashboard?

Walk DASH-Q-TYPE in references/dashboard-patterns.md.

Reusable pieces: DASH-KPI-TILE, DASH-CHART-CARD, DASH-FILTER-BAR, DASH-DATE-RANGE, DASH-STATE-MATRIX, DASH-TABLE-SPARK, DASH-DRILLDOWN, DASH-TOOLTIP.

The 14 principles

Each one has a full do and don't list in references/principles.md. The headline:

Non-negotiables

These are required rules a reviewer will FAIL. Everything else is a WARN with a fix.

• One y-axis per chart [DV-HONEST-002]; bars and areas start at zero [DV-HONEST-001].
• Categorical hues in fixed order, never cycled, eight at most [DV-COLOR-003]; chart colors are tokens [DV-COLOR-001]; an entity keeps its color [DV-COLOR-004].
• Color is never the only signal [DV-A11Y-001]; marks 3:1 and text 4.5:1 [DV-A11Y-002].
• Every chart has a text alternative and a table view [DV-A11Y-003] [DV-A11Y-004]; tooltips enhance and never gate [DV-A11Y-006].
• Partial periods, forecasts and missing data look different from the real thing [DV-HONEST-004] [DV-HONEST-008].
• Every KPI has a delta against a named period [DV-CONTEXT-002].
• One filter row above what it scopes, and every card obeys it [DV-FILTER-001] [DV-FILTER-004].
• Skeleton in final geometry on first load, held frame on refetch, errors isolated to the card [DV-STATE-001] [DV-FILTER-008] [DV-STATE-003].
• No hardcoded data in a chart component [DV-SUSTAIN-005].

Taste dials

When the project defines the three taste dials in VOIS.md or DESIGN.md: DENSITY moves the per-view cap from about 6 to 8 up to 10 visualizations and allows analyst forms for analyst audiences; MOTION never exceeds 300ms and always yields to reduced motion [DV-A11Y-008]; VARIANCE can vary card composition but never the form choice or any honesty rule. Dials tune within the rules, never against them.

Reference files

Generated from data/*.json by scripts/build-reference.mjs, so they can't drift:

Written by hand:

Structured data (query these instead of scanning prose)

Source of truth. The JSON is canonical and the generated references restate it. scripts/dataviz.test.mjs fails CI if an ID in prose has no JSON entry or the reverse.

Scripts

Relationship to other skills

vois-patterns first. It decides that the screen is a dashboard or contains data. Come here for what's inside it. vois-components (JOB-VISUALIZE-DATA) routes data jobs here, then picks the containers: Card, Tabs, Popover, Calendar, Table, Skeleton. vois-tokens supplies live token values, motion and hit-area rules. This skill adds chart roles on top and cites DS-A11Y-001, DS-A11Y-002, DS-ANIMATION-001 and DS-ANIMATION-004. righter writes every title, subtitle, tooltip label, empty state and error. This skill says what the state is, never the words. metrics-tagging instruments chart interactions (range change, legend toggle, drill-down, export) when asked. design-rationale explains why a form or color choice is right when someone pushes back.

Checklist before handoff

• Spec written for each visualization and check-spec has no FAIL
• Form reached through the tree (and vois_record_component_choice called, if available)
• Colors are chart tokens in fixed order, checked per mode
• Text alternative, accessibilityLayer, table view, keyboard path
• Tooltip and crosshair, legend for 2 or more series, drill-down affordance
• One filter row with date presets and a named comparison
• Skeleton, four empty cases, error, refetch and partial states built
• detect.mjs run and clean, or each finding justified
• Checked at 320, 640 and 1280px, light and dark
• vois_record_rule_usage called, if available