@dataimago/tokens 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/theme-colors-p3.json

@@ -0,0 +1,358 @@
+{
+  "color": {
+    "surface": {
+      "page": {
+        "light": {
+          "srgb": "#ededeb",
+          "oklch": "oklch(94.55% 0.0027 106.45)",
+          "p3": "color(display-p3 0.9294 0.9294 0.9223)"
+        },
+        "dark": {
+          "srgb": "#141410",
+          "oklch": "oklch(18.97% 0.0078 107.13)",
+          "p3": "color(display-p3 0.0784 0.0784 0.0643)"
+        },
+        "description": "Main page background — warm-grey (light) / ink-900 (dark)"
+      },
+      "page-scrolled": {
+        "light": {
+          "srgb": "#ededeb",
+          "oklch": "oklch(94.55% 0.0027 106.45)",
+          "p3": "color(display-p3 0.9294 0.9294 0.9223)"
+        },
+        "dark": {
+          "srgb": "#141410",
+          "oklch": "oklch(18.97% 0.0078 107.13)",
+          "p3": "color(display-p3 0.0784 0.0784 0.0643)"
+        },
+        "description": "Page background when navbar shrinks — matches page"
+      },
+      "elevated": {
+        "light": {
+          "srgb": "#f7f7f6",
+          "oklch": "oklch(97.59% 0.0013 106.42)",
+          "p3": "color(display-p3 0.9686 0.9686 0.9651)"
+        },
+        "dark": {
+          "srgb": "#1c1917",
+          "oklch": "oklch(21.61% 0.0061 56.04)",
+          "p3": "color(display-p3 0.1078 0.0985 0.0911)"
+        },
+        "description": "Cards, modals, dropdowns — one step above page (stone-50 on stone-100 / ink-800 on stone-900-aligned dark)"
+      },
+      "sunken": {
+        "light": {
+          "srgb": "#faf2e3",
+          "oklch": "oklch(96.34% 0.0216 83.26)",
+          "p3": "color(display-p3 0.9749 0.9501 0.8963)"
+        },
+        "dark": {
+          "srgb": "#0c0a09",
+          "oklch": "oklch(14.69% 0.0041 49.25)",
+          "p3": "color(display-p3 0.0457 0.0395 0.0358)"
+        },
+        "description": "Input fields, code blocks — below page level"
+      },
+      "navbar": {
+        "light": {
+          "srgb": "#ededeb",
+          "oklch": "oklch(94.55% 0.0027 106.45)",
+          "p3": "color(display-p3 0.9294 0.9294 0.9223)"
+        },
+        "dark": {
+          "srgb": "#141410",
+          "oklch": "oklch(18.97% 0.0078 107.13)",
+          "p3": "color(display-p3 0.0784 0.0784 0.0643)"
+        },
+        "description": "Navbar background — matches page in both themes"
+      },
+      "navbar-scrolled": {
+        "light": {
+          "srgb": "#ededeb",
+          "oklch": "oklch(94.55% 0.0027 106.45)",
+          "p3": "color(display-p3 0.9294 0.9294 0.9223)"
+        },
+        "dark": {
+          "srgb": "#141410",
+          "oklch": "oklch(18.97% 0.0078 107.13)",
+          "p3": "color(display-p3 0.0784 0.0784 0.0643)"
+        },
+        "description": "Navbar when scrolled/shrunk — matches page-scrolled"
+      },
+      "code": {
+        "light": {
+          "srgb": "#faf2e3",
+          "oklch": "oklch(96.34% 0.0216 83.26)",
+          "p3": "color(display-p3 0.9749 0.9501 0.8963)"
+        },
+        "dark": {
+          "srgb": "#1c1917",
+          "oklch": "oklch(21.61% 0.0061 56.04)",
+          "p3": "color(display-p3 0.1078 0.0985 0.0911)"
+        },
+        "description": "Code block and inline code background"
+      }
+    },
+    "border": {
+      "subtle": {
+        "light": {
+          "srgb": "#0c0a09",
+          "oklch": "oklch(14.69% 0.0041 49.25)",
+          "p3": "color(display-p3 0.0457 0.0395 0.0358)"
+        },
+        "dark": {
+          "srgb": "#fdf9f2",
+          "oklch": "oklch(98.33% 0.0102 81.8)",
+          "p3": "color(display-p3 0.9894 0.977 0.9518)"
+        },
+        "description": "Subtle borders — element separation"
+      },
+      "moderate": {
+        "light": {
+          "srgb": "#0c0a09",
+          "oklch": "oklch(14.69% 0.0041 49.25)",
+          "p3": "color(display-p3 0.0457 0.0395 0.0358)"
+        },
+        "dark": {
+          "srgb": "#fdf9f2",
+          "oklch": "oklch(98.33% 0.0102 81.8)",
+          "p3": "color(display-p3 0.9894 0.977 0.9518)"
+        },
+        "description": "Moderate borders — defined boundaries"
+      },
+      "strong": {
+        "light": {
+          "srgb": "#0c0a09",
+          "oklch": "oklch(14.69% 0.0041 49.25)",
+          "p3": "color(display-p3 0.0457 0.0395 0.0358)"
+        },
+        "dark": {
+          "srgb": "#fdf9f2",
+          "oklch": "oklch(98.33% 0.0102 81.8)",
+          "p3": "color(display-p3 0.9894 0.977 0.9518)"
+        },
+        "description": "Strong borders — prominent separation"
+      },
+      "card": {
+        "light": {
+          "srgb": "#0c0a09",
+          "oklch": "oklch(14.69% 0.0041 49.25)",
+          "p3": "color(display-p3 0.0457 0.0395 0.0358)"
+        },
+        "dark": {
+          "srgb": "#fdf9f2",
+          "oklch": "oklch(98.33% 0.0102 81.8)",
+          "p3": "color(display-p3 0.9894 0.977 0.9518)"
+        },
+        "description": "Card border color with transparency for subtle definition"
+      },
+      "code": {
+        "light": {
+          "srgb": "#d6d3d1",
+          "oklch": "oklch(86.87% 0.0043 56.37)",
+          "p3": "color(display-p3 0.8371 0.8278 0.8205)"
+        },
+        "dark": {
+          "srgb": "#292524",
+          "oklch": "oklch(26.85% 0.0063 34.3)",
+          "p3": "color(display-p3 0.1581 0.1456 0.1418)"
+        },
+        "description": "Code block border"
+      }
+    },
+    "content": {
+      "primary": {
+        "light": {
+          "srgb": "#14140f",
+          "oklch": "oklch(18.93% 0.0098 107.3)",
+          "p3": "color(display-p3 0.0784 0.0784 0.0608)"
+        },
+        "dark": {
+          "srgb": "#fdf9f2",
+          "oklch": "oklch(98.33% 0.0102 81.8)",
+          "p3": "color(display-p3 0.9894 0.977 0.9518)"
+        },
+        "description": "Primary text — stone-900 on stone-100 (light, matches presentation-theme.scss exactly) / paper-100 on dark surface"
+      },
+      "secondary": {
+        "light": {
+          "srgb": "#6a6a6a",
+          "oklch": "oklch(52.43% 0 0)",
+          "p3": "color(display-p3 0.4157 0.4157 0.4157)"
+        },
+        "dark": {
+          "srgb": "#a8a29e",
+          "oklch": "oklch(71.61% 0.0091 56.26)",
+          "p3": "color(display-p3 0.6547 0.6361 0.6215)"
+        },
+        "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": {
+          "srgb": "#706964",
+          "oklch": "oklch(52.57% 0.0118 58.05)",
+          "p3": "color(display-p3 0.4345 0.4127 0.3945)"
+        },
+        "dark": {
+          "srgb": "#89827d",
+          "oklch": "oklch(61.12% 0.0113 58.10)",
+          "p3": "color(display-p3 0.5325 0.5107 0.4925)"
+        },
+        "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": {
+          "srgb": "#fdf9f2",
+          "oklch": "oklch(98.33% 0.0102 81.8)",
+          "p3": "color(display-p3 0.9894 0.977 0.9518)"
+        },
+        "dark": {
+          "srgb": "#0c0a09",
+          "oklch": "oklch(14.69% 0.0041 49.25)",
+          "p3": "color(display-p3 0.0457 0.0395 0.0358)"
+        },
+        "description": "Inverse text — for contrasting backgrounds"
+      }
+    },
+    "interactive": {
+      "primary": {
+        "light": {
+          "srgb": "#434739",
+          "oklch": "oklch(38.97% 0.0235 120.45)",
+          "p3": "color(display-p3 0.2656 0.2779 0.2287)"
+        },
+        "dark": {
+          "srgb": "#98a384",
+          "oklch": "oklch(69.82% 0.0456 123.46)",
+          "p3": "color(display-p3 0.604 0.6378 0.5291)"
+        },
+        "description": "Primary interactive — forest-700 on light (7.75:1 on stone-100, white text 9.0:1 — passes WCAG AAA) / forest-300 on dark"
+      },
+      "hover": {
+        "light": {
+          "srgb": "#363a2e",
+          "oklch": "oklch(34.07% 0.021 122.5)",
+          "p3": "color(display-p3 0.2146 0.2269 0.1848)"
+        },
+        "dark": {
+          "srgb": "#7e8a6b",
+          "oklch": "oklch(61.5% 0.0473 124.97)",
+          "p3": "color(display-p3 0.5029 0.5397 0.4313)"
+        },
+        "description": "Hover state — forest-800 on light (slightly darker than canonical) / forest-400 on dark"
+      },
+      "accent": {
+        "light": {
+          "srgb": "#1f618d",
+          "oklch": "oklch(47.31% 0.0963 242.42)",
+          "p3": "color(display-p3 0.198 0.375 0.5385)"
+        },
+        "dark": {
+          "srgb": "#3498db",
+          "oklch": "oklch(65.31% 0.1347 242.69)",
+          "p3": "color(display-p3 0.3208 0.588 0.8369)"
+        },
+        "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": {
+          "srgb": "#434739",
+          "oklch": "oklch(38.97% 0.0235 120.45)",
+          "p3": "color(display-p3 0.2656 0.2779 0.2287)"
+        },
+        "dark": {
+          "srgb": "#98a384",
+          "oklch": "oklch(69.82% 0.0456 123.46)",
+          "p3": "color(display-p3 0.604 0.6378 0.5291)"
+        },
+        "description": "Focus indicators — mirrors interactive.primary"
+      }
+    },
+    "presentation": {
+      "accent": {
+        "light": {
+          "srgb": "#3498db",
+          "oklch": "oklch(65.31% 0.1347 242.69)",
+          "p3": "color(display-p3 0.3208 0.588 0.8369)"
+        },
+        "dark": {
+          "srgb": "#3498db",
+          "oklch": "oklch(65.31% 0.1347 242.69)",
+          "p3": "color(display-p3 0.3208 0.588 0.8369)"
+        },
+        "description": "Presentation accent — Flat-UI peter-river; reserved for reveal.js 2030s-feel highlights. Not for body prose or interactive primary use. Pairs well with copper on dark slides."
+      },
+      "accent-hover": {
+        "light": {
+          "srgb": "#2980b9",
+          "oklch": "oklch(57.59% 0.119 242.28)",
+          "p3": "color(display-p3 0.2638 0.495 0.7068)"
+        },
+        "dark": {
+          "srgb": "#2980b9",
+          "oklch": "oklch(57.59% 0.119 242.28)",
+          "p3": "color(display-p3 0.2638 0.495 0.7068)"
+        },
+        "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": {
+          "srgb": "#b87333",
+          "oklch": "oklch(61.8% 0.1171 60.4)",
+          "p3": "color(display-p3 0.7242 0.4389 0.1259)"
+        },
+        "dark": {
+          "srgb": "#ce8e5c",
+          "oklch": "oklch(69.98% 0.1021 58.08)",
+          "p3": "color(display-p3 0.8089 0.5486 0.3177)"
+        },
+        "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": {
+          "srgb": "#3b82f6",
+          "oklch": "oklch(62.31% 0.188 259.81)",
+          "p3": "color(display-p3 0.3047 0.5035 0.9338)"
+        },
+        "dark": {
+          "srgb": "#60a5fa",
+          "oklch": "oklch(71.37% 0.1434 254.62)",
+          "p3": "color(display-p3 0.4405 0.6403 0.9545)"
+        },
+        "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": {
+          "srgb": "#5a6310",
+          "oklch": "oklch(47.61% 0.1017 115.99)",
+          "p3": "color(display-p3 0.3595 0.3871 0.1309)"
+        },
+        "dark": {
+          "srgb": "#b2bf22",
+          "oklch": "oklch(76.9% 0.1655 114.7)",
+          "p3": "color(display-p3 0.7074 0.7474 0.2714)"
+        },
+        "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": {
+          "srgb": "#cc0000",
+          "oklch": "oklch(53.08% 0.2178 29.23)",
+          "p3": "color(display-p3 0.7331 0.1519 0.1019)"
+        },
+        "dark": {
+          "srgb": "#ff0000",
+          "oklch": "oklch(62.8% 0.2577 29.23)",
+          "p3": "color(display-p3 1 0 0)"
+        },
+        "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."
+      }
+    }
+  }
+}

