@mindlogic-ai/logician-ui 3.1.0-alpha.9 → 3.2.0-alpha.0

package/src/components/Workflow/stories/Workflow.stories.tsx

@@ -0,0 +1,111 @@
+import { Box, HStack, VStack } from '@chakra-ui/react';
+import type { Meta, StoryFn } from '@storybook/react';
+import { useState } from 'react';
+
+import { Subtext, Subtitle } from '@/components/Typography';
+
+import { NodeInspector } from '../canvas/DrawerShell';
+import { Workflow } from '../Workflow';
+import type { Graph, WorkflowSelection } from '../Workflow.types';
+import { toyGraph, toyNodeTypes } from './toyNodeTypes';
+
+/**
+ * The Workflow editor wired with toy (domain-free) node types. The same
+ * component powers FactChat's studio editor; the difference is entirely in the
+ * registered `nodeTypes` + the surrounding chrome the host composes.
+ */
+const meta: Meta<typeof Workflow> = {
+  title: 'Components/Workflow',
+  component: Workflow,
+  parameters: { layout: 'fullscreen' },
+  decorators: [
+    (Story) => (
+      <Box h="600px" w="100%" borderWidth="1px" borderColor="border.default">
+        <Story />
+      </Box>
+    ),
+  ],
+};
+export default meta;
+
+/**
+ * Default: palette + canvas + the built-in `<NodeInspector>` drawer. Drag a node
+ * from the palette, connect handles, undo/redo, auto-arrange, and click a node
+ * to edit it in the drawer.
+ */
+export const Default: StoryFn<typeof Workflow> = () => (
+  <Workflow nodeTypes={toyNodeTypes} defaultGraph={toyGraph as Graph}>
+    <NodeInspector />
+  </Workflow>
+);
+
+/** Empty canvas — only the palette. Proves the cold-start (no nodes) path. */
+export const Empty: StoryFn<typeof Workflow> = () => (
+  <Workflow nodeTypes={toyNodeTypes}>
+    <NodeInspector />
+  </Workflow>
+);
+
+/**
+ * No `<NodeInspector>` — the host owns inspection. Clicking a node drives a panel
+ * rendered *outside* the canvas via `onSelectionChange`. This is the seam for
+ * "clicking a node controls a different part of the UI".
+ */
+export const CustomSelectionPanel: StoryFn<typeof Workflow> = () => {
+  const [selection, setSelection] = useState<WorkflowSelection | null>(null);
+  return (
+    <HStack h="100%" gap={0} align="stretch">
+      <Box flex="1" minW={0}>
+        <Workflow
+          nodeTypes={toyNodeTypes}
+          defaultGraph={toyGraph as Graph}
+          onSelectionChange={setSelection}
+        />
+      </Box>
+      <VStack
+        w="280px"
+        p={4}
+        align="stretch"
+        borderLeftWidth="1px"
+        borderColor="border.default"
+        bg="bg.surface"
+      >
+        <Subtitle>My own panel</Subtitle>
+        <Subtext
+          color={selection ? undefined : 'slate.500'}
+          data-testid="selection-readout"
+        >
+          {selection
+            ? `Selected ${selection.type}: ${selection.id}`
+            : 'Click a node or edge…'}
+        </Subtext>
+      </VStack>
+    </HStack>
+  );
+};
+
+/**
+ * Read-only preview: no palette, the inspector renders as a legible non-editing
+ * view (controls disabled). Used for embedded thumbnails / version previews.
+ */
+export const ReadOnly: StoryFn<typeof Workflow> = () => (
+  <Workflow
+    nodeTypes={toyNodeTypes}
+    defaultGraph={toyGraph as Graph}
+    readOnly
+    showPalette={false}
+  >
+    <NodeInspector />
+  </Workflow>
+);
+
+/** Inspector docked on the left (e.g. when another surface owns the right rail). */
+export const LeftDockedInspector: StoryFn<typeof Workflow> = () => (
+  <Workflow
+    nodeTypes={toyNodeTypes}
+    defaultGraph={toyGraph as Graph}
+    showPalette={false}
+  >
+    <NodeInspector dock="left" />
+  </Workflow>
+);

package/src/components/Workflow/stories/toyNodeTypes.tsx

