@supertype.ai/foundations 0.1.28 → 0.1.30

package/README.md

@@ -4,8 +4,9 @@
 [![npm](https://img.shields.io/npm/v/%40supertype.ai%2Ffoundations?logo=npm&color=cb3837)](https://www.npmjs.com/package/@supertype.ai/foundations)
 [![license](https://img.shields.io/npm/l/%40supertype.ai%2Ffoundations?color=blue)](LICENSE)
 
-[The foundations philosophy](https://supertypeai.github.io/foundations/philosophy/) lays out the Raison d'être better, but the crux is that it is a reusable design system that binds typography primitives, content blocks, the long-form essay shell, the token and theme CSS, and the build-time tooling that keep baseline quality high (SEO, OG cards, lint rules, contrast
-checks) in a single package. Used by Supertype's own projects like [Viably work operating system](https://viably.app) and [supertype.ai](https://supertype.ai), it is also MIT-licensed and available for any Next.js 15+ project built atop Tailwind and Shadcn.
+[The foundations philosophy](https://supertypeai.github.io/foundations/philosophy/) explains the reasoning in more detail, but the short version is simple: this is a reusable design system for typography primitives, content blocks, the long-form essay shell, token and theme CSS, and the build-time tooling that keeps the baseline consistent. That includes SEO, OG cards, lint rules, and contrast checks.
+
+It is used in Supertype projects like [Viably work operating system](https://viably.app) and [supertype.ai](https://supertype.ai), and it is MIT-licensed for any Next.js 15+ app built on Tailwind and Shadcn.
 
 ```sh
 yarn add @supertype.ai/foundations
@@ -31,11 +32,11 @@ yarn example:install   # once, to install Next, the peers and the package
 yarn example           # then open http://localhost:3000
 ```
 
-[`examples/site`](examples/site) renders every component along with the code, and include whole-page [recipes](examples/site/app/_recipes) to copy into your project. Comes with the `dark` and `.editorial` switches.
+[`examples/site`](examples/site) renders every component with the code next to it, and includes whole-page [recipes](examples/site/app/_recipes) you can copy into your project. It also includes the `dark` and `.editorial` switches.
 
 ## Initialization and Diagnostics
 
-This package also ships a CLI that writes the CSS for you and checks the rest:
+This package includes a CLI that writes the CSS for you and checks the rest:
 
 ```sh
 npx @supertype.ai/foundations init      # edits your CSS entry, prints the rest
@@ -43,7 +44,7 @@ npx @supertype.ai/foundations doctor    # checks this app against everything bel
 ```
 
 `init` edits one file: the CSS entry that imports Tailwind. It adds the imports
-you are missing and reorders anything that is out of place. Run it with `--dry-run` first to see the patch. Everything else it prints for you to paste (the font binding, and the `llms.txt` lines for a coding agent).
+you are missing and reorders anything that is out of place. Run it with `--dry-run` first to preview the patch. Everything else it prints for you to paste is the font binding and the `llms.txt` lines for a coding agent.
 
 The steps performed by `init` are written out below anyway. See [the CLI](docs/cli.md) for the full list of checks and details.
 
@@ -59,13 +60,13 @@ Peers are React 19+, Next 15+, `next-view-transitions` 0.3+ and `@base-ui/react`
 <details>
 <summary>Installing from a git tag instead</summary>
 
-Every release is tagged as well as published, so a commit can be installed
-directly — useful for trying an unreleased fix. Pin a tag, never `#main`: an
-untagged git dependency re-resolves to a different commit on any fresh install.
+Every release is tagged and published, so a commit can be installed directly
+when you want to try an unreleased fix. Pin a tag rather than `#main`: an
+untagged git dependency resolves to a different commit on a fresh install.
 
 ```jsonc
 // package.json
-"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.28"
+"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.30"
 ```
 
 </details>
@@ -85,15 +86,16 @@ untagged git dependency re-resolves to a different commit on any fresh install.
 ```
 
 **The `@source` line is required.** Tailwind does not scan `node_modules` by
-default, so without it every class is purged and the components
-render with no styles at all.
+default, so without it the package&rsquo;s classes get purged and the
+components render without styles.
 
-**`theme.css` is required.** `tokens.css` names the colour roles; `theme.css` is
-what gives them values. Without it color utility can't be resolved, so the page renders unpainted with no error. It also carries
-`--secondary-ink`, `--subtle-foreground`, the four earth tones the marker
-highlight uses, and the `accordion-down` and `accordion-up` keyframes. Skip it
-only if you declare every role yourself; `foundations doctor` fails when neither
-is true.
+**`theme.css` is required.** `tokens.css` names the colour roles, and
+`theme.css` gives them values. Without it, the colour utilities cannot be
+resolved, so the page renders unpainted without an obvious error. It also
+carries `--secondary-ink`, `--subtle-foreground`, the four earth tones used
+for marker highlights, and the `accordion-down` and `accordion-up` keyframes.
+Skip it only if you declare every role yourself; `foundations doctor` fails if
+neither path is true.
 
 ### 3. Bind the fonts
 
@@ -112,8 +114,10 @@ const serif = Average({ variable: "--font-average", weight: "400", subsets: ["la
 <html className={`${sans.variable} ${mono.variable} ${serif.variable} font-sans`}>
 ```
 
-**Bind with `.variable`, never `.className`.** A className sets `font-family` on
-the element itself and leaves the roles unresolved, causing a mismatch where the page renders one typeface while every `font-sans` and `font-heading` utility on it renders another.
+**Bind with `.variable`, never `.className`.** A className sets `font-family`
+on the element itself and leaves the roles unresolved, which causes a mismatch
+where the page renders one typeface while the `font-sans` and `font-heading`
+utilities render another.
 
 ### 4. Check the wiring
 
@@ -213,9 +217,9 @@ only from this package, so you can paste it into your app and it compiles.
 
 ## For coding agents
 
-The package ships an `llms.txt` with the public API, the rules, and the mistakes
-that do not produce an error. Point your agent at it once and it stops
-hand-writing `text-sm text-muted-foreground` where a primitive exists:
+The package includes an `llms.txt` with the public API, the rules, and the
+mistakes that do not produce an error. Point your agent at it once and it stops
+writing `text-sm text-muted-foreground` where a primitive already exists:
 
 ```md
 <!-- CLAUDE.md, AGENTS.md, or your agent's equivalent -->
@@ -233,7 +237,7 @@ package.
 | import                                                                | contains                                                                 | docs                                         |
 | --------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
 | `@supertype.ai/foundations`                                           | all typography primitives, `cn`                                          | [Typography](docs/typography.md)             |
-| `@supertype.ai/foundations/blocks`                                    | `Card`, `Callout`, `Steps`, `Tabs`, `Accordion`, `Disclosure`, `SEGMENT` | [Blocks](docs/blocks.md)                     |
+| `@supertype.ai/foundations/blocks`                                    | `Button`, `Badge`, `Card`, `Callout`, `Steps`, `TabGroup`, `Accordion`, `SEGMENT` | [Blocks](docs/blocks.md)                     |
 | `@supertype.ai/foundations/mdx`                                       | `proseMdxComponents` — the MDX element map                               | [In MDX](docs/blocks.md#in-mdx)              |
 | `@supertype.ai/foundations/essay`                                     | the long-form shell, TOC, reading rail, post meta                        | [Essay](docs/essay.md)                       |
 | `@supertype.ai/foundations/seo`                                       | `createSeo(...)` — metadata + JSON-LD                                    | [Tooling](docs/tooling.md#seo-and-og-images) |

package/bin/foundations.mjs

@@ -518,9 +518,9 @@ const checkContrast = async (appRoot) => {
   const cssFile = findCssEntry(appRoot);
   if (!cssFile) return out;
 
-  let checkLegibility, checkSignals, formatFailures;
+  let checkLegibility, checkSignals, checkHairlines, formatFailures;
   try {
-    ({ checkLegibility, checkSignals, formatFailures } = await import(
+    ({ checkLegibility, checkSignals, checkHairlines, formatFailures } = await import(
       join(pkgRoot, "dist/contrast.js")
     ));
   } catch {
@@ -533,6 +533,9 @@ const checkContrast = async (appRoot) => {
   const groups = [
     ["error", "structural ink below 4.5:1", checkLegibility(css)],
     ["warn", "mark or tinted ink below its bar", checkSignals(css)],
+    // A rule owes no WCAG bar, so this can never be an error. It is here because
+    // an app that retints --border almost always retints one theme.
+    ["warn", "hairline too faint to read as a rule", checkHairlines(css)],
   ];
 
   for (const [level, title, failures] of groups) {

package/dist/blocks/accordion.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Children, cloneElement, isValidElement } from "react";
 import { cn } from "../cn.js";
+import { inkOnSurface } from "../tone.js";
 /**
  * A disclosure group: `<details>`/`<summary>`, no JS, correct before hydration.
  *
@@ -55,5 +56,5 @@ function deriveGroupName(children) {
     return `accordion-${(hash >>> 0).toString(36)}`;
 }
 export function Disclosure({ title, children, className, ...props }) {
-    return (_jsxs("details", { className: cn("group bg-card", className), ...props, children: [_jsxs("summary", { className: "flex cursor-pointer list-none items-center justify-between gap-4 px-4 py-3 text-sm font-medium text-foreground marker:hidden hover:bg-accent [&::-webkit-details-marker]:hidden", children: [title, _jsx("svg", { "aria-hidden": "true", className: "h-4 w-4 shrink-0 text-muted-foreground transition-transform group-open:rotate-180", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "m6 9 6 6 6-6" }) })] }), _jsx("div", { className: "px-4 pb-4 text-sm text-muted-foreground", children: children })] }));
+    return (_jsxs("details", { className: cn("group bg-card", inkOnSurface("--card-foreground"), className), ...props, children: [_jsxs("summary", { className: "flex cursor-pointer list-none items-center justify-between gap-4 px-4 py-3 text-sm font-medium text-foreground marker:hidden hover:bg-accent [&::-webkit-details-marker]:hidden", children: [title, _jsx("svg", { "aria-hidden": "true", className: "h-4 w-4 shrink-0 text-muted-foreground transition-transform group-open:rotate-180", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: "m6 9 6 6 6-6" }) })] }), _jsx("div", { className: "px-4 pb-4 text-sm text-muted-foreground", children: children })] }));
 }

package/dist/blocks/badge.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentProps, ReactElement } from "react";
+import { type VariantProps } from "class-variance-authority";
+import { type LinkBehavior } from "../href.js";
+declare const badge: (props?: ({
+    tone?: "muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive" | null | undefined;
+    size?: "sm" | "xs" | null | undefined;
+    pill?: boolean | null | undefined;
+    variant?: "solid" | "soft" | "outline" | "ghost" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type BadgeLook = VariantProps<typeof badge>;
+export declare function badgeVariants(props?: Parameters<typeof badge>[0]): string;
+/**
+ * A `span`, an anchor when given an `href` — a tag pill leading to its listing —
+ * and whatever `render` says otherwise — cloned rather than run through a
+ * `useRender` hook, which is what viably's badge did. A hook would make every
+ * badge in the tree a client component to serve the one call site that renders
+ * an anchor, and a badge is a label: it should cost nothing on the server. This
+ * is the same mechanism `Button` uses for the same reason.
+ *
+ * The `[a]:hover` rules above light up on their own when an anchor is the parent
+ * or the rendered element.
+ */
+export declare function Badge({ className, variant, tone, size, pill, render, href, external, newTab, ...props }: ComponentProps<"span"> & BadgeLook & LinkBehavior & {
+    render?: ReactElement;
+    href?: string;
+}): import("react").JSX.Element;
+export {};

package/dist/blocks/badge.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cva } from "class-variance-authority";
+import { cn } from "../cn.js";
+import { renderAs } from "./render-as.js";
+import { resolveLink } from "../href.js";
+import { FOCUS_RING } from "./focus.js";
+import { INK_ON_FILL, TONE, TONE_SURFACE, impliedTone } from "../tone.js";
+// ---------------------------------------------------------------------------
+// A label that is not a control. Same two axes as Button, and for the same
+// reason: the two apps had each grown their own list, and the lists disagreed
+// with each other and with the rest of the package.
+//
+// ssite's read `default | secondary | destructive | outline | success | warning
+// | supertype | tint`. Two of those are the package's tones under invented
+// spellings — `warning` for `warn`, `supertype` for `brand` — which is precisely
+// the second vocabulary a design system exists to prevent. `secondary` was
+// `bg-muted/80 text-foreground` against a `default` of `bg-muted
+// text-muted-foreground`: a distinction no reader could name, let alone use.
+//
+// viably's read `default | secondary | destructive | outline | ghost | link`,
+// which is a copy of the button list it was cargo-culted from — including the
+// `link` variant, which no badge has ever used, because a badge is not a link.
+//
+// So: `variant` for how much ink, `tone` for what it means, both spelled exactly
+// as Button spells them. `link` is absent because it was never real; everything
+// else about the vocabulary is the same list, so knowing one component's axes is
+// knowing this one's.
+// ---------------------------------------------------------------------------
+const badge = cva(cn("inline-flex w-fit shrink-0 items-center justify-center gap-1", "overflow-hidden border border-transparent font-medium whitespace-nowrap", cn("transition focus-visible:border-ring", FOCUS_RING), "aria-invalid:border-destructive aria-invalid:ring-destructive/20", "[&>svg]:pointer-events-none [&>svg]:size-3!", TONE_SURFACE), {
+    // Same cascade order as Button: `pill` beats `size` on radius.
+    variants: {
+        tone: TONE,
+        /**
+         * Two rungs, because a badge has two jobs. `sm` is the label riding beside
+         * a title; `xs` is the figure riding beside a toolbar control — a filter
+         * tally, an unread count.
+         *
+         * `leading-none` restates the default on purpose: `text-3xs` carries a
+         * line-height of its own, which lands after the base class and wins.
+         * Stating it per size is what keeps `!leading-none` out of call sites.
+         */
+        size: {
+            xs: "h-4 min-w-4 rounded px-1 text-3xs leading-none",
+            sm: "h-5 rounded-md px-2 py-0.5 text-xs leading-none",
+        },
+        pill: { true: "rounded-full", false: "" },
+        variant: {
+            solid: `bg-(--tone-fill) text-(color:--tone-ink) [a]:hover:bg-(--tone-fill-hover) ${INK_ON_FILL}`,
+            soft: "bg-(--tone-wash) text-(color:--tone-hue) [a]:hover:bg-(--tone-wash-hover)",
+            outline: "border-(color:--tone-line) text-(color:--tone-hue) [a]:hover:bg-(--tone-wash)",
+            ghost: "text-(color:--tone-hue) hover:bg-(--tone-wash)",
+        },
+    },
+    defaultVariants: { variant: "solid", size: "sm", pill: false },
+});
+export function badgeVariants(props = {}) {
+    return badge({ tone: props?.tone ?? impliedTone(props?.variant), ...props });
+}
+/**
+ * A `span`, an anchor when given an `href` — a tag pill leading to its listing —
+ * and whatever `render` says otherwise — cloned rather than run through a
+ * `useRender` hook, which is what viably's badge did. A hook would make every
+ * badge in the tree a client component to serve the one call site that renders
+ * an anchor, and a badge is a label: it should cost nothing on the server. This
+ * is the same mechanism `Button` uses for the same reason.
+ *
+ * The `[a]:hover` rules above light up on their own when an anchor is the parent
+ * or the rendered element.
+ */
+export function Badge({ className, variant, tone, size, pill, render, href, external, newTab, ...props }) {
+    const resolved = tone ?? impliedTone(variant);
+    const classes = cn(badge({ variant, tone: resolved, size, pill, className }));
+    const marks = {
+        "data-slot": "badge",
+        "data-variant": variant ?? "solid",
+        "data-tone": resolved,
+    };
+    if (href !== undefined) {
+        const { Component, props: link } = resolveLink(href, { external, newTab });
+        return (_jsx(Component, { ...marks, ...link, className: classes, ...props }));
+    }
+    const as = renderAs(render, classes, { ...marks, ...props });
+    if (as)
+        return as;
+    return _jsx("span", { ...marks, className: classes, ...props });
+}

package/dist/blocks/button.d.ts

@@ -0,0 +1,32 @@
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { type VariantProps } from "class-variance-authority";
+import { type LinkBehavior } from "../href.js";
+declare const button: (props?: ({
+    tone?: "muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive" | null | undefined;
+    size?: "sm" | "xs" | "md" | "lg" | "xl" | null | undefined;
+    icon?: boolean | null | undefined;
+    pill?: boolean | null | undefined;
+    variant?: "link" | "solid" | "soft" | "outline" | "ghost" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type ButtonLook = VariantProps<typeof button>;
+/**
+ * The class list, for the handful of places that style someone else's element
+ * and cannot render a `Button` — a router `Link` inside a `not-found`, a
+ * calendar day cell. Takes the same props, including the implied tone.
+ */
+export declare function buttonVariants(props?: Parameters<typeof button>[0]): string;
+/**
+ * `href` makes the button a link — the anchor is the button, and where the href
+ * goes is ../href.ts's decision, not the call site's. `render={<a href="…" />}`
+ * did this before, and got a bare anchor: no router, so a CTA reloaded the page
+ * and lost the view transition, and an off-site href never grew a `rel`.
+ *
+ * Either way a non-`<button>` element bypasses the primitive on purpose: Base UI
+ * always stamps `type="button"` or `role="button"`, and the latter drops an
+ * anchor out of screen-reader link navigation. `render` remains for an element
+ * that is genuinely neither — a `<label>`, a menu item.
+ */
+export declare function Button({ className, variant, tone, size, icon, pill, render, nativeButton, href, external, newTab, ...props }: ButtonPrimitive.Props & ButtonLook & LinkBehavior & {
+    href?: string;
+}): import("react").JSX.Element;
+export {};

package/dist/blocks/button.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { isValidElement } from "react";
+import { Button as ButtonPrimitive } from "@base-ui/react/button";
+import { cva } from "class-variance-authority";
+import { cn } from "../cn.js";
+import { renderAs } from "./render-as.js";
+import { resolveLink } from "../href.js";
+import { FOCUS_RING } from "./focus.js";
+import { INK_ON_FILL, TONE, TONE_SURFACE, impliedTone } from "../tone.js";
+// ---------------------------------------------------------------------------
+// The control both apps were re-declaring. viably and ssite each carried their
+// own `cva` with its own variant list — `default | secondary | accent |
+// destructive | ghost | outline | link` in one, the same names minus two plus a
+// `rose` in the other — and the two had already drifted on radius, on height,
+// and on what `destructive` even means (a solid red fill in ssite, a tinted wash
+// in viably).
+//
+// The fix is not a longer shared list. Those names answer two questions at once:
+//
+//   variant — how much ink the button spends. Filled, washed, hairline, bare.
+//   tone    — what the ink means. See ../tone.ts; Callout and TypographyLink
+//             take the same seven, because a component does not get to invent a
+//             name for a colour the package has already named. Its default is
+//             the one the variant implies — see `impliedTone`.
+//
+// `destructive` is a tone. `ghost` is a variant. A list holding both can only
+// express the pairs someone thought to add, which is why neither app could write
+// a quiet destructive button without a className.
+//
+// Everything else is a modifier, and both are boolean because both have exactly
+// two states: `icon` squares the box, `pill` rounds it off. They compose — a
+// round icon button is `icon pill` — which is why they are not one `shape` enum.
+// ---------------------------------------------------------------------------
+const button = cva(cn("inline-flex shrink-0 cursor-pointer items-center justify-center", "border border-transparent bg-clip-padding font-medium whitespace-nowrap", "transition select-none", 
+// The border joins the ring where a control has one; the ring itself is shared.
+cn(FOCUS_RING, "focus-visible:border-ring"), "active:not-aria-[haspopup]:translate-y-px", "disabled:pointer-events-none disabled:opacity-50", "aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20", "[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", TONE_SURFACE), {
+    // Key order is cascade order: `cva` emits these as declared and `cn` resolves
+    // a conflict in favour of the last one written. `pill` therefore beats
+    // `size` on radius, and `variant` beats `size` on the box — which is what
+    // lets `link` shed the height and padding of whatever size it was given.
+    // Reordering this object is a visual change.
+    variants: {
+        tone: TONE,
+        /**
+         * One ladder, 24px to 40px on a 4px step. `md` is the product default —
+         * dense rows of controls beside a table — and `lg`/`xl` the marketing
+         * rungs. `--radius-lg` is 10px and theme.css already labels it "buttons,
+         * default control"; the two rungs below borrow `md`, because a 10px radius
+         * on a 24px box reads as a lozenge.
+         */
+        size: {
+            xs: "h-6 gap-1 rounded-md px-2 text-xs [&_svg:not([class*='size-'])]:size-3",
+            sm: "h-7 gap-1 rounded-md px-2.5 text-[0.8rem] [&_svg:not([class*='size-'])]:size-3.5",
+            md: "h-8 gap-1.5 rounded-lg px-3 text-sm",
+            lg: "h-9 gap-2 rounded-lg px-4 text-sm",
+            xl: "h-10 gap-2 rounded-lg px-6 text-sm",
+        },
+        /** A square box for a lone glyph, on whichever rung you are already on. No second ladder of `icon-sm` names to keep aligned with the first. */
+        icon: { true: "px-0", false: "" },
+        /** Full-round corners. Marketing surfaces; also every filter chip. */
+        pill: { true: "rounded-full", false: "" },
+        variant: {
+            solid: `bg-(--tone-fill) text-(color:--tone-ink) hover:bg-(--tone-fill-hover) ${INK_ON_FILL}`,
+            soft: "bg-(--tone-wash) text-(color:--tone-hue) hover:bg-(--tone-wash-hover)",
+            outline: "border-(color:--tone-line) bg-background text-(color:--tone-hue) hover:bg-(--tone-wash)",
+            ghost: "text-(color:--tone-hue) hover:bg-(--tone-wash)",
+            // No box of its own: a button that reads as a link has to sit on the
+            // text baseline, not on a 32px control's centre line.
+            link: "h-auto gap-1 rounded-none px-0 py-0 text-(color:--tone-hue) underline-offset-4 hover:underline",
+        },
+    },
+    compoundVariants: [
+        { icon: true, size: "xs", class: "size-6" },
+        { icon: true, size: "sm", class: "size-7" },
+        { icon: true, size: "md", class: "size-8" },
+        { icon: true, size: "lg", class: "size-9" },
+        { icon: true, size: "xl", class: "size-10" },
+    ],
+    defaultVariants: {
+        variant: "solid",
+        size: "md",
+        icon: false,
+        pill: false,
+    },
+});
+/**
+ * The class list, for the handful of places that style someone else's element
+ * and cannot render a `Button` — a router `Link` inside a `not-found`, a
+ * calendar day cell. Takes the same props, including the implied tone.
+ */
+export function buttonVariants(props = {}) {
+    return button({ tone: props?.tone ?? impliedTone(props?.variant), ...props });
+}
+/**
+ * `href` makes the button a link — the anchor is the button, and where the href
+ * goes is ../href.ts's decision, not the call site's. `render={<a href="…" />}`
+ * did this before, and got a bare anchor: no router, so a CTA reloaded the page
+ * and lost the view transition, and an off-site href never grew a `rel`.
+ *
+ * Either way a non-`<button>` element bypasses the primitive on purpose: Base UI
+ * always stamps `type="button"` or `role="button"`, and the latter drops an
+ * anchor out of screen-reader link navigation. `render` remains for an element
+ * that is genuinely neither — a `<label>`, a menu item.
+ */
+export function Button({ className, variant, tone, size, icon, pill, render, nativeButton, href, external, newTab, ...props }) {
+    const resolved = tone ?? impliedTone(variant);
+    const classes = cn(button({ variant, tone: resolved, size, icon, pill, className }));
+    // The resolved axes, stamped: a child can style off its parent's tone, and a
+    // test can assert the ramp without asserting a class string.
+    const marks = {
+        "data-slot": "button",
+        "data-variant": variant ?? "solid",
+        "data-tone": resolved,
+    };
+    if (href !== undefined) {
+        const { Component, props: link } = resolveLink(href, { external, newTab });
+        return (_jsx(Component, { ...marks, ...link, className: classes, ...props }));
+    }
+    // `render.type !== "button"`: a plain <button/> still goes through the primitive, which
+    // is what supplies the native semantics.
+    const as = isValidElement(render) && render.type === "button"
+        ? null
+        : renderAs(render, classes, { ...marks, ...props });
+    if (as)
+        return as;
+    return (_jsx(ButtonPrimitive, { ...marks, className: classes, render: render, nativeButton: nativeButton ?? true, ...props }));
+}

package/dist/blocks/callout.d.ts

@@ -1,41 +1,5 @@
 import type { ComponentType, ReactNode } from "react";
-declare const TONE: {
-    /** The default: an explanation, not a problem. */
-    readonly muted: {
-        readonly box: "border-border bg-muted/40";
-        readonly title: "text-foreground";
-        readonly icon: "text-muted-foreground";
-        readonly rail: "bg-border";
-    };
-    /** Something failed and the reader needs to see that it did. */
-    readonly destructive: {
-        readonly box: "border-destructive/40 bg-destructive/5";
-        readonly title: "text-destructive";
-        readonly icon: "text-destructive";
-        readonly rail: "bg-destructive/60";
-    };
-    /** A prerequisite or a footgun: the reader can still proceed, but not blindly. */
-    readonly warn: {
-        readonly box: "border-warn/25 bg-warn/5";
-        readonly title: "text-warn-ink";
-        readonly icon: "text-warn";
-        readonly rail: "bg-warn/60";
-    };
-    /** A detail that rewards the reader rather than warning them. */
-    readonly accent: {
-        readonly box: "border-primary/25 bg-primary/5";
-        readonly title: "text-foreground";
-        readonly icon: "text-primary";
-        readonly rail: "bg-primary/60";
-    };
-};
-/**
- * Two densities, because this notice serves two ramps. `compact` is the product
- * default (12px title over 12px body, no rail) that the relay sheet and the contact
- * record already render. `editorial` is the docs form: body copy at reading size,
- * and a 3px accent rail carrying the tone so the surface itself can stay quiet.
- * Splitting on a prop rather than forking the component is the point of the file.
- */
+import { type Tone } from "../tone.js";
 export declare function Callout({ icon: Icon, title, tone, density, bodyClassName, action, children, className, }: {
     /** Injected, so the package needs no icon set. Optional: a notice whose title already reads as a label
      *  ("Replied into Norman's thread") gains nothing from a glyph beside it. */
@@ -43,7 +7,7 @@ export declare function Callout({ icon: Icon, title, tone, density, bodyClassNam
         className?: string;
     }>;
     title?: ReactNode;
-    tone?: keyof typeof TONE;
+    tone?: Tone;
     density?: "compact" | "editorial";
     /** For the one body that is not prose — a raw delivery error, which needs mono and its own
      *  line breaks preserved. */
@@ -54,4 +18,3 @@ export declare function Callout({ icon: Icon, title, tone, density, bodyClassNam
     children: ReactNode;
     className?: string;
 }): import("react").JSX.Element;
-export {};

package/dist/blocks/callout.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../cn.js";
+import { toneClass } from "../tone.js";
 import { TypographyCaption, TypographyLabel, TypographyMuted, TypographySmall, } from "../typography/paragraph.js";
 // ---------------------------------------------------------------------------
 // An inline notice: a titled paragraph that explains something the surface it sits in cannot say
@@ -15,47 +16,21 @@ import { TypographyCaption, TypographyLabel, TypographyMuted, TypographySmall, }
 // that just happened; these are quiet, permanent explanations sitting inside a panel, and they
 // must not announce themselves to a screen reader every time a sheet opens.
 // ---------------------------------------------------------------------------
-const TONE = {
-    /** The default: an explanation, not a problem. */
-    muted: {
-        box: "border-border bg-muted/40",
-        title: "text-foreground",
-        icon: "text-muted-foreground",
-        rail: "bg-border",
-    },
-    /** Something failed and the reader needs to see that it did. */
-    destructive: {
-        box: "border-destructive/40 bg-destructive/5",
-        title: "text-destructive",
-        icon: "text-destructive",
-        rail: "bg-destructive/60",
-    },
-    /** A prerequisite or a footgun: the reader can still proceed, but not blindly. */
-    warn: {
-        box: "border-warn/25 bg-warn/5",
-        title: "text-warn-ink",
-        icon: "text-warn",
-        rail: "bg-warn/60",
-    },
-    /** A detail that rewards the reader rather than warning them. */
-    accent: {
-        box: "border-primary/25 bg-primary/5",
-        title: "text-foreground",
-        icon: "text-primary",
-        rail: "bg-primary/60",
-    },
-};
 /**
- * Two densities, because this notice serves two ramps. `compact` is the product
- * default (12px title over 12px body, no rail) that the relay sheet and the contact
- * record already render. `editorial` is the docs form: body copy at reading size,
- * and a 3px accent rail carrying the tone so the surface itself can stay quiet.
- * Splitting on a prop rather than forking the component is the point of the file.
+ * No tone table of its own: the same seven `Button` and `TypographyLink` take.
+ * The four hand-tuned rows this file used to carry are gone, `accent` among them
+ * — it was `--primary` under another name, which is why a "tip" callout and a
+ * "primary" one were indistinguishable. `muted` keeps its name and its values.
+ * See ../tone.ts.
+ *
+ * A callout is a panel, so it tints with `--tone-veil` (5%) where a control uses
+ * `--tone-wash` (10%). That is the only thing this file knows about colour.
  */
+const BOX = "border-(color:--tone-line) bg-(--tone-veil)";
 export function Callout({ icon: Icon, title, tone = "muted", density = "compact", bodyClassName, action, children, className, }) {
-    const t = TONE[tone];
+    const toned = toneClass(tone);
     if (density === "editorial") {
-        return (_jsx("div", { className: cn("relative overflow-hidden rounded-lg border py-3.5 pl-5 pr-4", t.box, className), children: _jsxs("div", { className: "flex items-start gap-2.5", children: [Icon && _jsx(Icon, { className: cn("mt-0.5 size-4 shrink-0", t.icon) }), _jsxs("div", { className: "flex min-w-0 flex-col gap-1", children: [title && (_jsx(TypographyLabel, { className: t.title, children: title })), _jsx(TypographyMuted, { className: cn("leading-relaxed", bodyClassName), children: children }), action && (_jsx("div", { className: "mt-1 flex items-center gap-1", children: action }))] })] }) }));
+        return (_jsxs("div", { className: cn("relative overflow-hidden rounded-lg border py-3.5 pl-5 pr-4", toned, BOX, className), children: [_jsx("span", { "aria-hidden": true, className: "absolute inset-y-0 left-0 w-[3px] bg-(--tone-line)" }), _jsxs("div", { className: "flex items-start gap-2.5", children: [Icon && (_jsx(Icon, { className: "mt-0.5 size-4 shrink-0 text-(color:--tone-hue)" })), _jsxs("div", { className: "flex min-w-0 flex-col gap-1", children: [title && (_jsx(TypographyLabel, { className: "text-(color:--tone-hue)", children: title })), _jsx(TypographyMuted, { className: cn("leading-relaxed", bodyClassName), children: children }), action && (_jsx("div", { className: "mt-1 flex items-center gap-1", children: action }))] })] })] }));
     }
-    return (_jsxs("div", { className: cn("rounded-md border p-3", t.box, className), children: [title && (_jsxs(TypographySmall, { className: cn("flex items-center gap-1.5 font-medium", t.title), children: [Icon && _jsx(Icon, { className: cn("size-3.5 shrink-0", t.icon) }), title] })), _jsx(TypographyCaption, { className: cn("mt-1 block leading-relaxed", bodyClassName), children: children }), action && _jsx("div", { className: "mt-2 flex items-center gap-1", children: action })] }));
+    return (_jsxs("div", { className: cn("rounded-md border p-3", toned, BOX, className), children: [title && (_jsxs(TypographySmall, { className: "flex items-center gap-1.5 font-medium text-(color:--tone-hue)", children: [Icon && _jsx(Icon, { className: "size-3.5 shrink-0" }), title] })), _jsx(TypographyCaption, { className: cn("mt-1 block leading-relaxed", bodyClassName), children: children }), action && _jsx("div", { className: "mt-2 flex items-center gap-1", children: action })] }));
 }

package/dist/blocks/card.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps, ReactNode } from "react";
+import { type LinkBehavior } from "../href.js";
 /** Two columns from `sm` up: a pair reads as a set rather than two panels. */
 export declare function Cards({ className, children, ...props }: ComponentProps<"div">): import("react").JSX.Element;
 export declare function CardHeader({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
@@ -18,17 +19,15 @@ type CardShorthand = {
     title?: ReactNode;
     description?: ReactNode;
     icon?: ReactNode;
-    /** Override the scheme sniff: an absolute URL home, or a relative one away. */
-    external?: boolean;
 };
 /**
  * Takes either shape: `title`/`href` fills the header, or compose the slots
  * directly. Unrecognised props pass through — MDX authors reach for the whole
- * HTML surface. An href with a scheme leaves the app; the rest route through
- * the router's Link.
+ * HTML surface. Where the href goes is ../href.ts's call, the same one Button
+ * and TypographyLink make.
  */
-export declare function Card({ href, className, external, title, description, icon, children, ...rest }: CardShorthand & {
+export declare function Card({ href, className, external, newTab, title, description, icon, children, ...rest }: CardShorthand & LinkBehavior & {
     href?: string;
     children?: ReactNode;
-} & Omit<ComponentProps<"a">, keyof CardShorthand | "href" | "children">): import("react").JSX.Element;
+} & Omit<ComponentProps<"a">, keyof CardShorthand | keyof LinkBehavior | "href" | "children">): import("react").JSX.Element;
 export {};