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

package/src/foundations/BrandColour.mdx

@@ -39,7 +39,11 @@ token for which surface: **Setup/Theme/Using Semantic Tokens**.
 - **The twelve system hues are for categories only.** `category.{hue}.*`
   carries no status meaning.
 - **Blue means data and links.** `fg.link` for links; a blue monochrome ramp
-  for single-measure charts (see Using Semantic Tokens).
+  (`data.1–4`) for single-measure charts (see Using Semantic Tokens).
+- **Above and below a baseline is blue and orange.** Charts against a real
+  baseline (vs plan, vs average) use `diverging.*`: blue above, orange below,
+  `diverging.mid` at the baseline. Orange fills only, never red/green for
+  direction.
 - **No gradients.** A brand band is one solid colour.
 
 ## Neutrals
@@ -85,6 +89,7 @@ borrowing a hue.
 | The coral icon on the black run button (`action.iconOnSolid`) | Wide surfaces, light backgrounds, card fills |
 | The AI-working mark, the logo mark, large type (`action.mark`) | Promotion badges |
 | The unread count badge (`count.*`, a deeper coral red) | Warning and error text or borders; switches and checkboxes when on; links |
+| The prize amount on an event screen, as display type (`action.mark`) | Event card headers, modal footer bands, small eyebrow text |
 
 - **Points, not surfaces.** Nothing coral is larger than a button, badge or
   icon. Coral and the error red are only a few degrees apart in hue; at light
@@ -94,6 +99,34 @@ borrowing a hue.
   Super Agent diamond are status and identity marks, so they may appear next to
   a run signal.
 
+## Campaign and event surfaces
+
+First decide whether the screen is product or marketing. A page that needs a
+login, or has controls that change the account, is product. In-app event pages,
+their intro modals and promo banners are product. Marketing is everything
+outside the product that people see logged out: baze.co, SNS posts, print.
+
+- **In the product, events follow the coral rule above.** No coral fills and
+  no text on coral. Emphasis comes from the illustration; a band behind a card
+  header or modal footer is `bg.muted` or `layer.*`, never `secondary.surface`
+  or coral.
+- **The prize may be coral.** The reward amount as display type in
+  `action.mark` (24px and up, or 19px bold) is the screen's one coral moment.
+  Everything around it stays neutral.
+- **Small text is never coral.** Eyebrows and labels use `fg.subtle`. Darkening
+  coral until small text passes contrast lands right next to the error text red
+  (`danger.fg`).
+- **A thin decorative line counts as a point.** A coral line up to 4px with no
+  text or information on it is allowed, like the band under the FactChat promo
+  banner.
+- **Event CTAs stay `primary`.** An event screen is a product screen, so
+  `Button variant="accent"` stays on marketing heroes (see Button usage), and a
+  reward claim is never coral.
+- **A marketing page may have one full-bleed coral band.** Only ink or cream
+  content sits on it; elsewhere on that page coral is large type or art only.
+  The reference is baze.co/social: the offer section is the band, and
+  "80개 이상", "월 5,900원" and "9,000" are the large coral type.
+
 ## Status
 
 <Canvas of={BrandColour.Status} sourceState="none" />
@@ -186,7 +219,10 @@ BAZE의 화면은 따뜻한 무채색입니다. 크림·아이보리 바탕에
 - **열두 가지 시스템 색은 카테고리 구분에만 씁니다.** `category.{hue}.*`에는 상태의
   뜻이 없습니다.
 - **파란색은 데이터와 링크를 뜻합니다.** 링크는 `fg.link`, 하나의 값을 보여 주는
-  차트는 파란색 단색 단계를 씁니다(Using Semantic Tokens 참고).
+  차트는 파란색 단색 단계(`data.1–4`)를 씁니다(Using Semantic Tokens 참고).
+- **기준선 위아래는 파랑과 주황으로 나눕니다.** 계획 대비, 평균 대비처럼 실제 기준선이
+  있는 차트는 `diverging.*`를 씁니다. 기준선 위는 파랑, 아래는 주황, 기준선 자리는
+  `diverging.mid`입니다. 주황은 면에만 쓰고, 방향을 빨강·초록으로 나타내지 않습니다.
 - **그라데이션은 쓰지 않습니다.** 브랜드 띠는 단색 하나로 칠합니다.
 
 ## 무채색
