@flikk/ui 1.0.0-beta.30 → 1.0.0-beta.32

package/dist/components/core/Badge/Badge.types.d.ts

@@ -1,4 +1,4 @@
-import React, { ReactNode, MouseEvent } from "react";
+import React, { ReactNode } from "react";
 import { SemanticColor } from "../../../utils/colorUtils";
 import type { MeshPaletteName } from "../../effects/MeshGradient";
 export type BadgeVariant = "filled" | "outline" | "soft";
@@ -25,6 +25,10 @@ export interface BadgeTheme {
      * Styles for each badge size (flat structure)
      */
     sizes: Record<BadgeSize, string>;
+    /**
+     * Corner radius for each badge size (ignored when `pill` is set)
+     */
+    radiusSizes: Record<BadgeSize, string>;
     /**
      * Additional padding for pill-shaped badges
      */
@@ -37,21 +41,10 @@ export interface BadgeTheme {
      * Avatar sizes for each badge size
      */
     avatarSizes: Record<BadgeSize, string>;
-    /**
-     * Dismiss icon sizes (button sizes itself from icon + padding)
-     */
-    dismissSizes: Record<BadgeSize, string>;
     /**
      * Color styles for dot indicators
      */
     dotColors: Record<BadgeColor, string>;
-    /**
-     * State styles (disabled, hover, selected)
-     */
-    states: {
-        disabled: string;
-        hover: string;
-    };
 }
 /**
  * Theme overrides for Badge component
@@ -61,15 +54,11 @@ export interface BadgeThemeOverrides {
     variants?: Partial<Record<BadgeVariant, string>>;
     variantColors?: Partial<Record<BadgeVariant, Partial<Record<BadgeColor, string>>>>;
     sizes?: Partial<Record<BadgeSize, string>>;
+    radiusSizes?: Partial<Record<BadgeSize, string>>;
     pillSizes?: Partial<Record<BadgeSize, string>>;
     iconSizes?: Partial<Record<BadgeSize, string>>;
     avatarSizes?: Partial<Record<BadgeSize, string>>;
-    dismissSizes?: Partial<Record<BadgeSize, string>>;
     dotColors?: Partial<Record<BadgeColor, string>>;
-    states?: Partial<{
-        disabled: string;
-        hover: string;
-    }>;
 }
 export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "inputMode"> {
     /**
@@ -77,8 +66,18 @@ export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>,
      */
     children: ReactNode;
     /**
-     * The visual style variant of the badge (filled, outline, soft)
-     * @default 'filled'
+     * The visual style variant of the badge.
+     *
+     * `soft` is the default because a badge is a STATUS/METADATA label, not an
+     * action — a tinted chip is the idiom, and a full-strength fill overstates a
+     * label sitting next to real controls. Pick a non-default deliberately:
+     * - `filled`  — on imagery/gradients, or a genuine emphasis flag ("NEW")
+     * - `outline` — quiet keyword tags; in practice only reads well at `color="mono"`
+     *
+     * (Button defaults to `filled` — an action SHOULD be the loudest thing. Same
+     * vocabulary, opposite default, on purpose. See CLAUDE.md §8.)
+     *
+     * @default 'soft'
      */
     variant?: BadgeVariant;
     /**
@@ -127,21 +126,6 @@ export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>,
         /** Raw gradient color override; wins over `gradientVariant`. */
         gradientColors?: string[];
     };
-    /**
-     * Whether the badge is dismissible (shows close button)
-     * @default false
-     */
-    dismissible?: boolean;
-    /**
-     * Callback when close button is clicked
-     * Required when dismissible is true
-     */
-    onDismiss?: (event: MouseEvent<HTMLButtonElement>) => void;
-    /**
-     * Whether the badge is disabled
-     * @default false
-     */
-    disabled?: boolean;
     /**
      * Maximum width before truncating the label
      * Accepts CSS width value (e.g., '100px', '10rem') or number (pixels)

package/dist/components/core/Breadcrumbs/Breadcrumbs.theme.d.ts

@@ -13,7 +13,4 @@ export declare const breadcrumbsVariants: Record<BreadcrumbsVariant, Partial<Bre
 /**
  * Default chevron separator element
  */
-export declare const defaultSeparator: React.FunctionComponentElement<Omit<React.SVGProps<SVGSVGElement>, "ref"> & {
-    title?: string;
-    titleId?: string;
-} & React.RefAttributes<SVGSVGElement>>;
+export declare const defaultSeparator: React.FunctionComponentElement<import("@phosphor-icons/react").IconProps>;

package/dist/components/core/Breadcrumbs/Breadcrumbs.theme.js

@@ -1,5 +1,5 @@
 import React__default from 'react';
