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

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

@@ -4,9 +4,9 @@ const accordionTheme = {
     // Base container styles for stacked variant (unified card)
     baseStyleStacked: "w-full border border-[var(--color-border)] rounded-[var(--form-radius)] overflow-hidden",
     // Item styles for separated variant (individual cards with spacing)
-    itemStyle: "border border-[var(--color-border)] rounded-[var(--form-radius)] bg-white dark:bg-[var(--color-background-secondary)] overflow-hidden mb-2 last-of-type:mb-0",
+    itemStyle: "border border-[var(--color-border)] rounded-[var(--form-radius)] bg-[var(--color-surface)] overflow-hidden mb-2 last-of-type:mb-0",
     // Item styles for stacked variant (shared borders, no spacing)
-    itemStyleStacked: "bg-white border-t border-[var(--color-border)] first-of-type:border-t-0",
+    itemStyleStacked: "bg-[var(--color-surface)] border-t border-[var(--color-border)] first-of-type:border-t-0",
     // Trigger styles (shared across variants)
     triggerStyle: "flex w-full gap-3 items-center px-4 py-2.5 text-left font-medium transition-all duration-200 cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 text-[var(--color-text-primary)] text-sm",
     // Body styles (shared across variants)

package/dist/components/core/Accordion/AccordionTrigger.js

@@ -5,7 +5,7 @@ import { cn } from '../../../utils/cn.js';
 import { useAccordionContext } from './AccordionContext.js';
 import { useAccordionItemContext } from './AccordionItem.js';
 import { motion } from 'motion/react';
-import { PlusIcon } from '@heroicons/react/24/outline';
+import { Plus } from '@phosphor-icons/react';
 import { createTriggerIconVariants } from './Accordion.animations.js';
 
 const AccordionTrigger = React__default.forwardRef(({ children, className, chevron, chevronRotation, iconRotation, chevronPosition = "right", ...props }, ref) => {
@@ -14,7 +14,7 @@ const AccordionTrigger = React__default.forwardRef(({ children, className, chevr
     const { isOpen, disabled, toggle, triggerId, contentId } = useAccordionItemContext();
     const resolvedChevronRotation = (_a = chevronRotation !== null && chevronRotation !== void 0 ? chevronRotation : iconRotation) !== null && _a !== void 0 ? _a : 45;
     // Resolve the indicator icon
-    const defaultChevronIcon = jsx(PlusIcon, { className: "size-4", strokeWidth: 2 });
+    const defaultChevronIcon = jsx(Plus, { className: "size-4", weight: "bold" });
     const resolvedChevron = chevron === null
         ? null
         : chevron !== undefined

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

@@ -1,8 +1,9 @@
 import { Variants } from "motion/react";
 /**
  * Alert entrance/exit animation variants
- * Entrance: slide down from -8px + fade in
+ * Entrance: slide down from -12px + fade in
  * Exit: fade out + collapse height
+ * Uses library spring presets for a premium feel
  */
 export declare const alertVariants: Variants;
 /**

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

@@ -1,13 +1,18 @@
 "use client";
+import '../../../theme/ThemeContext.js';
+import '../../../theme/SurfaceContext.js';
+import { springs } from '../../../theme/animations.js';
+
 /**
  * Alert entrance/exit animation variants
- * Entrance: slide down from -8px + fade in
+ * Entrance: slide down from -12px + fade in
  * Exit: fade out + collapse height
+ * Uses library spring presets for a premium feel
  */
 const alertVariants = {
     hidden: {
         opacity: 0,
-        y: -8,
+        y: -12,
         height: 0,
         paddingTop: 0,
         paddingBottom: 0,
@@ -15,8 +20,13 @@ const alertVariants = {
         marginBottom: 0,
         overflow: "hidden",
         transition: {
-            duration: 0.15,
-            ease: [0.4, 0, 1, 1],
+            height: springs.smooth,
+            paddingTop: springs.smooth,
+            paddingBottom: springs.smooth,
+            marginTop: springs.smooth,
+            marginBottom: springs.smooth,
+            y: springs.premium,
+            opacity: { duration: 0.15 },
         },
     },
     visible: {
@@ -29,8 +39,13 @@ const alertVariants = {
         marginBottom: undefined,
         overflow: "visible",
         transition: {
-            duration: 0.2,
-            ease: [0.4, 0, 0.2, 1],
+            y: springs.premium,
+            height: springs.smooth,
+            paddingTop: springs.smooth,
+            paddingBottom: springs.smooth,
+            marginTop: springs.smooth,
+            marginBottom: springs.smooth,
+            opacity: { duration: 0.25 },
         },
     },
 };

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

@@ -5,15 +5,15 @@ 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 { X, XCircle, Warning, CheckCircle, Info, Bell } from '@phosphor-icons/react';
 import { Button } from '../Button/Button.js';
 
 const defaultIcons = {
-    neutral: BellIcon,
-    primary: InformationCircleIcon,
-    success: CheckCircleIcon,
-    warning: ExclamationTriangleIcon,
-    danger: XCircleIcon,
+    mono: Bell,
+    primary: Info,
+    success: CheckCircle,
+    warning: Warning,
+    danger: XCircle,
 };
 const Alert = React__default.forwardRef(({ color = "primary", title, subtitle, dismissible, icon, showIcon = true, avatar, actions, onDismiss, className, children, darkMode = false, ...props }, ref) => {
     var _a;
@@ -46,7 +46,7 @@ const Alert = React__default.forwardRef(({ color = "primary", title, subtitle, d
                         ? 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 }) }))] }));
+                        : 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: "mono", size: "sm", iconOnly: true, onClick: handleDismiss, "aria-label": "Dismiss alert", className: "rounded-full absolute top-2 right-2 flex-shrink-0", children: jsx(X, { className: "size-4", weight: "bold" }) }))] }));
     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();

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

