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

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

@@ -29,14 +29,16 @@ export const pickPrimaryIssue = (issues: Issue[]): Issue | null => {
 
 /**
  * Semantic color token for an issue severity — shared across issue list UIs.
- * `tone` selects the shade: the default `'main'` for text/icons, or `'dark'`
- * where `.main` is too light to read (e.g. the small list-bullet markers in
- * drawer issue callouts, which need extra contrast against the tinted bg).
+ * `role` selects which half of the status family: the default `'fg'` for
+ * text, icons and borders (it's tuned to read on both `bg.*` and the plain
+ * canvas, which is the 4.x two-tone `main`/`dark` split collapsed into one
+ * token), or `'solid'` for an actually-filled shape (a dot, a bar) that
+ * needs the stronger fill colour `.onSolid` text is designed to sit on.
  */
 export const severityColorToken = (
   severity: IssueSeverity,
-  tone: 'main' | 'dark' = 'main'
-): string => (severity === 'error' ? `danger.${tone}` : `warning.${tone}`);
+  role: 'fg' | 'solid' = 'fg'
+): string => (severity === 'error' ? `danger.${role}` : `warning.${role}`);
 
 /**
  * Tinted callout styling (bg / border / text) for an issue severity. Reuses the

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

@@ -7,5 +7,5 @@
  */
 export const workflowLabelProps = {
   fontWeight: 'semibold',
-  color: 'slate.1300',
+  color: 'fg.default',
 } as const;

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

