@elabs-ai/components-ui 4.2.0 → 5.0.0

package/src/components/top-nav/top-nav.tsx

@@ -4,13 +4,24 @@ import { cn } from "../../lib/cn";
 export interface TopNavProps extends HTMLAttributes<HTMLElement> {
   /** Left slot (brand on mobile, breadcrumbs, title). */
   start?: ReactNode;
+  /**
+   * Centred slot (e.g. a global search field, or horizontal primary
+   * navigation). Laid out as the middle column of a 3-column grid, so it
+   * stays visually centred in the bar regardless of how wide `start`/`end`
+   * are — plain `flex-1` filler only centres content when both sides are
+   * equal width. Passing `center` switches the bar to this grid layout and
+   * `children` is ignored (pass everything through `start`/`center`/`end`
+   * instead); omit `center` to keep the original `start` / `children` / `end`
+   * flex row unchanged.
+   */
+  center?: ReactNode;
   /** Right slot (search, actions, account menu). */
   end?: ReactNode;
 }
 
 /** Application top bar. Sticky, single row, brand-neutral. */
 export const TopNav = forwardRef<HTMLElement, TopNavProps>(function TopNav(
-  { className, start, end, children, ...props },
+  { className, start, center, end, children, ...props },
   ref,
 ) {
   return (
@@ -22,13 +33,32 @@ export const TopNav = forwardRef<HTMLElement, TopNavProps>(function TopNav(
       )}
       {...props}
     >
-      {start ? <div className="flex items-center gap-2">{start}</div> : null}
-      {children ? (
-        <div className="flex flex-1 items-center">{children}</div>
+      {center ? (
+        <div className="grid w-full grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-4">
+          <div
+            data-slot="top-nav-start"
+            className="flex min-w-0 items-center justify-self-start gap-2"
+          >
+            {start}
+          </div>
+          <div data-slot="top-nav-center" className="flex items-center justify-self-center">
+            {center}
+          </div>
+          <div data-slot="top-nav-end" className="flex min-w-0 items-center justify-self-end gap-2">
+            {end}
+          </div>
+        </div>
       ) : (
-        <div className="flex-1" />
+        <>
+          {start ? <div className="flex items-center gap-2">{start}</div> : null}
+          {children ? (
+            <div className="flex flex-1 items-center">{children}</div>
+          ) : (
+            <div className="flex-1" />
+          )}
+          {end ? <div className="flex items-center gap-2">{end}</div> : null}
+        </>
       )}
-      {end ? <div className="flex items-center gap-2">{end}</div> : null}
     </header>
   );
 });

package/src/components/tree/tree.stories.tsx

@@ -530,7 +530,7 @@ export const RevealSelectedNode: Story = {
 /**
  * `surface="sidebar"` renders the selected row with the sidebar's own active-item
  * treatment (`bg-sidebar-accent` + `text-sidebar-accent-foreground` + `font-medium`),
- * matching `SidebarMenuButton`'s active state — because the default `bg-accent`
+ * matching `SidebarMenuButton`'s active state — because the default `bg-selection`
  * fill is near-invisible against `--sidebar`. No fill is ≥3:1 on a sidebar, so
  * (like the Sidebar itself) perceivability comes from the foreground/weight shift
  * plus `aria-selected`, not fill contrast alone.

package/src/components/tree/tree.test.tsx

@@ -466,24 +466,24 @@ describe("Tree (surface prop)", () => {
     { id: "b", label: "Beta" },
   ];
 
-  it("default surface uses bg-accent on the selected row", async () => {
+  it("default surface uses bg-selection on the selected row", async () => {
     const user = userEvent.setup();
     render(<Tree nodes={simpleNodes} />);
     await user.click(screen.getByRole("treeitem", { name: /Alpha/ }));
     const selected = screen.getByRole("treeitem", { name: /Alpha/ });
     expect(selected).toHaveAttribute("aria-selected", "true");
     // classList gives exact token membership — avoids false matches from hover:bg-accent
-    expect(selected.classList.contains("bg-accent")).toBe(true);
+    expect(selected.classList.contains("bg-selection")).toBe(true);
     expect(selected.classList.contains("bg-sidebar-accent")).toBe(false);
   });
 
-  it("surface='default' (explicit) uses bg-accent on the selected row", async () => {
+  it("surface='default' (explicit) uses bg-selection on the selected row", async () => {
     const user = userEvent.setup();
     render(<Tree nodes={simpleNodes} surface="default" />);
     await user.click(screen.getByRole("treeitem", { name: /Alpha/ }));
     const selected = screen.getByRole("treeitem", { name: /Alpha/ });
     expect(selected).toHaveAttribute("aria-selected", "true");
-    expect(selected.classList.contains("bg-accent")).toBe(true);
+    expect(selected.classList.contains("bg-selection")).toBe(true);
     expect(selected.classList.contains("bg-sidebar-accent")).toBe(false);
   });
 

package/src/components/tree/tree.tsx

@@ -73,8 +73,8 @@ export interface TreeProps<T = unknown> extends Omit<HTMLAttributes<HTMLDivEleme
   checkboxes?: boolean;
   /**
    * The surface on which the tree is rendered.
-   * - `"default"` (default) — renders selected rows with `bg-accent` (for use on
-   *   background/card surfaces).
+   * - `"default"` (default) — renders selected rows with `bg-selection` (for use
+   *   on background/card surfaces).
    * - `"sidebar"` — renders selected rows with the sidebar's own active-item
    *   treatment (`bg-sidebar-accent` + `text-sidebar-accent-foreground` +
    *   `font-medium`), so selection reads consistently with `SidebarMenuButton`'s
@@ -311,7 +311,7 @@ function VirtualFlatRow<T>({
           selectionMode !== "none" &&
           (surface === "sidebar"
             ? "bg-sidebar-accent text-sidebar-accent-foreground font-medium"
-            : "bg-accent text-accent-foreground font-medium"),
+            : "bg-selection text-selection-foreground font-medium"),
         node.disabled && "cursor-not-allowed opacity-50 pointer-events-none",
       )}
       style={indentStyle}
@@ -594,7 +594,7 @@ function TreeItem<T>({
             selectionMode !== "none" &&
             (surface === "sidebar"
               ? "bg-sidebar-accent text-sidebar-accent-foreground font-medium"
-              : "bg-accent text-accent-foreground font-medium"),
+              : "bg-selection text-selection-foreground font-medium"),
           node.disabled && "cursor-not-allowed opacity-50 pointer-events-none",
         )}
         style={indentStyle}

package/src/components/typography/typography.stories.tsx

@@ -51,8 +51,10 @@ export const TextVariants: Story = {
       <Text variant="lead">Lead — a lead paragraph: the subtitle rung at body weight.</Text>
       <Text variant="body">Body — default reading text for app surfaces.</Text>
       <Text variant="caption">Caption — secondary / supporting body.</Text>
-      <Text variant="meta">Meta — metadata, eyebrows, timestamps.</Text>
+      <Text variant="meta">Meta — metadata, timestamps.</Text>
+      <Text variant="eyebrow">Eyebrow — an uppercase tracked label</Text>
       <Text variant="kpi">12,480</Text>
+      <Text variant="kpi-sm">1,284 — kpi-sm, a tile or satellite value</Text>
       <Text variant="code">pnpm --filter @elabs-ai/components-ui test</Text>
     </div>
   ),
@@ -84,6 +86,9 @@ export const Headings: Story = {
 export const HeadingSizeOverride: Story = {
   render: () => (
     <div className="space-y-3">
+      <Heading level={1} size="display-lg">
+        An h1 that reads as display-lg — a hero or deck headline
+      </Heading>
       <Heading level={2} size="display">
         An h2 that reads as display
       </Heading>
@@ -385,7 +390,7 @@ function CjkPanel({ sample }: { sample: CjkSample }) {
 }
 
 export const CJKFontAndLineBreaking: Story = {
-  name: "CJK font fallback + line-breaking (#15)",
+  name: "CJK font fallback + line-breaking",
   parameters: {
     docs: {
       description: {

package/src/components/typography/typography.tsx

@@ -27,6 +27,8 @@ export const TEXT_ROLE_REM = {
   meta: 0.75,
   kpi: 2,
   code: 0.8125,
+  "kpi-sm": 1.5,
+  "display-lg": 3,
 } as const;
 
 export type TextRole = keyof typeof TEXT_ROLE_REM;
@@ -41,6 +43,10 @@ export const textVariants = cva("", {
       meta: "text-meta",
       /** KPI values pair with tabular figures (interaction-guidelines). */
       kpi: "text-kpi tabular-nums",
+      /** A tile/satellite value — the rung between title and kpi. */
+      "kpi-sm": "text-kpi-sm tabular-nums",
+      /** An uppercase tracked label above a title or a column header. */
+      eyebrow: "text-eyebrow uppercase",
       /** Inline/block code pairs with the `--font-mono` seam. */
       code: "text-code font-mono",
     },
@@ -79,6 +85,8 @@ export const headingVariants = cva("text-balance text-foreground", {
   variants: {
     size: {
       /** display + title carry the `--font-display` brand seam (research 07 §E.5). */
+      /** A hero/deck headline — the rung above display. */
+      "display-lg": "font-display text-display-lg",
       display: "font-display text-display",
       title: "font-display text-title",
       subtitle: "text-subtitle",

package/src/components/view-toolbar/view-toolbar.stories.tsx

@@ -16,7 +16,7 @@ const meta = {
     docs: {
       description: {
         component:
-          "The row above a list, table or board — filters and context on the left, actions on the right. Its controls are ordinary tab stops on purpose: a dense secondary control row that should cost ONE tab stop with arrow-key roving is `Layout/Toolbar`, the component that actually claims the `toolbar` ARIA role. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs) and [Docs / View Toolbar Contract](?path=/docs/docs-view-toolbar-contract--docs) (rule R10) for the filter-chip, result-count and control-height rules of this row.",
+          "The row above a list, table or board — filters and context on the left, actions on the right. Its controls are ordinary tab stops on purpose: a dense secondary control row that should cost ONE tab stop with arrow-key roving is `Layout/Toolbar`, the component that actually claims the `toolbar` ARIA role. See [Choosing between similar components](?path=/docs/docs-choosing-between-similar-components--docs) and [ViewToolbar → Contract](?path=/docs/layout-viewtoolbar--contract) (rule R10) for the filter-chip, result-count and control-height rules of this row.",
       },
     },
   },
@@ -369,6 +369,7 @@ export const DarkTheme: Story = {
 
 /** The same row at decoration 10 — drawn, not filled. */
 export const HighDecoration: Story = {
+  tags: ["!dev"],
   globals: { decoration: "10" },
   render: () => (
     <ViewToolbar info={VIEW_INFO} actions={<ViewActions />} className="w-full max-w-4xl">

package/src/components/view-toolbar/view-toolbar.tsx

@@ -21,7 +21,7 @@
  *
  * - **No `cva`.** None of the four parts has a second visual axis today, and the
  *   rules forbid dead variants. A sticky/bounded bar is a caller `className`
- *   recipe (documented in `Docs/View Toolbar Contract`), not a variant.
+ *   recipe (documented in `Layout/ViewToolbar → Contract`), not a variant.
  * - **No `role="toolbar"` on the root.** That role promises roving-tabindex
  *   arrow-key navigation, which this row does not implement; claiming it would
  *   mislead assistive tech. Every control is an ordinary tab stop instead, and
@@ -65,7 +65,7 @@ export interface ViewToolbarProps extends HTMLAttributes<HTMLDivElement> {
    * focus but deliberately NOT on tap (and Radix suppresses the focus-open when
    * focus arrived from a pointer), so on a touch device this text is
    * unreachable. Treat `info` as progressive enhancement: never put something a
-   * phone user cannot do without in it. See `Docs/View Toolbar Contract`.
+   * phone user cannot do without in it. See `Layout/ViewToolbar → Contract`.
    */
   info?: ReactNode;
   /** Left cluster — status/context, `ViewToolbarFilters`, `ResultCount`. */

package/src/decoration.stories.tsx

@@ -2,7 +2,15 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect } from "storybook/test";
 import { DecorationProvider, type DecorationLevel } from "@elabs-ai/components-tokens";
 import { Button } from "./components/button";
-import { Card, CardContent, CardHeader, CardTitle } from "./components/card";
+import { FileText, PenLine, Plug, ShieldCheck, Workflow } from "lucide-react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardMedia,
+  CardTitle,
+} from "./components/card";
 import { Badge } from "./components/badge";
 import { Input } from "./components/input";
 
@@ -94,7 +102,7 @@ const FADES = ["top", "bottom", "edges", "center"] as const;
  * Budget: it spends the region's one focal drafting gesture. For a one-off fade on
  * a single element, use Tailwind's own `mask-t-from-*` / `mask-radial-*` utilities.
  *
- * Shipped in anger on `Patterns/Templates/Marketing`, whose hero band carries
+ * Shipped in anger on `Patterns/Templates/Starters/Marketing`, whose hero band carries
  * `data-decoration-fade="top"` so the sheet fades in behind the headline instead of
  * starting on a hard ruled edge — that template, not this matrix, is the surface to
  * judge the gesture on.
@@ -234,3 +242,206 @@ export const ControlsAreUntouched: Story = {
     await expect(getComputedStyle(button).backgroundColor).not.toBe("transparent");
   },
 };
+
+/**
+ * THE HAIRLINE FAMILY — the quiet line-work of a calm product page, as opt-in
+ * utilities (`packages/tokens`, the `--hairline-*` block). Like the paper
+ * grounds it is NOT on the dial: you ask for one gesture on one element and get
+ * it at any decoration level, in any theme. Lines take the theme's own rule ink
+ * (`--rule` / `--rule-strong`); the hatch is a translucent tint of
+ * `--foreground`, so a brand re-tints all of it by doing nothing.
+ *
+ * | utility | the gesture |
+ * | --- | --- |
+ * | `bg-hairline-hatch` | a faded diagonal hatch — the recessed WELL behind media (`CardMedia` default) |
+ * | `hairline-stack` | two sheet edges stacked under a card (`<Card stacked>`) |
+ * | `hairline-slot` | a dashed placeholder outline |
+ * | `hairline-frame` | dashed rails that run past a box's corners and fade |
+ * | `hairline-rails` | the same for a full-bleed section: rails down the content column |
+ * | `hairline-corners` | crop marks on the focal item |
+ * | `hairline-ticks-y` / `-x` | a tick ruler along an edge |
+ * | `hairline-rule` / `-y` | a dashed separator |
+ *
+ * Surfaces and the space between them only — never a control. One focal gesture
+ * per region; each utility owns its host's pseudo-elements, so nest a wrapper
+ * to combine two.
+ */
+export const Hairlines: Story = {
+  parameters: { layout: "fullscreen" },
+  render: () => (
+    <div className="bg-background px-6 py-12 text-foreground">
+      <div className="mx-auto grid max-w-5xl gap-4 md:grid-cols-3">
+        <Card>
+          <CardMedia data-testid="hairline-well">
+            <div className="flex w-full max-w-56 items-center gap-3 rounded-lg border border-card-border bg-card p-3 shadow-card">
+              <span className="flex size-9 items-center justify-center rounded-md bg-surface-muted text-muted-foreground">
+                <FileText aria-hidden="true" className="size-4" />
+              </span>
+              <span className="min-w-0 flex-1 space-y-1.5">
+                <span className="block truncate text-caption font-medium">q3-board-pack.pdf</span>
+                <span className="block h-1 rounded-full bg-surface-muted">
+                  <span className="block h-1 w-1/3 rounded-full bg-primary" />
+                </span>
+              </span>
+            </div>
+          </CardMedia>
+          <CardHeader>
+            <CardTitle>Hatch well</CardTitle>
+            <CardDescription>
+              <code>CardMedia</code> — a faded hairline hatch behind whatever the card shows.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+
+        <Card>
+          <CardMedia ground="none" className="items-end pb-0">
+            <Card
+              stacked
+              data-testid="hairline-stack"
+              className="w-full max-w-56 rounded-b-none border-b-0"
+            >
+              <CardContent className="space-y-2 p-4">
+                <p className="text-caption font-medium">Spending limit</p>
+                <span className="block h-2 rounded-sm bg-surface-muted">
+                  <span className="block h-2 w-2/5 rounded-sm bg-primary" />
+                </span>
+                <p className="text-meta text-muted-foreground">40% used · 60% free</p>
+              </CardContent>
+            </Card>
+          </CardMedia>
+          <CardHeader>
+            <CardTitle>Stacked sheets</CardTitle>
+            <CardDescription>
+              <code>{"<Card stacked>"}</code> — two sheet edges rise behind the top edge.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+
+        <Card>
+          <CardMedia ground="dots">
+            <div
+              data-testid="hairline-corners"
+              className="hairline-corners flex items-center gap-2 rounded-md border border-card-border bg-card px-3 py-2 shadow-card [--hairline-ink-strong:var(--primary-text)]"
+            >
+              <ShieldCheck aria-hidden="true" className="size-4 text-success-text" />
+              <span className="text-caption font-medium">Verified signer</span>
+              <PenLine aria-hidden="true" className="size-4 text-muted-foreground" />
+            </div>
+          </CardMedia>
+          <CardHeader>
+            <CardTitle>Crop corners on a dot field</CardTitle>
+            <CardDescription>
+              <code>hairline-corners</code> marks the focal item; re-inked here with one variable.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+
+        <Card className="md:col-span-2">
+          <CardHeader>
+            <CardTitle>Dashed slots</CardTitle>
+            <CardDescription>
+              <code>hairline-slot</code> — the empty seats next to the filled ones.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className="grid grid-cols-6 gap-3">
+              {[
+                Plug,
+                null,
+                Workflow,
+                null,
+                null,
+                ShieldCheck,
+                null,
+                FileText,
+                null,
+                PenLine,
+                null,
+                null,
+              ].map((Icon, i) =>
+                Icon ? (
+                  <span
+                    key={i}
+                    className="flex aspect-square items-center justify-center rounded-lg border border-card-border bg-card text-muted-foreground shadow-card"
+                  >
+                    <Icon aria-hidden="true" className="size-5" />
+                  </span>
+                ) : (
+                  <span
+                    key={i}
+                    data-slot-empty
+                    className="hairline-slot aspect-square rounded-lg"
+                  />
+                ),
+              )}
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Ruler and rule</CardTitle>
+            <CardDescription>
+              <code>hairline-ticks-y</code> and <code>hairline-rule</code>.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div data-testid="hairline-ticks" className="hairline-ticks-y space-y-2 ps-5">
+              <span className="block h-4 w-11/12 rounded-sm bg-primary" />
+              <span className="block h-4 w-7/12 rounded-sm bg-surface-muted" />
+              <span className="block h-4 w-4/12 rounded-sm bg-surface-muted" />
+            </div>
+            <hr className="hairline-rule" />
+            <p className="text-caption text-muted-foreground">Below the dashed rule.</p>
+          </CardContent>
+        </Card>
+      </div>
+
+      <div className="mx-auto mt-16 max-w-3xl">
+        <div data-testid="hairline-frame" className="hairline-frame p-8">
+          <p className="text-subtitle font-medium">Frame rails</p>
+          <p className="mt-1 text-caption text-muted-foreground">
+            <code>hairline-frame</code> — construction lines, not a border: each rail runs past the
+            corner and fades out, so the panel reads as placed on a drawing rather than boxed in.
+          </p>
+        </div>
+      </div>
+    </div>
+  ),
+  /**
+   * The contract a reading of the CSS cannot prove: every gesture is an INERT
+   * pseudo-element layer, the hosts are never masked (their children stay
+   * opaque), the one texture is never flat — and the hairlines are there at
+   * decoration 0, because this family does not ride the dial.
+   */
+  play: async ({ canvas }) => {
+    const well = canvas.getByTestId("hairline-well");
+    const wellLayer = getComputedStyle(well, "::before");
+    await expect(wellLayer.backgroundImage).toContain("gradient");
+    await expect(wellLayer.maskImage).not.toBe("none");
+    await expect(wellLayer.pointerEvents).toBe("none");
+    await expect(getComputedStyle(well).maskImage).toBe("none");
+
+    const stack = canvas.getByTestId("hairline-stack");
+    for (const pseudo of ["::before", "::after"] as const) {
+      const sheet = getComputedStyle(stack, pseudo);
+      await expect(sheet.content).not.toBe("none");
+      await expect(sheet.pointerEvents).toBe("none");
+      await expect(sheet.borderTopStyle).toBe("solid");
+      await expect(sheet.borderBottomWidth).toBe("0px");
+    }
+
+    for (const id of ["hairline-frame", "hairline-corners", "hairline-ticks"]) {
+      const host = canvas.getByTestId(id);
+      const layer = getComputedStyle(host, "::before");
+      await expect(layer.content).not.toBe("none");
+      await expect(layer.pointerEvents).toBe("none");
+      await expect(getComputedStyle(host).maskImage).toBe("none");
+    }
+
+    // The frame's rails overshoot the box and fade — never a hard stop.
+    const frame = getComputedStyle(canvas.getByTestId("hairline-frame"), "::before");
+    await expect(frame.maskImage).toContain("gradient");
+    await expect(Number.parseFloat(frame.left)).toBeLessThan(0);
+  },
+};

package/src/index.ts

@@ -18,6 +18,18 @@ export { cn } from "./lib/cn";
 // The canonical mobile-breakpoint check (Sidebar / ContextPanel Sheet fallback
 // pattern, research 09 §B.4) — exported so siblings don't fork a matchMedia hook.
 export { useIsMobile } from "./lib/use-mobile";
+// Scroll progress for site motion (ParallaxPlane): a native scroll timeline, a lazy
+// `motion` fallback (optional peer, dynamic import only), or static under reduced motion.
+export {
+  MOTION_FACTOR_FLOOR,
+  isMotionAtFloor,
+  readMotionFactor,
+  supportsScrollTimeline,
+  useScrollProgress,
+  type ScrollProgress,
+  type ScrollProgressMode,
+  type ScrollProgressOptions,
+} from "./lib/use-scroll-progress";
 // Browser file-download mechanics — one home for the Blob/URL → <a download> dance
 // (shared by ConversationDownload, downloadCsv, and Gallery). SSR-guarded.
 export { downloadBlob, downloadUrl } from "./lib/download";
@@ -134,6 +146,7 @@ export * from "./components/advanced-group";
 export * from "./components/app-sidebar";
 export * from "./components/alert";
 export * from "./components/alert-dialog";
+export * from "./components/ambient-field";
 export * from "./components/app-shell";
 export * from "./components/aspect-ratio";
 export * from "./components/attribution-panel";
@@ -204,12 +217,15 @@ export * from "./components/navigation-menu";
 export * from "./components/number-input";
 export * from "./components/page-shell";
 export * from "./components/pagination";
+export * from "./components/parallax-plane";
 export * from "./components/popover";
+export * from "./components/meter";
 export * from "./components/progress";
 export * from "./components/radio-group";
 export * from "./components/rating";
 export * from "./components/resizable";
 export * from "./components/reveal";
+export * from "./components/reveal-on-enter";
 export * from "./components/schema-form";
 export * from "./components/scroll-area";
 export * from "./components/section-header";
@@ -235,6 +251,7 @@ export * from "./components/tag-input";
 export * from "./components/team-switcher";
 export * from "./components/textarea";
 export * from "./components/theme-switcher";
+export * from "./components/theme-family-switch";
 export * from "./components/revision-timeline";
 export * from "./components/timeline";
 export * from "./components/toggle";
@@ -250,3 +267,32 @@ export * from "./components/view-toolbar";
 export * from "./components/virtual-select";
 export * from "./components/workspace-picker";
 export * from "./components/wizard";
+export * from "./components/command-chip";
+// SurfaceTour — RM-096
+export * from "./components/surface-tour";
+// SpecPlayground — RM-101
+export * from "./components/spec-playground";
+// IntegrationMatrix, InstallTabs — RM-102
+export * from "./components/integration-matrix";
+export * from "./components/install-tabs";
+// TokenSpotlight — RM-103
+export * from "./components/token-spotlight";
+// colorScaleFor — RM-124: the one value → colour-token scale (continuous / stepped,
+// quantile, Jenks, …) shared by `charts`, `data` and `maps`, which may not import each other.
+export {
+  colorScaleFor,
+  type ColorScale,
+  type ColorScaleCategory,
+  type ColorScaleDomain,
+  type ColorScaleMethod,
+  type ColorScalePalette,
+  type ColorScaleSpec,
+  type ColorScaleStep,
+  type ColorScaleStop,
+  type ColorScaleType,
+  type ColorScaleValue,
+  type ContinuousColorScaleMethod,
+  type ContinuousColorScaleSpec,
+  type SteppedColorScaleMethod,
+  type SteppedColorScaleSpec,
+} from "./lib/color-scale";

package/src/lib/cn.test.ts

@@ -36,4 +36,24 @@ describe("cn", () => {
   it("still dedupes conflicting text-<color> utilities against each other", () => {
     expect(cn("text-red-500", "text-blue-500")).toBe("text-blue-500");
   });
+
+  it("keeps every type role beside a text colour, and lets a later role replace it", () => {
+    for (const role of ["eyebrow", "kpi-sm", "display-lg", "heading-xs", "table-header"]) {
+      expect(cn(`text-${role}`, "text-muted-foreground")).toBe(
+        `text-${role} text-muted-foreground`,
+      );
+      expect(cn(`text-${role}`, "text-caption")).toBe("text-caption");
+    }
+  });
+
+  it("lets a caller's utility replace a component-seam token default", () => {
+    expect(cn("shadow-card", "shadow-none")).toBe("shadow-none");
+    expect(cn("shadow-popover", "shadow-lg")).toBe("shadow-lg");
+    expect(cn("shadow-dialog", "shadow-none")).toBe("shadow-none");
+    expect(cn("rounded-badge", "rounded-md")).toBe("rounded-md");
+    expect(cn("font-tabs-active", "font-bold")).toBe("font-bold");
+    expect(cn("leading-(--card-title-leading)", "leading-tight")).toBe("leading-tight");
+    expect(cn("tracking-(--table-header-tracking)", "tracking-wide")).toBe("tracking-wide");
+    expect(cn("text-table-header-foreground", "text-foreground")).toBe("text-foreground");
+  });
 });

package/src/lib/cn.ts

@@ -9,20 +9,45 @@ import { extendTailwindMerge } from "tailwind-merge";
  * group makes role-vs-role and role-vs-raw-size conflicts resolve correctly while
  * keeping role + color independent.
  */
-const TEXT_ROLES = ["display", "title", "subtitle", "body", "caption", "meta", "kpi", "code"];
+const TEXT_ROLES = [
+  "display-lg",
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "meta",
+  "eyebrow",
+  "heading-xs",
+  "kpi",
+  "kpi-sm",
+  "code",
+];
+
+/**
+ * Tailwind v4's CSS-variable shorthand (`leading-(--card-title-leading)`).
+ * tailwind-merge 2.x predates it and leaves such a class beside a caller's
+ * `leading-tight`, letting stylesheet order pick the winner. A typed hint
+ * (`text-(length:--x)`) is read as a variant prefix by 2.x and cannot be
+ * registered — give that seam a named `@theme` utility instead
+ * (`text-table-header`).
+ */
+const isVarShorthand = (value: string) => /^\(--[\w-]+\)$/.test(value);
 
 const twMerge = extendTailwindMerge({
   extend: {
     classGroups: {
-      "font-size": [{ text: TEXT_ROLES }],
+      "font-size": [{ text: [...TEXT_ROLES, "table-header"] }],
+      leading: [{ leading: [isVarShorthand] }],
+      tracking: [{ tracking: [isVarShorthand] }],
       // `font-display` is the display-face seam (sibling of font-mono, #187).
       "font-family": [{ font: ["display"] }],
-      // Theme-driven control/table knobs (themes.css § CONTROL UTILITIES and the
-      // `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /
+      // Theme-driven control/table/surface knobs (themes.css § CONTROL UTILITIES
+      // and the `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /
       // `font-bold` / `shadow-none` still replaces the token default.
-      "font-weight": [{ font: ["control", "table-header"] }],
-      rounded: [{ rounded: ["control"] }],
-      shadow: [{ shadow: ["input"] }],
+      "font-weight": [{ font: ["control", "table-header", "tabs-active"] }],
+      rounded: [{ rounded: ["control", "badge"] }],
+      shadow: [{ shadow: ["input", "card", "popover", "dialog"] }],
       h: [{ h: ["control", "control-sm", "control-lg", "header"] }],
       size: [{ size: ["control", "control-sm", "control-lg"] }],
       "min-w": [{ "min-w": ["control", "control-sm", "control-lg"] }],