@dataimago/tokens 0.1.0-alpha.2 → 0.1.0-alpha.22

package/README.md

@@ -5,15 +5,19 @@ Canonical design tokens for the dataimago ethical AI design system.
 ## What's in the box
 
 - `src/*.json` — the hand-authored JSON sources (colors, typography, spacing, effects, etc.).
-- `dist/tokens.css` / `dist/tokens.scss` — CSS custom properties emitted from the JSON sources, theme-aware (`[data-bs-theme]` + `prefers-color-scheme`).
+- `dist/tokens.css` / `dist/tokens.scss` — CSS custom properties emitted from the JSON sources, theme-aware (`[data-bs-theme]` + `prefers-color-scheme`). The system preference applies only while the root has no `data-bs-theme="light"`, so an explicit choice (e.g. `@dataimago/ui`'s `ThemeToggle`) wins in both directions.
 - `dist/index.{mjs,cjs,d.ts}` — typed JS/TS imports for token values.
+- `dist/tokens.dtcg.json` — additive DTCG-style export for tools and agents. It does not replace the current runtime JSON shape.
 
 ## Palette
 
 - `ink` — warm neutrals, 50–900
-- `cream` — warm paper, 50–500
-- `copper` — canonical interactive color (primary on light mode at 500, hover at 600)
-- `accent` — emancipation copper-red, reserved for high moral weight
+- `stone` — canonical page/surface neutral scale
+- `forest` — house primary interactive scale
+- `paper` — warm-surface option, retained as the renamed successor to the older `cream` framing
+- `presentation-blue` — presentation/accent source scale
+- `accent` — mode-aware semantic accent mapped to presentation-blue stops
+- `copper` — preserved decorative/editorial warmth scale
 
 All semantic tokens (`content.primary`, `surface.page`, `interactive.primary`, etc.) resolve to values in that palette.
 
@@ -25,12 +29,19 @@ import colors from "@dataimago/tokens/colors";
 
 // In CSS:
 // @import "@dataimago/tokens/css";
+
+// Tooling / agents:
+// import dtcg from "@dataimago/tokens/dtcg";
 ```
 
 ## Authoring
 
 Edit JSON under `src/` — this package is the source of truth. Run `pnpm --filter @dataimago/tokens build` to regenerate `dist/`.
 
+CSS-emitting files (`colors.json`, `theme-colors.json`, `typography.json`, `spacing.json`, `effects.json`) are structurally validated before build output is emitted. `frequent.json` and `components.json` remain metadata/reference manifests in this alpha line; do not treat them as normalized CSS-emitting token files until a migration records that decision.
+
+The current CSS custom property set is protected by `tools/check-css-vars.mjs` so Level-1 and Level-2 consumers do not lose variables during tightening work.
+
 ## Versioning
 
 Changes go through [Changesets](https://github.com/changesets/changesets). Any palette or semantic-token change is at least a minor version bump in alpha.

package/dist/index.cjs

@@ -40,24 +40,24 @@ const tokens = {
     },
     "border": {
       "subtle": {
-        "light": "rgba(12, 10, 9, 0.08)",
-        "dark": "rgba(253, 249, 242, 0.08)",
-        "description": "Subtle borders — element separation"
+        "light": "rgba(12, 10, 9, 0.45)",
+        "dark": "rgba(253, 249, 242, 0.45)",
+        "description": "Subtle borders — element separation. THE ALPHA IS THE ROLE: border.subtle / moderate / strong / card share one base color and are distinguished by opacity alone, so a gamut conversion that drops the alpha channel collapses four semantic roles into one opaque value (this happened in 17995c3, #72, 2026-06-28). No number is quoted here on purpose: the scale is set by the founder decision recorded in wi-20260817-border-alpha-scale-retune and gated by tools/contrast-check.mjs at the WCAG 1.4.11 non-text threshold (3:1). Read the value, not this sentence."
       },
       "moderate": {
-        "light": "rgba(12, 10, 9, 0.15)",
-        "dark": "rgba(253, 249, 242, 0.15)",
-        "description": "Moderate borders — defined boundaries"
+        "light": "rgba(12, 10, 9, 0.60)",
+        "dark": "rgba(253, 249, 242, 0.60)",
+        "description": "Moderate borders — defined boundaries. See border.subtle on why the alpha is load-bearing and why no number is quoted here."
       },
       "strong": {
-        "light": "rgba(12, 10, 9, 0.25)",
-        "dark": "rgba(253, 249, 242, 0.25)",
-        "description": "Strong borders — prominent separation"
+        "light": "rgba(12, 10, 9, 0.75)",
+        "dark": "rgba(253, 249, 242, 0.75)",
+        "description": "Strong borders — prominent separation. See border.subtle on why the alpha is load-bearing and why no number is quoted here."
       },
       "card": {
-        "light": "rgba(12, 10, 9, 0.15)",
-        "dark": "rgba(253, 249, 242, 0.15)",
-        "description": "Card border color with transparency for subtle definition"
+        "light": "rgba(12, 10, 9, 0.60)",
+        "dark": "rgba(253, 249, 242, 0.60)",
+        "description": "Card border color with transparency for subtle definition. See border.subtle on why the alpha is load-bearing and why no number is quoted here."
       },
       "code": {
         "light": "#d6d3d1",
@@ -72,14 +72,14 @@ const tokens = {
         "description": "Primary text — stone-900 on stone-100 (light, matches presentation-theme.scss exactly) / paper-100 on dark surface"
       },
       "secondary": {
-        "light": "#7c7c7c",
+        "light": "#6a6a6a",
         "dark": "#a8a29e",
-        "description": "Secondary text — stone-500 (light, matches presentation-theme.scss --color-secondary) / ink-300 on dark"
+        "description": "Secondary text — WCAG-AA on all light surfaces (≥4.6:1, darkened from stone-500 #7c7c7c which was 3.6:1) / ink-300 on dark"
       },
       "muted": {
-        "light": "#78716c",
-        "dark": "#78716c",
-        "description": "Muted text — captions, meta info"
+        "light": "#706964",
+        "dark": "#89827d",
+        "description": "Muted text — captions, meta info. WCAG-AA on all surfaces in both modes (darkened/lightened from #78716c which failed AA on page)"
       },
       "inverse": {
         "light": "#fdf9f2",
@@ -99,9 +99,9 @@ const tokens = {
         "description": "Hover state — forest-800 on light (slightly darker than canonical) / forest-400 on dark"
       },
       "accent": {
-        "light": "#b54a27",
-        "dark": "#b54a27",
-        "description": "Accent — emancipation copper-red; moral-weight color (preserved from copper era as deliberate non-interactive emphasis)"
+        "light": "#1f618d",
+        "dark": "#3498DB",
+        "description": "Accent — sky-blue moral-weight color (iteration-2). Light: accent-500 (5.68:1 on stone-100, AA with headroom; 6.66:1 white-on-color for backplates). Dark: accent-300 (5.41:1 on stone-900, AA with headroom — closes the iteration-1 dark-mode AA-large-only contrast gap). FIRST instance of mode-aware role mapping in the system: light and dark point to different palette stops rather than the same hex. The scale-name `accent` is preserved across iteration-1 → iteration-2 (consumer-side text-accent-500 keeps working). See wiki/decisions/iteration-2-blue-accent.md for the dialectical reframe of the iteration-1 emancipation-copper framing (sky/horizon/Enlightenment-blueprint/Reformation-Protestant traditions vs. Western-traffic-coding STOP-red)."
       },
       "focus": {
         "light": "#434739",
@@ -120,6 +120,121 @@ const tokens = {
         "dark": "#2980B9",
         "description": "Presentation accent hover/emphasized variant — Flat-UI belize-hole"
       }
+    },
+    "vertical-accent": {
+      "$comment": "Per-vertical brand accents — each Level-2 property's identity color, distinct from the house interactive.accent (the L1 sky-blue hub color). Mode-aware (light/dark stops) like interactive.accent. Used for app icons, navbar-logo emphasis, and per-vertical theming. Contrast vs surface.page verified WCAG: light values are the on-light marks, dark values the on-dark marks. dataimago (L1 hub) intentionally has no vertical accent — it uses interactive.accent + ink.",
+      "dissertation": {
+        "light": "#B87333",
+        "dark": "#CE8E5C",
+        "description": "dissertation-ai — copper (manuscript / annotation / the human hand in the margin). Light: 3.23:1 on stone-100 (AA-large; large-mark use). Dark: #CE8E5C 6.72:1 on ink-900 (AA)."
+      },
+      "rpkg": {
+        "light": "#3B82F6",
+        "dark": "#60A5FA",
+        "description": "rpkg-ai — engineering blue. Light: 3.14:1 on stone-100 (AA-large; large-mark use). Dark: #60A5FA 7.26:1 on ink-900 (AA)."
+      },
+      "SGPc": {
+        "light": "#5A6310",
+        "dark": "#B2BF22",
+        "description": "SGPc-ai — growth yellow-green (decided 2026-06-26). The brand value is the bright #B2BF22, but it fails contrast on light surfaces (1.73:1), so LIGHT mode uses the darkened companion #5A6310 (5.55:1 on stone-100 — full AA) and DARK mode uses the bright #B2BF22 (9.12:1 on ink-900). See wiki/decisions/sgpc-accent.md."
+      }
+    },
+    "brand-mark": {
+      "$comment": "Brand-MARK colors (the dataimago monogram / wordmark logo treatment) — distinct from the interactive.accent role. The signature monogram red is a wide-gamut PILOT (see wiki/decisions/p3-oklch-color.md). It is mode-aware for AA-normal headroom: a single red cannot clear 4.5:1 on BOTH the light page (#ededeb) and ink-900 — light needs a deep red, dark needs a bright one. LIGHT uses the deepened #cc0000 (faithful P3, contrast-first); DARK keeps the vivid display-P3 primary red (#ff0000 fallback → color(display-p3 1 0 0)), where #ff0000 already passes AA-normal. Vivid override authored in tools/color-converter.mjs (dark-only for the red), emitted as a `#hex → color(display-p3 …)` cascade in the -p3 build.",
+      "red": {
+        "light": "#cc0000",
+        "dark": "#ff0000",
+        "description": "Signature monogram red — mode-aware for AA-normal. LIGHT: deepened #cc0000 (5.0:1 on stone-100 #ededeb / 5.5:1 on elevated — full AA-normal, safe at small sizes / as text). DARK: vivid #ff0000 fallback + display-P3 primary red (4.6:1 on ink-900 — AA-normal). Logo-mark color only — NOT the interactive accent (which is iteration-2 blue). Large navbar lift-wash marks keep the vivid display-P3 red (AA-large, large-mark use); this token is the AA-normal value for arbitrary/small mark reuse."
+      }
+    },
+    "dataviz": {
+      "okabe-ito": {
+        "orange": {
+          "value": "#E69F00",
+          "description": "Okabe-Ito orange (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "sky-blue": {
+          "value": "#56B4E9",
+          "description": "Okabe-Ito sky blue (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "bluish-green": {
+          "value": "#009E73",
+          "description": "Okabe-Ito bluish green (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "yellow": {
+          "value": "#F0E442",
+          "description": "Okabe-Ito yellow — 1.13:1 on the light page: never use it without a mark outline or a label (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "blue": {
+          "value": "#0072B2",
+          "description": "Okabe-Ito blue (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "vermillion": {
+          "value": "#D55E00",
+          "description": "Okabe-Ito vermillion (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "reddish-purple": {
+          "value": "#CC79A7",
+          "description": "Okabe-Ito reddish purple (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "black": {
+          "light": "#000000",
+          "dark": "#FDF9F2",
+          "description": "Okabe-Ito black (Okabe & Ito 2008). In dark mode it becomes content.primary.dark: #000000 is 1.14:1 on the dark page. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        }
+      },
+      "categorical": {
+        "1": {
+          "value": "#E69F00",
+          "description": "= okabe-ito.orange (slot 1, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "2": {
+          "value": "#56B4E9",
+          "description": "= okabe-ito.sky-blue (slot 2, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "3": {
+          "value": "#009E73",
+          "description": "= okabe-ito.bluish-green (slot 3, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "4": {
+          "value": "#F0E442",
+          "description": "= okabe-ito.yellow (slot 4, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "5": {
+          "value": "#0072B2",
+          "description": "= okabe-ito.blue (slot 5, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "6": {
+          "value": "#D55E00",
+          "description": "= okabe-ito.vermillion (slot 6, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "7": {
+          "value": "#CC79A7",
+          "description": "= okabe-ito.reddish-purple (slot 7, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "8": {
+          "light": "#000000",
+          "dark": "#FDF9F2",
+          "description": "= okabe-ito.black (slot 8, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        }
+      },
+      "uncertainty": {
+        "outer": {
+          "light": "#D6D6D6",
+          "dark": "#333333",
+          "description": "Outermost nested uncertainty band (gray 0.84 in the LIwLD PSTricks figures). The ramp is mirrored in dark mode so the innermost band stays the strongest. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        },
+        "union": {
+          "light": "#9E9E9E",
+          "dark": "#6B6B6B",
+          "description": "Union band (gray 0.62); mirrored in dark mode. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        },
+        "inner": {
+          "light": "#333333",
+          "dark": "#D6D6D6",
+          "description": "Innermost band (gray 0.20); mirrored in dark mode, where #333333 would be 1.46:1. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        }
+      }
     }
   },
   "spacing": {
@@ -200,14 +315,14 @@ const tokens = {
   },
   "border": {
     "subtle": {
-      "light": "rgba(20, 20, 16, 0.1)",
-      "dark": "rgba(237, 237, 235, 0.1)",
-      "description": "Subtle borders - element separation"
+      "light": "rgba(20, 20, 16, 0.47)",
+      "dark": "rgba(237, 237, 235, 0.47)",
+      "description": "Subtle borders - element separation. THE ALPHA IS THE ROLE. Distinct from color.border.subtle: this family has its own base (20,20,16 / 237,237,235), so it needs a DIFFERENT alpha to render the same. 0.47 here matches 0.45 there at 3.07:1 on the worst surface; copying 0.45 would land at 2.90:1 and fail WCAG 1.4.11. Gated by tools/contrast-check.mjs."
     },
     "moderate": {
-      "light": "rgba(20, 20, 16, 0.15)",
-      "dark": "rgba(237, 237, 235, 0.15)",
-      "description": "Moderate borders - defined boundaries"
+      "light": "rgba(20, 20, 16, 0.63)",
+      "dark": "rgba(237, 237, 235, 0.63)",
+      "description": "Moderate borders - defined boundaries. 0.63 here matches color.border.moderate 0.60 in rendered contrast; see border.subtle on why the numbers differ between the two families."
     },
     "focus": {
       "light": "#3498DB",
@@ -282,16 +397,16 @@ const tokens = {
         "description": "Primary sans-serif font - body text"
       },
       "mono": {
-        "value": "JetBrains Mono, SF Mono, Monaco, Inconsolata, monospace",
-        "description": "Monospace font - code blocks and technical content"
+        "value": "Noto Sans Mono, SF Mono, Monaco, Inconsolata, monospace",
+        "description": "Noto Sans Mono — code blocks and technical content; matches the shipped font"
       },
       "display": {
         "value": "var(--font-family-display-editorial)",
-        "description": "DEPRECATED alias of display-editorial; preserved through 0.2.x and removed in 0.3.0. New code should reference --font-family-display-editorial or --font-family-display-documentation directly. See wiki/decisions/display-family-split.md."
+        "description": "Alias of display-editorial, and the load-bearing indirection .di-prose rebinds to swap a whole surface to the documentation family — do NOT rewrite heading rules to reference display-editorial directly or .di-prose stops working. Reference display-editorial/display-documentation explicitly only where the surface must NOT control the family (brand chrome, navbars). Its 0.3.0 removal was deferred 2026-08-10 under wiki/decisions/compatibility-contract.md (additive-only); removal now requires its own cleanup ADR. See wiki/decisions/display-family-split.md."
       },
       "display-editorial": {
-        "value": "Josefin Sans, system-ui, sans-serif",
-        "description": "Editorial display family — Josefin Sans, the brand voice. Used on surfaces where the heading does rhetorical/branding work: hero/landing, marketing, story showcases, slide titles. Default for unmarked headings. Pair with weight 500 (h1) per wiki/decisions/h1-weight-medium.md."
+        "value": "Josefin Sans, Noto Sans, system-ui, sans-serif",
+        "description": "Editorial display family — Josefin Sans, the brand voice. Used on surfaces where the heading does rhetorical/branding work: hero/landing, marketing, story showcases, slide titles. Default for unmarked headings. The Noto Sans fallback serves untagged text; tagged languages are handled by fonts/lang.css. Pair with weight 500 (h1) per wiki/decisions/h1-weight-medium.md."
       },
       "display-documentation": {
         "value": "Noto Sans, system-ui, sans-serif",
@@ -302,8 +417,8 @@ const tokens = {
         "description": "Brand font - dataimago navbar and branding elements"
       },
       "math": {
-        "value": "Noto Sans Math, Noto Sans, system-ui, sans-serif",
-        "description": "Mathematical notation font — Noto Sans Math for broad Unicode math coverage; harmonises with the Noto Sans body stack"
+        "value": "Noto Sans Math, math",
+        "description": "Noto Sans Math, falling back to the browser's maths face; native MathML is the maths contract"
       }
     },
     "size": {

package/dist/index.mjs

@@ -40,24 +40,24 @@ const tokens = {
     },
     "border": {
       "subtle": {
-        "light": "rgba(12, 10, 9, 0.08)",
-        "dark": "rgba(253, 249, 242, 0.08)",
-        "description": "Subtle borders — element separation"
+        "light": "rgba(12, 10, 9, 0.45)",
+        "dark": "rgba(253, 249, 242, 0.45)",
+        "description": "Subtle borders — element separation. THE ALPHA IS THE ROLE: border.subtle / moderate / strong / card share one base color and are distinguished by opacity alone, so a gamut conversion that drops the alpha channel collapses four semantic roles into one opaque value (this happened in 17995c3, #72, 2026-06-28). No number is quoted here on purpose: the scale is set by the founder decision recorded in wi-20260817-border-alpha-scale-retune and gated by tools/contrast-check.mjs at the WCAG 1.4.11 non-text threshold (3:1). Read the value, not this sentence."
       },
       "moderate": {
-        "light": "rgba(12, 10, 9, 0.15)",
-        "dark": "rgba(253, 249, 242, 0.15)",
-        "description": "Moderate borders — defined boundaries"
+        "light": "rgba(12, 10, 9, 0.60)",
+        "dark": "rgba(253, 249, 242, 0.60)",
+        "description": "Moderate borders — defined boundaries. See border.subtle on why the alpha is load-bearing and why no number is quoted here."
       },
       "strong": {
-        "light": "rgba(12, 10, 9, 0.25)",
-        "dark": "rgba(253, 249, 242, 0.25)",
-        "description": "Strong borders — prominent separation"
+        "light": "rgba(12, 10, 9, 0.75)",
+        "dark": "rgba(253, 249, 242, 0.75)",
+        "description": "Strong borders — prominent separation. See border.subtle on why the alpha is load-bearing and why no number is quoted here."
       },
       "card": {
-        "light": "rgba(12, 10, 9, 0.15)",
-        "dark": "rgba(253, 249, 242, 0.15)",
-        "description": "Card border color with transparency for subtle definition"
+        "light": "rgba(12, 10, 9, 0.60)",
+        "dark": "rgba(253, 249, 242, 0.60)",
+        "description": "Card border color with transparency for subtle definition. See border.subtle on why the alpha is load-bearing and why no number is quoted here."
       },
       "code": {
         "light": "#d6d3d1",
@@ -72,14 +72,14 @@ const tokens = {
         "description": "Primary text — stone-900 on stone-100 (light, matches presentation-theme.scss exactly) / paper-100 on dark surface"
       },
       "secondary": {
-        "light": "#7c7c7c",
+        "light": "#6a6a6a",
         "dark": "#a8a29e",
-        "description": "Secondary text — stone-500 (light, matches presentation-theme.scss --color-secondary) / ink-300 on dark"
+        "description": "Secondary text — WCAG-AA on all light surfaces (≥4.6:1, darkened from stone-500 #7c7c7c which was 3.6:1) / ink-300 on dark"
       },
       "muted": {
-        "light": "#78716c",
-        "dark": "#78716c",
-        "description": "Muted text — captions, meta info"
+        "light": "#706964",
+        "dark": "#89827d",
+        "description": "Muted text — captions, meta info. WCAG-AA on all surfaces in both modes (darkened/lightened from #78716c which failed AA on page)"
       },
       "inverse": {
         "light": "#fdf9f2",
@@ -99,9 +99,9 @@ const tokens = {
         "description": "Hover state — forest-800 on light (slightly darker than canonical) / forest-400 on dark"
       },
       "accent": {
-        "light": "#b54a27",
-        "dark": "#b54a27",
-        "description": "Accent — emancipation copper-red; moral-weight color (preserved from copper era as deliberate non-interactive emphasis)"
+        "light": "#1f618d",
+        "dark": "#3498DB",
+        "description": "Accent — sky-blue moral-weight color (iteration-2). Light: accent-500 (5.68:1 on stone-100, AA with headroom; 6.66:1 white-on-color for backplates). Dark: accent-300 (5.41:1 on stone-900, AA with headroom — closes the iteration-1 dark-mode AA-large-only contrast gap). FIRST instance of mode-aware role mapping in the system: light and dark point to different palette stops rather than the same hex. The scale-name `accent` is preserved across iteration-1 → iteration-2 (consumer-side text-accent-500 keeps working). See wiki/decisions/iteration-2-blue-accent.md for the dialectical reframe of the iteration-1 emancipation-copper framing (sky/horizon/Enlightenment-blueprint/Reformation-Protestant traditions vs. Western-traffic-coding STOP-red)."
       },
       "focus": {
         "light": "#434739",
@@ -120,6 +120,121 @@ const tokens = {
         "dark": "#2980B9",
         "description": "Presentation accent hover/emphasized variant — Flat-UI belize-hole"
       }
+    },
+    "vertical-accent": {
+      "$comment": "Per-vertical brand accents — each Level-2 property's identity color, distinct from the house interactive.accent (the L1 sky-blue hub color). Mode-aware (light/dark stops) like interactive.accent. Used for app icons, navbar-logo emphasis, and per-vertical theming. Contrast vs surface.page verified WCAG: light values are the on-light marks, dark values the on-dark marks. dataimago (L1 hub) intentionally has no vertical accent — it uses interactive.accent + ink.",
+      "dissertation": {
+        "light": "#B87333",
+        "dark": "#CE8E5C",
+        "description": "dissertation-ai — copper (manuscript / annotation / the human hand in the margin). Light: 3.23:1 on stone-100 (AA-large; large-mark use). Dark: #CE8E5C 6.72:1 on ink-900 (AA)."
+      },
+      "rpkg": {
+        "light": "#3B82F6",
+        "dark": "#60A5FA",
+        "description": "rpkg-ai — engineering blue. Light: 3.14:1 on stone-100 (AA-large; large-mark use). Dark: #60A5FA 7.26:1 on ink-900 (AA)."
+      },
+      "SGPc": {
+        "light": "#5A6310",
+        "dark": "#B2BF22",
+        "description": "SGPc-ai — growth yellow-green (decided 2026-06-26). The brand value is the bright #B2BF22, but it fails contrast on light surfaces (1.73:1), so LIGHT mode uses the darkened companion #5A6310 (5.55:1 on stone-100 — full AA) and DARK mode uses the bright #B2BF22 (9.12:1 on ink-900). See wiki/decisions/sgpc-accent.md."
+      }
+    },
+    "brand-mark": {
+      "$comment": "Brand-MARK colors (the dataimago monogram / wordmark logo treatment) — distinct from the interactive.accent role. The signature monogram red is a wide-gamut PILOT (see wiki/decisions/p3-oklch-color.md). It is mode-aware for AA-normal headroom: a single red cannot clear 4.5:1 on BOTH the light page (#ededeb) and ink-900 — light needs a deep red, dark needs a bright one. LIGHT uses the deepened #cc0000 (faithful P3, contrast-first); DARK keeps the vivid display-P3 primary red (#ff0000 fallback → color(display-p3 1 0 0)), where #ff0000 already passes AA-normal. Vivid override authored in tools/color-converter.mjs (dark-only for the red), emitted as a `#hex → color(display-p3 …)` cascade in the -p3 build.",
+      "red": {
+        "light": "#cc0000",
+        "dark": "#ff0000",
+        "description": "Signature monogram red — mode-aware for AA-normal. LIGHT: deepened #cc0000 (5.0:1 on stone-100 #ededeb / 5.5:1 on elevated — full AA-normal, safe at small sizes / as text). DARK: vivid #ff0000 fallback + display-P3 primary red (4.6:1 on ink-900 — AA-normal). Logo-mark color only — NOT the interactive accent (which is iteration-2 blue). Large navbar lift-wash marks keep the vivid display-P3 red (AA-large, large-mark use); this token is the AA-normal value for arbitrary/small mark reuse."
+      }
+    },
+    "dataviz": {
+      "okabe-ito": {
+        "orange": {
+          "value": "#E69F00",
+          "description": "Okabe-Ito orange (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "sky-blue": {
+          "value": "#56B4E9",
+          "description": "Okabe-Ito sky blue (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "bluish-green": {
+          "value": "#009E73",
+          "description": "Okabe-Ito bluish green (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "yellow": {
+          "value": "#F0E442",
+          "description": "Okabe-Ito yellow — 1.13:1 on the light page: never use it without a mark outline or a label (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "blue": {
+          "value": "#0072B2",
+          "description": "Okabe-Ito blue (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "vermillion": {
+          "value": "#D55E00",
+          "description": "Okabe-Ito vermillion (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "reddish-purple": {
+          "value": "#CC79A7",
+          "description": "Okabe-Ito reddish purple (Okabe & Ito 2008, colour-blind safe). House data-viz primitive; maintainer decision 2026-10-29."
+        },
+        "black": {
+          "light": "#000000",
+          "dark": "#FDF9F2",
+          "description": "Okabe-Ito black (Okabe & Ito 2008). In dark mode it becomes content.primary.dark: #000000 is 1.14:1 on the dark page. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        }
+      },
+      "categorical": {
+        "1": {
+          "value": "#E69F00",
+          "description": "= okabe-ito.orange (slot 1, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "2": {
+          "value": "#56B4E9",
+          "description": "= okabe-ito.sky-blue (slot 2, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "3": {
+          "value": "#009E73",
+          "description": "= okabe-ito.bluish-green (slot 3, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "4": {
+          "value": "#F0E442",
+          "description": "= okabe-ito.yellow (slot 4, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "5": {
+          "value": "#0072B2",
+          "description": "= okabe-ito.blue (slot 5, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "6": {
+          "value": "#D55E00",
+          "description": "= okabe-ito.vermillion (slot 6, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "7": {
+          "value": "#CC79A7",
+          "description": "= okabe-ito.reddish-purple (slot 7, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        },
+        "8": {
+          "light": "#000000",
+          "dark": "#FDF9F2",
+          "description": "= okabe-ito.black (slot 8, Wilke order). Categorical colour is never the only channel: pair it with marker shape, line style or a label."
+        }
+      },
+      "uncertainty": {
+        "outer": {
+          "light": "#D6D6D6",
+          "dark": "#333333",
+          "description": "Outermost nested uncertainty band (gray 0.84 in the LIwLD PSTricks figures). The ramp is mirrored in dark mode so the innermost band stays the strongest. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        },
+        "union": {
+          "light": "#9E9E9E",
+          "dark": "#6B6B6B",
+          "description": "Union band (gray 0.62); mirrored in dark mode. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        },
+        "inner": {
+          "light": "#333333",
+          "dark": "#D6D6D6",
+          "description": "Innermost band (gray 0.20); mirrored in dark mode, where #333333 would be 1.46:1. Dark value approved by the maintainer 2026-10-29 (dataviz-check --propose-dark)."
+        }
+      }
     }
   },
   "spacing": {
@@ -200,14 +315,14 @@ const tokens = {
   },
   "border": {
     "subtle": {
-      "light": "rgba(20, 20, 16, 0.1)",
-      "dark": "rgba(237, 237, 235, 0.1)",
-      "description": "Subtle borders - element separation"
+      "light": "rgba(20, 20, 16, 0.47)",
+      "dark": "rgba(237, 237, 235, 0.47)",
+      "description": "Subtle borders - element separation. THE ALPHA IS THE ROLE. Distinct from color.border.subtle: this family has its own base (20,20,16 / 237,237,235), so it needs a DIFFERENT alpha to render the same. 0.47 here matches 0.45 there at 3.07:1 on the worst surface; copying 0.45 would land at 2.90:1 and fail WCAG 1.4.11. Gated by tools/contrast-check.mjs."
     },
     "moderate": {
-      "light": "rgba(20, 20, 16, 0.15)",
-      "dark": "rgba(237, 237, 235, 0.15)",
-      "description": "Moderate borders - defined boundaries"
+      "light": "rgba(20, 20, 16, 0.63)",
+      "dark": "rgba(237, 237, 235, 0.63)",
+      "description": "Moderate borders - defined boundaries. 0.63 here matches color.border.moderate 0.60 in rendered contrast; see border.subtle on why the numbers differ between the two families."
     },
     "focus": {
       "light": "#3498DB",
@@ -282,16 +397,16 @@ const tokens = {
         "description": "Primary sans-serif font - body text"
       },
       "mono": {
-        "value": "JetBrains Mono, SF Mono, Monaco, Inconsolata, monospace",
-        "description": "Monospace font - code blocks and technical content"
+        "value": "Noto Sans Mono, SF Mono, Monaco, Inconsolata, monospace",
+        "description": "Noto Sans Mono — code blocks and technical content; matches the shipped font"
       },
       "display": {
         "value": "var(--font-family-display-editorial)",
-        "description": "DEPRECATED alias of display-editorial; preserved through 0.2.x and removed in 0.3.0. New code should reference --font-family-display-editorial or --font-family-display-documentation directly. See wiki/decisions/display-family-split.md."
+        "description": "Alias of display-editorial, and the load-bearing indirection .di-prose rebinds to swap a whole surface to the documentation family — do NOT rewrite heading rules to reference display-editorial directly or .di-prose stops working. Reference display-editorial/display-documentation explicitly only where the surface must NOT control the family (brand chrome, navbars). Its 0.3.0 removal was deferred 2026-08-10 under wiki/decisions/compatibility-contract.md (additive-only); removal now requires its own cleanup ADR. See wiki/decisions/display-family-split.md."
       },
       "display-editorial": {
-        "value": "Josefin Sans, system-ui, sans-serif",
-        "description": "Editorial display family — Josefin Sans, the brand voice. Used on surfaces where the heading does rhetorical/branding work: hero/landing, marketing, story showcases, slide titles. Default for unmarked headings. Pair with weight 500 (h1) per wiki/decisions/h1-weight-medium.md."
+        "value": "Josefin Sans, Noto Sans, system-ui, sans-serif",
+        "description": "Editorial display family — Josefin Sans, the brand voice. Used on surfaces where the heading does rhetorical/branding work: hero/landing, marketing, story showcases, slide titles. Default for unmarked headings. The Noto Sans fallback serves untagged text; tagged languages are handled by fonts/lang.css. Pair with weight 500 (h1) per wiki/decisions/h1-weight-medium.md."
       },
       "display-documentation": {
         "value": "Noto Sans, system-ui, sans-serif",
@@ -302,8 +417,8 @@ const tokens = {
         "description": "Brand font - dataimago navbar and branding elements"
       },
       "math": {
-        "value": "Noto Sans Math, Noto Sans, system-ui, sans-serif",
-        "description": "Mathematical notation font — Noto Sans Math for broad Unicode math coverage; harmonises with the Noto Sans body stack"
+        "value": "Noto Sans Math, math",
+        "description": "Noto Sans Math, falling back to the browser's maths face; native MathML is the maths contract"
       }
     },
     "size": {