@@ -0,0 +1,146 @@
+'use client';
+
+import { VStack } from '@chakra-ui/react';
+
+import { FormControl } from '@/components/FormControl';
+import { FormLabel } from '@/components/FormLabel';
+import { Bulb, Plus, Sparkles } from '@/components/Icon';
+import { Input } from '@/components/Input';
+
+import { defineNodeType, type NodeTypeDef } from '../Workflow.types';
+
+/**
+ * Toy node kinds used only by the stories. They prove the Workflow component is
+ * domain-free — these math primitives have nothing to do with any host app, yet
+ * exercise the full contract (handles, drawers, placement, output schema).
+ */
+
+type InputCfg = { value: number };
+type AddCfg = { label: string };
+type OutputCfg = { label: string };
+
+const inputNode = defineNodeType<InputCfg>({
+  kind: 'math.input',
+  label: 'Number',
+  description: 'Constant input',
+  category: 'trigger',
+  icon: Sparkles,
+  defaultConfig: () => ({ value: 1 }),
+  placement: { role: 'start' },
+  handles: () => ({ inputs: [], outputs: [{ id: 'out' }] }),
+  outputSchema: () => ({
+    type: 'object',
+    properties: { value: { type: 'number' } },
+    required: ['value'],
+    additionalProperties: false,
+  }),
+  getInstanceTitle: (cfg) => `${cfg.value}`,
+  renderDrawer: ({ config, onChange, readOnly }) => (
+    <FormControl>
+      <FormLabel>Value</FormLabel>
+      <Input
+        type="number"
+        value={config.value}
+        disabled={readOnly}
+        onChange={(e) =>
+          onChange({ ...config, value: Number(e.target.value) || 0 })
+        }
+      />
+    </FormControl>
+  ),
+});
+
+const addNode = defineNodeType<AddCfg>({
+  kind: 'math.add',
+  label: 'Add',
+  description: 'a + b',
+  category: 'logic',
+  icon: Plus,
+  defaultConfig: () => ({ label: 'sum' }),
+  handles: () => ({
+    inputs: [
+      { id: 'a', label: 'a' },
+      { id: 'b', label: 'b' },
+    ],
+    outputs: [{ id: 'out' }],
+  }),
+  outputSchema: () => ({
+    type: 'object',
+    properties: { value: { type: 'number' } },
+    required: ['value'],
+    additionalProperties: false,
+  }),
+  getInstanceTitle: (cfg) => cfg.label,
+  getMetaChips: (cfg) => [cfg.label],
+  renderDrawer: ({ config, onChange, readOnly }) => (
+    <VStack align="stretch" gap={3}>
+      <FormControl>
+        <FormLabel>Label</FormLabel>
+        <Input
+          value={config.label}
+          disabled={readOnly}
+          onChange={(e) => onChange({ ...config, label: e.target.value })}
+        />
+      </FormControl>
+    </VStack>
+  ),
+});
+
+const outputNode = defineNodeType<OutputCfg>({
+  kind: 'math.output',
+  label: 'Print',
+  description: 'Terminal output',
+  category: 'output',
+  icon: Bulb,
+  defaultConfig: () => ({ label: 'result' }),
+  placement: { minCount: 1, role: 'end' },
+  handles: () => ({ inputs: [{ id: 'in' }], outputs: [] }),
+  getInstanceTitle: (cfg) => cfg.label,
+  renderDrawer: ({ config, onChange, readOnly }) => (
+    <FormControl>
+      <FormLabel>Label</FormLabel>
+      <Input
+        value={config.label}
+        disabled={readOnly}
+        onChange={(e) => onChange({ ...config, label: e.target.value })}
+      />
+    </FormControl>
+  ),
+});
+
+export const toyNodeTypes: NodeTypeDef[] = [inputNode, addNode, outputNode];
+
+/** A small starter graph: two inputs feeding an Add, feeding a Print. */
+export const toyGraph = {
+  nodes: [
+    {
+      id: 'a',
+      kind: 'math.input',
+      position: { x: 0, y: 0 },
+      config: { value: 2 },
+    },
+    {
+      id: 'b',
+      kind: 'math.input',
+      position: { x: 0, y: 140 },
+      config: { value: 3 },
+    },
+    {
+      id: 'sum',
+      kind: 'math.add',
+      position: { x: 280, y: 70 },
+      config: { label: 'sum' },
+    },
+    {
+      id: 'print',
+      kind: 'math.output',
+      position: { x: 560, y: 70 },
+      config: { label: 'result' },
+    },
+  ],
+  edges: [
+    { id: 'e1', source: 'a', target: 'sum', targetHandle: 'a' },
+    { id: 'e2', source: 'b', target: 'sum', targetHandle: 'b' },
+    { id: 'e3', source: 'sum', target: 'print' },
+  ],
+};

