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

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

@@ -1,15 +1,90 @@
-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 { SealCheck, User } from '@phosphor-icons/react';
 
-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;
+// Each token's geometry, as the CSS variable that carries its px value. Keeping
+// the indirection means a themed `--avatar-size-*` still flows through.
+const SIZE_TOKEN_VAR = {
+    xs: "var(--avatar-size-xs)",
+    sm: "var(--avatar-size-sm)",
+    md: "var(--avatar-size-md)",
+    lg: "var(--avatar-size-lg)",
+    xl: "var(--avatar-size-xl)",
+};
+// The default px ladder from `theme.css`, mirrored here for ONE purpose: picking
+// which rung a numeric size's decorations (glyph, status dot, verified badge,
+// text gap) should borrow. Geometry never reads this — it always resolves
+// through the CSS variable above — so a theme that retunes the ladder still
+// sizes correctly; only the rung chosen for a numeric size reads the defaults.
+const SIZE_TOKEN_PX = {
+    xs: 24,
+    sm: 32,
+    md: 40,
+    lg: 48,
+    xl: 64,
+};
+const isSizeToken = (size) => typeof size === "string";
+/** The rung a size sits closest to. Identity for tokens. */
+const nearestSizeToken = (size) => {
+    if (isSizeToken(size))
+        return size;
+    return Object.keys(SIZE_TOKEN_PX).reduce((best, token) => Math.abs(SIZE_TOKEN_PX[token] - size) < Math.abs(SIZE_TOKEN_PX[best] - size)
+        ? token
+        : best);
+};
+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);
+    if (process.env.NODE_ENV !== "production" &&
+        typeof size === "number" &&
+        (!Number.isFinite(size) || size <= 0)) {
+        // eslint-disable-next-line no-console
+        console.warn(`[Avatar]: \`size\` must be a positive number of pixels; received ${size}.`);
+    }
+    // Exact geometry for the circle; nearest rung for everything hung off it.
+    const sizeValue = isSizeToken(size) ? SIZE_TOKEN_VAR[size] : `${size}px`;
+    const sizeToken = nearestSizeToken(size);
+    // Normalize null to undefined for internal use
+    const resolvedName = name !== null && name !== void 0 ? name : undefined;
+    // Initials derived from the name (the xs rung shows a single initial).
+    const initials = resolvedName
+        ? resolvedName
+            .split(" ")
+            .map((part) => part[0])
+            .slice(0, sizeToken === "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-mono-950)]"
+            : "text-[var(--color-mono-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,52 +118,42 @@ 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: "?" });
-        }
-        // 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 });
-    };
-    // Determine status indicator size based on avatar size
-    const getStatusSize = () => {
-        switch (size) {
-            case "xs":
-                return "size-1.5 left-0 bottom-0.5";
-            case "sm":
-                return "size-2 left-0 bottom-0";
-            case "md":
-                return "size-2 left-0 bottom-0";
-            case "lg":
-                return "size-2.5 left-0 bottom-0";
-            case "xl":
-                return "size-3 left-0 bottom-0";
-            default:
-                return "size-2 left-0 bottom-0";
+        // 2. Generate initials from name
+        if (initials) {
+            return jsx("span", { "aria-hidden": "true", children: initials });
         }
+        // 3. Default placeholder icon
+        return jsx(User, { className: "w-1/2 h-1/2" });
     };
     // 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.sizeStyle, avatarTheme.glyphSizes[sizeToken], className), style: { "--avatar-size": sizeValue }, "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(
+                // Ring WIDTH ramps per size (see `statusSizes`); only its colour
+                // is shared here.
+                "absolute rounded-full ring-[var(--color-background)]", avatarTheme.statusPositionStyle, avatarTheme.statusSizes[sizeToken], avatarTheme.statuses[status]), "aria-label": `Status: ${status}`, role: "status", "data-status": status })), verified && (jsx("span", { className: cn("absolute rounded-full z-10 inline-grid place-items-center ring-2 ring-[var(--color-background)] bg-white dark:bg-[var(--color-surface)] shadow-sm", avatarTheme.verifiedSizes[sizeToken]), "aria-label": "Verified", children: jsx(SealCheck, { 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[sizeToken]), 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[sizeToken]), children: resolvedTitle })), subtitle && (jsx("div", { className: cn(avatarTheme.subtitleStyle, avatarTheme.textSizes[sizeToken]), 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,16 @@
-import { AvatarSize, AvatarStatus } from "./Avatar.types";
-/**
- * Internal theme structure for the Avatar component
- */
+import { AvatarSizeToken, AvatarStatus } from "./Avatar.types";
 interface AvatarTheme {
     baseStyle: string;
-    sizes: Record<AvatarSize, string>;
+    sizeStyle: string;
+    glyphSizes: Record<AvatarSizeToken, string>;
     statuses: Record<AvatarStatus, string>;
+    statusPositionStyle: string;
+    statusSizes: Record<AvatarSizeToken, string>;
+    verifiedSizes: Record<AvatarSizeToken, string>;
+    titleStyle: string;
+    subtitleStyle: string;
+    textSizes: Record<AvatarSizeToken, string>;
+    gapSizes: Record<AvatarSizeToken, string>;
 }
-/**
- * Default theme for the Avatar component
- */
 export declare const avatarTheme: AvatarTheme;
 export {};

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

@@ -1,25 +1,91 @@
-/**
- * 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
-    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)]",
+    // `isolate` is load-bearing, not decoration: the circle's contents raise
+    // themselves above the gradient with `z-10`, and a `relative` box with
+    // `z-index: auto` does NOT create a stacking context — so that z-10 escaped
+    // into the WRAPPER's context and painted over the sibling status dot, which
+    // sits at `z-index: auto`. Isolating keeps the circle's internal layering
+    // internal, so the dot and badge stack by DOM order as intended.
+    baseStyle: "relative isolate 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",
+    // One geometry class for EVERY size. The px value arrives through the
+    // `--avatar-size` custom property, which Avatar sets inline: a token maps to
+    // its `--avatar-size-*` var, a number to `${n}px`. It has to travel as a
+    // variable rather than a generated `size-[30px]` class because per-value
+    // classes can't be interpolated — Tailwind only ships what it finds in this
+    // library's source, so an interpolated class would resolve to nothing.
+    sizeStyle: "size-[var(--avatar-size)]",
+    // The circle's own glyph (initials) — distinct from `textSizes`, which sizes
+    // the adjacent title/subtitle block.
+    glyphSizes: {
+        xs: "text-xs",
+        sm: "text-xs",
+        md: "text-sm",
+        lg: "text-sm",
+        xl: "text-sm",
     },
-    // Status indicator styles
     statuses: {
         online: "bg-[var(--color-success)]",
-        offline: "bg-neutral-400",
+        // NOT `--color-text-muted`: the text tokens are alpha derivations of
+        // `--color-text-primary` (57% opaque in light, 50% in dark), so using one
+        // as a FILL let the avatar photo show straight through the dot.
+        //
+        // A ramp rung rather than `--color-mono` (the §3 filled-neutral role) is a
+        // deliberate, measured exception — see CLAUDE.md §8. `--color-mono` is
+        // mono-900/200, tuned to carry `-contrast` TEXT; a status dot carries none,
+        // and at that weight the least-active state out-shouts the active ones.
+        // mono-500 is the only rung clearing WCAG 1.4.11's 3:1 against the dot's
+        // adjacent colour (its `--color-background` ring) in BOTH modes — 4.54
+        // light, 3.78 dark — which also puts it in the same band as its siblings
+        // (success 3.52, danger 4.57). One value, no `dark:` variant needed.
+        offline: "bg-[var(--color-mono-500)]",
         busy: "bg-[var(--color-danger)]",
         away: "bg-[var(--color-warning)]",
         none: "",
     },
+    // Placement, shared by every size. The avatar is a circle
+    // (`--avatar-radius: 50%`), so anchoring the dot to the bounding-box corner
+    // strands it outside the arc — the corner sits ~41% further from the centre
+    // than the edge does. The 45° point of a circle is `r(1 − 1/√2)` ≈ 14.6% of
+    // the diameter in from each edge; the half-translates then centre the dot on
+    // it, so it reads as attached at EVERY size, including arbitrary numeric ones
+    // (a px inset per rung can only ever be right for that rung's exact diameter).
+    statusPositionStyle: "left-[14.6%] bottom-[14.6%] -translate-x-1/2 translate-y-1/2",
+    // Dot AND ring ramp together, because what the eye reads is the badge's total
+    // footprint — and the ring used to be a flat 2px at every rung, making it
+    // proportionally 3.3× heavier on xs than on xl. Dot tracks ~20% of the
+    // diameter, ring ~5%, so the footprint stays near 30% across the ladder
+    // (was 42%→25%). xs is the one deliberate outlier at 33%: 20% of 24px is
+    // under 5px, which stops reading as a status colour at all, so the dot holds
+    // a 6px legibility floor there rather than scaling honestly.
+    statusSizes: {
+        xs: "size-1.5 ring-1",
+        sm: "size-1.5 ring-[1.5px]",
+        md: "size-2 ring-2",
+        lg: "size-2.5 ring-2",
+        xl: "size-3 ring-[3px]",
+    },
+    verifiedSizes: {
+        xs: "size-2.5 -right-0.5 -bottom-0.5",
+        sm: "size-3.5 -right-0.5 -bottom-0.5",
+        md: "size-4 -right-0.5 -bottom-0.5",
+        lg: "size-5 -right-0.5 -bottom-0.5",
+        xl: "size-5 -right-0.5 -bottom-0.5",
+    },
+    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,19 +1,31 @@
-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";
+/** The named rungs of the avatar size ladder (px values live in `theme.css`). */
+export type AvatarSizeToken = "xs" | "sm" | "md" | "lg" | "xl";
+/**
+ * A named rung, or an exact pixel size. A number sizes the circle precisely
+ * (`size={30}` → 30px) while its decorations — glyph, status dot, verified
+ * badge, text gap — snap to the nearest rung.
+ */
+export type AvatarSize = AvatarSizeToken | 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
+     * The size of the avatar — a named rung (`"md"`) or an exact pixel size
+     * (`30`). Prefer this over a `className="size-[30px]"` override: the shipped
+     * stylesheet only contains the classes used by this library's own source, so
+     * an arbitrary size utility resolves to nothing for consumers who don't run
+     * Tailwind themselves.
      * @default "md"
      */
     size?: AvatarSize;
@@ -23,9 +35,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 +99,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/Avatar/index.d.ts

@@ -1,2 +1,2 @@
 export { Avatar } from './Avatar';
-export type { AvatarProps, AvatarSize, AvatarStatus, } from './Avatar.types';
+export type { AvatarProps, AvatarSize, AvatarSizeToken, AvatarStatus, } from './Avatar.types';

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';
@@ -6,7 +7,7 @@ import { cn } from '../../../utils/cn.js';
 import { avatarGroupTheme } from './AvatarGroup.theme.js';
 import { getAnimationState, getAvatarGroupVariants } from './AvatarGroup.animations.js';
 
-const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "md", spacing = "normal", direction = "row", overflowIndicator, className, ariaLabel = "Group of users", shouldAnimate = true, ...props }, ref) => {
+const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "md", direction = "row", overflowIndicator, className, ariaLabel = "Group of users", shouldAnimate = true, ...props }, ref) => {
     const [hoveredIndex, setHoveredIndex] = useState(null);
     const shouldReduceMotion = useReducedMotion();
     const enableAnimations = shouldAnimate && !shouldReduceMotion;
@@ -14,23 +15,21 @@ const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "
     const memoizedData = useMemo(() => {
         const visibleAvatars = avatars.slice(0, max);
         const overflowCount = avatars.length > max ? avatars.length - max : 0;
-        const spacingClass = avatarGroupTheme.spacingStyles[spacing];
         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,
             overflowCount,
-            spacingClass,
             directionClass,
             totalPeople,
             groupDescription,
         };
-    }, [avatars, max, spacing, direction]);
-    const { visibleAvatars, overflowCount, spacingClass, directionClass, totalPeople, groupDescription, } = memoizedData;
-    return (jsxs("div", { ref: ref, className: cn(avatarGroupTheme.baseStyle, directionClass, className), role: "group", "aria-label": ariaLabel, "aria-description": `Contains ${totalPeople} users: ${groupDescription}`, "data-size": size, "data-spacing": spacing, "data-direction": direction, "data-total": totalPeople, "data-visible": visibleAvatars.length, "data-overflow": overflowCount > 0 ? "true" : "false", onMouseLeave: () => enableAnimations && setHoveredIndex(null), ...props, children: [visibleAvatars.map((avatarProps, index) => {
+    }, [avatars, max, direction]);
+    const { visibleAvatars, overflowCount, directionClass, totalPeople, groupDescription, } = memoizedData;
+    return (jsxs("div", { ref: ref, className: cn(avatarGroupTheme.baseStyle, directionClass, className), role: "group", "aria-label": ariaLabel, "aria-description": `Contains ${totalPeople} users: ${groupDescription}`, "data-size": size, "data-direction": direction, "data-total": totalPeople, "data-visible": visibleAvatars.length, "data-overflow": overflowCount > 0 ? "true" : "false", onMouseLeave: () => enableAnimations && setHoveredIndex(null), ...props, children: [visibleAvatars.map((avatarProps, index) => {
                 // Create contextual label for individual avatars in a group
                 const position = index + 1;
                 const contextLabel = avatarProps.contextualLabel || ` (${position} of ${totalPeople})`;
@@ -44,12 +43,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, 
+                    index > 0 ? avatarGroupTheme.spacingStyle : "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", avatarGroupTheme.spacingStyle), "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.d.ts

@@ -1,10 +1,9 @@
-import { AvatarGroupSpacing } from "./AvatarGroup.types";
 /**
  * Internal theme structure for the AvatarGroup component
  */
 interface AvatarGroupTheme {
     baseStyle: string;
-    spacingStyles: Record<AvatarGroupSpacing, string>;
+    spacingStyle: string;
     overflowAvatarStyle: string;
 }
 /**

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

@@ -3,15 +3,13 @@
  */
 const avatarGroupTheme = {
     // Base styles for the avatar group
-    baseStyle: "flex items-start",
-    // Spacing options - separated from hover effects
-    spacingStyles: {
-        tight: "-ml-5 z-10",
-        normal: "-ml-3 z-10",
-        loose: "-ml-2 z-10",
-    },
+    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).
+    // Overlap between stacked avatars — override per call site with className.
+    spacingStyle: "-ml-3 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/AvatarGroup/AvatarGroup.types.d.ts

@@ -1,6 +1,5 @@
 import { ReactNode } from 'react';
 import type { AvatarProps } from '../Avatar/Avatar.types';
-export type AvatarGroupSpacing = 'tight' | 'normal' | 'loose';
 export type AvatarGroupDirection = 'row' | 'row-reverse';
 export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
     /**
@@ -17,11 +16,6 @@ export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
      * @default "md"
      */
     size?: AvatarProps["size"];
-    /**
-     * Amount of overlap between avatars (higher value = more overlap)
-     * @default "normal"
-     */
-    spacing?: AvatarGroupSpacing;
     /**
      * Direction of the avatar stack
      * @default "row"

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

@@ -1,2 +1,2 @@
 export { AvatarGroup } from './AvatarGroup';
-export type { AvatarGroupProps, AvatarGroupSpacing, AvatarGroupDirection } from './AvatarGroup.types';
+export type { AvatarGroupProps, AvatarGroupDirection } from './AvatarGroup.types';

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

@@ -1,3 +1,6 @@
+"use client";
+import { PRESS_TRANSITION, HOVER_TRANSITION } from '../shared/interaction.animations.js';
+
 // Main badge variants with optimized transitions
 const badgeVariants = {
     initial: {
@@ -53,15 +56,15 @@ const dotVariants = {
 // Dismiss button variants - optimized for performance
 const dismissButtonVariants = {
     initial: {
-        opacity: 0.5,
+        opacity: 0.75,
     },
     hover: {
         opacity: 1,
-        transition: { duration: 0.15, ease: "easeOut" },
+        transition: HOVER_TRANSITION,
     },
     tap: {
         scale: 0.95,
-        transition: { duration: 0.1, ease: "easeOut" },
+        transition: PRESS_TRANSITION,
     },
 };
 // Optimized dismiss animation sequence

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>>;