@bearmenu/ui 0.7.1 → 0.8.1

package/src/components/place-details-mobile.tsx

@@ -83,7 +83,7 @@ export function PlaceDetailsMobile({
         <div className="rounded-[22px] overflow-hidden relative">
           <div className="h-44 flex items-center justify-center relative overflow-hidden">
             {/* Status badge — bottom right */}
-            <div className="absolute bottom-2 right-2 z-20 flex items-center gap-1.5 bg-surface border border-border px-2.5 h-7 rounded-[12px] text-[11px] font-medium text-foreground">
+            <div className="absolute bottom-2 right-2 z-20 flex items-center gap-1.5 bg-surface border border-border px-2.5 h-7 rounded-[12px] text-[11px] font-semibold text-foreground">
               <span
                 className={cn(
                   "w-1.5 h-1.5 rounded-full flex-shrink-0",
@@ -235,7 +235,7 @@ function MobileTabPlaceholder({
   return (
     <div
       className={cn(
-        "flex flex-1 min-w-0 items-center justify-center gap-1 px-1 py-2.5 text-[12px] font-medium border-b-2 -mb-px",
+        "flex flex-1 min-w-0 items-center justify-center gap-1 px-1 py-2.5 text-[12px] font-semibold border-b-2 -mb-px",
         active
           ? "border-primary text-foreground"
           : "border-transparent text-muted-foreground"

package/src/components/popover.tsx

@@ -12,15 +12,23 @@ const PopoverClose = PopoverPrimitive.Close;
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
->(({ className, align = "center", sideOffset = 4, ...props }, ref) => (
+>(({ className, align = "center", sideOffset = 4, collisionPadding = 12, ...props }, ref) => (
   <PopoverPrimitive.Portal>
     <PopoverPrimitive.Content
       ref={ref}
       data-slot="popover-content"
       align={align}
       sideOffset={sideOffset}
+      // Radix flips the side to avoid a collision, but a popover TALLER than the
+      // space on either side still overflows — and it overflows upward, off the
+      // top of the viewport, where the content cannot be scrolled back into
+      // view. `collisionPadding` keeps it off the edges; capping to Radix's
+      // measured available height and scrolling makes tall content fit rather
+      // than escape.
+      collisionPadding={collisionPadding}
       className={cn(
         "z-50 w-72 rounded-xl border border-border bg-popover p-4 text-popover-foreground shadow-xl outline-none",
+        "max-h-[var(--radix-popover-content-available-height)] overflow-y-auto overscroll-contain",
         "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className
       )}

package/src/components/select.tsx

@@ -11,7 +11,7 @@ const SelectGroup = SelectPrimitive.Group;
 const SelectValue = SelectPrimitive.Value;
 
 const selectTriggerVariants = cva(
-  "flex w-full items-center justify-between rounded-xl bg-background border border-border text-sm font-medium text-foreground transition-colors focus:outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[placeholder]:text-muted-foreground [&>span]:line-clamp-1 hover:border-foreground/30 aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive/40",
+  "flex w-full items-center justify-between rounded-xl bg-background border border-border text-sm font-semibold text-foreground transition-colors focus:outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 data-[placeholder]:text-muted-foreground [&>span]:line-clamp-1 hover:border-foreground/30 aria-invalid:border-destructive aria-invalid:focus-visible:ring-destructive/40",
   {
     variants: {
       size: {
@@ -126,7 +126,7 @@ const SelectItem = React.forwardRef<
     ref={ref}
     data-slot="select-item"
     className={cn(
-      "relative flex w-full cursor-default select-none items-center rounded-md py-2 pl-8 pr-2 text-sm outline-none transition-colors data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[state=checked]:font-medium",
+      "relative flex w-full cursor-default select-none items-center rounded-md py-2 pl-8 pr-2 text-sm outline-none transition-colors data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[state=checked]:font-semibold",
       className
     )}
     {...props}

package/src/components/selection-bar.tsx

@@ -40,7 +40,7 @@ const SelectionBar = React.forwardRef<HTMLDivElement, SelectionBarProps>(
         )}
         {...props}
       >
-        <div className="flex items-center gap-2 text-sm font-medium text-foreground">
+        <div className="flex items-center gap-2 text-sm font-semibold text-foreground">
           {onClear && (
             <button
               type="button"

package/src/components/sheet.tsx

@@ -29,21 +29,66 @@ const SheetOverlay = React.forwardRef<
 ));
 SheetOverlay.displayName = SheetPrimitive.Overlay.displayName;
 
+/**
+ * `attachment` controls whether the panel is welded to the viewport edge or
+ * floats clear of it.
+ *
+ * - `edge` (default) — the classic sheet: full bleed against its side, only the
+ *   two corners facing inward rounded. Every existing consumer gets this, so
+ *   adding `inset` changes nothing already shipped.
+ * - `inset` — a floating panel: held off all four edges, rounded on every
+ *   corner, page visible around it. Reads as a surface laid ON the page rather
+ *   than one grafted to it, which is what detail surfaces want — the content
+ *   behind stays legible as context instead of being cropped away.
+ *
+ * `inset` deliberately drops the border. At an edge the border is the seam
+ * between panel and viewport and has work to do; floating, the shadow already
+ * separates the two and a border only draws a hard line around the radius.
+ */
 const sheetVariants = cva(
-  "fixed z-[1000] gap-4 bg-background border-border p-6 shadow-2xl data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=open]:duration-[var(--duration-deliberate)] data-[state=closed]:duration-[var(--duration-exit-standard)] data-[state=open]:ease-[var(--ease-enter)] data-[state=closed]:ease-[var(--ease-exit)]",
+  "fixed z-[1000] gap-4 bg-background border-border shadow-2xl data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=open]:duration-[var(--duration-deliberate)] data-[state=closed]:duration-[var(--duration-exit-standard)] data-[state=open]:ease-[var(--ease-enter)] data-[state=closed]:ease-[var(--ease-exit)]",
   {
     variants: {
       side: {
-        top: "inset-x-0 top-0 border-b data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
+        top: "inset-x-0 top-0 data-[state=closed]:slide-out-to-top data-[state=open]:slide-in-from-top",
         bottom:
-          "inset-x-0 bottom-0 border-t data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom rounded-t-2xl",
-        left: "inset-y-0 left-0 h-full w-3/4 border-r data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left sm:max-w-sm rounded-r-2xl",
+          "inset-x-0 bottom-0 data-[state=closed]:slide-out-to-bottom data-[state=open]:slide-in-from-bottom",
+        left: "inset-y-0 left-0 h-full w-3/4 data-[state=closed]:slide-out-to-left data-[state=open]:slide-in-from-left",
         right:
-          "inset-y-0 right-0 h-full w-3/4 border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right sm:max-w-sm rounded-l-2xl",
+          "inset-y-0 right-0 h-full w-3/4 data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
+      },
+      attachment: {
+        edge: "p-6",
+        // Padding is the caller's business here: a detail surface runs a gallery
+        // and a sticky action bar to the panel edge, and a fixed p-6 would inset
+        // both. `edge` keeps its p-6 so nothing already shipped shifts.
+        inset: "rounded-2xl overflow-hidden",
       },
     },
+    compoundVariants: [
+      // `edge` restates exactly what each side carried before `attachment`
+      // existed — the seam border and the two inward-facing corners. Kept as
+      // compounds rather than left on `side` so `inset` is not fighting them
+      // through class-merge order.
+      // `sm:max-w-sm` lives here, not on `side`: an inset panel is sized by its
+      // caller, and a responsive cap left on `side` cannot be overridden from
+      // className — tailwind-merge scopes `sm:max-w-*` and `max-w-*` to
+      // different groups, so `max-w-none` loses to it at every width ≥ sm.
+      { side: "top", attachment: "edge", class: "border-b" },
+      { side: "bottom", attachment: "edge", class: "border-t rounded-t-2xl" },
+      { side: "left", attachment: "edge", class: "border-r rounded-r-2xl sm:max-w-sm" },
+      { side: "right", attachment: "edge", class: "border-l rounded-l-2xl sm:max-w-sm" },
+      // The inset offsets live here rather than on `attachment` because each
+      // side has to give up its own edge: a right-side panel clears top, right
+      // and bottom but is still anchored to the right.
+      { side: "right", attachment: "inset", class: "inset-y-3 right-3 h-auto" },
+      { side: "left", attachment: "inset", class: "inset-y-3 left-3 h-auto" },
+      { side: "top", attachment: "inset", class: "inset-x-3 top-3" },
+      { side: "bottom", attachment: "inset", class: "inset-x-3 bottom-3" },
+    ],
     defaultVariants: {
       side: "right",
+      attachment: "edge",
     },
   }
 );
@@ -51,20 +96,35 @@ const sheetVariants = cva(
 interface SheetContentProps
   extends
     React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>,
-    VariantProps<typeof sheetVariants> {}
+    VariantProps<typeof sheetVariants> {
+  /**
+   * Suppress the built-in floating close button. Use when the panel renders its
+   * own header row with a close control, which would otherwise stack two close
+   * buttons in the same corner.
+   */
+  hideClose?: boolean;
+}
 
 const SheetContent = React.forwardRef<
   React.ElementRef<typeof SheetPrimitive.Content>,
   SheetContentProps
->(({ side = "right", className, children, ...props }, ref) => (
+>(({ side = "right", attachment = "edge", className, children, hideClose, ...props }, ref) => (
   <SheetPortal>
     <SheetOverlay />
-    <SheetPrimitive.Content ref={ref} className={cn(sheetVariants({ side }), className)} {...props}>
+    <SheetPrimitive.Content
+      ref={ref}
+      className={cn(sheetVariants({ side, attachment }), className)}
+      {...props}
+    >
       {children}
-      <SheetPrimitive.Close className="absolute right-4 top-4 rounded-lg opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-secondary glass-hover p-2">
-        <X className="h-4 w-4" />
-        <span className="sr-only">Close</span>
-      </SheetPrimitive.Close>
+      {/* Surfaces that run their own header own the close control there, and
+          would otherwise stack two of them in the same corner. */}
+      {!hideClose && (
+        <SheetPrimitive.Close className="absolute right-4 top-4 rounded-lg opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-secondary glass-hover p-2">
+          <X className="h-4 w-4" />
+          <span className="sr-only">Close</span>
+        </SheetPrimitive.Close>
+      )}
     </SheetPrimitive.Content>
   </SheetPortal>
 ));

package/src/components/sliding-panels.stories.tsx

@@ -66,3 +66,73 @@ function SlidingPanelsDemo() {
 export const Default: Story = {
   render: () => <SlidingPanelsDemo />,
 };
+
+function KeyboardSafetyDemo() {
+  const [currentPanel, setCurrentPanel] = useState("list");
+
+  const panels = [
+    {
+      id: "list",
+      content: (
+        <div className="space-y-2 p-4">
+          <h3 className="text-lg font-semibold">Items</h3>
+          {["Espresso", "Cortado", "Flat white", "Cold brew"].map((item) => (
+            <Button
+              key={item}
+              variant="outline"
+              className="w-full justify-start"
+              onClick={() => setCurrentPanel("detail")}
+            >
+              {item}
+            </Button>
+          ))}
+        </div>
+      ),
+    },
+    {
+      id: "detail",
+      parentId: "list",
+      showBackButton: true,
+      backButtonLabel: "Assign",
+      content: (
+        <div className="space-y-3 p-4">
+          <p className="text-muted-foreground text-sm">
+            Tab through this panel — focus never reaches the list behind it, because inactive
+            panels are <code>inert</code>.
+          </p>
+          <div className="flex gap-2">
+            <Button variant="outline">Split</Button>
+            <Button variant="outline">Assign</Button>
+            <Button onClick={() => setCurrentPanel("list")}>Done</Button>
+          </div>
+        </div>
+      ),
+    },
+  ];
+
+  return (
+    <div className="w-[400px] space-y-4">
+      <p className="text-muted-foreground text-sm">
+        Open the detail panel, then press Tab repeatedly: only the visible panel is reachable.
+      </p>
+      <div className="rounded-lg border overflow-hidden">
+        <SlidingPanels
+          panels={panels}
+          currentPanel={currentPanel}
+          onPanelChange={setCurrentPanel}
+        />
+      </div>
+      <Button variant="ghost">Control after the panels</Button>
+    </div>
+  );
+}
+
+/**
+ * Hidden panels stay mounted so the slide can animate, but they carry `inert`
+ * — their controls are out of the tab order, untargetable by pointer, and
+ * skipped by find-in-page. Tab from the top of this story: focus goes through
+ * the active panel and straight on to "Control after the panels".
+ */
+export const HiddenPanelsAreNotTabbable: Story = {
+  render: () => <KeyboardSafetyDemo />,
+};

package/src/components/sliding-panels.test.tsx

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi } from "vitest";
+import { useState } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SlidingPanels, type Panel } from "./sliding-panels";
+
+const basePanels: Panel[] = [
+  { id: "one", content: <button type="button">Action one</button> },
+  {
+    id: "two",
+    showBackButton: true,
+    backButtonLabel: "Two",
+    content: <button type="button">Action two</button>,
+  },
+  { id: "three", content: <button type="button">Action three</button> },
+];
+
+const panelWrappers = () =>
+  Array.from(document.querySelectorAll<HTMLElement>('[data-slot="sliding-panel"]'));
+
+// The back button is icon-only, so it is the one button in the active panel
+// with no text content.
+const backButton = () =>
+  screen.getAllByRole("button").filter((button) => button.textContent === "")[0];
+
+function Controlled({ initial = "one" }: { initial?: string }) {
+  const [current, setCurrent] = useState(initial);
+  return (
+    <SlidingPanels panels={basePanels} currentPanel={current} onPanelChange={setCurrent} />
+  );
+}
+
+describe("SlidingPanels", () => {
+  it("renders every panel so transitions can animate", () => {
+    render(<Controlled />);
+    expect(panelWrappers()).toHaveLength(3);
+    expect(screen.getByText("Action three")).toBeInTheDocument();
+  });
+
+  it("marks inactive panels inert and leaves the active one interactive", () => {
+    render(<Controlled initial="two" />);
+    const [one, two, three] = panelWrappers();
+    expect(one).toHaveAttribute("inert");
+    expect(two).not.toHaveAttribute("inert");
+    expect(three).toHaveAttribute("inert");
+  });
+
+  it("keeps aria-hidden in sync with inert for engines that ignore inert", () => {
+    render(<Controlled initial="two" />);
+    const [one, two] = panelWrappers();
+    expect(one).toHaveAttribute("aria-hidden", "true");
+    expect(two).not.toHaveAttribute("aria-hidden", "true");
+  });
+
+  it("exposes active state via data-state", () => {
+    render(<Controlled initial="three" />);
+    expect(panelWrappers().map((el) => el.dataset.state)).toEqual([
+      "inactive",
+      "inactive",
+      "active",
+    ]);
+  });
+
+  it("moves inert onto the previously active panel after navigation", async () => {
+    const user = userEvent.setup();
+    render(<Controlled initial="two" />);
+    await user.click(backButton());
+
+    const [one, two] = panelWrappers();
+    expect(one).not.toHaveAttribute("inert");
+    expect(two).toHaveAttribute("inert");
+  });
+
+  it("keeps the transform transition classes on inert panels", () => {
+    render(<Controlled initial="two" />);
+    const [one, two, three] = panelWrappers();
+    expect(one.className).toContain("transition-transform");
+    expect(one.className).toContain("-translate-x-[calc(100%+8px)]");
+    expect(two.className).toContain("translate-x-0");
+    expect(three.className).toContain("translate-x-[calc(100%+8px)]");
+  });
+
+  it("never leaves the active panel inert in tree mode", () => {
+    const treePanels: Panel[] = [
+      { id: "root", content: <button type="button">Root</button> },
+      { id: "child", parentId: "root", content: <button type="button">Child</button> },
+      { id: "sibling", parentId: "root", content: <button type="button">Sibling</button> },
+    ];
+    render(
+      <SlidingPanels panels={treePanels} currentPanel="child" onPanelChange={vi.fn()} />
+    );
+    const [root, child, sibling] = panelWrappers();
+    expect(root).toHaveAttribute("inert");
+    expect(child).not.toHaveAttribute("inert");
+    expect(sibling).toHaveAttribute("inert");
+  });
+
+  it("navigates back to the parent panel from the back button", async () => {
+    const user = userEvent.setup();
+    const onPanelChange = vi.fn();
+    const treePanels: Panel[] = [
+      { id: "root", content: <button type="button">Root</button> },
+      {
+        id: "child",
+        parentId: "root",
+        showBackButton: true,
+        content: <button type="button">Child</button>,
+      },
+    ];
+    render(
+      <SlidingPanels panels={treePanels} currentPanel="child" onPanelChange={onPanelChange} />
+    );
+    await user.click(backButton());
+    expect(onPanelChange).toHaveBeenCalledWith("root");
+  });
+});

package/src/components/sliding-panels.tsx

@@ -82,6 +82,7 @@ export const SlidingPanels = ({
 
   return (
     <div
+      data-slot="sliding-panels"
       className={cn(
         "relative overflow-clip transition-[height] duration-500 ease-[cubic-bezier(0.32,0.72,0,1)]",
         className
@@ -101,12 +102,25 @@ export const SlidingPanels = ({
             ref={(el) => {
               panelRefs.current[index] = el;
             }}
+            data-slot="sliding-panel"
+            data-state={isActive ? "active" : "inactive"}
             className={cn(
               "absolute top-0 left-0 w-full transition-transform duration-500 ease-[cubic-bezier(0.32,0.72,0,1)]",
               isActive && "translate-x-0",
               isLeft && "-translate-x-[calc(100%+8px)]",
               isRight && "translate-x-[calc(100%+8px)]"
             )}
+            // Off-screen panels stay mounted (so the slide can animate), which
+            // used to leave their controls in the tab order behind the active
+            // panel. `inert` takes them out of tab order, pointer targeting and
+            // find-in-page without touching layout or the transform transition.
+            // Written as `true | undefined` rather than a raw boolean: HTML
+            // treats *any* value as inert, so a literal `inert={false}` would
+            // disable the active panel on renderers that stringify booleans.
+            // `aria-hidden` is kept alongside it: modern engines derive that
+            // semantic from `inert` itself (no double announcement), but older
+            // ones that ignore `inert` still need it to hide the subtree.
+            inert={!isActive || undefined}
             aria-hidden={!isActive}
           >
             {panel.showBackButton && (

package/src/components/sonner.tsx

@@ -1,10 +1,10 @@
 "use client";
 
 import {
+  CircleAlertIcon,
   CircleCheckIcon,
   InfoIcon,
   Loader2Icon,
-  OctagonXIcon,
   TriangleAlertIcon,
 } from "lucide-react";
 import { useTheme } from "next-themes";
@@ -21,7 +21,7 @@ const Toaster = ({ ...props }: ToasterProps) => {
         success: <CircleCheckIcon className="size-4" />,
         info: <InfoIcon className="size-4" />,
         warning: <TriangleAlertIcon className="size-4" />,
-        error: <OctagonXIcon className="size-4" />,
+        error: <CircleAlertIcon className="size-4" />,
         loading: <Loader2Icon className="size-4 animate-spin" />,
       }}
       style={

package/src/components/stepper.tsx

@@ -76,8 +76,11 @@ const Stepper = React.forwardRef<HTMLElement, StepperProps>(
                   <span
                     className={cn(
                       "whitespace-nowrap transition-colors",
+                      // current and complete share a weight; COLOUR carries the
+                      // state (full → 80% → 40%). `complete` was 500, the one
+                      // step that is not in the 400/600/700 system.
                       status === "current" && "font-semibold text-foreground",
-                      status === "complete" && "font-medium text-foreground/80",
+                      status === "complete" && "font-semibold text-foreground/80",
                       status === "upcoming" && "text-foreground/40",
                     )}
                   >

package/src/components/table.tsx

@@ -56,7 +56,7 @@ const TableFooter = React.forwardRef<
   <tfoot
     ref={ref}
     data-slot="table-footer"
-    className={cn("border-t border-border bg-muted/50 font-medium [&>tr]:last:border-b-0", className)}
+    className={cn("border-t border-border bg-muted/50 font-semibold [&>tr]:last:border-b-0", className)}
     {...props}
   />
 ));

package/src/components/tabs.tsx

@@ -115,7 +115,7 @@ const TabsTrigger = React.forwardRef<
       ref={composedRef}
       data-slot="tabs-trigger"
       className={cn(
-        "relative inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+        "relative inline-flex items-center justify-center whitespace-nowrap text-sm font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
         variant === "pill" &&
           "rounded-xl px-4 py-1.5 text-muted-foreground hover:text-foreground data-[state=active]:text-foreground",
         variant === "underline" &&

package/src/components/tag-group.tsx

@@ -18,7 +18,7 @@ const TagGroup = React.forwardRef<
     {...props}
   >
     {label && !srLabel && (
-      <span className="mr-1 text-xs font-medium text-muted-foreground">{label}</span>
+      <span className="mr-1 text-xs font-semibold text-muted-foreground">{label}</span>
     )}
     {children}
   </div>

package/src/components/tag.tsx

@@ -6,7 +6,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../lib/utils";
 
 const tagVariants = cva(
-  "inline-flex items-center gap-1 rounded-full border text-xs font-medium transition-colors",
+  "inline-flex items-center gap-1 rounded-full border text-xs font-semibold transition-colors",
   {
     variants: {
       variant: {

package/src/components/text.test.tsx

@@ -2,6 +2,24 @@ import { describe, it, expect } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { Text, textVariants } from "./text";
 
+// Every variant in the scale. Kept explicit (not derived from the cva config)
+// so adding a variant forces a deliberate edit here — the point of a CLOSED
+// set is that growing it is a decision, not a side effect.
+const VARIANTS = [
+  "display",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "body-lg",
+  "body",
+  "body-sm",
+  "small",
+  "caption",
+  "label",
+  "overline",
+] as const;
+
 // ─── textVariants utility ────────────────────────────────────────────────────
 
 describe("textVariants", () => {
@@ -29,17 +47,33 @@ describe("textVariants", () => {
     expect(textVariants({ variant: "body" })).toContain("text-base");
     expect(textVariants({ variant: "body-sm" })).toContain("text-sm");
     expect(textVariants({ variant: "caption" })).toContain("text-xs");
-    expect(textVariants({ variant: "label" })).toContain("font-medium");
+    expect(textVariants({ variant: "label" })).toContain("font-semibold");
     expect(textVariants({ variant: "overline" })).toContain("uppercase");
   });
 
-  it("maps weight props", () => {
+  it("maps weight props onto the 3-weight scale", () => {
     expect(textVariants({ weight: "normal" })).toContain("font-normal");
-    expect(textVariants({ weight: "medium" })).toContain("font-medium");
     expect(textVariants({ weight: "semibold" })).toContain("font-semibold");
     expect(textVariants({ weight: "bold" })).toContain("font-bold");
   });
 
+  // The scale is 400/600/700. `medium` survives as a deprecated alias so the
+  // existing call sites keep compiling, but it must never emit 500 again.
+  it("never emits weight 500", () => {
+    expect(textVariants({ weight: "medium" })).toContain("font-semibold");
+    for (const variant of VARIANTS) {
+      expect(textVariants({ variant })).not.toContain("font-medium");
+    }
+  });
+
+  // `body-lg` and `small` are deprecated duplicates. They must stay
+  // byte-compatible with the role that replaced them, or the two apps drift
+  // back onto two names for one size.
+  it("keeps deprecated aliases identical to their replacements", () => {
+    expect(textVariants({ variant: "body-lg" })).toBe(textVariants({ variant: "body" }));
+    expect(textVariants({ variant: "small" })).toContain("text-sm");
+  });
+
   it("maps leading props", () => {
     expect(textVariants({ leading: "none" })).toContain("leading-none");
     expect(textVariants({ leading: "tight" })).toContain("leading-tight");

package/src/components/text.tsx

@@ -2,6 +2,24 @@ import * as React from "react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../lib/utils";
 
+/**
+ * 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.
+ */
 const textVariants = cva("", {
   variants: {
     variant: {
@@ -10,12 +28,19 @@ const textVariants = cva("", {
       h2: "text-2xl font-semibold tracking-tight",
       h3: "text-xl font-semibold",
       h4: "text-lg font-semibold leading-none tracking-tight",
+      /** @deprecated Now identical to `body`. Use `body`. */
       "body-lg": "text-base leading-relaxed",
-      body: "text-base leading-normal",
+      // `leading-relaxed`, absorbing what `body-lg` was: 16px is the prose size
+      // and prose wants relaxed leading. Two variants differing only in
+      // line-height forced every author to choose between two names for one
+      // role, and the two apps duly diverged onto different ones.
+      body: "text-base leading-relaxed",
       "body-sm": "text-sm leading-relaxed",
+      /** @deprecated Use `body-sm` + `color="muted"` — same size, second name. */
       small: "text-sm text-muted-foreground",
       caption: "text-xs leading-normal text-muted-foreground",
-      label: "text-sm font-medium",
+      // 600, not 500 — see the weight scale below.
+      label: "text-sm font-semibold",
       overline: "text-xs font-semibold uppercase tracking-wider",
     },
     color: {
@@ -26,9 +51,13 @@ const textVariants = cva("", {
       "primary-foreground": "text-primary-foreground",
       inherit: "",
     },
+    // Three weights: 400 / 600 / 700. A fourth step is not a hierarchy level,
+    // it is noise — 500 against 600 is indistinguishable at body sizes while
+    // still counting as a separate treatment when you audit a screen.
     weight: {
       normal: "font-normal",
-      medium: "font-medium",
+      /** @deprecated Alias for `semibold`. 500 is not in the 3-weight system. */
+      medium: "font-semibold",
       semibold: "font-semibold",
       bold: "font-bold",
     },

package/src/components/toggle.tsx

@@ -7,7 +7,7 @@ import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../lib/utils";
 
 const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium hover:bg-accent/50 hover:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 transition-colors aria-invalid:ring-2 aria-invalid:ring-destructive/40 whitespace-nowrap",
+  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-semibold hover:bg-accent/50 hover:text-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 transition-colors aria-invalid:ring-2 aria-invalid:ring-destructive/40 whitespace-nowrap",
   {
     variants: {
       variant: {