@mindlogic-ai/logician-ui 5.0.0-alpha.2 → 5.0.0-alpha.21

package/src/theme/SemanticTokens.mdx

@@ -15,7 +15,7 @@ Values and contrast for every token: **Setup/Theme/BAZE Palette**.
 | --- | --- | --- |
 | Raw scale (colour names) | `ink.1–12`, `inkDark.1–12`, `sand.*`, `slate.*`, `coral.*`, `red.base` … | never in components |
 | Semantic step (role names) | `neutral.1–12`, `secondary.1–12` | a specific neutral step no role names |
-| Semantic role | `bg.*`, `layer.*`, `fg.*`, `border.*`, `primary.*`, `secondary.*`, `action.*`, `send.*`, `count.*`, `disabled.*`, `focus.ring`, status, `tooltip.*`, `category.*` | everything else |
+| Semantic role | `bg.*`, `layer.*`, `fg.*`, `border.*`, `primary.*`, `secondary.*`, `action.*`, `send.*`, `count.*`, `disabled.*`, `focus.ring`, status, `tooltip.*`, `category.*`, `data.*`, `diverging.*` | everything else |
 
 ```ts
 createLogicianTheme()                    // BAZE: { neutral: 'ink', secondary: 'sand' }
@@ -42,9 +42,11 @@ createLogicianTheme({ neutral: 'slate' }) // cool gray — app code unchanged
 | Run button (black + coral icon) · small coral marks | `action.bg` / `.fg` / `.iconOnSolid` · `action.mark` |
 | Send button, Button `accent` | `send.bg` / `.bgHover` / `.bgActive` / `.fg` |
 | Unread count | `count.bg` / `count.fg` |
-| Disabled (no opacity) | `disabled.bg` / `disabled.fg` |
+| Disabled (no opacity) | `disabled.bg` / `disabled.fg` · fill-less ghost button: `disabled.fgGhost` |
 | Status | `danger` · `success` · `warning` · `info` → `.bg` `.border` `.fg` `.solid` `.onSolid` |
 | Decorative category (tiles, avatars, tags, charts) | `category.{hue}.surface` / `.fg` |
+| Single-measure chart, usage bar, map, heatmap fill | `data.1`–`data.4` (4 = largest) |
+| Chart fill above / below a real baseline (vs plan, vs average) | `diverging.pos.1–3` / `diverging.neg.1–3`, `diverging.mid` at the baseline |
 
 Emphasis is weight, not colour: headings use `fg.default`, never `primary.*`.
 Status colours mean status — don't borrow `success`/`warning` for decoration;
@@ -57,25 +59,82 @@ Use it for both, and for nothing decorative.
 
 - **Links** — `fg.link` / `fg.linkHover` (blue ink, #48607A / #AFC7E1), in chat
   messages, markdown and app copy alike. Never ink-black or coral for a link.
-- **Data visualisation** — usage/share bars, single-measure bar and line charts,
-  maps, heatmaps, progress-by-share: a **blue monochrome ramp**, never a
-  rainbow and never a grey ramp. Steps differ in lightness only (the saturated
-  `blue.base` is left out); the largest value gets the strongest step.
-
-| Step | Light | Dark |
+- **Data visualisation** — usage/share bars, single-measure bar charts, maps,
+  heatmaps, progress-by-share: the `data.*` ramp, a **blue monochrome ramp**,
+  never a rainbow and never a grey ramp. Steps differ in lightness only (the
+  saturated `blue.base` is left out). **The higher number is the larger value**:
+  `data.4` is the strongest step in both modes (dark mode flips the lightness,
+  so `data.4` is the lightest blue there).
+- **Lines** — a single-measure line chart, and series 1 of a multi-series one,
+  stroke in `blue.base` (`#4674A4` / `#6892BD`, ≥ 4.5:1). A 2px line is not a
+  filled area: the ramp's darkest step `blue.ink` reads as slate grey at that
+  width, so lines take the saturated blue the ramp leaves out.
+
+| Token | Light | Dark |
 | --- | --- | --- |
