@tangle-network/ui 11.2.3 → 11.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.2.3",
+  "version": "11.3.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",
@@ -141,7 +141,7 @@
     "react-dom": "^18 || ^19",
     "react-router": "^7 || ^8",
     "yjs": "^13.6.0",
-    "@tangle-network/brand": "^1.1.0"
+    "@tangle-network/brand": "^1.4.0"
   },
   "peerDependenciesMeta": {
     "@nanostores/react": {

package/src/primitives/faint-text.test.tsx

@@ -0,0 +1,127 @@
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Input, Textarea } from "./input"
+import { StatCard } from "./stat-card"
+import { TerminalLine } from "./terminal-display"
+
+/**
+ * The quietest line in each primitive — a field hint, a stat subtitle, a log
+ * timestamp — must take its colour from a TOKEN, never from a faded stronger
+ * one.
+ *
+ * A translucent foreground does not render the colour it names: it renders that
+ * colour composited over whatever plane is behind it. So `text-muted-foreground/70`
+ * measures one ratio on a card and a different one on the canvas, and the same
+ * markup is legible in one place and not in another. That is how these three
+ * landed at 3.65:1, 2.91:1 and 3.4:1 while looking, in the source, like they had
+ * been styled deliberately.
+ *
+ * These assert the RULE rather than the current class string — the point is that
+ * faint text carries no alpha, not that it carries one specific token today.
+ */
+
+/**
+ * A class with its variant chain removed: `dark:hover:text-white/50` → `text-white/50`.
+ *
+ * Split on the colons that separate variants, which are the ones at bracket
+ * depth zero — an arbitrary value carries its own (`text-[color:var(--x)]`,
+ * `supports-[display:grid]:`) and splitting on those would mangle the utility.
+ */
+function bareUtility(cls: string): string {
+  let depth = 0
+  let start = 0
+  for (let i = 0; i < cls.length; i++) {
+    const c = cls[i]
+    if (c === "[") depth++
+    else if (c === "]") depth--
+    else if (c === ":" && depth === 0) start = i + 1
+  }
+  return cls.slice(start)
+}
+
+/** Colour utilities, where a trailing `/NN` is an alpha modifier rather than a fraction. */
+const COLOUR = "text|bg|border|ring|outline|decoration|placeholder|caret|accent|fill|stroke|divide|from|via|to|shadow"
+/** `text-white/70`, `bg-card/60`, `text-[var(--x)]/40`. */
+const ALPHA_MODIFIER = new RegExp(`^(?:${COLOUR})-.+/\\d{1,3}$`)
+/** `opacity-50` — the same fade by another route. */
+const OPACITY_UTILITY = /^opacity-\d{1,3}$/
+
+function expectSolidColour(el: HTMLElement | null, what: string) {
+  expect(el, `${what} should render`).not.toBeNull()
+  // Per class, not across the whole string: a variant prefix has no whitespace
+  // in it, so a single regex over the joined list never sees where one class
+  // ends — and `dark:text-white/50` slips past a pattern anchored on spaces.
+  const faded = (el?.className ?? "")
+    .split(/\s+/)
+    .filter(Boolean)
+    .filter((cls) => {
+      const bare = bareUtility(cls)
+      return ALPHA_MODIFIER.test(bare) || OPACITY_UTILITY.test(bare)
+    })
+  expect(faded, `${what} must take a token, not a faded colour`).toEqual([])
+}
+
+describe("the fade detector itself", () => {
+  // The guard below is only worth as much as this table. An earlier version
+  // anchored on whitespace and so never saw a variant prefix — `dark:text-white/50`
+  // read as clean, which is the exact mistake the guard exists to catch.
+  const FADED = [
+    "text-muted-foreground/70",
+    "text-[var(--text-dim)]/70",
+    "dark:text-white/50",
+    "hover:text-muted-foreground/70",
+    "group-hover:text-foreground/40",
+    "md:bg-card/60",
+    "supports-[display:grid]:text-white/50",
+    "opacity-50",
+    "hover:opacity-50",
+  ]
+  const SOLID = [
+    "text-[var(--text-dim)]",
+    "text-sm",
+    "text-muted-foreground",
+    "dark:text-white",
+    // A slash that is a FRACTION, not an alpha modifier — must not trip the guard.
+    "w-1/2",
+    "basis-1/3",
+    // A colon inside an arbitrary value, which must survive variant-stripping.
+    "text-[color:var(--text-dim)]",
+  ]
+  const isFaded = (cls: string) =>
+    ALPHA_MODIFIER.test(bareUtility(cls)) || OPACITY_UTILITY.test(bareUtility(cls))
+
+  for (const cls of FADED) {
+    it(`catches ${cls}`, () => expect(isFaded(cls)).toBe(true))
+  }
+  for (const cls of SOLID) {
+    it(`allows ${cls}`, () => expect(isFaded(cls)).toBe(false))
+  }
+})
+
+describe("faint text is a token, not a faded one", () => {
+  it("Input renders its hint at full strength", () => {
+    render(<Input label="Name" hint="Shown on your public profile" />)
+    expectSolidColour(
+      screen.getByText("Shown on your public profile"),
+      "the Input hint",
+    )
+  })
+
+  it("Textarea renders its hint at full strength", () => {
+    render(<Textarea label="Bio" hint="Markdown is supported" />)
+    expectSolidColour(
+      screen.getByText("Markdown is supported"),
+      "the Textarea hint",
+    )
+  })
+
+  it("StatCard renders its subtitle at full strength", () => {
+    render(<StatCard title="Sandboxes" value={12} subtitle="up from 9" />)
+    expectSolidColour(screen.getByText("up from 9"), "the StatCard subtitle")
+  })
+
+  it("TerminalLine renders its timestamp at full strength", () => {
+    render(<TerminalLine timestamp="12:04:11">compiling</TerminalLine>)
+    expectSolidColour(screen.getByText("[12:04:11]"), "the TerminalLine timestamp")
+  })
+})

package/src/primitives/index.ts

@@ -118,3 +118,15 @@ export { CodeBlock, CopyButton, InlineCode } from "./code-block";
 export type { CodeBlockProps, InlineCodeProps } from "./code-block";
 
 export { ThemeToggle, useTheme } from "./theme-toggle";
+
+export { PageHeader } from "./page-header";
+export type { PageHeaderProps } from "./page-header";
+
+export { StatusPill } from "./status-pill";
+export type { StatusPillProps, StatusTone } from "./status-pill";
+
+export { MetricStrip, Metric } from "./metric-strip";
+export type { MetricStripProps, MetricProps } from "./metric-strip";
+
+export { Toolbar, FilterField } from "./toolbar";
+export type { ToolbarProps, FilterFieldProps } from "./toolbar";

package/src/primitives/input.tsx

@@ -65,7 +65,7 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
         {input}
         {error && <p className="text-[var(--surface-danger-text)] text-sm font-medium">{error}</p>}
         {hint && !error && (
-          <p className="text-muted-foreground/70 text-sm">{hint}</p>
+          <p className="text-[var(--text-dim)] text-sm">{hint}</p>
         )}
       </div>
     );