package/src/components/Workflow/useWorkflowIssueMessage.test.ts

@@ -0,0 +1,101 @@
+import { createElement, type ReactNode } from 'react';
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { emptyGraph } from './graphReducer';
+import { useWorkflowIssueMessage } from './useWorkflowIssueMessage';
+import type { Issue, WorkflowTranslate } from './Workflow.types';
+import { WorkflowProvider } from './WorkflowContext';
+
+/**
+ * The hook is domain-free: it maps an issue's `code` to a deterministic
+ * `workflow_be_<code>` key and resolves it through the host-injected
+ * translator, falling back to the raw `issue.message` when the host has no
+ * matching key. These tests inject a stub translator that mimics the common
+ * "return the key when it's missing" contract, so they assert the mapping /
+ * normalization / fallback behavior without depending on any host catalog.
+ */
+const CATALOG: Record<string, string> = {
+  workflow_be_agent_model_required: 'Pick a model for the agent.',
+  workflow_be_cycle_detected: 'The graph has a cycle.',
+  workflow_be_if_else_input_attribute_unknown:
+    'Unknown attribute {invalidPath}; try {suggestedPath}.',
+};
+
+const translate: WorkflowTranslate = (key, vars) => {
+  const template = CATALOG[key];
+  if (template === undefined) return key; // mirror "missing key → key"
+  return template.replace(/\{(\w+)\}/g, (_, name) =>
+    String(vars?.[name] ?? `{${name}}`)
+  );
+};
+
+const wrapper = ({ children }: { children: ReactNode }) =>
+  createElement(
+    WorkflowProvider,
+    {
+      graph: emptyGraph,
+      dispatch: () => {},
+      undo: () => {},
+      redo: () => {},
+      canUndo: false,
+      canRedo: false,
+      nodeTypes: {},
+      translate,
+      issues: [],
+    },
+    children
+  );
+
+const renderResolver = () =>
+  renderHook(() => useWorkflowIssueMessage(), { wrapper }).result;
+
+describe('useWorkflowIssueMessage', () => {
+  it('resolves the workflow_be_<code> key via the injected translator', () => {
+    const result = renderResolver();
+    const issue: Issue = {
+      severity: 'error',
+      code: 'agent_model_required',
+      message: 'RAW_BE_FALLBACK',
+    };
+    expect(result.current(issue)).toBe('Pick a model for the agent.');
+    expect(result.current(issue)).not.toBe('RAW_BE_FALLBACK');
+  });
+
+  it('falls back to issue.message for an unknown code', () => {
+    const result = renderResolver();
+    const issue: Issue = {
+      severity: 'error',
+      code: 'totally_unknown_code',
+      message: 'RAW_BE_FALLBACK',
+    };
+    expect(result.current(issue)).toBe('RAW_BE_FALLBACK');
+  });
+
+  it('normalizes a dotted/uppercased code to the snake_case key', () => {
+    const result = renderResolver();
+    const issue: Issue = {
+      severity: 'error',
+      code: 'CYCLE.DETECTED',
+      message: 'RAW_BE_FALLBACK',
+    };
+    expect(result.current(issue)).toBe('The graph has a cycle.');
+  });
+
+  it('interpolates messageVars into the resolved copy', () => {
+    const result = renderResolver();
+    const issue: Issue = {
+      severity: 'error',
+      code: 'if_else_input_attribute_unknown',
+      message: 'RAW_BE_FALLBACK',
+      messageVars: {
+        invalidPath: 'input.answer',
+        suggestedPath: 'input.parsed.answer',
+      },
+    };
+    const message = result.current(issue);
+    expect(message).toContain('input.answer');
+    expect(message).toContain('input.parsed.answer');
+    expect(message).not.toBe('RAW_BE_FALLBACK');
+  });
+});

