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

package/src/components/Button/Button.tsx

@@ -1,30 +1,101 @@
 import { forwardRef } from 'react';
-import { Button as ChakraButton } from '@chakra-ui/react';
+import { Button as ChakraButton, SystemStyleObject } from '@chakra-ui/react';
 
 import { focusRing } from '@/utils/focusRing';
+import { mergeCss } from '@/utils/mergeCss';
 
-import { getButtonStyles } from './Button.styles';
-import { ButtonProps } from './Button.types';
+import { polymorphic } from '../../types/polymorphic';
+import {
+  isLegacyButtonProps,
+  resolveLegacyButtonVariant,
+  warnLegacyButtonProps,
+} from './Button.legacy';
+import { buttonTransition, getButtonStyles } from './Button.styles';
+import { ButtonOwnProps, ButtonProps, ButtonVariant } from './Button.types';
 
 /**
- * Button component with two-dimensional variant system.
- *
- * Combines `colorPalette` (semantic color) with `variant` (visual appearance)
- * for flexible, consistent button styling.
+ * Button — one `variant` role per button (5.0 BAZE palette).
  *
  * @example
  * ```tsx
- * <Button colorPalette="primary" variant="soft">Submit</Button>
- * <Button colorPalette="danger" variant="solid">Delete</Button>
- * <Button colorPalette="secondary" variant="outline">Cancel</Button>
- * <Button colorPalette="neutral" variant="ghost">Close</Button>
+ * <Button variant="primary">저장</Button>
+ * <Button variant="secondary">취소</Button>
+ * <Button>더 보기</Button> // subtle
+ * <Button variant="ghost" isDestructive>삭제</Button>
+ * <Button variant="danger">영구 삭제</Button>
+ * <Button variant="action"><Sparkles />실행</Button> // coral icon
+ * <Button variant="primary" lift>Get started</Button>
+ *
+ * // `as` carries the element's own props (see Button.types.ts):
+ * <Button as="a" href="/docs" target="_blank">문서</Button>
  * ```
  */
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ colorPalette, variant = 'soft', size, children, ...rest }, ref) => {
-    const palette = colorPalette ?? 'primary';
+const ButtonImpl = forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      variant: variantProp,
+      isDestructive: isDestructiveProp = false,
+      size,
+      lift,
+      children,
+      _hover: hoverProp,
+      _active: activeProp,
+      _disabled: disabledProp,
+      css: cssProp,
+      ...restWithLegacy
+    },
+    ref
+  ) => {
+    // 4.x callers (untyped JS, `as any`) can still hand us `colorPalette` and
+    // an old variant name. Strip it so it never reaches Chakra's own recipe,
+    // and map the pair onto a 5.0 role — see `Button.legacy.ts`.
+    const { colorPalette: legacyPalette, ...rest } =
+      restWithLegacy as typeof restWithLegacy & { colorPalette?: unknown };
+
+    let variant: ButtonVariant = variantProp ?? 'subtle';
+    let isDestructive = isDestructiveProp;
+    if (isLegacyButtonProps('button', legacyPalette, variantProp)) {
+      const resolved = resolveLegacyButtonVariant(
+        'button',
+        legacyPalette,
+        variantProp
+      );
+      warnLegacyButtonProps('Button', legacyPalette, variantProp, resolved);
+      variant = resolved.variant;
+      isDestructive = isDestructive || resolved.isDestructive;
+    }
+
+    const base = getButtonStyles(variant, isDestructive);
 
-    const styles = getButtonStyles(palette, variant);
+    // Merged rather than spread after: each variant already owns `_hover` and
+    // `_active` for its colours, and replacing either would drop them.
+    const styles = lift
+      ? {
+          ...base,
+          _hover: {
+            ...base._hover,
+            translate: '0 -1px',
+            // `drop-shadow`, not `box-shadow`. The keyboard focus ring is a
+            // box-shadow, and Chakra emits `:hover` after `:focus-visible`, so
+            // a focused button being hovered would lose its ring to this. A
+            // different property cannot collide with it at all — and unlike a
+            // box-shadow it follows the border radius for free.
+            filter: 'drop-shadow(0 3px 6px rgba(0, 0, 0, 0.18))',
+            // A black shadow does nothing on a dark canvas; deepen it there.
+            _dark: { filter: 'drop-shadow(0 3px 8px rgba(0, 0, 0, 0.55))' },
+          },
+          // Pressing puts it back on the surface, under the `scale`.
+          _active: { ...base._active, translate: '0 0', filter: 'none' },
+          // `:hover` still matches a disabled button, so the lift has to be
+          // switched off here rather than left to pointer-events.
+          // Merged so the variant's fixed disabled colours survive.
+          _disabled: {
+            ...(base._disabled as object),
+            translate: '0 0',
+            filter: 'none',
+          },
+        }
+      : base;
 
     /**
      * Chakra Button automatically maps size prop to textStyle:
@@ -44,13 +115,44 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
         size={size}
         borderRadius="md"
         {...styles}
+        // Merged, not left to `{...rest}`. A prop spread later replaces the
+        // whole object, so a call site adding one line — the 2px press ledge
+        // FactChat puts on its quiz buttons — used to silently drop the
+        // variant's pressed colour *and* the scale with it, and the button
+        // stopped reading as pressed at all. Its own keys still win; it just
+        // no longer erases the ones it did not mention. Deep, so a nested
+        // condition (lift's `_hover._dark`) survives a call site's own `_dark`.
+        _hover={mergeCss(styles._hover, hoverProp)}
+        _active={mergeCss(styles._active, activeProp)}
+        // `cursor` is a style prop, so it lands outside Chakra's
+        // `@layer recipes` and beat the recipe's disabled cursor — every
+        // disabled Button showed a pointer and read as clickable. The
+        // disabled cursor has to sit at this level, merged like the two above
+        // so a call site's `_disabled` cannot drop it.
+        _disabled={mergeCss(
+          '_disabled' in styles ? styles._disabled : undefined,
+          // Chakra disables a `loading` button too; it is working, not
+          // forbidden, so it gets `progress`.
+          { cursor: rest.loading ? 'progress' : 'not-allowed' },
+          disabledProp
+        )}
         {...focusRing}
         cursor="pointer"
-        transitionProperty="all"
-        transitionDuration="0.25s"
-        transitionTimingFunction="ease-in-out"
+        // Explicit identity so the press transitions from a definite value
+        // rather than relying on `scale: none` being read as 1.
+        scale="1"
+        // Two clocks on one element — the press is faster than the colour
+        // change — so the shorthand is written out and only the reduced-motion
+        // guard comes from the vocabulary.
+        transition={buttonTransition}
+        animationStyle="composite"
         ref={ref}
+        data-variant={variant}
+        data-destructive={isDestructive || undefined}
         {...rest}
+        // The `action` icon rule lives in `css` (a nested selector cannot be a
+        // style prop); merged so a call site's `css` adds to it.
+        css={mergeCss(base.css as SystemStyleObject | undefined, cssProp)}
       >
         {children}
       </ChakraButton>
@@ -58,4 +160,13 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
   }
 );
 
-Button.displayName = 'Button';
+/**
+ * Type-level polymorphism over the same runtime — see `polymorphic` in
+ * `src/types/polymorphic.ts` for what the cast does and why it is needed.
+ *
+ * `as` defaults to `'button'`, so nothing that already compiles stops
+ * compiling.
+ */
+ButtonImpl.displayName = 'Button';
+
+export const Button = polymorphic<ButtonOwnProps>(ButtonImpl);

package/src/components/Button/Button.types.ts

@@ -1,17 +1,46 @@
+import type { ElementType } from 'react';
 import { ButtonProps as ChakraButtonProps } from '@chakra-ui/react';
 
+// Relative, NOT `@/types/polymorphic`. Path aliases survive into the emitted
+// `.d.ts`, where they are resolved against the CONSUMER's tsconfig — so an app
+// with its own `@/*` alias either binds this to its own file or fails to
+// resolve it and silently degrades the type to `any`. Measured: with the alias,
+// `<Button as="a" nonsense={1}>` stopped erroring in FactChat. See the PR body.
+import type { PolymorphicProps } from '../../types/polymorphic';
+
 /**
- * Button color palette - defines the semantic color family.
+ * Button variant — one role per value (5.0 BAZE palette).
+ *
+ * Overrides Chakra UI's `variant` prop; Chakra's own variants are not supported.
+ * There is no separate colour axis any more: the role *is* the colour.
  *
- * This overrides Chakra UI's colorPalette prop with our Golden Ratio
- * color system values. Chakra's default colorPalettes are not supported.
+ * - `primary`: BAZE black fill — the one main action of a screen
+ * - `action`: black "run" button whose icon is coral (`action.iconOnSolid`)
+ * - `secondary`: outlined surface button — cancel, alternative actions
+ * - `subtle`: quiet warm-wash fill — low-emphasis actions (the default)
+ * - `ghost`: no fill, no border — toolbars, inline actions
+ * - `danger`: red fill — a confirmed destructive action
  *
- * - `primary`: Blue - main brand actions, CTAs
- * - `secondary`: Violet - accent actions, highlights
- * - `danger`: Rose - destructive actions, errors
- * - `success`: Green - positive actions, confirmations
- * - `warning`: Gold - caution actions, alerts
- * - `neutral`: Gray - low-emphasis, tertiary actions
+ * For a *secondary* destructive action (a "delete" link-ish button next to a
+ * form) keep `secondary`/`ghost`/`subtle` and add `isDestructive`.
+ */
+export type ButtonVariant =
+  | 'primary'
+  | 'action'
+  | 'secondary'
+  | 'subtle'
+  | 'ghost'
+  | 'danger';
+
+/**
+ * @deprecated 5.0 removed the colour axis — `colorPalette` is no longer a
+ * Button prop. Pick a `variant` role instead (and `isDestructive` for a
+ * danger-coloured secondary/ghost/subtle button). Kept only so existing type
+ * imports get a deprecation instead of a hard error; will be removed in 6.0.
+ *
+ * Old → new: `primary|neutral` + `solid` → `primary`; `danger` + `solid` →
+ * `danger`; any + `outline` → `secondary`; any + `soft` → `subtle`;
+ * `danger` + `outline|ghost|soft` → same role + `isDestructive`.
  */
 export type ButtonColorPalette =
   | 'primary'
@@ -22,49 +51,78 @@ export type ButtonColorPalette =
   | 'neutral';
 
 /**
- * Button variant - defines the visual appearance/fill style.
- *
- * This overrides Chakra UI's variant prop with our custom variants.
- * Chakra's default variants (solid, outline, ghost, link) are replaced
- * with our Golden Ratio-based styling system.
- *
- * - `solid`: Filled background with contrasting text (most prominent)
- * - `soft`: Light tinted background with darker text (subtle)
- * - `outline`: Transparent with colored border (medium emphasis)
- * - `ghost`: Transparent with no border (lowest emphasis)
+ * @deprecated 4.x variant names. Still accepted at runtime (mapped, with a
+ * development warning) but no longer part of `ButtonVariant`.
  */
-export type ButtonVariant = 'solid' | 'soft' | 'outline' | 'ghost';
+export type LegacyButtonVariant = 'solid' | 'soft' | 'outline' | 'ghost';
 
 /**
- * Button props with two-dimensional variant system.
+ * Button props.
  *
- * Combines `colorPalette` (what color) with `variant` (how it looks)
- * for flexible, consistent button styling.
- *
- * @note Overrides Chakra UI's `variant` and `colorPalette` props.
- *       Chakra's default values are not supported.
+ * @note Overrides Chakra UI's `variant`; Chakra's `colorPalette` /
+ *       `colorScheme` are not accepted.
  *
  * @example
  * ```tsx
- * <Button colorPalette="primary" variant="solid">Submit</Button>
- * <Button colorPalette="danger" variant="soft">Delete</Button>
- * <Button colorPalette="secondary" variant="outline">Cancel</Button>
+ * <Button variant="primary">저장</Button>
+ * <Button variant="secondary">취소</Button>
+ * <Button variant="ghost" isDestructive>삭제</Button>
+ * <Button variant="danger">영구 삭제</Button>
  * ```
  */
-export type ButtonProps = Omit<
+export type ButtonOwnProps = Omit<
   ChakraButtonProps,
-  'variant' | 'colorScheme' | 'colorPalette' | 'leftIcon' | 'rightIcon'
+  'variant' | 'colorScheme' | 'colorPalette' | 'leftIcon' | 'rightIcon' | 'as'
 > & {
   /**
-   * The color palette of the button (semantic color family).
-   * Overrides Chakra UI's colorPalette prop (Chakra v3).
-   * @default 'primary'
-   */
-  colorPalette?: ButtonColorPalette;
-  /**
-   * The visual variant of the button (fill style).
+   * The role of the button (fill, border and text colour together).
    * Overrides Chakra UI's variant prop.
-   * @default 'solid'
+   * @default 'subtle'
    */
   variant?: ButtonVariant;
+  /**
+   * Danger-coloured text (`danger.fg`) for a destructive action that does not
+   * deserve a red fill. Applies to `secondary`, `ghost` and `subtle`; the
+   * border and fill stay the variant's own. Ignored on `primary`, `action` and
+   * `danger` (use `variant="danger"` for a filled destructive button).
+   * @default false
+   */
+  isDestructive?: boolean;
+  /**
+   * Raises the button 1px on hover and puts a shadow under it, so it reads as
+   * lifting toward the pointer. Pressing sets it back down, under the existing
+   * `scale` press.
+   *
+   * Off by default and deliberately opt-in: a lift is emphasis, and a form of
+   * six buttons all lifting is noise. Use it where one button is the point of
+   * the screen — a primary call to action, a card that is itself a button — not
+   * as a house style.
+   *
+   * The shadow yields to the keyboard focus ring, which is also a `box-shadow`;
+   * a focused button that is also hovered keeps its ring and still lifts.
+   *
+   * @default false
+   */
+  lift?: boolean;
 };
+
+/**
+ * Props for `Button`, typed for whatever element `as` renders.
+ *
+ * Defaults to `'button'`, so `ButtonProps` on its own means exactly what it
+ * meant before this became polymorphic — every existing call site and every
+ * `ComponentProps<typeof Button>` keeps its type.
+ *
+ * `as` now carries the element's own props with it:
+ *
+ * ```tsx
+ * <Button as="a" href="/docs" target="_blank" rel="noreferrer">문서</Button>
+ * <Button as={Link} href="/admin" prefetch={false}>관리자</Button>
+ * ```
+ *
+ * Before, `as` swapped the rendered element but not the type — `href` was not a
+ * `<button>` prop, so consumers reached for `@ts-expect-error`. See
+ * `src/types/polymorphic.ts` for why `asChild` does not cover this case.
+ */
+export type ButtonProps<TElement extends ElementType = 'button'> =
+  PolymorphicProps<TElement, ButtonOwnProps>;

package/src/components/Button/Button.variants.test.tsx

@@ -0,0 +1,149 @@
+import { ChakraProvider } from '@chakra-ui/react';
+import { render, screen } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { system } from '../../theme';
+import { IconButton } from '../IconButton';
+import { getIconButtonStyles } from '../IconButton/IconButton.styles';
+import { Button } from './Button';
+import {
+  __resetLegacyButtonWarnings,
+  resolveLegacyButtonVariant,
+} from './Button.legacy';
+import { buttonVariantStyles, getButtonStyles } from './Button.styles';
+
+/**
+ * 5.0 API: one `variant` role, `isDestructive` for danger text, and runtime
+ * mapping of the removed 4.x `colorPalette × variant` pair.
+ */
+const wrap = (ui: React.ReactNode) =>
+  render(<ChakraProvider value={system}>{ui}</ChakraProvider>);
+
+describe('Button variants (5.0)', () => {
+  it("defaults to 'subtle'", () => {
+    wrap(<Button>A</Button>);
+    expect(screen.getByRole('button').dataset.variant).toBe('subtle');
+  });
+
+  it.each(Object.keys(buttonVariantStyles))('renders %s', (variant) => {
+    wrap(<Button variant={variant as never}>A</Button>);
+    expect(screen.getByRole('button').dataset.variant).toBe(variant);
+  });
+
+  it('reads no raw palette scales', () => {
+    const raw = JSON.stringify(buttonVariantStyles);
+    expect(raw).not.toMatch(/"(blue|violet|rose|gold|green|gray)\.\d/);
+  });
+
+  it('isDestructive recolours text on secondary/ghost/subtle only', () => {
+    expect(getButtonStyles('secondary', true).color).toBe('danger.fg');
+    expect(getButtonStyles('ghost', true).color).toBe('danger.fg');
+    expect(getButtonStyles('subtle', true).color).toBe('danger.fg');
+    // border stays the variant's own
+    expect(getButtonStyles('secondary', true).borderColor).toBe(
+      'border.default'
+    );
+    expect(getButtonStyles('primary', true).color).toBe('fg.onPrimary');
+    expect(getButtonStyles('danger', true).color).toBe('danger.onSolid');
+  });
+
+  it('disabled is a fixed colour pair, not opacity', () => {
+    expect(buttonVariantStyles.primary._disabled).toMatchObject({
+      bg: 'disabled.bg',
+      color: 'disabled.fg',
+      opacity: 1,
+    });
+    expect(buttonVariantStyles.ghost._disabled).toMatchObject({
+      bg: 'transparent',
+      color: 'disabled.fg',
+    });
+  });
+});
+
+describe('legacy 4.x props', () => {
+  let warn: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    __resetLegacyButtonWarnings();
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+  afterEach(() => warn.mockRestore());
+
+  it('danger/outline renders as secondary + destructive, and warns once', () => {
+    const legacy = { colorPalette: 'danger', variant: 'outline' } as any;
+    wrap(
+      <>
+        <Button {...legacy}>삭제</Button>
+        <Button {...legacy}>삭제</Button>
+      </>
+    );
+    const [first] = screen.getAllByRole('button');
+    expect(first.dataset.variant).toBe('secondary');
+    expect(first.dataset.destructive).toBe('true');
+    // never forwarded to the DOM / Chakra
+    expect(first.getAttribute('colorpalette')).toBeNull();
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('maps the codemod table', () => {
+    const m = (p: unknown, v: unknown, k: 'button' | 'icon' = 'button') => {
+      const r = resolveLegacyButtonVariant(k, p, v);
+      return `${r.variant}${r.isDestructive ? '+d' : ''}`;
+    };
+    expect(m(undefined, 'solid')).toBe('primary');
+    expect(m('neutral', 'solid')).toBe('primary');
+    expect(m('danger', 'solid')).toBe('danger');
+    expect(m('neutral', 'outline')).toBe('secondary');
+    expect(m('primary', 'ghost')).toBe('ghost');
+    expect(m('danger', 'ghost')).toBe('ghost+d');
+    expect(m('danger', 'soft')).toBe('subtle+d');
+    expect(m('primary', 'soft')).toBe('subtle');
+    expect(m('primary', undefined)).toBe('subtle');
+    expect(
+      resolveLegacyButtonVariant('button', 'warning', 'solid').needsHuman
+    ).toBe(true);
+    expect(m('danger', 'soft', 'icon')).toBe('ghost+d');
+    expect(m('neutral', 'ghost', 'icon')).toBe('ghost');
+    expect(m(undefined, undefined, 'icon')).toBe('ghost');
+  });
+
+  it('a new variant with no colorPalette does not warn', () => {
+    wrap(<Button variant="primary">A</Button>);
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
+
+describe('IconButton variants (5.0)', () => {
+  it("defaults to 'ghost' with fg.icon", () => {
+    wrap(
+      <IconButton aria-label="x">
+        <svg />
+      </IconButton>
+    );
+    expect(screen.getByRole('button').dataset.variant).toBe('ghost');
+    expect(getIconButtonStyles().color).toBe('fg.icon');
+  });
+
+  it('action is the coral send button', () => {
+    wrap(
+      <IconButton aria-label="send" variant="action">
+        <svg />
+      </IconButton>
+    );
+    expect(screen.getByRole('button').dataset.variant).toBe('action');
+    expect(getIconButtonStyles('action').bgColor).toBe('send.bg');
+    expect(getIconButtonStyles('action').color).toBe('send.fg');
+  });
+
+  it('legacy danger colorPalette maps to ghost + destructive', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    wrap(
+      <IconButton aria-label="x" {...({ colorPalette: 'danger' } as any)}>
+        <svg />
+      </IconButton>
+    );
+    const button = screen.getByRole('button');
+    expect(button.dataset.variant).toBe('ghost');
+    expect(button.dataset.destructive).toBe('true');
+    warn.mockRestore();
+  });
+});

package/src/components/Button/index.tsx

@@ -3,10 +3,13 @@ export {
   buttonColorPalettes,
   buttonColorPaletteStyles,
   buttonVariants,
+  buttonVariantStyles,
   getButtonStyles,
 } from './Button.styles';
 export type {
   ButtonColorPalette,
+  ButtonOwnProps,
   ButtonProps,
   ButtonVariant,
+  LegacyButtonVariant,
 } from './Button.types';

package/src/components/Card/Card.stories.tsx

@@ -16,9 +16,39 @@ type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
 
-export const Gradient: Story = {
+export const Wash: Story = {
   args: {
-    variant: 'gradient',
-    children: 'Gradient Card',
+    variant: 'wash',
+    children: 'Wash Card',
   },
 };
+
+export const Elevated: Story = {
+  args: {
+    variant: 'elevated',
+    children: 'Elevated Card',
+  },
+};
+
+/**
+ * `as` swaps the rendered element **and** the props it accepts.
+ *
+ * A card whose whole surface is one target should *be* the control, not a
+ * `<div>` with an `onClick`. As a `<button>` it lands in the tab order,
+ * announces as a button, and responds to Enter and Space for free — none of
+ * which a click handler on a `<div>` gives you.
+ *
+ * `type="button"` below is a `<button>` prop, and it type-checks because
+ * `as="button"` carried it in. Pass it whenever you do this: a `<button>` with
+ * no `type` defaults to `submit`, so a card that later lands inside a form
+ * would submit it.
+ */
+export const AsButton: Story = {
+  args: {
+    clickable: true,
+    children: '눌러서 자세히 보기',
+  },
+  render: (args) => (
+    <Card {...args} as="button" type="button" textAlign="left" />
+  ),
+};

package/src/components/Card/Card.styles.ts

@@ -2,18 +2,43 @@
  * Card styles using the Golden Ratio color system.
  */
 
+/**
+ * The clickable hover is flat: the ground steps one tier to `bg.subtle` and
+ * the border darkens to `border.strong`. Nothing lifts and nothing grows a
+ * shadow. A raised hover said "this floats", and a card in a list does not;
+ * the tier step and the border say "this is the one under the pointer" with
+ * no elevation, and both tokens invert, so the state reads in dark mode where
+ * a neutral tint would vanish.
+ */
 export const clickableStyles = {
   cursor: 'pointer',
   _hover: {
-    boxShadow: 'lg',
+    bg: 'bg.subtle',
+    borderColor: 'border.strong',
   },
 };
 
+/**
+ * The wash card: a neutral `bg.muted` ground, borderless. For a block that
+ * summarises or concludes (an AI summary, a total after a purchase, the
+ * invitation being accepted) — the wash alone separates it from the page, so
+ * it does not need a hairline on top of it. (Not the sand `secondary.surface`:
+ * that tint reads peach as a background and is accent-only.)
+ */
+const washStyles = {
+  bg: 'bg.muted',
+  borderColor: 'transparent',
+};
+
 export const variantStyles = {
   default: {},
-  gradient: {
-    bg: 'linear-gradient(180deg, var(--chakra-colors-bg-subtle) 0%, var(--chakra-colors-bg-surface) 100%)',
-    border: '1px solid',
-    borderColor: 'primary.light',
+  wash: washStyles,
+  // Soft resting elevation — a gentle shadow does the separating, so the border
+  // can soften to `border.subtle` (which alone would be too faint, especially in
+  // dark mode). Use for standalone content cards that should read as raised
+  // objects rather than flat framed boxes.
+  elevated: {
+    boxShadow: 'sm',
+    borderColor: 'border.subtle',
   },
 };

package/src/components/Card/Card.tsx

@@ -1,10 +1,11 @@
 import { forwardRef } from 'react';
 import { Card as ChakraCard } from '@chakra-ui/react';
 
+import { polymorphic } from '../../types/polymorphic';
 import { clickableStyles, variantStyles } from './Card.styles';
-import { CardProps } from './Card.types';
+import { CardOwnProps } from './Card.types';
 
-export const Card = forwardRef<HTMLDivElement, CardProps>(
+const CardImpl = forwardRef<HTMLDivElement, CardOwnProps>(
   ({ clickable, variant = 'default', _hover, ...rest }, ref) => {
     const mergedHover = clickable
       ? { ...clickableStyles._hover, ..._hover }
@@ -18,15 +19,13 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
         color="fg.default"
         boxShadow="none"
         border="1px solid"
-        // border.default (gray.300 / gray.1100 _dark) instead of border.subtle:
-        // subtle's _dark (gray.1300 #1E2433) is ~invisible on bg.surface in dark,
-        // so cards blended into the canvas. default gives the card a discernible
-        // edge in both modes. The `gradient` variant keeps its primary.light border.
-        borderColor="border.default"
+        borderColor="border.subtle"
         borderRadius="lg"
+        // Was `transitionDuration="normal"` — a Chakra v2 token absent from v3.
+        // It fell through as a literal, `transition-duration: normal` is invalid
+        // CSS, and the whole declaration was dropped, so hover never transitioned.
+        animationStyle="feedback"
         transitionProperty="common"
-        transitionDuration="normal"
-        transitionTimingFunction="ease"
         p={8}
         {...(clickable ? { cursor: clickableStyles.cursor } : {})}
         {...variantStyles[variant]}
@@ -37,4 +36,7 @@ export const Card = forwardRef<HTMLDivElement, CardProps>(
   }
 );
 
-Card.displayName = 'Card';
+/** Type-level polymorphism over the same runtime — see the note on `Button`. */
+CardImpl.displayName = 'Card';
+
+export const Card = polymorphic<CardOwnProps, 'div'>(CardImpl);