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

package/src/guidelines/_components/Lang.tsx

@@ -0,0 +1,175 @@
+/**
+ * Doc-only language switch for the Storybook guideline pages.
+ *
+ * One MDX file carries both languages: wrap each block in `<En>` / `<Ko>` and
+ * put `<LangToggle />` at the top of the page. The choice is kept in
+ * localStorage (default English) and every block on the page — and on every
+ * other guideline page — follows it.
+ *
+ * Not part of the published library: nothing in `src/index.ts` imports it,
+ * `check-component-exports.js` only scans `src/components`, and the rollup
+ * build excludes `src/guidelines/**`.
+ */
+import { ReactNode, useSyncExternalStore } from 'react';
+
+type DocLang = 'en' | 'ko';
+
+const STORAGE_KEY = 'logician-ui:docs-lang';
+const listeners = new Set<() => void>();
+let current: DocLang | undefined;
+
+const read = (): DocLang => {
+  try {
+    return window.localStorage.getItem(STORAGE_KEY) === 'ko' ? 'ko' : 'en';
+  } catch {
+    return 'en';
+  }
+};
+
+const write = (lang: DocLang) => {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, lang);
+  } catch {
+    // Storage blocked (private mode): the switch still works for this page.
+  }
+  current = lang;
+  listeners.forEach((notify) => notify());
+};
+
+const snapshot = (): DocLang => (current ??= read());
+
+// Another tab changed it: one listener for the whole page, not one per block.
+const onStorage = (event: StorageEvent) => {
+  if (event.key !== STORAGE_KEY) return;
+  current = read();
+  listeners.forEach((notify) => notify());
+};
+
+const subscribe = (notify: () => void) => {
+  if (listeners.size === 0) window.addEventListener('storage', onStorage);
+  listeners.add(notify);
+  return () => {
+    listeners.delete(notify);
+    if (listeners.size === 0) window.removeEventListener('storage', onStorage);
+  };
+};
+
+/** The language the reader picked; `'en'` until they pick one. */
+const useDocLang = (): DocLang =>
+  useSyncExternalStore(subscribe, snapshot, () => 'en');
+
+const pick = <V,>(lang: DocLang, en: V, ko: V) => (lang === 'ko' ? ko : en);
+
+const Block = ({ lang, children }: { lang: DocLang; children: ReactNode }) =>
+  useDocLang() === lang ? <div lang={lang}>{children}</div> : null;
+
+/** English block. Leave a blank line after the opening tag so Markdown parses. */
+export const En = ({ children }: { children: ReactNode }) => (
+  <Block lang="en">{children}</Block>
+);
+
+/** Korean block. Leave a blank line after the opening tag so Markdown parses. */
+export const Ko = ({ children }: { children: ReactNode }) => (
+  <Block lang="ko">{children}</Block>
+);
+
+/** Inline text in the reader's language, for captions and table cells. */
+export const T = ({ en, ko }: { en: ReactNode; ko: ReactNode }) => {
+  const lang = useDocLang();
+  return <span lang={lang}>{pick(lang, en, ko)}</span>;
+};
+
+const OPTIONS: { value: DocLang; label: string }[] = [
+  { value: 'en', label: 'English' },
+  { value: 'ko', label: '한국어' },
+];
+
+/** Top-of-page switch. Renders as a two-button segmented control. */
+export const LangToggle = () => {
+  const lang = useDocLang();
+  return (
+    <div
+      role="group"
+      aria-label="Language / 언어"
+      style={{
+        display: 'inline-flex',
+        border: '1px solid #D8D2CA',
+        borderRadius: 8,
+        overflow: 'hidden',
+        margin: '0 0 16px',
+        fontSize: 13,
+      }}
+    >
+      {OPTIONS.map((option) => {
+        const active = option.value === lang;
+        return (
+          <button
+            key={option.value}
+            type="button"
+            lang={option.value}
+            aria-pressed={active}
+            onClick={() => write(option.value)}
+            style={{
+              padding: '6px 14px',
+              border: 0,
+              cursor: 'pointer',
+              fontWeight: active ? 700 : 400,
+              background: active ? '#252525' : 'transparent',
+              color: active ? '#F5EDE0' : '#252525',
+            }}
+          >
+            {option.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+};
+
+const VERDICT = {
+  do: {
+    mark: '✓',
+    en: 'Do',
+    ko: '이렇게 하세요',
+    rule: '#5E7A37',
+    ink: '#425C17',
+  },
+  dont: {
+    mark: '×',
+    en: "Don't",
+    ko: '이렇게 하지 마세요',
+    rule: '#A02525',
+    ink: '#A02525',
+  },
+};
+
+/** Do / Don't caption under a `<Canvas>` specimen. */
+export const Verdict = ({
+  kind,
+  en,
+  ko,
+}: {
+  kind: 'do' | 'dont';
+  en: ReactNode;
+  ko: ReactNode;
+}) => {
+  const lang = useDocLang();
+  const v = VERDICT[kind];
+  return (
+    <p
+      lang={lang}
+      style={{
+        margin: '-12px 0 28px',
+        paddingLeft: 12,
+        borderLeft: `3px solid ${v.rule}`,
+        fontSize: 14,
+        lineHeight: 1.6,
+      }}
+    >
+      <strong style={{ color: v.ink }}>
+        {v.mark} {pick(lang, v.en, v.ko)}.
+      </strong>{' '}
+      {pick(lang, en, ko)}
+    </p>
+  );
+};

package/src/guidelines/_components/TokenTable.tsx

@@ -0,0 +1,136 @@
+/**
+ * Doc-only token table for guideline pages: one row per semantic token, with
+ * its light and dark value resolved from the shipped theme
+ * (`getSwatchGroups` in `src/theme/paletteSwatches.ts`). No hex is written by
+ * hand, so a palette change shows up here on the next build.
+ *
+ * Render it inside a story (it uses Chakra), then pull the story into MDX with
+ * `<Canvas of={…} />` or `<Story of={…} />`. Not exported from the library.
+ */
+import type { ReactNode } from 'react';
+import { Box, Grid } from '@chakra-ui/react';
+import { readableColor } from 'polished';
+
+import { getSwatchGroups, Swatch } from '../../theme/paletteSwatches';
+import { T } from './Lang';
+
+const SWATCHES: ReadonlyMap<string, Swatch> = new Map(
+  getSwatchGroups().flatMap(([, swatches]) =>
+    swatches.map((swatch) => [swatch.path, swatch] as const)
+  )
+);
+
+/** Light and dark hex of a public semantic token. Throws on an unknown name. */
+const resolveToken = (path: string): Swatch => {
+  const swatch = SWATCHES.get(path);
+  if (!swatch) throw new Error(`Unknown semantic colour token: ${path}`);
+  return swatch;
+};
+
+/** Label colour for a chip: brand black or white, whichever reads on it. */
+const labelOn = (hex: string) =>
+  readableColor(hex, '#252525', '#FFFFFF', false);
+
+const Chip = ({ hex }: { hex: string }) => {
+  const transparent = !/^#/.test(hex);
+  return (
+    <Box
+      // Literal values, not tokens: the chip shows one fixed mode's value
+      // whatever mode the page is in.
+      style={{
+        background: transparent ? undefined : hex,
+        color: transparent ? undefined : labelOn(hex),
+      }}
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderStyle={transparent ? 'dashed' : 'solid'}
+      borderRadius="sm"
+      px={2}
+      py={1.5}
+      fontFamily="mono"
+      fontSize="11px"
+      minW="88px"
+    >
+      {hex.replace('#', '')}
+    </Box>
+  );
+};
+
+type TokenRow = {
+  /** Semantic token path, e.g. `primary.main`. */
+  token: string;
+  /** What the token is for, in the reader's language. */
+  use?: ReactNode;
+};
+
+const HEADERS: ReactNode[] = [
+  <T key="token" en="Token" ko="토큰" />,
+  <T key="light" en="Light" ko="라이트" />,
+  <T key="dark" en="Dark" ko="다크" />,
+  <T key="use" en="Use" ko="쓰는 곳" />,
+];
+
+/**
+ * Token | light | dark | use. Pass `rows` as token names or `{ token, use }`;
+ * `use` is usually a `<T en ko />` so it follows the page language.
+ */
+export const TokenTable = ({ rows }: { rows: (string | TokenRow)[] }) => {
+  const normalised = rows.map((row) =>
+    typeof row === 'string' ? { token: row } : row
+  );
+  const hasUse = normalised.some((row) => row.use);
+  return (
+    <Grid
+      templateColumns={{
+        base: 'minmax(0,1fr) auto auto',
+        md: hasUse
+          ? 'minmax(160px,auto) auto auto minmax(0,1fr)'
+          : 'minmax(160px,auto) auto auto',
+      }}
+      columnGap={3}
+      rowGap={1.5}
+      alignItems="center"
+      justifyContent="start"
+      fontSize="13px"
+      color="fg.default"
+      maxW="100%"
+    >
+      {HEADERS.slice(0, hasUse ? 4 : 3).map((header, i) => (
+        <Box
+          key={i}
+          fontWeight="bold"
+          color="fg.subtle"
+          display={i === 3 ? { base: 'none', md: 'block' } : undefined}
+        >
+          {header}
+        </Box>
+      ))}
+      {normalised.map(({ token, use }) => {
+        const { light, dark } = resolveToken(token);
+        return (
+          <Box key={token} display="contents">
+            <Box fontFamily="mono" fontSize="12px" wordBreak="break-all">
+              {token}
+              {use && (
+                <Box
+                  display={{ base: 'block', md: 'none' }}
+                  fontFamily="body"
+                  color="fg.subtle"
+                >
+                  {use}
+                </Box>
+              )}
+            </Box>
+            <Chip hex={light} />
+            <Chip hex={dark} />
+            {hasUse && (
+              <Box display={{ base: 'none', md: 'block' }} color="fg.muted">
+                {use}
+              </Box>
+            )}
+          </Box>
+        );
+      })}
+    </Grid>
+  );
+};

package/src/theme/BazePalette.stories.tsx

@@ -7,7 +7,19 @@ import {
   ROLE_TOKEN_PATHS,
   SYSTEM_HUE_NAMES,
 } from './colors';
-import { CORAL, RAMPS, SCHEMES, SYSTEM_HUES } from './palette.generated';
+import {
+  CORAL,
+  DATAVIZ,
+  RAMPS,
+  SCHEMES,
+  SYSTEM_HUES,
+} from './palette.generated';
+import {
+  DATA_VIZ_LABEL_TOKEN,
+  DATA_VIZ_LABELS,
+  type DataVizKey,
+  resolveColor,
+} from './paletteSwatches';
 
 /**
  * logician-ui 5.0 BAZE palette — the three token layers.
@@ -104,6 +116,12 @@ export const RawScales: Story = {
           <Chip key={k} hex={hex} label={k} />
         ))}
       </Flex>
+      <H4>dataviz</H4>
+      <Flex gap={2} wrap="wrap">
+        {Object.entries(DATAVIZ).map(([k, hex]) => (
+          <Chip key={k} hex={hex} label={k} />
+        ))}
+      </Flex>
       <H4>system hues</H4>
       <Grid templateColumns="120px repeat(8, 1fr)" gap={1} fontSize="11px">
         <span />
@@ -157,6 +175,98 @@ export const RoleTokens: Story = {
   ),
 };
 
+const DATA_STEPS = (Object.keys(DATA_VIZ_LABELS) as DataVizKey[]).filter((k) =>
+  k.startsWith('data-')
+);
+/** Display order: far below → baseline → far above. */
+const DIVERGING_STEPS: DataVizKey[] = [
+  'diverging-neg-3',
+  'diverging-neg-2',
+  'diverging-neg-1',
+  'diverging-mid',
+  'diverging-pos-1',
+  'diverging-pos-2',
+  'diverging-pos-3',
+];
+
+/** A fill with the in-cell label `DATA_VIZ_LABELS` gives it (or none). */
+const DataCell = ({
+  flat,
+  hex,
+  mode,
+}: {
+  flat: DataVizKey;
+  hex: string;
+  mode: 'light' | 'dark';
+}) => {
+  const label = DATA_VIZ_LABELS[flat][mode];
+  const labelHex =
+    label && resolveColor(`{colors.${DATA_VIZ_LABEL_TOKEN[label]}}`, mode);
+  return (
+    <Stack gap={1}>
+      <Flex
+        bg={hex}
+        color={labelHex || undefined}
+        h="56px"
+        align="center"
+        justify="center"
+        fontSize="13px"
+        fontWeight="bold"
+        borderRadius="sm"
+      >
+        {labelHex && '42%'}
+      </Flex>
+      {/* Plain boxes: the panel paints its own mode, so text inherits its colour. */}
+      <Box fontFamily="mono" fontSize="11px">
+        {ROLE_TOKEN_PATHS[flat]}
+      </Box>
+      <Box fontSize="10px">
+        {hex} ·{' '}
+        {labelHex
+          ? `${label} label ${ratio(hex, labelHex).toFixed(2)}`
+          : 'no in-cell label'}
+      </Box>
+    </Stack>
+  );
+};
+
+/**
+ * Data-visualisation fills — `data.1–4` (single measure, 4 = largest) and
+ * `diverging.*` (blue above the baseline, orange below, `diverging.mid` at it)
+ * — in light and dark, each with the in-cell label it can carry.
+ */
+export const DataViz: Story = {
+  render: () => (
+    <Stack gap={6} maxW="1100px">
+      {(['light', 'dark'] as const).map((mode) => {
+        const table = SCHEMES.ink[mode] as Record<string, string>;
+        return (
+          <Stack
+            key={mode}
+            gap={4}
+            p={4}
+            borderRadius="md"
+            bg={table['bg-canvas']}
+            color={table['fg-default']}
+          >
+            <Box fontWeight="bold">{mode}</Box>
+            <Grid templateColumns="repeat(4, 1fr)" gap={2}>
+              {DATA_STEPS.map((k) => (
+                <DataCell key={k} flat={k} hex={table[k]} mode={mode} />
+              ))}
+            </Grid>
+            <Grid templateColumns="repeat(7, 1fr)" gap={2}>
+              {DIVERGING_STEPS.map((k) => (
+                <DataCell key={k} flat={k} hex={table[k]} mode={mode} />
+              ))}
+            </Grid>
+          </Stack>
+        );
+      })}
+    </Stack>
+  ),
+};
+
 /** Live tokens on this page's colour mode — flip the toolbar to check dark. */
 export const Category: Story = {
   render: () => (

package/src/theme/Palette.stories.tsx

@@ -30,9 +30,9 @@ const meta = {
 
 Three layers; components read only the last one.
 
-1. **Raw scales** — \`ink\` / \`inkDark\`, \`sand\` / \`sandDark\`, \`slate\` / \`slateDark\` (1–12), \`coral\`, and 12 system hues. Values come from \`scripts/palette/generate.mjs\`.
+1. **Raw scales** — \`ink\` / \`inkDark\`, \`sand\` / \`sandDark\`, \`slate\` / \`slateDark\` (1–12), \`coral\`, 12 system hues, and \`dataviz\`. Values come from \`scripts/palette/generate.mjs\`.
 2. **Semantic steps** — \`neutral.1–12\` and \`secondary.1–12\`, filled by the theme option: \`createLogicianTheme({ neutral: 'ink' | 'slate', secondary: 'sand' })\` (or \`<LogicianProvider theme={…}>\`).
-3. **Role tokens** — \`bg.*\`, \`layer.*\`, \`fg.*\`, \`border.*\`, \`primary.*\`, \`action.*\`, status \`{bg,border,fg,solid,onSolid}\`, \`category.*\` …
+3. **Role tokens** — \`bg.*\`, \`layer.*\`, \`fg.*\`, \`border.*\`, \`primary.*\`, \`action.*\`, status \`{bg,border,fg,solid,onSolid}\`, \`category.*\`, data-viz fills \`data.*\` / \`diverging.*\` …
 
 Every value below is shown in light and dark. Contrast is audited in CI (\`contrast.test.ts\`) in light, dark and both high-contrast modes. The 4.x names still resolve as aliases until 6.0 and are listed at the bottom, not in the grid. Setup/Theme/BAZE Palette shows the raw scales and every role in all four modes.
         `,

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' }
@@ -45,6 +45,8 @@ createLogicianTheme({ neutral: 'slate' }) // cool gray — app code unchanged
 | 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` |
+| 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 | `#38332E` (`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,11 +143,11 @@ 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
@@ -166,8 +166,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 +251,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