-| 1 (largest) | `#48607A` (`blue.ink`) · white label | `#AFC7E1` (`blue.inkDark`) · ink label |
-| 2 | `#7492B3` · ink label | `#7492B3` · ink label |
-| 3 | `#AFC7E1` · ink label | `#48607A` · white label |
-| 4 | `#DFEBF9` (`blue.surface`) · ink label | `#232F3D` (`blue.surfaceDark`) · white label |
-
-Pick each label by measured contrast (≥ 4.5:1), not by step number.
-A chart that must tell several *categories* apart (multi-series lines) keeps
-`CHART_SERIES_HUES` in `LineGraph/seriesColors.ts`, which leaves blue out so
-no series reads as a link or an info state.
+| `data.4` (largest) | `#48607A` (`blue.ink`) · white label | `#AFC7E1` (`blue.inkDark`) · ink label |
+| `data.3` | `#7492B3` (`dataviz.blueMid`) · ink label | `#7492B3` · ink label |
+| `data.2` | `#AFC7E1` (`blue.inkDark`) · ink label | `#48607A` (`blue.ink`) · white label |
+| `data.1` (smallest) | `#DFEBF9` (`blue.surface`) · ink label | `#232F3D` (`blue.surfaceDark`) · white label |
+
+Pick each label by measured contrast (≥ 4.5:1), not by step number. Ink is
+`#252525`, white is `#FFFFFF`, in either mode; `contrast.test.ts` re-measures
+every label in this section, including the diverging table below.
+
+A chart that must tell several *categories* apart (multi-series lines) starts
+with the same data blue (`blue.base`) and then cycles `CHART_SERIES_HUES` in
+`LineGraph/seriesColors.ts` (teal, pink, indigo, purple, brown, …), which
+leaves red, yellow and green out so no series reads as a status.
 `info` is also blue; status always comes with an icon and words, so a blue
 chart is never mistaken for an info notice.
 
+### Diverging: above and below a baseline
+
+When the value has a **real zero or baseline** and both directions mean
+something — actual vs plan, this month vs the average, change since last
+week — use the `diverging.*` ramp. A one-sided value (a count, a share, a
+usage total) keeps `data.*`, even if some bars are small.
+
+- **Blue is above the baseline, orange is below** (`diverging.pos.*` /
+  `diverging.neg.*`). `3` is the largest distance from the baseline on either
+  side, and the two sides share their lightness per step, so the same
+  distance looks the same size in both directions.
+- **The baseline itself is `diverging.mid`** (neutral step 3, so it follows
+  the neutral scheme). Never white or `bg.canvas`: a "no change" cell must
+  still read as a cell.
+- **Never red and green for direction.** Above/below is not good/bad. When a
+  direction is good or bad, that is a status: say it with an icon and words,
+  as everywhere else.
+- **Orange is for fills only** — bars, cells, areas. Never orange text or
+  icons; labels and axis text stay `fg.*`. Lines keep the stroke rules
+  above.
+- **The legend names the direction in words** ("above plan" / "below plan"),
+  not only with the two colours.
+
+| Token | Light | Dark |
+| --- | --- | --- |
+| `diverging.pos.3` (far above) | `#2C5D91` · white label | `#A9C7EB` · ink label |
+| `diverging.pos.2` | `#5890CD` · ink label | `#5890CD` · ink label |
+| `diverging.pos.1` (just above) | `#A9C7EB` · ink label | `#2C5D91` · white label |
+| `diverging.mid` (at the baseline) | `#EDE9E2` (`neutral.3`) · ink label | `#2E2F2F` (`neutral.3`) · white label |
+| `diverging.neg.1` (just below) | `#E4BBA0` · ink label | `#85491A` · white label |
+| `diverging.neg.2` | `#BF7946` · **no in-cell label**; label outside the mark | `#BF7946` · **no in-cell label**; label outside the mark |
+| `diverging.neg.3` (far below) | `#85491A` · white label | `#E4BBA0` · ink label |
+
+`diverging.neg.2` clears neither label (ink 4.41:1, white 3.48:1), so values
+for that step go beside or above the bar, not inside it. The `diverging.mid`
+values shown are the `ink` scheme; with `neutral: 'slate'` it is slate step 3.
+
+The diverging ramp is a dedicated data-viz ramp (OKLCH chroma ≈ 0.10–0.11 at
+steps 2–3, 0.06 at step 1, the same on both sides): paired with the dusty
+`data.*` blue (≈ 0.05), any warm hue reads as brown. Blue ↔ orange
+also keeps the widest colour-blind separation of the pairs considered; gold
+reads as a warning and purple collapses into blue for deuteranopes.
+
+`data.*` and `diverging.*` are fills: under high contrast they keep their
+value (like `bg.track`), and in-cell labels are audited at 4.5:1 in light and
+dark.
+
 ## Modes
 
 Every role flips with the colour mode (`_light` / `_dark`) and has a

