@lovett/ui 0.0.5 → 0.0.7

package/dist/styles.css

@@ -25,6 +25,8 @@
  *   .has-leading/trailing, .is-error/disabled,
  *   .size-sm/lg                                        — Input, Textarea
  *   .scrollbar-hide                                    — ChipNav
+ *   .ds-enter-pop, .ds-enter-rise                      — DropdownMenu,
+ *                                                        FloatingStatusBar
  *   prefers-reduced-motion block                       — accessibility
  *
  * Out of scope for Phase 1: .empty, .skel, .field*, .pg-header, .search-bar,
@@ -33,6 +35,24 @@
  * consumers (Field, EmptyState, PageHeader, etc.) arrive in later phases.
  */
 
+/* ---- PANE MASK ---- */
+/**
+ * Opaque fill matching the MainLayout content pane, for a sticky element that
+ * must hide content scrolling beneath it.
+ *
+ * Exists because the mask has to equal the pane EXACTLY or content shows
+ * through / bands, and the only token that does is `--main-content-bg` —
+ * internal, so lens code cannot name it (CLAUDE.md §5). Same shape as
+ * `.ds-card-tray` owning `--tray-bg`: the class lives here, consumers use the
+ * class. This is NOT a raised surface — do not reach for `--surface-raised`
+ * (ADR-063); a sticky mask must match the pane, not sit above it.
+ *
+ * Consumers: sem-spec `output/index.tsx`, `share-view/ad-preview-section.tsx`.
+ */
+.ds-pane-mask {
+  background: rgb(var(--main-content-bg));
+}
+
 /* ---- CARD SURFACE ---- */
 .ds-card-surface {
   background: rgb(var(--bg-card));
@@ -57,6 +77,11 @@
 
 /* ---- CARD TRAY ---- */
 .ds-card-tray {
+  /* 4px, not 10. Concentric radius is outer = inner + padding, so a
+     16px card around a 12px tray wants a 4px inset — at 10 the maths
+     was 22 and the corners fought each other. It is also what every
+     kit in the corpus measures (AI Agent: pad 4, r16 outer / r12
+     inner), and it is what reads as thinner and sleeker. */
   margin: var(--tray-inset);
   background: rgb(var(--tray-bg));
   /* Owner ask: visible 1px border on the inner tray so the tray surface
@@ -534,8 +559,57 @@
   transform: scaleY(2);
 }
 
+/* ---- ENTRANCE ANIMATIONS ----
+ *
+ * These exist because `animate-in` / `fade-in-0` / `zoom-in-95` /
+ * `slide-in-from-bottom-2` are NOT Tailwind core utilities — they ship in
+ * `tailwindcss-animate` / `tw-animate-css`, neither of which is a dependency
+ * of this repo. Both of the kit's entrance animations were therefore
+ * referencing classes that were never generated and had never run, while
+ * typecheck, lint and build stayed green.
+ *
+ * Adding the dependency would need an ADR (CLAUDE.md §1); two keyframes do
+ * not. Durations come from the motion tokens rather than being re-specified
+ * per call site.
+ */
+@keyframes ds-enter-pop {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+@keyframes ds-enter-rise {
+  from {
+    opacity: 0;
+    transform: translateY(0.5rem);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+/* Popovers, menus, dropdowns — anchored to a trigger, so they scale open. */
+.ds-enter-pop {
+  animation: ds-enter-pop var(--dur-fast) var(--ease-out);
+}
+/* Bars and toasts entering from a screen edge. Animates `transform`, which
+ * composes with (rather than overwrites) a `translate`-based centering
+ * utility such as `-translate-x-1/2`. */
+.ds-enter-rise {
+  animation: ds-enter-rise var(--dur-base) var(--ease-out);
+}
+
 /* ---- REDUCED MOTION ---- */
 @media (prefers-reduced-motion: reduce) {
+  /* 0.01ms rather than `none` so animationend still fires for any listener. */
+  .ds-enter-pop,
+  .ds-enter-rise {
+    animation-duration: 0.01ms !important;
+  }
   .btn,
   .btn-primary,
   .input-shell {

package/dist/tokens.css

@@ -30,7 +30,7 @@
  *     • Text:      --foreground, --text-secondary, --text-tertiary,
  *                  --text-muted, --muted-foreground
  *     • Semantic:  --success(-bg), --warning(-bg), --info(-bg),
- *                  --destructive(-foreground)
+ *                  --destructive(-bg, -foreground)
  *     • Folder:    --folder-red/amber/emerald/teal/blue/violet/pink/
  *                  slate/ink (categorical palette for folder accents)
  *     • Spacing:   --space-1…12 (4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48)
@@ -125,32 +125,23 @@
   /* ============================================================
      DARK THEME SURFACES  — INTERNAL (primitives only)
      ============================================================ */
-  --background: 9 9 11;
   --foreground: 244 244 245;
-  --bg-surface: 17 17 19;
-  --bg-elevated: 24 24 27;
-  --bg-card: 20 20 22;
-  --bg-card-hover: 26 26 29;
-  --bg-input: 15 15 17;
-
-  --card: 20 20 22;
+  /* PUBLIC (ADR-063 D1): opaque elevated surface for bespoke lens/app
+     floating chrome (pills, capsules, one-off raised panels) that can't be a
+     primitive. Same values as the INTERNAL --bg-elevated by design. */
   --card-foreground: 244 244 245;
-  --popover: 24 24 27;
   --popover-foreground: 244 244 245;
-
-  --muted: 39 39 42;
   --muted-foreground: 161 161 170;
   --text-secondary: 161 161 170;
-  --text-tertiary: 113 113 122;
-  --text-muted: 82 82 91;
-
-  --secondary: 39 39 42;
+  /* Lifted 113->132 / 82->106: at the old values --text-tertiary measured
+     3.56:1 and --text-muted 2.22:1 on --bg-card, i.e. both under the 3:1
+     floor on the surface they are most often used on. */
+  --text-tertiary: 132 132 141;
+  --text-muted: 106 106 115;
   --secondary-foreground: 244 244 245;
 
   --border: 255 255 255 / 0.08;
   --border-strong: 255 255 255 / 0.14;
-  --input: 39 39 42;
-
   /* Semantic — PUBLIC */
   --success: 16 185 129;
   --success-bg: 16 185 129 / 0.12;
@@ -159,6 +150,7 @@
   --info: 59 130 246;
   --info-bg: 59 130 246 / 0.12;
   --destructive: 239 68 68;
+  --destructive-bg: 239 68 68 / 0.12;
   --destructive-foreground: 255 255 255;
 
   /* Folder palette — PUBLIC. Categorical accents for Asset folders
@@ -211,8 +203,6 @@
   --bullet-offset-y: 7px;
 
   /* Recessed card footer strip — INTERNAL (<Card.Foot>) */
-  --card-foot-bg: 255 255 255 / 0.025;
-
   /* Card surface — INTERNAL (<Card>) */
   --border-card: 255 255 255 / 0.08;
   --card-shadow-rest:
@@ -221,13 +211,10 @@
     0 4px 12px rgb(0 0 0 / 0.28);
 
   /* Card-tray — INTERNAL (<Card.Tray>) */
-  --tray-bg: 24 24 27;
-  --tray-inset: 10px;
+  --tray-inset: 4px;
   --radius-tray: var(--radius-md);
 
   /* Card frame — INTERNAL (outer .ds-card-surface bg in framed mode) */
-  --card-frame-bg: 20 20 22;
-
   /* ============================================================
      CALCULATOR SHELL v2 — INTERNAL (ADR-076 D7). Consumed only by
      the v2 primitives (CalculatorShellV2 header, StatRow tiles) and
@@ -250,7 +237,6 @@
   /* ============================================================
      MAIN CONTENT AREA — INTERNAL (layout primitives only)
      ============================================================ */
-  --main-content-bg: 10 10 11;
   --main-content-border: 255 255 255 / 0.08;
 
   /* ============================================================
@@ -294,9 +280,6 @@
   --surface-overlay: 255 255 255 / 0.06;
   --surface-overlay-strong: 255 255 255 / 0.10;
   --surface-overlay-stronger: 255 255 255 / 0.16;
-
-  --page-bg: 5 5 6;
-  --bg-input-hover: 19 19 22;
   --modal-overlay: 0 0 0 / 0.65;
 
   /* `--surface-on-accent` — PUBLIC (Phase Sidebar-E MIN-1, ADR-049).
@@ -349,7 +332,43 @@
   --toast-border: 255 255 255 / 0.10;
 
   /* Canvas placement bg — INTERNAL (placement primitive) */
-  --canvas-placement-bg: 17 17 19;
+
+  /* Surface ladder — dark. Same five roles, same hue family. */
+  --surface-page: 11 11 12;
+  --surface-frame: 21 21 23;
+  --surface-card: 27 27 30;
+  --surface-inset: 45 45 48;
+  --surface-hover: 55 55 59;
+  /* A control you can act on — input, select, option tile, chip-button.
+     Sits at CARD level on purpose: in light that is white against the
+     frame behind it, which reads "type here"; in dark it is raised above
+     the frame. --muted/--surface-inset is the RECESSED role (wells, zebra,
+     table headers) and reads as disabled when a control borrows it. The
+     lenses were borrowing it because --bg-input is internal and this
+     public role did not exist. */
+  --surface-control: var(--surface-card);
+  --surface-elevated: 37 37 40;
+
+  --page-bg: var(--surface-page);
+  --background: var(--surface-page);
+  --main-content-bg: var(--surface-page);
+  --bg-surface: var(--surface-frame);
+  --bg-card: var(--surface-card);
+  --card: var(--surface-card);
+  --tray-bg: var(--surface-card);
+  --card-frame-bg: var(--surface-frame);
+  --card-foot-bg: var(--surface-frame);
+  --bg-elevated: var(--surface-elevated);
+  --surface-raised: var(--surface-elevated);
+  --popover: var(--surface-elevated);
+  --bg-input: var(--surface-frame);
+  --muted: var(--surface-inset);
+  --input: var(--surface-inset);
+  --secondary: var(--surface-inset);
+  --canvas-placement-bg: var(--surface-frame);
+  --bg-card-hover: var(--surface-hover);
+  --bg-input-hover: var(--surface-inset);
+
 }
 
 /* ============================================================
@@ -382,27 +401,15 @@
    * almost entirely on --border-card (0.07). If cards visually
    * disappear, bump --border-card. Hover/muted/input-hover stay
    * darker on purpose so state changes remain visible. */
-  --background: 254 254 254;
   --foreground: 17 17 19;
-  --bg-surface: 254 254 254;
-  --bg-elevated: 255 255 255;
-  --bg-card: 255 255 255;
-  --bg-card-hover: 244 244 244;
-  --bg-input: 255 255 255;
-  --bg-input-hover: 253 253 253;
-
-  --card: 255 255 255;
+  /* PUBLIC (ADR-063 D1) — see the dark block note. */
   --card-foreground: 17 17 19;
-  --popover: 255 255 255;
   --popover-foreground: 17 17 19;
-
-  --muted: 245 245 245;
   --muted-foreground: 82 82 91;
   --text-secondary: 82 82 91;
   /* --text-tertiary stays from :root */
-  --text-muted: 161 161 170;
-
-  --secondary: 244 244 245;
+  /* Lifted 161->137 — was 2.56:1 on a white card. */
+  --text-muted: 137 137 146;
   --secondary-foreground: 17 17 19;
 
   --border: 0 0 0 / 0.12;
@@ -412,8 +419,6 @@
    * to delineate. The 0.16 value worked when --bg-input was slate-tinted; on
    * white-on-white the prior border was too subtle. */
   --border-input: 0 0 0 / 0.22;
-  --input: 244 244 245;
-
   --success: 5 150 105;
   --success-bg: 5 150 105 / 0.10;
   /* `--warning` and the folder palette are intentionally split out
@@ -423,13 +428,12 @@
   --info: 37 99 235;
   --info-bg: 37 99 235 / 0.10;
   --destructive: 220 38 38;
+  --destructive-bg: 220 38 38 / 0.10;
 
   --surface-overlay-soft: 0 0 0 / 0.03;
   --surface-overlay: 0 0 0 / 0.05;
   --surface-overlay-strong: 0 0 0 / 0.08;
   --surface-overlay-stronger: 0 0 0 / 0.12;
-
-  --page-bg: 254 254 254;
   --modal-overlay: 0 0 0 / 0.40;
   /* `--surface-on-accent` stays white in light mode too — see :root
    * comment. Declared here for symmetry / future-proofing. */
@@ -449,17 +453,7 @@
    * what was actually painting "the steely background" the owner
    * flagged; --page-bg is the body, but MainLayout's content area
    * paints with this token. Both must move together. */
-  --main-content-bg: 254 254 254;
   --main-content-border: 0 0 0 / 0.10;
-
-  --canvas-placement-bg: 241 245 249;
-
-  --card-foot-bg: 248 250 252;
-
-  --tray-bg: 255 255 255;
-
-  --card-frame-bg: 248 250 252;
-
   /* Calculator Shell v2 — light overrides (ADR-076 D7). */
   --brand-ink: 20 20 23;
   --shell-shadow:
@@ -483,6 +477,68 @@
     0 2px 4px rgb(0 0 0 / 0.07),
     0 8px 24px rgb(0 0 0 / 0.09);
 
+  /* ============================================================
+     SURFACE LADDER — the canonical set (2026-08-04)
+     ------------------------------------------------------------
+     Before this, 19 surface tokens carried 4 distinct values, in
+     THREE different grey families: --card-frame-bg / --card-foot-bg
+     at hue 248 (slate), --muted / --bg-card-hover at 90
+     (achromatic), --input / --secondary at 286 (zinc). Mixing grey
+     families is what reads as "inconsistent" long before anyone can
+     say which value is wrong.
+
+     Everything now sits on hue 286 — the family the TEXT ramp
+     already uses (--foreground and every --text-* measure 285.8-286.4),
+     so greys and type finally agree.
+
+     FIVE roles. Every legacy name below is an alias onto one of them,
+     so no component changes and nothing is orphaned:
+
+       page    the document. PURE WHITE — no grey backdrop.
+       card    cards, trays, inputs, popovers. Also white; separation
+               is border + shadow, not a fill step.
+       frame   the CONTAINED BACKGROUND for a group of sections —
+               <FrameStack> wrapping several <SectionCard>. The only
+               place a grey surface is correct.
+       inset   recessed wells, table header strips, zebra rows.
+       hover   the deepest step; hover on an inset.
+     ============================================================ */
+  --surface-page: 255 255 255;
+  --surface-card: 255 255 255;
+  --surface-frame: 247 247 249;
+  --surface-inset: 242 242 244;
+  --surface-hover: 238 238 240;
+  /* A control you can act on — input, select, option tile, chip-button.
+     Sits at CARD level on purpose: in light that is white against the
+     frame behind it, which reads "type here"; in dark it is raised above
+     the frame. --muted/--surface-inset is the RECESSED role (wells, zebra,
+     table headers) and reads as disabled when a control borrows it. The
+     lenses were borrowing it because --bg-input is internal and this
+     public role did not exist. */
+  --surface-control: var(--surface-card);
+
+  /* Legacy names — aliases onto the five above. Kept so the ~1,300
+     existing call sites keep working; prefer the canonical names. */
+  --page-bg: var(--surface-page);
+  --background: var(--surface-page);
+  --bg-surface: var(--surface-page);
+  --main-content-bg: var(--surface-page);
+  --bg-card: var(--surface-card);
+  --card: var(--surface-card);
+  --tray-bg: var(--surface-card);
+  --bg-elevated: var(--surface-card);
+  --surface-raised: var(--surface-card);
+  --popover: var(--surface-card);
+  --bg-input: var(--surface-card);
+  --card-frame-bg: var(--surface-frame);
+  --card-foot-bg: var(--surface-frame);
+  --muted: var(--surface-inset);
+  --input: var(--surface-inset);
+  --secondary: var(--surface-inset);
+  --canvas-placement-bg: var(--surface-inset);
+  --bg-card-hover: var(--surface-hover);
+  --bg-input-hover: var(--surface-frame);
+
 }
 
 /* ============================================================
@@ -510,7 +566,12 @@
    dark even though the rest of the shell is light.
    ============================================================ */
 [data-theme="light"] {
-  --sidebar-bg: 244 244 248;
+  /* Flat white — this token is the app FRAME (main-layout.tsx paints the
+     whole shell with it), so a grey here tints every light page behind the
+     floating content card. The card's border + shadow carry the separation.
+     Matches meta-ads-audit-dashboard, which consumes the same tokens and
+     sets its rail to --page-bg. */
+  --sidebar-bg: 255 255 255;
   --sidebar-surface: 0 0 0 / 0.04;
   --sidebar-surface-hover: 0 0 0 / 0.08;
   --sidebar-surface-active: 207 14 15 / 0.10;
@@ -571,9 +632,69 @@
    so the hex literals are permitted here and nowhere in apps/.
    ============================================================ */
 :root {
-  --color-meta-blue: #1877f2;
+  --color-meta-blue: rgb(var(--platform-facebook));
   --color-meta-ink: #050505;
   --color-surface-50: #fafafa;
   --color-surface-100: #f4f4f5;
   --color-surface-200: #e4e4e7;
 }
+
+/* ============================================================
+   PLATFORM BRAND + MEDIA-OVERLAY TOKENS (theme-INDEPENDENT)
+   ------------------------------------------------------------
+   Third-party brand colours. Facebook is #1877F2 whether the
+   workspace is light or dark, so these deliberately sit OUTSIDE
+   the theme blocks — putting them in the theme would make a
+   platform badge change colour with the app, which is wrong.
+
+   This block exists because `swipes.css` and `collections.css`
+   each said, in their own header: "when a second consumer of
+   these exact tokens lands, promote to packages/ui/src/tokens.css".
+   Three landed (collections, ad-intel, the social previews), and
+   the same Facebook blue ended up defined in seven places under
+   seven names — plus an eighth, `--adstage-fb-like`, at a DIFFERENT
+   and wrong value (#2078f4). This is that promotion.
+
+   BARE TRIPLES, not complete colours: the same brand colour is
+   used at different opacities per surface (swipes/collections
+   badges at 0.78, ad-intel at 0.85), so the alpha belongs at the
+   call site — `rgb(var(--platform-facebook) / 0.78)`. Baking an
+   alpha into the token is what makes it un-shareable.
+
+   The `--media-*` overlays DO carry their alpha, because there the
+   opacity ramp IS the shared definition: swipes and collections
+   used byte-identical values.
+
+   Platform-chrome and exempt substrate (packages/ui), so the
+   literals are permitted here and nowhere in apps/.
+   ============================================================ */
+:root {
+  /* Platform brand colours. */
+  --platform-facebook: 24 119 242;
+  --platform-instagram: 225 48 108;
+  --platform-linkedin: 10 102 194;
+  --platform-google: 66 133 244;
+  /* Google's logo green — the discovery report's tiles use it where the
+   * badge surfaces use the logo blue above. Both are real, both are used. */
+  --platform-google-green: 52 168 83;
+  --platform-youtube: 255 0 0;
+  /* TikTok's brand is black, which only works as a BADGE FILL (white text
+   * on it). As an icon colour on a dark card it measures 1.22:1, so the
+   * discovery tiles use theme-aware --folder-slate instead. Same reason
+   * there is no --platform-x: X is brand-black too, and its one consumer
+   * uses --folder-ink, which is byte-identical in light mode. */
+  --platform-tiktok: 0 0 0;
+  --platform-yelp: 211 35 35;
+  --platform-email: 245 158 11;
+  --platform-website: 255 255 255;
+  /* Near-white reads on every brand fill above. */
+  --platform-on-color: 255 255 255;
+
+  /* Overlays on creative media. Theme-independent because the thing
+   * underneath is an image, not a themed surface. */
+  --media-scrim-strong: 0 0 0 / 0.78;
+  --media-scrim-mid: 0 0 0 / 0.2;
+  --media-scrim-label: 0 0 0 / 0.55;
+  --media-on-scrim: 255 255 255 / 0.88;
+  --media-overlay-btn: 255 255 255 / 0.14;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovett/ui",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "private": false,
   "type": "module",
   "description": "Design system primitives, tokens, layouts, and patterns for the Lovett portfolio.",
@@ -15,7 +15,8 @@
       "import": "./dist/index.js"
     },
     "./tokens.css": "./dist/tokens.css",
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./theme-v2.css": "./dist/theme-v2.css"
   },
   "publishConfig": {
     "access": "restricted"
@@ -32,14 +33,23 @@
     "react-router-dom": "^7.1.0"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^22",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@types/react-syntax-highlighter": "^15.5.13",
+    "@vitejs/plugin-react": "^4.3.4",
     "eslint": "^9.17.0",
+    "jsdom": "^29.1.1",
     "lucide-react": "^0.469.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "react-router-dom": "^7.1.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.2"
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.6"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -55,7 +65,9 @@
   },
   "scripts": {
     "lint": "eslint .",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:ci": "vitest run --no-file-parallelism",
     "build": "tsup",
     "clean": "rm -rf dist"
   },

package/src/__tests__/button.test.tsx

@@ -0,0 +1,137 @@
+/**
+ * Button — 254 consuming files, previously zero tests.
+ *
+ * These assert the contract every consumer relies on, not appearance:
+ * the base class survives a caller `className`, the ref reaches the
+ * element, rest props land on the DOM node, and loading implies disabled.
+ */
+import { createRef } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Button } from '../button'
+
+describe('Button', () => {
+  it('renders its children in a <button>', () => {
+    render(<Button>Save</Button>)
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument()
+  })
+
+  it('defaults to type="button" so it never submits a form by accident', () => {
+    render(<Button>Save</Button>)
+    expect(screen.getByRole('button')).toHaveAttribute('type', 'button')
+  })
+
+  it('honours an explicit type', () => {
+    render(<Button type="submit">Save</Button>)
+    expect(screen.getByRole('button')).toHaveAttribute('type', 'submit')
+  })
+
+  it('defaults to the primary variant at md', () => {
+    render(<Button>Save</Button>)
+    const btn = screen.getByRole('button')
+    expect(btn).toHaveClass('btn', 'btn-primary')
+    // md is the default and maps to no size modifier.
+    expect(btn.className).not.toMatch(/size-(sm|lg)/)
+  })
+
+  it.each([
+    ['primary', 'btn-primary'],
+    ['secondary', 'btn-secondary'],
+    ['outline', 'btn-outline'],
+    ['ghost', 'btn-ghost'],
+    ['destructive', 'btn-destructive'],
+    ['destructive-soft', 'btn-destructive-soft'],
+    ['icon', 'btn-icon'],
+    ['toolbar', 'btn-toolbar'],
+  ] as const)('maps variant=%s to .%s', (variant, expected) => {
+    render(<Button variant={variant}>x</Button>)
+    expect(screen.getByRole('button')).toHaveClass('btn', expected)
+  })
+
+  it.each([
+    ['sm', 'size-sm'],
+    ['lg', 'size-lg'],
+  ] as const)('maps size=%s to .%s', (size, expected) => {
+    render(<Button size={size}>x</Button>)
+    expect(screen.getByRole('button')).toHaveClass(expected)
+  })
+
+  it('applies is-circle only when shape=circle AND variant=icon', () => {
+    const { rerender } = render(
+      <Button shape="circle" variant="icon">
+        x
+      </Button>,
+    )
+    expect(screen.getByRole('button')).toHaveClass('is-circle')
+
+    rerender(
+      <Button shape="circle" variant="primary">
+        x
+      </Button>,
+    )
+    expect(screen.getByRole('button')).not.toHaveClass('is-circle')
+  })
+
+  it('MERGES a caller className rather than replacing the base classes', () => {
+    // Five other primitives use `className ??` replace semantics, which
+    // silently deletes their base layout. Button must not join them.
+    render(<Button className="w-full">x</Button>)
+    expect(screen.getByRole('button')).toHaveClass('btn', 'btn-primary', 'w-full')
+  })
+
+  it('disables itself while loading and flags .is-loading', () => {
+    render(<Button loading>Saving</Button>)
+    const btn = screen.getByRole('button')
+    expect(btn).toBeDisabled()
+    expect(btn).toHaveClass('is-loading')
+  })
+
+  it('does not fire onClick while loading', async () => {
+    const onClick = vi.fn()
+    render(
+      <Button loading onClick={onClick}>
+        Saving
+      </Button>,
+    )
+    await userEvent.click(screen.getByRole('button'))
+    expect(onClick).not.toHaveBeenCalled()
+  })
+
+  it('fires onClick when enabled', async () => {
+    const onClick = vi.fn()
+    render(<Button onClick={onClick}>Save</Button>)
+    await userEvent.click(screen.getByRole('button'))
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('forwards a ref to the underlying <button>', () => {
+    const ref = createRef<HTMLButtonElement>()
+    render(<Button ref={ref}>x</Button>)
+    expect(ref.current).toBeInstanceOf(HTMLButtonElement)
+  })
+
+  it('spreads rest props onto the DOM node', () => {
+    render(
+      <Button aria-describedby="hint" data-testid="cta">
+        x
+      </Button>,
+    )
+    const btn = screen.getByTestId('cta')
+    expect(btn).toHaveAttribute('aria-describedby', 'hint')
+  })
+
+  it('renders leading and trailing icons around the label', () => {
+    render(
+      <Button
+        leadingIcon={<span data-testid="lead" />}
+        trailingIcon={<span data-testid="trail" />}
+      >
+        Label
+      </Button>,
+    )
+    expect(screen.getByTestId('lead')).toBeInTheDocument()
+    expect(screen.getByTestId('trail')).toBeInTheDocument()
+    expect(screen.getByRole('button')).toHaveTextContent('Label')
+  })
+})