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

package/src/theme/Palette.stories.tsx

@@ -26,7 +26,8 @@ import { colors, semanticTokens } from './colors';
  * Helper function to resolve a semantic token reference to its actual hex value.
  * E.g., '{colors.blue.500}' -> '#1751D0'
  */
-const resolveTokenReference = (reference: string): string => {
+const resolveTokenReference = (reference: string | undefined): string => {
+  if (!reference) return '';
   // Scale reference, e.g. '{colors.blue.500}' or '{colors.gray.1500}'.
   const scaleMatch = reference.match(/^\{colors\.(\w+)\.(\w+)\}$/);
   if (scaleMatch) {
@@ -51,21 +52,27 @@ const resolveTokenReference = (reference: string): string => {
 
 /**
  * A semantic token `value` is either a plain reference string (legacy) or a
- * mode-conditional object `{ base, _dark }`. Resolve it to concrete light/dark
- * hex codes so the palette can show both modes side by side.
+ * mode-conditional object with any of `base` / `_light` / `_dark`. Resolve it to
+ * concrete light/dark hex codes so the palette can show both modes side by side.
  */
-type TokenValue = string | { base: string; _dark?: string };
+type TokenValue =
+  | string
+  | { base?: string; _light?: string; _dark?: string };
 
 const resolveTokenValue = (
-  value: TokenValue
+  value: TokenValue | undefined
 ): { light: string; dark: string } => {
+  if (!value) return { light: '', dark: '' };
   if (typeof value === 'string') {
     const hex = resolveTokenReference(value);
     return { light: hex, dark: hex };
   }
+  // A `_light` / `_dark` condition wins over `base` in its mode; fall back to
+  // `base` (then the other mode) when a token omits one, so tokens declared with
+  // only `_light`/`_dark` (e.g. `*.DEFAULT`, `border.subtle`) resolve too.
   return {
-    light: resolveTokenReference(value.base),
-    dark: resolveTokenReference(value._dark ?? value.base),
+    light: resolveTokenReference(value._light ?? value.base ?? value._dark),
+    dark: resolveTokenReference(value._dark ?? value.base ?? value._light),
   };
 };
 
@@ -296,14 +303,35 @@ export const SemanticTokens: Story = {
                 {color}
               </H4>
               <Grid templateColumns="repeat(auto-fill, minmax(132px, 1fr))" gap={2} flex="1" minW="0">
-                {Object.entries(shades).map(([shade, shadeValue]) => (
-                  <ColorCard
-                    key={shade}
-                    color={color}
-                    shade={shade}
-                    shadeValue={(shadeValue as any).value as TokenValue}
-                  />
-                ))}
+                {Object.entries(shades).flatMap(([shade, shadeValue]) => {
+                  const node = shadeValue as any;
+                  // Leaf token: render its value directly.
+                  if (node && node.value !== undefined) {
+                    return [
+                      <ColorCard
+                        key={shade}
+                        color={color}
+                        shade={shade}
+                        shadeValue={node.value as TokenValue}
+                      />,
+                    ];
+                  }
+                  // Nested group (e.g. bg.invalid → bg.invalid.subtle): render
+                  // each leaf beneath it as `<shade>.<sub>`.
+                  if (node && typeof node === 'object') {
+                    return Object.entries(node)
+                      .filter(([, sub]) => (sub as any)?.value !== undefined)
+                      .map(([subShade, sub]) => (
+                        <ColorCard
+                          key={`${shade}.${subShade}`}
+                          color={color}
+                          shade={`${shade}.${subShade}`}
+                          shadeValue={(sub as any).value as TokenValue}
+                        />
+                      ));
+                  }
+                  return [];
+                })}
               </Grid>
             </Flex>
           ))}
@@ -754,14 +782,35 @@ export const Default: Story = {
                 {color}
               </H4>
               <Grid templateColumns="repeat(auto-fill, minmax(132px, 1fr))" gap={2} flex="1" minW="0">
-                {Object.entries(shades).map(([shade, shadeValue]) => (
-                  <ColorCard
-                    key={shade}
-                    color={color}
-                    shade={shade}
-                    shadeValue={(shadeValue as any).value as TokenValue}
-                  />
-                ))}
+                {Object.entries(shades).flatMap(([shade, shadeValue]) => {
+                  const node = shadeValue as any;
+                  // Leaf token: render its value directly.
+                  if (node && node.value !== undefined) {
+                    return [
+                      <ColorCard
+                        key={shade}
+                        color={color}
+                        shade={shade}
+                        shadeValue={node.value as TokenValue}
+                      />,
+                    ];
+                  }
+                  // Nested group (e.g. bg.invalid → bg.invalid.subtle): render
+                  // each leaf beneath it as `<shade>.<sub>`.
+                  if (node && typeof node === 'object') {
+                    return Object.entries(node)
+                      .filter(([, sub]) => (sub as any)?.value !== undefined)
+                      .map(([subShade, sub]) => (
+                        <ColorCard
+                          key={`${shade}.${subShade}`}
+                          color={color}
+                          shade={`${shade}.${subShade}`}
+                          shadeValue={(sub as any).value as TokenValue}
+                        />
+                      ));
+                  }
+                  return [];
+                })}
               </Grid>
             </Flex>
           ))}