package/src/theme/claude.md

@@ -143,16 +143,24 @@ is the maintainer's view.
 
 ### Layers and files
 
-| Layer                                                                                                                                                                     | Where                                            | Rule                                                                          |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
-| Raw scales `ink`/`inkDark`, `sand`/`sandDark`, `slate`/`slateDark` (1–12), `coral`, 12 system hues `{base, baseDark, hc, hcDark, surface, ink, surfaceDark, inkDark}`     | `palette.generated.ts` → `colors` in `colors.ts` | Components and recipes **never** read them                                    |
-| Semantic steps `neutral.1–12`, `secondary.1–12`                                                                                                                           | `createSemanticColors()`                         | Filled by the theme option (`neutral: 'ink' \| 'slate'`, `secondary: 'sand'`) |
-| Roles (`bg.*`, `layer.*`, `fg.*`, `border.*`, `primary.*`, `secondary.*`, `action.*`, `send.*`, `count.*`, `disabled.*`, `focus.ring`, status, `tooltip.*`, `category.*`) | `ROLE_TOKEN_PATHS` + `createSemanticColors()`    | The only colours a component reads                                            |
+| Layer                                                                                                                                                                                              | Where                                            | Rule                                                                          |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Raw scales `ink`/`inkDark`, `sand`/`sandDark`, `slate`/`slateDark` (1–12), `coral`, 12 system hues `{base, baseDark, hc, hcDark, surface, ink, surfaceDark, inkDark}`, `dataviz`                   | `palette.generated.ts` → `colors` in `colors.ts` | Components and recipes **never** read them                                    |
+| Semantic steps `neutral.1–12`, `secondary.1–12`                                                                                                                                                    | `createSemanticColors()`                         | Filled by the theme option (`neutral: 'ink' \| 'slate'`, `secondary: 'sand'`) |
+| Roles (`bg.*`, `layer.*`, `fg.*`, `border.*`, `primary.*`, `secondary.*`, `action.*`, `send.*`, `count.*`, `disabled.*`, `focus.ring`, status, `tooltip.*`, `category.*`, `data.*`, `diverging.*`) | `ROLE_TOKEN_PATHS` + `createSemanticColors()`    | The only colours a component reads                                            |
 
 - **Values come from the generator.** `scripts/palette/generate.mjs` ports the
   designer prototype (OKLCH, contrast-targeted steps) and `--check`s it against
   `scripts/palette/reference.json`. Change a value there, regenerate, commit
   `palette.generated.ts`. Never hand-edit the generated file.
+- **Dark mode is a neutral charcoal**, not the prototype's warm dark ramp
+  (re-tuned 2026-10-27; light is still the prototype). `inkDark` steps 1–7
+  hold chroma ≤ 0.003 and only the text steps keep a trace of warmth
+  (≤ 0.008); the canvas is `#171717`; body text is its own anchor
+  (`fgDark`, ≈ 14:1; HC dark `fgHcDark`, ≈ 16:1), not cream; dark
+  `action.fg` uses the same anchor. HC dark `fg.muted` is the OKLCH midpoint
+  of `fg.subtle` and `fg.default`, so the three text levels stay distinct. A warm tint that is invisible in light
+  reads as sepia on a dark ground — keep new dark values near-neutral.
 - **High contrast** (`prefers-contrast: more`): a role whose HC value differs
   reads an internal helper `scheme.light.*` / `scheme.dark.*` (`{ base,
 _moreContrast }`) because Chakra cannot nest `_dark` inside `_moreContrast`
