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

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/componentMotion.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkmarkDraw } from './Checkbox/Checkbox.styles';
+import { modalAnimation } from './Modal/Modal.styles';
+import { indeterminateSweep } from './ProgressBar/ProgressBar.styles';
+import { dotPop } from './Radio/Radio.styles';
+import { indicatorTravel } from './SegmentedControl/SegmentedControl.styles';
+import { spinAnimation } from './Spinner/Spinner.styles';
+
+/**
+ * The six motions that are one component's own business rather than shared
+ * vocabulary. They left `theme/animationStyles` because nothing else picks
+ * them, but the guarantees that made the vocabulary trustworthy have to travel
+ * with them — otherwise "move it into the component" quietly means "stop
+ * checking it".
+ *
+ * These assert on the style objects rather than on rendered CSS: what moved is
+ * the *composition*, and the composition is what can rot. The rendered-output
+ * checks that prove a preset actually reaches its element still live next to
+ * the components that own them.
+ */
+const REDUCE = '_motionReduce';
+
+/** Every local motion, and whether it is a loop (which turns off differently). */
+const LOCAL = [
+  { name: 'spinAnimation', style: spinAnimation, loop: true },
+  { name: 'indeterminateSweep', style: indeterminateSweep, loop: true },
+  { name: 'checkmarkDraw', style: checkmarkDraw, loop: false },
+  { name: 'dotPop', style: dotPop, loop: false },
+  { name: 'indicatorTravel', style: indicatorTravel, loop: false },
+] as const;
+
+describe('component-local motion', () => {
+  it('every one of them still answers reduced motion', () => {
+    // The policy that was structural in the theme stays structural here: a
+    // component that animates and forgets the guard fails on the day it is
+    // written, not the day someone reports the dizziness.
+    LOCAL.forEach(({ name, style }) => {
+      expect(style, name).toHaveProperty(REDUCE);
+    });
+  });
+
+  it('no loop turns itself off by zeroing its duration', () => {
+    // A finite transition can be zeroed because its end state survives. A loop
+    // has no end state: zeroing parks the element at an arbitrary frame — a
+    // spinner stuck at some angle reads as a hung request, not a working one.
+    LOCAL.filter((l) => l.loop).forEach(({ name, style }) => {
+      const reduced = style[REDUCE] as Record<string, unknown>;
+      expect(reduced.animationDuration, name).not.toBe('motion.instant');
+    });
+  });
+
+  it('keeps the spinner turning, slower, because it is the signal', () => {
+    const reduced = spinAnimation[REDUCE] as Record<string, unknown>;
+    // Still an animation, still infinite — only the rate changed.
+    expect(reduced.animationName).toBeUndefined();
+    expect(reduced.animationDuration).toBe('motion.loop.sweep');
+    expect(spinAnimation.animationDuration).toBe('motion.loop.turn');
+  });
+
+  it('stops the indeterminate bar, whose signal lives in the surrounding UI', () => {
+    expect(
+      (indeterminateSweep[REDUCE] as Record<string, unknown>).animationName
+    ).toBe('none');
+  });
+
+  it('turns both seamless loops at a constant rate', () => {
+    // A rotation and a track crossing both return to their own start. Easing
+    // decelerates into the last frame and accelerates out of the first, which
+    // are the same position — so the eye catches a stutter once per cycle.
+    [spinAnimation, indeterminateSweep].forEach((style) =>
+      expect(style.animationTimingFunction).toBe('linear')
+    );
+  });
+
+  it('names Chakra keyframes rather than redefining them', () => {
+    // Redefining a keyframe we did not author replaces it for every Chakra
+    // component that reads it by name.
+    expect(spinAnimation.animationName).toBe('spin');
+  });
+
+  it('leaves the Modal owning its movement and nothing else', () => {
+    // The clock comes from `presence`; only the two names are local. A
+    // duration here would be the asymmetry policy drifting out of reach of the
+    // test that enforces it.
+    expect(modalAnimation).toEqual({
+      _open: { animationName: 'modal-in' },
+      _closed: { animationName: 'modal-out' },
+    });
+  });
+
+  it('reaches the Ark indicator through custom properties, not style props', () => {
+    // Ark inlines this part's `transition-*`, and an inline declaration beats
+    // any class — the two custom properties are the only seam left.
+    expect(indicatorTravel).toHaveProperty('--transition-duration');
+    expect(indicatorTravel).toHaveProperty('--transition-timing-function');
+    expect(indicatorTravel).not.toHaveProperty('transitionDuration');
+  });
+
+  it('restores what the checkmark draw presupposes', () => {
+    // The dash pattern is what hides the tick before it is stroked; leaving it
+    // on under reduced motion would leave a dashed checkmark.
+    const reduced = checkmarkDraw[REDUCE] as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(reduced['& polyline, & path'].strokeDasharray).toBe('none');
+    expect(reduced['& polyline, & path'].animation).toBe('none');
+  });
+});

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([]);
+  });
+});