@mindlogic-ai/logician-ui 5.0.0-alpha.3 → 5.0.0-alpha.30

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.*`, `control.*`, `mark.starred`, `disabled.*`, `focus.ring`, status, `tooltip.*`, `category.*`, `data.*`, `diverging.*` | everything else |
 
 ```ts
 createLogicianTheme()                    // BAZE: { neutral: 'ink', secondary: 'sand' }
@@ -32,7 +32,7 @@ createLogicianTheme({ neutral: 'slate' }) // cool gray — app code unchanged
 | Raised surface (card, menu, popover, input) | `bg.surface` |
 | Body · secondary · caption text | `fg.default` · `fg.muted` · `fg.subtle` |
 | Icon · placeholder | `fg.icon` · `fg.placeholder` |
-| Link | `fg.link` + underline, hover `fg.linkHover` |
+| Link | `fg.link` + 1px underline at rest; hover `fg.linkHover` + 2px underline |
 | Divider · card border · input/checkbox border | `border.subtle` · `border.default` · `border.control` |
 | Primary (black) fill · text on it | `primary.main` / `.hover` / `.active` · `fg.onPrimary` |
 | Hover / press wash, selected row | `primary.wash` / `primary.washActive` · `primary.selected` |
@@ -42,40 +42,139 @@ 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` |
+| On/off state: Switch on, selected toggle chip · thumb or label on it | `control.on` · `control.onFg` |
+| User-marked item: favourite star, saved template, bookmark (filled) | `mark.starred` (the unmarked outline stays `fg.icon`) |
+| 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;
 that is what `category.*` is for.
 
+## State: on and starred
+
+**Binary on/off state uses `control.on`; user-marked items (star/bookmark) use
+`mark.starred`; never `primary`/black/white or a status colour for state.**
+
+- **`control.on`** fills a control that is on: the Switch track, a selected
+  toggle chip, any on/off control. Whatever is drawn on it (the thumb, the
+  chip label) is `control.onFg`. It is green today (#30862D light / #8FC46E
+  dark), the value Switch read from `success.solid` before, but it is not a
+  status: "on" does not mean "succeeded", and the two may move apart.
+- **`mark.starred`** fills something the user marked to keep: a favourite, a
+  saved template, a starred item, a bookmark. The filled icon takes
+  `mark.starred`; the unmarked outline stays `fg.icon`, so selected and
+  unselected differ in colour as well as in shape.
+- **Why not `primary`.** `primary.main` is the same ink (#252525 light, the
+  pale sand in dark) as the outline icon next to it, so a filled star and an
+  empty one could only be told apart by shape. A status colour would say
+  something about the item that is not true.
+- **Not coral, blue or teal/mint.** Coral is send, run, AI-working and the
+  count badge; blue is data and links; teal and mint are not product UI.
+- Checkbox stays `primary.main` when checked.
+
+| Token | Light | Dark | High contrast (light / dark) |
+| --- | --- | --- | --- |
+| `control.on` | `#30862D` (4.59:1 on white) | `#8FC46E` (7.22:1 on `bg.surface`) | `#036805` / `#8FC46E` |
+| `control.onFg` | `#FFFFFF` | `#1B1B1B` | same |
+| `mark.starred` | `#B78100` (3.41:1 on white, 3.01:1 on `layer.1`) | `#E4AC44` (`yellow.base`, 7.22:1 on `bg.surface`) | `#976300` (4.51:1 on `layer.1`) / `#E4AC44` |
+
+`mark.starred` is the yellow hue (BAZE's gold). `yellow.base` is only 2.04:1
+on white, so light mode darkens it in OKLCH (same hue) until it clears 3:1 on
+every light layer; dark mode uses `yellow.base` itself.
+
 ## Blue means data and links
 
 Blue is the one hue BAZE gives a meaning outside status: **data and links**.
 Use it for both, and for nothing decorative.
 
-- **Links** — `fg.link` / `fg.linkHover` (blue ink, #48607A / #AFC7E1), in chat
+- **Links** — `fg.link` (blue ink, #48607A light / #AFC7E1 dark), 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 |
+  **Always underlined, at rest too**: next to body text (#252525) the blue is
+  only 2.36:1, under the 3:1 that colour alone would need (WCAG 1.4.1), so the
+  underline is what marks it as a link. Hover is `fg.linkHover` — further from
+  the canvas than rest, never toward it: #304760 light (9.56:1 on white vs
+  6.50:1 at rest), #C5DEF8 dark (10.66:1 vs 8.48:1 on `bg.surface`) — and the
+  underline thickens to 2px.
+- **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.*`, `control.*`, `mark.starred`, `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.
 
@@ -221,6 +230,14 @@ fontSizes: {
 
 **Base font size:** `14px` (set in `global.ts`)
 
+## Control sizes
+
+`controlSizes.ts` is the single size scale for every control (Button's values:
+xs `sizes.8` · sm `sizes.9` · md `sizes.10` · lg `sizes.11`, one textStyle per
+size). `recipes/controls.ts` maps Chakra's button / input / textarea / select /
+combobox / tabs / checkbox / radioGroup / switch recipes onto it. See
+`src/components/claude.md` → Control sizes.
+
 ## Border Radius
 
 ```tsx
@@ -246,12 +263,20 @@ follow the scheme and high contrast. Base font size is 14px.
 1. Read only role tokens; reach for `neutral.N` only when no role names the job.
 2. Emphasis is weight, not colour — never `primary.*` for text.
 3. Status colours carry status meaning; decoration uses `category.*`.
+   State is neither: binary on/off state uses `control.on` (+ `control.onFg`
+   for the thumb or label on it); user-marked items (star/bookmark) use
+   `mark.starred`; never `primary`/black/white or a status colour for state.
 4. Beige (`secondary.surface*`) is for small surfaces (bubbles, soft
    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.
@@ -15,8 +16,12 @@
  *    `createLogicianTheme({ neutral, secondary })` decides which raw scale fills
  *    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}.*`.
+ *    `secondary.*`, `action.*`, `send.*`, `count.*`, `control.*` (on/off
+ *    state), `mark.starred` (user-marked items), `disabled.*`, `focus.ring`,
+ *    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 +41,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 +97,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 +141,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>;
 
@@ -187,8 +209,16 @@ const PATHS: Record<FlatKey, string> = {
   'send-fg': 'send.fg',
   'count-bg': 'count.bg',
   'count-fg': 'count.fg',
+  // State, not status: a binary control that is on (Switch, selected toggle
+  // chip) and the thing on it (thumb, chip label); something the user marked
+  // to keep (favourite star, bookmark). Never primary/black/white or a status
+  // colour for either.
+  'control-on': 'control.on',
+  'control-onFg': 'control.onFg',
+  'mark-starred': 'mark.starred',
   '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 +244,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 +281,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 +292,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 +372,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 +426,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 +462,28 @@ 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'}`
+  | `control.${'on' | 'onFg'}`
+  | 'mark.starred'
+  | `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
@@ -46,6 +47,10 @@ const PAIRS: [string, string, Kind][] = [
         ['action-mark', bg, 'nontext'],
         ['primary-main', bg, 'nontext'],
         ['danger-fg', bg, 'nontext'],
+        // An on Switch track / selected chip against the ground it sits on,
+        // and a starred mark (a filled icon) on every layer (WCAG 1.4.11).
+        ['control-on', bg, 'nontext'],
+        ['mark-starred', bg, 'nontext'],
       ] as [string, string, Kind][]
   ),
   ['fg-placeholder', 'bg-surface', 'text'],
@@ -64,6 +69,10 @@ const PAIRS: [string, string, Kind][] = [
   ['fg-muted', 'bg-subtle', 'text'],
   ['fg-icon', 'bg-muted', 'nontext'],
   ['fg-icon', 'bg-subtle', 'nontext'],
+  // The favourite star sits on a bg.surface circle over thumbnails, and on
+  // bg.muted cards.
+  ['mark-starred', 'bg-surface', 'nontext'],
+  ['mark-starred', 'bg-muted', 'nontext'],
   ['fg-default', 'secondary-surface', 'text'],
   ['secondary-fgStrong', 'secondary-surface', 'text'],
   ['secondary-fgStrong', 'secondary-surfaceStrong', 'text'],
@@ -85,6 +94,8 @@ const PAIRS: [string, string, Kind][] = [
   ['danger-onSolid', 'danger-solid', 'text'],
   ['success-fg', 'success-bg', 'text'],
   ['success-onSolid', 'success-solid', 'text'],
+  // `text`: a selected toggle chip puts its label on control.on.
+  ['control-onFg', 'control-on', 'text'],
   ['warning-fg', 'warning-bg', 'text'],
   ['warning-onSolid', 'warning-solid', 'text'],
   ['info-fg', 'info-bg', 'text'],
@@ -129,6 +140,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 +150,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 +272,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 +332,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 +357,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)$/,