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

package/src/components/Workflow/Workflow.usage.mdx

@@ -0,0 +1,199 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as WorkflowStories from './stories/Workflow.stories';
+
+<Meta of={WorkflowStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Workflow
+
+A node-based workflow editor on React Flow: a drag-and-drop palette, a
+canvas with undo/redo, auto-arrange and selection, and an optional inspector
+drawer. It ships **no node types**: you register yours with
+`defineNodeType`, and you own persistence and validation. FactChat's studio
+behaviour editor is built on it. Full API: `Workflow/README.md`.
+
+## When to use
+
+- Users build or read a graph of steps with branches: triggers, AI steps,
+  conditions, outputs.
+- A read-only picture of a saved flow (`readOnly`, `showPalette={false}`,
+  `minHeight={0}`).
+
+## When not to use
+
+- A fixed, linear sequence of steps → a numbered list or a stepper.
+- A hierarchy → `Tree`.
+- A settings form that happens to have sections → `Accordion` or `Card`s.
+
+## Options that change behaviour
+
+| Prop / part | Means |
+| --- | --- |
+| `nodeTypes` | Required. Your node kinds; `category` (`trigger`, `ai`, `logic`, `safety`, `output`, `note`) drives the tile colour |
+| `graph` + `onGraphChange`, or `defaultGraph` | Controlled or uncontrolled graph |
+| `<NodeInspector />` child | Built-in drawer on selection (`dock="left" \| "right"`); omit it and use `onSelectionChange` to drive your own panel |
+| `issues` / `validating` | Render-only validation you supply; the editor does not validate |
+| `readOnly` | No palette, no connecting, dragging or deleting; the inspector becomes a read-only view |
+| `translate` | Chrome copy. Without it the bundled strings resolve to Korean |
+| `useWorkflowActions().addNode` | Add nodes without dragging (a "+" toolbar, a tap-to-add list) |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Workflow
+
+React Flow 위에 만든 노드 기반 워크플로 편집기입니다. 끌어다 놓는 팔레트, 실행 취소·
+다시 실행, 자동 정렬, 선택이 되는 캔버스, 그리고 선택해서 켜는 속성 서랍이 있습니다.
+**노드 종류는 하나도 들어 있지 않습니다.** `defineNodeType`으로 직접 등록하고, 저장과
+검증도 앱이 맡습니다. FactChat 스튜디오의 동작 편집기가 이것으로 만들어졌습니다. 전체
+API는 `Workflow/README.md`에 있습니다.
+
+## 언제 쓰나요
+
+- 사용자가 갈래가 있는 단계 그래프(트리거, AI 단계, 조건, 출력)를 만들거나 읽을 때.
+- 저장된 흐름을 읽기 전용 그림으로 보여 줄 때(`readOnly`, `showPalette={false}`,
+  `minHeight={0}`).
+
+## 언제 쓰지 않나요
+
+- 갈래 없이 정해진 순서의 단계라면 번호 목록이나 단계 표시를 씁니다.
+- 계층이라면 `Tree`를 씁니다.
+- 섹션이 있는 설정 폼이라면 `Accordion`이나 `Card`를 씁니다.
+
+## 동작을 바꾸는 옵션
+
+| 속성 / 파트 | 뜻 |
+| --- | --- |
+| `nodeTypes` | 필수. 노드 종류. `category`(`trigger`, `ai`, `logic`, `safety`, `output`, `note`)가 타일 색을 정합니다 |
+| `graph` + `onGraphChange`, 또는 `defaultGraph` | 제어 그래프 또는 비제어 그래프 |
+| 자식 `<NodeInspector />` | 선택하면 열리는 기본 서랍(`dock="left" \| "right"`). 빼고 `onSelectionChange`로 직접 만든 패널을 움직일 수도 있습니다 |
+| `issues` / `validating` | 앱이 넘기는 검증 결과를 그리기만 합니다. 편집기가 검증하지 않습니다 |
+| `readOnly` | 팔레트를 숨기고 연결·이동·삭제를 막습니다. 서랍은 읽기 전용 보기가 됩니다 |
+| `translate` | 화면 문구 번역 함수. 넘기지 않으면 내장 문구가 한국어로 나옵니다 |
+| `useWorkflowActions().addNode` | 끌지 않고 노드를 추가합니다("+" 도구 모음, 눌러서 추가하는 목록) |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={WorkflowStories.AddNodeWithoutDrag} />
+<Verdict
+  kind="do"
+  en="Offer a way to add nodes without dragging: a + beside the selected node or a list of node types, built on useWorkflowActions().addNode."
+  ko="끌지 않고도 노드를 추가할 방법을 줍니다. useWorkflowActions().addNode로 선택한 노드 옆의 +나 노드 종류 목록을 만듭니다."
+/>
+
+<Canvas of={WorkflowStories.ReadOnly} />
+<Verdict
+  kind="do"
+  en="Use readOnly for a saved flow the user can look at but not change."
+  ko="사용자가 보기만 하고 바꾸지 않는 저장된 흐름에는 readOnly를 씁니다."
+/>
+
+<Verdict
+  kind="dont"
+  en="Validate inside the editor or rely on canvas colour alone for errors. Pass issues with a message; they appear on the node and in the drawer as text."
+  ko="편집기 안에서 검증하거나 캔버스 색만으로 오류를 알리지 마세요. 메시지가 있는 issues를 넘기면 노드와 서랍에 글로 나타납니다."
+/>
+
+<En>
+
+## Content
+
+- Node `label`s are short operational nouns (Message, Condition). The README
+  keeps them untranslated on purpose.
+- `getMetaChips` shows a few words of config on the card; keep chips short.
+- Issue `message`s say what to fix: "연결되지 않은 출구가 있습니다", not "오류".
+
+## Accessibility
+
+What Workflow does for you:
+
+- Canvas controls (zoom, fit, undo, redo, lock, auto-arrange) are buttons
+  with translated names; the palette is a labelled region with a named close
+  button (WCAG 4.1.2).
+- Keyboard shortcuts: ⌘/Ctrl+Z and +Y (undo, redo), +C/+V (copy, paste),
+  +D (duplicate), Delete/Backspace (remove the selected node or edge), Escape
+  (close the inspector). They stay out of the way while typing in a field.
+
+What you still have to do:
+
+- **Give a non-drag way to add nodes** (WCAG 2.5.7): the palette is
+  drag-and-drop. Use `useWorkflowActions().addNode`, as in the Do example.
+- **Pass `translate`** for any non-Korean app, or the chrome is announced in
+  Korean.
+- Moving nodes and drawing connections are pointer gestures in React Flow;
+  the graph is hard to edit by keyboard alone. Keep the inspector the place
+  where every setting can be changed by keyboard (WCAG 2.1.1).
+
+## Tokens
+
+Node tiles take their colour from `category`; override the mapping with
+`categoryTokens`. See `Workflow/README.md`, "Theming, layout & read-only".
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 노드 `label`은 짧은 동작 명사(Message, Condition)로 씁니다. README는 일부러 번역하지
+  않습니다.
+- `getMetaChips`는 카드에 설정값 몇 단어를 보여 줍니다. 칩은 짧게 씁니다.
+- issue의 `message`에는 고칠 내용을 씁니다. '오류'가 아니라 '연결되지 않은 출구가
+  있습니다'처럼 씁니다.
+
+## 접근성
+
+Workflow가 알아서 하는 일
+
+- 캔버스 컨트롤(확대, 축소, 화면 맞춤, 실행 취소, 다시 실행, 잠금, 자동 정렬)은 번역된
+  이름이 있는 버튼이고, 팔레트는 이름이 있는 영역이며 닫기 버튼에도 이름이 있습니다
+  (WCAG 4.1.2).
+- 단축키: ⌘/Ctrl+Z와 +Y(실행 취소, 다시 실행), +C/+V(복사, 붙여넣기), +D(복제),
+  Delete/Backspace(선택한 노드나 연결 삭제), Escape(서랍 닫기). 입력 칸에 글을 쓰는
+  동안에는 동작하지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **끌지 않고 노드를 추가하는 방법을 줍니다**(WCAG 2.5.7). 팔레트는 끌어다 놓는
+  방식입니다. 이렇게 하세요 예시처럼 `useWorkflowActions().addNode`를 씁니다.
+- 한국어가 아닌 앱이라면 **`translate`를 넘깁니다.** 넘기지 않으면 화면 문구가 한국어로
+  읽힙니다.
+- 노드 이동과 연결 그리기는 React Flow의 포인터 동작이라 키보드만으로 그래프를 고치기
+  어렵습니다. 모든 설정은 서랍에서 키보드로 바꿀 수 있게 합니다(WCAG 2.1.1).
+
+## 토큰
+
+노드 타일 색은 `category`에서 오며, `categoryTokens`로 바꿀 수 있습니다.
+`Workflow/README.md`의 "Theming, layout & read-only"를 봅니다.
+
+</Ko>
+
+<En>
+
+## Related
+
+- **Tree**: a hierarchy rather than a graph.
+- **Banner**: graph-wide issues above the canvas.
+- `Workflow/README.md`: node types, the inspector, selection, `hostBridge`.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tree**: 그래프가 아니라 계층일 때.
+- **Banner**: 캔버스 위의 그래프 전체 문제.
+- `Workflow/README.md`: 노드 종류, 서랍, 선택, `hostBridge`.
+
+</Ko>

package/src/components/noRawScales.test.ts

@@ -4,7 +4,7 @@ import { join, relative } from 'node:path';
 import { describe, expect, it } from 'vitest';
 
 import { SYSTEM_HUE_NAMES } from '@/theme/colors';
-import { CORAL } from '@/theme/palette.generated';
+import { CORAL, DATAVIZ } from '@/theme/palette.generated';
 
 /**
  * Components read ROLE tokens (`bg.*`, `fg.*`, `primary.*`, `category.*` …),
@@ -64,6 +64,7 @@ const TOKEN = new RegExp(
   `(?<![\\w.$-])(?:` +
     `(?:${alt(numeric)})\\.\\d+` +
     `|coral\\.(?:${alt(Object.keys(CORAL))})` +
+    `|dataviz\\.(?:${alt(Object.keys(DATAVIZ))})` +
     `|(?:${alt(SYSTEM_HUE_NAMES)})\\.(?:${alt(HUE_KEYS)})` +
     `)(?![\\w.])`,
   'g'
@@ -124,6 +125,7 @@ describe('components read no raw palette scales', () => {
       "'ink.12'",
       "'sandDark.3'",
       "'coral.base'",
+      "'dataviz.blueMid'",
       "'red.surface'",
       "'blue.hc'",
       "'blackAlpha.600'",
@@ -135,6 +137,8 @@ describe('components read no raw palette scales', () => {
       "'category.green.surface'",
       "'green'",
       "'fg.default'",
+      "'data.4'",
+      "'diverging.pos.3'",
       'theme.colors.gray.100',
       "'--chakra-colors-gray-100'",
       "'secondary.surface'",

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