package/src/theme-colors.json

@@ -2,19 +2,19 @@
   "color": {
     "surface": {
       "page": {
-        "light": "#fdf9f2",
-        "dark": "#0c0a09",
-        "description": "Main page background — cream-100 (light) / ink-900 (dark)"
+        "light": "#ededeb",
+        "dark": "#141410",
+        "description": "Main page background — warm-grey (light) / ink-900 (dark)"
       },
       "page-scrolled": {
-        "light": "#fdf9f2",
-        "dark": "#0c0a09",
+        "light": "#ededeb",
+        "dark": "#141410",
         "description": "Page background when navbar shrinks — matches page"
       },
       "elevated": {
-        "light": "#fefdfb",
+        "light": "#f7f7f6",
         "dark": "#1c1917",
-        "description": "Cards, modals, dropdowns — one step above page"
+        "description": "Cards, modals, dropdowns — one step above page (stone-50 on stone-100 / ink-800 on stone-900-aligned dark)"
       },
       "sunken": {
         "light": "#faf2e3",
@@ -22,13 +22,13 @@
         "description": "Input fields, code blocks — below page level"
       },
       "navbar": {
-        "light": "#fdf9f2",
-        "dark": "#0c0a09",
+        "light": "#ededeb",
+        "dark": "#141410",
         "description": "Navbar background — matches page in both themes"
       },
       "navbar-scrolled": {
-        "light": "#fdf9f2",
-        "dark": "#0c0a09",
+        "light": "#ededeb",
+        "dark": "#141410",
         "description": "Navbar when scrolled/shrunk — matches page-scrolled"
       },
       "code": {
@@ -66,19 +66,19 @@
     },
     "content": {
       "primary": {
-        "light": "#0c0a09",
+        "light": "#14140f",
         "dark": "#fdf9f2",
-        "description": "Primary text — ink-900 on cream-100 (light) / cream-100 on ink-900 (dark)"
+        "description": "Primary text — stone-900 on stone-100 (light, matches presentation-theme.scss exactly) / paper-100 on dark surface"
       },
       "secondary": {
-        "light": "#57534e",
+        "light": "#6a6a6a",
         "dark": "#a8a29e",
-        "description": "Secondary text — medium emphasis on both themes"
+        "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 (light ≥4.6:1, dark ≥4.6:1; darkened/lightened from #78716c which failed AA on page)"
       },
       "inverse": {
         "light": "#fdf9f2",
@@ -88,23 +88,23 @@
     },
     "interactive": {
       "primary": {
-        "light": "#d46820",
-        "dark": "#f0a467",
-        "description": "Primary interactive — copper-500 on light, copper-300 on dark"
+        "light": "#434739",
+        "dark": "#98a384",
+        "description": "Primary interactive — forest-700 on light (7.75:1 on stone-100, white text 9.0:1 — passes WCAG AAA) / forest-300 on dark"
       },
       "hover": {
-        "light": "#b55017",
-        "dark": "#ea8441",
-        "description": "Hover state — copper-600 on light, copper-400 on dark"
+        "light": "#363a2e",
+        "dark": "#7e8a6b",
+        "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"
+        "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": "#d46820",
-        "dark": "#f0a467",
+        "light": "#434739",
+        "dark": "#98a384",
         "description": "Focus indicators — mirrors interactive.primary"
       }
     },
@@ -119,6 +119,32 @@
         "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). Re-authored at higher P3 chroma (~+28% light / +27% dark) for a vivid wide-gamut pop; sRGB fallback unchanged so contrast is preserved. 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."
+      }
     }
   }
 }