@@ -125,7 +125,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
         {textarea}
         {error && <p className="text-[var(--surface-danger-text)] text-sm">{error}</p>}
         {hint && !error && (
-          <p className="text-muted-foreground/70 text-sm">{hint}</p>
+          <p className="text-[var(--text-dim)] text-sm">{hint}</p>
         )}
       </div>
     );

package/src/primitives/metric-strip.test.tsx

@@ -0,0 +1,181 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Metric, MetricStrip } from "./metric-strip";
+
+describe("MetricStrip", () => {
+  it("pairs each label with its value as a described term", () => {
+    render(
+      <MetricStrip>
+        <Metric label="Balance" value="$248.55" />
+      </MetricStrip>,
+    );
+    // The label is wrapped for truncation, so assert the term it belongs to.
+    expect(screen.getByText("Balance").closest("dt")).not.toBeNull();
+    expect(screen.getByText("$248.55").tagName).toBe("DD");
+  });
+
+  // axe's `definition-list` rule allows only dt, dd, script, template and div
+  // as direct children of a dl. The hint is a second dd for this reason: a <p>
+  // between the terms is a violation, and it was one.
+  it("puts only permitted elements directly inside the dl", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Spend" value="$12.00" hint="This month" />
+        <Metric label="Runs" value="41" />
+      </MetricStrip>,
+    );
+    const dl = container.querySelector("dl") as HTMLElement;
+    const permitted = new Set(["DT", "DD", "SCRIPT", "TEMPLATE", "DIV"]);
+    for (const child of Array.from(dl.children)) {
+      expect(permitted).toContain(child.tagName);
+    }
+  });
+
+  it("renders the hint as a dd rather than a paragraph", () => {
+    render(
+      <MetricStrip>
+        <Metric label="Spend" value="$12.00" hint="Personal wallet" />
+      </MetricStrip>,
+    );
+    const hint = screen.getByText("Personal wallet");
+    expect(hint.tagName).toBe("DD");
+  });
+
+  it("omits the hint entirely when not given", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Runs" value="41" />
+      </MetricStrip>,
+    );
+    expect(container.querySelectorAll("dd")).toHaveLength(1);
+  });
+
+  // `attention` means a person has to do something, so it shows a pill next to
+  // the label. A zero on its own is not attention.
+  it("shows a pill beside the label only when attention is set", () => {
+    const { rerender, container } = render(
+      <MetricStrip>
+        <Metric label="Balance" value="$0.00" />
+      </MetricStrip>,
+    );
+    expect(container.querySelector("svg")).toBeNull();
+
+    rerender(
+      <MetricStrip>
+        <Metric
+          attention={{ tone: "danger", label: "Empty" }}
+          label="Balance"
+          value="$0.00"
+        />
+      </MetricStrip>,
+    );
+    expect(screen.getByText("Empty")).toBeInTheDocument();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("raises the value's tone only for a danger attention", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric
+          attention={{ tone: "danger", label: "Empty" }}
+          label="Balance"
+          value="$0.00"
+        />
+      </MetricStrip>,
+    );
+    const value = screen.getByText("$0.00");
+    expect(value.className).toContain("--surface-danger-text");
+    expect(container.querySelectorAll("dd")).toHaveLength(1);
+  });
+
+  // The divider is drawn only where it belongs, never drawn and then
+  // suppressed: `border-l` alongside `border-l-0` variants puts both in one
+  // conflict group whose winner is decided by emitted-rule order, and that
+  // resolved the wrong way at every breakpoint — every item kept a left border,
+  // including the first in each row.
+  it("draws the divider without a suppressing counterpart", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Balance" value="$0.00" />
+      </MetricStrip>,
+    );
+    const item = (container.querySelector("dl") as HTMLElement)
+      .children[0] as HTMLElement;
+    expect(item.className).not.toContain("border-l-0");
+  });
+
+  // The row-start test has to name the same column count the grid does, at each
+  // breakpoint. Nothing in the type system ties them together, so changing the
+  // grid to three columns without moving the divider puts a rule mid-row. Read
+  // both out of the rendered classes and require them to agree, so the coupling
+  // is enforced rather than only described.
+  it("keeps the divider's row-start test matching the grid's column count", () => {
+    const { container } = render(
+      <MetricStrip>
+        <Metric label="Balance" value="$0.00" />
+      </MetricStrip>,
+    );
+    const dl = container.querySelector("dl") as HTMLElement;
+    const item = dl.children[0] as HTMLElement;
+
+    // `grid-cols-N` unprefixed is the base breakpoint; `<bp>:grid-cols-N` is that
+    // breakpoint. The divider spells the same breakpoints as `max-<bp>:` / `<bp>:`.
+    const columnsAt = (prefix: string) => {
+      const re = prefix
+        ? new RegExp(`(?:^| )${prefix}:grid-cols-(\\d+)(?: |$)`)
+        : /(?:^| )grid-cols-(\d+)(?: |$)/;
+      const m = dl.className.match(re);
+      return m ? Number(m[1]) : null;
+    };
+    const modulusAt = (prefix: string) => {
+      const m = item.className.match(
+        new RegExp(`(?:^| )${prefix}:\\[&:not\\(:nth-child\\((\\d+)n\\+1\\)\\)\\]:border-l(?: |$)`),
+      );
+      return m ? Number(m[1]) : null;
+    };
+
+    // base grid (below sm) is guarded by the `max-sm:` divider rule
+    expect(modulusAt("max-sm")).toBe(columnsAt(""));
+    // the `sm:` grid is guarded by the `sm:` divider rule
+    expect(modulusAt("sm")).toBe(columnsAt("sm"));
+
+    // Every grid-cols breakpoint the strip declares must have a divider rule.
+    const declared = [...dl.className.matchAll(/(?:^| )(?:([a-z]+):)?grid-cols-\d+(?= |$)/g)]
+      .map((m) => m[1] ?? "");
+    for (const bp of declared) {
+      const guard = bp === "" ? "max-sm" : bp;
+      expect(
+        modulusAt(guard),
+        `grid-cols at "${bp || "base"}" has no matching ${guard}: divider rule`,
+      ).not.toBeNull();
+    }
+  });
+
+  it("titles the hint too, so a truncated qualifier stays recoverable", () => {
+    render(
+      <MetricStrip>
+        <Metric
+          hint="Personal wallet (0x1234abcd5678efgh)"
+          label="Balance"
+          value="$248.55"
+        />
+      </MetricStrip>,
+    );
+    expect(screen.getByText("Personal wallet (0x1234abcd5678efgh)")).toHaveAttribute(
+      "title",
+      "Personal wallet (0x1234abcd5678efgh)",
+    );
+  });
+
+  it("titles a string value so a truncated figure stays readable", () => {
+    render(
+      <MetricStrip>
+        <Metric label="Balance" value="$1,284,003.10" />
+      </MetricStrip>,
+    );
+    expect(screen.getByText("$1,284,003.10")).toHaveAttribute(
+      "title",
+      "$1,284,003.10",
+    );
+  });
+});