-import { ChevronRightIcon } from '@heroicons/react/20/solid';
+import { CaretRight } from '@phosphor-icons/react';
 
 /**
  * Default theme configuration for Breadcrumbs component
@@ -7,10 +7,10 @@ import { ChevronRightIcon } from '@heroicons/react/20/solid';
  * Simple layout styles are inlined in the component
  */
 const breadcrumbsTheme = {
-    link: "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors duration-150 font-medium",
+    link: "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors duration-[var(--motion-duration-fast)] font-medium",
     current: "text-[var(--color-text-primary)] font-medium",
     separator: "text-[var(--color-text-muted)] select-none",
-    ellipsis: "text-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors duration-150 cursor-pointer p-1 rounded hover:bg-[var(--color-surface-hover)]",
+    ellipsis: "text-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] transition-colors duration-[var(--motion-duration-fast)] cursor-pointer p-1 rounded hover:bg-[var(--color-surface-hover)]",
 };
 /**
  * Variant styles for different breadcrumb appearances
@@ -18,15 +18,15 @@ const breadcrumbsTheme = {
 const breadcrumbsVariants = {
     default: {},
     muted: {
-        link: "text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)] transition-colors duration-150 font-normal",
+        link: "text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)] transition-colors duration-[var(--motion-duration-fast)] font-normal",
         current: "text-[var(--color-text-secondary)] font-normal",
         separator: "text-[var(--color-border)]",
-        ellipsis: "text-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)] transition-colors duration-150 cursor-pointer p-1 rounded hover:bg-[var(--color-background-secondary)]",
+        ellipsis: "text-sm text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)] transition-colors duration-[var(--motion-duration-fast)] cursor-pointer p-1 rounded hover:bg-[var(--color-surface)]",
     },
 };
 /**
  * Default chevron separator element
  */
-const defaultSeparator = React__default.createElement(ChevronRightIcon, { className: "size-4" });
+const defaultSeparator = React__default.createElement(CaretRight, { className: "size-4" });
 
 export { breadcrumbsTheme, breadcrumbsVariants, defaultSeparator };

package/dist/components/core/Button/Button.js

@@ -1,34 +1,19 @@
 "use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default, { useCallback, useRef } from 'react';
+import React__default, { useCallback } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
 import { buttonTheme } from './Button.theme.js';
 import { cn } from '../../../utils/cn.js';
 import { Spinner } from '../Spinner/Spinner.js';
-import { useRipple, getRippleAnimation, getRippleColorClass } from './Button.ripple.js';
+import { Ripple } from '../shared/Ripple.js';
+import { createPressVariants } from '../shared/interaction.animations.js';
 