@@ -77,7 +77,7 @@ export const CustomSelectionPanel: StoryFn<typeof Workflow> = () => {
       >
         <Subtitle>My own panel</Subtitle>
         <Subtext
-          color={selection ? undefined : 'slate.500'}
+          color={selection ? undefined : 'fg.subtle'}
           data-testid="selection-readout"
         >
           {selection
@@ -124,8 +124,7 @@ function AddAfterButton({ nodeId }: { nodeId: string }) {
     <IconButton
       aria-label={`Add after ${source.label}`}
       size="sm"
-      variant="solid"
-      colorPalette="primary"
+      variant="primary"
       borderRadius="full"
       onClick={() => addNode('math.add', { after: nodeId })}
     >
@@ -149,14 +148,14 @@ function TapPalette() {
       bg="bg.surface"
     >
       <Subtitle>Tap to add</Subtitle>
-      <Subtext color="slate.500" data-testid="add-target">
+      <Subtext color="fg.subtle" data-testid="add-target">
         {source ? `Connect after ${source.label}` : 'Add at the centre'}
       </Subtext>
       {Object.values(nodeTypes).map((def) => (
         <Button
           key={def.kind}
           size="sm"
-          variant="outline"
+          variant="secondary"
           onClick={() =>
             addNode(
               def.kind,

package/src/components/a11y.kwcag.test.tsx

@@ -2,7 +2,7 @@ import { render } from '@testing-library/react';
 import axe from 'axe-core';
 import { beforeAll, describe, expect, it } from 'vitest';
 
-import { buttonColorPaletteStyles } from '@/components/Button/Button.styles';
+import { buttonVariantStyles } from '@/components/Button/Button.styles';
 import { FileInput } from '@/components/FileInput';
 import { LogicianProvider } from '@/components/LogicianProvider';
 import { baseMarkdownComponents } from '@/components/Markdown/Markdown';
@@ -16,7 +16,8 @@ import {
 } from '@/components/Slider';
 import { TAB_RAMP } from '@/components/Tabs';
 import { Link, LINK_RAMP, Subtitle } from '@/components/Typography';
-import { colors } from '@/theme/colors';
+import { ROLE_TOKEN_PATHS } from '@/theme/colors';
+import { SCHEMES } from '@/theme/palette.generated';
 
 /**
  * Regressions for the accessibility defects a KWCAG 2.1 (한국형 웹 콘텐츠 접근성
@@ -243,7 +244,7 @@ describe('KWCAG 5.1.3.3 텍스트 콘텐츠의 명도 대비', () => {
     // dropped anything else — so a per-theme `{ base, _dark }`, which is the
     // documented way to fix a contrast problem, was silently replaced by the
     // default. Accepted by the type, discarded at runtime, no error either way.
-    const custom = { base: 'danger.main', _dark: 'danger.dark' };
+    const custom = { base: 'danger.solid', _dark: 'danger.fg' };
     const { container } = withProvider(
       <Link href="#" color={custom}>
         링크
@@ -336,62 +337,31 @@ describe('브랜드 색 대비 — Link · Tab 램프', () => {
     return (hi + 0.05) / (lo + 0.05);
   };
 
-  /** The canvas each mode's text is read against (`bg.surface`). */
-  const LIGHT_CANVAS = '#FFFFFF';
-  const DARK_CANVAS = '#181A20';
+  /** The surface each mode's text is read against (`bg.surface`, the raised one). */
+  const LIGHT_CANVAS = SCHEMES.ink.light['bg-surface'];
+  const DARK_CANVAS = SCHEMES.ink.dark['bg-surface'];
   const AA_BODY_TEXT = 4.5;
 
   /**
-   * Semantic token → raw hex, per mode. Only the steps this ramp uses; kept
-   * literal so the test breaks loudly if the semantic layer is re-pointed
-   * rather than silently measuring the wrong colour.
+   * Semantic token → shipped hex, per mode, read from the generated BAZE
+   * scheme table (the same values `src/theme/contrast.test.ts` pins the theme
+   * to). The ramps hold token NAMES, so this measures what the component reads.
    */
-  const RESOLVED: Record<string, { base: string; _dark: string }> = {
-    'primary.main': {
-      base: colors.blue[500].value,
-      _dark: colors.blue[300].value,
-    },
-    'primary.dark': {
-      base: colors.blue[700].value,
-      _dark: colors.blue[200].value,
-    },
-    'primary.darker': {
-      base: colors.blue[900].value,
-      _dark: colors.blue[100].value,
-    },
-    'danger.main': {
-      base: colors.rose[500].value,
-      _dark: colors.rose[300].value,
-    },
-    'danger.dark': {
-      base: colors.rose[700].value,
-      _dark: colors.rose[200].value,
-    },
-    'danger.darker': {
-      base: colors.rose[900].value,
-      _dark: colors.rose[100].value,
-    },
-    // The ink steps. These INVERT rather than shift — that is the whole point,
-    // and the reason the neutral button and the selected tab can be one token
-    // in both modes instead of a two-arm ramp.
-    'fg.emphasized': {
-      base: colors.gray[1300].value,
-      _dark: colors.grayDark[200].value,
-    },
-    'bg.inverse': {
-      base: colors.gray[1300].value,
-      _dark: colors.grayDark[50].value,
-    },
-    'fg.inverse': {
-      base: colors.gray[0].value,
-      _dark: colors.grayDark[1400].value,
-    },
+  const BY_PATH = Object.fromEntries(
+    Object.entries(ROLE_TOKEN_PATHS).map(([flat, path]) => [
+      path.replace(/\.DEFAULT$/, ''),
+      flat as keyof (typeof SCHEMES)['ink']['light'],
+    ])
+  );
+  const ALIASES: Record<string, string> = {
+    'fg.emphasized': 'fg.default',
+    'bg.inverse': 'tooltip.bg',
+    'fg.inverse': 'tooltip.fg',
   };
-
   const resolve = (token: string, mode: 'base' | '_dark') => {
-    const entry = RESOLVED[token];
-    if (!entry) throw new Error(`토큰 ${token} 의 원색이 이 표에 없다`);
-    return entry[mode];
+    const flat = BY_PATH[ALIASES[token] ?? token];
+    if (!flat) throw new Error(`토큰 ${token} 의 원색이 이 표에 없다`);
+    return SCHEMES.ink[mode === 'base' ? 'light' : 'dark'][flat];
   };
 
   it.each([
@@ -404,39 +374,51 @@ describe('브랜드 색 대비 — Link · Tab 램프', () => {
     // hardcoded the expected steps passed just fine with the hover pointing at
     // `primary.main` — measuring the right arithmetic about the wrong colour.
     expect(
-      contrast(resolve(ramp.base, 'base'), LIGHT_CANVAS)
+      contrast(resolve(ramp, 'base'), LIGHT_CANVAS)
     ).toBeGreaterThanOrEqual(AA_BODY_TEXT);
     expect(
-      contrast(resolve(ramp._dark, '_dark'), DARK_CANVAS)
+      contrast(resolve(ramp, '_dark'), DARK_CANVAS)
     ).toBeGreaterThanOrEqual(AA_BODY_TEXT);
   });
 
-  it('hover 가 배경 반대쪽으로 간다 — 양쪽 모드에서', () => {
-    // The invariant the defect broke: hovering must make the link stand out
+  it('hover 가 배경 반대쪽으로 간다 — 라이트', () => {
+    // The invariant the 4.x defect broke: hovering must make the link stand out
     // MORE. "One step darker" is correct on a white page and backwards on a
     // dark one, where darker means toward the background.
-    for (const [mode, canvas] of [
-      ['base', LIGHT_CANVAS],
-      ['_dark', DARK_CANVAS],
-    ] as const) {
-      const resting = contrast(resolve(LINK_RAMP.default[mode], mode), canvas);
+    const resting = contrast(resolve(LINK_RAMP.default, 'base'), LIGHT_CANVAS);
+    const hover = contrast(
+      resolve(LINK_RAMP.defaultHover, 'base'),
+      LIGHT_CANVAS
+    );
+    expect(hover).toBeGreaterThan(resting);
+  });
+
+  // KNOWN (5.0 open question, needs designer sign-off): the BAZE guide's dark
+  // `fg.linkHover` #8BB7E3 is 6.52:1 on bg.surface against the resting link's
+  // 7.89:1 — the hover moves TOWARD the background. Both still clear 4.5:1 and
+  // the underline thickens 1px → 2px, so the hover cue survives, but this is
+  // the exact inversion this file was written to stop. `it.fails` keeps the
+  // invariant on record: when the value is fixed this starts passing and fails
+  // the suite, so flip it back to `it`.
+  it.fails(
+    'hover 가 배경 반대쪽으로 간다 — 다크 (BAZE 가이드 값 확인 필요)',
+    () => {
+      const resting = contrast(
+        resolve(LINK_RAMP.default, '_dark'),
+        DARK_CANVAS
+      );
       const hover = contrast(
-        resolve(LINK_RAMP.defaultHover[mode], mode),
-        canvas
+        resolve(LINK_RAMP.defaultHover, '_dark'),
+        DARK_CANVAS
       );
-      expect(
-        hover,
-        `${mode} 에서 hover 가 resting 보다 흐리다`
-      ).toBeGreaterThan(resting);
+      expect(hover).toBeGreaterThan(resting);
     }
-  });
+  );
 
   it('선택된 가로 탭의 레이블이 라이트·다크 양쪽에서 4.5:1 을 넘는다', () => {
-    // Measured against `DARK_CANVAS` (#181A20), the RAISED surface — not the
-    // page background (#0E1014). That distinction is the whole defect:
-    // `primary.main` is 4.59:1 on the page and 4.19:1 here, so the selected tab
-    // passed every full-page scan and failed the first time a tab list rendered
-    // inside a modal. The stricter of the two surfaces is the one to hold.
+    // Measured against the RAISED surface (bg.surface), not the page canvas:
+    // in 4.x `primary.main` passed on the page and failed inside a modal, so
+    // the stricter of the two surfaces is the one to hold.
     expect(
       contrast(resolve(TAB_RAMP.label, 'base'), LIGHT_CANVAS)
     ).toBeGreaterThanOrEqual(AA_BODY_TEXT);
@@ -460,14 +442,13 @@ describe('브랜드 색 대비 — Link · Tab 램프', () => {
   });
 
   /**
-   * The regression this file did not have, and the defect it would have caught:
-   * `neutral` + `solid` shipped a white label on `gray.700`, which is 4.12:1 in
-   * light and 3.15:1 in dark. A neutral fill has to INVERT with the mode — a
-   * shift fixes one arm and breaks the other, which is exactly what the obvious
-   * "one step darker" does (5.32:1 light, 3.08:1 dark).
+   * The 4.x regression: `neutral` + `solid` shipped a white label on
+   * `gray.700` (4.12:1 light, 3.15:1 dark). In 5.0 that button is `primary`
+   * (black / beige fill), which has to INVERT with the mode — a shift fixes
+   * one arm and breaks the other.
    */
-  it('중립 solid 버튼의 레이블이 라이트·다크 양쪽에서 4.5:1 을 넘는다', () => {
-    const { bgColor, color } = buttonColorPaletteStyles.neutral.solid;
+  it('primary 버튼의 레이블이 라이트·다크 양쪽에서 4.5:1 을 넘는다', () => {
+    const { bgColor, color } = buttonVariantStyles.primary;
 
     expect(
       contrast(
@@ -488,9 +469,9 @@ describe('브랜드 색 대비 — Link · Tab 램프', () => {
    * space. Ink on charcoal is the failure mode: a FIXED near-black would be
    * ~1.2:1 against a dark canvas, which is why `bg.inverse` inverts.
    */
-  it('중립 solid 버튼의 면이 양쪽 모드에서 캔버스와 3:1 이상 갈라진다', () => {
+  it('primary 버튼의 면이 양쪽 모드에서 캔버스와 3:1 이상 갈라진다', () => {
     const AA_NON_TEXT = 3;
-    const { bgColor } = buttonColorPaletteStyles.neutral.solid;
+    const { bgColor } = buttonVariantStyles.primary;
 
     expect(
       contrast(resolve(bgColor as string, 'base'), LIGHT_CANVAS)

package/src/components/claude.md

@@ -28,12 +28,7 @@ import { ComponentNameProps } from './ComponentName.types';
 
 export const ComponentName = forwardRef(
   ({ variant = 'default', ...rest }: ComponentNameProps, ref) => {
-    return (
-      <ChakraComponentName
-        ref={ref}
-        {...rest}
-      />
-    );
+    return <ChakraComponentName ref={ref} {...rest} />;
   }
 );
 
@@ -55,6 +50,7 @@ export type ComponentNameProps = Omit<ChakraComponentNameProps, 'variant'> & {
 ```
 
 **Key patterns:**
+
 - Extend Chakra UI component props using `Omit<>` to override specific props
 - Define custom variant types when overriding Chakra's variant system
 - Export all types for external use
@@ -70,25 +66,22 @@ export const variantStyles: Record<
   Partial<ComponentNameProps>
 > = {
   primary: {
-    borderColor: 'primary.main',
-    bgColor: 'primary.main',
-    color: 'white',
-    _hover: {
-      bgColor: 'blue.800',
-    },
+    bg: 'primary.main',
+    color: 'fg.onPrimary',
+    _hover: { bg: 'primary.hover' },
+    _active: { bg: 'primary.active' },
   },
   secondary: {
-    borderColor: 'gray.400',
-    bgColor: 'white',
-    color: 'gray.1200',
-    _hover: {
-      bgColor: 'gray.50',
-    },
+    bg: 'bg.surface',
+    borderColor: 'border.default',
+    color: 'fg.default',
+    _hover: { bg: 'primary.wash' },
   },
 };
 ```
 
 **Best practices:**
+
 - Use theme tokens (semantic tokens preferred)
 - Define all interactive states (`_hover`, `_focus`, `_disabled`, `_active`)
 - Keep styles type-safe with `Partial<ComponentNameProps>`
@@ -103,6 +96,7 @@ export type { ComponentNameProps } from './ComponentName.types';
 ```
 
 Then add to `src/index.ts`:
+
 ```tsx
 export * from './components/ComponentName';
 ```
@@ -122,6 +116,7 @@ Component.displayName = 'Component';
 ```
 
 **Why:**
+
 - Enables ref forwarding for DOM manipulation
 - Required for Chakra UI integration
 - Supports form libraries (React Hook Form, Formik)
@@ -136,7 +131,10 @@ import { useTheme, useToken } from '@chakra-ui/react';
 
 const Component = () => {
   const theme = useTheme();
-  const primaryColor = useToken('colors', theme.semanticTokens.colors.primary.main);
+  const primaryColor = useToken(
+    'colors',
+    theme.semanticTokens.colors.primary.main
+  );
 
   // Use semantic tokens when available
   const borderColor = theme.semanticTokens.colors.primary.main;
@@ -144,49 +142,33 @@ const Component = () => {
 ```
 
 **Semantic tokens to use:**
-- `primary.main`, `primary.light` - Primary brand colors
-- `danger.main` - Error/danger states
+
+- `primary.main` / `primary.wash` / `primary.selected` - primary (BAZE black) fill, hover wash, selected row — see src/theme/SemanticTokens.mdx
+- `danger.{bg,border,fg,solid,onSolid}` (and success/warning/info) - status states. `danger.main` is a deprecated 4.x alias
 - `bg.*` / `fg.*` / `border.*` - Neutral surfaces, text, and borders that **flip with
-  color mode**. Prefer these over raw `gray.*`/`white` so components work in dark mode
-  (see `src/theme/claude.md` → Neutral Semantic Tokens). Raw `gray.*` is only for values
-  that must stay fixed across modes.
+  color mode**. Components never read raw scales (5.0 has no `gray` scale at all) — use these so components work in dark mode
+  (see `src/theme/claude.md` → Color System — BAZE).
 
 ### Common Style Patterns
 
 #### Focus States
-```tsx
-_focus={{
-  outline: 'none',
-  boxShadow: `rgb(255, 255, 255) 0px 0px 0px 2px, ${primaryMainColor} 0px 0px 0px 4px`,
-}}
-```
 
-#### Disabled States
 ```tsx
-_disabled={{
-  opacity: 1,
-  cursor: 'not-allowed',
-  bg: 'gray.50',
-  color: 'gray.1000',
-}}
+import { focusRing } from '@/utils/focusRing';
+_focusVisible = { focusRing }; // inner bg.canvas band + outer focus.ring
 ```
 
-#### Read-Only States
+#### Disabled / Read-Only States
+
 ```tsx
-_readOnly={{
-  opacity: 1,
-  cursor: 'not-allowed',
-  bg: 'gray.50',
-  color: 'gray.600',
-  borderColor: 'gray.200',
-}}
+import { disabledControl, disabledText } from '@/utils/disabledControl';
+_disabled = { disabledControl }; // fixed disabled.* colours — never opacity
 ```
 
 #### Hover States
+
 ```tsx
-_hover={{
-  borderColor: 'gray.600',
-}}
+_hover={{ borderColor: 'border.strong' }}
 ```
 
 ## Form Components
@@ -228,9 +210,7 @@ const Input = forwardRef((props, ref) => {
       onCompositionStart={handleCompositionStart}
       onCompositionEnd={handleCompositionEnd}
       onKeyDown={handleKeyDown}
-      borderColor="gray.400"
-      focusBorderColor="primary.main"
-      errorBorderColor="danger.main"
+      borderColor="border.control"
       {...props}
     />
   );
@@ -238,6 +218,7 @@ const Input = forwardRef((props, ref) => {
 ```
 
 **Key considerations:**
+
 - Handle IME composition for international input
 - Support controlled/uncontrolled modes
 - Include focus, error, and disabled states
@@ -273,6 +254,7 @@ const createSyntheticEvent = (
 ### Default Values
 
 Provide sensible defaults:
+
 ```tsx
 const Button = ({ variant = 'secondary', size = 'md', ...rest }) => {
   // secondary is safer default than primary
@@ -283,11 +265,12 @@ const Button = ({ variant = 'secondary', size = 'md', ...rest }) => {
 ### Prop Spreading
 
 Always spread props at the end:
+
 ```tsx
 <ChakraComponent
   // Your custom props first
   variant={variant}
-  borderColor="gray.400"
+  borderColor="border.control"
   // Then spread remaining props
   {...rest}
 />
@@ -296,6 +279,7 @@ Always spread props at the end:
 ### Custom Props vs Chakra Props
 
 Prefer Chakra's built-in props when available:
+
 - ✅ Use `isDisabled` instead of `disabled`
 - ✅ Use `isReadOnly` instead of `readonly`
 - ✅ Use `isInvalid` for error states
@@ -312,12 +296,9 @@ Prefer Chakra's built-in props when available:
 - Maintain proper focus management
 
 ### Example:
+
 ```tsx
-<Button
-  aria-label="Close dialog"
-  onClick={onClose}
-  tabIndex={0}
->
+<Button aria-label="Close dialog" onClick={onClose} tabIndex={0}>
   Close
 </Button>
 ```
@@ -337,6 +318,7 @@ import { formatNumber } from '../../utils/formatNumber';
 ```
 
 Available aliases:
+
 - `@/components/*`
 - `@/utils/*`
 - `@/hooks/*`
@@ -352,7 +334,7 @@ See `.storybook/claude.md` for Storybook-specific patterns.
 1. **Forgetting forwardRef**: Always use it for components wrapping DOM elements
 2. **Not setting displayName**: Required for React DevTools
 3. **Hardcoded / non-flipping colors**: Use theme tokens instead — and for neutrals use the
-   flipping `bg.*`/`fg.*`/`border.*` tokens, not raw `gray.*`/`white` (which stay stuck in
+   flipping `bg.*`/`fg.*`/`border.*` tokens, not raw scales or `white` (which stay stuck in
    light mode under `.dark`)
 4. **Missing focus states**: Required for accessibility
 5. **Props in wrong order**: Custom props before spread

package/src/components/noRawScales.test.ts

@@ -0,0 +1,152 @@
+/* eslint-disable no-deprecated-tokens -- the strings below are fixtures for the pattern under test */
+import { readdirSync, readFileSync } from 'node:fs';
+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';
+
+/**
+ * Components read ROLE tokens (`bg.*`, `fg.*`, `primary.*`, `category.*` …),
+ * never a raw scale step. A raw step does not flip with colour mode or follow
+ * the `neutral` / `secondary` theme option, and the contrast audit only checks
+ * roles — so a raw step in a component is an unaudited colour.
+ *
+ * `Button.variants.test.tsx` used to check this for Button's style table only;
+ * this scans every component source file (stories and tests excluded).
+ *
+ * Only `<scale>.<step>` token strings are flagged — `'green'` as a hue name, a
+ * `category.green.surface` role, or `theme.colors.gray` property access are
+ * not.
+ */
+
+const ROOT = join(__dirname);
+const REPO = join(__dirname, '..', '..');
+
+/** 4.x primitive scales (numeric steps). */
+const LEGACY_SCALES = [
+  'blue',
+  'violet',
+  'rose',
+  'gold',
+  'green',
+  'gray',
+  'grayDark',
+  'slate',
+];
+/** 5.0 raw numeric scales. */
+const RAW_SCALES = ['ink', 'inkDark', 'sand', 'sandDark', 'slate', 'slateDark'];
+/** Chakra's alpha scales (numeric steps). */
+const ALPHA_SCALES = ['whiteAlpha', 'blackAlpha'];
+/** Named-step keys of the 12 system hues. */
+const HUE_KEYS = [
+  'base',
+  'baseDark',
+  'hc',
+  'hcDark',
+  'surface',
+  'surfaceDark',
+  'ink',
+  'inkDark',
+];
+
+const numeric = [
+  ...new Set([...LEGACY_SCALES, ...RAW_SCALES, ...ALPHA_SCALES]),
+];
+const alt = (xs: readonly string[]) => xs.join('|');
+
+/**
+ * Not preceded by a word char, `.`, `$` or `-` (so `category.blue.surface`,
+ * `colors.gray.100` and `--chakra-colors-gray-100` are not hits); not followed
+ * by a word char or `.`.
+ */
+const TOKEN = new RegExp(
+  `(?<![\\w.$-])(?:` +
+    `(?:${alt(numeric)})\\.\\d+` +
+    `|coral\\.(?:${alt(Object.keys(CORAL))})` +
+    `|(?:${alt(SYSTEM_HUE_NAMES)})\\.(?:${alt(HUE_KEYS)})` +
+    `)(?![\\w.])`,
+  'g'
+);
+
+/**
+ * Files allowed to name raw steps, and why. Keep this short and specific:
+ * an entry needs a reason a reviewer would accept, not "TODO".
+ */
+const ALLOWED: Record<string, string> = {
+  // The sheet's scrim is the same `blackAlpha.500` Chakra's own dialog
+  // backdrop recipe uses (Modal inherits it), so a sheet and a modal dim the
+  // page identically. A scrim is meant to be mode-invariant; there is no role
+  // token for it.
+  'src/components/BottomSheet/BottomSheet.styles.ts':
+    'mirrors Chakra dialog backdrop (blackAlpha.500)',
+};
+
+const walk = (dir: string): string[] =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((d) => {
+    const p = join(dir, d.name);
+    if (d.isDirectory()) return walk(p);
+    return /\.(ts|tsx)$/.test(d.name) &&
+      !/\.(stories|test|spec)\.(ts|tsx)$/.test(d.name) &&
+      !d.name.endsWith('.d.ts')
+      ? [p]
+      : [];
+  });
+
+/** Drop comments, keeping line numbers. */
+const stripComments = (src: string) =>
+  src
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^:'"`\\])\/\/[^\n]*/g, '$1');
+
+const findHits = () => {
+  const hits: string[] = [];
+  for (const file of walk(ROOT)) {
+    const rel = relative(REPO, file);
+    if (rel in ALLOWED) continue;
+    const lines = stripComments(readFileSync(file, 'utf8')).split('\n');
+    lines.forEach((line, i) => {
+      for (const m of line.matchAll(TOKEN)) {
+        hits.push(`${rel}:${i + 1}  ${m[0]}`);
+      }
+    });
+  }
+  return hits;
+};
+
+describe('components read no raw palette scales', () => {
+  it('the pattern flags raw steps and spares roles', () => {
+    const flagged = (s: string) => (s.match(TOKEN) ?? []).length > 0;
+    for (const raw of [
+      "'gray.50'",
+      '"blue.500"',
+      "'grayDark.200'",
+      "'ink.12'",
+      "'sandDark.3'",
+      "'coral.base'",
+      "'red.surface'",
+      "'blue.hc'",
+      "'blackAlpha.600'",
+      '`whiteAlpha.300`',
+    ]) {
+      expect(flagged(raw), raw).toBe(true);
+    }
+    for (const role of [
+      "'category.green.surface'",
+      "'green'",
+      "'fg.default'",
+      'theme.colors.gray.100',
+      "'--chakra-colors-gray-100'",
+      "'secondary.surface'",
+      "'neutral.12'",
+      "'secondary.3'",
+      "'primary.main'",
+    ]) {
+      expect(flagged(role), role).toBe(false);
+    }
+  });
+
+  it('no component source names a raw scale step', () => {
+    expect(findHits()).toEqual([]);
+  });
+});