chart-factory 0.1.2

package/docs/color-guide.md

@@ -0,0 +1,134 @@
+# Color guide — choosing, not configuring
+
+How to make color *decisions* in Chart Factory. For the option reference see
+[API.md](API.md); for the palette surface see
+[Palettes (`ChartFactory.palettes`)](API.md#palettes-chartfactorypalettes).
+This guide is deliberately bounded to Chart Factory's builders — it is not a
+general visualization textbook.
+
+## Rule zero: omit color options
+
+**The defaults are the house style.** Single-series charts use `--chart-primary`
+(brand blue); multi-series charts use the Set2 categorical palette
+(`--area-color-1..8`, CVD-safe, matched across families, theme-aware). Most
+configs should pass **no color options at all** — every color you hardcode is
+one that stops re-theming, stops dark-mode adaptation, and drifts from the
+house look. Reach for a color option only when one of the decisions below
+genuinely applies.
+
+## Pick the palette *type* from the data, not the look
+
+| Your data is… | Type | Test | Examples |
+|---|---|---|---|
+| Ordered, one direction (counts, density, intensity) | **Sequential** | "Is 80 *more of the same thing* than 20?" | `Viridis`, `Blues`, `YlOrRd` |
+| Ordered around a **meaningful midpoint** (zero, average, target, 50%) | **Diverging** | "Is the midpoint a real boundary — above vs below?" | `RdBu`, `Temperature`, `PuOr` |
+| Named categories with no order | **Categorical** | "Would reordering the legend lose nothing?" | `Set2` (default), `OkabeIto`, `Dark2` |
+| Mostly noise, a few values that must pop | **Alert** | "Do only the extremes matter?" | `OrangeAlert`, `ForestAlert` |
+
+The classic mistake is diverging-for-sequential: a red-to-blue ramp on plain
+counts invents a midpoint the data doesn't have. The reverse mistake hides
+one: profit/loss on a `Blues` ramp buries the zero crossing. **Ask where the
+midpoint is. No answer → sequential. Real answer → diverging, and pin it with
+`colorDomain: [-max, max]` so the neutral center sits on the true zero.**
+
+- Heatmap/hexbin/contour/calendar take `colorScheme: 'Viridis'` (or any
+  sequential/diverging palette or d3 interpolator name).
+- `Bar.createDiverging` colors by sign (green/red trend semantics) and
+  `Bar.createLikert` builds its own diverging ramp from the temperature
+  tokens — both already encode direction; don't override either with a
+  categorical palette.
+- Never use a sequential ramp for categories — adjacent steps are
+  indistinguishable as fills; that's what categorical palettes are for.
+
+## Categories: fewer, then gray the rest
+
+Legibility collapses past **6–8 categories** — that's why Set2 has 8 colors,
+not 20. Past that, don't grab a 12-color palette; **shrink the category count**:
+
+```js
+const top = ChartFactory.data.topN(rows, 'revenue', 5, { by: 'segment', other: 'Other' });
+```
+
+The residual bucket is handled for you: **a series or slice named "Other" is
+automatically colored neutral gray** (`--chart-neutral`) by the default
+palettes, and it does *not* consume a palette slot — real categories keep
+their colors. This applies to stacked/normalized/streamgraph areas,
+stacked/grouped/vertical bars, multi-line, histogram overlays, donut
+(including its own `minSlice` fold), and the derived shell legend
+(`legend: true`). Passing explicit `colors` or `colorMap` disables it —
+that's the escape hatch when "Other" is a genuine category.
+
+Keep "Other" **last** in `keys`/data order (`data.topN` already does this):
+gray reads as "the remainder", and remainders belong at the end.
+
+## Reserved meanings — don't spend them on categories
+
+Some colors already mean something in this system. Using them as arbitrary
+category colors creates false signals:
+
+- **Green/red = direction.** `--chart-trend-up` / `--chart-trend-down` drive
+  slope-trend coloring, diverging bars, and up/down markers. A category that
+  happens to be green will be read as "good".
+- **Red = anomaly** (`--chart-anomaly`): pulse/forecast anomaly markers.
+- **Gray = de-emphasis**: the residual bucket, muted series in
+  highlight modes, context layers. Never use gray for a category you want
+  the reader to care about.
+- Avoid red+green as a categorical *pair* entirely — it's the most common
+  color-vision confusion. If direction matters and accessibility is critical,
+  pair color with another channel the way the builders already do
+  (slope direction, diverging sides, anomaly markers are all positional too).
+
+For context/reference series (a benchmark line behind the real data, last
+year's shape), use `extraLayers` with a neutral:
+`{ type: 'line', y: 'lastYear', color: 'var(--chart-neutral)', behind: true }`.
+
+## Accessibility (CVD)
+
+The defaults are already safe: **Set2** (categorical) and **Viridis**-family
+(sequential) are colorblind-safe. If you deviate, check before shipping:
+
+```js
+ChartFactory.palettes.isColorblindSafe('RdYlGn')          // false — avoid
+ChartFactory.palettes.list('categorical')
+    .filter(ChartFactory.palettes.isColorblindSafe)       // safe alternatives
+```
+
+`OkabeIto` is the strictest categorical choice (designed for all CVD types) —
+but note its 8th color is pure black, which disappears on dark backgrounds;
+slice it to 7 if you need dark-mode parity. `RdYlGn` (“traffic light”) is the
+most-requested unsafe palette; `RdYlBu` or `Temperature` carry the same
+bad-to-good reading safely.
+
+## Dark mode: already handled
+
+Sequential/diverging ramps re-anchor their pale end toward the surface under
+`[data-theme="dark"]`; the categorical tokens have dark variants; charts
+re-theme on `ChartFactory.rerenderAll()` (or `setTheme(name)`, which does
+both steps). **Do not compensate manually** — no "dark mode palettes", no
+hand-lightened hexes. If you pass literal hexes, you own their dark-mode
+behavior; prefer `var(--…)` token strings (they re-theme via CSS) or palette
+*names* (re-resolved per render).
+
+Dark mode is one instance of the general theming contract — external
+"companion themes" (own token scope, texture fills, mark filters) are
+documented in [theming.md](theming.md).
+
+## Scenario → palette
+
+| Scenario | Use |
+|---|---|
+| Any single-series chart | nothing — `--chart-primary` |
+| Any multi-series chart, ≤8 categories | nothing — Set2 default |
+| >8 categories | `data.topN(...)` + auto-grayed "Other" |
+| Heatmap / density / calendar intensity | `colorScheme: 'Viridis'` (or `Blues` for corporate-quiet) |
+| Above/below zero, plus/minus, diff vs target | `colorScheme: 'RdBu'` or `'Temperature'`, domain pinned symmetric |
+| Performance bad→good with CVD safety | `RdYlBu` or `Temperature` (not `RdYlGn`) |
+| Strict accessibility requirement | `colors: 'OkabeIto'` (7 colors on dark) |
+| Benchmark/context series | `extraLayers` + `var(--chart-neutral)`, `behind: true` |
+| Status/semantic UI values | `colors: 'Status'` (success/warning/error/info) |
+| Yes/no, on/off | `colors: 'Binary'` |
+
+One consistency rule across a dashboard: **same entity, same color,
+everywhere.** When several charts show the same categories, pass the same
+explicit `colors`/`colorMap` (or use `linkGroup`'s shared `colorFor`) rather
+than letting encounter order assign different hues per chart.