-// Button animation variants (module-level constant)
-const BUTTON_TAP_ANIMATION = {
-    tap: {
-        scale: 0.95,
-        transition: {
-            duration: 0.1,
-            type: "spring",
-            stiffness: 400,
-            damping: 10,
-        },
-    },
-};
-const Button = React__default.forwardRef(({ children, className = "", iconOnly = false, state = "default", size = "md", color, variant, block = false, onClick, enableRipple = true, rippleEffect = "default", rippleClassName, rippleScale = 10, showReflection = true, darkMode = false, disabled: disabledProp, "aria-label": ariaLabelProp, onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...restProps }, ref) => {
-    var _a, _b, _c, _d, _e, _f;
+// Shared press physics (module-level constant)
+const BUTTON_PRESS_VARIANTS = createPressVariants(0.97);
+const Button = React__default.forwardRef(({ children, iconStart, iconEnd, className = "", iconOnly = false, state = "default", size = "md", color, variant, block = false, onClick, enableRipple = true, showReflection = true, darkMode = false, disabled: disabledProp, "aria-label": ariaLabelProp, onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...restProps }, ref) => {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const shouldReduceMotion = useReducedMotion();
     const shouldDisableAnimations = !!shouldReduceMotion;
-    // Initialize ripple hook
-    const { ripples, createRipple, buttonRef, effect } = useRipple({
-        scale: rippleScale,
-        duration: 600,
-        effect: rippleEffect,
-    });
     // Resolve color and variant with defaults
     const resolvedColor = color || "primary";
     const resolvedVariant = variant || "filled";
@@ -43,13 +28,10 @@ const Button = React__default.forwardRef(({ children, className = "", iconOnly =
         }
     }
     // Safe onClick handler - respect both state="disabled" and disabled={true}
+    // (the ripple wires itself to the DOM node — see <Ripple /> below)
     const handleClick = useCallback((event) => {
         if (isDisabled)
             return;
-        // Create ripple effect if enabled
-        if (enableRipple && !shouldReduceMotion) {
-            createRipple(event);
-        }
         try {
             onClick === null || onClick === void 0 ? void 0 : onClick(event);
         }
@@ -59,7 +41,7 @@ const Button = React__default.forwardRef(({ children, className = "", iconOnly =
                 console.error("Error in button click handler:", error);
             }
         }
-    }, [onClick, isDisabled, enableRipple, shouldReduceMotion, createRipple]);
+    }, [onClick, isDisabled]);
     // Compute theme classes (direct computation - faster than useMemo)
     const sizeClasses = ((_b = (_a = buttonTheme.sizes) === null || _a === void 0 ? void 0 : _a[size]) === null || _b === void 0 ? void 0 : _b[iconOnly ? "iconOnly" : "default"]) || "";
     const colorClasses = ((_c = buttonTheme.variantColors[resolvedVariant]) === null || _c === void 0 ? void 0 : _c[resolvedColor]) || "";
@@ -78,8 +60,9 @@ const Button = React__default.forwardRef(({ children, className = "", iconOnly =
     const animationProps = shouldDisableAnimations
         ? {}
         : {
-            whileTap: !isDisabled ? "tap" : undefined,
-            variants: BUTTON_TAP_ANIMATION,
+            animate: "rest",
+            whileTap: !isDisabled ? "press" : undefined,
+            variants: BUTTON_PRESS_VARIANTS,
         };
     // Spinner inherits the button's text color (the `-contrast` token on filled
     // variants, the semantic color on outline/soft/ghost) so it always contrasts
@@ -92,36 +75,9 @@ const Button = React__default.forwardRef(({ children, className = "", iconOnly =
     // single time below, instead of spreading `restProps` and then
     // unconditionally overwriting it with `state`.
     const consumerDataState = restProps["data-state"];
-    // Track the latest forwarded ref to avoid mergedRef recreation on inline callback refs
-    const forwardedRef = useRef(ref);
-    forwardedRef.current = ref;
-    // Merge refs - stable callback that won't cause DOM detach/attach cycles
-    const mergedRef = useCallback((node) => {
-        // Set ripple's buttonRef
-        if (buttonRef) {
-            buttonRef.current = node;
-        }
-        // Set forwarded ref
-        const fRef = forwardedRef.current;
-        if (typeof fRef === "function") {
-            fRef(node);
-        }
-        else if (fRef) {
-            fRef.current =
-                node;
-        }
-    }, [buttonRef]);
-    return (jsxs(motion.button, { type: "button", ...restProps, ...animationProps, ref: mergedRef, className: cn(buttonTheme.baseStyle, colorClasses, variantClasses, sizeClasses, blockStyle, stateClasses, darkMode && "dark", className), disabled: isDisabled, "data-state": consumerDataState !== null && consumerDataState !== void 0 ? consumerDataState : state, "data-color": resolvedColor, "data-variant": resolvedVariant, "data-size": size, "data-icon-only": iconOnly ? "true" : "false", "data-block": block ? "true" : "false", "aria-disabled": isDisabled || undefined, "aria-busy": isLoading || undefined, "aria-label": ariaLabel, onClick: handleClick, children: [showReflection &&
+    return (jsxs(motion.button, { type: "button", ...restProps, ...animationProps, ref: ref, className: cn(buttonTheme.baseStyle, colorClasses, variantClasses, sizeClasses, blockStyle, stateClasses, darkMode && "dark", className), disabled: isDisabled, "data-state": consumerDataState !== null && consumerDataState !== void 0 ? consumerDataState : state, "data-color": resolvedColor, "data-variant": resolvedVariant, "data-size": size, "data-icon-only": iconOnly ? "true" : "false", "data-block": block ? "true" : "false", "aria-disabled": isDisabled || undefined, "aria-busy": isLoading || undefined, "aria-label": ariaLabel, onClick: handleClick, children: [showReflection &&
                 resolvedVariant !== "ghost" &&
-                resolvedVariant !== "outline" && (jsx("div", { className: "pointer-events-none absolute inset-px border-t-[0.5px] border-white/50 rounded-[inherit] blur-[0.75px]" })), isLoading && (jsx("div", { className: "absolute inset-0 flex items-center justify-center", children: jsx(Spinner, { size: "sm", color: color, className: spinnerClassName }) })), jsx("span", { className: cn("inline-flex items-center gap-2 whitespace-nowrap", isLoading && "opacity-0"), children: children }), enableRipple &&
-                ripples.map((ripple) => {
-                    const animation = getRippleAnimation(effect, ripple, rippleScale);
-                    return (jsx(motion.span, { initial: animation.initial, animate: animation.animate, transition: animation.transition, className: cn("absolute rounded-full size-5 pointer-events-none ", animation.className, rippleClassName ||
-                            getRippleColorClass(resolvedVariant, resolvedColor)), style: {
-                            top: ripple.y - 10,
-                            left: ripple.x - 10,
-                        } }, ripple.id));
-                })] }));
+                resolvedVariant !== "outline" && (jsx("div", { className: "pointer-events-none absolute inset-px border-t-[0.5px] border-white/50 rounded-[inherit] blur-[0.75px]" })), isLoading && (jsx("div", { className: "absolute inset-0 flex items-center justify-center", children: jsx(Spinner, { size: "sm", color: color, className: spinnerClassName }) })), jsxs("span", { className: cn("inline-flex items-center gap-2 whitespace-nowrap", isLoading && "opacity-0"), children: [iconStart && (jsx("span", { className: cn("inline-flex shrink-0 items-center justify-center", (_g = buttonTheme.iconSizes) === null || _g === void 0 ? void 0 : _g[size]), "aria-hidden": "true", children: iconStart })), children, iconEnd && (jsx("span", { className: cn("inline-flex shrink-0 items-center justify-center", (_h = buttonTheme.iconSizes) === null || _h === void 0 ? void 0 : _h[size]), "aria-hidden": "true", children: iconEnd }))] }), enableRipple && jsx(Ripple, {})] }));
 });
 // Set display name for dev tools and Storybook
 Button.displayName = "Button";

package/dist/components/core/Button/Button.theme.d.ts

@@ -16,6 +16,8 @@ export interface ButtonTheme {
         default: string;
         iconOnly: string;
     }>;
+    /** Wrapper sizing for the `iconStart`/`iconEnd` slots, per button size. */
+    iconSizes: Record<ButtonSize, string>;
     states: Partial<Record<ButtonState, string>>;
     blockStyle: string;
 }

package/dist/components/core/Button/Button.theme.js

@@ -3,34 +3,39 @@
  */
 const buttonTheme = {
     // Base styles for the button element
-    baseStyle: "relative inline-flex items-center justify-center gap-2 focus:outline-none rounded-[var(--button-radius)] overflow-hidden cursor-pointer transition-all duration-300 ease-in-out min-w-fit flex-shrink-0 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 cursor-pointer backdrop-blur-sm",
+    baseStyle: "relative inline-flex items-center justify-center gap-2 focus:outline-none rounded-[var(--button-radius)] overflow-hidden cursor-pointer transition-[color,background-color,border-color,box-shadow,filter,opacity] duration-[var(--motion-duration-fast)] ease-out min-w-fit flex-shrink-0 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 cursor-pointer backdrop-blur-sm",
     // Visual style variants - STRUCTURE only (no colors)
     variantStyles: {
-        filled: "border border-black/25 hover:brightness-[0.9] dark:hover:brightness-[1.15]",
+        filled: "border border-black/15 hover:brightness-[0.9] dark:hover:brightness-[1.15]",
         outline: "bg-transparent border",
         soft: "border-transparent",
         ghost: "bg-transparent border-transparent",
     },
     // Color styles organized BY VARIANT for reliable dark: prefixes
     variantColors: {
-        // Filled variant - solid backgrounds
+        // Filled variant - solid backgrounds.
+        // Border split: LIGHT edge is the universal `border-black/25` from
+        // variantStyles.filled (later in the stylesheet, it beats any light
+        // border-* set here — don't add one). DARK keeps color-matched
+        // `dark:border-*` per color (dark variants compile after black/25 and
+        // win; a black edge would be invisible on dark fills).
         filled: {
-            neutral: "bg-[var(--color-neutral-900)] text-white border-[var(--color-border)] " +
-                "focus-visible:outline-[var(--color-neutral-800)] " +
-                "dark:bg-[var(--color-neutral-200)] dark:text-[var(--color-neutral-900)] dark:border-[var(--color-neutral-200)]",
-            primary: "bg-[var(--color-primary)] text-[var(--color-primary-contrast)] border-[var(--color-primary)] " +
+            mono: "bg-[var(--color-mono)] text-[var(--color-mono-contrast)] " +
+                "focus-visible:outline-[var(--color-mono-800)] " +
+                "dark:border-[var(--color-mono)]",
+            primary: "bg-[var(--color-primary)] text-[var(--color-primary-contrast)] " +
                 "focus-visible:outline-[var(--color-primary-600)] " +
-                "dark:text-[var(--color-primary-contrast)] dark:bg-[var(--color-primary)] dark:border-[var(--color-primary-600)]",
-            danger: "bg-[var(--color-danger)] text-[var(--color-danger-contrast)] border-[var(--color-danger)] " +
+                "dark:border-[var(--color-primary-600)]",
+            danger: "bg-[var(--color-danger)] text-[var(--color-danger-contrast)] " +
                 "focus-visible:outline-[var(--color-danger-600)] " +
                 "dark:bg-[var(--color-danger-600)] dark:border-[var(--color-danger-600)]",
         },
         // Outline variant - transparent bg with colored border
         outline: {
-            neutral: "text-[var(--color-text-primary)] border-[var(--color-border-secondary)] " +
-                "hover:bg-[var(--color-neutral-100)] " +
+            mono: "text-[var(--color-text-primary)] border-[var(--color-border-secondary)] " +
+                "hover:bg-[var(--color-mono-100)] " +
                 "focus-visible:outline-[var(--color-text-secondary)] " +
-                "dark:hover:bg-[var(--color-background-secondary)]",
+                "dark:hover:bg-[var(--color-surface)]",
             primary: "text-[var(--color-text-primary)] border-[var(--color-primary-600)]/30 " +
                 "hover:bg-[var(--color-primary-100)] " +
                 "focus-visible:outline-[var(--color-primary-600)] " +
@@ -44,11 +49,11 @@ const buttonTheme = {
         },
         // Soft variant - subtle background tints
         soft: {
-            neutral: "text-[var(--color-text-primary)] bg-[var(--color-neutral-100)] " +
-                "hover:bg-[var(--color-neutral-200)] " +
+            mono: "text-[var(--color-text-primary)] bg-[var(--color-mono-100)] " +
+                "hover:bg-[var(--color-mono-200)] " +
                 "focus-visible:outline-[var(--color-text-secondary)] " +
-                "dark:text-[var(--color-text-primary)] dark:bg-[var(--color-neutral-900)] " +
-                "dark:hover:bg-[var(--color-neutral-800)]",
+                "dark:text-[var(--color-text-primary)] dark:bg-[var(--color-mono-900)] " +
+                "dark:hover:bg-[var(--color-mono-800)]",
             primary: "text-[var(--color-primary-600)] bg-[var(--color-primary)]/10 " +
                 "hover:bg-[var(--color-primary-50)] " +
                 "focus-visible:outline-[var(--color-primary-600)] " +
@@ -62,10 +67,10 @@ const buttonTheme = {
         },
         // Ghost variant - transparent bg, subtle hover, full padding
         ghost: {
-            neutral: "text-[var(--color-text-primary)] " +
-                "hover:bg-[var(--color-neutral-100)] " +
+            mono: "text-[var(--color-text-primary)] " +
+                "hover:bg-[var(--color-mono-100)] " +
                 "focus-visible:outline-[var(--color-text-secondary)] " +
-                "dark:text-[var(--color-text-primary)] dark:hover:bg-[var(--color-neutral-800)]",
+                "dark:text-[var(--color-text-primary)] dark:hover:bg-[var(--color-mono-800)]",
             primary: "text-[var(--color-primary-600)] " +
                 "hover:bg-[var(--color-primary-50)] " +
                 "focus-visible:outline-[var(--color-primary-600)] " +
@@ -81,18 +86,26 @@ const buttonTheme = {
         sm: {
             // Tighten the corner radius at sm so a short button doesn't read as a pill
             // (overrides baseStyle's rounded-[var(--button-radius)] via twMerge).
-            default: "font-medium min-h-[var(--button-min-h-sm)] px-[var(--button-px-sm)] py-[var(--button-py-sm)] text-sm rounded-[calc(var(--button-radius)*0.75)]",
+            default: "font-medium min-h-[var(--button-min-h-sm)] px-[var(--button-px-sm)] py-[var(--button-py-sm)] text-[length:var(--button-text-size-sm)]/[var(--button-line-height-sm)] rounded-[calc(var(--button-radius)*0.75)]",
             iconOnly: "size-[var(--button-icon-size-sm)] p-[var(--button-icon-p-sm)] rounded-[calc(var(--button-radius)*0.75)]",
         },
         md: {
-            default: "font-medium min-h-[var(--button-min-h-md)] px-[var(--button-px-md)] py-[var(--button-py-md)] text-sm",
+            default: "font-medium min-h-[var(--button-min-h-md)] px-[var(--button-px-md)] py-[var(--button-py-md)] text-[length:var(--button-text-size-md)]/[var(--button-line-height-md)]",
             iconOnly: "size-[var(--button-icon-size-md)] p-[var(--button-icon-p-md)]",
         },
         lg: {
-            default: "font-medium min-h-[var(--button-min-h-lg)] px-[var(--button-px-lg)] py-[var(--button-py-lg)] text-base",
+            default: "font-medium min-h-[var(--button-min-h-lg)] px-[var(--button-px-lg)] py-[var(--button-py-lg)] text-[length:var(--button-text-size-lg)]/[var(--button-line-height-lg)]",
             iconOnly: "size-[var(--button-icon-size-lg)] p-[var(--button-icon-p-lg)]",
         },
     },
+    // Icon slot sizing. `[&>svg]:size-*` sizes the icon itself, so a caller passing a bare
+    // <SearchIcon /> with no className still lands at the right size — mirrors Badge's
+    // iconSizes. A caller's own className on the icon still wins.
+    iconSizes: {
+        sm: "size-3.5 [&>svg]:size-3.5",
+        md: "size-4 [&>svg]:size-4",
+        lg: "size-5 [&>svg]:size-5",
+    },
     // State styles
     states: {
         disabled: "opacity-60 cursor-not-allowed pointer-events-none saturate-0",

package/dist/components/core/Button/Button.types.d.ts

@@ -1,5 +1,4 @@
 import React from "react";
-import { RippleEffectType } from "./Button.ripple";
 /**
  * Button component props
  * @property {ButtonColor} color - The semantic color/intent of the button
@@ -8,10 +7,7 @@ import { RippleEffectType } from "./Button.ripple";
  * @property {ButtonState} state - The state of the button (default, loading, disabled)
  * @property {boolean} iconOnly - Whether the button should display as icon-only (square padding)
  * @property {boolean} block - Whether the button should be full width
- * @property {boolean} enableRipple - Whether to enable ripple effect on click
- * @property {RippleEffectType} rippleEffect - Type of ripple effect (default, aurora, particle, glass, neon, echo)
- * @property {string} rippleClassName - Custom class name for ripple styling
- * @property {number} rippleScale - Scale multiplier for ripple expansion (default: 10)
+ * @property {boolean} enableRipple - Whether to enable the press ripple
  */
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     /** The semantic color/intent of the button */
@@ -26,18 +22,35 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
     iconOnly?: boolean;
     /** Whether the button should be full width */
     block?: boolean;
+    /**
+     * Small decorative icon before the label, auto-sized to the button's `size`.
+     *
+     * The SERIALIZABLE front door — composing the icon into `children` stays the
+     * idiomatic hand-written form (`<Button><SearchIcon className="size-4" />Search</Button>`)
+     * and is unchanged. This slot exists because a generative UI spec is JSON: it can name
+     * an icon but cannot pass a React element, so `children` alone leaves an LLM unable to
+     * put an icon on a button at all. Same "one contract, two front doors" shape as Card's
+     * `title`/`subtitle` slot-props and the collection `items` APIs (CLAUDE.md §2).
+     *
+     * Deliberately NO `contentStart`/`contentEnd` counterpart: those take arbitrary
+     * ReactNode, which is not serializable, so they would buy the generative path nothing
+     * — compose those into `children`.
+     */
+    iconStart?: React.ReactNode;
+    /** Small decorative icon after the label, auto-sized to the button's `size`. See `iconStart`. */
+    iconEnd?: React.ReactNode;
     /** Button contents */
     children?: React.ReactNode;
     /** Additional class names */
     className?: string;
-    /** Whether to enable ripple effect on click */
+    /**
+     * Whether to show the press ripple.
+     *
+     * The ripple is pointer-only — keyboard activation gets the focus ring
+     * instead — and is suppressed automatically under `prefers-reduced-motion`.
+     * @default true
+     */
     enableRipple?: boolean;
-    /** Type of ripple effect: 'default' | 'aurora' | 'particle' | 'glass' | 'neon' | 'echo' */
-    rippleEffect?: RippleEffectType;
-    /** Custom class name for ripple styling */
-    rippleClassName?: string;
-    /** Scale multiplier for ripple expansion (default: 10) */
-    rippleScale?: number;
     /** Whether to show the glass reflection effect (default: true) */
     showReflection?: boolean;
     /**
@@ -49,7 +62,7 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
      */
     darkMode?: boolean;
 }
-export type ButtonColor = "neutral" | "primary" | "danger";
+export type ButtonColor = "mono" | "primary" | "danger";
 export type ButtonVariant = "filled" | "outline" | "soft" | "ghost";
 export type ButtonSize = "sm" | "md" | "lg";
 export type ButtonState = "default" | "disabled" | "loading";

package/dist/components/core/Button/index.d.ts

@@ -1,4 +1,2 @@
 export { Button } from './Button';
 export * from './Button.types';
-export { useRipple, getRippleColorClass, getRippleAnimation } from './Button.ripple';
-export type { RippleEffectType, RippleConfig, Ripple } from './Button.ripple';

package/dist/components/core/Calendar/Calendar.js

@@ -2,10 +2,13 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useState, useCallback, useEffect, useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
-import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/outline';
+import { CaretLeft, CaretRight } from '@phosphor-icons/react';
 import { calendarTheme } from './Calendar.theme.js';
 import { calendarAnimations } from './Calendar.animations.js';
 import { cn } from '../../../utils/cn.js';
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { springs } from '../../../theme/animations.js';
 import { Select } from '../../forms/Select/Select.js';
 import '../../forms/Select/Select.theme.js';
 import { Button } from '../Button/Button.js';
@@ -113,7 +116,9 @@ const generateCalendarDays = (year, month, selectedValue, mode = 'single', today
     }
     return days;
 };
-const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultValue, onChange, minDate, maxDate, isDateDisabled: customIsDateDisabled, showToday = true, selectTodayByDefault = false, weekdays = ["M", "T", "W", "T", "F", "S", "S"], months, size = "md", headerMode, enableMonthDropdown = true, enableYearDropdown = true, yearRange, viewDate: externalViewDate, onViewDateChange, onNavigatePrev, onNavigateNext, showOtherMonthDays = true, className, ...props }, ref) => {
+const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultValue, onChange, minDate, maxDate, isDateDisabled: customIsDateDisabled, showToday = true, selectTodayByDefault = false, weekdays = ["M", "T", "W", "T", "F", "S", "S"], months, size = "md", headerMode, enableMonthDropdown = true, enableYearDropdown = true, yearRange, viewDate: externalViewDate, onViewDateChange, onNavigatePrev, onNavigateNext, showOtherMonthDays = true, className, 
+// Destructure motion-conflicting props to avoid type issues
+onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...props }, ref) => {
     // Determine initial view date from value/defaultValue
     const getInitialViewDate = () => {
         if (value) {
@@ -298,6 +303,16 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
         maxDate,
         customIsDateDisabled,
     ]);
+    // Calculate days grid height dynamically to animate height smoothly without layout scale distortion
+    const gridHeight = useMemo(() => {
+        const rowCount = calendarDays.length / 7;
+        // Must mirror calendarTheme.dayButtonSizes (size-8/10/12 → 32/40/48px)
+        const rowHeight = size === 'sm' ? 32 : size === 'lg' ? 48 : 40;
+        // Row height * number of rows + gap-y (2px) * (number of rows - 1),
+        // plus the grid's py-1 (4px top + bottom) that keeps focus rings
+        // visible inside the overflow-hidden clip.
+        return rowCount * rowHeight + (rowCount - 1) * 2 + 8;
+    }, [calendarDays.length, size]);
     // Reset the roving tabindex target whenever the visible month changes —
     // prefer the selected day, then today, then the first day of the month.
     // Deliberately does NOT depend on `selectedValue`/`calendarDays` so that
@@ -446,9 +461,9 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
             }
         }
     }, [minDate, maxDate, customIsDateDisabled, currentMonth, currentYear, onViewDateChange, mode, value, onChange, selectedValue, rangeSelectionState]);
-    return (jsxs("div", { ref: ref, className: cn(calendarTheme.baseStyle, className), ...props, children: [jsxs("div", { className: calendarTheme.headerStyle, children: [onNavigatePrev !== null && (jsx(Button, { onClick: navigateToPreviousMonth, "aria-label": "Previous month", disabled: !canNavigateToPrev, iconOnly: true, variant: "ghost", color: "neutral", size: "sm", children: jsx(ChevronLeftIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigatePrev === null && jsx("div", { className: "w-8" }), resolvedHeaderMode === 'static' ? (jsxs("h2", { className: calendarTheme.titleStyle, children: [getMonthName(viewDate, months), " ", currentYear] })) : (jsxs("div", { className: calendarTheme.headerDropdownsStyle, children: [(resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableMonthDropdown)) && (jsx(Select, { value: currentMonth.toString(), onChange: handleMonthChange, options: monthOptions, displayValue: currentAbbreviatedMonth, size: "sm", className: "font-medium" })), (resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableYearDropdown)) && (jsx(Select, { value: currentYear.toString(), onChange: handleYearChange, options: yearOptions, size: "sm", className: "font-medium" }))] })), onNavigateNext !== null && (jsx(Button, { onClick: navigateToNextMonth, "aria-label": "Next month", disabled: !canNavigateToNext, iconOnly: true, variant: "ghost", color: "neutral", size: "sm", children: jsx(ChevronRightIcon, { className: "size-4", strokeWidth: 2 }) })), onNavigateNext === null && jsx("div", { className: "w-8" })] }), jsx("div", { className: calendarTheme.weekdaysStyle, children: weekdays.map((day, i) => (
+    return (jsxs("div", { ref: ref, className: cn(calendarTheme.baseStyle, className), ...props, children: [jsxs("div", { className: calendarTheme.headerStyle, children: [onNavigatePrev !== null && (jsx(Button, { onClick: navigateToPreviousMonth, "aria-label": "Previous month", disabled: !canNavigateToPrev, iconOnly: true, variant: "ghost", color: "mono", size: "sm", children: jsx(CaretLeft, { className: "size-4", weight: "bold" }) })), onNavigatePrev === null && jsx("div", { className: "w-8" }), resolvedHeaderMode === 'static' ? (jsxs("h2", { className: calendarTheme.titleStyle, children: [getMonthName(viewDate, months), " ", currentYear] })) : (jsxs("div", { className: calendarTheme.headerDropdownsStyle, children: [(resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableMonthDropdown)) && (jsx(Select, { value: currentMonth.toString(), onChange: handleMonthChange, options: monthOptions, displayValue: currentAbbreviatedMonth, size: "sm", className: "font-medium" })), (resolvedHeaderMode === 'dropdown' || (resolvedHeaderMode === 'mixed' && enableYearDropdown)) && (jsx(Select, { value: currentYear.toString(), onChange: handleYearChange, options: yearOptions, size: "sm", className: "font-medium" }))] })), onNavigateNext !== null && (jsx(Button, { onClick: navigateToNextMonth, "aria-label": "Next month", disabled: !canNavigateToNext, iconOnly: true, variant: "ghost", color: "mono", size: "sm", children: jsx(CaretRight, { className: "size-4", weight: "bold" }) })), onNavigateNext === null && jsx("div", { className: "w-8" })] }), jsx("div", { className: calendarTheme.weekdaysStyle, children: weekdays.map((day, i) => (
                 // Index in the key: default labels (e.g. M,T,W,T,F,S,S) repeat, so `day` alone is not unique.
-                jsx("div", { className: calendarTheme.weekdayStyle, children: day }, `${day}-${i}`))) }), jsx("div", { className: calendarTheme.daysGridStyle, children: calendarDays.map((day, index) => {
+                jsx("div", { className: calendarTheme.weekdayStyle, children: day }, `${day}-${i}`))) }), jsx(motion.div, { animate: { height: gridHeight }, transition: springs.smooth, className: cn(calendarTheme.daysGridStyle, "content-start overflow-hidden py-1 -my-1"), children: calendarDays.map((day, index) => {
                     var _a;
                     const dayNumber = day.date.getDate();
                     const isInStrip = day.isRangeStart || day.isRangeEnd || day.isInRange;
@@ -483,7 +498,7 @@ const Calendar = React__default.forwardRef(({ mode = 'single', value, defaultVal
                                 // the onFocus round-trip.
                                 setFocusedIndex(index);
                                 handleDateSelect(day.date);
-                            }, onKeyDown: (e) => handleDayKeyDown(e, index), onFocus: () => setFocusedIndex(index), tabIndex: index === focusedIndex ? 0 : -1, disabled: day.isDisabled, className: cn(calendarTheme.dayButtonStyle, (_a = calendarTheme.dayButtonSizes) === null || _a === void 0 ? void 0 : _a[size]), "data-selected": day.isSelected, "data-range-start": day.isRangeStart, "data-range-end": day.isRangeEnd, "data-in-range": day.isInRange, "data-today": day.isToday && !day.isSelected && !day.isRangeStart && !day.isRangeEnd, "data-disabled": day.isDisabled, "data-other-month": !day.isCurrentMonth, "aria-label": `Select ${day.date.toLocaleDateString()}`, variants: shouldReduceMotion ? {} : calendarAnimations.dayButton, whileHover: shouldReduceMotion ? undefined : (!day.isDisabled ? "hover" : undefined), whileTap: shouldReduceMotion ? undefined : (!day.isDisabled ? "tap" : undefined), children: [jsx("time", { dateTime: day.date.toISOString().split("T")[0], children: dayNumber }), day.isToday && (jsx(motion.span, { className: "absolute z-10 bottom-1 left-1/2 -translate-x-1/2 w-1 h-1 bg-[var(--color-primary)] rounded-full", variants: shouldReduceMotion ? {} : calendarAnimations.todayDot, initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate" }))] }) }, day.date.toISOString()));
+                            }, onKeyDown: (e) => handleDayKeyDown(e, index), onFocus: () => setFocusedIndex(index), tabIndex: index === focusedIndex ? 0 : -1, disabled: day.isDisabled, className: cn(calendarTheme.dayButtonStyle, (_a = calendarTheme.dayButtonSizes) === null || _a === void 0 ? void 0 : _a[size]), "data-selected": day.isSelected || day.isRangeStart || day.isRangeEnd, "data-range-start": day.isRangeStart, "data-range-end": day.isRangeEnd, "data-in-range": day.isInRange, "data-today": day.isToday && !day.isSelected && !day.isRangeStart && !day.isRangeEnd, "data-disabled": day.isDisabled, "data-other-month": !day.isCurrentMonth, "aria-label": `Select ${day.date.toLocaleDateString()}`, variants: shouldReduceMotion ? {} : calendarAnimations.dayButton, whileHover: shouldReduceMotion ? undefined : (!day.isDisabled ? "hover" : undefined), whileTap: shouldReduceMotion ? undefined : (!day.isDisabled ? "tap" : undefined), children: [jsx("time", { dateTime: day.date.toISOString().split("T")[0], children: dayNumber }), day.isToday && (jsx(motion.span, { className: "absolute z-10 bottom-1 left-1/2 -translate-x-1/2 w-1 h-1 bg-[var(--color-primary)] rounded-full", variants: shouldReduceMotion ? {} : calendarAnimations.todayDot, initial: shouldReduceMotion ? undefined : "initial", animate: shouldReduceMotion ? undefined : "animate" }))] }) }, day.date.toISOString()));
                 }) })] }));
 });
 Calendar.displayName = "Calendar";

package/dist/components/core/Calendar/Calendar.theme.js

@@ -7,47 +7,39 @@ const calendarTheme = {
     headerStyle: "flex items-center justify-between mb-4",
     titleStyle: "text-sm font-semibold text-[var(--color-text-primary)] " + "",
     headerDropdownsStyle: "grid grid-cols-2 items-center gap-2 flex-1 justify-center mx-3",
-    navButtonStyle: "inline-flex items-center justify-center size-8 rounded-[calc(var(--radius-base)*0.75)] border-0 bg-transparent " +
-        "text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-primary-50)] " +
-        "focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
-        "transition-colors disabled:opacity-50 disabled:cursor-not-allowed " +
-        // Dark mode
-        "dark:text-[var(--color-neutral-500)] dark:hover:text-[var(--color-neutral-200)] dark:hover:bg-[var(--color-neutral-800)] " +
-        "dark:focus-visible:ring-offset-[var(--color-neutral-900)]",
     weekdaysStyle: "grid grid-cols-7 mb-2",
-    weekdayStyle: "flex items-center justify-center h-8 text-xs font-medium text-[var(--color-text-muted)] " +
-        "dark:text-[var(--color-neutral-500)]",
+    weekdayStyle: "flex items-center justify-center h-8 text-xs font-medium text-[var(--color-text-muted)]",
     daysGridStyle: "grid grid-cols-7 gap-y-0.5 gap-x-0",
-    rangeCellStyle: "bg-[var(--color-primary-50)]/70 " +
+    rangeCellStyle: "bg-[var(--color-primary-300)]/50 dark:bg-[var(--color-primary-500)]/20 " +
         "data-[range-pos=start]:rounded-l-full " +
         "data-[range-pos=end]:rounded-r-full " +
-        "data-[range-pos=single]:rounded-full " +
-        "dark:bg-[var(--color-primary-900)]/50",
+        "data-[range-pos=single]:rounded-full",
     dayButtonStyle: "relative z-10 flex items-center justify-center rounded-full border-0 bg-transparent font-medium cursor-pointer " +
-        "transition-all duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
+        "transition-all duration-[var(--motion-duration-base)] focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 " +
         // Base text color
-        "text-[var(--color-text-primary)] dark:text-[var(--color-neutral-200)] " +
+        "text-[var(--color-text-primary)] " +
         // Hover state
-        "hover:bg-[var(--color-primary-50)] dark:hover:bg-[var(--color-neutral-800)] " +
+        "hover:bg-[var(--color-primary-50)] dark:hover:bg-[var(--color-primary)]/30 " +
         // Selected state
         "data-[selected=true]:bg-[var(--color-primary)] data-[selected=true]:text-[var(--color-primary-contrast)] " +
-        "data-[selected=true]:hover:bg-[var(--color-primary-600)] data-[selected=true]:border-t data-[selected=true]:border-white/30 " +
+        "data-[selected=true]:hover:bg-[var(--color-primary-600)] data-[selected=true]:dark:hover:bg-[var(--color-primary)]/80 data-[selected=true]:border-t data-[selected=true]:border-white/30 " +
         // Today indicator
         "data-[today=true]:text-[var(--color-primary)] dark:data-[today=true]:text-[var(--color-primary-400)] " +
         // Disabled state
         "data-[disabled=true]:text-[var(--color-text-muted)] data-[disabled=true]:opacity-50 " +
         "data-[disabled=true]:cursor-not-allowed data-[disabled=true]:hover:bg-transparent " +
-        "dark:data-[disabled=true]:text-[var(--color-neutral-600)] " +
         // Other month state
         "data-[other-month=true]:text-[var(--color-text-muted)] data-[other-month=true]:opacity-60 " +
-        "dark:data-[other-month=true]:text-[var(--color-neutral-600)] " +
-        // Range mode states (strip background handled by wrapper cell)
-        "data-[range-start=true]:bg-[var(--color-primary)] data-[range-start=true]:text-[var(--color-primary-contrast)] " +
-        "data-[range-end=true]:bg-[var(--color-primary)] data-[range-end=true]:text-[var(--color-primary-contrast)] " +
+        // Range mode: endpoints (start/end) reuse the single-selected styling via
+        // data-selected (set in Calendar.tsx) — ONE source of truth for a selected
+        // day (fill, text, border, hover). In-range (between) days only override
+        // text colour for readability on the strip; their hover intentionally falls
+        // through to the base day-hover above, so a hovered day looks identical
+        // whether or not it sits inside a range.
         "data-[in-range=true]:text-[var(--color-text-primary)] " +
-        "dark:data-[in-range=true]:text-[var(--color-neutral-200)] " +
+        "dark:data-[in-range=true]:text-[var(--color-mono-200)] " +
         // Focus offset for dark mode
-        "dark:focus-visible:ring-offset-[var(--color-neutral-900)]",
+        "dark:focus-visible:ring-offset-[var(--color-mono-900)]",
     dayButtonSizes: {
         sm: "size-8 text-sm",
         md: "size-10 text-sm",

package/dist/components/core/Calendar/Calendar.types.d.ts

@@ -117,7 +117,6 @@ export interface CalendarTheme {
     headerStyle: string;
     titleStyle: string;
     headerDropdownsStyle: string;
-    navButtonStyle: string;
     weekdaysStyle: string;
     weekdayStyle: string;
     daysGridStyle: string;