@@ -231,6 +267,7 @@ BAZE의 화면은 따뜻한 무채색입니다. 크림·아이보리 바탕에
 | 블랙 실행 버튼 위의 코랄 아이콘 (`action.iconOnSolid`) | 넓은 면, 옅은 배경, 카드 바탕 |
 | AI 작업 중 표시, 로고 마크, 큰 글씨 (`action.mark`) | 프로모션 배지 |
 | 읽지 않은 숫자 배지 (`count.*`, 조금 더 진한 코랄 레드) | 경고·오류 문구와 테두리, 켜진 스위치·체크박스, 링크 |
+| 이벤트 화면의 보상 금액 큰 글씨 (`action.mark`) | 이벤트 카드 머리와 모달 하단 띠, 작은 머리말 글자 |
 
 - **면이 아니라 점으로 씁니다.** 버튼·배지·아이콘보다 큰 면을 코랄로 칠하지 않습니다.
   코랄과 오류 빨강은 색상 차이가 몇 도밖에 나지 않아 옅게 쓰면 같은 색이 됩니다.
@@ -239,6 +276,32 @@ BAZE의 화면은 따뜻한 무채색입니다. 크림·아이보리 바탕에
   버튼이 사라지고 그 자리에 로딩 표시가 나타납니다. 숫자 배지와 Super Agent 마름모는
   상태와 정체성을 나타내는 표시라 실행 신호와 함께 보여도 됩니다.
 
+## 캠페인·이벤트 화면
+
+먼저 그 화면이 제품인지 마케팅인지 가립니다. 로그인해야 들어갈 수 있거나 계정을
+바꾸는 조작이 있으면 제품입니다. 앱 안의 이벤트 페이지와 그 안내 모달, 프로모션
+배너도 제품입니다. 마케팅은 제품 밖에서 로그인 없이 보는 화면으로, baze.co, SNS
+게시물, 인쇄물이 여기에 해당합니다.
+
+- **제품 안의 이벤트도 위의 코랄 규칙을 따릅니다.** 코랄로 면을 칠하지 않고 코랄
+  위에 글자를 올리지 않습니다. 강조는 일러스트로 하고, 카드 머리나 모달 하단의 띠는
+  `bg.muted`나 `layer.*`로 칠합니다. `secondary.surface`나 코랄은 쓰지 않습니다.
+- **보상 금액은 코랄로 쓸 수 있습니다.** 보상 금액을 `action.mark` 큰 글씨(24px
+  이상, 또는 19px 굵게)로 쓰는 것이 그 화면의 하나뿐인 코랄입니다. 주변은 모두
+  무채색으로 둡니다.
+- **작은 글자는 코랄로 쓰지 않습니다.** 작은 머리말이나 라벨은 `fg.subtle`을 씁니다.
+  작은 글자가 대비 기준을 넘을 때까지 코랄을 어둡게 하면 오류 문구의 빨강
+  (`danger.fg`)과 거의 같아집니다.
+- **얇은 장식선은 점으로 봅니다.** 글자나 정보 없이 장식만 하는 4px 이하의 코랄 선은
+  써도 됩니다. FactChat 프로모션 배너 아래의 띠가 그 예입니다.
+- **이벤트의 행동 유도 버튼은 `primary`입니다.** 이벤트 화면도 제품 화면이므로
+  `Button variant="accent"`는 마케팅 히어로에만 씁니다(Button 사용법 참고). 보상 받기
+  버튼도 코랄로 칠하지 않습니다.
+- **마케팅 페이지에는 화면 폭을 가득 채우는 코랄 띠를 하나 둘 수 있습니다.** 그 위에는
+  블랙이나 크림색 내용만 올리고, 페이지의 나머지 부분에서 코랄은 큰 글씨나 그림에만
+  씁니다. 기준은 baze.co/social입니다. 혜택 섹션이 그 띠이고, "80개 이상",
+  "월 5,900원", "9,000"이 코랄 큰 글씨입니다.
+
 ## 상태
 
 <Canvas of={BrandColour.Status} sourceState="none" />

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
 

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,9 @@
  *    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}.*`, 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 +39,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';
@@ -122,6 +131,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>;
 
@@ -214,6 +226,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. */
@@ -249,6 +275,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;
@@ -421,6 +448,9 @@ export type SemanticColorToken =
   | `danger.${'solidHover' | 'solidActive'}`
   | `tooltip.${'bg' | 'fg'}`
   | `category.${Hue}.${'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
@@ -137,6 +138,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 +260,30 @@ describe.each(SCHEME_NAMES)('contrast — %s scheme', (neutral) => {
     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 +298,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', () => {