@bearmenu/ui 0.7.1 → 0.8.2

package/dist/components/text.d.ts

@@ -3,6 +3,24 @@ import * as class_variance_authority_types from 'class-variance-authority/types'
 import * as React from 'react';
 import { VariantProps } from 'class-variance-authority';
 
+/**
+ * The type scale is a CLOSED set of roles. Seven carry every surface:
+ *
+ *   h1       page title          30/700
+ *   h3       section heading     20/600
+ *   body     running prose       16/400 relaxed
+ *   label    row / item title    14/600
+ *   body-sm  secondary fact      14/400
+ *   overline eyebrow             12/600 uppercase
+ *   caption  fine print          12/400
+ *
+ * Emphasis, colour and tabular figures are ORTHOGONAL modifiers (`weight`,
+ * `color`, className) — they must never be expressed by changing SIZE. A
+ * paragraph that steps 16 → 14 mid-sentence to mark its lead reads as two
+ * paragraphs jammed together; that is what the modifiers exist for.
+ *
+ * Weights are 400 / 600 / 700. 500 is not in the system.
+ */
 declare const textVariants: (props?: ({
     variant?: "h2" | "h3" | "label" | "body" | "caption" | "h1" | "h4" | "small" | "display" | "body-lg" | "body-sm" | "overline" | null | undefined;
     color?: "inherit" | "default" | "destructive" | "muted" | "primary" | "primary-foreground" | null | undefined;

package/dist/components/text.js

@@ -1,3 +1,3 @@
-export { Text, textVariants } from '../chunk-Y5D5LP4A.js';
+export { Text, textVariants } from '../chunk-7BWTYWM3.js';
 import '../chunk-FEK5XGZW.js';
 import '../chunk-3GWWZKX7.js';

package/dist/components/toggle-group.js

@@ -1,4 +1,4 @@
-import { toggleVariants } from '../chunk-ZBBUKXM5.js';
+import { toggleVariants } from '../chunk-X3WMRKOW.js';
 import { cn } from '../chunk-FEK5XGZW.js';
 import { __objRest, __spreadProps, __spreadValues } from '../chunk-3GWWZKX7.js';
 import * as React from 'react';

package/dist/components/toggle.js

@@ -1,3 +1,3 @@
-export { Toggle, toggleVariants } from '../chunk-ZBBUKXM5.js';
+export { Toggle, toggleVariants } from '../chunk-X3WMRKOW.js';
 import '../chunk-FEK5XGZW.js';
 import '../chunk-3GWWZKX7.js';

package/dist/lib/card-hover.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Card hover motion tokens — the shared recipe for any card with a cover image.
+ *
+ * Every card type animates the same set of properties (transform on the card
+ * root, transform on the image, box-shadow on the image wrapper) so the timings
+ * must stay in lockstep. Defining the tokens in one place is the only way to
+ * guarantee a hover that feels identical across a mixed grid.
+ *
+ * Prefer the COMPOSED tokens (`HOVER_IMAGE_WRAPPER`, `HOVER_IMAGE_MOTION`) over
+ * re-assembling a recipe from `HOVER_DURATION` + `HOVER_EASE` + a shadow at the
+ * call site. Consumers that did the latter silently shipped without a hover
+ * shadow — the transition and the resting shadow were wired up, the hover state
+ * simply never was, and nothing failed loudly. One class per element is what
+ * stops that.
+ *
+ * Companion CSS custom properties live in `./globals.css`:
+ *   --shadow-card-image / --shadow-card-image-hover / --shadow-menu-cover-inset
+ * They carry the dark-mode override, so none of these tokens needs a `dark:`
+ * twin of every state. A consumer app must NOT redefine them locally — app
+ * stylesheets are imported after this one and would silently win.
+ *
+ * Why we don't animate filter / mix-blend-mode opacity:
+ *   - filter animations (`saturate`, `brightness`) on <img> are CPU-heavy and
+ *     can hitch on lower-end devices.
+ *   - mix-blend-multiply opacity transitions composite at unpredictable frame
+ *     rates so they never sync with transform/opacity transitions.
+ * Restricting hover to transform + box-shadow keeps every element on the same
+ * GPU-composited frame, which is what makes the in/out feel perfectly synced.
+ */
+declare const HOVER_DURATION = "duration-[320ms]";
+declare const HOVER_EASE = "ease-[cubic-bezier(0.4,0,0.2,1)]";
+/** Apply to the card root — composes the base transform transition. */
+declare const HOVER_MOTION = "transition-transform duration-[320ms] ease-[cubic-bezier(0.4,0,0.2,1)] motion-reduce:transition-none will-change-transform";
+/** Apply to elements that animate box-shadow on hover (image wrappers). */
+declare const HOVER_SHADOW_MOTION = "transition-shadow duration-[320ms] ease-[cubic-bezier(0.4,0,0.2,1)]";
+/** Grid/standard/hero card variants — full lift. */
+declare const HOVER_LIFT_GRID = "[@media(hover:hover)]:hover:-translate-y-1";
+/**
+ * Same lift as `HOVER_LIFT_GRID`, but driven by a NAMED `group/card` ancestor
+ * instead of the element's own `:hover`.
+ *
+ * For overlays that must render as SIBLINGS of the interactive card rather than
+ * children — e.g. a pill that is itself a button or link, which would be
+ * invalid ARIA nested inside the card's own `role="button"` / `<a>`. A sibling
+ * can't inherit the card's transform, so it stays pinned while the card lifts
+ * out from under it. Putting `group/card` on the shared wrapper and this token
+ * on BOTH the card and the overlay moves them as one, and means hovering the
+ * overlay lifts the card too (its own `:hover` never fires for a sibling).
+ */
+declare const HOVER_LIFT_GRID_GROUP = "[@media(hover:hover)]:group-hover/card:-translate-y-1";
+/** List/compact row variants — half lift since rows are denser. */
+declare const HOVER_LIFT_LIST = "[@media(hover:hover)]:hover:-translate-y-0.5";
+/** Image inside a card — scales subtly on group hover. */
+declare const HOVER_IMAGE_SCALE = "group-hover:scale-[1.05]";
+/** Drop-in className for the `<img>` element inside card image wrappers. */
+declare const HOVER_IMAGE_MOTION = "transition-transform duration-[320ms] ease-[cubic-bezier(0.4,0,0.2,1)] motion-reduce:transition-none will-change-transform group-hover:scale-[1.05]";
+/** Warm image-wrapper shadow that deepens on group hover. */
+declare const HOVER_IMAGE_SHADOW = "shadow-[var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-card-image-hover)]";
+/**
+ * Same lift, for covers that ALSO carry an inset "well" edge on a generated
+ * illustration rather than a photo. `box-shadow` is a single property, so the
+ * inset can't be a second `shadow-*` class stacked on `HOVER_IMAGE_SHADOW`; it
+ * has to be part of the same value, which is why both states are spelled out.
+ */
+declare const HOVER_IMAGE_SHADOW_INSET = "shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image-hover)]";
+/**
+ * The whole cover-wrapper recipe: shadow transition + the warm lift. Pair with
+ * `HOVER_IMAGE_MOTION` on the image inside (covers that render a generated
+ * illustration have no image to scale and use this alone).
+ */
+declare const HOVER_IMAGE_WRAPPER = "transition-shadow duration-[320ms] ease-[cubic-bezier(0.4,0,0.2,1)] shadow-[var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-card-image-hover)]";
+/** `HOVER_IMAGE_WRAPPER` for the inset-well covers. */
+declare const HOVER_IMAGE_WRAPPER_INSET = "transition-shadow duration-[320ms] ease-[cubic-bezier(0.4,0,0.2,1)] shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image-hover)]";
+
+export { HOVER_DURATION, HOVER_EASE, HOVER_IMAGE_MOTION, HOVER_IMAGE_SCALE, HOVER_IMAGE_SHADOW, HOVER_IMAGE_SHADOW_INSET, HOVER_IMAGE_WRAPPER, HOVER_IMAGE_WRAPPER_INSET, HOVER_LIFT_GRID, HOVER_LIFT_GRID_GROUP, HOVER_LIFT_LIST, HOVER_MOTION, HOVER_SHADOW_MOTION };

package/dist/lib/card-hover.js

@@ -0,0 +1,18 @@
+import '../chunk-3GWWZKX7.js';
+
+// src/lib/card-hover.ts
+var HOVER_DURATION = "duration-[320ms]";
+var HOVER_EASE = "ease-[cubic-bezier(0.4,0,0.2,1)]";
+var HOVER_MOTION = `transition-transform ${HOVER_DURATION} ${HOVER_EASE} motion-reduce:transition-none will-change-transform`;
+var HOVER_SHADOW_MOTION = `transition-shadow ${HOVER_DURATION} ${HOVER_EASE}`;
+var HOVER_LIFT_GRID = "[@media(hover:hover)]:hover:-translate-y-1";
+var HOVER_LIFT_GRID_GROUP = "[@media(hover:hover)]:group-hover/card:-translate-y-1";
+var HOVER_LIFT_LIST = "[@media(hover:hover)]:hover:-translate-y-0.5";
+var HOVER_IMAGE_SCALE = "group-hover:scale-[1.05]";
+var HOVER_IMAGE_MOTION = `${HOVER_MOTION} ${HOVER_IMAGE_SCALE}`;
+var HOVER_IMAGE_SHADOW = "shadow-[var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-card-image-hover)]";
+var HOVER_IMAGE_SHADOW_INSET = "shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image)] [@media(hover:hover)]:group-hover:shadow-[var(--shadow-menu-cover-inset),var(--shadow-card-image-hover)]";
+var HOVER_IMAGE_WRAPPER = `${HOVER_SHADOW_MOTION} ${HOVER_IMAGE_SHADOW}`;
+var HOVER_IMAGE_WRAPPER_INSET = `${HOVER_SHADOW_MOTION} ${HOVER_IMAGE_SHADOW_INSET}`;
+
+export { HOVER_DURATION, HOVER_EASE, HOVER_IMAGE_MOTION, HOVER_IMAGE_SCALE, HOVER_IMAGE_SHADOW, HOVER_IMAGE_SHADOW_INSET, HOVER_IMAGE_WRAPPER, HOVER_IMAGE_WRAPPER_INSET, HOVER_LIFT_GRID, HOVER_LIFT_GRID_GROUP, HOVER_LIFT_LIST, HOVER_MOTION, HOVER_SHADOW_MOTION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bearmenu/ui",
-  "version": "0.7.1",
+  "version": "0.8.2",
   "description": "BearMenu design system — shared UI tokens, primitives, and components",
   "license": "UNLICENSED",
   "repository": {

package/src/components/accordion.tsx

@@ -29,7 +29,7 @@ const AccordionTrigger = React.forwardRef<
       ref={ref}
       data-slot="accordion-trigger"
       className={cn(
-        "flex flex-1 cursor-pointer items-center justify-between py-4 text-sm font-medium text-foreground transition-colors hover:text-foreground/80",
+        "flex flex-1 cursor-pointer items-center justify-between py-4 text-sm font-semibold text-foreground transition-colors hover:text-foreground/80",
         "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 rounded-sm",
         "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50",
         "[&[data-state=open]>svg]:rotate-180",

package/src/components/avatar.stories.tsx

@@ -1,5 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Avatar, AvatarFallback, AvatarImage } from "./avatar";
+import { Avatar, AvatarFallback, AvatarGroup, AvatarImage, type AvatarSize } from "./avatar";
+
+const sizes: AvatarSize[] = ["xs", "sm", "default", "lg", "xl"];
+
+const people = ["AB", "CD", "EF", "GH", "IJ", "KL", "MN"];
 
 const meta = {
   title: "Components/Avatar",
@@ -30,37 +34,66 @@ export const Fallback: Story = {
 export const Sizes: Story = {
   render: () => (
     <div className="flex items-center gap-4">
-      <Avatar className="h-8 w-8">
-        <AvatarFallback className="text-xs">S</AvatarFallback>
-      </Avatar>
-      <Avatar>
-        <AvatarFallback>MD</AvatarFallback>
-      </Avatar>
-      <Avatar className="h-14 w-14">
-        <AvatarFallback className="text-lg">LG</AvatarFallback>
-      </Avatar>
-      <Avatar className="h-20 w-20">
-        <AvatarFallback className="text-xl">XL</AvatarFallback>
-      </Avatar>
+      {sizes.map((size) => (
+        <Avatar key={size} size={size}>
+          <AvatarFallback>{size.slice(0, 2).toUpperCase()}</AvatarFallback>
+        </Avatar>
+      ))}
     </div>
   ),
 };
 
 export const Group: Story = {
   render: () => (
-    <div className="flex -space-x-3">
-      <Avatar className="border-2 border-background">
-        <AvatarFallback>A</AvatarFallback>
-      </Avatar>
-      <Avatar className="border-2 border-background">
-        <AvatarFallback>B</AvatarFallback>
-      </Avatar>
-      <Avatar className="border-2 border-background">
-        <AvatarFallback>C</AvatarFallback>
-      </Avatar>
-      <Avatar className="border-2 border-background">
-        <AvatarFallback className="text-xs">+3</AvatarFallback>
-      </Avatar>
+    <AvatarGroup max={4} spacing="tight">
+      {people.map((initials) => (
+        <Avatar key={initials}>
+          <AvatarFallback>{initials}</AvatarFallback>
+        </Avatar>
+      ))}
+    </AvatarGroup>
+  ),
+};
+
+/**
+ * `AvatarGroup` takes the same `size` union as `Avatar`. It sizes the "+N"
+ * overflow chip and is inherited by child avatars, so the row stays one
+ * consistent height without per-call-site class overrides.
+ */
+export const GroupSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      {sizes.map((size) => (
+        <div key={size} className="flex items-center gap-4">
+          <span className="w-16 text-xs text-muted-foreground">{size}</span>
+          <AvatarGroup max={3} spacing="tight" size={size}>
+            {people.map((initials) => (
+              <Avatar key={initials}>
+                <AvatarFallback>{initials}</AvatarFallback>
+              </Avatar>
+            ))}
+          </AvatarGroup>
+        </div>
+      ))}
     </div>
   ),
 };
+
+/**
+ * An individual `Avatar` can still opt out of the group size — useful for
+ * highlighting "you" inside a roster.
+ */
+export const GroupSizeOverride: Story = {
+  render: () => (
+    <AvatarGroup max={4} spacing="tight" size="sm">
+      <Avatar size="lg">
+        <AvatarFallback>ME</AvatarFallback>
+      </Avatar>
+      {people.map((initials) => (
+        <Avatar key={initials}>
+          <AvatarFallback>{initials}</AvatarFallback>
+        </Avatar>
+      ))}
+    </AvatarGroup>
+  ),
+};

package/src/components/avatar.test.tsx

@@ -0,0 +1,129 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Avatar, AvatarBadge, AvatarFallback, AvatarGroup } from "./avatar";
+
+// Returned as an array, not a fragment: AvatarGroup counts its direct children,
+// and a fragment would collapse the whole set into one child.
+const members = (count: number) =>
+  Array.from({ length: count }, (_, i) => (
+    <Avatar key={i}>
+      <AvatarFallback>{String.fromCharCode(65 + i)}</AvatarFallback>
+    </Avatar>
+  ));
+
+const overflowChip = () => document.querySelector('[data-slot="avatar-group-overflow"]');
+const avatars = () => Array.from(document.querySelectorAll('[data-slot="avatar"]'));
+
+describe("Avatar", () => {
+  it("applies the default size scale when no size is given", () => {
+    render(
+      <Avatar>
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>
+    );
+    expect(avatars()[0]).toHaveClass("size-10", "text-sm");
+  });
+
+  it("applies an explicit size variant", () => {
+    render(
+      <Avatar size="xs">
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>
+    );
+    expect(avatars()[0]).toHaveClass("size-6", "text-[10px]");
+  });
+
+  it("scales AvatarBadge off the avatar size via context", () => {
+    render(
+      <Avatar size="xl">
+        <AvatarFallback>JD</AvatarFallback>
+        <AvatarBadge />
+      </Avatar>
+    );
+    expect(document.querySelector('[data-slot="avatar-badge"]')).toHaveClass("size-4");
+  });
+});
+
+describe("AvatarGroup", () => {
+  it("renders no overflow chip when the item count fits within max", () => {
+    render(
+      <AvatarGroup max={3}>
+        {members(3)}
+      </AvatarGroup>
+    );
+    expect(overflowChip()).toBeNull();
+  });
+
+  it("renders a +N overflow chip for the hidden remainder", () => {
+    render(
+      <AvatarGroup max={2}>
+        {members(5)}
+      </AvatarGroup>
+    );
+    expect(screen.getByText("+3")).toBeInTheDocument();
+    expect(avatars()).toHaveLength(2);
+  });
+
+  it("keeps the pre-existing chip appearance when no size is passed", () => {
+    render(
+      <AvatarGroup max={1}>
+        {members(3)}
+      </AvatarGroup>
+    );
+    expect(overflowChip()).toHaveClass("size-10", "text-xs");
+  });
+
+  it.each([
+    ["xs", "size-6", "text-[9px]"],
+    ["sm", "size-8", "text-[10px]"],
+    ["default", "size-10", "text-xs"],
+    ["lg", "size-12", "text-sm"],
+    ["xl", "size-16", "text-base"],
+  ] as const)("sizes the overflow chip to match a %s group", (size, sizeClass, textClass) => {
+    render(
+      <AvatarGroup max={1} size={size}>
+        {members(4)}
+      </AvatarGroup>
+    );
+    expect(overflowChip()).toHaveClass(sizeClass, textClass);
+  });
+
+  it("passes the group size down to child avatars", () => {
+    render(
+      <AvatarGroup max={2} size="sm">
+        {members(4)}
+      </AvatarGroup>
+    );
+    for (const avatar of avatars()) {
+      expect(avatar).toHaveClass("size-8");
+    }
+  });
+
+  it("lets an individual avatar override the group size", () => {
+    render(
+      <AvatarGroup size="sm">
+        <Avatar>
+          <AvatarFallback>A</AvatarFallback>
+        </Avatar>
+        <Avatar size="lg">
+          <AvatarFallback>B</AvatarFallback>
+        </Avatar>
+      </AvatarGroup>
+    );
+    const [inherited, overridden] = avatars();
+    expect(inherited).toHaveClass("size-8");
+    expect(overridden).toHaveClass("size-12");
+  });
+
+  it("scales avatar and chip together so the group reads as one row", () => {
+    render(
+      <AvatarGroup max={2} size="xs">
+        {members(9)}
+      </AvatarGroup>
+    );
+    for (const avatar of avatars()) {
+      expect(avatar).toHaveClass("size-6");
+    }
+    expect(overflowChip()).toHaveClass("size-6");
+  });
+});

package/src/components/avatar.tsx

@@ -23,22 +23,32 @@ const avatarVariants = cva(
   }
 );
 
-const AvatarContext = React.createContext<VariantProps<typeof avatarVariants>["size"]>("default");
+type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>;
+
+const AvatarContext = React.createContext<AvatarSize>("default");
 
 const Avatar = React.forwardRef<
   React.ElementRef<typeof AvatarPrimitive.Root>,
   React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root> &
     VariantProps<typeof avatarVariants>
->(({ className, size = "default", ...props }, ref) => (
-  <AvatarContext.Provider value={size}>
-    <AvatarPrimitive.Root
-      ref={ref}
-      data-slot="avatar"
-      className={cn(avatarVariants({ size }), className)}
-      {...props}
-    />
-  </AvatarContext.Provider>
-));
+>(({ className, size, ...props }, ref) => {
+  // An explicit `size` always wins; otherwise inherit from the nearest
+  // AvatarGroup (context defaults to "default", so a standalone Avatar with no
+  // size behaves exactly as before).
+  const inheritedSize = React.useContext(AvatarContext);
+  const resolvedSize = size ?? inheritedSize;
+
+  return (
+    <AvatarContext.Provider value={resolvedSize}>
+      <AvatarPrimitive.Root
+        ref={ref}
+        data-slot="avatar"
+        className={cn(avatarVariants({ size: resolvedSize }), className)}
+        {...props}
+      />
+    </AvatarContext.Provider>
+  );
+});
 Avatar.displayName = AvatarPrimitive.Root.displayName;
 
 const AvatarImage = React.forwardRef<
@@ -62,7 +72,7 @@ const AvatarFallback = React.forwardRef<
     ref={ref}
     data-slot="avatar-fallback"
     className={cn(
-      "flex size-full items-center justify-center rounded-full bg-muted font-medium text-muted-foreground",
+      "flex size-full items-center justify-center rounded-full bg-muted font-semibold text-muted-foreground",
       className
     )}
     {...props}
@@ -85,14 +95,14 @@ const AvatarBadge = React.forwardRef<
     tone?: "success" | "warning" | "destructive" | "muted";
   }
 >(({ className, placement = "bottom-right", tone = "success", ...props }, ref) => {
-  const size = React.useContext(AvatarContext) ?? "default";
+  const size = React.useContext(AvatarContext);
   return (
     <span
       ref={ref}
       data-slot="avatar-badge"
       className={cn(
         "absolute block rounded-full ring-background",
-        badgeOffset[size as keyof typeof badgeOffset],
+        badgeOffset[size],
         placement === "top-right" ? "right-0 top-0" : "bottom-0 right-0",
         tone === "success" && "bg-success",
         tone === "warning" && "bg-warning",
@@ -106,37 +116,83 @@ const AvatarBadge = React.forwardRef<
 });
 AvatarBadge.displayName = "AvatarBadge";
 
+// The "+N" chip tracks the group's avatar size. Its label sits one step below
+// the matching Avatar text rung — a two-glyph "+12" needs more room inside the
+// same circle than a one-glyph initial. `default` reproduces the pre-0.8
+// hardcoded appearance (size-10 text-xs) exactly.
+const avatarGroupOverflowVariants = cva(
+  "relative inline-flex shrink-0 items-center justify-center rounded-full bg-muted font-semibold text-muted-foreground ring-2 ring-background",
+  {
+    variants: {
+      size: {
+        xs: "size-6 text-[9px]",
+        sm: "size-8 text-[10px]",
+        default: "size-10 text-xs",
+        lg: "size-12 text-sm",
+        xl: "size-16 text-base",
+      },
+    },
+    defaultVariants: {
+      size: "default",
+    },
+  }
+);
+
 const AvatarGroup = React.forwardRef<
   HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement> & { max?: number; spacing?: "tight" | "default" | "loose" }
->(({ className, children, max, spacing = "default", ...props }, ref) => {
+  React.HTMLAttributes<HTMLDivElement> & {
+    max?: number;
+    spacing?: "tight" | "default" | "loose";
+    /**
+     * Size for the whole group: sets the "+N" overflow chip and is inherited by
+     * child `Avatar`s that don't set their own `size`. Defaults to "default".
+     */
+    size?: AvatarSize;
+  }
+>(({ className, children, max, spacing = "default", size, ...props }, ref) => {
+  const inheritedSize = React.useContext(AvatarContext);
+  const resolvedSize = size ?? inheritedSize;
   const items = React.Children.toArray(children);
   const visible = max ? items.slice(0, max) : items;
   const overflow = max ? items.length - max : 0;
 
   return (
-    <div
-      ref={ref}
-      data-slot="avatar-group"
-      className={cn(
-        "flex items-center",
-        spacing === "tight" && "-space-x-3",
-        spacing === "default" && "-space-x-2",
-        spacing === "loose" && "-space-x-1",
-        "[&>*]:ring-2 [&>*]:ring-background",
-        className
-      )}
-      {...props}
-    >
-      {visible}
-      {overflow > 0 && (
-        <span className="relative inline-flex size-10 items-center justify-center rounded-full bg-muted text-xs font-medium text-muted-foreground ring-2 ring-background">
-          +{overflow}
-        </span>
-      )}
-    </div>
+    <AvatarContext.Provider value={resolvedSize}>
+      <div
+        ref={ref}
+        data-slot="avatar-group"
+        className={cn(
+          "flex items-center",
+          spacing === "tight" && "-space-x-3",
+          spacing === "default" && "-space-x-2",
+          spacing === "loose" && "-space-x-1",
+          "[&>*]:ring-2 [&>*]:ring-background",
+          className
+        )}
+        {...props}
+      >
+        {visible}
+        {overflow > 0 && (
+          <span
+            data-slot="avatar-group-overflow"
+            className={avatarGroupOverflowVariants({ size: resolvedSize })}
+          >
+            +{overflow}
+          </span>
+        )}
+      </div>
+    </AvatarContext.Provider>
   );
 });
 AvatarGroup.displayName = "AvatarGroup";
 
-export { Avatar, AvatarImage, AvatarFallback, AvatarBadge, AvatarGroup, avatarVariants };
+export {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  avatarVariants,
+  avatarGroupOverflowVariants,
+};
+export type { AvatarSize };

package/src/components/badge.tsx

@@ -37,10 +37,22 @@ const badgeVariants = cva(
 );
 
 export interface BadgeProps
-  extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {}
+  extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
+  /**
+   * Element to render. Defaults to `div`.
+   *
+   * Use `"span"` when the badge sits inside a `<button>` or a `<p>` — their
+   * content model is phrasing content, so a `div` in there is invalid HTML.
+   * That is the common case for a badge sitting inline with a title on a
+   * clickable row.
+   */
+  as?: "div" | "span";
+}
 
-function Badge({ className, variant, live, ...props }: BadgeProps) {
-  return <div data-slot="badge" className={cn(badgeVariants({ variant, live }), className)} {...props} />;
+function Badge({ className, variant, live, as: Tag = "div", ...props }: BadgeProps) {
+  return (
+    <Tag data-slot="badge" className={cn(badgeVariants({ variant, live }), className)} {...props} />
+  );
 }
 
 export { Badge, badgeVariants };

package/src/components/breadcrumb.tsx

@@ -59,7 +59,7 @@ function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
       role="link"
       aria-disabled="true"
       aria-current="page"
-      className={cn("font-medium text-foreground", className)}
+      className={cn("font-semibold text-foreground", className)}
       {...props}
     />
   );

package/src/components/button.tsx

@@ -6,7 +6,7 @@ import { cn } from "../lib/utils";
 import { useHaptic } from "../hooks/use-haptic";
 
 const buttonVariants = cva(
-  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 cursor-pointer [@media(pointer:coarse)]:active:scale-95",
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-xl text-sm font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0 cursor-pointer [@media(pointer:coarse)]:active:scale-95",
   {
     variants: {
       variant: {
@@ -21,6 +21,21 @@ const buttonVariants = cva(
         ghost: "hover:bg-accent hover:text-accent-foreground",
         link: "text-primary underline-offset-4 hover:underline",
         glass: "glass glass-hover text-foreground",
+        /**
+         * Chrome sitting ON a photo — share, close, favourite over a hero or
+         * card image. `glass` is the wrong tool there: it resolves
+         * `text-foreground`, which is near-black in light mode and disappears
+         * into a dark photo.
+         *
+         * Deliberately NOT theme-aware, and so deliberately different from
+         * `Badge`'s `overlay` (`bg-foreground/70 text-background`, which
+         * inverts). A photo is equally a photo in both themes — this chrome has
+         * to contrast with the image beneath it, not with the app canvas, so it
+         * stays dark-on-light-glyph either way. Reconcile Badge to this, not the
+         * reverse, if the two are ever unified.
+         */
+        overlay:
+          "bg-black/40 text-white backdrop-blur-sm hover:bg-black/60 focus-visible:ring-white/70",
         brown:
           "bg-brown text-brown-foreground shadow-sm hover:bg-brown/85 hover:shadow",
         antagonist:

package/src/components/calendar.tsx

@@ -58,7 +58,7 @@ function Calendar({
           defaultClassNames.month_caption
         ),
         dropdowns: cn(
-          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium",
+          "flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-semibold",
           defaultClassNames.dropdowns
         ),
         dropdown_root: cn(
@@ -67,7 +67,7 @@ function Calendar({
         ),
         dropdown: cn("absolute inset-0 bg-popover opacity-0", defaultClassNames.dropdown),
         caption_label: cn(
-          "font-medium select-none",
+          "font-semibold select-none",
           captionLayout === "label"
             ? "text-sm"
             : "flex h-8 items-center gap-1 rounded-md pr-1 pl-2 text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground",