components / datachart

DataChart

Pure-SVG chart surface for line, bar, and area series with optional legend and lightweight point tooltips.

Overview

What it is

This section explains the intent of the component before the implementation details.

  • DataChart gives DK a first-party data-visualization surface without introducing a third-party chart dependency.
  • It focuses on the core chart shapes most product teams need first: line, bar, and area.

Aliases

chart, graph

Decision guide

How to choose it

Use these notes to decide quickly whether this is the right DK component for the job.

Decision guide

  • Choose DataChart when the interaction should feel deliberate, documented, and reusable across product surfaces.
  • If the scenario is more specialized than the current DataChart contract, prefer a simpler component or build a dedicated workflow on top of the lower-level DK primitives.

Do

  • Keep the DataChart label, value, or status language direct enough to scan quickly.
  • Use the documented size and state recipes instead of inventing one-off variants in product code.

Do not

  • Do not hide the main purpose of DataChart behind decorative copy or overloaded surface treatments.
  • Do not stretch DataChart into a workflow it was not designed to handle just because the visuals are close.

Usage

When to use

Prefer these situations when choosing this component.

  • Use DataChart for compact product analytics, trend summaries, or operational dashboards.
  • Use the tooltip and legend together when multiple series share the same canvas.

Usage

When not to use

These patterns are better served by a different component or a simpler surface.

  • Do not use DataChart for stacked, zoomable, or exploration-heavy analysis in this v1 contract.
  • Do not use it when a table communicates the values more clearly.

Anti-patterns

  • Using DataChart as a generic layout container instead of a purpose-built interaction or content surface.
  • Forking the documented recipe in product code instead of extending the shared DK contract.

Migration notes

  • Migrate legacy datachart usage by mapping existing variants and states onto the documented DK props before porting any custom styling.
  • Treat the docs examples as the reference contract for accessibility and event behavior during adoption.

Anatomy

Structural parts

The anatomy explains which pieces matter to the recipe and accessibility model.

chart canvas shell

surface

Owns the chart background, border, and internal spacing.

category labels and grid

axis

Supports interpretation of the plotted values.

series explanation

legend

Maps color to each series label.

point detail

tooltip

Shows focused or hovered value details.

API

Public interface

The docs contract distinguishes props, DOM events, and slots so integration behavior is explicit.

Props

NameTypeDefaultDescription
type'line' | 'bar' | 'area'—Chart rendering mode.
seriesArray<{ id: string; label: string; values: number[]; tone?: "brand" | "success" | "warning" | "danger" | "neutral" }>—Series values to plot.
categoriesstring[]—Category labels aligned with each value index.
titlestring—Chart title.
descriptionstring—Optional supporting description.
heightnumber280SVG height in pixels.
showLegendbooleantrueShows the series legend.
showGridbooleantrueShows horizontal grid lines.
showTooltipbooleantrueShows hover/focus tooltip details.
valueFormat(value: number) => string—Optional formatter for displayed values.
emptyTitlestring—Title shown when no chart data is available.
emptyDescriptionstring—Supporting empty-state guidance.
themeThemeContract—Overrides the compiled DK theme used to resolve tokens and recipes for this component.

Slots

NameDescription
defaultDataChart is prop-driven in v1 and does not expose custom series or tooltip slots.

Recipes

Variants, sizes, and states

These notes summarize the intended recipe surface rather than exposing raw implementation detail first.

Variants

  • line: Trend-focused path chart
  • bar: Comparative column chart
  • area: Filled trend chart

Sizes

  • default: DataChart uses an explicit height prop rather than recipe sizes.

States

  • rest: Chart rendered without an active point
  • tooltip: One point or bar is active for focused reading

Accessibility

Accessibility contract

This is the behavior the component promises to assistive tech and keyboard users today.

Semantics

  • Uses figure and SVG semantics for the chart surface and associated description.

Keyboard

  • Focused points or bars can reveal the same tooltip details as hover.

Screen readers

  • The chart title, description, legend, and focused values should communicate enough context for non-visual users to understand the trend.

Checklist

  • Verify the visible label or title still produces a clear accessible name.
  • Verify focus remains obvious in every supported state and size.
  • Verify disabled, selected, and error states do not rely on color alone.

Implementation

Tokens and slot vars

This section shows the representative compiled slot variables that the runtime consumes for the selected design system.

root

--dk-chart-gap
0.75rem

surface

--dk-chart-surface-bg
#f2f5fb
--dk-chart-surface-fg
#16181c
--dk-chart-surface-border
#95989d
--dk-chart-surface-radius
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)
--dk-chart-surface-padding
1rem
--dk-chart-grid
#95989d
--dk-chart-axis
#16181c
--dk-chart-brand
#2072e4
--dk-chart-success
#279936
--dk-chart-warning
#dca400
--dk-chart-danger
#cc272e
--dk-chart-neutral
#95989d

title

--dk-chart-title-size
1rem
--dk-chart-title-weight
650

description

--dk-chart-description-size
0.875rem

axis

--dk-chart-axis-size
0.75rem

legend

--dk-chart-legend-size
0.8rem

tooltip

--dk-chart-tooltip-bg
#f2f5fb
--dk-chart-tooltip-fg
#16181c
--dk-chart-tooltip-border
#95989d
--dk-chart-tooltip-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

empty

--dk-chart-empty-size
0.9rem

Implementation notes

  • DataChart stays deliberately small in scope so it can remain first-party, proof-friendly, and dependency-free.

Implementation checklist

  • Use the public component API first and only drop to lower-level primitives when the component contract genuinely does not fit.
  • Keep theme overrides token-driven so proofs and recipes stay meaningful.
  • Verify the shipped examples and proof fixtures still represent the real product scenario you are implementing.

Examples

Copy-paste examples

Each example is intentionally practical, grouped by starter, common pattern, and edge-case coverage.

Examples
3
Depth
expanded

Starter

1 example

starter

Starter: line trend

A simple trend chart for one or two comparable series.

Copy snippet

<DataChart type="line" title="Revenue" categories={['Jan', 'Feb', 'Mar']} series={[{ id: 'mrr', label: 'MRR', values: [12, 18, 24] }]} />

Common patterns

1 example

common

Common: comparative bar chart

Bar mode works well for side-by-side category comparisons.

Copy snippet

<DataChart type="bar" title="Activation" categories={['Week 1', 'Week 2', 'Week 3']} series={activationSeries} />

Edge cases

1 example

edge

Edge: filled trend with hidden legend

Area mode can read well for one primary metric and restrained dashboard treatment.

Copy snippet

<DataChart type="area" title="Active users" showLegend={false} categories={['Mon', 'Tue', 'Wed']} series={activeUserSeries} />

Verification

Curated proof fixtures

Proofs stay visible in the docs so the system shows what it can guarantee, not just what it can render.

line

pass

type=line

  • Contrast: 98.5 Lc
  • Layout: 0 / 320, 640

bar

pass

type=bar

  • Contrast: 98.5 Lc
  • Layout: 0 / 320, 640

area

pass

type=area

  • Contrast: 98.5 Lc
  • Layout: 0 / 320, 640