@@ -7,25 +7,64 @@ 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';
+import { SealCheck, User } from '@phosphor-icons/react';
 
 // 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 (xs shows a single initial).
+    // Initials derived from the name (the xs rung shows a single initial).
     const initials = resolvedName
         ? resolvedName
             .split(" ")
             .map((part) => part[0])
-            .slice(0, size === "xs" ? 1 : initialsCount)
+            .slice(0, sizeToken === "xs" ? 1 : initialsCount)
             .join("")
             .toUpperCase()
         : "";
@@ -40,8 +79,8 @@ const Avatar = React__default.forwardRef(({ src, name, size = "md", status = "no
     // 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)]"
+            ? "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).
@@ -88,41 +127,7 @@ const Avatar = React__default.forwardRef(({ src, name, size = "md", status = "no
             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 = () => {
-        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";
-        }
-    };
-    // 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";
-        }
+        return jsx(User, { className: "w-1/2 h-1/2" });
     };
     // Create full accessibility label including context if provided
     const accessibilityLabel = contextualLabel
@@ -133,7 +138,10 @@ const Avatar = React__default.forwardRef(({ src, name, size = "md", status = "no
     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)]" }) }))] }));
+    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
@@ -145,7 +153,7 @@ const Avatar = React__default.forwardRef(({ src, name, size = "md", status = "no
             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 }));
     }
     // 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 }))] })] }));
+    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,12 +1,16 @@
-import { AvatarSize, AvatarStatus } from "./Avatar.types";
+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<AvatarSize, string>;
-    gapSizes: Record<AvatarSize, string>;
+    textSizes: Record<AvatarSizeToken, string>;
+    gapSizes: Record<AvatarSizeToken, string>;
 }
 export declare const avatarTheme: AvatarTheme;
 export {};

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

@@ -1,19 +1,75 @@
 const avatarTheme = {
-    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-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",
+    // `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",
     },
     statuses: {
         online: "bg-[var(--color-success)]",
-        offline: "bg-[var(--color-text-muted)]",
+        // 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: {

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

@@ -1,6 +1,13 @@
 import { ReactNode } from "react";
 import type { MeshPaletteName } from "../../effects/MeshGradient";
-export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | number;
+/** 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> {
     /**
@@ -14,7 +21,11 @@ export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     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;

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.js

@@ -7,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;
@@ -15,7 +15,6 @@ 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
@@ -24,14 +23,13 @@ const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "
         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})`;
@@ -50,10 +48,10 @@ const AvatarGroup = React__default.forwardRef(({ avatars = [], max = 5, size = "
                     // 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("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` })) }))] }));
+            }), 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

@@ -6,12 +6,8 @@ const avatarGroupTheme = {
     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",
-        normal: "-ml-3 z-10",
-        loose: "-ml-2 z-10",
-    },
+    // Overlap between stacked avatars — override per call site with className.
+    spacingStyle: "-ml-3 z-10",
     // Overflow avatar styles
     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",
 };

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,4 +1,6 @@
 "use client";
+import { PRESS_TRANSITION, HOVER_TRANSITION } from '../shared/interaction.animations.js';
+
 // Main badge variants with optimized transitions
 const badgeVariants = {
     initial: {
@@ -58,11 +60,11 @@ const dismissButtonVariants = {
     },
     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.js

@@ -2,7 +2,7 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
 import React__default, { useState, useCallback } from 'react';
 import { useReducedMotion, AnimatePresence, motion } from 'motion/react';
-import { XMarkIcon } from '@heroicons/react/24/outline';
+import { X } from '@phosphor-icons/react';
 import { cn } from '../../../utils/cn.js';
 import { Avatar } from '../Avatar/Avatar.js';
 import { animationTiming, dismissVariants, badgeVariants, dismissButtonVariants, dotVariants } from './Badge.animations.js';
@@ -131,7 +131,12 @@ const Badge = React__default.memo(React__default.forwardRef(({ children, variant
             return (jsx("span", { className: cn("inline-flex items-center justify-center shrink-0 overflow-hidden [&_div]:!size-full", (_a = theme.avatarSizes) === null || _a === void 0 ? void 0 : _a[size], pill ? "rounded-full -ml-2" : "rounded-full -ml-0"), children: jsx(Avatar, { src: avatar.src, name: avatar.name, gradient: avatar.gradient, gradientVariant: avatar.gradientVariant, gradientColors: avatar.gradientColors, fallback: avatar.fallback, initialsCount: avatar.initialsCount, size: "xs", className: cn("!size-full border-0", pill ? "rounded-full" : "rounded-md ring-0") }) }));
         }
         if (iconStart) {
-            return (jsx("span", { className: cn("inline-flex items-center justify-center flex-shrink-0 -ml-1", (_b = theme.iconSizes) === null || _b === void 0 ? void 0 : _b[size]), "aria-hidden": "true", children: iconStart }));
+            return (jsx("span", { className: cn("inline-flex items-center justify-center flex-shrink-0", 
+                // Optical tuck into the cap curve — pill only (it has the extra
+                // pillSizes padding to absorb it). On a regular badge the base
+                // px-1 padding is 4px, so -ml-1 left the icon ~1px from the
+                // border. Mirrors the avatar path's pill/non-pill conditional.
+                pill ? "-ml-1" : "-ml-0", (_b = theme.iconSizes) === null || _b === void 0 ? void 0 : _b[size]), "aria-hidden": "true", children: iconStart }));
         }
         if (withDot) {
             if (shouldAnimate) {
@@ -151,7 +156,7 @@ const Badge = React__default.memo(React__default.forwardRef(({ children, variant
                                 ? `${maxWidth}px`
                                 : maxWidth,
                         }
-                        : undefined, children: children }), dismissible && (jsx("button", { type: "button", onClick: handleDismiss, className: "badge-dismiss-btn -mr-0.5 rounded-full p-0.5 cursor-pointer", "aria-label": "Dismiss", disabled: disabled, children: jsx(XMarkIcon, { className: cn("badge-dismiss-icon", (_p = theme.dismissSizes) === null || _p === void 0 ? void 0 : _p[size]), "aria-hidden": "true" }) }))] })) : null;
+                        : undefined, children: children }), dismissible && (jsx("button", { type: "button", onClick: handleDismiss, className: "badge-dismiss-btn -mr-0.5 rounded-full p-0.5 cursor-pointer", "aria-label": "Dismiss", disabled: disabled, children: jsx(X, { className: cn("badge-dismiss-icon", (_p = theme.dismissSizes) === null || _p === void 0 ? void 0 : _p[size]), "aria-hidden": "true" }) }))] })) : null;
     }
     return (jsx(AnimatePresence, { mode: "wait", children: isVisible && (jsxs(motion.span, { ref: ref, className: baseStyles, onClick: handleClick, "aria-disabled": disabled || undefined, variants: dismissible ? dismissVariants : badgeVariants, initial: "initial", animate: "animate", exit: "exit", ...dataAttributes, ...props, children: [renderLeftContent(), jsx("span", { className: cn("badge-content", maxWidth && "truncate"), style: maxWidth
                         ? {
@@ -159,7 +164,7 @@ const Badge = React__default.memo(React__default.forwardRef(({ children, variant
                                 ? `${maxWidth}px`
                                 : maxWidth,
                         }
-                        : undefined, children: children }), dismissible && (jsx(motion.button, { type: "button", onClick: handleDismiss, className: "badge-dismiss-btn -mr-0.5 rounded-full p-0.5 cursor-pointer", "aria-label": "Dismiss", disabled: disabled, variants: dismissButtonVariants, initial: "initial", whileHover: "hover", whileTap: "tap", children: jsx(XMarkIcon, { className: cn("badge-dismiss-icon", (_q = theme.dismissSizes) === null || _q === void 0 ? void 0 : _q[size]), "aria-hidden": "true", strokeWidth: 2 }) }))] })) }));
+                        : undefined, children: children }), dismissible && (jsx(motion.button, { type: "button", onClick: handleDismiss, className: "badge-dismiss-btn -mr-0.5 rounded-full p-0.5 cursor-pointer", "aria-label": "Dismiss", disabled: disabled, variants: dismissButtonVariants, initial: "initial", whileHover: "hover", whileTap: "tap", children: jsx(X, { className: cn("badge-dismiss-icon", (_q = theme.dismissSizes) === null || _q === void 0 ? void 0 : _q[size]), "aria-hidden": "true", weight: "bold" }) }))] })) }));
 }));
 Badge.displayName = "Badge";