design-a-chart

# Design a Chart From a User Goal Use this scenario loop: **trigger → inspect → decide → build → verify**. Do not begin with a chart type, even when the request names one. ## Setup Turn the request into this brief before writing chart code: ```ts interface ChartBrief { question: string decision: string observation: string metric: { value: string; unit: string; denominator?: string } comparison: 'time' | 'category' | 'distribution' | 'relationship' | 'composition' evidence: readonly string[] } export const brief: ChartBrief = { question: 'Which acquisition channel improved conversion without losing volume?', decision: 'Choose where to increase next-month spend', observation: 'one row per channel and month', metric: { value: 'conversionRate', unit: '%', denominator: 'sessions' }, comparison: 'time', evidence: ['conversion rate', 'sessions', 'month', 'channel'], } ``` If the question, observation, unit, denominator, or decision is unknown, inspect the data and surrounding product before choosing marks. ## Core Patterns ### Match the form to the reader's comparison - Change over ordered time → line; discrete periods → bars. - Named-category magnitude → sorted horizontal bars or dots. - Distribution → histogram, ECDF, box, violin, or faceted histograms. - Relationship → scatterplot; add size only for a meaningful third quantity. - Composition → stack for totals, normalized stack for proportions, mosaic for two categorical dimensions. - Flow, hierarchy, network, or spatial questions → use their first-party layouts only when topology is the question. Read [the visual-task matrix](references/visual-task-matrix.md) for the full routing table. ### Separate observed, target, and projected values ```ts import { areaY, defineChart, lineY, ruleY } from '@tanstack/charts' import { scaleLinear } from '@tanstack/charts/scales/linear' import { scalePoint } from '@tanstack/charts/scales/point' const rows = [ { month: 'Jan', actual: 82, forecast: null, low: null, high: null }, { month: 'Feb', actual: 91, forecast: null, low: null, high: null }, { month: 'Mar', actual: null, forecast: 96, low: 88, high: 106 }, { month: 'Apr', actual: null, forecast: 103, low: 90, high: 119 }, ] export const chart = defineChart({ marks: [ areaY(rows, { x: 'month', y1: 'low', y2: 'high', fillOpacity: 0.15 }), lineY(rows, { x: 'month', y: 'actual', strokeWidth: 2.5 }), lineY(rows, { x: 'month', y: 'forecast', strokeDasharray: '5 4' }), ruleY([100], { strokeDasharray: '2 3' }), ], scales: { x: { scale: scalePoint }, y: { scale: scaleLinear, axis: { label: 'Indexed revenue' } }, }, }) ``` Use different channels for status and uncertainty. A continuous unqualified line implies equal epistemic status. ### Define proof before polish For every chart, verify: - the visual answers the stated question; - axes, legend, title, or adjacent copy identify units and comparison; - ordering, aggregation, missing-value policy, and baseline are deliberate; - exact-value tasks have a table or textual equivalent; - the smallest supported container preserves the important comparison; - pointer, keyboard, updates, and empty states tell the same story. ## Common Mistakes ### CRITICAL Starting with the requested chart type Wrong: implement “make this a pie chart” before identifying the comparison. Correct: restate the decision and recommend the form that makes that comparison perceptually direct. If the user retains a weaker form, state its analytical limitation and preserve the underlying semantics. A familiar chart can answer a different question than the user needs. Source: `docs/guides/choosing-a-chart.md` ### HIGH Showing a rate without its denominator Wrong: show conversion rate alone. Correct: keep sessions or eligible population in the prepared row and expose it beside the rate or in the tooltip. Normalized values can reverse interpretation when volume changes. Source: `API-FRICTION.md` F-217; `docs/reference/transforms.md` ### CRITICAL Rendering projections as observed history Wrong: connect actuals and forecasts with one undifferentiated line. Correct: encode the forecast boundary, projected segment, and uncertainty explicitly. Continuous treatment implies equal certainty. Source: `docs/examples/lines-and-areas.md`; `docs/reference/marks/difference.md` ### HIGH Choosing area or angle for precise ranking Wrong: rank close values with wedges, bubbles, or interior stack layers. Correct: use aligned position or length when exact ordering is the reader's task. Area and angle emphasize shape or part-to-whole relationships, not precise rank. Source: `docs/guides/choosing-a-chart.md`; `docs/examples/bars-and-rankings.md` ### HIGH Tension: analytical honesty versus visual simplicity Simplifying aggregation can hide denominators, lineage, uncertainty, or missing-value policy. Preserve the evidence needed to interpret the result before reducing visual detail. See also: `prepare-chart-data/SKILL.md` § Common Mistakes ## References - [Analytical task and visual-form matrix](references/visual-task-matrix.md) See also: `prepare-chart-data/SKILL.md` and `compose-marks-and-views/SKILL.md` — the analytical task determines both the transform and mark composition.