package/src/typography.json

@@ -2,7 +2,7 @@
   "font": {
     "family": {
       "sans": {
-        "value": "Fira Sans, system-ui, sans-serif",
+        "value": "Noto Sans, Fira Sans, system-ui, sans-serif",
         "description": "Primary sans-serif font - body text"
       },
       "mono": {
@@ -10,16 +10,24 @@
         "description": "Monospace font - code blocks and technical content"
       },
       "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."
+      },
+      "display-editorial": {
         "value": "Josefin Sans, system-ui, sans-serif",
-        "description": "Display font - headings and prominent text"
+        "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."
+      },
+      "display-documentation": {
+        "value": "Noto Sans, system-ui, sans-serif",
+        "description": "Documentation display family — Noto Sans, the wayfinding voice. Used on surfaces where the heading does structural work: API docs, foundation Section h2s, KNOWLEDGE.md/CLAUDE.md headings, long-form research subheadings. Activated by wrapping content in .di-prose; pair with weight 600 (semibold). See wiki/decisions/display-family-split.md."
       },
       "brand": {
         "value": "Futura, system-ui, sans-serif",
         "description": "Brand font - dataimago navbar and branding elements"
       },
       "math": {
-        "value": "Fira Math, Fira Sans Math, system-ui, sans-serif",
-        "description": "Mathematical notation font"
+        "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"
       }
     },
     "size": {
@@ -86,9 +94,10 @@
         "description": "Bold — h1, strong emphasis"
       },
       "heading": {
+        "_invariant": "Heading-weight cluster — 400 floor for all Josefin Sans headings (see wiki/decisions/josefin-weight-floor.md). Sub-400 weights (200, 300) are bound to the opt-in .di-numeric-display utility class, never the default for prose-tier headings. Per wiki/decisions/h1-weight-medium.md the prose-correct band for editorial headings is 400–500.",
         "h1": {
-          "value": "var(--font-weight-bold)",
-          "description": "Heading h1 weight — bold (700). Top-level voice; carries the most typographic presence."
+          "value": "var(--font-weight-medium)",
+          "description": "Heading h1 weight — medium (500). Top-level editorial voice; preserves Josefin Sans's geometric character at hero scale (was bold/700 before iteration-1; see wiki/decisions/h1-weight-medium.md)."
         },
         "h2": {
           "value": "var(--font-weight-medium)",
@@ -143,6 +152,17 @@
         "value": "1.625",
         "description": "Relaxed line height - long-form content"
       }
+    },
+    "feature-settings": {
+      "_invariant": "OpenType feature settings cluster — display rules apply lining figures (lnum) so numerals render uniform-baseline at heading scale; body rules retain old-style figures where they belong (in-line numerical mentions in prose). See wiki/decisions/display-lining-figures.md.",
+      "display": {
+        "value": "\"lnum\"",
+        "description": "Lining figures (lnum) for display headings — uniform baseline, uniform height; corrects Josefin Sans's old-style default figures that read as casual at editorial/title scale. Consumed by every CSS rule whose font-family resolves to --font-family-display, --font-family-display-editorial, or --font-family-display-documentation."
+      },
+      "body": {
+        "value": "\"normal\"",
+        "description": "Default figure style for body text — preserves Josefin's old-style figures where they harmonize with lowercase letterforms in continuous prose."
+      }
     }
   }
 }