Charts & data visualization

A chart is an answer to a question. The job of every chart in Marmo is to make a single question easier to answer than reading a row of numbers — and to do it in a way the eye and brain understand without instructions.

This page covers what to draw, how to draw it, how it should behave, and — at the end — the criteria a chart must clear before it ships, drawn from cognitive psychology and interaction-design fundamentals.

Status: alpha. Library choice is Recharts (see § Library).

---

Principles

Six rules. They override anything else on this page.

1. One question per chart. Every chart answers a single, named question. Two questions = two charts.
2. No distortion. Bar baselines start at zero. No 3D. No truncated axes that exaggerate change. No inverted scales without an explicit label.
3. Color is meaning. Reusing the same color for the same series across the product is a contract with the reader. Don't break it.
4. Color is never the only channel. Every color signal also exists as text, icon, position, or pattern.
5. A chart without a table is incomplete. Every meaningful chart ships with a tabular alternative — for screen readers, for export, for copy-paste.
6. One clear chart beats six dense tiles. A scorecard plus one well-chosen chart almost always beats a 6-up grid of half-thoughts.

---

Pick the right chart

Start from the question, not the data shape.

Rules of thumb

• Pie allowed only when there are ≤ 4 slices summing to a meaningful 100%. Otherwise use a bar chart.
• Two y-axes mislead more than they explain. Split into two charts.
• 3D: never.

Compare across categories?

Bar (horizontal ≥ 5; vertical ≤ 5)

How has X changed over time?

Line (continuous) · Column (discrete)

What is X made of?

Donut (≤ 4 slices) · Stacked bar · Treemap

How has composition shifted?

Stacked area / column

Is X correlated with Y?

Scatter · Bubble (third dim)

Above / below a target?

Bullet · Scorecard with delta

---

Chart catalog

Each chart has a single best-fit and one or two anti-patterns. Treat this as the source of truth when proposing dashboard tiles.

---

Color — palette types

Four palette archetypes carry every chart. Pick the palette by the kind of data, not by the brand.

Categorical tokens — how to use them

Marmo ships ten categorical hues. Each hue has a -bright sibling for emphasis bands inside the same category. Use the hue name, not a chart index — designers reference categories by name in Figma, and tokens line up 1:1.

The -bright siblings (--color-chart-cat-teal-bright, --color-chart-cat-violet-bright, …) are paler steps of the same hue:

The two rules that decide which token to use

1. Different categories → different hues. A new category gets a new hue from the categorical palette, in the order above. Never recolor a category between pages — the hue is the category's identity.
2. Same variable, different bands → same hue, -bright sibling. When one variable is split into emphasis bands (new vs. returning, active vs. inactive, current vs. comparison period, converted vs. drop-off), use the same hue's base + -bright rather than a second hue. The eye reads "same family" instead of "two unrelated categories".

Example: A "Users by source" chart uses 10 categorical hues — one per source. The "New vs returning users" chart uses one categorical hue at base + -bright — same category, two bands.

Rules

• 10-hue ceiling for categorical. Beyond ten, perception breaks down — the eye stops distinguishing.
• Reserve semantic colors. Red = error, green = success, amber = warning, in semantic UI roles. The chart-categorical tokens of the same hue (cat-red, cat-green, cat-amber) are categorical-only — never use them to signal status.
• One brand accent on the most-important series; neutrals for the rest when the chart has a single hero series. Almost always clearer than rainbows.
• Color-blind safe. Test categorical palettes through Deuteranopia and Protanopia simulators. When two adjacent hues are close, add patterns or icons.
• Same hue + -bright always before a second hue when the variable is one thing in two bands.

---

Composition — axes, labels, gridlines

How are orders trending this year?

Title · the question

Y label · outside data area

Gridlines · light, behind data

Ticks · 4–7 across

Tooltip · hover + focus

Footnote · source / range

---

Context — pair the chart with a summary

A chart shows the shape of the data. A scorecard answers "should I care right now?". On a dashboard, almost every standalone chart should travel with one — above or beside it — so the reader gets both signals in a single glance.

Revenue$585K +8.4% vs last quarter

---

Sort, order, and direction

Ordering is meaning. Get it wrong and a ranked chart reads like noise.

---

Annotations & reference lines

Annotations turn a chart into a story. Use them sparingly so they don't compete with the data.

• Reference lines for targets, thresholds, or averages. Label at the right edge in a neutral tone — never the categorical palette.
• Vertical event guides for launches, outages, policy changes, or pricing shifts. One-line label, same weight as axis labels, smaller size.
• Cap at two annotations per dashboard-sized chart. More belongs in a dedicated story or report view.
• Don't annotate every peak. If the eye already notices it, the chart is doing its job.
• Annotations are part of the alt text. A screen reader user should learn about the target line and the event from the chart's aria-label or description.

---

Small multiples

When the same metric needs to be compared across many categories, don't pile series onto one chart — break it into a grid of tiny identical charts (small multiples).

US

EU

UK

CA

AU

BR

---

Legends

Direct labels vs. legends

A legend forces the reader to glance back and forth between the data and the key. Direct labels remove that cost.