package/src/components/Workflow/useWorkflowIssueMessage.ts

@@ -0,0 +1,49 @@
+'use client';
+
+import { useCallback } from 'react';
+
+import type { Issue } from './Workflow.types';
+import { useWorkflowTranslate } from './WorkflowContext';
+
+/**
+ * Maps backend workflow validation issue codes to translated messages.
+ * Mirrors the connectors error-message hook precedent
+ * (`useConnectorErrorMessage`): the backend owns validation and returns raw
+ * English in `Issue.message` (kept as a fallback for tests / logs), while
+ * rendering surfaces resolve the localized copy here.
+ *
+ * Node kind names (Agent, Classify, etc.) are intentionally kept in English
+ * across the UI; issues that interpolate them pass the raw `def.label` string
+ * in `messageVars`, and Korean sentences read naturally with the
+ * mixed-language token (e.g. "Agent는 최소 1개 이상 필요합니다").
+ */
+export const useWorkflowIssueMessage = () => {
+  const translate = useWorkflowTranslate();
+
+  return useCallback(
+    (issue: Issue): string => {
+      // Coerce all interpolation values to strings — `useTranslate`
+      // returns a React-element array when a numeric var is passed,
+      // which loses its string-ness through the `as string` cast and
+      // breaks downstream code that joins or trims the message.
+      const vars = issue.messageVars
+        ? Object.fromEntries(
+            Object.entries(issue.messageVars).map(([k, v]) => [k, String(v)])
+          )
+        : undefined;
+      const t = (key: string) => translate(key, vars) as string;
+      // Backend (`INVALID_GRAPH`) issues arrive with the validator's own
+      // snake_case `code` (e.g. `agent_model_required`), localized under a
+      // deterministic `workflow_be_<code>` key. Normalize defensively so a
+      // dotted/uppercased variant still resolves. `useTranslate` returns the
+      // key itself when no entry exists, so a missing key falls back to the
+      // raw English `issue.message`.
+      const beKey = `workflow_be_${issue.code
+        .toLowerCase()
+        .replace(/[.-]/g, '_')}`;
+      const beMessage = t(beKey);
+      return beMessage === beKey ? issue.message : beMessage;
+    },
+    [translate]
+  );
+};

package/src/components/Workflow/useWorkflowKeyboard.ts

