agent_docs/data_viz_colors.md
Rama main · réplica de lectura del repositorio original.
# Data Visualization Colors
> Single source of truth for chart and visualization colors in ClickStack. Read
> this before adding, changing, or hard-coding a color in any chart, sparkline,
> heatmap, legend, status pill, or other data display.
## TL;DR
There are **three** color systems for data viz, with three different consumption
patterns:
| System | Use for | Source of truth | How to consume |
| ------------------------------------ | ------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Categorical (10 hues)** | Multi-series line/bar/area/pie charts | `CATEGORICAL_HEX_BY_TOKEN` in `utils.ts` (CSS vars mirror it) | `getColorProps(index, label)` (positional) / `getColorFromCSSToken('chart-{hue}')` (by name) |
| **Semantic (success/warn/err/info)** | Status indicators, log levels, deltas | CSS vars `--color-chart-{success,warning,error,info}` | `getChartColor{Success,Warning,Error,Info}()` |
| **Heatmap continuous** | `DBHeatmapChart` density gradients | `darkPalette`/`lightPalette` arrays | Imported directly from `DBHeatmapChart.tsx` |
**Hard rules**:
- **Never** pass a hex color to a chart series. Always go through one of the
helpers above so theme switching works.
- **Never** map log levels to raw Mantine colors (`red.5`, `yellow.6`). Use
`logLevelColor()` / `getColorProps()` — they pick the theme-correct semantic
chart color.
- The categorical palette and the heatmap palette are **different things**.
Don't reuse `--color-chart-{hue}` for heatmap density; don't reuse the heatmap
arrays for series colors.
## Where the colors live
### Categorical palette (`--color-chart-{hue}`)
The categorical palette is **unified across themes** — based on Observable 10
([d3 schemeObservable10](https://observablehq.com/@d3/color-schemes)), with
`chart-blue` swapped to `#437eef` so it matches the brand link color
(`--click-global-color-text-link-default` for ClickStack, same hue for HyperDX
series). All other hues are straight from Observable 10. Identical on HyperDX
and ClickStack:
| Token | Hex |
| ------------------ | --------- |
| `chart-blue` | `#437eef` |
| `chart-orange` | `#efb118` |
| `chart-red` | `#ff725c` |
| `chart-cyan` | `#6cc5b0` |
| `chart-green` | `#3ca951` |
| `chart-pink` | `#ff8ab7` |
| `chart-purple` | `#a463f2` |
| `chart-light-blue` | `#97bbf5` |
| `chart-brown` | `#9c6b4e` |
| `chart-gray` | `#9498a0` |
**Source of truth for categorical hues lives in JS.** The matching
`--color-chart-{hue}` CSS vars, included from
`packages/app/src/theme/_tokens.scss`, are a stylesheet-author
affordance only — `getColorFromCSSVariable` and `getColorFromCSSToken` skip
`getComputedStyle` for categorical tokens and return values straight from
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`. A DOM round-trip per series buys
nothing.
The CSS vars exist for:
- SCSS modules and inline `style={{ background: 'var(--color-chart-blue)' }}`
consumers (no JS import needed).
- Devtools inspection while debugging chart styling.
- Forward-compat: if a future brand wants to override hues, switch
`getColorFromCSSVariable`/`getColorFromCSSToken` back to reading the var and
add per-brand entries to `CATEGORICAL_HEX_BY_TOKEN`.
The categorical hues and semantic chart colors live in a single shared partial,
`packages/app/src/theme/_chart-categorical-tokens.scss` (`chart-categorical-tokens`
and `chart-semantic-tokens` mixins). `theme/_tokens.scss` `@use`s it and
`@include`s both mixins inside its `chart-tokens` mixin, which is then
`@include`'d inside both `[data-mantine-color-scheme]` selectors. Sass inlines
the bodies at each call site, so the emitted CSS has the same per-scheme
specificity as a hand-duplicated block would — but the source lives in **one
place**. **If you change a categorical hex in the shared partial, change it in
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts` too. If you change a semantic hex,
update `SEMANTIC_CHART_PALETTE` in `utils.ts` too — the SCSS and JS sources are
intentionally mirrored.**
Chart series colors are not the brand accent. `success` and `info` reuse
categorical `chart-green` and `chart-blue`. The yellow ClickStack accent stays
in non-chart chrome (Mantine accent, sidebar, Click UI globals).
### Semantic chart colors (`--color-chart-{success|warning|error|info}`)
```text
--color-chart-success # success / OK / ingested fills
--color-chart-warning # warnings, throttling, slowdowns
--color-chart-error # failures, errors, alerts firing
--color-chart-info # info-level logs, neutral "primary" series
--color-chart-success-highlight # hover/selected variants (lighter shades)
--color-chart-warning-highlight
--color-chart-error-highlight
```
Defined in the shared `chart-semantic-tokens` mixin. `success` reuses
categorical `chart-green` (`#3ca951`); `info` reuses categorical `chart-blue`
(`#437eef`). Warning and error use the same Observable hexes.
Unlike the categorical hues, **the semantic CSS vars are read at runtime** via
`getComputedStyle` (see `getSemanticChartColor` in `utils.ts`). That keeps
inline `var(--color-chart-warning)` consumers like `LogLevel.tsx` in sync with
the stylesheet, and it lets JS callers like `getChartColorSuccess()` return the
same hex.
### Single source of truth in TS (`packages/app/src/utils.ts`)
```text
CATEGORICAL_HEX_BY_TOKEN # { 'chart-blue': '#437eef', ... } — file-private,
# authoritative for categorical hues
SEMANTIC_CHART_PALETTE # { success, warning, error, info, …highlight } — file-private,
# SSR/fallback for the semantic CSS vars
COLORS # ordered hex array, derived from CATEGORICAL_PALETTE_TOKENS
```
`COLORS[i]` equals `CATEGORICAL_HEX_BY_TOKEN[CATEGORICAL_PALETTE_TOKENS[i]]`.
`COLORS` is what `getColorFromCSSVariable(i)` returns — on both server and
client, since categorical hues no longer round-trip through the CSS var.
The hue-named `CHART_PALETTE_TOKENS`, `CATEGORICAL_PALETTE_TOKENS`, and
`SEMANTIC_PALETTE_TOKENS` constants live in `packages/common-utils/src/types.ts`
so the Zod schema can reference them (shared with the API).
### Reader functions (`packages/app/src/utils.ts`)
These are the only functions React code should call:
| Function | Returns |
| -------------------------------- | ----------------------------------------------------------- |
| `getColorProps(index, level)` | Categorical color by index, with log-level override applied |
| `semanticKeyedColor(key, index)` | Same, but driven by `key` (e.g. series name) |
| `getColorFromCSSToken(token)` | Resolves any `ChartPaletteToken` (categorical or semantic) |
| `getChartColorSuccess()` | `var(--color-chart-success)` resolved to a hex string |
| `getChartColorWarning()` | `var(--color-chart-warning)` resolved |
| `getChartColorError()` | `var(--color-chart-error)` resolved |
| `getChartColorInfo()` | `var(--color-chart-info)` resolved (brand-primary for info) |
| `getChartColor*Highlight()` | Hover/selected variants |
| `logLevelColor(key)` | Maps `'error' \| 'warn' \| 'info'` → semantic color |
| `getLogLevelColorOrder()` | Stable ordering for log-level series |
Internals worth knowing:
- `getColorFromCSSVariable(index)` returns `COLORS[index % 10]` directly — no
DOM read. Categorical hues are unified across themes, so the JS palette is
authoritative.
- `getColorFromCSSToken(token)` is split:
- Categorical tokens (`chart-blue`, etc.) come straight from
`CATEGORICAL_HEX_BY_TOKEN` — same shortcut, no `getComputedStyle`.
- Semantic tokens (`chart-success`, `-warning`, `-error`) read
`--color-{token}` from `documentElement` via `getComputedStyle` and fall
back to `SEMANTIC_CHART_PALETTE` when running server-side or when the DOM
read fails.
- `getSemanticChartColor(varName, key)` is the shared helper that backs the
`getChartColor{Success,Warning,Error,Info}()` readers. SSR and DOM-read
failures use `SEMANTIC_CHART_PALETTE`. Charts usually render after data
fetch on the client, so that fallback rarely reaches the DOM.
### Legacy `chart-1` … `chart-10` tokens
The number-tile color picker (#2265) initially shipped with numeric tokens
(`chart-1` … `chart-10`). Renamed here to hue-named tokens so stored configs and
the upcoming external API surface are self-documenting.
Existing stored configs keep working. The mapping:
```text
chart-1 -> chart-green (was HyperDX brand green at slot 1)
chart-2 -> chart-blue (was HyperDX slot 2)
chart-3 -> chart-orange
...
chart-10 -> chart-gray
```
It preserves the HyperDX slot ordering from #2265, so HyperDX users see no
visual change.
> **⚠️ ClickStack legacy color caveat.** Pre-rename ClickStack used a different
> slot ordering than HyperDX (`--color-chart-1` was brand blue `#437eef`, not
> brand green; `--color-chart-2` was orange, not blue; etc.). Because the
> migration map preserves HyperDX slot ordering, any ClickStack dashboard saved
> via #2265 will visually shift: stored `chart-1` flips from brand blue to
> Observable green, `chart-2` flips from orange to blue, and so on. We chose
> this trade-off deliberately over branching the legacy map by active theme:
> `LEGACY_CHART_PALETTE_TOKEN_MAP` lives in `common-utils` (shared with the
> API), and migration is one-shot persisted on next save — theme-branching would
> couple common-utils to browser DOM state and still produce wrong results for
> users whose active theme changed since the original pick. Affected users can
> manually re-pick the desired hue via the (now hue-labeled) color picker. Use
> `chart-info` semantic if you need the brand-primary appearance.
**`ChartPaletteTokenSchema` itself stays strict** (a plain `z.enum`). Wrapping
it in `z.preprocess` would force the schema's `z.input` type to `unknown`, which
poisons `validateRequest`'s `req.body` inference in the API package all the way
up to `Dashboard.tiles[i].config.color`. Strict input/output equality is more
important than a one-line runtime migration buried in the schema.
Migration happens at two complementary layers instead:
1. **Fetch-time _and_ write-time** — `normalizeDashboardTileColors` in
`packages/app/src/dashboard.ts` walks every tile and rewrites any legacy
`config.color` to its hue-named equivalent via `resolveChartPaletteToken`. It
runs on every read (`useDashboards` / `fetchLocalDashboards`) and on every
write (`useUpdateDashboard` / `useCreateDashboard`). The write-time pass is
what lets JSON imports (`DBDashboardImportPage`), presets, and
MCP-constructed payloads pass the strict server-side validator, and it
converges the DB-side data on next save instead of leaving legacy tokens in
storage forever.
2. **Render-time** — `DBNumberChart` and `ColorSwatchInput` also call
`resolveChartPaletteToken` as belt-and-suspenders for tiles constructed in
memory between fetch and save (e.g. `ChartEditor` form state, unit-test
fixtures, hand-rolled `Tile` literals).
`LEGACY_CHART_PALETTE_TOKEN_MAP` and `resolveChartPaletteToken` live in
`packages/common-utils/src/types.ts` next to the enum.
### Heatmap palette (component-local)
`packages/app/src/components/DBHeatmapChart.tsx`:
- `darkPalette` (lines ~145–155): 7 stops, indigo → amber.
- `lightPalette` (lines ~156–164): 7 stops, medium blue → deep orange.
- Selected at the call site by `useMantineColorScheme()` and
`colorScheme === 'light' ? lightPalette : darkPalette`.
These are **scheme-aware, not brand-aware**: HyperDX dark and ClickStack dark
share the same heatmap gradient, same for light. Red is intentionally omitted
from the high end so it can be reserved for error overlays.
`DBHeatmapChart.tsx` re-exports `darkPalette` and `lightPalette`.
`DBSearchHeatmapChart.tsx` imports them via that re-export — **do not**
duplicate the arrays in another component.
### Trace and delta-specific colors
A few component-local accents that are **not** part of the categorical or
semantic palettes:
- `ALL_SPANS_COLOR = 'var(--mantine-color-blue-6)'` in
`packages/app/src/components/deltaChartUtils.ts` — the "all spans" reference
bar in `DBDeltaChart`. Keep using this var; don't replace it with a
categorical token (it's a comparison reference, not a series).
- Trace waterfall span tints in `DBTraceWaterfallChart.tsx` — derived from span
attributes, not from this palette.
## Storybook reference
The visual reference for the categorical and semantic palettes is the storybook
story at `packages/app/src/theme/ChartColors.stories.tsx`. It renders
`AllChartColors`, `BarChartPreview`, `LineChartPreview`,
`SemanticColorsPreview`, and `AccessibilityCheck`. Run storybook in the `app`
package to inspect both schemes side by side.
The number-tile color picker (`ColorSwatchInput.stories.tsx`) renders the same
tokens through the user-facing picker UI.
## How to consume (recipes)
### Multi-series time-series chart
`ChartUtils.tsx → setLineColors` already wires the categorical palette per
series via `getColorProps(index, level)` in `packages/app/src/ChartUtils.tsx`.
**You should not have to think about chart colors when adding a new chart that
goes through `seriesToTimeSeries` / `setLineColors`** — they handle it.
If you're rendering a custom chart outside that pipeline:
```tsx
import { getColorProps } from '@/utils';
const series = data.map((s, i) => ({
name: s.label,
color: getColorProps(i, s.label),
data: s.points,
}));
```
`level` (the second arg) is used to override with semantic colors when the label
looks like a log level (`'error'`, `'warn'`, `'info'`, etc.). Pass `s.label` if
it might encode a log level, otherwise pass an empty string.
### Identity color ("this thing is always blue")
For UI surfaces that should always render a specific hue regardless of
multi-series ordering:
```tsx
import { getColorFromCSSToken } from '@/utils';
<Text c={getColorFromCSSToken('chart-blue')}>Always blue</Text>;
```
Or directly in CSS:
```tsx
<Box style={{ background: 'var(--color-chart-blue)' }} />
```
### Status pill / delta indicator
```tsx
import { getChartColorError, getChartColorSuccess } from '@/utils';
<Box style={{ background: getChartColorError() }} />
<Box style={{ background: getChartColorSuccess() }} />
```
These functions return resolved hex strings, so they can be used in inline
styles or passed to libraries that don't understand CSS vars (e.g. `uPlot`'s
canvas fills).
If you're styling a DOM element with regular CSS, prefer the var directly:
```tsx
<Box style={{ background: 'var(--color-chart-success)' }} />
```
The var route reacts instantly to theme switches without re-running React. Use
the function form only when you need a string at compute time (canvas/WebGL,
library config objects, etc.).
### User-customizable chart color (number tile etc.)
`ColorSwatchInput` stores the choice as a `ChartPaletteToken`. Resolve to a hex
at paint time via `getColorFromCSSToken(token)`. Never store hex strings in
chart configs — tokens reflow correctly across themes and color modes.
### Heatmap
```tsx
import { useMantineColorScheme } from '@mantine/core';
import { darkPalette, lightPalette } from '@/components/DBHeatmapChart';
const { colorScheme } = useMantineColorScheme();
const palette = colorScheme === 'light' ? lightPalette : darkPalette;
```
That's the only correct way to consume the heatmap gradient. Never reconstruct
it.
### Pie / donut where slice order matters
The categorical palette is **ordered for distinguishability** — adjacent slots
are designed to contrast. If you're drawing a pie chart where the largest slice
should always be the most prominent color, sort your data first and let the
index map to the palette naturally:
```tsx
const sorted = data.toSorted((a, b) => b.value - a.value);
const slices = sorted.map((d, i) => ({
...d,
color: getColorProps(i, d.label),
}));
```
`ChartUtils.tsx → buildPieChartData` already does this.
## Color mode
- `--color-chart-success` uses categorical `chart-green` (`#3ca951`).
- `--color-chart-info` uses categorical `chart-blue` (`#437eef`, same as
`--click-global-color-text-link-default`), so info-level logs and
`getChartColorInfo()` render that blue.
- The brand accent is **yellow** (`--palette-brand-300: #faff69`). It is **not**
in the chart palette and should not be added — yellow on a light background
fails contrast, and yellow as a series color reads as "warning" in most
contexts.
- The dark/light scheme split is handled by CSS (the same vars get redefined
inside each scheme selector). React code does not need to branch on scheme
except for the heatmap palette.
- The chart vars are intentionally included in both the dark and light blocks.
Change the shared mixin, not one selector.
## Adding new entries
### A new categorical hue (11th token)
Don't, unless you have a real need. Ten distinguishable hues is the upper bound
for readable categorical legends — beyond that, viewers can't tell slices apart,
and color-blind viewers definitely can't. Solutions in descending order of
preference:
1. **Group small categories** into "Other" before charting.
2. **Reuse slots** with patterns/strokes/labels for disambiguation.
3. If you really must extend: add `--color-chart-{newhue}` to the shared
`_chart-categorical-tokens.scss` partial — one edit covers both schemes via
the existing `@include` chain. Then append
`'chart-{newhue}'` to `CHART_PALETTE_TOKENS` in `common-utils/src/types.ts`,
add the hex to `CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`, and add a label
entry in `ColorSwatchInput.tsx` → `TOKEN_LABELS` and
`ChartColors.stories.tsx` → `COLOR_LABELS`.
### A new semantic color (e.g. `--color-chart-pending`)
1. Pick the hex.
2. Add `--color-chart-pending` and (if needed) `--color-chart-pending-highlight`
to the `@mixin chart-semantic-tokens` block in
`_chart-categorical-tokens.scss`. The mixin is `@include`'d from
`theme/_tokens.scss` inside each scheme selector — one edit covers dark
and light.
3. Add `pending` (and optionally `pendingHighlight`) to `SEMANTIC_CHART_PALETTE`
in `utils.ts`.
4. Append `'chart-pending'` to `CHART_PALETTE_TOKENS` (and
`SEMANTIC_PALETTE_TOKENS` slice will pick it up automatically) in
`common-utils/src/types.ts`.
5. Add a `getChartColorPending()` reader in `utils.ts` that calls
`getSemanticChartColor('--color-chart-pending', 'pending')`.
6. Update `ChartColors.stories.tsx` `SEMANTIC_CHART_COLORS` so the new color
shows up in the design-tokens story.
7. Add a `'chart-pending': 'Pending'` entry to `TOKEN_LABELS` in
`ColorSwatchInput.tsx`.
8. If it should override based on a label / status string, extend
`getLevelColor` / `logLevelColor` accordingly.
### A new heatmap palette
The current arrays were tuned to (a) be visible on the chart's dark/light
background, (b) avoid red at the high end so error overlays stay readable, and
(c) follow a perceptually monotonic luminance ramp. Don't add a new palette
without those three properties verified — both "physically dim" and
"perceptually noisy" gradients hurt readability.
If you do need to add one (e.g. for a different chart type), keep it
component-local like the existing ones, and re-use the same scheme-pick pattern
(`useMantineColorScheme` + ternary).
## Anti-patterns
```tsx
<Bar fill="#4269d0" /> // hex string in a chart
<Line stroke="red" /> // CSS color keyword
<Pill bg="green.5" /> // raw Mantine palette for a status
<Bar fill={CATEGORICAL_HEX_BY_TOKEN['chart-blue']} /> // palette object is module-private
```
Why each is wrong:
- **Hex / keyword**: bypasses theme switching. Dark/light won't react, and any
future per-theme tweak won't propagate.
- **Raw Mantine**: bypasses semantic mapping. `green.5` is not the same as
`--color-chart-success` once we tweak the brand palette.
- **Importing palette objects**: `CATEGORICAL_HEX_BY_TOKEN` and
`SEMANTIC_CHART_PALETTE` are module-private. The exported surface is the
reader functions, the token enums, and `COLORS` (the SSR fallback array —
prefer `getColorProps` / `getColorFromCSSToken` over indexing it directly).
## Pre-merge checklist for chart-touching PRs
- [ ] Toggled dark ↔ light — categorical and semantic colors stay legible on
both backgrounds; heatmap gradient flips palettes.
- [ ] Status indicators use `getChartColor*()` / `var(--color-chart-*)`, not raw
Mantine colors.
- [ ] No new hex strings in chart components — all colors flow through
`utils.ts` helpers or CSS vars.
- [ ] If you added or changed a categorical hex, changed it in **both** places
(`_chart-categorical-tokens.scss` shared partial,
`CATEGORICAL_HEX_BY_TOKEN` in `utils.ts`).
- [ ] If you added or changed a semantic hex, changed it in **both** places
(`chart-semantic-tokens` mixin in `_chart-categorical-tokens.scss`,
`SEMANTIC_CHART_PALETTE` in `utils.ts`).
- [ ] Storybook `Design tokens / Chart colors` still renders correctly.
## File reference summary
| What | Where |
| --------------------------------------------------- | -------------------------------------------------------------------------------- |
| Shared chart vars (10 categorical hues + semantics) | `packages/app/src/theme/_chart-categorical-tokens.scss` |
| `chart-tokens` mixin (`@include` chain) | `packages/app/src/theme/_tokens.scss` |
| JS palette objects + reader functions | `packages/app/src/utils.ts` |
| Palette token enum + legacy migration | `packages/common-utils/src/types.ts` |
| Multi-series wiring (`setLineColors` etc.) | `packages/app/src/ChartUtils.tsx` |
| Number-tile color picker | `packages/app/src/components/ColorSwatchInput.tsx` |
| Heatmap palettes | `packages/app/src/components/DBHeatmapChart.tsx` (`darkPalette`, `lightPalette`) |
| Storybook visual reference | `packages/app/src/theme/ChartColors.stories.tsx` |
| Delta "all spans" reference color | `packages/app/src/components/deltaChartUtils.ts` (`ALL_SPANS_COLOR`) |