Chart Color & Encoding System

By Micah Boswell (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

  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

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

npm install
npm run dev

Then open the preview and navigate to /charts.

Tests

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").