package/src/theme/animationStyles.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+
+import { system } from './index';
+import { animationStyles, durations } from './motion';
+
+/** The presets that carry a `transition-*` clock, as opposed to the two hatches. */
+const CLOCKED = ['press', 'feedback', 'travel', 'spring'] as const;
+
+const applied = (name: string, extra: object = {}) =>
+  system.css({ animationStyle: name, ...extra });
+
+const REDUCED_QUERY = '@media (prefers-reduced-motion: reduce)';
+
+/** How Chakra spells `_open` / `_closed` once the condition is resolved. */
+const OPEN = '&:is([open], [data-open], [data-state=open])';
+const CLOSED = '&:is([closed], [data-closed], [data-state=closed])';
+
+type Css = Record<string, any>;
+
+/**
+ * Every duration variable this theme can emit, mapped back to its milliseconds.
+ *
+ * Built by walking the token tree rather than by string-munging the variable
+ * name: `--chakra-durations-motion-loop-turn` could be `motion.loop.turn` or
+ * `motion.loop-turn` and the name alone cannot say which, so the walk is the
+ * only spelling that stays correct as the scale grows.
+ */
+const DURATION_MS: Record<string, number> = {};
+const collect = (node: object, path: string[]) => {
+  Object.entries(node).forEach(([key, child]) => {
+    const next = [...path, key];
+    if (child && typeof child === 'object' && 'value' in child) {
+      const full = ['durations', ...next].join('.');
+      DURATION_MS[system.tokens.getVar(full) as string] = parseFloat(
+        String(system.token(full))
+      );
+    } else if (child && typeof child === 'object') {
+      collect(child, next);
+    }
+  });
+};
+collect(durations, []);
+// Chakra's own scale is reachable from a preset too — `presence` exits on `fast`.
+['fastest', 'faster', 'fast', 'moderate', 'slow', 'slower', 'slowest'].forEach(
+  (name) => {
+    DURATION_MS[system.tokens.getVar(`durations.${name}`) as string] =
+      parseFloat(String(system.token(`durations.${name}`)));
+  }
+);
+
+/**
+ * The vocabulary exists so "anything that animates honours reduced motion" is
+ * structural rather than remembered, and so no preset can quietly fall back to
+ * `transition-property: all`. These tests are what makes both true — a preset
+ * added without a guard fails here rather than in someone's browser.
+ */
+describe('motion vocabulary', () => {
+  it('is registered in the theme, so `animationStyle` accepts every name', () => {
+    // Registered rather than imported is the whole design: it puts the presets
+    // in the same slot as `textStyle`, which is what lets a consuming app remap
+    // one from its own config.
+    const registered = system.query.animationStyles.list();
+    Object.keys(animationStyles).forEach((name) => {
+      expect(registered, name).toContain(name);
+    });
+  });
+
+  it('every preset carries a reduced-motion branch', () => {
+    Object.keys(animationStyles).forEach((name) => {
+      expect(applied(name), name).toHaveProperty(REDUCED_QUERY);
+    });
+  });
+
+  it('the guard zeroes the duration rather than removing the state change', () => {
+    expect(applied('spring')[REDUCED_QUERY]).toEqual({
+      transitionDuration: 'var(--chakra-durations-motion-instant)',
+    });
+  });
+
+  it('no preset leaves transition-property to default to `all`', () => {
+    // CSS defaults it to `all`, so a preset that omitted the property would
+    // animate everything on the element — including layout the consumer set.
+    // `none` makes a forgotten call-site prop show up as nothing moving.
+    CLOCKED.forEach((name) => {
+      const property = applied(name).transitionProperty;
+      expect(property, name).toBeDefined();
+      expect(property, name).not.toBe('all');
+    });
+  });
+
+  it("the call site's property wins over the preset default", () => {
+    expect(
+      applied('feedback', { transitionProperty: 'opacity' })
+    ).toMatchObject({ transitionProperty: 'opacity' });
+    // ...regardless of which is written first.
+    expect(
+      system.css({ transitionProperty: 'opacity', animationStyle: 'feedback' })
+    ).toMatchObject({ transitionProperty: 'opacity' });
+  });
+
+  it('presets resolve to the intended timings', () => {
+    const timing = (name: string) => [
+      applied(name).transitionDuration,
+      applied(name).transitionTimingFunction,
+    ];
+    const d = (n: string) => `var(--chakra-durations-${n})`;
+    const e = (n: string) => `var(--chakra-easings-${n})`;
+
+    expect(timing('press')).toEqual([d('motion-press'), e('emphasized')]);
+    expect(timing('feedback')).toEqual([d('fast'), e('standard')]);
+    expect(timing('travel')).toEqual([d('motion-base'), e('emphasized')]);
+    expect(timing('spring')).toEqual([d('motion-base'), e('overshoot')]);
+  });
+});
+
+/**
+ * The asymmetry is a *policy*, and a policy nobody can enforce is a paragraph
+ * in a changelog. An enter has to be read; an exit is already decided and is
+ * only in the way. Every surface that appears and disappears owes the reader
+ * the same ratio, and the sixth one added is the one that would have restated
+ * 300/300 by hand.
+ *
+ * So this walks the whole vocabulary rather than naming the presets it knows
+ * about: a new preset with an `_open` branch is caught here on the day it is
+ * written, not the day someone notices a dialog outstaying its welcome.
+ */
+describe('the enter/exit policy', () => {
+  const withOpen = Object.keys(animationStyles).filter(
+    (name) => OPEN in (applied(name) as Css)
+  );
+
+  it('covers the presets that actually declare an open state', () => {
+    // A guard on the guard: if the condition Chakra emits for `_open` ever
+    // changes spelling, `withOpen` silently empties and every assertion below
+    // passes over nothing.
+    // `presence` and its shorter anchored twin are the only global presets
+    // with an open state — the Modal carries its own two keyframe names and
+    // borrows the `presence` clock. The walk stays a walk rather than an
+    // assertion about these two alone, so the next preset with an `_open`
+    // branch is covered the day it is written.
+    expect(withOpen).toEqual(['presence', 'presence-anchored']);
+  });
+
+  it('never declares an enter without the matching exit', () => {
+    withOpen.forEach((name) => {
+      expect(applied(name), name).toHaveProperty(CLOSED);
+    });
+  });
+
+  it('leaves in strictly less time than it arrives', () => {
+    withOpen.forEach((name) => {
+      const css = applied(name) as Css;
+      const enter = DURATION_MS[css[OPEN].animationDuration];
+      const exit = DURATION_MS[css[CLOSED].animationDuration];
+      // Resolved, not compared as token names: `motion.base` and `fast` say
+      // nothing about which is longer, and the whole point is the numbers.
+      expect(enter, `${name} enter`).toBeGreaterThan(0);
+      expect(exit, `${name} exit`).toBeLessThan(enter);
+    });
+  });
+
+  it('declares no animation-name of its own, so each recipe keeps its own', () => {
+    // The reason one preset can sit on a menu that slides, a popover that
+    // scales and a collapsible that interpolates a measured height. A name here
+    // would flatten all three into whatever it named.
+    withOpen.forEach((name) => {
+      const css = applied(name) as Css;
+      expect(css[OPEN].animationName, name).toBeUndefined();
+      expect(css[CLOSED].animationName, name).toBeUndefined();
+    });
+  });
+
+  it('opens anchored popups faster than dialogs, on the same curves', () => {
+    const full = applied('presence') as Css;
+    const anchored = applied('presence-anchored') as Css;
+    expect(DURATION_MS[anchored[OPEN].animationDuration]).toBe(200);
+    expect(DURATION_MS[anchored[CLOSED].animationDuration]).toBe(100);
+    expect(anchored[OPEN].animationTimingFunction).toBe(
+      full[OPEN].animationTimingFunction
+    );
+    expect(anchored[CLOSED].animationTimingFunction).toBe(
+      full[CLOSED].animationTimingFunction
+    );
+  });
+});