@@ -0,0 +1,126 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+import { cloneNode } from './createNode';
+import type { GraphNode } from './Workflow.types';
+import { useWorkflow } from './WorkflowContext';
+
+/**
+ * True while a keystroke is being typed into a form field. Graph-level
+ * shortcuts must yield so the field keeps normal text editing — including
+ * its own native undo.
+ */
+const isEditingText = (target: EventTarget | null): boolean => {
+  if (!(target instanceof HTMLElement)) return false;
+  return (
+    target.tagName === 'INPUT' ||
+    target.tagName === 'TEXTAREA' ||
+    target.isContentEditable
+  );
+};
+
+/**
+ * Keyboard shortcuts for the workflow editor: undo/redo, copy/paste and
+ * duplicate of the selected node, Delete/Backspace to remove the selected node
+ * OR edge, and Escape to close the inspector. No-ops in read-only mode (the
+ * Behavior-tab preview). React Flow's own Delete/Backspace binding still fires
+ * for canvas-focused selections; this mirrors it so a selection made elsewhere
+ * (e.g. via the inspector) is still removable.
+ */
+export function useWorkflowKeyboard(): void {
+  const {
+    undo,
+    redo,
+    readOnly,
+    graph,
+    dispatch,
+    editor,
+    getNodeType,
+    setDrawerTarget,
+    setSelectedNodeId,
+    setSelectedEdgeId,
+  } = useWorkflow();
+  const clipboardRef = useRef<GraphNode | null>(null);
+  const selectedNodeId = editor.selectedNodeId;
+  const selectedEdgeId = editor.selectedEdgeId;
+
+  useEffect(() => {
+    if (readOnly) return;
+
+    const pickSelected = (): GraphNode | null => {
+      const node = graph.nodes.find((n) => n.id === selectedNodeId);
+      if (!node || getNodeType(node.kind)?.placement?.pinned) return null;
+      return node;
+    };
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      // Text-editing shortcuts belong to the focused field, not the graph.
+      if (isEditingText(e.target)) return;
+
+      if (e.key === 'Escape') {
+        setDrawerTarget(null);
+        setSelectedNodeId(null);
+        setSelectedEdgeId(null);
+        return;
+      }
+
+      if (e.key === 'Delete' || e.key === 'Backspace') {
+        // Delete a selected edge (node deletion stays with React Flow's own
+        // binding, which also clears edges attached to the removed node).
+        if (
+          selectedEdgeId &&
+          graph.edges.some((ed) => ed.id === selectedEdgeId)
+        ) {
+          dispatch({ type: 'deleteEdge', id: selectedEdgeId });
+          setSelectedEdgeId(null);
+          setDrawerTarget(null);
+        }
+        return;
+      }
+
+      if (!e.metaKey && !e.ctrlKey) return;
+      const key = e.key.toLowerCase();
+
+      if (key === 'z') {
+        e.preventDefault();
+        if (e.shiftKey) redo();
+        else undo();
+      } else if (key === 'y') {
+        e.preventDefault();
+        redo();
+      } else if (key === 'c') {
+        const node = pickSelected();
+        if (node) clipboardRef.current = node;
+      } else if (key === 'v') {
+        e.preventDefault();
+        if (clipboardRef.current) {
+          dispatch({
+            type: 'addNode',
+            node: cloneNode(clipboardRef.current, graph.nodes),
+          });
+        }
+      } else if (key === 'd') {
+        e.preventDefault();
+        const node = pickSelected();
+        if (node)
+          dispatch({ type: 'addNode', node: cloneNode(node, graph.nodes) });
+      }
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [
+    undo,
+    redo,
+    readOnly,
+    graph,
+    dispatch,
+    selectedNodeId,
+    selectedEdgeId,
+    getNodeType,
+    setDrawerTarget,
+    setSelectedNodeId,
+    setSelectedEdgeId,
+  ]);
+}

package/src/index.ts

@@ -88,6 +88,7 @@ export * from './components/Tag';
 export * from './components/Textarea';
 export * from './components/Toast';
 export * from './components/Tooltip';
+export * from './components/Workflow';
 // Typography Components (excluding Link to avoid conflict with Link component)
 export {
   H1,

package/src/test-support/setup.ts

@@ -0,0 +1,11 @@
+/**
+ * Vitest test setup — loaded before the suite runs.
+ */
+
+import '@testing-library/jest-dom/vitest';
+
+// jsdom doesn't implement element scrolling; canvas components that autoscroll
+// (e.g. focusing a field) call scrollTo on container elements in tests.
+if (!Element.prototype.scrollTo) {
+  Element.prototype.scrollTo = () => {};
+}

package/src/theme/SemanticTokens.mdx

@@ -34,7 +34,7 @@ primitive depending on the active color mode.
 Two payoffs:
 
 1. **Dark mode for free.** Add `color="fg.default"` and it's `gray.1300` in
-   light and `gray.50` in dark — no `useColorMode`, no conditionals.
+   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.
 
@@ -49,21 +49,38 @@ have no semantic meaning.
 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.default` | `gray.1300` | `gray.200` | Primary text, headings, icons |
-| `fg.muted` | `gray.900` | `gray.300` | Secondary text, captions, supporting icons |
-| `fg.subtle` | `gray.700` | `gray.600` | Tertiary text, placeholders, disabled-ish labels |
+| `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) |
@@ -86,6 +103,30 @@ between a light and a dark value.
 </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
@@ -110,6 +151,18 @@ flips in dark mode:
 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
@@ -119,9 +172,10 @@ the nearest semantic token:
 
 | Was (primitive) | Use (semantic) |
 | --- | --- |
-| `gray.1000`–`gray.1500` as text | `fg.default` |
-| `gray.800`–`gray.900` as text | `fg.muted` |
-| `gray.500`–`gray.700` as text/icon | `fg.subtle` |
+| `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` |