Charts (line / bar / area / pie / scatter / graph)
components specs/components/charts.kmd
Canonical chart primitives — line / bar / stacked-bar / area / scatter / pie / donut / sparkline / graph (node-edge). Behavior contract; library binding is impl detail. Replaces ad-hoc chart-lib picks in Koder admin tools (Forge metrics, Hub analytics, Talk stats). Modeled after Ant Design G2/G6 + PatternFly + Material 3.
Quando esta spec se aplica
Triggers primários
- Pick a chart component for a Koder product surface
Todos os triggers
- Render data visualization in a Koder admin tool
- Replace a third-party chart with the canonical primitive
Corpo da especificação
Component — Charts
Status: v0.1.0 — Draft. Behavior contract; library binding (Victory / Recharts / G2 / fl_chart for Flutter) is impl detail chosen per surface.
R1 — Chart-type catalog
| Type | Use when |
|---|---|
| Line | Continuous data over time; 1-5 series |
| Bar | Categorical comparison; vertical default, horizontal on long labels |
| Stacked bar | Part-of-whole over categories |
| Area | Magnitude over time with emphasis on cumulative value |
| Scatter | Correlation between two variables; outlier detection |
| Pie | Part-of-whole, ≤ 5 slices (otherwise use bar) |
| Donut | Pie + central value display |
| Sparkline | Inline mini-chart in tables / cards; no axes |
| Graph | Nodes + edges (topology, dependency, mind-map) |
Other types (treemap, sankey, heatmap, candlestick, 3D, geospatial) out of v0 — open separate ticket if a Koder product needs one.
R2 — Color usage
- Series colors: cycle through Verge accent palette in canonical order
(defined in
specs/themes/color-roles.kmd— for v0 use--kdr-accent→ +30° HCL → +60° → +90° → +120°). NEVER hardcode hex; consume via tokens. - Status colors (success / warning / danger) used ONLY when the data itself is status-typed (uptime chart green/yellow/red); otherwise stick to the accent cycle.
- Color-blind a11y per
specs/themes/a11y-modes.kmd(#062):- Lines and bars MUST also vary in pattern / stroke style when ≥ 3 series share a chart — color alone is insufficient.
R3 — Axes
- X-axis labels rotate to 45° when overlap detected (auto), otherwise horizontal.
- Y-axis: locale-aware number formatting (per
specs/content/grammar- and-mechanics.kmdR4 —1,234.56en-US vs1.234,56pt-BR). - Grid lines: subtle (
--kdr-borderat 50% opacity); never dominate the data.
R4 — Tooltips
On hover (or focus / tap), show a tooltip:
- Series name (per legend) + data point value
- For multi-series at the same X position: stacked tooltip listing all series + values
- Position: above the data point; flips below if no space
- Dismiss: pointer leave / blur / outside-tap / Esc
R5 — Keyboard navigation
| Key | Action |
|---|---|
| Tab | Enter the chart (focus moves to first data point) |
| ← / → | Navigate adjacent data points within a series |
| ↑ / ↓ | Switch active series (multi-series charts) |
| Enter | "Drill" — emit a drill event (consumer handles) |
| Esc | Exit chart focus |
R6 — Screen-reader
- Each chart MUST emit a
<table>data-alternate sibling (role="presentation"if visually hidden), so SR users can read the data values without parsing the SVG. - Chart container
role="img"witharia-label= chart title + brief description (e.g. "Line chart, monthly active users, 6 months"). - On focused data point: live-region announces "{series}: {value} at {x-label}".
R7 — i18n
- Axis labels, legend labels, tooltip series names translatable per
specs/i18n/contract.kmd. - Number formatting per locale (R3).
- Date formatting on time-axis charts: locale-aware short form
(per
specs/components/date-picker.kmdR7).
R8 — OUIA
Per specs/testing/ouia-test-hooks.kmd:
data-ouia-component-type="Chart"(orLineChart,BarChart, … for type-specific)data-ouia-component-id="<chart-slug>"data-ouia-safe="true"only when data loaded + render complete (no animation in progress).
R9 — Empty / loading / error
- Empty data: render
patterns/empty-state.kmdinside chart container. - Loading:
components/skeleton.kmdshape mirror (a placeholder grid). - Error: error pattern with retry button (when data fetch fails).
Não-escopo
- Specific library binding (Victory vs Recharts vs G2 vs fl_chart) — consumer choice; spec ratifies behavior contract only.
- Real-time streaming / WebSocket data updates (separate ticket if pursued).
- 3D, geospatial, financial candlestick, heatmap, treemap, sankey (case-by-case; open ticket per type when a product needs one).
Referências
specs/themes/verge.kmdspecs/themes/color-roles.kmdspecs/components/data-table.kmdspecs/testing/ouia-test-hooks.kmd