Chart

Overview

Chart é o sistema de visualização de dados do KDS. Ele não inventa um motor próprio: empacota o Recharts num conjunto de componentes opinados (ChartContainer, ChartTooltip, ChartLegend, mais o helper ChartStyle) que tipam, normalizam estilo e plugam direto na arquitetura de tokens canônica — os 5 esquemas cromáticos descritos na seção de Tokens / Chart.

A escolha por Recharts é deliberada. Ele cobre sem fricção os 6 tipos clássicos de gráfico (Area, Bar, Line, Pie, Radar, Radial) que rodam 90% dos dashboards de produto, expõe API declarativa em JSX que combina com as convenções do KDS, e tem footprint razoável quando comparado a alternativas full-canvas como ECharts.

Para visualizações fora dessa cobertura — geomaps, sankey complexos, force-directed networks — esse primitivo não é o caminho; saia da abstração e instale a biblioteca apropriada (Visx, ECharts, Mapbox) na própria página, sem tentar moldar Chart para o que ele não foi feito.

Anatomy

ChartContainer (config + responsive wrapper)
└─ Recharts chart (AreaChart | BarChart | LineChart | PieChart | RadarChart | RadialBarChart)
   ├─ CartesianGrid / PolarGrid       ← grade (opcional)
   ├─ XAxis / YAxis / PolarAngleAxis  ← eixos
   ├─ ChartTooltip
   │  └─ ChartTooltipContent          ← tooltip estilizado
   ├─ ChartLegend
   │  └─ ChartLegendContent           ← legenda estilizada
   └─ Area | Bar | Line | Pie | Radar | RadialBar  ← séries

ChartContainer cuida de três coisas: contexto (passa o config para tooltip e legenda), responsividade (envolve em ResponsiveContainer do Recharts) e geração de variáveis CSS (ChartStyle) para que cada série tenha cor consistente em light e dark mode. Tudo o que vai dentro é Recharts puro — você compõe a visualização exatamente como faria no Recharts standalone, sem camadas extras de DSL.

Subcomponents

Usage

A composição mínima leva ChartContainer envolvendo uma chart do Recharts, com tooltip e legenda nos slots correspondentes:

import {
  ChartContainer,
  ChartTooltip,
  ChartTooltipContent,
  type ChartConfig
} from "@kalvner/kds/data/chart";
import { Area, AreaChart, CartesianGrid, XAxis, YAxis } from "recharts";

const config = {
  revenue: { label: "Receita", color: "var(--color-chart-cat-1)" }
} satisfies ChartConfig;

export function MonthlyRevenue({ data }) {
  return (
    <ChartContainer config={config} className="h-[220px] w-full">
      <AreaChart data={data}>
        <CartesianGrid strokeDasharray="3 3" vertical={false} />
        <XAxis dataKey="month" tickLine={false} axisLine={false} />
        <YAxis hide />
        <ChartTooltip content={<ChartTooltipContent />} />
        <Area
          dataKey="revenue"
          type="monotone"
          stroke="var(--color-chart-cat-1)"
          fill="var(--color-chart-cat-1)"
          fillOpacity={0.3}
        />
      </AreaChart>
    </ChartContainer>
  );
}

Setup

Chart variants

ChartConfig

ChartConfig é o tipo do objeto que descreve cada série da chart — label exibido em tooltip e legenda, cor (token CSS), e ícone opcional. As chaves precisam casar com os dataKey usados nas séries Recharts.

import type { ChartConfig } from "@kalvner/kds/data/chart";

const config = {
  revenue: {
    label: "Receita",
    color: "var(--color-chart-cat-1)"
  },
  target: {
    label: "Meta",
    color: "var(--color-chart-cat-2)"
  }
} satisfies ChartConfig;

Tooltip & Legend

Os helpers ChartTooltipContent e ChartLegendContent aceitam variações para casos diferentes. Use o que melhor responde à pergunta "o que o leitor precisa saber ao passar o mouse?".

When to use

A escolha entre os 6 tipos depende da forma do dado — não do gosto. A matriz abaixo é a heurística canônica do KDS, com link para o esquema cromático recomendado em cada caso.

When not to use

• Geomaps — choropleth, bubble maps, point maps. Use uma lib dedicada (Mapbox GL, Leaflet, react-simple-maps).
• Networks / sankey / hierarquias — Recharts não tem cobertura decente; instale Visx ou ECharts pontualmente para esses casos.
• Heatmaps densos (matrizes >50×50) — performance e leitura caem; use ECharts ou D3 puro.
• Charts críticos para acessibilidade plena — quando o gráfico é o conteúdo principal de uma página e precisa ser navegável por leitor de tela com semântica de tabela, considere renderizar também uma <table> correspondente em vez de depender só de SVG.

Best practices

Do

• Use sempre tokens KDS (var(--color-chart-cat-N), --color-chart-status-*, etc) para cores de série. O sistema garante consistência multi-tema e segurança para daltonismo.
• Limite Categorical a 5-6 séries — acima disso, agrupe ("Outros") ou troque para small multiples (vários gráficos pequenos).
• Reserve Status para gráficos que encodam significado (sucesso/erro). Em charts puramente categóricos, usar verde = "bom" polui a leitura.
• Mantenha a altura do ChartContainer fixa, mesmo durante loading. Layout shift em dashboards é particularmente desagradável.
• Tooltips com hideLabel em pies e radials — o nome da fatia já é informação suficiente, o header redundante pesa.

Don't

• Não use Pie com mais de 5 fatias — fatias finas viram ruído. Migre para Bar horizontal.
• Não chumbe hex hardcoded em séries — viola a arquitetura de tokens e quebra dark mode.
• Não confie só em cor para diferenciar séries críticas. Reforce com forma (sólido/tracejado), label direto na linha, ou ícone via config.icon.
• Não empilhe Bar/Area quando a soma não tem significado real — o leitor vai inferir uma métrica composta que você não pretendeu comunicar.
• Não use Divergent sem ponto central explícito (zero, baseline, média) — sem o pivô, a paleta vira só "duas cores".

Accessibility

Charts em SVG têm limitações herdadas: leitores de tela leem o SVG como uma lista de elementos, não como uma tabela tabular. O Chart KDS dá ferramentas para mitigar — não milagres.

Related

• Tokens · Chart — os 5 esquemas canônicos com guia de uso por tipo de dado
• Tokens · Sequential — gradiente de uma matiz para dados ordenados
• Tokens · Categorical — hues distintos para categorias nominais
• Tokens · Status — estado semântico discreto
• Recharts — biblioteca subjacente, para composição de chart-types não cobertos aqui
• ChartConfig type — exportado de @kalvner/kds/data/chart
• Chart color schemes foundations (vault interno) — fundamentação acadêmica e de mercado dos 5 esquemas