@@ -166,8 +174,9 @@ _moreContrast }`) because Chakra cannot nest `_dark` inside `_moreContrast`
 ### Adding or changing a token
 
 1. Add it to the generator (`buildScheme`) and to `PATHS` in `colors.ts`.
-2. Register its contrast pair(s) in `contrast.test.ts` (`PAIRS`, `SEP`), or a
-   reason in `NO_PAIR`. The registry test fails until you do; the audit runs
+2. Register its contrast pair(s) in `contrast.test.ts` (`PAIRS`, `SEP`; a
+   data-viz fill goes in `DATA_VIZ_LABELS` (`paletteSwatches.ts`) with its in-cell label), or a reason in
+   `NO_PAIR`. The registry test fails until you do; the audit runs
    light / dark / hcLight / hcDark for every neutral scheme.
 3. Add it to `SemanticColorToken` and to SemanticTokens.mdx.
 
@@ -250,8 +259,13 @@ follow the scheme and high contrast. Base font size is 14px.
    badges/tags, the modal header band), never rows or panels.
 5. Disabled = `disabled.*`, not opacity. Focus = `focusRing`.
 6. Blue means data and links: links are `fg.link`; data visualisation
-   (usage bars, single-measure charts, maps) is a blue monochrome ramp, never a
-   rainbow or grey ramp. Values: SemanticTokens.mdx → "Blue means data and links".
+   (usage bars, single-measure bar charts, maps) fills with `data.1–4` (4 =
+   largest), never a rainbow or grey ramp; line strokes (single-measure, and
+   series 1) use `blue.base`. Values against a real baseline (vs plan, vs
+   average) fill with `diverging.pos.1–3` (above, blue) / `diverging.neg.1–3`
+   (below, orange) and `diverging.mid` at the baseline — never red/green for
+   direction, never orange text or icons. Values and labels:
+   SemanticTokens.mdx → "Blue means data and links".
 
 ## Extending the Theme
 

package/src/theme/colors.ts

@@ -7,7 +7,8 @@
  *    black), `sand.1–12` / `sandDark.1–12` (beige-brown), `slate.1–12` /
  *    `slateDark.1–12` (today's cool gray rebuilt on the same contrast targets),
  *    `coral.*`, and the 12 system hues (`red` … `brown`, each
- *    `{base, baseDark, hc, hcDark, surface, ink, surfaceDark, inkDark}`).
+ *    `{base, baseDark, hc, hcDark, surface, ink, surfaceDark, inkDark}`), and
+ *    `dataviz.*` (the data-visualisation values no hue step covers).
  *    The step number is the job (Radix-style): 1–3 backgrounds, 4–6 dividers
  *    and borders, 7 control border (3:1), 8 icon/placeholder (4.5:1), 9–11
  *    text, 12 maximum contrast.
@@ -16,7 +17,10 @@
  *    them (default `ink` / `sand`).
  * 3. **Semantic roles** — `bg.*`, `layer.*`, `fg.*`, `border.*`, `primary.*`,
  *    `secondary.*`, `action.*`, `send.*`, `count.*`, `disabled.*`, `focus.ring`,
- *    the four status families, `tooltip.*`, `category.{hue}.*`.
+ *    the four status families, `tooltip.*`, `category.{hue}.*` (plus the
+ *    nameless `category.neutral.*`), the `bg.logo` / `fg.onLogo` tile, and the
+ *    data-visualisation fills `data.1–4` and `diverging.{pos,neg}.1–3` /
+ *    `diverging.mid`.
  *
  * Every value comes from `palette.generated.ts` (see
  * `scripts/palette/generate.mjs`), which ports the designer-reviewed prototype
@@ -36,7 +40,13 @@
  * `no-deprecated-tokens` lint rule. They are removed in 6.0.
  */
 import DEPRECATED from './deprecatedColorTokens.json';
-import { CORAL, RAMPS, SCHEMES, SYSTEM_HUES } from './palette.generated';
+import {
+  CORAL,
+  DATAVIZ,
+  RAMPS,
+  SCHEMES,
+  SYSTEM_HUES,
+} from './palette.generated';
 
 /** Raw scale that fills `neutral.1–12` and every neutral role. */
 export type NeutralScale = 'ink' | 'slate';
@@ -86,17 +96,25 @@ function rampTokens(
   return out;
 }
 
+/** Brand anchor (generator name) → raw token: `{name}.key` or `{name}Dark.key`. */
+const ANCHOR_TOKENS = [
+  ['cream', 'light', 'cream'],
+  ['press', 'light', 'press'],
+  ['fgDark', 'dark', 'fg'],
+  ['primaryDark', 'dark', 'primary'],
+  ['primaryHoverDark', 'dark', 'primaryHover'],
+  ['pressDark', 'dark', 'press'],
+] as const;
+
 function scaleTokens(name: 'ink' | 'sand' | 'slate') {
   const r = RAMPS[name];
-  const a = r.anchors as Partial<
-    Record<'cream' | 'press' | 'primaryDark' | 'pressDark', string>
-  >;
+  const a = r.anchors as Record<string, string | undefined>;
   const light: Record<string, string> = {};
   const dark: Record<string, string> = { canvas: r.canvasDark };
-  if (a.cream) light.cream = a.cream;
-  if (a.press) light.press = a.press;
-  if (a.primaryDark) dark.primary = a.primaryDark;
-  if (a.pressDark) dark.press = a.pressDark;
+  for (const [anchor, mode, key] of ANCHOR_TOKENS) {
+    const hex = a[anchor];
+    if (hex) (mode === 'light' ? light : dark)[key] = hex;
+  }
   return {
     [name]: rampTokens(r.light, light),
     [`${name}Dark`]: rampTokens(r.dark, dark),
@@ -122,6 +140,9 @@ export const colors = {
       ),
     ])
   ),
+  dataviz: Object.fromEntries(
+    Object.entries(DATAVIZ).map(([k, val]) => [k, v(val)])
+  ),
   white: v('#FFFFFF'),
 } as Record<string, Record<string, TokenValue> | TokenValue>;
 
@@ -189,6 +210,7 @@ const PATHS: Record<FlatKey, string> = {
   'count-fg': 'count.fg',
   'disabled-bg': 'disabled.bg',
   'disabled-fg': 'disabled.fg',
+  'disabled-fgGhost': 'disabled.fgGhost',
   focus: 'focus.ring',
   'danger-bg': 'danger.bg',
   'danger-border': 'danger.border',
@@ -214,6 +236,20 @@ const PATHS: Record<FlatKey, string> = {
   'info-onSolid': 'info.onSolid',
   'tooltip-bg': 'tooltip.bg',
   'tooltip-fg': 'tooltip.fg',
+  // Data visualisation (fills only). Higher number = larger value, in both
+  // modes; the dark values flip lightness so the strongest step stays the
+  // most prominent on a dark canvas.
+  'data-1': 'data.1',
+  'data-2': 'data.2',
+  'data-3': 'data.3',
+  'data-4': 'data.4',
+  'diverging-pos-1': 'diverging.pos.1',
+  'diverging-pos-2': 'diverging.pos.2',
+  'diverging-pos-3': 'diverging.pos.3',
+  'diverging-neg-1': 'diverging.neg.1',
+  'diverging-neg-2': 'diverging.neg.2',
+  'diverging-neg-3': 'diverging.neg.3',
+  'diverging-mid': 'diverging.mid',
 };
 
 /** Exposed for tests and docs: every role token generated from the scheme table. */
@@ -237,10 +273,9 @@ function buildRefIndex(neutral: NeutralScale, secondary: SecondaryScale) {
     for (const s of STEPS) add(RAMPS[name].dark[s], `${name}Dark.${s}`);
     add(RAMPS[name].canvasDark, `${name}Dark.canvas`);
     const a = RAMPS[name].anchors as Record<string, string>;
-    if (a.cream) add(a.cream, `${name}.cream`);
-    if (a.press) add(a.press, `${name}.press`);
-    if (a.primaryDark) add(a.primaryDark, `${name}Dark.primary`);
-    if (a.pressDark) add(a.pressDark, `${name}Dark.press`);
+    for (const [anchor, mode, key] of ANCHOR_TOKENS)
+      if (a[anchor])
+        add(a[anchor], `${name}${mode === 'dark' ? 'Dark' : ''}.${key}`);
   };
   addScale(neutral);
   addScale(secondary);
@@ -249,6 +284,7 @@ function buildRefIndex(neutral: NeutralScale, secondary: SecondaryScale) {
   for (const hue of SYSTEM_HUE_NAMES)
     for (const [k, hex] of Object.entries(SYSTEM_HUES[hue]))
       add(hex, `${hue}.${k}`);
+  for (const [k, hex] of Object.entries(DATAVIZ)) add(hex, `dataviz.${k}`);
   // The brand black/cream anchors exist only on ink; reachable from any scheme.
   if (neutral !== 'ink') addScale('ink');
   return (hex: string) => index.get(hex.toUpperCase()) ?? hex;
@@ -328,6 +364,11 @@ export function createSemanticColors({
     'fg.emphasized': 'fg.default',
     'bg.invalid.subtle': 'danger.bg',
     'bg.highlighted': 'warning.bg',
+    // The no-identity pair, shaped like a category pair so a `colorPalette`
+    // can point at it (`colorPalette="category.neutral"`, the avatar recipe's
+    // default). Not a 13th hue — `hueForName` never returns it.
+    'category.neutral.surface': 'bg.muted',
+    'category.neutral.fg': 'secondary.fgStrong',
     // Every other name Chakra's own recipes read (menu/combobox `_highlighted`
     // is `bg.emphasized/60`, radiomark borders are `border.emphasized`, the
     // field recipe reads `fg.error` …). 4.x got these for free because its
@@ -377,6 +418,15 @@ export function createSemanticColors({
     } as never);
   }
 
+  // Logo tile: model, chatbot and brand marks are drawn for a light ground,
+  // so the tile stays light in both modes (white, then the warm cream anchor
+  // in dark so it does not glare on the dark canvas), and the text on it stays
+  // dark in both modes. Avatar `variant="logo"` reads the pair.
+  setPath(tree, 'bg.logo', {
+    value: { _light: '{colors.white}', _dark: '{colors.ink.cream}' },
+  } as never);
+  setPath(tree, 'fg.onLogo', { value: `{colors.${neutral}.11}` });
+
   // Deprecated 4.x names → 5.0 replacement (removed in 6.0).
   for (const [oldName, newName] of Object.entries(DEPRECATED.aliases))
     setPath(tree, oldName, { value: `{colors.${newName}}` });
@@ -404,23 +454,26 @@ type StatusFamily = 'danger' | 'success' | 'warning' | 'info';
 export type SemanticColorToken =
   | `neutral.${Step}`
   | `secondary.${Step}`
-  | `bg.${'canvas' | 'surface' | 'raised' | 'subtle' | 'muted' | 'sunken' | 'track' | 'inverse' | 'panel' | 'highlighted'}`
+  | `bg.${'canvas' | 'surface' | 'raised' | 'subtle' | 'muted' | 'sunken' | 'track' | 'inverse' | 'panel' | 'highlighted' | 'logo'}`
   | 'bg.invalid.subtle'
   | `layer.${1 | 2 | 3}`
   | `layer.${1 | 2 | 3}.${'hover' | 'active'}`
-  | `fg.${'default' | 'emphasized' | 'muted' | 'subtle' | 'icon' | 'placeholder' | 'onPrimary' | 'link' | 'linkHover' | 'inverse'}`
+  | `fg.${'default' | 'emphasized' | 'muted' | 'subtle' | 'icon' | 'placeholder' | 'onPrimary' | 'onLogo' | 'link' | 'linkHover' | 'inverse'}`
   | `border.${'subtle' | 'default' | 'strong' | 'control'}`
   | `primary.${'main' | 'hover' | 'active' | 'wash' | 'washActive' | 'selected'}`
   | `secondary.${'surface' | 'surfaceStrong' | 'border' | 'fg' | 'fgStrong'}`
   | `action.${'mark' | 'iconOnSolid' | 'bg' | 'bgHover' | 'bgActive' | 'fg' | 'border'}`
   | `send.${'bg' | 'bgHover' | 'bgActive' | 'fg'}`
   | `count.${'bg' | 'fg'}`
-  | `disabled.${'bg' | 'fg'}`
+  | `disabled.${'bg' | 'fg' | 'fgGhost'}`
   | 'focus.ring'
   | `${StatusFamily}.${'bg' | 'border' | 'fg' | 'solid' | 'onSolid'}`
   | `danger.${'solidHover' | 'solidActive'}`
   | `tooltip.${'bg' | 'fg'}`
-  | `category.${Hue}.${'surface' | 'fg'}`
+  | `category.${Hue | 'neutral'}.${'surface' | 'fg'}`
+  | `data.${1 | 2 | 3 | 4}`
+  | `diverging.${'pos' | 'neg'}.${1 | 2 | 3}`
+  | 'diverging.mid'
   | DeprecatedSemanticColorToken;
 
 /**

package/src/theme/contrast.test.ts

@@ -10,6 +10,7 @@ import {
 } from './colors';
 import { system } from './index';
 import { SCHEMES } from './palette.generated';
+import { DATA_VIZ_LABEL_TOKEN, DATA_VIZ_LABELS } from './paletteSwatches';
 
 /**
  * Contrast audit for the BAZE semantic tokens — the same check as section 3-1
@@ -129,6 +130,8 @@ const NO_PAIR: Record<string, string> = {
     'disabled controls are exempt from WCAG contrast (1.4.3 / 1.4.11)',
   'disabled-fg':
     'disabled controls are exempt from WCAG contrast (1.4.3 / 1.4.11)',
+  'disabled-fgGhost':
+    'disabled controls are exempt from WCAG contrast (1.4.3 / 1.4.11)',
   'danger-border':
     'decorative edge of a status surface; the fg/icon carries the status',
   'success-border': 'decorative edge of a status surface',
@@ -137,6 +140,12 @@ const NO_PAIR: Record<string, string> = {
   track: 'unfilled track; the filled part (primary-main) carries the value',
 };
 
+// Data-viz fills (`data.*`, `diverging.*`) are registered through
+// DATA_VIZ_LABELS (paletteSwatches.ts): each fill with the in-cell label it may
+// carry. Audited at 4.5:1 in light and dark, like the category pairs: the fills
+// keep their value under high contrast (they are fills, like `track`), so an
+// in-cell label is not held to the 7:1 high-contrast text target.
+
 // ───────────────────────────── resolver ─────────────────────────────
 
 const lum = (h: string) => {
@@ -253,6 +262,52 @@ describe.each(SCHEME_NAMES)('contrast — %s scheme', (neutral) => {
     expect(failures).toEqual([]);
   });
 
+  it('the nameless avatar pair (category.neutral) reads as text (≥ 4.5:1, all modes)', () => {
+    const failures = MODES.flatMap((mode) => {
+      const c = ratio(
+        resolve('category.neutral.fg', mode),
+        resolve('category.neutral.surface', mode)
+      );
+      return c >= 4.5 ? [] : [`${mode}: ${c.toFixed(2)}`];
+    });
+    expect(failures).toEqual([]);
+  });
+
+  it('logo tile stays light in both modes and its text reads (≥ 4.5:1)', () => {
+    const failures = MODES.flatMap((mode) => {
+      const tile = resolve('bg.logo', mode);
+      const c = ratio(resolve('fg.onLogo', mode), tile);
+      const out = c >= 4.5 ? [] : [`fg.onLogo ${mode}: ${c.toFixed(2)}`];
+      // "Light": a logo drawn for white must keep a light ground in dark mode.
+      return lum(tile) > 0.7 ? out : [...out, `bg.logo ${mode} is not light`];
+    });
+    expect(failures).toEqual([]);
+  });
+
+  it('data-viz fills: each in-cell label clears 4.5:1, and "no label" means neither does (light and dark)', () => {
+    const failures = Object.entries(DATA_VIZ_LABELS).flatMap(([fill, labels]) =>
+      (['light', 'dark'] as const).flatMap((mode) => {
+        const bg = flat(fill, mode);
+        const label = labels[mode];
+        if (label) {
+          const c = ratio(resolve(DATA_VIZ_LABEL_TOKEN[label], mode), bg);
+          return c >= 4.5
+            ? []
+            : [`${label} on ${fill} ${mode}: ${c.toFixed(2)}`];
+        }
+        const best = Math.max(
+          ...Object.values(DATA_VIZ_LABEL_TOKEN).map((t) =>
+            ratio(resolve(t, mode), bg)
+          )
+        );
+        return best < 4.5
+          ? []
+          : [`${fill} ${mode} has no label but one clears ${best.toFixed(2)}`];
+      })
+    );
+    expect(failures).toEqual([]);
+  });
+
   it('every deprecated 4.x name resolves to its replacement in all modes', () => {
     for (const [oldName, newName] of Object.entries(DEPRECATED_COLOR_TOKENS))
       for (const mode of MODES)
@@ -267,6 +322,7 @@ describe('contrast registry', () => {
     ...PAIRS.flatMap(([a, b]) => [a, b]),
     ...SEP.flatMap(([a, b]) => [a, b]),
     ...Object.keys(NO_PAIR),
+    ...Object.keys(DATA_VIZ_LABELS),
   ]);
 
   it('every role token has a contrast pair or a NO_PAIR reason', () => {
@@ -291,6 +347,7 @@ describe('contrast registry', () => {
       /^secondary\.\d+$/,
       /^scheme\.(light|dark)\.\w+$/, // internal high-contrast helpers
       /^category\.\w+\.(surface|fg)$/, // audited by the category test
+      /^(bg\.logo|fg\.onLogo)$/, // audited by the logo tile test
       // kept 4.x names / Chakra globals that reuse a role value verbatim
       /^(bg|fg|border)$/,
       /^bg\.(panel|raised|inverse|sunken|highlighted|invalid\.subtle)$/,

package/src/theme/global.ts

@@ -35,10 +35,29 @@ export const globalCss = defineGlobalStyles({
   },
 
   'html, body': {
-    // Mode-aware primary text (neutral.11 light / cream dark).
+    // Mode-aware primary text (neutral.11 light / off-white dark).
     color: 'fg.default',
   },
 
+  // Korean breaks between 어절, not mid-word — but only Korean. Japanese and
+  // Chinese have no spaces, so `keep-all` turns a whole sentence into one
+  // unbreakable run that overflows its box. Set once on <html> by language
+  // and let it inherit (`word-break` is inherited), so a component that asks
+  // for `break-all` (emails, keys, file names) still gets it. The Typography
+  // components used to hard-code `keep-all` on themselves, which left every
+  // ja screen to undo it one call site at a time.
+  'html:lang(ko)': {
+    wordBreak: 'keep-all',
+  },
+  // Japanese wraps at phrase boundaries (文節) where the browser can find them
+  // (Chromium 119+, ja only). Elsewhere the rule is skipped and ja keeps the
+  // default `normal`, which breaks between characters — never `keep-all`.
+  'html:lang(ja)': {
+    '@supports (word-break: auto-phrase)': {
+      wordBreak: 'auto-phrase',
+    },
+  },
+
   '#__next': {
     height: 'var(--chakra-vh)',
   },

package/src/theme/index.ts

@@ -15,6 +15,7 @@ import {
 import { globalCss } from './global';
 import { animationStyles, durations, easings, keyframes } from './motion';
 import { accordionSlotRecipe } from './recipes/accordion';
+import { avatarSlotRecipe } from './recipes/avatar';
 import { tableSlotRecipe } from './recipes/table';
 
 /**
@@ -403,6 +404,7 @@ export function createLogicianTheme(options: LogicianThemeOptions = {}) {
       },
       slotRecipes: {
         accordion: accordionSlotRecipe,
+        avatar: avatarSlotRecipe,
         table: tableSlotRecipe,
         select: selectSlotRecipe,
       },