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

package/src/components/Card/Card.types.ts

@@ -1,8 +1,28 @@
+import type { ElementType } from 'react';
 import { CardRootProps as ChakraCardRootProps } from '@chakra-ui/react';
 
-export type CardVariant = 'default' | 'gradient';
+// Relative, NOT `@/types/*` — see `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
 
-export type CardProps = ChakraCardRootProps & {
+export type CardVariant = 'default' | 'wash' | 'elevated';
+
+export type CardOwnProps = Omit<ChakraCardRootProps, 'as'> & {
   clickable?: boolean;
   variant?: CardVariant;
 };
+
+/**
+ * Props for `Card`, typed for whatever element `as` renders.
+ *
+ * A `clickable` card is the case that needs this: the whole card is one target,
+ * so it should BE the link rather than contain one. Defaults to `'div'`, so
+ * bare `CardProps` is unchanged.
+ *
+ * ```tsx
+ * <Card clickable as={NextLink} href={`/courses/${id}`}>…</Card>
+ * ```
+ */
+export type CardProps<TElement extends ElementType = 'div'> = PolymorphicProps<
+  TElement,
+  CardOwnProps
+>;

package/src/components/Card/index.ts

@@ -1,2 +1,2 @@
 export { Card } from './Card';
-export type { CardProps } from './Card.types';
+export type { CardOwnProps, CardProps, CardVariant } from './Card.types';

package/src/components/Checkbox/Checkbox.styles.ts

@@ -0,0 +1,26 @@
+import type { SystemStyleObject } from '@chakra-ui/react';
+
+import { CHECKMARK_DASH } from '@/theme/motion';
+
+/**
+ * Strokes the checkmark on instead of flashing it in, one `motion.beat` after
+ * the box fills.
+ *
+ * Local rather than part of the shared vocabulary because it is sized to one
+ * icon: the dash is {@link CHECKMARK_DASH} user units, which covers Chakra's
+ * ~22.6-unit tick with a margin. Anything else drawing a path would need its
+ * own length, which is exactly the sign that this is a component's business
+ * rather than a preset everyone chooses from.
+ *
+ * An animation rather than a transition because the polyline only mounts once
+ * the box is checked — there is no previous value for a transition to run from.
+ */
+export const checkmarkDraw: SystemStyleObject = {
+  '& polyline, & path': {
+    strokeDasharray: CHECKMARK_DASH,
+    animation: `checkmark-draw var(--chakra-durations-moderate) var(--chakra-easings-emphasized) var(--chakra-durations-motion-beat) both`,
+  },
+  _motionReduce: {
+    '& polyline, & path': { animation: 'none', strokeDasharray: 'none' },
+  },
+};

package/src/components/Checkbox/CheckboxControl.tsx

@@ -4,32 +4,48 @@ import {
   CheckboxControlProps,
 } from '@chakra-ui/react';
 
+import { disabledControl } from '@/utils/disabledControl';
 import { focusRing } from '@/utils/focusRing';
 
+import { checkmarkDraw } from './Checkbox.styles';
+
 export const CheckboxControl = forwardRef<HTMLDivElement, CheckboxControlProps>(
   (props, ref) => (
     <ChakraCheckbox.Control
       ref={ref}
       borderRadius="xs"
-      // The unchecked box is border-only, so it needs a clearly visible outline.
-      // gray.500 in light; gray.800 in dark (border.strong's gray.900 was only
-      // 2.80:1 on canvas — gray.800 reaches the 3:1 non-text-contrast bar).
-      borderColor={{ base: 'gray.500', _dark: 'gray.800' }}
+      // The unchecked box is border-only, so it needs a clearly visible outline;
+      // border.control is the 3:1 non-text-contrast token built for exactly this
+      // (input/checkbox/radio borders), on the same raised surface as Input.
+      bg="bg.surface"
+      borderColor="border.control"
       borderWidth="1px"
-      _checked={{ bgColor: 'primary.main', borderColor: 'primary.main' }}
-      _indeterminate={{ bgColor: 'primary.main', borderColor: 'primary.main' }}
+      _checked={{
+        bgColor: 'primary.main',
+        borderColor: 'primary.main',
+        color: 'fg.onPrimary',
+      }}
+      _indeterminate={{
+        bgColor: 'primary.main',
+        borderColor: 'primary.main',
+        color: 'fg.onPrimary',
+      }}
       cursor="pointer"
       _disabled={{
+        ...disabledControl,
         cursor: 'not-allowed',
-        // Flip the disabled fill (was a flat light gray.300 that stayed bright
-        // on dark, unlike Input/Textarea whose disabled fills flip).
-        bgColor: { base: 'gray.300', _dark: 'gray.1200' },
-        borderColor: 'border.subtle',
       }}
+      // The box fills first, then the tick is stroked on 60ms later. Firing them
+      // together reads as one indistinct flash; the gap makes it two beats —
+      // "pressed", then "confirmed".
+      animationStyle="feedback"
+      transitionProperty="background-color, border-color"
       {...focusRing}
       {...props}
     >
-      <ChakraCheckbox.Indicator />
+      {/* The polyline only mounts once checked, so the draw runs on mount —
+          exactly when we want it. */}
+      <ChakraCheckbox.Indicator css={checkmarkDraw} />
     </ChakraCheckbox.Control>
   )
 );

package/src/components/Chip/Chip.stories.tsx

@@ -1,39 +1,22 @@
-import { Box, Flex, Text } from '@chakra-ui/react';
+import { Flex } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
-import { Chip, colorSchemes, variants } from '.';
+import { Chip } from '.';
 
 /**
- * A chip component for displaying tags, labels, or status indicators.
+ * **Deprecated since 5.0** — `Chip` is a thin alias of `Tag` and is removed in
+ * 6.0. These stories only show that unmigrated call sites still render; new
+ * code uses `Tag` (`tone`, `selected`, `category`).
  *
- * Uses a two-dimensional variant system:
- * - `colorScheme`: What semantic color (primary, secondary, danger, etc.)
- * - `variant`: How it looks visually (solid, soft, outline)
+ * Mapping: `outline` → neutral · `primary` + `solid` → `selected` ·
+ * `danger` / `success` / `warning` → that `tone` · everything else → neutral.
  */
 const meta = {
-  title: 'Components/Chip',
+  title: 'Components/Chip (deprecated)',
   component: Chip,
   tags: ['autodocs'],
   args: {
     children: 'Chip',
-    colorScheme: 'primary',
-    variant: 'soft',
-  },
-  argTypes: {
-    colorScheme: {
-      control: 'select',
-      options: colorSchemes,
-      description: 'The semantic color of the chip',
-    },
-    variant: {
-      control: 'select',
-      options: variants,
-      description: 'The visual style of the chip',
-    },
-    children: {
-      control: 'text',
-      description: 'The content of the chip',
-    },
   },
 } satisfies Meta<typeof Chip>;
 
@@ -41,223 +24,27 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-/**
- * Default chip with primary color and soft variant.
- */
 export const Default: Story = {};
 
-/**
- * Primary color chips in different variants.
- */
-export const Primary: Story = {
+/** 4.x props on the left of each pair render as the 5.0 Tag on the right. */
+export const LegacyMapping: Story = {
   render: () => (
-    <Flex gap={3} align="center">
-      <Chip colorScheme="primary" variant="solid">
-        Solid
-      </Chip>
+    <Flex gap={3} wrap="wrap" align="center">
       <Chip colorScheme="primary" variant="soft">
-        Soft
-      </Chip>
-      <Chip colorScheme="primary" variant="outline">
-        Outline
-      </Chip>
-    </Flex>
-  ),
-};
-
-/**
- * Secondary color chips in different variants.
- */
-export const Secondary: Story = {
-  render: () => (
-    <Flex gap={3} align="center">
-      <Chip colorScheme="secondary" variant="solid">
-        Solid
-      </Chip>
-      <Chip colorScheme="secondary" variant="soft">
-        Soft
-      </Chip>
-      <Chip colorScheme="secondary" variant="outline">
-        Outline
+        primary soft → neutral
       </Chip>
-    </Flex>
-  ),
-};
-
-/**
- * Danger color chips for error states.
- */
-export const Danger: Story = {
-  render: () => (
-    <Flex gap={3} align="center">
-      <Chip colorScheme="danger" variant="solid">
-        Error
+      <Chip colorScheme="primary" variant="solid">
+        primary solid → selected
       </Chip>
       <Chip colorScheme="danger" variant="soft">
-        Error
-      </Chip>
-      <Chip colorScheme="danger" variant="outline">
-        Error
+        danger → tone danger
       </Chip>
-    </Flex>
-  ),
-};
-
-/**
- * Success color chips for completed states.
- */
-export const Success: Story = {
-  render: () => (
-    <Flex gap={3} align="center">
       <Chip colorScheme="success" variant="solid">
-        Completed
-      </Chip>
-      <Chip colorScheme="success" variant="soft">
-        Completed
-      </Chip>
-      <Chip colorScheme="success" variant="outline">
-        Completed
-      </Chip>
-    </Flex>
-  ),
-};
-
-/**
- * Warning color chips for pending states.
- */
-export const Warning: Story = {
-  render: () => (
-    <Flex gap={3} align="center">
-      <Chip colorScheme="warning" variant="solid">
-        Pending
-      </Chip>
-      <Chip colorScheme="warning" variant="soft">
-        Pending
+        success → tone success
       </Chip>
       <Chip colorScheme="warning" variant="outline">
-        Pending
-      </Chip>
-    </Flex>
-  ),
-};
-
-/**
- * Neutral color chips for default states.
- */
-export const Neutral: Story = {
-  render: () => (
-    <Flex gap={3} align="center">
-      <Chip colorScheme="neutral" variant="solid">
-        Draft
-      </Chip>
-      <Chip colorScheme="neutral" variant="soft">
-        Draft
+        outline → neutral
       </Chip>
-      <Chip colorScheme="neutral" variant="outline">
-        Draft
-      </Chip>
-    </Flex>
-  ),
-};
-
-/**
- * Shows all combinations of colorScheme × variant in a matrix layout.
- */
-export const AllCombinations: Story = {
-  render: () => (
-    <Box>
-      {/* Header row */}
-      <Flex mb={4} gap={4} align="center">
-        <Box w="100px" />
-        {variants.map((variant) => (
-          <Box key={variant} w="100px" textAlign="center">
-            <Text fontWeight="bold" textStyle="subtext">
-              {variant}
-            </Text>
-          </Box>
-        ))}
-      </Flex>
-
-      {/* Color scheme rows */}
-      {colorSchemes.map((colorScheme) => (
-        <Flex key={colorScheme} mb={4} gap={4} align="center">
-          <Box w="100px">
-            <Text fontWeight="medium" textStyle="subtext">
-              {colorScheme}
-            </Text>
-          </Box>
-          {variants.map((variant) => (
-            <Box key={`${colorScheme}-${variant}`} w="100px" textAlign="center">
-              <Chip colorScheme={colorScheme} variant={variant}>
-                Chip
-              </Chip>
-            </Box>
-          ))}
-        </Flex>
-      ))}
-    </Box>
-  ),
-};
-
-/**
- * Chips in use cases with labels.
- */
-export const UseCases: Story = {
-  render: () => (
-    <Flex direction="column" gap={6}>
-      <Box>
-        <Text mb={2} fontWeight="bold">
-          Status indicators:
-        </Text>
-        <Flex gap={2} wrap="wrap">
-          <Chip colorScheme="success" variant="soft">
-            Active
-          </Chip>
-          <Chip colorScheme="warning" variant="soft">
-            Pending
-          </Chip>
-          <Chip colorScheme="danger" variant="soft">
-            Inactive
-          </Chip>
-          <Chip colorScheme="neutral" variant="soft">
-            Draft
-          </Chip>
-        </Flex>
-      </Box>
-
-      <Box>
-        <Text mb={2} fontWeight="bold">
-          Category tags:
-        </Text>
-        <Flex gap={2} wrap="wrap">
-          <Chip colorScheme="primary" variant="outline">
-            React
-          </Chip>
-          <Chip colorScheme="secondary" variant="outline">
-            TypeScript
-          </Chip>
-          <Chip colorScheme="success" variant="outline">
-            Chakra UI
-          </Chip>
-        </Flex>
-      </Box>
-
-      <Box>
-        <Text mb={2} fontWeight="bold">
-          Priority levels:
-        </Text>
-        <Flex gap={2} wrap="wrap">
-          <Chip colorScheme="danger" variant="solid">
-            High
-          </Chip>
-          <Chip colorScheme="warning" variant="solid">
-            Medium
-          </Chip>
-          <Chip colorScheme="neutral" variant="solid">
-            Low
-          </Chip>
-        </Flex>
-      </Box>
     </Flex>
   ),
 };

package/src/components/Chip/Chip.tsx

@@ -1,37 +1,50 @@
 import { ForwardedRef, forwardRef } from 'react';
-import { Badge as ChakraBadge } from '@chakra-ui/react';
 
-import { focusRing } from '@/utils/focusRing';
-
-import { baseStyles, getChipStyles } from './Chip.styles';
-import { ChipProps } from './Chip.types';
+import { polymorphic } from '../../types/polymorphic';
+import { Tag } from '../Tag/Tag';
+import { ChipOwnProps } from './Chip.types';
 
 /**
- * A chip component for displaying tags, labels, or status indicators.
- *
- * Uses a two-dimensional variant system:
- * - `colorScheme`: What semantic color (primary, secondary, danger, etc.)
- * - `variant`: How it looks visually (solid, soft, outline)
+ * @deprecated Since 5.0 `Chip` is a thin alias of `Tag` and will be removed in
+ * 6.0. Replace `<Chip colorScheme="danger" variant="soft">` with
+ * `<Tag tone="danger">`, a "solid" (primary / secondary / neutral) chip with
+ * `<Tag as="button" selected>`, and everything else with `<Tag>`. Full table:
+ * `mapLegacyTagProps`. Warns once per colorScheme × variant in development.
  *
- * @example
- * ```tsx
- * <Chip colorScheme="primary" variant="solid">Active</Chip>
- * <Chip colorScheme="danger" variant="soft">Error</Chip>
- * <Chip colorScheme="success" variant="outline">Completed</Chip>
- * ```
+ * The alias keeps Chip's pill shape (32px radius, roomier padding) so an
+ * unmigrated screen does not shift.
  */
-export const Chip = forwardRef(
+const ChipImpl = forwardRef(
   (
-    { colorScheme = 'primary', variant = 'soft', ...rest }: ChipProps,
-    ref?: ForwardedRef<HTMLButtonElement>
+    {
+      colorScheme,
+      colorPalette,
+      variant = 'soft',
+      tone,
+      selected,
+      ...rest
+    }: ChipOwnProps,
+    ref?: ForwardedRef<HTMLDivElement>
   ) => {
-    const styles = getChipStyles(colorScheme, variant);
-
+    // Tag owns the mapping (see `mapLegacyTagProps`) and the once-per-combo
+    // dev warning; Chip only supplies its 4.x defaults (primary / soft) and
+    // its name. Passing the pair through, rather than a mapped `selected`,
+    // keeps a "solid" Chip a selected *look* without turning it into a toggle.
+    const legacy = {
+      colorPalette: colorScheme ?? colorPalette ?? 'primary',
+      variant,
+      __legacyComponent: 'Chip',
+    } as object;
     return (
-      <ChakraBadge
-        {...baseStyles}
-        {...styles}
-        {...focusRing}
+      <Tag
+        borderRadius="32px"
+        px={3}
+        py={2}
+        fontWeight="medium"
+        textTransform="none"
+        tone={tone}
+        selected={selected}
+        {...legacy}
         {...rest}
         ref={ref}
       />
@@ -39,4 +52,11 @@ export const Chip = forwardRef(
   }
 );
 
-Chip.displayName = 'Chip';
+ChipImpl.displayName = 'Chip';
+
+/**
+ * @deprecated Use `Tag`. Removed in 6.0.
+ *
+ * Type-level polymorphism over the same runtime — see `polymorphic`.
+ */
+export const Chip = polymorphic<ChipOwnProps, 'span'>(ChipImpl);

package/src/components/Chip/Chip.types.ts

@@ -1,14 +1,13 @@
-import { BadgeProps as ChakraBadgeProps } from '@chakra-ui/react';
+import type { ElementType } from 'react';
+
+// Relative, NOT `@/types/*` — see `src/types/polymorphic.ts`.
+import type { PolymorphicProps } from '../../types/polymorphic';
+import type { TagOwnProps } from '../Tag/Tag.types';
 
 /**
- * Chip color schemes - determines the semantic color of the chip.
- *
- * This prop overrides Chakra UI's native `colorScheme` prop to provide
- * a controlled set of color options that align with our design system.
- *
- * @example
- * <Chip colorScheme="primary" variant="solid">Primary</Chip>
- * <Chip colorScheme="danger" variant="soft">Error</Chip>
+ * 4.x Chip colour schemes, mapped onto Tag at runtime.
+ * @deprecated `Chip` is now an alias of `Tag` — use `tone` / `selected` /
+ * `category` on `Tag`. Removed in 6.0.
  */
 export type ChipColorScheme =
   | 'primary'
@@ -19,25 +18,53 @@ export type ChipColorScheme =
   | 'neutral';
 
 /**
- * Chip variants - determines the visual style of the chip.
- *
- * - solid: Filled background with contrasting text
- * - soft: Light background tint with darker text
- * - outline: Transparent background with colored border
+ * 4.x Chip variants, mapped onto Tag at runtime.
+ * @deprecated Use `Tag`. Removed in 6.0.
  */
 export type ChipVariant = 'solid' | 'soft' | 'outline';
 
 /**
- * ChipProps uses a two-dimensional variant system:
- * - `colorScheme`: What semantic color (primary, secondary, danger, etc.)
- * - `variant`: How it looks visually (solid, soft, outline)
+ * @deprecated `Chip` is an alias of `Tag` since 5.0 — use `TagOwnProps`.
+ * Removed in 6.0.
+ *
+ * `colorScheme` / `variant` / `colorPalette` are still in the type ONLY so
+ * unmigrated 4.x call sites keep compiling; they are deprecated aliases,
+ * mapped at runtime by `mapLegacyTagProps` (with a once-per-combination dev
+ * warning) and removed with Chip in 6.0:
  *
- * This matches the Button component's architecture for consistency.
+ * - `primary` / `secondary` / `neutral` × `soft` (default) or `outline` → neutral
+ * - `primary` / `secondary` / `neutral` × `solid` → `selected` (look only — not
+ *   a toggle unless `selected` is passed explicitly)
+ * - `danger` / `success` / `warning` × `soft` → that `tone`
+ * - `danger` / `success` / `warning` × `solid` → that `tone` (no solid fill
+ *   in 5.0 — warns "choose by hand")
+ * - `danger` / `success` / `warning` × `outline` → neutral (warns "choose by hand")
+ *
+ * New Tag props (`tone`, `selected`, `category`) win when given.
  */
-export interface ChipProps extends Omit<
-  ChakraBadgeProps,
-  'colorScheme' | 'variant'
-> {
+export type ChipOwnProps = TagOwnProps & {
+  /**
+   * @deprecated 4.x alias, mapped at runtime — use Tag's `tone` / `selected`.
+   * Defaults to `primary` (the 4.x Chip default).
+   */
   colorScheme?: ChipColorScheme;
+  /**
+   * @deprecated 4.x alias, mapped at runtime — use Tag's `selected` (for
+   * `solid`) or nothing. Defaults to `soft`.
+   */
   variant?: ChipVariant;
-}
+  /**
+   * @deprecated 4.x alias of `colorScheme` (Chakra's palette prop), mapped
+   * at runtime. `colorScheme` wins when both are given.
+   */
+  colorPalette?: ChipColorScheme;
+};
+
+/**
+ * @deprecated `Chip` is an alias of `Tag` since 5.0 — use `TagProps`.
+ * Removed in 6.0.
+ */
+export type ChipProps<TElement extends ElementType = 'span'> = PolymorphicProps<
+  TElement,
+  ChipOwnProps
+>;

package/src/components/Chip/index.ts

@@ -1,8 +1,7 @@
 export { Chip } from './Chip';
-export {
-  colorSchemes,
-  colorSchemeStyles,
-  getChipStyles,
-  variants,
-} from './Chip.styles';
-export type { ChipColorScheme, ChipProps, ChipVariant } from './Chip.types';
+export type {
+  ChipColorScheme,
+  ChipOwnProps,
+  ChipProps,
+  ChipVariant,
+} from './Chip.types';

package/src/components/Code/Code.tsx

@@ -97,7 +97,7 @@ export const Code = ({
       cursor="pointer"
     >
       <ChakraCodeBlock.CopyIndicator
-        copied={<FaCheck color="success.main" boxSize="xs" />}
+        copied={<FaCheck color="success.fg" boxSize="xs" />}
       />
     </ChakraCodeBlock.CopyTrigger>
   ) : null;
@@ -157,13 +157,12 @@ export const Code = ({
                   : String(translate('copy'))
               }
               size="sm"
-              colorPalette="neutral"
               variant="ghost"
               color="fg.muted"
               onClick={handleOverlayCopy}
             >
               {isCopied ? (
-                <FaCheck color="success.main" boxSize="xs" />
+                <FaCheck color="success.fg" boxSize="xs" />
               ) : (
                 <FaRegCopy boxSize="xs" />
               )}