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

package/src/components/Workflow/canvas/GraphErrorBanner/GraphErrorBanner.tsx

@@ -167,7 +167,7 @@ export function GraphErrorBanner({
       maxW="md"
       bg="bg.surface"
       borderWidth="1px"
-      borderColor={errorCount > 0 ? 'danger.main' : 'warning.main'}
+      borderColor={errorCount > 0 ? 'danger.border' : 'warning.border'}
       borderRadius="md"
       boxShadow="sm"
       overflow="hidden"
@@ -178,12 +178,12 @@ export function GraphErrorBanner({
           gap={2}
           px={3}
           py={2}
-          bg="slate.50"
+          bg="bg.subtle"
           borderBottomWidth="1px"
-          borderColor="slate.200"
+          borderColor="border.default"
         >
           <Spinner size="xs" />
-          <Subtext fontWeight="semibold" color="slate.1100">
+          <Subtext fontWeight="semibold" color="fg.default">
             {translate('workflow_issues_validating') as string}
           </Subtext>
         </Flex>
@@ -205,12 +205,12 @@ export function GraphErrorBanner({
         transitionProperty="opacity"
         onClick={() => setOpen((o) => !o)}
       >
-        <Text fontSize="sm" fontWeight="semibold" color="slate.1300">
+        <Text fontSize="sm" fontWeight="semibold" color="fg.default">
           {summarize(errorCount, warningCount)}
         </Text>
         <ChevronDownIcon
           boxSize="xs"
-          color="slate.900"
+          color="fg.icon"
           transform={open ? 'rotate(180deg)' : 'none'}
           animationStyle="feedback"
           transitionProperty="transform"
@@ -226,27 +226,27 @@ export function GraphErrorBanner({
           animationStyle="feedback"
           transitionProperty="opacity"
           borderTopWidth="1px"
-          borderColor="slate.200"
+          borderColor="border.default"
         >
           {groups.map((group, gi) => (
             <Box
               key={group.key}
               borderTopWidth={gi === 0 ? 0 : '1px'}
-              borderColor="slate.200"
+              borderColor="border.default"
             >
               <Flex
                 align="center"
                 gap={2}
                 px={3}
                 py={1.5}
-                bg="slate.50"
+                bg="bg.subtle"
                 cursor={group.node ? 'pointer' : 'default'}
-                _hover={group.node ? { bg: 'slate.100' } : undefined}
+                _hover={group.node ? { bg: 'primary.wash' } : undefined}
                 onClick={group.node ? () => jumpToNode(group.key) : undefined}
               >
                 {group.def?.icon ? (
                   <Box
-                    color="slate.1100"
+                    color="fg.default"
                     display="flex"
                     alignItems="center"
                     flexShrink={0}
@@ -254,7 +254,7 @@ export function GraphErrorBanner({
                     <group.def.icon boxSize="xs" />
                   </Box>
                 ) : null}
-                <Subtext fontWeight="semibold" color="slate.1300" truncate>
+                <Subtext fontWeight="semibold" color="fg.default" truncate>
                   {group.node
                     ? getNodeTitle(group.node, group.def)
                     : translate('workflow_drawer_graph_group_title')}

package/src/components/Workflow/canvas/IconTile/IconTile.styles.ts

@@ -3,29 +3,45 @@ import type { CategoryTokenMap, CategoryTokens } from './IconTile.types';
 
 /**
  * Default mapping from the six categories to logician-ui semantic color
- * tokens. "fg" tints the icon, "bg" fills the tile background. Output and
- * Note don't map cleanly to a `colorPalette` so they're spelled out with
- * raw token pairs.
+ * tokens. "fg" tints the icon, "bg" fills the tile background.
+ *
+ * 5.0: category tiles are decorative, not status — so five of the six pick a
+ * `category.*` hue (purely for visual grouping, swap-able via `categoryTokens`
+ * without implying anything is wrong/warning/safe) instead of borrowing
+ * `success`/`danger`/`secondary`, which are status/brand families with their
+ * own meaning elsewhere in the same canvas. `output` has no obvious hue, so
+ * it gets the documented neutral pair (`primary.wash` + `fg.default`) instead
+ * of inventing a 13th hue. `note` keeps a real `warning.*` triple — unlike the
+ * others it already reads as "a note needs your attention", which IS a status
+ * meaning, so it stays on the status family rather than moving to a hue.
  *
  * Host apps that want to retheme can override the map via the
  * `categoryTokens` prop on `<Workflow>` — see WorkflowContext.
  */
 export const DEFAULT_CATEGORY_TOKENS: CategoryTokenMap = {
   trigger: {
-    bg: 'success.lightest',
-    fg: 'success.main',
-    border: 'slate.300',
+    bg: 'category.green.surface',
+    fg: 'category.green.fg',
+    border: 'border.default',
+  },
+  ai: {
+    bg: 'category.purple.surface',
+    fg: 'category.purple.fg',
+    border: 'border.default',
   },
-  ai: { bg: 'primary.lightest', fg: 'primary.main', border: 'slate.300' },
   logic: {
-    bg: 'secondary.lightest',
-    fg: 'secondary.main',
-    border: 'slate.300',
+    bg: 'category.brown.surface',
+    fg: 'category.brown.fg',
+    border: 'border.default',
+  },
+  safety: {
+    bg: 'category.red.surface',
+    fg: 'category.red.fg',
+    border: 'border.default',
   },
-  safety: { bg: 'danger.lightest', fg: 'danger.main', border: 'slate.300' },
-  output: { bg: 'slate.50', fg: 'slate.1200', border: 'slate.300' },
+  output: { bg: 'primary.wash', fg: 'fg.default', border: 'border.default' },
   // Note's `border` doubles as the body border so it reads as warm, not gray.
-  note: { bg: 'warning.lightest', fg: 'warning.dark', border: 'warning.light' },
+  note: { bg: 'warning.bg', fg: 'warning.fg', border: 'warning.border' },
 };
 
 /**

package/src/components/Workflow/canvas/IssueList/IssueList.tsx

@@ -58,7 +58,7 @@ export function IssueList({
           py={1.5}
           align="center"
           cursor={onIssueClick ? 'pointer' : undefined}
-          _hover={onIssueClick ? { bg: 'slate.50' } : undefined}
+          _hover={onIssueClick ? { bg: 'primary.wash' } : undefined}
           onClick={
             onIssueClick
               ? (e) => {
@@ -72,9 +72,9 @@ export function IssueList({
             w="3px"
             flexShrink={0}
             borderRadius="full"
-            bg={severityColorToken(issue.severity)}
+            bg={severityColorToken(issue.severity, 'solid')}
           />
-          <Text fontSize="sm" color="slate.1200">
+          <Text fontSize="sm" color="fg.default">
             {resolveMessage ? resolveMessage(issue) : issue.message}
           </Text>
         </Flex>

package/src/components/Workflow/canvas/NodePalette/NodePalette.tsx

@@ -70,16 +70,16 @@ function PaletteItem({ def }: { def: NodeTypeDef }) {
           tokens={categoryTokens}
         />
         <Stack gap={0} flex={1} minWidth={0}>
-          <Subtext fontWeight="semibold" color="slate.1200" lineClamp={1}>
+          <Subtext fontWeight="semibold" color="fg.default" lineClamp={1}>
             {def.label}
           </Subtext>
           {description ? (
-            <Subtext color="slate.900" lineClamp={1}>
+            <Subtext color="fg.muted" lineClamp={1}>
               {description}
             </Subtext>
           ) : null}
         </Stack>
-        <Box color="slate.700" display="flex" alignItems="center">
+        <Box color="fg.icon" display="flex" alignItems="center">
           <GripVerticalIcon boxSize="xs" />
         </Box>
       </HStack>
@@ -148,16 +148,15 @@ export function NodePalette({ onClose }: { onClose: () => void }) {
         px={4}
         py={3}
         borderBottom="1px solid"
-        borderColor="slate.200"
+        borderColor="border.default"
       >
-        <Subtitle id={titleId} color="slate.1300">
+        <Subtitle id={titleId} color="fg.default">
           {translate('workflow_palette_title')}
         </Subtitle>
         <IconButton
           aria-label={translate('workflow_palette_close') as string}
           size="xs"
           variant="ghost"
-          colorPalette="neutral"
           onClick={onClose}
         >
           <CloseIcon boxSize="xs" aria-hidden />
@@ -169,7 +168,7 @@ export function NodePalette({ onClose }: { onClose: () => void }) {
             <Stack key={category} gap={2}>
               <Subtext
                 fontWeight="bold"
-                color="slate.900"
+                color="fg.muted"
                 textTransform="uppercase"
                 letterSpacing="wider"
                 pl={1}

package/src/components/Workflow/canvas/NodePalette/NodePaletteToggle.tsx

@@ -25,8 +25,7 @@ export function NodePaletteToggle({ onOpen }: { onOpen: () => void }) {
         <IconButton
           aria-label={label}
           size="md"
-          variant="outline"
-          colorPalette="neutral"
+          variant="secondary"
           bg="bg.surface"
           boxShadow="md"
           onClick={onOpen}

package/src/components/Workflow/canvas/NodeShell/NodeShell.styles.ts

@@ -1,3 +1,4 @@
+import { CANVAS_STROKE_TOKEN, colorVar } from '../colorVar';
 import type { PortStyle } from './NodeShell.types';
 
 export const CARD_WIDTH = '174px';
@@ -44,17 +45,14 @@ export const MAX_META_CHIPS = 4;
 
 /**
  * React Flow `<Handle>` takes inline SVG-style props rather than Chakra
- * tokens, so port colors are spelled as CSS vars from the theme.
+ * tokens, so port colors are spelled as CSS vars from the theme (`colorVar`).
+ * The ring uses the same stroke token as the edges it terminates.
  */
-function colorVar(token: string): string {
-  return `var(--chakra-colors-${token.replace(/\./g, '-')})`;
-}
-
 export const PORT_STYLE: PortStyle = {
   width: 8,
   height: 8,
   background: colorVar('bg.surface'),
-  border: `1.5px solid ${colorVar('slate.700')}`,
+  border: `1.5px solid ${colorVar(CANVAS_STROKE_TOKEN)}`,
 };
 
 /**
@@ -79,6 +77,6 @@ export const metaChipStyles = {
  */
 export const metaChipToneStyles = {
   default: {},
-  danger: { bg: 'danger.lightest', color: 'danger.dark' },
-  warning: { bg: 'warning.lightest', color: 'warning.dark' },
+  danger: { bg: 'danger.bg', color: 'danger.fg' },
+  warning: { bg: 'warning.bg', color: 'warning.fg' },
 } as const;

package/src/components/Workflow/canvas/NodeShell/NodeShell.test.tsx

@@ -0,0 +1,79 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render } from '@testing-library/react';
+import { ReactFlowProvider } from '@xyflow/react';
+import { describe, expect, it } from 'vitest';
+
+import type { CreatedIcon } from '@/components/Icon';
+
+import { system } from '../../../../theme';
+import type { RunState } from '../../Workflow.types';
+import { NodeShell } from './NodeShell';
+import type { NodeShellProps } from './NodeShell.types';
+
+// SVG icons resolve to data URLs under vitest; the shell only needs something
+// renderable.
+const StubIcon = (() => null) as unknown as CreatedIcon;
+
+function renderShell(props: Partial<NodeShellProps>) {
+  const { container } = render(
+    <ChakraProvider value={system}>
+      <ReactFlowProvider>
+        <NodeShell
+          label="Agent"
+          category="ai"
+          icon={StubIcon}
+          selected={false}
+          runState="idle"
+          issues={[]}
+          inputs={[]}
+          outputs={[]}
+          {...props}
+        />
+      </ReactFlowProvider>
+    </ChakraProvider>
+  );
+  return container.firstElementChild as HTMLElement;
+}
+
+/** jsdom keeps the `outline` shorthand as written and does not expand it. */
+const ringOf = (el: HTMLElement) => {
+  const cs = getComputedStyle(el);
+  return { outline: cs.outline, outlineColor: cs.outlineColor };
+};
+const SELECTION_RING = {
+  outline: '1px solid',
+  outlineColor: 'var(--chakra-colors-primary-main)',
+};
+
+/**
+ * Selection must stay visible on top of the run-result chrome: after a run
+ * every node is done or failed, and a clicked node with no ring gives the
+ * reader no cue for which node the inspector is showing.
+ */
+describe('NodeShell selection ring', () => {
+  it.each<RunState>(['idle', 'done', 'error'])(
+    'a selected node in runState %s has an outline',
+    (runState) => {
+      expect(ringOf(renderShell({ selected: true, runState }))).toEqual(
+        SELECTION_RING
+      );
+    }
+  );
+
+  it('a selected node with a validation error has an outline', () => {
+    const card = renderShell({
+      selected: true,
+      issues: [{ severity: 'error', code: 'invalid', message: 'bad' }],
+    });
+    expect(ringOf(card)).toEqual(SELECTION_RING);
+  });
+
+  it.each<RunState>(['idle', 'done', 'error'])(
+    'an unselected node in runState %s has no outline',
+    (runState) => {
+      expect(ringOf(renderShell({ selected: false, runState })).outline).toBe(
+        ''
+      );
+    }
+  );
+});

package/src/components/Workflow/canvas/NodeShell/NodeShell.tsx

@@ -60,12 +60,25 @@ function normalizeChip(spec: MetaChipSpec): {
 }
 
 /**
- * Ring + body-border treatment per state. Notes keep their warm border in
- * all states but still surface the primary ring when selected so the active
+ * Ring + body treatment per state. Notes keep their warm border in all
+ * states but still surface the primary ring when selected so the active
  * annotation is visible.
  *
- * Precedence for the ring color: running > error > selected > warning.
- * The default-case border is `slate.300`.
+ * Two independent layers:
+ *
+ * - Status chrome (border + body), by precedence running > failed (run error
+ *   or a validation issue) > completed > warning > default. Failed and
+ *   completed tint the whole card with the status colour
+ *   (`danger.bg`/`success.bg`) so the result still reads at a glance once the
+ *   selection moves on. A node's own validation issues (`hasError`) get the
+ *   same failed treatment as a runtime error (`runState === 'error'`) — both
+ *   mean "something is wrong with this node". The default border is
+ *   `border.default`.
+ * - Selection: a 1px `primary.main` outline, added on top of whatever status
+ *   chrome the node has. After a run every node is done or failed, so if
+ *   status replaced selection a clicked node would show no cue at all. Running
+ *   wears the same outline — both mean "this is the node in focus". On a
+ *   plain or warning node selection also takes the border, as before.
  */
 function getRingChrome(
   category: NodeCategory,
@@ -75,45 +88,38 @@ function getRingChrome(
   runState: RunState,
   noteBorder: string
 ): RingChrome {
+  const selectionRing = selected
+    ? { outline: '1px solid', outlineColor: 'primary.main' }
+    : {};
   if (category === 'note') {
-    if (selected) {
-      return {
-        borderColor: noteBorder,
-        outline: '3px solid',
-        outlineColor: 'primary.lighter',
-      };
-    }
-    return { borderColor: noteBorder };
+    return { borderColor: noteBorder, ...selectionRing };
   }
   if (runState === 'running') {
     return {
       borderColor: 'primary.main',
-      outline: '3px solid',
-      outlineColor: 'primary.lighter',
+      outline: '1px solid',
+      outlineColor: 'primary.main',
     };
   }
-  if (hasError) {
-    return {
-      borderColor: 'danger.main',
-      outline: '3px solid',
-      outlineColor: 'danger.lighter',
-    };
+  if (runState === 'error' || hasError) {
+    return { borderColor: 'danger.border', bg: 'danger.bg', ...selectionRing };
   }
-  if (selected) {
+  if (runState === 'done') {
     return {
-      borderColor: 'primary.main',
-      outline: '3px solid',
-      outlineColor: 'primary.lighter',
+      borderColor: 'success.border',
+      bg: 'success.bg',
+      ...selectionRing,
     };
   }
-  if (hasWarning) return { borderColor: 'warning.main' };
-  return { borderColor: 'slate.300' };
+  if (selected) return { borderColor: 'primary.main', ...selectionRing };
+  if (hasWarning) return { borderColor: 'warning.border' };
+  return { borderColor: 'border.default' };
 }
 
 /**
  * Header glyph independently selected from the ring. Error wins over
  * warning wins over running's status dot — so an error inside a running
- * node still surfaces the alert, instead of being hidden by the green
+ * node still surfaces the alert, instead of being hidden by the primary
  * dot.
  */
 function getHeaderBadge(
@@ -123,26 +129,29 @@ function getHeaderBadge(
 ): ReactNode {
   if (hasError) {
     return (
-      <Box color="danger.main" display="flex" alignItems="center">
+      <Box color="danger.fg" display="flex" alignItems="center">
         <AlertTriangleIcon boxSize="xs" />
       </Box>
     );
   }
   if (hasWarning) {
     return (
-      <Box color="warning.dark" display="flex" alignItems="center">
+      <Box color="warning.fg" display="flex" alignItems="center">
         <AlertTriangleIcon boxSize="xs" />
       </Box>
     );
   }
   if (runState === 'running') {
+    // Matches the ring colour (`primary.main`) rather than `success.*` — a
+    // green "running" dot read as a false "done" signal sitting right next
+    // to the real completed state's green card fill.
     return (
       <Box
         boxSize="2.5"
         borderRadius="full"
-        bg="success.main"
+        bg="primary.main"
         outline="3px solid"
-        outlineColor="success.lighter"
+        outlineColor="primary.wash"
       />
     );
   }
@@ -205,7 +214,7 @@ export function NodeShell({
       outline={ring.outline}
       outlineColor={ring.outlineColor}
       boxShadow="sm"
-      bg={isNote ? tokens.bg : 'bg.surface'}
+      bg={isNote ? tokens.bg : (ring.bg ?? 'bg.surface')}
       position="relative"
       // Center the body within the port-driven min-height so a content-light
       // node (e.g. Start) sits mid-card rather than pinned to the top edge.
@@ -217,18 +226,18 @@ export function NodeShell({
         <Stack gap={1} px={3} py={2}>
           <HStack
             gap={1}
-            color="warning.dark"
+            color="warning.fg"
             fontWeight="bold"
             letterSpacing="wider"
             textTransform="uppercase"
           >
             <StickyNoteIcon boxSize="xs" />
-            <Subtext color="warning.dark" fontWeight="bold">
+            <Subtext color="warning.fg" fontWeight="bold">
               Note
             </Subtext>
           </HStack>
           {customBody ?? (
-            <Subtext color="slate.1200" lineHeight={1.45}>
+            <Subtext color="fg.default" lineHeight={1.45}>
               {instanceTitle ?? label}
             </Subtext>
           )}
@@ -248,11 +257,11 @@ export function NodeShell({
                 tokens={categoryTokens}
               />
               <Stack gap={0} flex={1} minWidth={0}>
-                <Subtext fontWeight="semibold" color="slate.1200" lineClamp={1}>
+                <Subtext fontWeight="semibold" color="fg.default" lineClamp={1}>
                   {label}
                 </Subtext>
                 {instanceTitle ? (
-                  <Subtext color="slate.900" lineClamp={1}>
+                  <Subtext color="fg.muted" lineClamp={1}>
                     {instanceTitle}
                   </Subtext>
                 ) : null}

package/src/components/Workflow/canvas/NodeShell/NodeShell.types.ts

@@ -40,6 +40,8 @@ export type RingChrome = {
   borderColor: string;
   outline?: string;
   outlineColor?: string;
+  /** Card background override for a status fill (failed/completed). */
+  bg?: string;
 };
 
 export type PortStyle = CSSProperties;

package/src/components/Workflow/canvas/SeverityDot/SeverityDot.tsx

@@ -8,17 +8,18 @@ import { severityColorToken } from '../issueSeverity';
 interface SeverityDotProps extends BoxProps {
   severity: IssueSeverity;
   /**
-   * Shade of the severity colour. `dark` reads better as a small marker on a
-   * tinted callout background; `main` suits a header dot on white. Defaults to
-   * `main`.
+   * Which half of the status family fills the dot. `fg` reads better as a
+   * small marker on a tinted callout background (it's tuned to work on
+   * `.bg` too); `solid` suits a header dot on a plain surface. Defaults to
+   * `solid`.
    */
-  tone?: 'main' | 'dark';
+  tone?: 'solid' | 'fg';
 }
 
 /** Small round severity marker shared by the issue callout and the issue list. */
 export function SeverityDot({
   severity,
-  tone = 'main',
+  tone = 'solid',
   ...rest
 }: SeverityDotProps) {
   return (

package/src/components/Workflow/canvas/canvasStroke.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+
+import { SCHEMES } from '../../../theme/palette.generated';
+import { defaultEdgeOptions } from './Canvas/Canvas.styles';
+import { colorVar } from './colorVar';
+import { PORT_STYLE } from './NodeShell/NodeShell.styles';
+
+/**
+ * Edges, arrowheads and port rings are non-text marks: they need ≥ 3:1
+ * (≥ 4.5:1 in high contrast, as in src/theme/contrast.test.ts) against every
+ * surface they sit on. The colour is read back out of the shipped styles, so
+ * the test follows whatever token the canvas actually paints.
+ */
+
+type Mode = 'light' | 'dark' | 'hcLight' | 'hcDark';
+const MODES: Mode[] = ['light', 'dark', 'hcLight', 'hcDark'];
+const SURFACES = ['bg-canvas', 'bg-surface', 'bg-subtle', 'primary-wash'];
+
+const lum = (h: string) => {
+  const c = [1, 3, 5]
+    .map((i) => parseInt(h.slice(i, i + 2), 16) / 255)
+    .map((x) => (x <= 0.03928 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+};
+const ratio = (a: string, b: string) => {
+  const x = lum(a);
+  const y = lum(b);
+  return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05);
+};
+
+const kebab = (flat: string) =>
+  flat.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
+/** `var(--chakra-colors-fg-icon)` → the SCHEMES value for that role. */
+function resolveVar(
+  css: string,
+  table: Record<string, string>
+): string | undefined {
+  const name = /var\(--chakra-colors-([a-z0-9-]+)\)/.exec(css)?.[1];
+  const key = Object.keys(table).find((k) => kebab(k) === name);
+  return key ? table[key] : undefined;
+}
+
+const STROKES: [string, string][] = [
+  ['edge stroke', String(defaultEdgeOptions.style?.stroke)],
+  [
+    'arrowhead',
+    String(
+      (defaultEdgeOptions.markerEnd as { color?: string } | undefined)?.color
+    ),
+  ],
+  ['port ring', String(PORT_STYLE.border)],
+];
+
+describe('colorVar', () => {
+  it('kebab-cases camelCase segments the way Chakra emits them', () => {
+    expect(colorVar('fg.onPrimary')).toBe('var(--chakra-colors-fg-on-primary)');
+    expect(colorVar('primary.washActive')).toBe(
+      'var(--chakra-colors-primary-wash-active)'
+    );
+    expect(colorVar('bg.surface')).toBe('var(--chakra-colors-bg-surface)');
+  });
+});
+
+describe.each(Object.keys(SCHEMES) as (keyof typeof SCHEMES)[])(
+  'canvas strokes — %s scheme',
+  (scheme) => {
+    it.each(MODES)('clear non-text contrast on every surface in %s', (mode) => {
+      const table = SCHEMES[scheme][mode] as Record<string, string>;
+      const need = mode.startsWith('hc') ? 4.5 : 3;
+      const failures = STROKES.flatMap(([what, css]) => {
+        const fg = resolveVar(css, table);
+        if (!fg) return [`${what}: ${css} names no role token`];
+        return SURFACES.flatMap((bg) => {
+          const c = ratio(fg, table[bg]);
+          return c >= need - 1e-9
+            ? []
+            : [`${what} (${css}) on ${bg}: ${c.toFixed(2)} < ${need}`];
+        });
+      });
+      expect(failures).toEqual([]);
+    });
+  }
+);

package/src/components/Workflow/canvas/colorVar.ts

@@ -0,0 +1,26 @@
+/**
+ * Token path → the CSS variable Chakra emits for it, for the React Flow props
+ * (`<Handle style>`, edge `style` / `markerEnd`) that take raw CSS rather than
+ * Chakra tokens. Chakra kebab-cases every segment, so `fg.onPrimary` is
+ * `--chakra-colors-fg-on-primary`; swapping only the dots would name a
+ * variable that never exists and the declaration would silently fall back.
+ */
+export function colorVar(token: string): string {
+  const name = token
+    .split('.')
+    .map((segment) => segment.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`))
+    .join('-');
+  return `var(--chakra-colors-${name})`;
+}
+
+/**
+ * Colour of the canvas's structural strokes — edges, arrowheads and port
+ * rings. These are the only marks that say what connects to what, so they are
+ * non-text graphics and need ≥ 3:1 against every surface they sit on
+ * (`primary.wash` canvas, `bg.subtle` read-only canvas, `bg.canvas` in dark,
+ * `bg.surface` behind a port). `border.strong` is a separator (~1.7:1 on the
+ * wash) and fails that; `fg.icon` is the role for non-text marks and clears it
+ * in every mode (see `canvasStroke.test.ts`). 4.x drew these in `slate.700`,
+ * which deprecatedColorTokens.json maps to `neutral.8` — the same job.
+ */
+export const CANVAS_STROKE_TOKEN = 'fg.icon';