@mindlogic-ai/logician-ui 4.0.0 → 5.0.0-alpha.0

package/src/theme/SemanticTokens.mdx

@@ -2,254 +2,73 @@ import { Meta } from '@storybook/blocks';
 
 <Meta title="Setup/Theme/Using Semantic Tokens" />
 
-# Using Semantic Tokens
+# Using Semantic Tokens (5.0 · BAZE)
 
-The design system ships a layer of **semantic color tokens** on top of the raw
-color palette. They are the colors you should reach for in app and component
-code. This guide explains what they are, when to use which, and how they make
-light/dark mode work automatically.
+Components and apps read **role tokens** only. The raw scales (`ink`, `sand`,
+`slate`, `coral`, the 12 system hues) exist so the theme can build the roles;
+reading them directly means a theme switch or a tenant override will not follow.
+Values and contrast for every token: **Setup/Theme/BAZE Palette**.
 
-> Looking for the live swatches and exact hex values? See
-> **Setup/Theme → Palette** — this page is the _how-to_.
+## Three layers
 
----
+| Layer | Names | Example |
+| --- | --- | --- |
+| 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 |
 
-## Why semantic tokens?
-
-A **primitive** like `gray.300` or `blue.500` is a fixed color. It means the
-same thing everywhere and never changes between light and dark.
-
-A **semantic token** like `fg.default` or `bg.surface` describes the _role_ a
-color plays ("primary text", "raised surface"), and resolves to a different
-primitive depending on the active color mode.
-
-```tsx
-// ❌ Primitive — frozen. Looks fine in light, unreadable in dark.
-<Text color="gray.1300" bg="white" />
-
-// ✅ Semantic — flips with the mode automatically.
-<Text color="fg.default" bg="bg.surface" />
+```ts
+createLogicianTheme()                    // BAZE: { neutral: 'ink', secondary: 'sand' }
+createLogicianTheme({ neutral: 'slate' }) // cool gray — app code unchanged
+<LogicianProvider theme={{ neutral: 'slate' }} />
 ```
 
-Two payoffs:
-
-1. **Dark mode for free.** Add `color="fg.default"` and it's `gray.1300` in
-   light and a light neutral in dark — no `useColorMode`, no conditionals.
-2. **Intent, not value.** `border.subtle` always reads as "a low-emphasis
-   divider," whatever the mode. The intent is encoded once, in the theme.
-
-**Rule of thumb:** in app/component code, prefer semantic tokens. Drop to a
-primitive (`gray.300`, `blue.500`, …) only for one-off visuals that genuinely
-have no semantic meaning.
-
----
-
-## The neutral tokens
-
-These cover text, surfaces, and borders — the bulk of any UI. Each flips
-between a light and a dark value.
-
-> **Dark neutrals are desaturated.** The `Dark` columns below name the `gray`
-> step each token mirrors, but in dark mode every neutral actually resolves to a
-> _halved-saturation_ counterpart of that step (the blue-tinted `gray` ramp is
-> right for light surfaces but muddy as a dark one). Light values are exactly the
-> named `gray` step. You never reference the desaturated values directly — use
-> the tokens.
-
-### Foreground — `fg.*` (text & icons)
-
-| Token | Light | Dark | Use for |
-| --- | --- | --- | --- |
-| `fg.emphasized` | `gray.1300` | `gray.200` | Headings, titles, key figures, strong emphasis |
-| `fg.default` | `gray.1000` | `gray.300` | Primary **body** text |
-| `fg.muted` | `gray.900` | `gray.400` | Secondary text, captions, supporting icons |
-| `fg.subtle` | `gray.700` | `gray.600`† | Tertiary text, placeholders, icons |
-| `fg.inverse` | `gray.0` | `gray.1400` | Text on an **inverse** surface (e.g. tooltip) |
-
-† `fg.subtle`'s dark value is bumped one step lighter than the straight mirror so
-helper/secondary text clears WCAG AA 4.5:1 on `bg.muted`.
-
-> `fg.default` is the body weight; `fg.emphasized` is the strongest step (the
-> near-black `gray.1300` `fg.default` used to be). Reach for `emphasized` only
-> when you want maximum contrast — headings, key numbers.
-
-### Background — `bg.*` (surfaces & fills)
-
-| Token | Light | Dark | Use for |
-| --- | --- | --- | --- |
-| `bg.canvas` | `gray.0` | `gray.1500` | App/page background |
-| `bg.surface` | `white` | `gray.1400` | Raised surface — cards, popovers, menus, modals |
-| `bg.raised` | `white` | `gray.1100` | Strongly-raised neutral — one level above `surface` (e.g. a selected segment); tops the dark ramp so it reads as lifted |
-| `bg.sunken` | `gray.50` | `gray.1500` | Sunken page wash for list/overview surfaces, so `bg.surface` cards read as raised above it |
-| `bg.subtle` | `gray.50` | `gray.1300` | Subtle fill, hover background, secondary surface |
-| `bg.muted` | `gray.100` | `gray.1200` | Muted fill, tertiary surface, neutral chips |
-| `bg.inverse` | `gray.1300` | `gray.50` | High-contrast/inverse surface (flips with mode) |
-| `bg.selected` | `blue.25` | `blue.900` | Selected rows/items (mirrors `primary.lightest`) |
-| `bg.invalid.subtle` | `rose.25` | `rose.900` | Validation-error rows/fields (mirrors `danger.lightest`) |
-| `bg.highlighted` | `gold.25` | `gold.900` | Transient highlights, scroll-to emphasis (mirrors `warning.lightest`) |
-
-### Border — `border.*` (borders & dividers)
+## Which token
 
-| Token | Light | Dark | Use for |
-| --- | --- | --- | --- |
-| `border.subtle` | `gray.200` | `gray.1300` | Low-emphasis dividers, faint outlines |
-| `border.default` | `gray.300` | `gray.1100` | Standard borders, container outlines |
-| `border.strong` | `gray.500` | `gray.900` | High-emphasis borders, form-control outlines |
-
-```tsx
-<Box bg="bg.surface" borderColor="border.default" borderWidth="1px">
-  <Heading color="fg.default">Title</Heading>
-  <Text color="fg.muted">Supporting copy</Text>
-</Box>
-```
-
-### `slate.*` — foundational mode-aware neutral family
-
-`slate.0`–`slate.1500` is a **first-class neutral palette**, sitting alongside
-the raw `gray.*` primitives but **mode-aware**: `slate.N` is `gray.N` in light
-and the desaturated counterpart in dark, so one token holds the same tonal level
-in both modes (`slate.300` is a light divider in light and the matching dark
-divider in dark — no `_dark={{…}}` at the call site). It lives under
-`semanticTokens` only because Chakra requires that for the `_dark` flip;
-conceptually it's a **foundation** (a tonal scale), not a **role**.
-
-```tsx
-// Use a role token when one matches the intent (carries semantics + AA tuning):
-<Text color="fg.muted" />
-
-// Reach for slate when you need a specific neutral step no role names — the
-// mode-aware equivalent of dropping to a raw gray.N:
-<Box borderColor="slate.300" bg="slate.50" />
-```
-
-> `slate` and the role tokens (`fg`/`bg`/`border`) are **distinct ramps** —
-> `slate` is a mechanical light↔dark mirror, while the roles carry hand-tuned
-> dark values (AA bumps, hierarchy). They share light values but **diverge in
-> dark**, so they are not drop-in interchangeable. Pick by intent, not by value.
-
----
-
-## The brand tokens
-
-Five intent palettes — `primary` (blue), `secondary` (violet), `danger` (rose),
-`success` (green), `warning` (gold) — each expose a 7-step scale that also
-flips in dark mode:
-
-| Step | Typical use |
+| Need | Token |
 | --- | --- |
-| `lightest` / `extralight` | Tinted backgrounds (badges, soft buttons, banners) |
-| `lighter` / `light` | Hover/pressed tints, subtle fills |
-| `main` | The action color — links, focus rings, ghost/outline text, icons |
-| `dark` | Emphasis text on a light/tinted background |
-| `darker` | High-contrast text |
-
-```tsx
-<Badge bg="danger.extralight" color="danger.dark">Error</Badge>
-<Link color="primary.main">Learn more</Link>
-```
-
-In dark mode these steps lighten so they keep contrast on dark surfaces — e.g.
-`primary.main` is `blue.500` in light and lifts to `blue.300` in dark.
-
-### Solid brand fills — `primary.fill` / `primary.fillStrong`
-
-For a **solid blue surface with white text/icons on top** (modal headers, hero
-banners, brand badges), use `primary.fill` (or `primary.fillStrong` for a deeper
-shade) rather than `primary.main`. The `*.main`/`*.dark` steps lighten in dark —
-right for foreground, but too light to carry white text as a fill — so the
-`fill*` tokens stay deep blue in both modes.
-
-```tsx
-<ModalHeader bg="primary.fill" color="white">Upgrade</ModalHeader>
-```
-
----
-
-## Migration cheat-sheet
-
-Replacing primitives in existing code? Map by role, not by exact value — pick
-the nearest semantic token:
-
-| Was (primitive) | Use (semantic) |
+| Page background | `bg.canvas` (layer 0) |
+| Sidebar / panel on the page · card on that panel · panel in a card | `layer.1` · `layer.2` · `layer.3` (each with `.hover` / `.active`) |
+| 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` |
+| 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` |
+| Soft badge/tag fill, avatar fallback, wash card, info box · notice band · brand modal header | `bg.muted` · `bg.subtle` · `layer.3` (neutral grounds) |
+| Beige accent: text, icons, borders on those (`secondary` identity) | `secondary.fg` / `.fgStrong` / `.border` |
+| Beige tint (tint/accent only — **not a component background**: reads peach as a fill) | `secondary.surface` / `.surfaceStrong` |
+| Run button (black + coral icon) · small coral marks | `action.bg` / `.fg` / `.iconOnSolid` · `action.mark` |
+| Send button | `send.bg` / `.bgHover` / `.bgActive` / `.fg` |
+| Unread count | `count.bg` / `count.fg` |
+| Disabled (no opacity) | `disabled.bg` / `disabled.fg` |
+| Status | `danger` · `success` · `warning` · `info` → `.bg` `.border` `.fg` `.solid` `.onSolid` |
+| Decorative category (tiles, avatars, tags, charts) | `category.{hue}.surface` / `.fg` |
+
+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.
+
+## Modes
+
+Every role flips with the colour mode (`_light` / `_dark`) and has a
+high-contrast value under `prefers-contrast: more` (text 7:1, controls/icons
+4.5:1). `src/theme/contrast.test.ts` measures every registered fg/bg pair in all
+four modes; adding a token without registering its pair fails CI.
+
+## Migrating from 4.x
+
+4.x names still resolve in 5.0 as deprecated aliases (removed in 6.0) and the
+`no-deprecated-tokens` lint rule names the replacement. Run the codemod:
+see `MIGRATION-5.0.md` and `codemods/5.0/README.md`.
+
+| 4.x | 5.0 |
 | --- | --- |
-| `gray.1200`–`gray.1500` as heading/strong text | `fg.emphasized` |
-| `gray.1000`–`gray.1100` as body text | `fg.default` |
-| `gray.900` as secondary text | `fg.muted` |
-| `gray.500`–`gray.800` as tertiary text/icon | `fg.subtle` |
-| `white` / `gray.0` surface | `bg.surface` / `bg.canvas` |
-| `gray.50` / `gray.100` fill | `bg.subtle` / `bg.muted` |
-| `gray.200` / `gray.300` border | `border.subtle` / `border.default` |
-| `gray.500` border | `border.strong` |
-| `blue.*` / `rose.*` … intent color | matching `primary.*` / `danger.*` … step |
-
-The full set of names is exported as the `SemanticColorToken` type
-(`fg.default`, `bg.surface`, `primary.main`, …) for codemods and review.
-
----
-
-## How light/dark actually resolves
-
-- The mode is a **class on `<html>`**: `.dark` toggles every token's `_dark`
-  value (the Chakra v3 default `_dark` selector). No class = light.
-- `LogicianProvider` mounts the color-mode runtime by default (backed by
-  `next-themes`) and owns `color-scheme`. Consumers should add
-  `suppressHydrationWarning` to their `<html>`.
-
-```tsx
-<LogicianProvider defaultColorMode="system">
-  <App />
-</LogicianProvider>
-```
-
-`LogicianProvider` props: `defaultColorMode`, `forcedColorMode` (pin a mode for
-staged rollouts), `enableColorMode`.
-
-### Reading / toggling the mode
-
-```tsx
-import { useColorMode, useColorModeValue, ColorModeToggle } from '@mindlogic-ai/logician-ui';
-
-const { colorMode, setColorMode, toggleColorMode } = useColorMode();
-
-// Prefer tokens; use this only when a value can't be a token (e.g. an image).
-const src = useColorModeValue('/logo-light.svg', '/logo-dark.svg');
-
-// Drop-in switch:
-<ColorModeToggle />
-```
-
----
-
-## Authoring mode-aware components
-
-**Prefer tokens.** If you must vary a raw value by mode, use a conditional
-object — light stays exact, dark overrides:
-
-```tsx
-<Box bgColor={{ base: 'gray.300', _dark: 'gray.1200' }} />
-```
-
-For **third-party libraries that don't understand Chakra tokens** (e.g.
-recharts), pass the token's CSS variable so it still flips via the `.dark`
-class:
-
-```tsx
-<XAxis tick={{ fill: 'var(--chakra-colors-fg-muted)' }} />
-```
-
----
-
-## Contrast / accessibility
-
-The semantic pairings are tuned to meet **WCAG AA** in both modes. A couple of
-things to keep in mind:
-
-- **Solid color buttons keep white labels** on the saturated fill in both
-  modes — except **`warning` (gold)**, which uses a dark label because
-  white-on-gold fails AA. If you build a custom solid `warning` surface, use
-  dark text.
-- For **border-only** controls (e.g. an unchecked checkbox), reach for
-  `border.strong` so the outline clears the 3:1 non-text-contrast bar on dark.
-
-When in doubt, verify the specific pair in **Setup/Theme → Palette**, which
-shows the resolved light/dark values side by side.
+| `primary.lightest` / `extralight` · `lighter` · `light` · `dark` / `darker` | `primary.wash` · `primary.washActive` · `border.strong` · `fg.default` |
+| `primary.fill` · `fillStrong` | `primary.main` · `primary.hover` |
+| `{danger,success,warning}.lightest/extralight` · `lighter/light` · `main` · `dark/darker` | `.bg` · `.border` · `.solid` · `.fg` |
+| `secondary.extralight` · `lighter` · `light` · `main` · `dark` | `secondary.surface` · `.surfaceStrong` · `.border` · `.fg` · `.fgStrong` — the first two are tint-only, not a background: a 4.x `bg="secondary.extralight"/"lighter"` becomes `bg.muted` (or `bg.subtle` for a page-level band) |
+| `bg.selected` · `fg.accent` | `primary.selected` · `primary.main` (links → `fg.link`) |
+| `slate.0/50 · 100 · 200 · 300 · 400 · 500/600 · 700 · 800/900 · 1000/1100 · 1200/1300 · 1400/1500` | `neutral.1 · 2 · 3 · 5 · 6 · 7 · 8 · 9 · 10 · 11 · 12` |
+| raw `blue.N`, `gray.N`, `rose.N` … | removed — pick the role by use (`gray.N` follows the slate row) |

package/src/theme/Surfaces.stories.tsx

@@ -30,11 +30,11 @@ import { H4, Subtext, Text } from '../components/Typography';
  * | token | light | role |
  * | --- | --- | --- |
  * | `bg.surface` | `white` | cards / elevated surfaces |
- * | `bg.sunken` | `gray.50` | primary page wash for list / overview pages |
- * | `bg.canvas` | `gray.0` | navigation chrome |
+ * | `bg.sunken` | `neutral.1` | primary page wash for list / overview pages |
+ * | `bg.canvas` | `white` | navigation chrome |
  *
  * The trap: several component fills also live in the lightest grays — `bg.subtle`
- * is `gray.50` (**identical to `bg.sunken`**) and `bg.muted` is `gray.100`
+ * is `neutral.1` (**identical to `bg.sunken`**) and `bg.muted` is `neutral.2`
  * (~1.03:1 against `bg.sunken`). A component that paints a resting surface with
  * those tokens reads fine on a `bg.surface` card but loses its bounds on a
  * `bg.sunken` page. These stories exist to catch exactly that — a control should

package/src/theme/chakraTokens.test.ts

@@ -0,0 +1,115 @@
+import { createSystem, defaultConfig } from '@chakra-ui/react';
+import { describe, expect, it } from 'vitest';
+
+import { createSemanticColors } from './colors';
+import { createLogicianTheme, normalizeSemanticOverrides } from './index';
+
+type Tree = Record<string, unknown>;
+
+const leaves = (node: Tree, prefix = ''): string[] =>
+  Object.entries(node).flatMap(([key, child]) => {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (child && typeof child === 'object' && 'value' in (child as Tree))
+      return [path];
+    return child && typeof child === 'object'
+      ? leaves(child as Tree, path)
+      : [];
+  });
+
+/** Every `--chakra-colors-*` declaration, keyed `selector :: var`. */
+const tokenDecls = (
+  node: unknown,
+  selector = '',
+  out = new Map<string, string>()
+) => {
+  for (const [key, child] of Object.entries(node as Tree)) {
+    if (child && typeof child === 'object')
+      tokenDecls(child, key.startsWith('@') ? selector : key, out);
+    else out.set(`${selector} :: ${key}`, String(child));
+  }
+  return out;
+};
+const ROOT = '&:where(html, .chakra-theme)';
+const LIGHT = ':root &, .light &';
+
+const chakraColors = defaultConfig.theme?.semanticTokens?.colors as Tree;
+
+describe("Chakra's own neutral and status colour names", () => {
+  // Chakra's recipes read these (menu/combobox `_highlighted: bg.emphasized/60`,
+  // radiomark `border.emphasized`, field `fg.error`). Without a Logician value
+  // they resolve to Chakra's zinc/red palette, which 5.0 no longer shadows.
+  for (const scheme of ['ink', 'slate'] as const) {
+    it(`are all defined by the ${scheme} theme`, () => {
+      const ours = new Set(
+        leaves(createSemanticColors({ neutral: scheme }) as Tree)
+      );
+      const missing = ['bg', 'fg', 'border']
+        .flatMap((group) =>
+          leaves(chakraColors[group] as Tree).map((p) => `${group}.${p}`)
+        )
+        .filter((p) => !ours.has(p));
+      expect(missing).toEqual([]);
+    });
+  }
+
+  it('resolve to Logician roles, not Chakra palette values', () => {
+    const system = createSystem(defaultConfig, createLogicianTheme());
+    const decls = tokenDecls(system.getTokenCss());
+    expect(decls.get(`${ROOT} :: --chakra-colors-bg-emphasized`)).toBe(
+      'var(--chakra-colors-layer-1-active)'
+    );
+    expect(decls.get(`${ROOT} :: --chakra-colors-fg-error`)).toBe(
+      'var(--chakra-colors-danger-fg)'
+    );
+  });
+});
+
+describe('normalizeSemanticOverrides', () => {
+  const override = {
+    theme: {
+      semanticTokens: {
+        colors: {
+          primary: { main: { value: { base: '#ff0000', _dark: '#00ff00' } } },
+        },
+      },
+    },
+  };
+
+  it('copies base into _light so a 4.x-style override wins in light mode', () => {
+    const out = normalizeSemanticOverrides(override);
+    expect(
+      (
+        out.theme?.semanticTokens?.colors as Tree & {
+          primary: { main: { value: unknown } };
+        }
+      ).primary.main.value
+    ).toEqual({ _light: '#ff0000', base: '#ff0000', _dark: '#00ff00' });
+  });
+
+  it('the merged system renders the override, not the library _light', () => {
+    const lightValue = (cfg: typeof override) =>
+      tokenDecls(
+        createSystem(defaultConfig, createLogicianTheme(), cfg).getTokenCss()
+      ).get(`${LIGHT} :: --chakra-colors-primary-main`);
+    // Without normalising, the library's `_light` (ink) wins in light mode.
+    expect(lightValue(override)).not.toBe('#ff0000');
+    expect(lightValue(normalizeSemanticOverrides(override))).toBe('#ff0000');
+  });
+
+  it('leaves string values and explicit _light untouched', () => {
+    const cfg = {
+      theme: {
+        semanticTokens: {
+          colors: {
+            a: { value: '#123456' },
+            b: { value: { _light: '#111111', base: '#222222' } },
+          },
+        },
+      },
+    };
+    const colors = normalizeSemanticOverrides(cfg).theme?.semanticTokens
+      ?.colors as Tree & { a: { value: unknown }; b: { value: unknown } };
+    expect(colors.a.value).toBe('#123456');
+    expect(colors.b.value).toEqual({ _light: '#111111', base: '#222222' });
+  });
+});