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

package/src/components/Button/Button.styles.ts

@@ -4,6 +4,60 @@ import { ButtonColorPalette, ButtonVariant } from './Button.types';
 
 type StyleProps = Partial<ChakraButtonProps>;
 
+/**
+ * The press is timed apart from everything else.
+ *
+ * This used to be `transitionProperty="all"` at a flat `0.25s`, which put the
+ * press on the same 250ms clock as a colour change. A press has to read as
+ * *contact* — the finger is already gone by 250ms and the button is still
+ * sinking — so it takes `motion.press` (120ms) while colour, border and shadow
+ * keep the slower step, since those are feedback rather than touch.
+ *
+ * ## Why the press uses `scale`, not `transform: scale()`
+ *
+ * `transform` is a single property, so a `_active` of `transform: scale(0.97)`
+ * *replaced* whatever transform the call site had set — and call sites use it
+ * for layout. `CopyableCode` centres its button with `translateY(-50%)`, so
+ * pressing it dropped the button half its own height, and once `transform` was
+ * being transitioned that drop became a visible slide.
+ *
+ * The individual `scale` property composes with `transform` instead of
+ * overwriting it, so a consumer can position with `transform` and still get the
+ * press. Anything that presses should use `scale`, never `transform: scale()`.
+ *
+ * Naming the properties also stops `all` from animating things nobody asked it
+ * to (width, padding) when a consumer changes them on hover.
+ */
+const PRESS = 'var(--chakra-durations-motion-press)';
+const FEEDBACK = 'var(--chakra-durations-fast)';
+const STANDARD = 'var(--chakra-easings-standard)';
+// The press is contact, so it eases out: `standard` starts slowly and the
+// first frames lag behind the finger.
+const EMPHASIZED = 'var(--chakra-easings-emphasized)';
+
+export const buttonTransition = [
+  `scale ${PRESS} ${EMPHASIZED}`,
+  ...[
+    'background-color',
+    'border-color',
+    'color',
+    // No `box-shadow`: no variant sets one, so the only box-shadow that ever
+    // changes here is the keyboard focus ring, and that should appear at once.
+    'opacity',
+    // Both moved by `lift`, listed unconditionally because a property nobody
+    // changes costs nothing, and leaving them out would make the opt-in jump.
+    'translate',
+    // Nothing here sets `transform` — the press deliberately uses `scale` so it
+    // cannot clobber a call site. But call sites do set it (a 2px press ledge,
+    // an icon nudge), and under the old `transitionProperty: all` those moved
+    // smoothly. Naming the properties took that away and left them snapping,
+    // which is a regression the call site cannot see in this file. Listing it
+    // costs nothing while we set it nowhere.
+    'transform',
+    'filter',
+  ].map((property) => `${property} ${FEEDBACK} ${STANDARD}`),
+].join(', ');
+
 /**
  * Two-dimensional Button styles using the Golden Ratio color system.
  *
@@ -42,20 +96,24 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'blue.700',
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     soft: {
-      borderColor: 'transparent',
+      // Same-hue hairline so soft reads as a defined control on white, not a
+      // floating fill. `lighter` sits well below `outline`'s `.main` border, so
+      // soft stays the quieter of the two bordered variants; it also equals the
+      // hover/active fill, so the border melts into the fill on interaction.
+      borderColor: 'primary.lighter',
       bgColor: 'primary.extralight', // #E8EEFB
       color: 'primary.dark', // #0D317D
       _hover: {
-        borderColor: 'transparent',
+        borderColor: 'primary.lighter',
         bgColor: 'primary.lighter', // #B9CBF3
       },
       _active: {
         bgColor: 'primary.lighter', // #B9CBF3 — same as hover, scale provides pressed feedback
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     outline: {
@@ -67,7 +125,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'primary.lighter', // #B9CBF3
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     ghost: {
@@ -79,7 +137,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'primary.lighter', // #B9CBF3
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
   },
@@ -98,20 +156,20 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'violet.700',
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     soft: {
-      borderColor: 'transparent',
+      borderColor: 'secondary.lighter',
       bgColor: 'secondary.extralight', // #F4E8FB
       color: 'secondary.dark', // #570D7D
       _hover: {
-        borderColor: 'transparent',
+        borderColor: 'secondary.lighter',
         bgColor: 'secondary.lighter', // #DEB9F3
       },
       _active: {
         bgColor: 'secondary.lighter', // #DEB9F3 — same as hover, scale provides pressed feedback
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     outline: {
@@ -123,7 +181,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'secondary.lighter', // #DEB9F3
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     ghost: {
@@ -135,7 +193,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'secondary.lighter', // #DEB9F3
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
   },
@@ -154,20 +212,20 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'rose.700',
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     soft: {
-      borderColor: 'transparent',
+      borderColor: 'danger.lighter',
       bgColor: 'danger.extralight', // #FBE8E9
       color: 'danger.dark', // #7D0D14
       _hover: {
-        borderColor: 'transparent',
+        borderColor: 'danger.lighter',
         bgColor: 'danger.lighter', // #F3B9BD
       },
       _active: {
         bgColor: 'danger.lighter', // #F3B9BD — same as hover, scale provides pressed feedback
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     outline: {
@@ -179,7 +237,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'danger.lighter', // #F3B9BD
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     ghost: {
@@ -191,7 +249,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'danger.lighter', // #F3B9BD
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
   },
@@ -210,20 +268,20 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'green.800',
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     soft: {
-      borderColor: 'transparent',
+      borderColor: 'success.lighter',
       bgColor: 'success.extralight', // #E9FBE8
       color: 'success.dark', // #147D0D
       _hover: {
-        borderColor: 'transparent',
+        borderColor: 'success.lighter',
         bgColor: 'success.lighter', // #BDF3B9
       },
       _active: {
         bgColor: 'success.lighter', // #BDF3B9 — same as hover, scale provides pressed feedback
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     outline: {
@@ -235,7 +293,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'success.lighter', // #BDF3B9
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     ghost: {
@@ -247,7 +305,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'success.lighter', // #BDF3B9
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
   },
@@ -269,20 +327,20 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'gold.600',
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     soft: {
-      borderColor: 'transparent',
+      borderColor: 'warning.lighter',
       bgColor: 'warning.extralight', // #FBF6E8
       color: 'warning.dark', // #7D610D
       _hover: {
-        borderColor: 'transparent',
+        borderColor: 'warning.lighter',
         bgColor: 'warning.lighter', // #F3E4B9
       },
       _active: {
         bgColor: 'warning.lighter', // #F3E4B9 — same as hover, scale provides pressed feedback
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     outline: {
@@ -294,7 +352,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'warning.lighter', // #F3E4B9
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     ghost: {
@@ -306,7 +364,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'warning.lighter', // #F3E4B9
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
   },
@@ -315,33 +373,57 @@ export const buttonColorPaletteStyles: Record<
    * Neutral (Gray) color scheme
    */
   neutral: {
+    /**
+     * The INK action — the one high-emphasis fill in the system with no hue.
+     *
+     * Was `gray.700` under a white label, which failed AA in **both** modes and
+     * failed worse in the one nobody screenshots: white on `#737D96` measures
+     * **4.12:1** in light, and the semantic gray scale inverts, so in dark the
+     * same token resolves to `grayDark.fg700` `#8D919D` and the label lands at
+     * **3.15:1**. This was the only palette x variant combination in the system
+     * below the 4.5:1 text gate.
+     *
+     * "One step darker" does not fix it — `gray.800` is 5.32:1 light but
+     * **3.08:1** dark, i.e. worse, because darkening the light arm lightens the
+     * dark one. A neutral fill has to INVERT, not shift, which is exactly what
+     * `bg.inverse` / `fg.inverse` already do: ink under a near-white label on a
+     * light page, brand paper under an ink label on a dark one. Measured
+     * **15.11:1** and **15.88:1**, with the fill itself 15.49:1 / 16.36:1 clear
+     * of its canvas so it still reads as a control.
+     *
+     * `gray.1200` / `gray.1100` for hover and active for the same reason: both
+     * step AWAY from the resting fill toward the page in whichever mode is
+     * live, because they invert too. Labels stay 10.8:1 or better throughout.
+     */
     solid: {
-      borderColor: 'gray.700',
-      bgColor: 'gray.700', // #737D96
-      color: 'white',
+      borderColor: 'bg.inverse',
+      bgColor: 'bg.inverse',
+      color: 'fg.inverse',
       _hover: {
-        borderColor: 'gray.800',
-        bgColor: 'gray.800', // #616B85
+        borderColor: 'gray.1200',
+        bgColor: 'gray.1200',
       },
       _active: {
-        bgColor: 'gray.900', // #505A74
-        transform: 'scale(0.97)',
+        bgColor: 'gray.1100',
+        scale: '0.97',
       },
     },
     soft: {
-      borderColor: 'transparent',
+      // `border.default` (not a gray tint) so the neutral hairline stays visible
+      // in dark mode, where `border.subtle` collapses into the fill.
+      borderColor: 'border.default', // gray.300 / gray.1100 (_dark)
       // Neutral fills flip with the mode (light values preserved: bg.subtle →
       // gray.50, bg.muted → gray.100). Without this the surface stayed light in
       // dark mode while the fg.default text flipped to light = invisible.
       bgColor: 'bg.subtle', // gray.50 / gray.1300 (_dark)
       color: 'fg.default',
       _hover: {
-        borderColor: 'transparent',
+        borderColor: 'border.default',
         bgColor: 'bg.muted', // gray.100 / gray.1200 (_dark)
       },
       _active: {
         bgColor: 'bg.muted', // matches hover; scale provides pressed feedback
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     outline: {
@@ -353,7 +435,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'bg.muted', // gray.100 / gray.1200 (_dark)
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
     ghost: {
@@ -365,7 +447,7 @@ export const buttonColorPaletteStyles: Record<
       },
       _active: {
         bgColor: 'bg.muted', // gray.100 / gray.1200 (_dark)
-        transform: 'scale(0.97)',
+        scale: '0.97',
       },
     },
   },

package/src/components/Button/Button.tsx

@@ -2,9 +2,11 @@ import { forwardRef } from 'react';
 import { Button as ChakraButton } 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 { buttonTransition, getButtonStyles } from './Button.styles';
+import { ButtonOwnProps, ButtonProps } from './Button.types';
 
 /**
  * Button component with two-dimensional variant system.
@@ -18,13 +20,55 @@ import { ButtonProps } from './Button.types';
  * <Button colorPalette="danger" variant="solid">Delete</Button>
  * <Button colorPalette="secondary" variant="outline">Cancel</Button>
  * <Button colorPalette="neutral" variant="ghost">Close</Button>
+ * <Button colorPalette="primary" variant="solid" 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 ButtonImpl = forwardRef<HTMLButtonElement, ButtonProps>(
+  (
+    {
+      colorPalette,
+      variant = 'soft',
+      size,
+      lift,
+      children,
+      _hover: hoverProp,
+      _active: activeProp,
+      _disabled: disabledProp,
+      ...rest
+    },
+    ref
+  ) => {
     const palette = colorPalette ?? 'primary';
 
-    const styles = getButtonStyles(palette, variant);
+    const base = 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.
+          _disabled: { translate: '0 0', filter: 'none' },
+        }
+      : base;
 
     /**
      * Chakra Button automatically maps size prop to textStyle:
@@ -44,11 +88,37 @@ 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}
         {...rest}
       >
@@ -58,4 +128,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,5 +1,13 @@
+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.
  *
@@ -51,9 +59,9 @@ export type ButtonVariant = 'solid' | 'soft' | 'outline' | 'ghost';
  * <Button colorPalette="secondary" variant="outline">Cancel</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).
@@ -67,4 +75,41 @@ export type ButtonProps = Omit<
    * @default 'solid'
    */
   variant?: ButtonVariant;
+  /**
+   * 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/index.tsx

@@ -7,6 +7,7 @@ export {
 } from './Button.styles';
 export type {
   ButtonColorPalette,
+  ButtonOwnProps,
   ButtonProps,
   ButtonVariant,
 } 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,50 @@
  * 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: one tier off the page with a hairline. For a block that
+ * summarises or concludes (an AI summary, a total after a purchase, the
+ * invitation being accepted). It is what `gradient` used to paint with a
+ * 180deg wash and a brand-tinted border; the gradient read as decoration and
+ * the tinted border claimed brand for a surface that is not an action.
+ *
+ * The tier is `bg.subtle` in light but `bg.muted` in dark: `bg.subtle` sits
+ * one grayDark step above `bg.surface` there, too close to read as a different
+ * surface, and `border.subtle` resolves to the same step, so the hairline would
+ * vanish. `border.default` keeps the edge in both modes.
+ */
+const washStyles = {
+  bg: { base: 'bg.subtle', _dark: 'bg.muted' },
+  borderColor: 'border.default',
+};
+
 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,
+  /** @deprecated Renders as `wash`; use `variant="wash"`. */
+  gradient: 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',
   },
 };