package/src/theme/claude.md

@@ -6,13 +6,132 @@ The Logician UI theme system extends Chakra UI's theming capabilities with the *
 
 ```
 src/theme/
-├── index.ts          # Main theme export
+├── index.ts          # Main theme export (also defines textStyles)
 ├── colors.ts         # Color palette & semantic tokens
+├── motion.ts         # Duration/easing scales & the animationStyle presets
 ├── font.ts           # Font family definitions
 ├── global.ts         # Global CSS styles
-└── Palette.stories.tsx  # Visual color palette reference
+├── Palette.stories.tsx  # Visual color palette reference
+└── Motion.stories.tsx   # Motion preset & scale reference
 ```
 
+## Motion
+
+**Never write a duration or a curve as a literal.** Everything below exists so
+that `300ms` and `cubic-bezier(...)` do not appear in component code.
+
+### Start here — which of the three
+
+```
+An element already on screen, one of its values changes   →  a preset
+An element appears / disappears / has to replay           →  a component
+You are using a library component (Switch, Card, …)       →  nothing. It is done.
+```
+
+The third is the common case. Reaching for `animationStyle` by hand means you
+are building something the library does not have.
+
+### Presets — `animationStyle`
+
+A name carries duration, curve and reduced-motion together, the way
+`textStyle="h3"` carries family, size, weight, leading and tracking.
+
+```tsx
+<Switch.Control
+  _checked={{ bg: 'primary.main' }}      // when it changes
+  animationStyle="feedback"              // how long, what curve
+  transitionProperty="background-color"  // what moves
+/>
+```
+
+Those three roles are separate and all three are required. A preset is a clock —
+it never knows *what* moves, so `transitionProperty` stays at the call site.
+
+| Preset | For |
+|---|---|
+| `press` | Contact — a button going down under the pointer |
+| `feedback` | Hover and state colour |
+| `travel` | Something moving to a new position or size |
+| `spring` | A physical flip, or two things crossing |
+| `presence` | A part with **both** an open and a closed state |
+| `presence-anchored` | The same, for a popup anchored to a trigger (Menu, Select, Combobox, Popover, Tooltip) |
+| `stagger` | Siblings arriving in sequence (with `staggerProps(index)`) |
+| `composite` | Escape hatch — one element needing two different clocks |
+
+**Eight is the whole list and that is policy.** A motion with one caller belongs
+next to that caller, not here (see `Spinner.styles.ts`, `Checkbox.styles.ts`).
+Adding an eighth needs two real call sites that the existing seven cannot
+express.
+
+Three rules are inside the preset definitions, so no component has to remember
+them:
+
+- **`transitionProperty` defaults to `none`.** CSS defaults it to `all`, which
+  would animate every property on the element — including ones the call site
+  set. Forgetting the prop means nothing moves, which is visible; the CSS
+  default fails invisibly.
+- **`prefers-reduced-motion`** is handled. Loops are the exception and slow down
+  rather than stopping — a frozen spinner reads as a dead request.
+- **Enter is 300ms, exit is 150ms** for `presence` (Modal, BottomSheet,
+  Collapsible) and **200ms / 100ms** for `presence-anchored`, enforced by a test.
+
+Three things `animationStyle` accepts and should never be given — all three
+compile, and all three are caught by lint instead of by types, because Chakra
+types the prop as `… | AnyString`:
+
+```tsx
+<Box animationStyle="feedbak" />                  // typo — silently does nothing
+<Box animationStyle="feedback" />                 // no scope — nothing moves
+<Box animationStyle={['travel', 'spring']} />     // read as RESPONSIVE BREAKPOINTS,
+                                                  // not as two motions
+```
+
+### Components — `Components/Motion/*` in Storybook
+
+CSS transitions need a before-value to interpolate from, so they cannot animate
+something that did not exist a moment ago, and cannot be replayed on demand.
+That is what these are for.
+
+| Component | For |
+|---|---|
+| `Pulse` | A value just landed — pop once |
+| `Shake` | Refusal. Never use it for emphasis |
+| `Appear` | One element entering on mount |
+| `Reveal` | A block opening underneath what is being read |
+| `FlyTo` | This went there — a ghost between two measured rects |
+| `Confetti` | One celebratory burst |
+| `CountUp` | A number rising |
+| `SwapTransition` | Content being replaced — steps, records |
+
+`Pulse` and `Shake` replay when `trigger` **changes**, and never on first render
+(a counter that mounts at 12 has not just become 12).
+
+They are not interchangeable with the presets and not a fallback for them. If
+the element can close, use `presence`; if siblings arrive with it, `stagger`.
+
+Each wraps differently, so check its TSDoc before putting one inside a `<tr>` or
+an Ark part that walks its own children: `Pulse` / `Shake` / `Appear` add one
+`div`, `Reveal` / `SwapTransition` add two, `FlyTo` portals, `Confetti` is an
+overlay, `CountUp` is the `<span>` itself.
+
+### Raw values — the escape hatch
+
+`durations` and `easings` are registered in the theme, so `motion.base` and
+`overshoot` resolve anywhere CSS does. Reach for the raw exports only where CSS
+cannot: `MOTION_DURATION_MS` / `MOTION_DURATION_S` / `MOTION_EASE` /
+`MOTION_EASE_CSS` for a third-party animation API, and `cubicBezier(curve)` to
+evaluate a house curve in JavaScript (a count-up that invents its own
+`easeOutCubic` lands on a different curve from the card beside it).
+
+Durations carry a `motion.` prefix so they sit alongside Chakra's scale rather
+than redefining `slow` / `slower`, which its `dialog`, `drawer` and `progress`
+recipes read — redefining a token you did not author retimes every component
+that reads it. There are deliberately no `motion.*` tokens for 150ms and 200ms:
+Chakra's `fast` and `moderate` are exactly those, and two names for one number
+is worse than remembering which scale to reach into.
+
+`Theme/Motion` in Storybook is the live version of this page.
+
 ## Golden Ratio Color System
 
 ### Design Principles