• Prefer direct labels at the end of lines, beside bars, or on slices when there are ≤ 3 series or the labels fit without overlap.
• Use a legend only when direct labeling would crowd the plot.
• When direct labels are used, omit the legend entirely — never both.
• Direct labels inherit series color; pair them with the same icon/marker used in the chart so the connection survives without color.

Legend overflow — +N More

When the series list outruns the legend strip, don't wrap to a third line and don't shrink the type. Show the first few chips inline (in value order, matching the visual order in the chart) and collapse the tail into a +N More chip whose hover/focus popover lists the rest with the same color swatches.

• Visible chips: 3–5 is the sweet spot at dashboard-tile width.
• The overflow chip is interactive — hover and focus reveal the popover.
• The chips inside the popover use the same swatch + label format as the inline chips. No alternative shapes.
• The overflow popover is supplemental, not the canonical legend — its contents must also be reachable via the chart's "View as table" fallback.

BarListLegend ships this overflow pattern out of the box; see Chart → BarListLegend.

---

Tooltips

---

States

Charts have the same lifecycle as any other surface. Define each one explicitly.

---

Interaction & keyboard

• Hover / focus: show tooltip + crosshair.
• Click: open detail (drill-down) or filter, but never both. Pick one per chart and document it.
• Keyboard: Tab to enter the chart, Arrow keys to move between data points, Enter to select, Escape to clear selection.
• Zoom & pan: opt-in; don't ship them on dashboard tiles by default.
• Brush selection (for time series): only when the user can actually do something with the selection (filter, export, drill).

---

Accessibility — non-negotiable checklist

• Data table alternative linked from every chart (<details> or "View as table" toggle).
• Color is never the sole signal — pair with text, icon, position, or pattern (WCAG 1.4.1).
• role="img" and aria-label on the SVG root, with a one-sentence summary of the chart's takeaway.
• aria-describedby linking to a longer description for complex charts.
• Keyboard navigable through data points with visible focus.
• Live region (aria-live="polite") for dynamic updates on real-time charts.
• Don't rely on hover-only tooltips — same info on focus.
• Respect prefers-reduced-motion for entrance animations and live tickers.
• Color-blind tested. Run categorical palettes through Deuteranopia + Protanopia simulators.

---

Library — Recharts

Marmo charts are built on Recharts. It's the only chart library we use, the only one to install, and the only one to reach for when proposing a new chart. Wrap every chart in a Marmo Card or PageSection shell so spacing, headings, and toolbar patterns stay consistent.

Recharts gives us:

• Bar, column, line, area, stacked area, scatter, pie/donut, composed, and funnel out of the box.
• React-native composition (<BarChart>, <XAxis>, <Tooltip>, …) — no imperative API.
• A ResponsiveContainer that handles parent-driven sizing, which keeps charts honest inside dashboard tiles.

Wrapper checklist

Every chart wrapper we ship on top of Recharts must set:

• Default colors from the token palette (categorical / sequential / diverging / monochromatic).
• Tabular figures + locale-aware number/date formatting.
• <Tooltip> with a crosshair on time-series charts; hover and focus.
• Empty / loading / error states baked in (see States).
• role="img", aria-label, "View as table" toggle.
• prefers-reduced-motion respected — isAnimationActive={false} when the user opts out.

@marmoui/ui ships the shared primitives: ChartContainer + ChartTooltip / ChartLegend (token-aware Recharts wrapper), BarList + BarListLegend (DOM-based ranking), ChartFunnel (generic conversion funnel), LeadLifecycleFunnel (trapezoid funnel with built-in quality-flag Alert), ChartSkeleton, ChartEmpty, ChartTable. See Chart for the API. Higher-level scaffolding (ChartTile, KPIScorecard) used in these docs previews is not yet shipped — tracked on the roadmap.

---

Do / don't

---

Numbers, dates, and locales

• Use the same date and number format as the rest of the app (locale-aware when shipped).
• Tabular figures across all chart text — required for axes and tooltips, where digits must align.
• Compact notation for axis labels (1.2k, 3.4M); full precision in tooltips.
• Currency: ISO format with locale-aware grouping.

---

Outliers and data quality

Real data is messy. The chart is responsible for telling the truth about that, not papering over it.

---

How this connects to the rest of the system

Every rule on this page is an application of the broader Marmo design language — the five criteria every design must pass: is the question obvious, is the answer effortless, does it match expectations, is exploration safe, is it inclusive? A chart is just a screen with axes.

This page sticks to the chart-specific application: title is the question, ≤ 10 categorical hues (with -bright siblings for same-variable bands), ≤ 4 series per single chart, baselines at zero, hover and focus, Skeleton during load, table alternative.

---

Sources (chart-specific)

• Andrew Abela — Chart Chooser methodology (decision-by-question lineage).
• WCAG 2.1 — 1.4.1 (Use of Color).
• Norman, Cooper, Weinschenk, Yablonski, Cleveland & McGill — the cognition and perception research behind these criteria.

---

Related

• Voice & Tone — Empty state, Permission denied formulas
• Colors
• Typography
• Patterns