remarque-tokens 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to `remarque-tokens` are documented here. Token value
 changes always state the design rationale — downstream sites pin against
 these entries when syncing.
 
+## 0.22.0 — 2026-07-23
+
+Dataviz categorical tokens — bridge-derived, golden-gated (closes #94). The syntax-palette pattern's fourth application, closing the "Dataviz Tokens" section's long-standing "guidance, not a palette" gap now that the upstream dataset ships a per-theme `dataviz` block (`@williamzujkowski/oklch-terminal-themes` 0.5.0).
+
+### Added
+- **6 `--color-viz-1..6` palette-tier slots**, hand-authored in both themes from `remarque-light`/`remarque-dark`'s `dataviz.categorical` block, serialized as round numbers (identity/serialization contract, same as `--color-syntax-*`). 6 slots, not 8 — the dataset's own floor (516 of 633 corpus themes ship exactly 6). Every slot ≥ **3:1** against `--color-bg` in both themes — Carbon's mark-on-background line, not text's 4.5:1 (marks are read at a glance, not continuously like prose). Added to `tokens-palette.css`'s `:root`, `@media (prefers-color-scheme: dark)`, `[data-theme="dark"]`/`:root.dark`, and the demo's `[data-theme="light"]` mirror.
+- **`remarque-theme` dataviz derivation.** Derives all 6 slots from the source theme's own `dataviz.categorical` array (first 6 entries, dataset order, per theme independently — order is **not** reconciled hue-for-hue across a light/dark pair; verified the upstream order itself differs between `remarque-light` and `remarque-dark`, consistent with this file's existing "dark mode is independently tuned, not inverted" stance). Same keep-if-passing-else-solve pattern as every other slot, chroma capped at 0.14. **Fallback:** an installed dataset older than 0.5.0 (still legal under the `>=0.1.0` peerDependencies floor) has no `dataviz` block — `remarque-theme` errors loudly naming the missing field and the upgrade path rather than synthesizing a guessed ramp from raw ANSI colors (the upstream categorical-selection algorithm is undocumented; guessing at it could silently diverge from a real 0.5.0+ dataset).
+- **`remarque-theme --dataviz`** (optional, judgment-call item). Emits `--viz-sequential-N`/`--viz-diverging-N` custom properties from the dataset's `dataviz.sequential`/`.diverging` ramps — gamut-clamped but NOT contrast-solved (a sequential ramp's low end is designed to sit near `--color-bg`) and NOT audited/golden-gated like `--color-viz-1..6` (these are per-use ramps, not identity tokens). Purely additive: omitting the flag leaves the derived `--color-*` output byte-identical to before.
+- **Audit extension** (`scripts/audit.mjs`, `scripts/theme.mjs` self-verify) — 6 new `CHECKS` pairings (`color-viz-1..6` vs `color-bg` at 3.0). `scripts/test-audit.mjs` fixtures updated with the 6 slots plus a must-fail case (`viz-slot-fails.css`) proving the pairings are actually wired in.
+- **Golden gate** (`scripts/palette-golden.mjs`) extended to the 6 new slots — ΔE2000 = 0.000 in both themes (the hand-authored values are literal transcriptions of the dataset's own numbers, unlike the solved slots elsewhere in the palette).
+- **REMARQUE.md "Dataviz Tokens"** rewritten: the 6 shipped tokens with light/dark values and ratios, the 3:1 mark-threshold rationale, a mandatory non-color-redundancy rule (shape/pattern/label — never color alone, per Carbon and tsundoku's precedent), and a documented recipe for sequential/diverging ramps (direct JSON consumption from the dataset, or `remarque-theme --dataviz`). New Enforcement Checklist line.
+- **Demo** (`site/src/pages/tokens.astro`): a "Dataviz" section rendering all 6 swatches in both themes with contrast ratios and a shape-coded legend (circle/square/triangle) demonstrating the non-color-redundancy rule directly. Placed on `tokens.astro`, which carries zero visual-regression baselines — this ships with no new/changed screenshot baselines.
+- **Repin**: `@williamzujkowski/oklch-terminal-themes` devDependency 0.4.0 → 0.5.0 (exact). Corpus test (`scripts/test-theme.mjs`) still 65/65 pairs passing — the dataset gained fields (`dataviz` on every theme), not themes, matching the repin pattern's usual shape.
+
 ## 0.21.0 — 2026-07-23
 
 Forced-colors (Windows High Contrast Mode) + `prefers-contrast: more` support (closes #93) — the ratified program's highest-value accessibility item.

package/REMARQUE.md

@@ -256,14 +256,45 @@ Reference/Docs and Project Dossier pages often need to show several screenshots
 
 ## Dataviz Tokens
 
-Charts are not yet a first-class Remarque surface, but tools built with the system inevitably need them. Rather than inventing chart-specific tokens, map dataviz elements onto vocabulary that already exists, so a chart survives a palette swap the same way prose and chrome do:
+Charts are a first-class Remarque surface: `tokens-palette.css` ships 6 hand-authored `--color-viz-*` categorical slots, bridge-derived and golden-gated against the upstream `remarque-light`/`remarque-dark` themes' `dataviz.categorical` block the same way the rest of the default palette is (issue #94 — the syntax-palette pattern's fourth application). The rest of a chart still maps onto vocabulary that already exists, so it survives a palette swap the same way prose and chrome do:
 
 - **Grid lines** use `--color-border` — never a separate "chart gray." Grid lines are structural, not decorative, and already have a sanctioned quiet role.
 - **Axis text and tick labels** use `--font-mono` at `--text-meta`, `--color-muted` — the same register as metadata rows and captions, never the body or display face.
-- **Categorical color ramp** is derived, not hand-picked: rotate hue at the accent's lightness/chroma steps — the same discipline "Changing the Accent Hue" already prescribes (fix lightness, vary hue, reduce chroma until every value clears the gamut) — producing a small hue family distinct from `--color-accent` itself, so chart color is never mistaken for the system's one interactive signal.
-- That ramp must be **audit-validated**, exactly like a palette override: every ramp color needs to clear gamut and 4.5:1 contrast against `--color-bg`/`--color-surface` in both themes before it ships.
+- **Categorical color** uses `--color-viz-1` through `--color-viz-6` (below) — never `--color-accent`, so chart color is never mistaken for the system's one interactive signal.
 
-**Precedent:** [tsundoku](https://github.com/williamzujkowski/tsundoku) built the underlying pattern already — its `DESIGN-NOTES.md` documents an 8-hue "orthogonal category system" (`--pop-pink`/`--pop-blue`/`--pop-green`/etc.), kept deliberately separate from `--color-accent` and used for content taxonomy (book categories, reading status) rather than interactivity. It held those hues to roughly the same lightness/contrast discipline as its audited palette, but by its own admission the hues were **never run through `remarque-audit`'s `CHECKS` array** — that is the one gap this guidance closes. A dataviz ramp should follow tsundoku's separation-from-accent instinct, but unlike its precedent, it must pass the audit before it ships.
+### Slots
+
+6 slots, not 8 — the upstream dataset's own floor: 516 of the 633 corpus themes ship exactly 6 `dataviz.categorical` entries, so shipping 8 would leave 2 unfillable on most themes. Every slot is verified ≥ **3:1** against `--color-bg` in both themes — Carbon's mark-on-background line, not text's 4.5:1. The distinction is deliberate: a chart mark is a small area read at a glance and identified by hue difference from its neighbors, not a string of characters read continuously letter-by-letter, so it gets the WCAG 1.4.11 non-text threshold (the same one `--color-border-bold` already uses for functional borders), not 1.4.3's text threshold.
+
+| Slot | Light | Dark |
+|---|---|---|
+| `--color-viz-1` | `oklch(0.538 0.121 250.5)` — 4.74:1 | `oklch(0.708 0.129 249.5)` — 7.53:1 |
+| `--color-viz-2` | `oklch(0.541 0.111 85.5)` — 4.73:1 | `oklch(0.712 0.13 85.3)` — 7.54:1 |
+| `--color-viz-3` | `oklch(0.524 0.12 24.6)` — 5.35:1 | `oklch(0.724 0.129 310.2)` — 7.55:1 |
+| `--color-viz-4` | `oklch(0.499 0.12 144.8)` — 5.32:1 | `oklch(0.725 0.129 25.4)` — 7.55:1 |
+| `--color-viz-5` | `oklch(0.524 0.121 309.6)` — 5.33:1 | `oklch(0.696 0.129 144.9)` — 7.53:1 |
+| `--color-viz-6` | `oklch(0.528 0.09 195.8)` — 4.74:1 | `oklch(0.697 0.119 194.8)` — 7.57:1 |
+
+**Order is not reconciled hue-for-hue across the pair.** The upstream `dataviz.categorical` order for `remarque-light` (blue, yellow, red, green, purple, cyan) does not match `remarque-dark`'s (blue, yellow, purple, red, green, cyan) — verified directly against the shipped dataset. `--color-viz-3` is reddish in light mode and purplish in dark mode. This is the same stance the rest of this file already takes for every other slot: **dark mode is independently tuned, not an inversion** — it is not a bug that a toggle recolors series 3, any more than it is a bug that `--color-fg`'s exact hue differs by theme.
+
+**Non-color redundancy (Carbon precedent, mandatory):** never use `--color-viz-*` as the *sole* distinguisher between series. Pair every categorical color with a second channel — a distinct marker shape (circle/square/triangle), a line dash pattern, or a direct end-of-line/legend label — so the chart still communicates under color-vision deficiency or `forced-colors: active` (which the marks themselves do not attempt to survive; see "Forced Colors & Contrast Preferences" for what *is* covered). This mirrors [tsundoku](https://github.com/williamzujkowski/tsundoku)'s `DESIGN-NOTES.md`, which documents an 8-hue "orthogonal category system" kept deliberately separate from its accent — the categorical slots above formalize that instinct as an audited, bridge-derived token set instead of a hand-picked one-off.
+
+### Derivation
+
+`remarque-theme` derives all 6 slots from the source theme's own `dataviz.categorical` array (dataset 0.5.0+) — first 6 entries, in the dataset's order, same keep-if-passing-else-solve pattern as every other slot, targeted at `--color-bg` (not `--color-surface`) at 3:1. Chroma is capped at 0.14, the same ceiling as `--color-accent`/`--color-syntax-*`. `scripts/palette-golden.mjs` extends its ΔE2000 ≤ 2.0 gate to all 6 slots.
+
+**Fallback (dataset predates the field):** an installed `@williamzujkowski/oklch-terminal-themes` older than 0.5.0 — still legal under this package's `>=0.1.0` peerDependencies floor — has no `dataviz` block at all. `remarque-theme` does **not** attempt to synthesize a categorical ramp from raw ANSI colors in that case: the upstream categorical-selection algorithm is undocumented, and approximating it could silently diverge from what a real 0.5.0+ dataset ships. It errors loudly instead, naming the missing field and the upgrade path — the smaller, honest option over a plausible-looking guess.
+
+### Sequential / diverging ramps
+
+Sequential and diverging ramps are **not** shipped as tokens — a fixed `--color-viz-seq-N` token set would misrepresent them, because a ramp's *step count* is dataset-defined (6-8, whatever the source theme carries) and a specific ramp is chosen per-use (a heatmap's sequential scale, a signed-difference chart's diverging scale), not once per theme like a categorical identity slot. Two ways to consume them:
+
+1. **Direct JSON consumption** — read the dataset's `dataviz.sequential`/`dataviz.diverging` arrays straight from the installed package:
+   ```js
+   const { sequential, diverging } = require('@williamzujkowski/oklch-terminal-themes/themes/remarque-light.json').dataviz;
+   ```
+   Each entry carries `oklch` (structured `{l, c, h}`) and `oklchCss` (a ready-to-use `oklch(...)` string) — no parsing required.
+2. **`remarque-theme --dataviz`** — emits `--viz-sequential-1..N` and `--viz-diverging-1..N` custom properties (`N` = the source theme's own ramp length) alongside the normal derived palette. Gamut-clamped but **not** contrast-solved (a sequential ramp's low end is designed to sit near `--color-bg`; solving it to a contrast floor would defeat the ramp) — advisory output, not audited or golden-gated like `--color-viz-1..6`. A future `remarque-audit --json`/`remarque-theme --json` could expose the same arrays as structured output; today, `--dataviz`'s CSS-property emission and direct JSON consumption above cover the need.
 
 ---
 
@@ -491,6 +522,7 @@ Every PR that ships Remarque pages MUST pass (`npm run audit` automates the colo
 - [ ] Body line-height ≥ 1.5 (Remarque target: 1.75).
 - [ ] Every `--color-syntax-*` slot ≥ 4.5:1 against `--color-code-bg` in both themes (see "Syntax Highlighting").
 - [ ] Every `--color-error`/`--color-success`/`--color-warning`/`--color-disabled` ≥ 4.5:1 against `--color-bg` **and** `--color-surface` in both themes; every `-subtle` background keeps `--color-fg` ≥ 4.5:1 on it (see "State Colors"). State colors used only for feedback moments, never decoration.
+- [ ] Every `--color-viz-*` slot ≥ 3:1 against `--color-bg` in both themes (see "Dataviz Tokens") — the mark-on-background line, not text's 4.5:1. Never used as the sole distinguisher between series — pair with a non-color redundancy (shape, pattern, or a direct label).
 - [ ] No bare `z-index` number in consumer CSS — reference `tokens-core.css`'s `--z-*` scale (see "Stacking").
 - [ ] Any new color-only affordance (hover/focus signal, state indicator, structural divider) is checked against forced-colors mode — does it survive, or does it need a `@media (forced-colors: active)` fallback? (see "Forced Colors & Contrast Preferences")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "engines": {
     "node": ">=18"
   },
@@ -32,7 +32,7 @@
     "drift": "node scripts/drift-check.mjs"
   },
   "devDependencies": {
-    "@williamzujkowski/oklch-terminal-themes": "0.4.0",
+    "@williamzujkowski/oklch-terminal-themes": "0.5.0",
     "ajv": "^8.20.0",
     "culori": "^4.0.2"
   },

package/scripts/audit.mjs

@@ -168,6 +168,15 @@ const CHECKS = [
   ['color-fg', 'color-error-subtle', 4.5, 'state: fg on error-subtle banner bg'],
   ['color-fg', 'color-success-subtle', 4.5, 'state: fg on success-subtle banner bg'],
   ['color-fg', 'color-warning-subtle', 4.5, 'state: fg on warning-subtle banner bg'],
+  // Dataviz categorical slots (issue #94) — 3:1 is Carbon's mark-on-
+  // background line, not text's 4.5:1: these are chart marks read at a
+  // glance, not prose. See REMARQUE.md "Dataviz Tokens".
+  ['color-viz-1', 'color-bg', 3.0, 'dataviz: categorical 1 (mark)'],
+  ['color-viz-2', 'color-bg', 3.0, 'dataviz: categorical 2 (mark)'],
+  ['color-viz-3', 'color-bg', 3.0, 'dataviz: categorical 3 (mark)'],
+  ['color-viz-4', 'color-bg', 3.0, 'dataviz: categorical 4 (mark)'],
+  ['color-viz-5', 'color-bg', 3.0, 'dataviz: categorical 5 (mark)'],
+  ['color-viz-6', 'color-bg', 3.0, 'dataviz: categorical 6 (mark)'],
 ];
 
 for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {

package/scripts/theme.mjs

@@ -22,6 +22,10 @@
  * meaningful "theme's own value" to preserve. The 9 --color-syntax-*
  * slots (issue #53) are derived straight from the theme's 16 ANSI
  * colors instead — see the "Syntax-highlighting slots" section below.
+ * The 6 --color-viz-* categorical slots (issue #94) are derived from
+ * the dataset's own dataviz.categorical block (0.5.0+) instead of ANSI —
+ * see "Dataviz categorical slots" below, including its dataset-predates-
+ * the-field fallback (a clean error, not a synthesized guess).
  * Output passes remarque-audit BY CONSTRUCTION — this script
  * self-verifies the same pairings before it will emit anything.
  *
@@ -50,13 +54,18 @@ try {
   OWN_VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
 } catch { /* provenance is best-effort */ }
 
-const USAGE = `usage: remarque-theme <light-slug> [--dark <dark-slug>] [-o out.css] [--scope <name>]
+const USAGE = `usage: remarque-theme <light-slug> [--dark <dark-slug>] [-o out.css] [--scope <name>] [--dataviz]
 
   <light-slug>     slug of a theme with isDark=false in ${PKG_SPEC}
   --dark <slug>    slug of a theme with isDark=true; defaults to the light
                     theme's "counterpart" from the dataset (0.2.0+) when it
                     has one, and is required when it doesn't
   -o, --output     write the derived palette here instead of stdout
+  --dataviz        also emit --viz-sequential-N / --viz-diverging-N custom
+                    properties from the dataset's dataviz.sequential/
+                    .diverging ramps (0.5.0+ only; issue #94). These are
+                    advisory, per-use ramps, NOT identity tokens — they are
+                    not audited or golden-gated like --color-viz-1..6
   --scope <name>   emit under [data-palette="<name>"] instead of :root — for
                     the palette-deck module (remarque-tokens/deck), where
                     several generated palettes coexist in one stylesheet and
@@ -75,13 +84,14 @@ function die(msg) {
 /* ── CLI args ─────────────────────────────────────────────────────── */
 
 const argv = process.argv.slice(2);
-let darkSlug, outFile, scopeName;
+let darkSlug, outFile, scopeName, dataviz = false;
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === '--dark') darkSlug = argv[++i];
   else if (a === '-o' || a === '--output') outFile = argv[++i];
   else if (a === '--scope') scopeName = argv[++i];
+  else if (a === '--dataviz') dataviz = true;
   else if (a === '-h' || a === '--help') { console.log(USAGE); process.exit(0); }
   else positional.push(a);
 }
@@ -506,6 +516,54 @@ function deriveStateSubtle(bgL, H, chromaCap, fg, dir) {
   return [L, c, r1(H)];
 }
 
+/* ── Dataviz categorical slots (issue #94) ────────────────────────────
+ * The upstream dataset (0.5.0+) ships a per-theme `dataviz.categorical`
+ * array — 6-8 ordered ColorValues already selected upstream for mutual
+ * distinguishability, the same kind of "this domain already carries the
+ * personality" argument as the syntax slots' ANSI colors. --color-viz-1
+ * through --color-viz-6 take the first 6 (633/633 corpus themes ship at
+ * least 6; 516 ship exactly 6 — that floor is why 6 ships, not 8), kept-
+ * if-passing/solved the same way as every other slot, verified against
+ * --color-bg (not --color-surface) at 3:1 — Carbon's mark-vs-background
+ * line, not text's 4.5:1 (REMARQUE.md "Dataviz Tokens": these are chart
+ * marks read at a glance, not prose read continuously).
+ *
+ * Order is taken as-is from the dataset, per theme independently — it is
+ * NOT reconciled to match hue-for-hue between a light/dark pair (the
+ * upstream categorical order does not always agree across a pair's two
+ * halves; verified empirically against remarque-light/remarque-dark).
+ * This is the same "dark mode is independently tuned, not inverted"
+ * stance the rest of this file already takes for every other slot.
+ *
+ * Fallback: a dataset older than 0.5.0 (still legal under this package's
+ * `>=0.1.0` peerDependencies floor) has no dataviz block at all. Rather
+ * than reverse-engineer the upstream's undocumented categorical-
+ * selection algorithm from raw ANSI colors — which could silently
+ * diverge from what a real 0.5.0+ dataset actually ships — this errors
+ * loudly and points at the upgrade. The smaller, honest option.
+ */
+
+const VIZ_CHROMA_CAP = 0.14; // same restrained ceiling as accent/syntax/state
+const VIZ_TARGET = 3.0; // Carbon's mark-on-background line
+
+function deriveVizCategorical(t, label, slug, bg, dir) {
+  const cats = t.dataviz && Array.isArray(t.dataviz.categorical) ? t.dataviz.categorical : null;
+  if (!cats || cats.length < 6) {
+    die(
+      `${label} theme "${slug}" has no dataviz.categorical (or fewer than 6 entries) in the installed ` +
+      `${PKG_SPEC}@${themesVersion} — upgrade the dataset to >=0.5.0 (dataviz.categorical landed there; issue #94) ` +
+      `and retry.\nremarque-theme does NOT synthesize a categorical ramp from raw ANSI colors as a fallback — the ` +
+      `upstream categorical-selection algorithm is undocumented, so approximating it here could silently diverge ` +
+      `from what a real 0.5.0+ dataset ships. Erroring with an upgrade instruction is the smaller, honest option.`
+    );
+  }
+  return cats.slice(0, 6).map((entry, i) => {
+    const [L0, C0, H0] = validateOklch(entry.oklch, `${label} dataviz.categorical[${i}]`);
+    const C = Math.min(C0, VIZ_CHROMA_CAP);
+    return keepOrSolve(L0, C, H0, bg, VIZ_TARGET, dir);
+  });
+}
+
 /* ── LIGHT derivation ─────────────────────────────────────────────── */
 
 function deriveLight(t) {
@@ -553,6 +611,9 @@ function deriveLight(t) {
   const stateErrorSubtle = deriveStateSubtle(bg[0], stateError[2], 0.02, fg, 'darker');
   const stateSuccessSubtle = deriveStateSubtle(bg[0], stateSuccess[2], 0.02, fg, 'darker');
   const stateWarningSubtle = deriveStateSubtle(bg[0], stateWarning[2], 0.02, fg, 'darker');
+  // Dataviz categorical slots (issue #94) — see deriveVizCategorical above.
+  // Verified against --color-bg (not surface) at 3:1.
+  const viz = deriveVizCategorical(t, 'light', lightSlug, bg, 'darker');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': [r3(bg[0] - 0.02), bg[1], bg[2]],
@@ -585,6 +646,12 @@ function deriveLight(t) {
     'color-warning': stateWarning,
     'color-warning-subtle': stateWarningSubtle,
     'color-disabled': { ref: 'color-muted' },
+    'color-viz-1': viz[0],
+    'color-viz-2': viz[1],
+    'color-viz-3': viz[2],
+    'color-viz-4': viz[3],
+    'color-viz-5': viz[4],
+    'color-viz-6': viz[5],
   };
   const tokens = {};
   for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
@@ -646,6 +713,9 @@ function deriveDark(t, accentHueLight) {
   const stateErrorSubtle = deriveStateSubtle(bg[0], stateError[2], 0.04, fg, 'lighter');
   const stateSuccessSubtle = deriveStateSubtle(bg[0], stateSuccess[2], 0.04, fg, 'lighter');
   const stateWarningSubtle = deriveStateSubtle(bg[0], stateWarning[2], 0.04, fg, 'lighter');
+  // Dataviz categorical slots (issue #94) — mirrors the light derivation,
+  // direction flipped ('lighter': marks on a dark bg).
+  const viz = deriveVizCategorical(t, 'dark', darkSlug, bg, 'lighter');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': surface,
@@ -678,6 +748,12 @@ function deriveDark(t, accentHueLight) {
     'color-warning': stateWarning,
     'color-warning-subtle': stateWarningSubtle,
     'color-disabled': { ref: 'color-muted' },
+    'color-viz-1': viz[0],
+    'color-viz-2': viz[1],
+    'color-viz-3': viz[2],
+    'color-viz-4': viz[3],
+    'color-viz-5': viz[4],
+    'color-viz-6': viz[5],
   };
   const tokens = {};
   for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
@@ -725,6 +801,12 @@ const CHECKS = [
   ['color-fg', 'color-error-subtle', 4.5, 'state: fg on error-subtle banner bg'],
   ['color-fg', 'color-success-subtle', 4.5, 'state: fg on success-subtle banner bg'],
   ['color-fg', 'color-warning-subtle', 4.5, 'state: fg on warning-subtle banner bg'],
+  ['color-viz-1', 'color-bg', 3.0, 'dataviz: categorical 1 (mark)'],
+  ['color-viz-2', 'color-bg', 3.0, 'dataviz: categorical 2 (mark)'],
+  ['color-viz-3', 'color-bg', 3.0, 'dataviz: categorical 3 (mark)'],
+  ['color-viz-4', 'color-bg', 3.0, 'dataviz: categorical 4 (mark)'],
+  ['color-viz-5', 'color-bg', 3.0, 'dataviz: categorical 5 (mark)'],
+  ['color-viz-6', 'color-bg', 3.0, 'dataviz: categorical 6 (mark)'],
 ];
 
 function resolveRaw(raw, name, seen = new Set()) {
@@ -765,6 +847,42 @@ const scopeNote = scopeName
   ? `\n *\n * Scoped for remarque-tokens/deck (--scope "${scopeName}") — this is one\n * palette among several coexisting in a stylesheet, switched at runtime\n * via [data-palette] rather than owning :root outright. Self-verification\n * below runs on the same derived [L,C,H] values regardless of scope; see\n * REMARQUE.md "Palette Deck" for the audit story on scoped output.`
   : '';
 
+// --dataviz (issue #94, optional, judgment-call item 6): advisory
+// --viz-sequential-N / --viz-diverging-N ramps straight from the
+// dataset's dataviz block — gamut-clamped but NOT contrast-solved (a
+// sequential ramp's low end is DESIGNED to sit near --color-bg; solving
+// it to a contrast floor would defeat the ramp). Not audited, not
+// golden-gated — see REMARQUE.md "Dataviz Tokens" for the recipe this
+// flag implements and why these are ramps, not identity tokens.
+function vizRamp(entries, prefix) {
+  return entries.map((e, i) => {
+    const [L0, C0, H0] = validateOklch(e.oklch, `${prefix}[${i}]`);
+    const L = r3(Math.min(1, Math.max(0, L0)));
+    return `  --${prefix}-${i + 1}: ${fmt([L, fitChroma(L, C0, H0), r1(H0)])};`;
+  }).join('\n');
+}
+let vizBlock = '';
+if (dataviz) {
+  const { sequential: seqL, diverging: divL } = themeLight.dataviz || {};
+  const { sequential: seqD, diverging: divD } = themeDark.dataviz || {};
+  if (!seqL || !divL || !seqD || !divD) {
+    die(`--dataviz requires dataviz.sequential/.diverging in the installed ${PKG_SPEC}@${themesVersion} — upgrade to >=0.5.0 (issue #94) and retry.`);
+  }
+  vizBlock = `
+/* --dataviz ramps (issue #94) — advisory, NOT audited/golden-gated like
+ * --color-viz-1..6 above. See REMARQUE.md "Dataviz Tokens". */
+${lightSelector} {
+${vizRamp(seqL, 'viz-sequential')}
+${vizRamp(divL, 'viz-diverging')}
+}
+
+${darkSelector} {
+${vizRamp(seqD, 'viz-sequential')}
+${vizRamp(divD, 'viz-diverging')}
+}
+`;
+}
+
 const css = `/*
  * Generated by remarque-theme (remarque-tokens ${OWN_VERSION}) — DO NOT HAND-EDIT.
  * Regenerate instead: ${regenCmd}
@@ -786,7 +904,7 @@ ${decls(light.tokens)}
 ${darkSelector} {
 ${decls(dark.tokens)}
 }
-`;
+${vizBlock}`;
 
 if (outFile) {
   writeFileSync(outFile, css);

package/tokens-palette.css

@@ -16,7 +16,9 @@
  *   - Colors: every replacement palette must pass the contrast audit
  *     (npm run audit) — fg-muted ≥ 7:1, muted ≥ 4.5:1 on bg AND
  *     surface, accent + accent-hover ≥ 4.5:1, border-bold ≥ 3:1,
- *     every --color-syntax-* slot ≥ 4.5:1 on --color-code-bg,
+ *     every --color-syntax-* slot ≥ 4.5:1 on --color-code-bg, every
+ *     --color-viz-* slot ≥ 3:1 on --color-bg (Carbon's mark-on-
+ *     background line, not text's 4.5:1 — see "Dataviz Tokens"),
  *     in BOTH themes.
  *   - Accent: change the hue by re-deriving accent/accent-hover/
  *     accent-subtle/selection at the SAME lightness values used here,
@@ -117,6 +119,25 @@
   --color-warning:        oklch(0.52 0.105 85);   /* ANSI yellow — 5.17:1 bg / 5.02:1 surface */
   --color-warning-subtle: oklch(0.95 0.02  85);   /* faint yellow banner background */
   --color-disabled:       var(--color-muted);     /* muted family, not ANSI-derived */
+
+  /* Dataviz categorical ramp (issue #94) — hand-authored from
+     remarque-light's dataviz.categorical block (scripts/theme.mjs),
+     serialized as round numbers (golden-gated: scripts/palette-golden.mjs).
+     6 slots, not 8 — the dataset's own floor (516/633 corpus themes ship
+     exactly 6; shipping 8 would leave 2 unfillable on most themes). Every
+     slot ≥ 3:1 on --color-bg — Carbon's mark-on-background line, NOT
+     text's 4.5:1 (these are chart marks read at a glance, never prose).
+     Order is the dataset's own — NOT reconciled hue-for-hue against the
+     dark block below (dark mode is independently tuned, same stance as
+     every other slot; see REMARQUE.md "Dataviz Tokens"). Pair with a
+     non-color redundancy (shape, pattern, or a direct label) — never
+     color alone, per the same Carbon precedent. */
+  --color-viz-1: oklch(0.538 0.121 250.5);  /* 4.74:1 on bg */
+  --color-viz-2: oklch(0.541 0.111 85.5);   /* 4.73:1 on bg */
+  --color-viz-3: oklch(0.524 0.12  24.6);   /* 5.35:1 on bg */
+  --color-viz-4: oklch(0.499 0.12  144.8);  /* 5.32:1 on bg */
+  --color-viz-5: oklch(0.524 0.121 309.6);  /* 5.33:1 on bg */
+  --color-viz-6: oklch(0.528 0.09  195.8);  /* 4.74:1 on bg */
 }
 
 /* ─── Color: Dark theme ─────────────────────────────────── */
@@ -174,6 +195,16 @@
     --color-warning:        oklch(0.62 0.11 85);    /* 5.29:1 bg / 5.03:1 surface */
     --color-warning-subtle: oklch(0.22 0.04 85);
     --color-disabled:       var(--color-muted);
+
+    /* Dataviz categorical ramp (issue #94) — derived from remarque-dark's
+       dataviz.categorical block; see the light block above for the full
+       rationale. Every slot ≥ 3:1 on --color-bg. */
+    --color-viz-1: oklch(0.708 0.129 249.5);  /* 7.53:1 on bg */
+    --color-viz-2: oklch(0.712 0.13  85.3);   /* 7.54:1 on bg */
+    --color-viz-3: oklch(0.724 0.129 310.2);  /* 7.55:1 on bg */
+    --color-viz-4: oklch(0.725 0.129 25.4);   /* 7.55:1 on bg */
+    --color-viz-5: oklch(0.696 0.129 144.9);  /* 7.53:1 on bg */
+    --color-viz-6: oklch(0.697 0.119 194.8);  /* 7.57:1 on bg */
   }
 }
 
@@ -227,6 +258,15 @@
   --color-warning:        oklch(0.62 0.11 85);
   --color-warning-subtle: oklch(0.22 0.04 85);
   --color-disabled:       var(--color-muted);
+
+  /* Dataviz categorical ramp (issue #94) — see the light :root block
+     above for the full rationale. */
+  --color-viz-1: oklch(0.708 0.129 249.5);
+  --color-viz-2: oklch(0.712 0.13  85.3);
+  --color-viz-3: oklch(0.724 0.129 310.2);
+  --color-viz-4: oklch(0.725 0.129 25.4);
+  --color-viz-5: oklch(0.696 0.129 144.9);
+  --color-viz-6: oklch(0.697 0.119 194.8);
 }
 
 /* ─── prefers-contrast: more ────────────────────────────────

package/tokens.d.ts

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.21.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.22.0). Do not edit — the CSS
  * (tokens-core.css + tokens-palette.css) is the source of truth;
  * tokens.json is the intermediate machine-readable form this file is
  * generated from. Regenerate with: node scripts/tokens-json.mjs
@@ -104,7 +104,13 @@ export type RemarquePaletteToken =
   | 'color-success-subtle'
   | 'color-warning'
   | 'color-warning-subtle'
-  | 'color-disabled';
+  | 'color-disabled'
+  | 'color-viz-1'
+  | 'color-viz-2'
+  | 'color-viz-3'
+  | 'color-viz-4'
+  | 'color-viz-5'
+  | 'color-viz-6';
 
 /** Every Remarque token name, core + palette. */
 export type RemarqueToken = RemarqueCoreToken | RemarquePaletteToken;
@@ -392,6 +398,30 @@ export interface RemarqueTokenValues {
       readonly light: "var(--color-muted)";
       readonly dark: "var(--color-muted)";
     };
+    readonly 'color-viz-1': {
+      readonly light: "oklch(0.538 0.121 250.5)";
+      readonly dark: "oklch(0.708 0.129 249.5)";
+    };
+    readonly 'color-viz-2': {
+      readonly light: "oklch(0.541 0.111 85.5)";
+      readonly dark: "oklch(0.712 0.13  85.3)";
+    };
+    readonly 'color-viz-3': {
+      readonly light: "oklch(0.524 0.12  24.6)";
+      readonly dark: "oklch(0.724 0.129 310.2)";
+    };
+    readonly 'color-viz-4': {
+      readonly light: "oklch(0.499 0.12  144.8)";
+      readonly dark: "oklch(0.725 0.129 25.4)";
+    };
+    readonly 'color-viz-5': {
+      readonly light: "oklch(0.524 0.121 309.6)";
+      readonly dark: "oklch(0.696 0.129 144.9)";
+    };
+    readonly 'color-viz-6': {
+      readonly light: "oklch(0.528 0.09  195.8)";
+      readonly dark: "oklch(0.697 0.119 194.8)";
+    };
   };
 }
 

package/tokens.json

@@ -3,7 +3,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.21.0",
+      "version": "0.22.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"
@@ -610,6 +610,60 @@
       "dark": {
         "$value": "var(--color-muted)"
       }
+    },
+    "color-viz-1": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.538 0.121 250.5)"
+      },
+      "dark": {
+        "$value": "oklch(0.708 0.129 249.5)"
+      }
+    },
+    "color-viz-2": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.541 0.111 85.5)"
+      },
+      "dark": {
+        "$value": "oklch(0.712 0.13  85.3)"
+      }
+    },
+    "color-viz-3": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.524 0.12  24.6)"
+      },
+      "dark": {
+        "$value": "oklch(0.724 0.129 310.2)"
+      }
+    },
+    "color-viz-4": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.499 0.12  144.8)"
+      },
+      "dark": {
+        "$value": "oklch(0.725 0.129 25.4)"
+      }
+    },
+    "color-viz-5": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.524 0.121 309.6)"
+      },
+      "dark": {
+        "$value": "oklch(0.696 0.129 144.9)"
+      }
+    },
+    "color-viz-6": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.528 0.09  195.8)"
+      },
+      "dark": {
+        "$value": "oklch(0.697 0.119 194.8)"
+      }
     }
   }
 }