package/src/primitives/metric-strip.tsx

@@ -0,0 +1,122 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { StatusPill, type StatusTone } from "./status-pill";
+
+/**
+ * The headline figures for a console page, as ONE statement rather than four.
+ *
+ * A row of separate stat cards is the default and it is usually wrong here.
+ * Each card is a box that must be tall enough for its longest member, so a row
+ * mixing "$248.55 / Personal wallet" against a bare "0" leaves the short ones
+ * mostly empty; and four bordered boxes read as four unrelated facts when they
+ * are four readings of one account. `MetricStrip` puts them on one plane
+ * divided by hairlines: same information, one object, no holes.
+ *
+ * The divider is a border on the item rather than a `divide-*` utility on the
+ * parent, because these wrap. `divide-x` draws from DOM order and leaves a
+ * stray rule at the start of every wrapped line; a per-item leading border
+ * suppressed at each row start does not.
+ */
+export interface MetricStripProps
+  extends React.HTMLAttributes<HTMLDListElement> {
+  children: React.ReactNode;
+}
+
+const MetricStrip = React.forwardRef<HTMLDListElement, MetricStripProps>(
+  ({ className, children, ...props }, ref) => (
+    <dl
+      ref={ref}
+      className={cn(
+        "grid grid-cols-2 rounded-[var(--radius-lg)] border border-border bg-card shadow-[var(--shadow-card)] sm:grid-cols-4",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </dl>
+  ),
+);
+MetricStrip.displayName = "MetricStrip";
+
+export interface MetricProps extends React.HTMLAttributes<HTMLDivElement> {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  /** The qualifying line: which wallet, which window, what the limit is. */
+  hint?: React.ReactNode;
+  /** Raises the value's tone and shows a pill beside the label. A metric is
+   *  `attention` only when a person has to DO something — not merely when a
+   *  number is zero. */
+  attention?: { tone: StatusTone; label: string };
+}
+
+/**
+ * One reading inside a `MetricStrip`.
+ *
+ * `<dt>` carries the label and `<dd>` the value, so the pair is announced as a
+ * described term rather than as two loose strings — the semantic that makes a
+ * figure legible without the visual grouping.
+ *
+ * The value is `tabular-nums`: these sit in a row and change on a timer, and
+ * proportional digits make the column jitter every time a 1 becomes an 8.
+ */
+const Metric = React.forwardRef<HTMLDivElement, MetricProps>(
+  ({ className, label, value, hint, attention, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        // Leading hairline, DRAWN only where a divider belongs — never drawn
+        // and then suppressed. Stating it as `border-l` plus `border-l-0`
+        // variants puts both in one conflict group, where the winner is decided
+        // by emitted-rule order rather than by intent; that resolved the wrong
+        // way at every breakpoint and left a rule down the start of each row.
+        // `:not(:nth-child(Nn+1))` is the row-start test for the column count
+        // at that breakpoint, so no rule ever contradicts another.
+        //
+        // N is COUPLED to the grid template on `MetricStrip`: 2 columns below
+        // `sm`, 4 from `sm`. A new breakpoint there — `md:grid-cols-3`, say —
+        // needs its `md:[&:not(:nth-child(3n+1))]:border-l` here in the same
+        // change, or the dividers land mid-row at that width.
+        "border-border p-4 sm:p-5",
+        "max-sm:[&:not(:nth-child(2n+1))]:border-l",
+        "sm:[&:not(:nth-child(4n+1))]:border-l",
+        className,
+      )}
+      {...props}
+    >
+      <dt className="flex items-center gap-2 text-muted-foreground text-sm">
+        <span className="truncate">{label}</span>
+        {attention && (
+          <StatusPill tone={attention.tone}>{attention.label}</StatusPill>
+        )}
+      </dt>
+      {/* `truncate`, and a step down until the column is wide enough for the
+          longest figure this strip carries. A balance renders as "$248.55" on a
+          funded account and as "$1,284,003.10" on a busy one, and at four
+          columns the wide case has nowhere to go — it either overflows its cell
+          or pushes the whole strip past the page. */}
+      <dd
+        className={cn(
+          "mt-1 truncate font-semibold text-xl tabular-nums tracking-tight lg:text-2xl",
+          attention?.tone === "danger" && "text-[var(--surface-danger-text)]",
+        )}
+        title={typeof value === "string" ? value : undefined}
+      >
+        {value}
+      </dd>
+      {hint && (
+        // Titled for the same reason the value is: the line truncates, and a
+        // hint is where the qualifying detail lives — which wallet, which
+        // window — so a clipped one is the case most worth recovering.
+        <dd
+          className="mt-0.5 truncate text-[var(--text-dim)] text-xs"
+          title={typeof hint === "string" ? hint : undefined}
+        >
+          {hint}
+        </dd>
+      )}
+    </div>
+  ),
+);
+Metric.displayName = "Metric";
+
+export { Metric, MetricStrip };

package/src/primitives/page-header.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { PageHeader } from "./page-header";
+
+describe("PageHeader", () => {
+  it("renders the title as the page's only h1", () => {
+    render(<PageHeader title="Workflows" />);
+    const headings = screen.getAllByRole("heading", { level: 1 });
+    expect(headings).toHaveLength(1);
+    expect(headings[0]).toHaveTextContent("Workflows");
+  });
+
+  it("steps the title down to h2 for a nested surface", () => {
+    render(<PageHeader level={2} title="Skills" />);
+    expect(screen.queryByRole("heading", { level: 1 })).toBeNull();
+    expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
+      "Skills",
+    );
+  });
+
+  it("puts the id on the heading so a region can point aria-labelledby at it", () => {
+    render(<PageHeader titleId="keys-title" title="API keys" />);
+    expect(screen.getByRole("heading", { level: 1 })).toHaveAttribute(
+      "id",
+      "keys-title",
+    );
+  });
+
+  // The description is prose ABOUT the page, so it must not land in the
+  // heading — a paragraph rendered where a heading goes reads as body copy to a
+  // sighted reader and as the page's accessible name to a screen reader.
+  it("keeps the description out of the heading", () => {
+    render(<PageHeader title="Billing" description="Spend and invoices." />);
+    const heading = screen.getByRole("heading", { level: 1 });
+    expect(heading).toHaveTextContent("Billing");
+    expect(heading).not.toHaveTextContent("Spend and invoices.");
+    expect(screen.getByText("Spend and invoices.")).toBeInTheDocument();
+  });
+
+  it("renders the actions and meta slots when given", () => {
+    render(
+      <PageHeader
+        title="Teams"
+        actions={<button type="button">Invite</button>}
+        meta={<span>4 members</span>}
+      />,
+    );
+    expect(screen.getByRole("button", { name: "Invite" })).toBeInTheDocument();
+    expect(screen.getByText("4 members")).toBeInTheDocument();
+  });
+
+  it("omits the optional slots entirely when not given", () => {
+    const { container } = render(<PageHeader title="Alerts" />);
+    expect(container.querySelector("p")).toBeNull();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+});

package/src/primitives/page-header.tsx

@@ -0,0 +1,86 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * The one masthead every console page opens with.
+ *
+ * A page identifies itself in three separate registers, and each gets its own
+ * slot here so they cannot compete for the same one:
+ *
+ *   - `title` — what the page IS. The `<h1>`, and the only `<h1>`.
+ *   - `description` — one line on what it is for. Prose belongs here, never in
+ *     the title slot: a paragraph rendered where a heading goes reads as body
+ *     copy to a sighted reader and as nothing at all to a screen reader, which
+ *     is how a page ends up with no accessible name.
+ *   - `actions` — what the reader can DO from here, right-aligned and wrapping
+ *     under the title on a narrow viewport rather than squeezing it.
+ *
+ * `meta` is the fourth register and the one most often missing: the small facts
+ * that qualify everything below (a count, a scope, a window). They sit on their
+ * own line under the title so a reader can tell the difference between "this
+ * page has nothing in it" and "this filter matches nothing".
+ *
+ * `titleId` is exposed so a page can point `aria-labelledby` at the heading
+ * from a region further down without minting a second copy of the string.
+ */
+export interface PageHeaderProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  actions?: React.ReactNode;
+  meta?: React.ReactNode;
+  titleId?: string;
+  /** Renders the title one step down for a nested/tab surface. */
+  level?: 1 | 2;
+}
+
+const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
+  (
+    {
+      className,
+      title,
+      description,
+      actions,
+      meta,
+      titleId,
+      level = 1,
+      ...props
+    },
+    ref,
+  ) => {
+    const Heading = level === 1 ? "h1" : "h2";
+    return (
+      <header ref={ref} className={cn("mb-6", className)} {...props}>
+        <div className="flex flex-wrap items-start justify-between gap-x-6 gap-y-3">
+          <div className="min-w-0">
+            <Heading
+              id={titleId}
+              className={cn(
+                "text-balance font-semibold tracking-tight",
+                level === 1 ? "text-2xl" : "text-lg",
+              )}
+            >
+              {title}
+            </Heading>
+            {description && (
+              <p className="mt-1 max-w-prose text-muted-foreground text-sm">
+                {description}
+              </p>
+            )}
+          </div>
+          {actions && (
+            <div className="flex flex-wrap items-center gap-2">{actions}</div>
+          )}
+        </div>
+        {meta && (
+          <div className="mt-3 flex flex-wrap items-center gap-x-4 gap-y-2 text-[var(--text-dim)] text-xs">
+            {meta}
+          </div>
+        )}
+      </header>
+    );
+  },
+);
+PageHeader.displayName = "PageHeader";
+
+export { PageHeader };

package/src/primitives/stat-card.tsx

@@ -58,8 +58,12 @@ const StatCard = React.forwardRef<HTMLDivElement, StatCardProps>(
           <div className="space-y-1">
             <p className="text-muted-foreground text-sm">{title}</p>
             <p className="font-bold text-3xl tracking-tight">{value}</p>
+            {/* A token, never `opacity-70` over the muted tone: a translucent
+                foreground renders as the token COMPOSITED over whatever plane sits
+                behind it, so the same class lands a different colour — and a
+                different contrast ratio — on a card than on the canvas. */}
             {subtitle && (
-              <p className="text-muted-foreground opacity-70 text-xs">{subtitle}</p>
+              <p className="text-[var(--text-dim)] text-xs">{subtitle}</p>
             )}
             {trend && trendStatus && (
               <div