Visualizations

# Chart Color & Encoding System

By **Micah Boswell** ([socraticstatic](https://github.com/socraticstatic)). Copyright © 2026 Micah Boswell. All rights reserved.

A token-driven, math-backed palette system for ECharts dashboards. Generates categorical, sequential, and diverging palettes, and pairs every color slot with a matching dash, decal, and marker shape so meaning survives even when color fails. **Categorical** palettes are audited pairwise against WCAG contrast, color-vision deficiency (CVD) simulation, and grayscale. **Sequential and diverging** ramps are audited for background contrast and built for monotonic OKLab lightness (their grayscale-survival property); pairwise ΔE separation is intentionally not applied to ramps, whose stops are designed to be perceptually adjacent. Honesty note: past ~6 hues, no palette keeps colors reliably distinct under dichromacy — the configured CVD/ΔE floors in `constraints.ts` are deliberately minimal at high N, and the redundant dash/decal/shape encodings are what carry series identity.

> Current version: **0.7.0** (`PALETTE_VERSION` in `src/charts/version.ts`; history in `CHANGELOG.md`).

---

## Jobs To Be Done

**Primary**
- **JTBD-1** — Pick a palette I can defend (contrast + CVD + grayscale audited).
- **JTBD-2** — Charts stay readable for colorblind users (color + dash + decal + shape).
- **JTBD-3** — Same entity stays the same color everywhere.
- **JTBD-4** — Doesn't break when series count changes (graceful Top-N + Other).
- **JTBD-5** — Light and dark mode equally good.
- **JTBD-6** — Right chart-type encoding chosen automatically.
- **JTBD-7** — Prove it works before shipping (live QA harness).

**Secondary**
- **JTBD-8** — Per-user color pin (`localStorage`, scoped by entity ID).
- **JTBD-9** — Brand-locked anchor slots seed the optimizer.
- **JTBD-10** — Surface infeasibility with documented relaxation order.
- **JTBD-11** — Instant theme switch (precomputed cache).
- **JTBD-12** — Stay maintainable (no raw color literals; versioned palette; docs always current).

**Out of scope (named, not built):** multi-tenant solving, SSR/PDF export, telemetry, task-based usability study.

---

## Architecture

```text
  index.css tokens (HSL)
         │
         ▼
  constraints.ts  ──────┐
  brand/semantic locks ─┤
  background + chrome  ─┼──►  optimizer (OKLab + CVD + gamut)
  N + posture          ─┤              │
  reserved slots       ─┘              ▼
                                ordered slot list
                                (color, dash, decal, shape)
                                       │
                                       ▼
                          echartsTheme.ts adapter
                                       │
                                       ▼
                          ECharts components (demo)
                                       │
                                       ▼
                          QA harness (CVD / grayscale / contrast)
```

---

## Deliverables

| # | Deliverable | Serves JTBD |
|---|---|---|
| 1 | Token contract (`src/index.css` + `tailwind.config.ts`) | 1, 5, 9, 12 |
| 2 | Constraint config (`src/charts/constraints.ts`) | 1, 9, 10 |
| 3 | Palette optimizer (`src/charts/palette/`) | 1, 2, 4, 10 |
| 4 | Aligned encoding scales (`src/charts/encoding.ts`) | 2, 3, 6 |
| 5 | ECharts theme adapter (`src/charts/echartsTheme.ts`) | 5, 6, 11 |
| 6 | Demo route `/charts` | 7 |
| 7 | QA harness (CVD / grayscale / contrast / posture / N) | 2, 7, 10 |
| 8 | Test suite | 1, 2, 4, 12 |
| 9 | Override + versioning scaffolding | 8, 12 |
| 10 | This `README.md` | 12 |
| 11 | `CHANGELOG.md` | 12 |

---

## Tiers

### Tier 1 — Tokens & constraints
Semantic chart tokens in `index.css` (HSL, light + dark): surfaces, neutrals, status, anchors, states. Tailwind `chart` color group exposes them. `constraints.ts` defines ΔE thresholds, posture presets (`kpi`, `comparative`, `exploratory`), Top-N + Other overflow, and constraint-relaxation priority.

### Tier 2 — Optimizer & encoding scales
- `palette/cvd.ts` — Machado 2009 deutan/protan/tritan matrices.
- `palette/distance.ts` — OKLab ΔE + worst-of-three CVD ΔE.
- `palette/gamut.ts` — chroma-reduction gamut mapping into sRGB.
- `palette/categorical.ts` — seeded farthest-point + simulated-annealing maximin solver.
- `palette/ramps.ts` — monotonic-L OKLCH sequential and diverging ramps.
- `palette/assignment.ts` — bipartite stable assignment when N changes.
- `encoding.ts` — `dashScale`, `decalScale`, `shapeScale` indexed 1:1 with color.

### Tier 3 — Adapter, demo, lifecycle
- `echartsTheme.ts` reads CSS vars at runtime and emits an ECharts theme + helpers (`buildLineSeries`, `buildBarSeries`, `buildVisualMap`).
- `components/charts/EChart.tsx` wraps `echarts-for-react` with atomic theme swap.
- `/charts` is a **constrained palette builder** beside the chart preview: chart type, N, theme, vision preview, and fixtures are controlled from one place. Posture, palette family, and ramp shape are derived. The default N snap is capped to the runtime-probed safe max so out-of-the-box palettes clear every configured ΔE / CVD floor and WCAG 3:1 contrast with zero solver relaxations; the slider can be dragged past the safe cap into an educational range where the audit panel shows exactly which floors break.
- Every render runs the accessibility audit (`audit.ts`): per-vision OKLab ΔE (normal + deutan + protan + tritan + achromatopsia) against per-mode thresholds, plus WCAG 2.2 SC 1.4.11 (≥ 3:1) contrast vs. background. Result is shown as a `pass` / `warn` / `fail` badge with per-vision detail.
- `setEntityColor(entityId, slotIndex)` persists per-user pins in `localStorage`.
- `PALETTE_VERSION` aligns with `CHANGELOG.md`.

---

## Run

```bash
npm install
npm run dev
```

Then open the preview and navigate to **`/charts`**.

### Tests

```bash
npx vitest run
```

Covers the palette primitives (`stableAssign`, `sequentialRamp` L-monotonicity, `divergingRamp` length, aligned encoding scales), `solveCategorical` property tests across N=2..8 (determinism, in-gamut sRGB, threshold-or-relaxation contract, lock-honoring), entity pins (permutation safety, collision bumping, paired remap of color/dash/decal/shape), URL state round-trips, and fixture determinism + messy-mode characteristics (nulls on lines, missing heatmap cells, diverging outliers).


### Reading the accessibility harness
- **Overall verdict**: `pass` (all modes pass + WCAG ≥ 3:1), `warn` (≤ 1 vision mode fails, contrast still passes), or `fail`.
- **Per-vision tiles**: minimum pairwise ΔE under each simulation, vs. the configured threshold. Note the CVD and normal-vision thresholds (`constraints.ts`) are deliberately low floors, not perceptual guarantees — they exist to catch outright collisions while the dash/decal/shape scales carry identity at high N.
- **Worst contrast vs. background**: WCAG 2.2 SC 1.4.11 ratio for non-text marks; threshold ≥ 3:1.
- **Best-practice rationale**: one-line explanation of why this chart type has its specific limits, plus per-N warnings (e.g. "Pie charts above 5 slices misrepresent magnitudes").

### Exporting a palette

The green **Export palette** button on `/charts` opens a tabbed dialog with five emitters from `src/charts/paletteExport.ts`:

- **CSS variables** — `:root` (or `.dark`) block with `--chart-bg`, `--chart-cat-N`, `--chart-seq-N`, `--chart-div-N`, plus semantic positive/negative. When Compare is on with normal vision, Variant B is emitted under `[data-chart-variant="b"]`.
- **Tailwind config** — `chart.cat/seq/div` map that references the CSS vars above, paste-ready under `theme.extend.colors`.
- **ECharts theme** — full `registerTheme` payload (color, backgroundColor, axis/legend/tooltip, sequential + diverging `visualMap` ramps).
- **Figma Tokens** — Tokens Studio / W3C-style JSON with `chart.{surface,semantic,categorical,sequential,diverging}` and `$metadata.generator`.
- **SVG swatches** — single-page printable sheet labeled with hex + slot index.

The **Export audit report** button (next to it) still produces the standalone HTML audit (charts + warnings + accessibility metrics, single-variant or A vs. B).

### Palette builder

The only active builder controls live beside the chart preview. They update the rendered chart immediately, clamp N to the safe built-in range for the selected kind/theme, and clear any stale inline token overrides on load so built-in palettes remain compliant.

### Coach tour

A coach tour auto-opens on first visit (`localStorage["chart-tour-seen-v1"]`) and walks through the chart-side builder controls and export flow. Replay it anytime via **Take the tour** in the page header.

### Presets

The **Presets** panel ships 6 curated starters ("Finance KPI", "Analytics exploratory", "Board / comparative", "Marketing share", "Ops heatmap", "Variance / diverging") and lets you save your own named `(kind, n, theme)` configurations under `localStorage["chart-palette-presets-v1"]`. Color overrides are stored separately so presets stay solver-stable across palette updates. The **Compare presets** sub-panel lets you pick any two (curated, user, or the live builder state) and shows a side-by-side diff of chart kind, family, posture, N, recommended N, max N, and theme — differing rows highlighted in warning tint, ⚠ flags N above the kind's recommended ceiling.

### Entity pins

The **Entity pins** panel (categorical charts) lets you lock a series to a specific slot — color, dash, decal, and shape together — so the same entity keeps the same identity across filters, reloads, and dashboards. "Auto" means "let the solver assign the next free slot in order"; picking `Slot k` writes the pin to `localStorage["chart-entity-color-pins-v1"]` via `setEntityColor`. Collisions (two entities pinning the same slot) are auto-resolved — the later entity is bumped to the next free slot and listed under "Collisions". Implements JTBD-3 ("keep the same entity the same color everywhere").

### Benchma