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

package/dist/components/core/Alert/Alert.js

@@ -1,7 +1,10 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
-import React__default from 'react';
+import React__default, { useState } from 'react';
+import { useReducedMotion, motion } from 'motion/react';
 import { cn } from '../../../utils/cn.js';
 import { alertTheme } from './Alert.theme.js';
+import { reducedMotionAlertVariants, alertVariants } from './Alert.animations.js';
 import { XMarkIcon, XCircleIcon, ExclamationTriangleIcon, CheckCircleIcon, InformationCircleIcon, BellIcon } from '@heroicons/react/24/solid';
 import { Button } from '../Button/Button.js';
 
@@ -12,12 +15,18 @@ const defaultIcons = {
     warning: ExclamationTriangleIcon,
     danger: XCircleIcon,
 };
-const Alert = React__default.forwardRef(({ variant = "default", color = "primary", title, subtitle, dismissible, icon, showIcon = true, avatar, actions, onDismiss, className, children, darkMode = false, ...props }, ref) => {
+const Alert = React__default.forwardRef(({ color = "primary", title, subtitle, dismissible, icon, showIcon = true, avatar, actions, onDismiss, className, children, darkMode = false, ...props }, ref) => {
     var _a;
+    const shouldReduceMotion = useReducedMotion();
+    const [isDismissing, setIsDismissing] = useState(false);
     const iconColor = (_a = alertTheme.iconColors[color]) !== null && _a !== void 0 ? _a : alertTheme.iconColors.primary;
     const showDismiss = dismissible === true || (dismissible !== false && !!onDismiss);
     const handleDismiss = () => {
-        onDismiss === null || onDismiss === void 0 ? void 0 : onDismiss();
+        if (shouldReduceMotion) {
+            onDismiss === null || onDismiss === void 0 ? void 0 : onDismiss();
+            return;
+        }
+        setIsDismissing(true);
     };
     const renderIconOrAvatar = () => {
         if (avatar) {
@@ -32,7 +41,17 @@ const Alert = React__default.forwardRef(({ variant = "default", color = "primary
         const IconComponent = defaultIcons[color];
         return (jsx("div", { className: "flex-shrink-0 w-6 h-6 mt-1", "aria-hidden": "true", children: jsx(IconComponent, { className: cn("w-6 h-6", iconColor) }) }));
     };
-    const alertNode = (jsxs("div", { ref: ref, className: cn(alertTheme.baseStyle, alertTheme.variants[variant], className), role: "alert", "aria-live": "assertive", "aria-atomic": "true", ...props, children: [renderIconOrAvatar(), jsxs("div", { className: `flex-1 min-w-0 ${showDismiss ? "mr-5" : ""}`, children: [title && (jsx("div", { className: cn("font-semibold text-[var(--color-text-primary)]"), children: title })), subtitle && (jsx("div", { className: "text-[var(--color-text-secondary)]/90 mt-1", children: subtitle })), children && jsx("div", { className: "mt-2", children: children }), actions && (jsx("div", { className: "flex items-center gap-2 mt-6", children: actions }))] }), showDismiss && (jsx(Button, { variant: "link", color: "neutral", size: "sm", iconOnly: true, onClick: handleDismiss, "aria-label": "Dismiss alert", className: "rounded-full absolute top-2 right-2 flex-shrink-0", children: jsx(XMarkIcon, { className: "size-4", strokeWidth: 2 }) }))] }));
+    const isUrgent = color === 'danger' || color === 'warning';
+    const alertContent = (jsxs("div", { ref: ref, className: cn(alertTheme.baseStyle, className), role: isUrgent ? 'alert' : 'status', "aria-live": isUrgent ? undefined : 'polite', ...props, children: [renderIconOrAvatar(), jsxs("div", { className: `flex-1 min-w-0 ${showDismiss ? "mr-5" : ""}`, children: [title && (typeof title === 'string'
+                        ? jsx("div", { className: cn("font-semibold text-[var(--color-text-primary)]"), children: title })
+                        : title), subtitle && (typeof subtitle === 'string'
+                        ? jsx("div", { className: "text-[var(--color-text-secondary)]/90 mt-1", children: subtitle })
+                        : subtitle), children && jsx("div", { className: "mt-2", children: children }), actions && (jsx("div", { className: "flex items-center gap-2 mt-6", children: actions }))] }), showDismiss && (jsx(Button, { variant: "ghost", color: "neutral", size: "sm", iconOnly: true, onClick: handleDismiss, "aria-label": "Dismiss alert", className: "rounded-full absolute top-2 right-2 flex-shrink-0", children: jsx(XMarkIcon, { className: "size-4", strokeWidth: 2 }) }))] }));
+    const alertNode = (jsx(motion.div, { variants: shouldReduceMotion ? reducedMotionAlertVariants : alertVariants, initial: "hidden", animate: isDismissing ? "hidden" : "visible", onAnimationComplete: (definition) => {
+            if (definition === "hidden" && isDismissing) {
+                onDismiss === null || onDismiss === void 0 ? void 0 : onDismiss();
+            }
+        }, children: alertContent }));
     if (darkMode) {
         return jsx("div", { className: "dark", children: alertNode });
     }

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

@@ -1,3 +1,5 @@
+import { semanticTextColors } from '../../../utils/colorUtils.js';
+
 /**
  * Default theme configuration for Alert component
  * Uses flat color organization matching Badge pattern
@@ -5,19 +7,8 @@
 const alertTheme = {
     // Base styles applied to all alerts
     baseStyle: "relative flex items-start gap-3 rounded-[var(--alert-radius)] p-4 text-sm border border-[var(--color-border)] backdrop-blur-md bg-white dark:bg-[var(--color-background-secondary)]/80",
-    // Visual style variants (structure only, no colors)
-    variants: {
-        default: "",
-        glass: "glass-effect",
-    },
     // Icon color styles per color
-    iconColors: {
-        neutral: "text-[var(--color-text-primary)]",
-        primary: "text-[var(--color-primary)]",
-        success: "text-[var(--color-success)]",
-        warning: "text-[var(--color-warning)]",
-        danger: "text-[var(--color-danger)]",
-    },
+    iconColors: semanticTextColors,
     // State styles
     states: {
         dismissible: "pr-10",

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

@@ -1,20 +1,15 @@
 import { HTMLAttributes, ReactNode } from "react";
+import { SemanticColor } from "../../../utils/colorUtils";
 /**
  * Alert semantic colors (intent)
  */
-export type AlertColor = "neutral" | "primary" | "success" | "warning" | "danger";
-/**
- * Alert visual variant
- */
-export type AlertVariant = "default" | "glass";
+export type AlertColor = SemanticColor;
 /**
  * Theme configuration for Alert component
  */
 export interface AlertTheme {
     /** Base styles applied to all alerts */
     baseStyle: string;
-    /** Visual style variants (structure only, no colors) */
-    variants: Record<AlertVariant, string>;
     /** Icon color styles per color */
     iconColors: Record<AlertColor, string>;
     /** State styles */
@@ -22,15 +17,13 @@ export interface AlertTheme {
         dismissible: string;
     };
 }
-export interface AlertProps extends HTMLAttributes<HTMLDivElement> {
-    /** Visual variant */
-    variant?: AlertVariant;
+export interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
     /** Semantic color */
     color?: AlertColor;
     /** The main title/message of the alert */
-    title?: string;
+    title?: ReactNode;
     /** Additional subtitle text */
-    subtitle?: string;
+    subtitle?: ReactNode;
     /** Whether the alert can be dismissed */
     dismissible?: boolean;
     /**
@@ -44,7 +37,7 @@ export interface AlertProps extends HTMLAttributes<HTMLDivElement> {
     showIcon?: boolean;
     /**
      * Avatar to display (takes precedence over icons)
-     * Example: avatar={<Avatar src="..." alt="User name" size="md" />}
+     * Example: avatar={<Avatar src="..." name="User name" size="md" />}
      */
     avatar?: ReactNode;
     /**

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

@@ -1,3 +1,3 @@
 export { Alert } from './Alert';
-export type { AlertProps, AlertVariant, AlertColor, AlertTheme } from './Alert.types';
+export type { AlertProps, AlertColor, AlertTheme } from './Alert.types';
 export { alertTheme } from './Alert.theme';

package/dist/components/core/AlertDialog/AlertDialog.js

@@ -1,8 +1,22 @@
+"use client";
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 import { useState, isValidElement, cloneElement } from 'react';
 import { Modal } from '../Modal/Modal.js';
 import { cn } from '../../../utils/cn.js';
+import { useModalContext } from '../Modal/ModalContext.js';
 
+/**
+ * Renders AlertDialog's subtitle and stamps Modal's computed `subtitleId`
+ * onto the actual element so `aria-describedby` (wired up by Modal.tsx)
+ * resolves to a real node. `Modal.Subtitle` isn't used here because it
+ * always renders a `<p>`, and AlertDialog's subtitle can carry block-level
+ * content (e.g. a nested `Select`) which is invalid inside a paragraph.
+ * Must be rendered as a descendant of `<Modal>` so `useModalContext` resolves.
+ */
+function AlertDialogSubtitle({ children }) {
+    const { subtitleId } = useModalContext();
+    return (jsx("div", { id: subtitleId, className: "text-[var(--color-text-secondary)] text-base", children: children }));
+}
 const AlertDialog = ({ trigger, icon, title, subtitle, footer, className, }) => {
     const [isOpen, setIsOpen] = useState(false);
     const handleOpen = () => setIsOpen(true);
@@ -10,7 +24,7 @@ const AlertDialog = ({ trigger, icon, title, subtitle, footer, className, }) =>
     const triggerElement = isValidElement(trigger)
         ? cloneElement(trigger, { onClick: handleOpen })
         : null;
-    return (jsxs(Fragment, { children: [triggerElement, jsxs(Modal, { isOpen: isOpen, onClose: handleClose, size: "sm", closeOnOverlayClick: false, closeOnEsc: false, showCloseButton: false, role: "alertdialog", className: cn("!overflow-visible", className), children: [jsxs(Modal.Header, { children: [icon && (jsx("div", { className: "text-2xl rounded-full p-3  mb-3 w-fit glass-effect shadow-xl shadow-black/5", "aria-hidden": "true", children: icon })), jsx(Modal.Title, { children: title })] }), jsx(Modal.Body, { className: "pt-2", children: jsx("div", { className: "text-[var(--color-text-secondary)] text-sm", children: subtitle }) }), footer && (jsx(Modal.Footer, { className: "pb-6", children: footer(handleClose) }))] })] }));
+    return (jsxs(Fragment, { children: [triggerElement, jsxs(Modal, { isOpen: isOpen, onClose: handleClose, size: "sm", closeOnOverlayClick: false, closeOnEsc: !footer, showCloseButton: false, role: "alertdialog", className: cn("!overflow-visible", className), children: [jsxs(Modal.Header, { children: [icon && (jsx("div", { className: "text-2xl rounded-full p-3  mb-3 w-fit glass-effect shadow-xl shadow-black/5", "aria-hidden": "true", children: icon })), jsx(Modal.Title, { children: title })] }), jsx(Modal.Body, { className: "pt-2", children: jsx(AlertDialogSubtitle, { children: subtitle }) }), footer && (jsx(Modal.Footer, { className: "pb-6", children: footer(handleClose) }))] })] }));
 };
 AlertDialog.displayName = "AlertDialog";
 

package/dist/components/core/Avatar/Avatar.js

@@ -1,15 +1,51 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
 import React__default, { useState, useRef, useEffect, useCallback } from 'react';
 import { cn } from '../../../utils/cn.js';
 import { avatarTheme } from './Avatar.theme.js';
 import { Tooltip } from '../Tooltip/Tooltip.js';
 import '../Tooltip/Tooltip.animations.js';
+import { MeshGradient } from '../../effects/MeshGradient/MeshGradient.js';
+import { MESH_PALETTE_BY_NAME, DEFAULT_MESH_COLORS, getMeshTextTone } from '../../effects/MeshGradient/MeshGradient.utils.js';
+import { CheckBadgeIcon, UserIcon } from '@heroicons/react/24/solid';
 
-const Avatar = React__default.forwardRef(({ src, alt = "Avatar", // Default alt text for better accessibility
-size = "md", status = "none", fallback, className, role, lazyLoad = true, retryCount = 0, retryDelay = 1000, contextualLabel, groupPosition, showTooltip = false, ...props }, ref) => {
+// Number of marble shapes the gradient renders — shared by the render and the
+// text-tone calc so both read the same deterministic field. The gradient's blur
+// is resolution-independent (SVG viewBox units), so no per-size tuning is needed.
+const MESH_COUNT = 2;
+const Avatar = React__default.forwardRef(({ src, name, size = "md", status = "none", fallback, gradient = false, gradientVariant = "marble", gradientColors, className, role, lazyLoad = true, retryCount = 0, retryDelay = 1000, contextualLabel, groupPosition, showTooltip = false, initialsCount = 2, title, subtitle, verified = false, ...props }, ref) => {
+    var _a;
     const [imageError, setImageError] = useState(false);
     const [retries, setRetries] = useState(0);
     const retryTimerRef = useRef(null);
+    // Normalize null to undefined for internal use
+    const resolvedName = name !== null && name !== void 0 ? name : undefined;
+    // Initials derived from the name (xs shows a single initial).
+    const initials = resolvedName
+        ? resolvedName
+            .split(" ")
+            .map((part) => part[0])
+            .slice(0, size === "xs" ? 1 : initialsCount)
+            .join("")
+            .toUpperCase()
+        : "";
+    // Seed the background gradient from an explicit string, else the name.
+    const gradientSeed = typeof gradient === "string" ? gradient : (resolvedName !== null && resolvedName !== void 0 ? resolvedName : "avatar");
+    // Resolve the palette: raw `gradientColors` wins, else the named variant,
+    // falling back to the default marble set.
+    const gradientPalette = gradientColors && gradientColors.length
+        ? gradientColors
+        : ((_a = MESH_PALETTE_BY_NAME[gradientVariant]) !== null && _a !== void 0 ? _a : DEFAULT_MESH_COLORS);
+    // Auto-pick readable initials color from the gradient's luminance, using the
+    // theme-stable neutral tokens (so the choice holds in light AND dark mode).
+    const gradientTextColor = gradient
+        ? getMeshTextTone(gradientSeed, gradientPalette, MESH_COUNT) === "dark"
+            ? "text-[var(--color-neutral-950)]"
+            : "text-[var(--color-neutral-50)]"
+        : undefined;
+    // Glyph shown over the gradient: explicit fallback, else initials, else none
+    // (a clean gradient — no default user icon when there's no name).
+    const gradientGlyph = fallback !== null && fallback !== void 0 ? fallback : (initials ? jsx("span", { "aria-hidden": "true", children: initials }) : null);
     // Clear timeout on unmount to prevent memory leaks
     useEffect(() => {
         return () => {
@@ -43,21 +79,16 @@ size = "md", status = "none", fallback, className, role, lazyLoad = true, retryC
     }, [retries, retryCount, retryDelay]);
     // Handle fallback content
     const getFallbackContent = () => {
+        // 1. Explicit fallback always wins
         if (fallback) {
             return fallback;
         }
-        // If no fallback provided and no alt text, use placeholder
-        if (alt === "Avatar") {
-            return jsx("span", { "aria-hidden": "true", children: "?" });
+        // 2. Generate initials from name
+        if (initials) {
+            return jsx("span", { "aria-hidden": "true", children: initials });
         }
-        // Use initials from alt text
-        const initials = alt
-            .split(" ")
-            .map((part) => part[0])
-            .slice(0, 1)
-            .join("")
-            .toUpperCase();
-        return jsx("span", { "aria-hidden": "true", children: initials });
+        // 3. Default placeholder icon
+        return jsx(UserIcon, { className: "w-1/2 h-1/2" });
     };
     // Determine status indicator size based on avatar size
     const getStatusSize = () => {
@@ -76,19 +107,45 @@ size = "md", status = "none", fallback, className, role, lazyLoad = true, retryC
                 return "size-2 left-0 bottom-0";
         }
     };
+    // Determine verified badge size based on avatar size
+    const getVerifiedBadgeSize = () => {
+        switch (size) {
+            case "xs":
+                return "size-2.5 -right-0.5 -bottom-0.5";
+            case "sm":
+                return "size-3.5 -right-0.5 -bottom-0.5";
+            case "md":
+                return "size-4 -right-0.5 -bottom-0.5";
+            case "lg":
+                return "size-5 -right-1 -bottom-1";
+            case "xl":
+                return "size-6 -right-1.5 -bottom-1.5";
+            default:
+                return "size-4 -right-0.5 -bottom-0.5";
+        }
+    };
     // Create full accessibility label including context if provided
     const accessibilityLabel = contextualLabel
-        ? `${alt}${contextualLabel}`
-        : alt;
+        ? `${resolvedName !== null && resolvedName !== void 0 ? resolvedName : "Avatar"}${contextualLabel}`
+        : (resolvedName !== null && resolvedName !== void 0 ? resolvedName : "Avatar");
     // Determine appropriate ARIA role
     const ariaRole = role || (src ? undefined : "img");
-    // Avatar content to potentially wrap in tooltip
-    const avatarContent = (jsxs("div", { ref: ref, className: cn("relative inline-flex avatar-wrapper", groupPosition), role: ariaRole === "presentation" ? "presentation" : undefined, "aria-label": ariaRole === "presentation" ? undefined : accessibilityLabel, "data-size": size, "data-status": status, "data-error": imageError ? "true" : "false", ...props, children: [jsx("div", { className: cn(avatarTheme.baseStyle, avatarTheme.sizes[size], className), "aria-hidden": ariaRole === "presentation" ? "true" : undefined, "data-size": size, children: src && !imageError ? (jsx("img", { src: src, alt: alt, className: "size-full object-cover object-top", onError: handleImageError, loading: lazyLoad ? "lazy" : undefined, "aria-hidden": ariaRole === "presentation" ? "true" : undefined, "data-loaded": "true" })) : (jsx("div", { className: "avatar-fallback", children: getFallbackContent() })) }), status !== "none" && (jsx("span", { className: cn("absolute rounded-full ring-2 ring-[var(--color-background)]", getStatusSize(), avatarTheme.statuses[status]), "aria-label": `Status: ${status}`, role: "status", "data-status": status }))] }));
-    // Conditionally wrap in tooltip
-    if (showTooltip && alt && alt !== "Avatar") {
-        return (jsx(Tooltip, { content: alt, placement: "top", children: avatarContent }));
+    const resolvedTitle = title !== null && title !== void 0 ? title : (subtitle ? resolvedName : undefined);
+    const hasTextSection = !!(resolvedTitle || subtitle);
+    // The avatar circle with status indicator
+    const avatarCircle = (jsxs("div", { className: cn("relative inline-flex avatar-wrapper shrink-0", groupPosition), children: [jsxs("div", { className: cn(avatarTheme.baseStyle, avatarTheme.sizes[size], className), "aria-hidden": ariaRole === "presentation" ? "true" : undefined, "data-size": size, children: [gradient && (jsx(MeshGradient, { seed: gradientSeed, colors: gradientPalette, count: MESH_COUNT })), src && !imageError ? (jsx("img", { src: src, alt: resolvedName !== null && resolvedName !== void 0 ? resolvedName : "Avatar", className: "relative z-10 size-full object-cover object-top", onError: handleImageError, loading: lazyLoad ? "lazy" : undefined, "aria-hidden": ariaRole === "presentation" ? "true" : undefined, "data-loaded": "true" })) : (jsx("div", { className: cn("avatar-fallback relative z-10 flex items-center justify-center size-full", gradient && cn(gradientTextColor, "drop-shadow")), children: gradient ? gradientGlyph : getFallbackContent() }))] }), status !== "none" && (jsx("span", { className: cn("absolute rounded-full ring-2 ring-[var(--color-background)]", getStatusSize(), avatarTheme.statuses[status]), "aria-label": `Status: ${status}`, role: "status", "data-status": status })), verified && (jsx("span", { className: cn("absolute rounded-full inline-grid place-items-center ring-2 ring-[var(--color-background)] bg-white dark:bg-[var(--color-surface)] shadow-sm", getVerifiedBadgeSize()), "aria-label": "Verified", children: jsx(CheckBadgeIcon, { className: "size-full text-[var(--color-primary)]" }) }))] }));
+    // Wrap circle in tooltip if needed
+    const avatarWithTooltip = showTooltip && resolvedName ? (jsx(Tooltip, { content: resolvedName, placement: "top", children: avatarCircle })) : (avatarCircle);
+    // If no text section, render just the avatar
+    if (!hasTextSection) {
+        return (jsx("div", { ref: ref, 
+            // inline-flex so the inline-flex circle is a flex child, not inline-level
+            // content — a plain block wrapper leaves a ~5px baseline descender below
+            // the circle, inflating the box and misaligning AvatarGroup's overflow chip.
+            className: "inline-flex", role: ariaRole, "aria-label": ariaRole === "presentation" ? undefined : accessibilityLabel, "data-size": size, "data-status": status, "data-error": imageError ? "true" : "false", ...props, children: avatarWithTooltip }));
     }
-    return avatarContent;
+    // Render avatar with text section
+    return (jsxs("div", { ref: ref, className: cn("inline-flex items-center", avatarTheme.gapSizes[size]), role: ariaRole, "aria-label": ariaRole === "presentation" ? undefined : accessibilityLabel, "data-size": size, "data-status": status, "data-error": imageError ? "true" : "false", ...props, children: [avatarWithTooltip, jsxs("div", { className: "min-w-0", children: [resolvedTitle && (jsx("div", { className: cn(avatarTheme.titleStyle, avatarTheme.textSizes[size]), children: resolvedTitle })), subtitle && (jsx("div", { className: cn(avatarTheme.subtitleStyle, avatarTheme.textSizes[size]), children: subtitle }))] })] }));
 });
 // Set display name for dev tools and Storybook
 Avatar.displayName = "Avatar";

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

@@ -1,14 +1,12 @@
 import { AvatarSize, AvatarStatus } from "./Avatar.types";
-/**
- * Internal theme structure for the Avatar component
- */
 interface AvatarTheme {
     baseStyle: string;
     sizes: Record<AvatarSize, string>;
     statuses: Record<AvatarStatus, string>;
+    titleStyle: string;
+    subtitleStyle: string;
+    textSizes: Record<AvatarSize, string>;
+    gapSizes: Record<AvatarSize, string>;
 }
-/**
- * Default theme for the Avatar component
- */
 export declare const avatarTheme: AvatarTheme;
 export {};

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

@@ -1,25 +1,35 @@
-/**
- * Default theme for the Avatar component
- */
 const avatarTheme = {
-    // Base styles for the avatar element
-    baseStyle: "relative inline-flex items-center justify-center overflow-hidden bg-neutral-200 text-[var(--color-text-primary)] font-semibold tracking-tighter rounded-[var(--avatar-radius)] ring-2 ring-[var(--color-primary)]/10 border border-[var(--border)] transition-all duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 glass-effect",
-    // Size variants using CSS variables
+    baseStyle: "relative inline-flex items-center justify-center overflow-hidden bg-[var(--color-surface)] text-[var(--color-text-primary)] font-bold tracking-tighter rounded-[var(--avatar-radius)] border border-[var(--color-border)] transition-all duration-200 focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2",
     sizes: {
-        xs: "size-[var(--avatar-size-xs)] text-[var(--avatar-text-xs)]",
-        sm: "size-[var(--avatar-size-sm)] text-[var(--avatar-text-sm)]",
-        md: "size-[var(--avatar-size-md)] text-[var(--avatar-text-md)]",
-        lg: "size-[var(--avatar-size-lg)] text-[var(--avatar-text-lg)]",
-        xl: "size-[var(--avatar-size-xl)] text-[var(--avatar-text-xl)]",
+        xs: "size-[var(--avatar-size-xs)] text-xs",
+        sm: "size-[var(--avatar-size-sm)] text-xs",
+        md: "size-[var(--avatar-size-md)] text-sm",
+        lg: "size-[var(--avatar-size-lg)] text-sm",
+        xl: "size-[var(--avatar-size-xl)] text-sm",
     },
-    // Status indicator styles
     statuses: {
         online: "bg-[var(--color-success)]",
-        offline: "bg-neutral-400",
+        offline: "bg-[var(--color-text-muted)]",
         busy: "bg-[var(--color-danger)]",
         away: "bg-[var(--color-warning)]",
         none: "",
     },
+    titleStyle: "font-medium leading-tight text-[var(--color-text-primary)] truncate",
+    subtitleStyle: "leading-tight text-[var(--color-text-muted)] truncate",
+    textSizes: {
+        xs: "text-xs",
+        sm: "text-xs",
+        md: "text-sm",
+        lg: "text-sm",
+        xl: "text-sm",
+    },
+    gapSizes: {
+        xs: "gap-1.5",
+        sm: "gap-2",
+        md: "gap-2.5",
+        lg: "gap-3",
+        xl: "gap-3",
+    },
 };
 
 export { avatarTheme };

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

@@ -1,17 +1,18 @@
-import { ReactNode } from 'react';
-export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-export type AvatarStatus = 'online' | 'offline' | 'busy' | 'away' | 'none';
+import { ReactNode } from "react";
+import type { MeshPaletteName } from "../../effects/MeshGradient";
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | number;
+export type AvatarStatus = "online" | "offline" | "busy" | "away" | "none";
 export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
     /**
      * The source URL for the avatar image
      */
     src?: string;
     /**
-     * Alternative text for the avatar image.
-     * Should describe the person or entity represented by the avatar.
-     * @default "Avatar"
+     * The name of the person or entity represented by the avatar.
+     * Used to generate initials for the fallback and as alt text for the image.
+     * Accepts `null` for compatibility with nullable data sources.
      */
-    alt?: string;
+    name?: string | null;
     /**
      * The size of the avatar
      * @default "md"
@@ -23,9 +24,30 @@ export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     status?: AvatarStatus;
     /**
-     * Fallback content to display when image fails to load or no src is provided
+     * Fallback content to display when image fails to load or no src is provided.
+     * Overrides the default placeholder icon and auto-generated initials.
      */
     fallback?: ReactNode;
+    /**
+     * Render a deterministic mesh-gradient as the avatar's background layer. The
+     * image (when present) sits over it, and the initials/icon overlay on top in
+     * white — so it shows through as a colorful, identicon-style backdrop whenever
+     * there's no image. Pass `true` to seed from `name`, or a string for an
+     * explicit, stable seed (e.g. a user id).
+     * @default false
+     */
+    gradient?: boolean | string;
+    /**
+     * Curated color palette for the gradient background. Only applies when
+     * `gradient` is set. Overridden by `gradientColors` when that is provided.
+     * @default "marble"
+     */
+    gradientVariant?: MeshPaletteName;
+    /**
+     * Raw color override for the gradient background (any CSS colors). Wins over
+     * `gradientVariant`. Only applies when `gradient` is set.
+     */
+    gradientColors?: string[];
     /**
      * ARIA role for the avatar
      * Use "presentation" for purely decorative avatars
@@ -66,4 +88,17 @@ export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
      * @default 2
      */
     initialsCount?: number;
+    /**
+     * Title text displayed next to the avatar.
+     * Defaults to `name` if not provided.
+     */
+    title?: string;
+    /**
+     * Subtitle text displayed below the title (e.g., email, role).
+     */
+    subtitle?: string;
+    /**
+     * Whether to show a verification badge overlay at the bottom right.
+     */
+    verified?: boolean;
 }

package/dist/components/core/AvatarGroup/AvatarGroup.animations.js

@@ -1,3 +1,4 @@
+"use client";
 /**
  * Animation variants for AvatarGroup hover effects
  * Creates a "Fan Pop" effect where:
@@ -38,8 +39,8 @@ const getAvatarGroupVariants = (shouldReduceMotion = false, enableAnimations = t
         },
         notHovered: () => {
             return {
-                scale: 0.95,
-                y: 2,
+                scale: 1,
+                y: 0,
                 filter: "saturate(0)",
                 transition: {
                     type: "spring",

package/dist/components/core/AvatarGroup/AvatarGroup.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useState, useMemo } from 'react';
 import { useReducedMotion, motion } from 'motion/react';
@@ -18,7 +19,7 @@ const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "
         const directionClass = direction === "row-reverse" ? "flex-row-reverse" : "flex-row";
         const totalPeople = avatars.length;
         const groupDescription = avatars
-            .map((avatar) => avatar.alt || "User")
+            .map((avatar) => avatar.name || "User")
             .join(", ");
         return {
             visibleAvatars,
@@ -44,12 +45,15 @@ const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "
                     }
                     : {};
                 return (jsx(MotionDiv, { className: cn(
+                    // flex (not the default block) so the inline-flex Avatar is a flex
+                    // child — a block wrapper would leave a baseline descender below it,
+                    // inflating the row and dropping the self-centered overflow chip.
+                    "flex", 
                     // First avatar doesn't need negative margin
                     index > 0 ? spacingClass : "z-10"), "data-position": position, "data-index": index, ...motionProps, children: jsx(Avatar, { size: size, ...avatarProps, contextualLabel: contextLabel, 
                         // Ensure that groupPosition is not passed to avoid conflicts
                         groupPosition: undefined }) }, index));
-            }), overflowCount > 0 && (jsx("div", { className: cn(spacingClass, enableAnimations &&
-                    "transition-transform duration-200 hover:scale-110"), "data-overflow-count": overflowCount, children: overflowIndicator ? (overflowIndicator(overflowCount)) : (jsx(Avatar, { size: size, alt: `+${overflowCount} more`, fallback: jsxs("span", { children: ["+", overflowCount] }), className: avatarGroupTheme.overflowAvatarStyle, role: "img", "aria-label": `+ ${overflowCount} more users` })) }))] }));
+            }), overflowCount > 0 && (jsx("div", { className: cn("flex", spacingClass), "data-overflow-count": overflowCount, children: overflowIndicator ? (overflowIndicator(overflowCount)) : (jsx(Avatar, { size: size, name: `+${overflowCount} more`, fallback: jsxs("span", { children: ["+", overflowCount] }), className: avatarGroupTheme.overflowAvatarStyle, role: "img", "aria-label": `+ ${overflowCount} more users` })) }))] }));
 });
 // Set display name for dev tools and Storybook
 AvatarGroup.displayName = "AvatarGroup";

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

@@ -3,7 +3,9 @@
  */
 const avatarGroupTheme = {
     // Base styles for the avatar group
-    baseStyle: "flex items-start",
+    baseStyle: "flex items-center",
+    // NOTE: items-center only works because Avatar's wrapper no longer leaves a
+    // baseline descender below the circle (Avatar.tsx wrapper is inline-flex).
     // Spacing options - separated from hover effects
     spacingStyles: {
         tight: "-ml-5 z-10",
@@ -11,7 +13,7 @@ const avatarGroupTheme = {
         loose: "-ml-2 z-10",
     },
     // Overflow avatar styles
-    overflowAvatarStyle: "bg-[var(--color-neutral-100)] text-[var(--color-text-primary)] font-semibold text-sm flex items-center justify-center hover:bg-neutral-200 transition-colors duration-200",
+    overflowAvatarStyle: "bg-[var(--color-surface)]/60 backdrop-blur-sm text-[var(--color-text-secondary)] font-bold tracking-tight text-[10px] flex items-center justify-center size-6",
 };
 
 export { avatarGroupTheme };

package/dist/components/core/Badge/Badge.animations.js

@@ -1,3 +1,4 @@
+"use client";
 // Main badge variants with optimized transitions
 const badgeVariants = {
     initial: {
@@ -53,7 +54,7 @@ const dotVariants = {
 // Dismiss button variants - optimized for performance
 const dismissButtonVariants = {
     initial: {
-        opacity: 0.5,
+        opacity: 0.75,
     },
     hover: {
         opacity: 1,

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

@@ -11,4 +11,4 @@ import { BadgeProps } from "./Badge.types";
  * <Badge dismissible onDismiss={handleDismiss}>Removable</Badge>
  * ```
  */
-export declare const Badge: React.NamedExoticComponent<Omit<BadgeProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const Badge: React.NamedExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;