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

package/dist/components/core/Drawer/DrawerContext.js

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, useContext } from 'react';
+
+// Lives in its own module (not Drawer.tsx) so sub-components can consume the
+// context without importing Drawer.tsx, which imports them back (circular dep).
+// Drawer.tsx re-exports `useDrawerContext`, so `from "./Drawer"` keeps working.
+const DrawerContext = createContext(undefined);
+const useDrawerContext = () => {
+    const ctx = useContext(DrawerContext);
+    if (!ctx)
+        throw new Error("Drawer compound components must be used within <Drawer>");
+    return ctx;
+};
+
+export { DrawerContext, useDrawerContext };

package/dist/components/core/Drawer/DrawerFooter.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
 const DrawerFooter = ({ children, className, ...props }) => {
     const { theme } = useDrawerContext();

package/dist/components/core/Drawer/DrawerHeader.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 import { Button } from '../Button/Button.js';
 import 'react';
 import { XMarkIcon } from '@heroicons/react/24/outline';
@@ -8,7 +9,7 @@ import { XMarkIcon } from '@heroicons/react/24/outline';
 const DrawerHeader = ({ children, icon, showCloseButton, className, ...props }) => {
     const { onClose, showCloseButton: contextShowCloseButton, theme, } = useDrawerContext();
     const shouldShowCloseButton = showCloseButton !== null && showCloseButton !== void 0 ? showCloseButton : contextShowCloseButton;
-    return (jsxs("div", { className: cn(theme.header, className), ...props, children: [jsxs("div", { className: cn(theme.headerContent), children: [icon && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-secondary)]", children: icon })), jsx("div", { className: "flex-1 min-w-0", children: children })] }), shouldShowCloseButton && (jsx(Button, { color: "neutral", variant: "soft", iconOnly: true, size: "sm", onClick: onClose, "aria-label": "Close drawer", className: "rounded-full shrink-0", children: jsx(XMarkIcon, { className: "size-5" }) }))] }));
+    return (jsxs("div", { className: cn(theme.header, className), ...props, children: [jsxs("div", { className: cn(theme.headerContent), children: [icon && (jsx("div", { className: "flex-shrink-0 text-[var(--color-text-secondary)]", children: icon })), jsx("div", { className: "flex-1 min-w-0", children: children })] }), shouldShowCloseButton && (jsx(Button, { color: "neutral", variant: "outline", iconOnly: true, size: "sm", onClick: onClose, "aria-label": "Close drawer", className: "rounded-full shrink-0", children: jsx(XMarkIcon, { className: "size-4" }) }))] }));
 };
 DrawerHeader.displayName = "Drawer.Header";
 

package/dist/components/core/Drawer/DrawerSubtitle.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
 const DrawerSubtitle = ({ children, className, ...props }) => {
     const { theme, subtitleId } = useDrawerContext();

package/dist/components/core/Drawer/DrawerTitle.js

@@ -1,6 +1,7 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import { cn } from '../../../utils/cn.js';
-import { useDrawerContext } from './Drawer.js';
+import { useDrawerContext } from './DrawerContext.js';
 
 const DrawerTitle = ({ children, className, as: Tag = 'h2', ...props }) => {
     const { theme, titleId } = useDrawerContext();

package/dist/components/core/Dropdown/Dropdown.js

@@ -1,5 +1,6 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
-import { useState, useRef, useId, useCallback } from 'react';
+import { useState, useMemo, useRef, useId, useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { DropdownContext } from './DropdownContext.js';
 import { DropdownTrigger } from './DropdownTrigger.js';
@@ -35,9 +36,7 @@ const DropdownRoot = ({ children, className, isOpen: controlledIsOpen, defaultIs
     const isControlledOpen = controlledIsOpen !== undefined;
     const isOpen = isControlledOpen ? controlledIsOpen : uncontrolledIsOpen;
     const isControlledSelection = controlledSelectedKeys !== undefined;
-    const selectedKeys = isControlledSelection
-        ? new Set(controlledSelectedKeys)
-        : uncontrolledSelectedKeys;
+    const selectedKeys = useMemo(() => (isControlledSelection ? new Set(controlledSelectedKeys) : uncontrolledSelectedKeys), [isControlledSelection, controlledSelectedKeys, uncontrolledSelectedKeys]);
     // Refs for positioning
     const triggerRef = useRef(null);
     const menuRef = useRef(null);
@@ -59,14 +58,14 @@ const DropdownRoot = ({ children, className, isOpen: controlledIsOpen, defaultIs
         onSelectionChange === null || onSelectionChange === void 0 ? void 0 : onSelectionChange(Array.from(keys));
     }, [isControlledSelection, onSelectionChange]);
     // Merge theme with overrides
-    const theme = {
+    const theme = useMemo(() => ({
         ...dropdownTheme,
         ...(themeOverrides || {}),
-    };
+    }), [themeOverrides]);
     // Convert disabled keys array to Set
-    const disabledKeysSet = new Set(disabledKeys);
+    const disabledKeysSet = useMemo(() => new Set(disabledKeys), [disabledKeys]);
     // Context value
-    const contextValue = {
+    const contextValue = useMemo(() => ({
         isOpen,
         onOpenChange: handleOpenChange,
         triggerRef,
@@ -81,7 +80,22 @@ const DropdownRoot = ({ children, className, isOpen: controlledIsOpen, defaultIs
         onAction,
         onSelectionChange: handleSelectionChange,
         theme,
-    };
+    }), [
+        isOpen,
+        handleOpenChange,
+        triggerRef,
+        menuRef,
+        menuId,
+        placement,
+        offset,
+        closeOnSelect,
+        disabledKeysSet,
+        selectedKeys,
+        selectionMode,
+        onAction,
+        handleSelectionChange,
+        theme,
+    ]);
     return (jsx(DropdownContext.Provider, { value: contextValue, children: jsx("div", { className: cn("dropdown contents", darkMode && "dark", className), "data-state": isOpen ? "open" : "closed", ...props, children: children }) }));
 };
 DropdownRoot.displayName = "Dropdown";

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

@@ -1,9 +1,10 @@
 import { menuItemTheme } from '../MenuItem/MenuItem.theme.js';
 
 const dropdownTheme = {
-    // Menu container - similar to Popover but with menu-specific styling
-    menuStyle: "min-w-[200px] max-h-[400px] overflow-y-auto rounded-[var(--dropdown-radius)] border border-[var(--color-border)] bg-[var(--color-surface-overlay)]/80 backdrop-blur-md shadow-real-xl focus:outline-none flex disabled:cursor-not-allowed " +
-        "dark:bg-[var(--color-surface-overlay)]/80",
+    // Menu container - similar to Popover but with menu-specific styling.
+    // bg + shadow come from the relative-elevation engine (surfaceClasses) at runtime so
+    // a nested menu lifts above its host; keep the frosted blur + border + radius here.
+    menuStyle: "min-w-[200px] max-h-[400px] overflow-y-auto rounded-[var(--dropdown-radius)] border border-[var(--color-border)] backdrop-blur-md focus:outline-none flex disabled:cursor-not-allowed gap-0.5",
     // Delegate item styles to shared MenuItem theme
     itemBaseStyle: menuItemTheme.baseStyle,
     itemDangerStyle: menuItemTheme.dangerStyle,

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

@@ -1,5 +1,6 @@
 import React, { ReactNode } from "react";
 import { DropdownTheme } from "./Dropdown.theme";
+import type { SurfaceElevation } from "../../../theme/SurfaceContext";
 export type DropdownPlacement = "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
 export type SelectionMode = "none" | "single" | "multiple";
 export interface DropdownContextValue {
@@ -53,6 +54,13 @@ export interface DropdownMenuProps extends React.HTMLAttributes<HTMLDivElement>
     portal?: boolean;
     horizontal?: boolean;
     "aria-label"?: string;
+    /**
+     * Pin the surface elevation rung (overrides the automatic relative lift).
+     * A rung number (1–8) or a semantic alias ("surface"/"raised"/"overlay"…).
+     */
+    elevation?: SurfaceElevation;
+    /** `false` opts out of the relative lift — paints at the menu's base rung. */
+    lift?: boolean;
 }
 export interface DropdownItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color" | "onSelect"> {
     itemKey: string;

package/dist/components/core/Dropdown/DropdownContext.js

@@ -1,3 +1,4 @@
+"use client";
 import { createContext, useContext } from 'react';
 
 const DropdownContext = createContext(undefined);

package/dist/components/core/Dropdown/DropdownItem.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useCallback } from 'react';
 import { CheckIcon } from '@heroicons/react/16/solid';

package/dist/components/core/Dropdown/DropdownMenu.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default, { useRef, useState, useEffect, useCallback } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
@@ -8,11 +9,16 @@ import { useClickOutside } from '../../../hooks/useClickOutside.js';
 import { useSelectPortal } from '../../../hooks/useSelectPortal.js';
 import { useIsClient } from '../../../hooks/useIsClient.js';
 import { useDarkMode } from '../../../hooks/useDarkMode.js';
+import { useSurfaceElevation, SurfaceProvider, surfaceClasses } from '../../../theme/SurfaceContext.js';
+import '../../../theme/ThemeContext.js';
+import { getOverlayMenuVariants } from '../../../theme/animations.js';
 
 /**
  * DropdownMenu component - renders the menu with keyboard navigation
  */
-const DropdownMenu = React__default.forwardRef(({ children, className, animation = true, portal = true, horizontal = false, "aria-label": ariaLabel, ...props }, ref) => {
+const DropdownMenu = React__default.forwardRef(({ children, className, animation = true, portal = true, horizontal = false, "aria-label": ariaLabel, elevation, lift, ...props }, ref) => {
+    // Relative elevation: lift one+ rung above the host surface (overlay base = 5).
+    const surfaceLevel = useSurfaceElevation({ baseRung: 5, offset: 2, elevation, lift });
     const { isOpen, onOpenChange, triggerRef, menuRef, menuId, placement, offset, theme, } = useDropdownContext();
     // Detect dark mode for portal content
     const isDarkMode = useDarkMode();
@@ -129,12 +135,20 @@ const DropdownMenu = React__default.forwardRef(({ children, className, animation
     ]);
     // Click outside to close
     useClickOutside(localRef, (e) => {
-        var _a;
+        var _a, _b, _c;
         // Skip if clicking on the trigger element
         if (e.target === triggerRef.current ||
             ((_a = triggerRef.current) === null || _a === void 0 ? void 0 : _a.contains(e.target))) {
             return;
         }
+        // Ignore clicks that land inside any FlikkUI overlay portal (a nested
+        // Select/Tooltip/Dropdown/Popover renders to document.body, outside our
+        // menu's own DOM subtree — without this it would count as an outside
+        // click and dismiss the menu). See the `data-flikkui-portal` convention
+        // (CLAUDE.md §11) — mirrors PopoverBody's bail.
+        if ((_c = (_b = e.target) === null || _b === void 0 ? void 0 : _b.closest) === null || _c === void 0 ? void 0 : _c.call(_b, "[data-flikkui-portal]")) {
+            return;
+        }
         onOpenChange(false);
     });
     // Focus first item when menu opens. Retry until focus actually LANDS:
@@ -188,33 +202,19 @@ const DropdownMenu = React__default.forwardRef(({ children, className, animation
     // a hardcoded top-down drop reads backwards there. `actualPlacement` (not
     // the prop) so a viewport-flipped menu animates from its real side.
     const side = (actualPlacement || placement || "bottom").split("-")[0];
-    const closedShift = side === "top"
-        ? { y: 10 }
-        : side === "left"
-            ? { x: 10 }
-            : side === "right"
-                ? { x: -10 }
-                : { y: -10 };
     const transformOrigin = side === "top" ? "bottom" : side === "left" ? "right" : side === "right" ? "left" : "top";
-    const menuVariants = {
-        hidden: { opacity: 0, scale: 0.95, x: 0, y: 0, ...closedShift },
-        visible: { opacity: 1, scale: 1, x: 0, y: 0 },
-        exit: { opacity: 0, scale: 0.95, x: 0, y: 0, ...closedShift },
-    };
+    const menuVariants = getOverlayMenuVariants(side, {
+        scale: 0.97,
+        shift: 6,
+    });
     // Extract DOM props to avoid type conflicts with Framer Motion
     const { onAnimationStart, onAnimationEnd, onDrag, onDragStart, onDragEnd, ...domProps } = props;
-    const menuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", theme.menuStyle, horizontal ? "flex-row p-1" : "flex-col p-1", className), style: {
+    const menuContent = (jsx(AnimatePresence, { children: isOpen && (jsx(motion.div, { ref: handleRef, className: cn("fixed z-50", surfaceClasses(surfaceLevel, { translucent: true }), theme.menuStyle, horizontal ? "flex-row p-1" : "flex-col p-1", className), style: {
                 ...cssVariables,
                 top: `${position.top}px`,
                 left: `${position.left}px`,
                 transformOrigin,
-            }, id: menuId, role: "menu", "aria-label": ariaLabel || undefined, "aria-orientation": horizontal ? "horizontal" : "vertical", tabIndex: -1, onKeyDown: handleKeyDown, variants: shouldReduceMotion || !animation ? {} : menuVariants, initial: shouldReduceMotion || !animation ? undefined : "hidden", animate: shouldReduceMotion || !animation ? undefined : "visible", exit: shouldReduceMotion || !animation ? undefined : "exit", transition: shouldReduceMotion || !animation
-                ? { duration: 0 }
-                : {
-                    type: "spring",
-                    stiffness: 500,
-                    damping: 30,
-                }, "data-state": isOpen ? "open" : "closed", "data-placement": placement, ...domProps, children: children })) }));
+            }, id: menuId, role: "menu", "aria-label": ariaLabel || undefined, "aria-orientation": horizontal ? "horizontal" : "vertical", tabIndex: -1, onKeyDown: handleKeyDown, variants: shouldReduceMotion || !animation ? {} : menuVariants, initial: shouldReduceMotion || !animation ? undefined : "hidden", animate: shouldReduceMotion || !animation ? undefined : "visible", exit: shouldReduceMotion || !animation ? undefined : "exit", transition: shouldReduceMotion || !animation ? { duration: 0 } : undefined, "data-state": isOpen ? "open" : "closed", "data-placement": placement, ...domProps, children: jsx(SurfaceProvider, { level: surfaceLevel, children: children }) })) }));
     // Use portal if specified - wrap with dark class for dark mode support
     if (portal && isClient) {
         return createPortal(jsx("div", { "data-flikkui-portal": "", className: isDarkMode ? "dark" : undefined, children: menuContent }), document.body);

package/dist/components/core/Dropdown/DropdownSection.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/core/Dropdown/DropdownSeparator.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx } from 'react/jsx-runtime';
 import React__default from 'react';
 import { cn } from '../../../utils/cn.js';

package/dist/components/core/Dropdown/DropdownTrigger.js

@@ -1,6 +1,24 @@
+"use client";
 import React__default, { useCallback } from 'react';
+import { cn } from '../../../utils/cn.js';
 import { useDropdownContext } from './DropdownContext.js';
 
+/**
+ * Default interaction treatment applied to EVERY trigger so a dropdown opener shows a
+ * consistent active state for free — no per-usage classes. Hover AND open both paint the
+ * single `--color-surface-hover` interaction tint (§3), so the two read identically (the
+ * trigger doesn't visually "change" when you hover an already-open menu).
+ *
+ * 🔴 Keyed on `aria-expanded`, NOT `data-[state=open]`: a `Button` trigger overwrites its own
+ * `data-state` (idle/loading), clobbering the open flag — `aria-expanded` is the reliable hook.
+ *
+ * Injected FIRST in the className merge, so a consumer's own `className` on the trigger child
+ * always wins (shadcn override model). `hover` + `dark:hover` are both set because a Button
+ * variant declares each as a separate variant, and twMerge only dedupes matching ones.
+ */
+const triggerInteractionStyle = "hover:bg-[var(--color-surface-hover)] hover:text-[var(--color-text-primary)] " +
+    "dark:hover:bg-[var(--color-surface-hover)] " +
+    "aria-[expanded=true]:bg-[var(--color-surface-hover)] aria-[expanded=true]:text-[var(--color-text-primary)]";
 /**
  * DropdownTrigger component - wraps the trigger element
  */
@@ -37,7 +55,9 @@ const DropdownTrigger = ({ children, className }) => {
         "aria-haspopup": "menu",
         "aria-controls": isOpen ? menuId : undefined,
         "data-state": isOpen ? "open" : "closed",
-        className: className || ((_a = childElement.props) === null || _a === void 0 ? void 0 : _a.className),
+        // Default interaction style first → child's own className (and the Trigger's
+        // `className` prop) override it.
+        className: cn(triggerInteractionStyle, (_a = childElement.props) === null || _a === void 0 ? void 0 : _a.className, className),
     });
     return trigger;
 };

package/dist/components/core/HeroCard/HeroCard.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useRef, useCallback, useEffect } from 'react';
 import { useReducedMotion } from 'motion/react';

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

@@ -1,6 +1,6 @@
 const heroCardTheme = {
     // Shares Card's radius token; gradient runs on the primary scale so it follows the app theme.
-    baseStyle: "relative overflow-hidden rounded-[calc(var(--card-radius)*2)] p-10 text-white bg-gradient-to-br from-[var(--color-primary-600)] via-[var(--color-primary-700)] to-[var(--color-primary-500)] ring-4 ring-[var(--color-primary)]/20 ",
+    baseStyle: "relative overflow-hidden rounded-[calc(var(--card-radius)*2)] p-10 text-[var(--color-primary-contrast)] bg-gradient-to-br from-[var(--color-primary-600)] via-[var(--color-primary-700)] to-[var(--color-primary-500)] ring-4 ring-[var(--color-primary)]/20 ",
     imageStyle: "absolute inset-0 z-0 pointer-events-none bg-cover",
     contentStyle: "relative z-10",
 };

package/dist/components/core/ImagePlaceholder/ImagePlaceholder.js

@@ -16,9 +16,18 @@ import { imagePlaceholderTheme } from './ImagePlaceholder.theme.js';
  * </ImagePlaceholder>
  * ```
  */
-const ImagePlaceholder = React__default.forwardRef(({ ratio = 16 / 9, bordered = true, rounded = true, pattern, children, className, ...rest }, ref) => {
+const ImagePlaceholder = React__default.forwardRef((props, ref) => {
+    // `ratio` is intentionally NOT given a destructured default: JSX preserves
+    // an explicit `ratio={undefined}` as an own "ratio" key on `props` (with
+    // value `undefined`), distinct from omitting the prop entirely (no key at
+    // all). That distinction is what lets `ratio={undefined}` genuinely skip
+    // the AspectRatio wrapper, while an omitted `ratio` still falls back to
+    // the documented 16:9 default.
+    const { ratio: ratioProp, bordered = true, rounded = true, pattern, children, className, ...rest } = props;
+    const skipAspectRatio = "ratio" in props && ratioProp === undefined;
+    const ratio = ratioProp === undefined ? 16 / 9 : ratioProp;
     const surface = (jsxs("div", { ref: ref, className: cn(imagePlaceholderTheme.surfaceStyle, rounded && imagePlaceholderTheme.roundedStyle, bordered && imagePlaceholderTheme.borderedStyle, className), ...rest, children: [jsx(StripePattern, { ...pattern }), children !== undefined && (jsx("div", { className: imagePlaceholderTheme.contentStyle, children: children }))] }));
-    if (ratio === undefined) {
+    if (skipAspectRatio) {
         return surface;
     }
     return jsx(AspectRatio, { ratio: ratio, children: surface });

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

@@ -1,7 +1,7 @@
 const imagePlaceholderTheme = {
-    surfaceStyle: "relative w-full h-full overflow-hidden bg-[var(--color-background-secondary)]",
+    surfaceStyle: "relative w-full h-full overflow-hidden bg-[var(--color-surface-sunken)]",
     borderedStyle: "border border-dashed border-[var(--color-border)]",
-    roundedStyle: "rounded-[var(--card-rounded)]",
+    roundedStyle: "rounded-[var(--card-radius)]",
     contentStyle: "absolute inset-0 z-10 flex items-center justify-center text-[var(--color-text-muted)]",
 };
 

package/dist/components/core/Link/Link.d.ts

@@ -1,4 +1,4 @@
 import React from "react";
 import { LinkProps } from "./Link.types";
-declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;
+declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement>>;
 export { Link };

package/dist/components/core/Link/Link.js

@@ -1,41 +1,70 @@
-import { jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
-import { buttonTheme } from '../Button/Button.theme.js';
 import { cn } from '../../../utils/cn.js';
 
-const Link = React__default.forwardRef(({ children, className = "", size = "inherit", disabled = false, href, 
+/**
+ * Link — a simple, text-styled link.
+ *
+ * Polymorphic by behavior: renders an `<a>` when `href` is provided (real
+ * navigation) and a `<button>` otherwise (an action styled as a link). The
+ * link styling is self-contained here; override anything via `className`.
+ */
+// Resting link look (transparent; underline grows in on hover via the motion
+// span below). Kept minimal and open.
+const LINK_BASE = "relative inline-flex items-center justify-center gap-2 bg-transparent border-transparent cursor-pointer " +
+    "transition-colors duration-300 ease-in-out " +
+    "focus:outline-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2";
+// Animated underline — a bottom-anchored line that scales in from the left on
+// hover/focus. `bg-current` inherits each color variant's text tint.
+const LINK_UNDERLINE = "pointer-events-none absolute bottom-0 left-0 h-px w-full bg-current";
+const UNDERLINE_VARIANTS = { rest: { scaleX: 0 }, hover: { scaleX: 1 } };
+// Text tint per semantic color — the one thing `color` drives.
+const LINK_COLORS = {
+    neutral: "text-[var(--color-text-secondary)] hover:text-[var(--color-text-primary)] " +
+        "focus-visible:outline-[var(--color-text-secondary)] dark:text-[var(--color-text-primary)]",
+    primary: "text-[var(--color-primary-600)] focus-visible:outline-[var(--color-primary-600)] " +
+        "dark:text-[var(--color-primary-300)]",
+    success: "text-[var(--color-success-600)] focus-visible:outline-[var(--color-success-600)] " +
+        "dark:text-[var(--color-success-300)]",
+    warning: "text-[var(--color-warning-600)] focus-visible:outline-[var(--color-warning-600)] " +
+        "dark:text-[var(--color-warning-300)]",
+    danger: "text-[var(--color-danger-600)] focus-visible:outline-[var(--color-danger-600)] " +
+        "dark:text-[var(--color-danger-300)]",
+};
+const LINK_DISABLED = "opacity-50 cursor-not-allowed pointer-events-none";
+// Size map — `inherit` matches surrounding text (default).
+const LINK_SIZES = {
+    inherit: "h-fit",
+    sm: "font-semibold p-0 text-sm h-fit",
+    md: "font-semibold p-0 text-sm h-fit",
+};
+const Link = React__default.forwardRef(({ children, className = "", size = "inherit", color = "primary", disabled = false, href, type = "button", 
 // Destructure motion-conflicting props to avoid type issues
 onAnimationStart: _onAnimationStart, onAnimationEnd: _onAnimationEnd, onDrag: _onDrag, onDragStart: _onDragStart, onDragEnd: _onDragEnd, ...props }, ref) => {
     const shouldReduceMotion = useReducedMotion();
-    const color = "primary"; // Default to primary, can be overridden by className
-    // A link is essentially a button with variant="link"
-    const resolvedVariant = "link";
-    // Memoize theme classes for performance
-    const themeClasses = useMemo(() => {
-        var _a, _b, _c, _d, _e, _f;
-        const sizeClasses = size === "inherit"
-            ? "h-fit"
-            : ((_b = (_a = buttonTheme.sizes) === null || _a === void 0 ? void 0 : _a[size]) === null || _b === void 0 ? void 0 : _b[resolvedVariant]) || "";
-        const colorClasses = ((_d = (_c = buttonTheme.variantColors) === null || _c === void 0 ? void 0 : _c[resolvedVariant]) === null || _d === void 0 ? void 0 : _d[color]) || "";
-        const variantClasses = ((_e = buttonTheme.variantStyles) === null || _e === void 0 ? void 0 : _e[resolvedVariant]) || "";
-        const stateClasses = disabled ? ((_f = buttonTheme.states) === null || _f === void 0 ? void 0 : _f.disabled) || "" : "";
-        return {
-            sizeClasses,
-            colorClasses,
-            variantClasses,
-            stateClasses,
-        };
-    }, [size, color, disabled]);
-    const animationProps = useMemo(() => shouldReduceMotion
+    const classes = cn(LINK_BASE, LINK_COLORS[color], LINK_SIZES[size], disabled && LINK_DISABLED, className);
+    // Drive the underline via variant propagation: the parent toggles the
+    // "hover" label on hover/focus, the underline span reads its own variant.
+    const animationProps = useMemo(() => disabled
         ? {}
         : {
-            whileHover: { scale: 1.02 },
-            whileTap: { scale: 0.98 },
-        }, [shouldReduceMotion]);
-    return (jsx(motion.a, { ref: ref, href: disabled ? undefined : href, className: cn(buttonTheme.baseStyle, themeClasses.colorClasses, themeClasses.variantClasses, themeClasses.sizeClasses, themeClasses.stateClasses, 
-        // Special case for link variant to have an underline
-        "underline underline-offset-4 rounded-none font-semibold text-sm", className), "data-color": color, "data-variant": resolvedVariant, "data-size": size, "aria-disabled": disabled || undefined, ...(disabled ? {} : animationProps), ...props, children: children }));
+            initial: "rest",
+            animate: "rest",
+            whileHover: "hover",
+            whileFocus: "hover",
+            ...(shouldReduceMotion ? {} : { whileTap: { scale: 0.98 } }),
+        }, [shouldReduceMotion, disabled]);
+    const underlineTransition = shouldReduceMotion
+        ? { duration: 0 }
+        : { duration: 0.3, ease: "easeInOut" };
+    const underline = !disabled ? (jsx(motion.span, { "aria-hidden": "true", className: LINK_UNDERLINE, style: { originX: 0 }, variants: UNDERLINE_VARIANTS, transition: underlineTransition })) : null;
+    // `href` → real navigational anchor; otherwise an action button.
+    if (href !== undefined) {
+        return (jsxs(motion.a, { ref: ref, href: disabled ? undefined : href, className: classes, "data-size": size, "aria-disabled": disabled || undefined, ...animationProps, ...props, children: [children, underline] }));
+    }
+    return (jsxs(motion.button, { ref: ref, type: type, className: classes, "data-size": size, disabled: disabled, "aria-disabled": disabled || undefined, ...animationProps, ...props, children: [children, underline] }));
 });
 Link.displayName = "Link";
 

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

@@ -1,22 +1,39 @@
 import React from "react";
-import { ButtonSize } from "../Button";
-export type LinkSize = ButtonSize | "inherit";
+import { SemanticColor } from "../../../utils/colorUtils";
+export type LinkSize = "sm" | "md" | "inherit";
+/** Link semantic color — the shared SemanticColor set (matches Button/Alert/Badge). */
+export type LinkColor = SemanticColor;
 /**
- * Link component props
- * Extends standard anchor attributes.
+ * Link component props.
+ *
+ * Polymorphic by behavior: pass `href` to render a navigational `<a>`; omit it
+ * (and pass `onClick`) to render a real `<button>` styled as a link. This lets
+ * Link stand in for both hyperlinks and low-emphasis text-action buttons
+ * without the accessibility cost of a clickable anchor that has no href.
  */
-export interface LinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'color'> {
+export interface LinkProps extends Omit<React.HTMLAttributes<HTMLElement>, "color"> {
     /**
      * The size of the link.
      * @default "inherit"
      */
     size?: LinkSize;
-    /** The state of the link */
+    /**
+     * Semantic color.
+     * @default "primary"
+     */
+    color?: LinkColor;
+    /** Whether the link is disabled. */
     disabled?: boolean;
     /** Link contents */
     children?: React.ReactNode;
-    /** Additional class names */
+    /** Additional class names (highest-priority style override) */
     className?: string;
-    /** The URL that the hyperlink points to. */
+    /** The URL the hyperlink points to. When set, Link renders an `<a>`. */
     href?: string;
+    /** Anchor target (only meaningful with `href`). */
+    target?: string;
+    /** Anchor rel (only meaningful with `href`). */
+    rel?: string;
+    /** Button type when rendered as a `<button>` (no `href`). @default "button" */
+    type?: "button" | "submit" | "reset";
 }