@supertype.ai/foundations 0.1.28 → 0.1.30

package/dist/essay/layout.d.ts

@@ -1,10 +1,11 @@
 import type { ComponentProps, ComponentType, ReactNode } from "react";
+import type { TocHeading } from "./toc.js";
 /**
  * Three tracks with the third empty: two would push the prose off-centre the
  * moment an aside appeared, setting body copy on a different axis per page.
  * The measure grows per step — a comfortable line length is a range.
  *
- * The margin track is what the third one buys, and it only exists if the
+ * The margin track is what the third one buys, and appears only where the
  * container can pay for it:
  *
  *   aside = (container − 3rem padding − measure) ÷ 2 − 2.5rem gutter
@@ -24,6 +25,41 @@ import type { ComponentProps, ComponentType, ReactNode } from "react";
 export declare function EssayColumns({ aside, children, className, ...props }: ComponentProps<"div"> & {
     aside?: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * The margin track's contents, pinned as the column scrolls.
+ *
+ * The offset is stated here and nowhere else: it has to clear the same sticky
+ * site nav that `EssaySection`'s `scroll-mt` clears, and two literals a file
+ * apart is how an anchored heading ends up under the chrome that the rail
+ * scrolled it to.
+ */
+export declare function EssayAside({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * The join between a header and the body under it: the one place in the package that draws
+ * it, so a seam cannot be ruled twice by a header and a layout that cannot see each other.
+ *
+ * The rule is for the narrow layout alone. Past `@6xl` the margin rail marks the join, and
+ * the header's own bottom padding is the whole of the gap.
+ */
+export declare function EssayBody({ children, className, }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+/**
+ * The reading column with a scroll-spied rail in its margin: an article whose
+ * body is prose or MDX, rather than the declared sections `EssayLayout` sets.
+ *
+ * The rail is dropped when a piece has no headings, so a short post gets a
+ * centred measure instead of a margin holding an empty nav.
+ */
+export declare function ReadingLayout({ headings, children, className, }: {
+    headings: readonly TocHeading[];
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
 /** A separator between meta items. Decorative, so it is hidden from assistive tech. */
 export declare function MetaDot({ className }: {
     className?: string;

package/dist/essay/layout.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../cn.js";
+import { ReadingRail } from "./reading.js";
 /**
  * Three tracks with the third empty: two would push the prose off-centre the
  * moment an aside appeared, setting body copy on a different axis per page.
  * The measure grows per step — a comfortable line length is a range.
  *
- * The margin track is what the third one buys, and it only exists if the
+ * The margin track is what the third one buys, and appears only where the
  * container can pay for it:
  *
  *   aside = (container − 3rem padding − measure) ÷ 2 − 2.5rem gutter
@@ -25,6 +26,37 @@ import { cn } from "../cn.js";
 export function EssayColumns({ aside, children, className, ...props }) {
     return (_jsx("div", { className: "@container w-full", children: _jsxs("div", { className: cn("mx-auto grid w-full max-w-6xl gap-10 px-6", "@6xl:grid-cols-[1fr_minmax(0,42rem)_1fr] @6xl:gap-0", "@7xl:max-w-7xl @7xl:grid-cols-[1fr_minmax(0,44rem)_1fr]", "@min-[84rem]:max-w-[84rem] @min-[84rem]:grid-cols-[1fr_minmax(0,46rem)_1fr]", className), ...props, children: [_jsx("div", { className: "hidden @6xl:block @6xl:pr-10", children: aside }), _jsx("div", { className: "mx-auto w-full min-w-0 max-w-2xl @6xl:max-w-none", children: children }), _jsx("div", { className: "hidden @6xl:block" })] }) }));
 }
+/**
+ * The margin track's contents, pinned as the column scrolls.
+ *
+ * The offset is stated here and nowhere else: it has to clear the same sticky
+ * site nav that `EssaySection`'s `scroll-mt` clears, and two literals a file
+ * apart is how an anchored heading ends up under the chrome that the rail
+ * scrolled it to.
+ */
+export function EssayAside({ children, className, }) {
+    return _jsx("div", { className: cn("sticky top-24", className), children: children });
+}
+/**
+ * The join between a header and the body under it: the one place in the package that draws
+ * it, so a seam cannot be ruled twice by a header and a layout that cannot see each other.
+ *
+ * The rule is for the narrow layout alone. Past `@6xl` the margin rail marks the join, and
+ * the header's own bottom padding is the whole of the gap.
+ */
+export function EssayBody({ children, className, }) {
+    return (_jsx("div", { className: cn("border-t border-border pt-12 @6xl:border-t-0 @6xl:pt-0", className), children: children }));
+}
+/**
+ * The reading column with a scroll-spied rail in its margin: an article whose
+ * body is prose or MDX, rather than the declared sections `EssayLayout` sets.
+ *
+ * The rail is dropped when a piece has no headings, so a short post gets a
+ * centred measure instead of a margin holding an empty nav.
+ */
+export function ReadingLayout({ headings, children, className, }) {
+    return (_jsx(EssayColumns, { className: cn("pb-16 sm:pb-24", className), aside: headings.length > 0 ? (_jsx(EssayAside, { children: _jsx(ReadingRail, { headings: headings }) })) : undefined, children: _jsx(EssayBody, { children: children }) }));
+}
 /** A separator between meta items. Decorative, so it is hidden from assistive tech. */
 export function MetaDot({ className }) {
     return (_jsx("span", { "aria-hidden": true, className: cn("text-muted-foreground/50", className), children: "\u00B7" }));

package/dist/essay/rail.d.ts

@@ -10,6 +10,16 @@ export declare function RailLink({ active, nested, className, children, render,
     /** A sub-heading under the item above it, indented a step further in. */
     nested?: boolean;
     children: ReactNode;
-    /** Swap the anchor for another link element, e.g. `<Link href={…} />`. */
+    /**
+     * Swap the anchor for another link element, e.g. `<Link href={…} />`.
+     *
+     * The one link in the package that does NOT take an `href` and route it
+     * itself, and deliberately: this module is reached from `contents.tsx`,
+     * `reading.tsx` and `layout.tsx`, which a consumer imports in bare Node and in
+     * a test runner with no Next installed. Importing ../href.ts here would put
+     * `next/link` on that path — test/essay-toc.test.ts is what holds the line.
+     * The rail's own links are `#hash` anchors, which want no router anyway; a
+     * rail of routes passes the router's Link through `render`.
+     */
     render?: ReactElement<ComponentProps<"a">>;
 }): import("react").JSX.Element;

package/dist/essay/reading.d.ts

@@ -12,6 +12,6 @@ export declare function ReadingProgressBar({ className }: {
  * stores, so mounting them together costs one scroll subscription, not two.
  */
 export declare function ReadingRail({ headings, className, }: {
-    headings: TocHeading[];
+    headings: readonly TocHeading[];
     className?: string;
 }): import("react").JSX.Element | null;

package/dist/essay/scroll.js

@@ -1,7 +1,7 @@
 "use client";
 import { useEffect, useState, useSyncExternalStore } from "react";
 /**
- * Reading progress 0→1 from one shared listener: a page mounts both the bar and
+ * Reading progress, 0 to 1, from one shared listener: a page mounts both the bar and
  * the rail, and hook-local state would double every subscription. Reads coalesce
  * to a frame, since `scrollHeight` forces layout.
  */

package/dist/href.d.ts

@@ -0,0 +1,42 @@
+import type { ComponentProps, ReactElement } from "react";
+/**
+ * Where a link goes, decided once.
+ *
+ * This branch — scheme test, router `Link` or plain `<a>`, `rel` on the way out
+ * — was written three times: Card, TypographyLink, and (by omission) every call
+ * site that reached for `render={<a href="…" />}` because the component it was
+ * calling had no `href` of its own. The last of those is the expensive copy: it
+ * looks like a styling escape hatch and is actually a routing decision, made at
+ * the call site, wrongly. A hero CTA written that way full-page-reloads past the
+ * router and drops the view transition, and nothing in the type system says so.
+ *
+ * So components take `href`, not an anchor. `render` stays for what it is for:
+ * an element that is genuinely not an anchor.
+ */
+/** A scheme (`mailto:`, `https:`) means the href leaves the app entirely. */
+export declare function isExternalHref(href: string): boolean;
+export type LinkBehavior = {
+    /** Override the scheme sniff: an absolute URL that is home, or a relative one that is not. */
+    external?: boolean;
+    /**
+     * Defaults on for an http(s) href, off for everything else — `mailto:` and
+     * `tel:` hand off to another app and have no tab to open.
+     */
+    newTab?: boolean;
+};
+/** `Link` requires its own href; as far as a call site here goes it is an anchor. */
+type AnchorComponent = (props: ComponentProps<"a">) => ReactElement | null;
+export type ResolvedLink = {
+    Component: AnchorComponent | "a";
+    /** Spread onto the element: the href, plus `target`/`rel` when it opens away. */
+    props: ComponentProps<"a">;
+    /** For a caller that renders differently for an off-site link — an arrow glyph, an icon. */
+    external: boolean;
+};
+/**
+ * A same-page hash is the one internal href that stays a plain anchor: routing
+ * `#section` through the router asks for a navigation and a view transition to
+ * reach a place the browser can already scroll to.
+ */
+export declare function resolveLink(href: string, { external, newTab }?: LinkBehavior): ResolvedLink;
+export {};

package/dist/href.js

@@ -0,0 +1,63 @@
+import { Link } from "next-view-transitions";
+/**
+ * Where a link goes, decided once.
+ *
+ * This branch — scheme test, router `Link` or plain `<a>`, `rel` on the way out
+ * — was written three times: Card, TypographyLink, and (by omission) every call
+ * site that reached for `render={<a href="…" />}` because the component it was
+ * calling had no `href` of its own. The last of those is the expensive copy: it
+ * looks like a styling escape hatch and is actually a routing decision, made at
+ * the call site, wrongly. A hero CTA written that way full-page-reloads past the
+ * router and drops the view transition, and nothing in the type system says so.
+ *
+ * So components take `href`, not an anchor. `render` stays for what it is for:
+ * an element that is genuinely not an anchor.
+ */
+/** A scheme (`mailto:`, `https:`) means the href leaves the app entirely. */
+export function isExternalHref(href) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(href);
+}
+/**
+ * What a wrong `href` is worth saying out loud.
+ *
+ * A value exported from a `"use client"` module and imported by a server
+ * component arrives as a boundary stub — a function that throws when called —
+ * rather than the string it is in the client bundle. Passing one here read as
+ * `TypeError: href.startsWith is not a function`, which React reported with an
+ * empty stack: no component, no file, and every route in the app failing at once
+ * because the offending link sat in a layout.
+ *
+ * The value is the diagnosis, so it goes in the message. `String()` on that stub
+ * prints the "Attempted to call X() from the server" text React put there, which
+ * names the export and the boundary in one line.
+ */
+function assertHref(href) {
+    if (typeof href === "string")
+        return;
+    const seen = typeof href === "function"
+        ? `a function: ${String(href).replace(/\s+/g, " ").slice(0, 160)}`
+        : `${typeof href}: ${JSON.stringify(href)}`;
+    throw new TypeError(`href must be a string, and this one is ${seen}. A function here is usually ` +
+        `a value exported from a "use client" module and imported by a server ` +
+        `component, which crosses the boundary as a stub rather than a string. ` +
+        `Move the constant to a plain module and import it from both sides.`);
+}
+/**
+ * A same-page hash is the one internal href that stays a plain anchor: routing
+ * `#section` through the router asks for a navigation and a view transition to
+ * reach a place the browser can already scroll to.
+ */
+export function resolveLink(href, { external, newTab } = {}) {
+    assertHref(href);
+    const leavesApp = external ?? isExternalHref(href);
+    const away = leavesApp && (newTab ?? href.startsWith("http"));
+    const inPage = !leavesApp && href.startsWith("#");
+    return {
+        Component: leavesApp || inPage ? "a" : Link,
+        props: {
+            href,
+            ...(away ? { target: "_blank", rel: "noopener noreferrer" } : {}),
+        },
+        external: leavesApp,
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export { cn } from "./cn.js";
+export { toneClass, impliedTone, INK_ON_FILL, inkOnSurface, type Tone, } from "./tone.js";
+export { resolveLink, isExternalHref, type LinkBehavior, type ResolvedLink, } from "./href.js";
 export * from "./typography/index.js";

package/dist/index.js

@@ -1,4 +1,13 @@
 export { cn } from "./cn.js";
+// The semantic colour vocabulary. Exported from the root because typography
+// takes it too: a link has a tone, drawn from the same seven a button has.
+// `toneClass` only: the raw table and its derived half used to ship separately,
+// and the order they were combined in was load-bearing.
+export { toneClass, impliedTone, INK_ON_FILL, inkOnSurface, } from "./tone.js";
+// Where an href goes, for the rare call site that styles someone else's element
+// and cannot render a Card/Button/TypographyLink — the same pairing with
+// `buttonVariants`. Prefer passing `href` to a component over calling this.
+export { resolveLink, isExternalHref, } from "./href.js";
 export * from "./typography/index.js";
 // NOTE: blocks, the MDX map, and the Shiki plugin are all deliberately absent
 // from this barrel.

package/dist/mdx.d.ts

@@ -1,9 +1,30 @@
-import type { ComponentProps } from "react";
+import { type ComponentProps, type ReactNode } from "react";
 import { Disclosure, DisclosureGroup } from "./blocks/accordion.js";
 import { Callout } from "./blocks/callout.js";
 import { Card, Cards } from "./blocks/card.js";
 import { Step, Steps } from "./blocks/steps.js";
-import { TabGroup, Tab } from "./blocks/tabs.js";
+/**
+ * `<Tabs items={["npm","pnpm"]}>` with a `<Tab>` per panel: the shape an MDX author
+ * writes, and the only place in the package that speaks it.
+ *
+ * Children pair with `items` **by position**, since a caller writing markdown has no
+ * value to bind. `value` on a `<Tab>` is for the author's eye and is not matched —
+ * matching it would silently drop a panel the moment a label was edited. The label is
+ * the value here, so the strip still survives a reorder.
+ *
+ * This lived in `TabGroup` and made `TabGroup` unusable everywhere else: an app has data,
+ * not positional children, so every one of them rebuilt the adapter by hand. Positional
+ * children are an authoring convenience, not a component API, so they stop here.
+ */
+declare function MdxTabs({ items, children }: {
+    items: string[];
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** `value` names the panel at the call site; it is not used for matching. */
+declare function MdxTab({ children }: {
+    value?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
  * Rendered from markdown syntax, so there is no call site and no knob — a knob
  * here is one every project turns differently. Headings carry variants and this
@@ -19,8 +40,8 @@ export declare const proseMdxComponents: {
     Accordions: typeof DisclosureGroup;
     Accordion: typeof Disclosure;
     Banner: (props: ComponentProps<typeof Callout>) => import("react").JSX.Element;
-    Tabs: typeof TabGroup;
-    Tab: typeof Tab;
+    Tabs: typeof MdxTabs;
+    Tab: typeof MdxTab;
     Steps: typeof Steps;
     Step: typeof Step;
     h1: (props: ComponentProps<"h1">) => import("react").JSX.Element;
@@ -45,3 +66,4 @@ export declare const proseMdxComponents: {
     th: (props: ComponentProps<"th">) => import("react").JSX.Element;
     td: (props: ComponentProps<"td">) => import("react").JSX.Element;
 };
+export {};

package/dist/mdx.js

@@ -1,4 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Children } from "react";
 import { TypographyH1, TypographyH2, TypographyH3, TypographyH4, } from "./typography/header.js";
 import { cn } from "./cn.js";
 import Image from "next/image";
@@ -6,8 +7,33 @@ import { Disclosure, DisclosureGroup } from "./blocks/accordion.js";
 import { Callout } from "./blocks/callout.js";
 import { Card, Cards } from "./blocks/card.js";
 import { Step, Steps } from "./blocks/steps.js";
-import { TabGroup, Tab } from "./blocks/tabs.js";
+import { TabGroup } from "./blocks/tabs.js";
 import { TypographyProse, TypographyProseList, TypographyLink, } from "./typography/paragraph.js";
+/**
+ * `<Tabs items={["npm","pnpm"]}>` with a `<Tab>` per panel: the shape an MDX author
+ * writes, and the only place in the package that speaks it.
+ *
+ * Children pair with `items` **by position**, since a caller writing markdown has no
+ * value to bind. `value` on a `<Tab>` is for the author's eye and is not matched —
+ * matching it would silently drop a panel the moment a label was edited. The label is
+ * the value here, so the strip still survives a reorder.
+ *
+ * This lived in `TabGroup` and made `TabGroup` unusable everywhere else: an app has data,
+ * not positional children, so every one of them rebuilt the adapter by hand. Positional
+ * children are an authoring convenience, not a component API, so they stop here.
+ */
+function MdxTabs({ items, children }) {
+    const panels = Children.toArray(children);
+    return (_jsx(TabGroup, { tabs: items.map((label, i) => ({
+            value: label,
+            label,
+            content: panels[i],
+        })) }));
+}
+/** `value` names the panel at the call site; it is not used for matching. */
+function MdxTab({ children }) {
+    return _jsx(_Fragment, { children: children });
+}
 /**
  * Rendered from markdown syntax, so there is no call site and no knob — a knob
  * here is one every project turns differently. Headings carry variants and this
@@ -26,8 +52,8 @@ export const proseMdxComponents = {
     Accordions: DisclosureGroup,
     Accordion: Disclosure,
     Banner: (props) => (_jsx(Callout, { density: "editorial", ...props })),
-    Tabs: TabGroup,
-    Tab,
+    Tabs: MdxTabs,
+    Tab: MdxTab,
     Steps,
     Step,
     h1: (props) => (_jsx(TypographyH1, { variant: "display", ...props })),

package/dist/tone.d.ts

@@ -0,0 +1,130 @@
+/**
+ * One semantic colour vocabulary, for every component that carries meaning in a
+ * hue: Button, Callout, TypographyLink. Before this there were three lists —
+ * Callout's `muted`, TypographyLink's `foreground` and a button's `default` were
+ * three spellings of "no meaning at all", and `accent` named `--accent` on a
+ * button and `--primary` in a callout.
+ *
+ * A component that wants a tone does not get to invent a name for one.
+ *
+ * Seven tones, seven tokens, one to one. That is the test for admitting a new
+ * one: `muted` is `--muted`, `warn` is `--warn`, and a proposed tone with no
+ * token of its own is a second name for a tone that already has one. It is what
+ * ruled out `neutral` (no such token, and `muted` is the word the rest of the
+ * package already uses — `--muted-foreground`, `TypographyMuted`,
+ * `TypographyP tone="muted"`), `accent` (that is `--primary`'s hover tint, so a
+ * washed `primary` renders the same control), and `info` (a real token, but
+ * `success | warn | destructive` is already the complete good/careful/bad
+ * triad, and nothing in either app had ever reached for a fourth).
+ *
+ * The rule the package already applies to every tinted role holds here too, and
+ * is why each row names three values rather than one: `--tone-fill` is a surface,
+ * `--tone-ink` is the label printed on it, and `--tone-hue` is the same colour
+ * used as words. A fill is a mark and clears 3:1; an ink is read and clears
+ * 4.5:1. Tuning one value to do both jobs sinks whichever job it was not tuned
+ * for. `checkSignals` in /contrast is the test.
+ *
+ * Custom properties rather than thirty-five class strings: a tone declares, a
+ * component spends. `Button` has five variants and `Callout` two densities, and
+ * neither has a per-tone branch anywhere in it.
+ */
+/**
+ * `muted` is the only row that names a fourth value. A hairline derived from the
+ * ink at 45% is right for a hue and wrong for the absence of one. `--border` is
+ * the tuned answer there, in place of a wash of `--foreground`.
+ *
+ * Its hue is `--foreground` rather than `--muted-foreground` on purpose. `muted`
+ * says the control carries no meaning, not that it carries less contrast — a
+ * cancel button beside a save button is quiet because it is not filled in, and
+ * its label still has to be read.
+ *
+ * `brand` is the consumer's own identity, and the only row whose token the
+ * package does not define. It falls back to `--primary`, so an app that has no
+ * identity hue of its own gets its principal one — the tone stays meaningful
+ * everywhere rather than rendering nothing in the apps that skipped it.
+ */
+export declare const TONE: {
+    /** No meaning: chrome, toolbars, anything that must not compete. */
+    readonly muted: "[--tone-fill:var(--muted)] [--tone-ink:var(--foreground)] [--tone-hue:var(--foreground)] [--tone-line:var(--border)]";
+    /** The principal action, and the package's default wherever a tone is optional. */
+    readonly primary: "[--tone-fill:var(--primary)] [--tone-ink:var(--primary-foreground)] [--tone-hue:var(--primary-ink,var(--primary))]";
+    /** The warm accent. `--secondary-ink` is its readable cut; the fill is not. */
+    readonly secondary: "[--tone-fill:var(--secondary)] [--tone-ink:var(--secondary-foreground)] [--tone-hue:var(--secondary-ink)]";
+    /** The consumer's identity hue, if it defined one. Otherwise the principal one. */
+    readonly brand: "[--tone-fill:var(--brand,var(--primary))] [--tone-ink:var(--brand-foreground,var(--primary-foreground))] [--tone-hue:var(--brand-ink,var(--primary-ink,var(--primary)))]";
+    /** It worked. */
+    readonly success: "[--tone-fill:var(--success)] [--tone-ink:var(--success-foreground)] [--tone-hue:var(--success-ink)]";
+    /** A footgun: the reader can still proceed, but not blindly. */
+    readonly warn: "[--tone-fill:var(--warn)] [--tone-ink:var(--warn-foreground)] [--tone-hue:var(--warn-ink)]";
+    /** It deletes something, or it already failed. */
+    readonly destructive: "[--tone-fill:var(--destructive)] [--tone-ink:var(--destructive-foreground)] [--tone-hue:var(--destructive)]";
+};
+export type Tone = keyof typeof TONE;
+/**
+ * What every tone is worth once mixed, derived once here rather than eight times
+ * above. Declared before `TONE` in any class list, so `neutral` can override
+ * `--tone-line`.
+ *
+ * Expressed as variables rather than through Tailwind's `/10` modifier because
+ * the modifier's support for arbitrary custom properties is a moving target,
+ * while `color-mix` is what the modifier compiles to anyway — the same CSS, one
+ * layer less of trust.
+ *
+ * A hover moves the fill 18% toward `--hover-toward`, the extreme theme.css
+ * points away from the page: black on latte, white on espresso. The token
+ * carries the direction and the percentage carries the state. Mixing toward
+ * `--foreground` instead made the step as long as the gap between the fill and
+ * the ink, so a `primary` button moved 4.9 ΔL* on latte against 6.2 on espresso
+ * and read as no hover at all. Every tone now clears 6 ΔL* in both themes,
+ * measured in test/composition.test.ts. A `dark:` override here is what the
+ * package's own ESLint rule exists to prevent.
+ */
+export declare const TONE_SURFACE: string;
+/**
+ * A tone, as one class list. This is the only thing a component should need.
+ *
+ * It was two — `cn(TONE_SURFACE, TONE[tone])` — and the order was load-bearing
+ * in a way nothing enforced: the derived values have to be declared first so
+ * `muted` can override `--tone-line` with `--border`. Getting that backwards
+ * gave every quiet control a hairline washed out of its own ink, and the only
+ * thing standing between a caller and that bug was a comment. Two arguments
+ * whose order matters and whose values always travel together is one argument.
+ */
+export declare const toneClass: (tone: Tone) => string;
+/**
+ * The ink a nested element inherits, declared by whatever painted the surface
+ * under it. Two properties, one rule: paint a background, hand down its ink.
+ *
+ * `toneClass` alone is a palette, not a surface — a `Callout` spends the same
+ * seven values as a filled `Button` and tints at 5%, so the words inside it
+ * still sit on the page and still want the page's ink. Only a component that
+ * actually fills promotes `--tone-ink` to the inherited ink, and the type
+ * primitives read it with the page as their fallback. A tint that promotes
+ * nothing is therefore correct by default, which is the failure this replaces:
+ * `TypographyLabel` pinned `text-foreground`, won over the `text-primary-foreground`
+ * on the anchor around it, and printed 2.34:1 on a filled button.
+ *
+ * `--ink-muted` collapses to the ink itself, because a hue fill has no second
+ * rung: mixing the ink 20% toward `--primary` measures 4.22:1 on the
+ * espresso theme and 3.49:1 at 30%. Nothing on a filled control may be quieter
+ * than its label. Wanting two rungs is wanting a tinted surface.
+ */
+export declare const INK_ON_FILL = "[--ink:var(--tone-ink)] [--ink-muted:var(--tone-ink)]";
+/**
+ * The same contract for a surface the tones do not name: `--card`, `--popover`,
+ * a sidebar. These are tints of the page rather than hues, so both rungs
+ * survive and the pair is stated rather than collapsed.
+ */
+export declare const inkOnSurface: (ink: string, muted?: string) => string;
+/**
+ * What an unstated tone means, given how much ink the component is spending.
+ * Shared, because `Button` and `Badge` both need it and two copies of a default
+ * is how two components come to disagree about what saying nothing means.
+ *
+ * Filling a control in is how a page says *this is the action*, so a filled one
+ * with nothing else stated is the principal one; anything less is chrome until a
+ * call site says otherwise. Measured, not assumed: 244 of the 246 buttons across
+ * both apps that name a variant name `outline` or `ghost`, and every one wants
+ * the page's own ink.
+ */
+export declare const impliedTone: (variant: string | null | undefined) => Tone;

package/dist/tone.js

@@ -0,0 +1,140 @@
+/**
+ * One semantic colour vocabulary, for every component that carries meaning in a
+ * hue: Button, Callout, TypographyLink. Before this there were three lists —
+ * Callout's `muted`, TypographyLink's `foreground` and a button's `default` were
+ * three spellings of "no meaning at all", and `accent` named `--accent` on a
+ * button and `--primary` in a callout.
+ *
+ * A component that wants a tone does not get to invent a name for one.
+ *
+ * Seven tones, seven tokens, one to one. That is the test for admitting a new
+ * one: `muted` is `--muted`, `warn` is `--warn`, and a proposed tone with no
+ * token of its own is a second name for a tone that already has one. It is what
+ * ruled out `neutral` (no such token, and `muted` is the word the rest of the
+ * package already uses — `--muted-foreground`, `TypographyMuted`,
+ * `TypographyP tone="muted"`), `accent` (that is `--primary`'s hover tint, so a
+ * washed `primary` renders the same control), and `info` (a real token, but
+ * `success | warn | destructive` is already the complete good/careful/bad
+ * triad, and nothing in either app had ever reached for a fourth).
+ *
+ * The rule the package already applies to every tinted role holds here too, and
+ * is why each row names three values rather than one: `--tone-fill` is a surface,
+ * `--tone-ink` is the label printed on it, and `--tone-hue` is the same colour
+ * used as words. A fill is a mark and clears 3:1; an ink is read and clears
+ * 4.5:1. Tuning one value to do both jobs sinks whichever job it was not tuned
+ * for. `checkSignals` in /contrast is the test.
+ *
+ * Custom properties rather than thirty-five class strings: a tone declares, a
+ * component spends. `Button` has five variants and `Callout` two densities, and
+ * neither has a per-tone branch anywhere in it.
+ */
+/**
+ * `muted` is the only row that names a fourth value. A hairline derived from the
+ * ink at 45% is right for a hue and wrong for the absence of one. `--border` is
+ * the tuned answer there, in place of a wash of `--foreground`.
+ *
+ * Its hue is `--foreground` rather than `--muted-foreground` on purpose. `muted`
+ * says the control carries no meaning, not that it carries less contrast — a
+ * cancel button beside a save button is quiet because it is not filled in, and
+ * its label still has to be read.
+ *
+ * `brand` is the consumer's own identity, and the only row whose token the
+ * package does not define. It falls back to `--primary`, so an app that has no
+ * identity hue of its own gets its principal one — the tone stays meaningful
+ * everywhere rather than rendering nothing in the apps that skipped it.
+ */
+export const TONE = {
+    /** No meaning: chrome, toolbars, anything that must not compete. */
+    muted: "[--tone-fill:var(--muted)] [--tone-ink:var(--foreground)] [--tone-hue:var(--foreground)] [--tone-line:var(--border)]",
+    /** The principal action, and the package's default wherever a tone is optional. */
+    primary: "[--tone-fill:var(--primary)] [--tone-ink:var(--primary-foreground)] [--tone-hue:var(--primary-ink,var(--primary))]",
+    /** The warm accent. `--secondary-ink` is its readable cut; the fill is not. */
+    secondary: "[--tone-fill:var(--secondary)] [--tone-ink:var(--secondary-foreground)] [--tone-hue:var(--secondary-ink)]",
+    /** The consumer's identity hue, if it defined one. Otherwise the principal one. */
+    brand: "[--tone-fill:var(--brand,var(--primary))] [--tone-ink:var(--brand-foreground,var(--primary-foreground))] [--tone-hue:var(--brand-ink,var(--primary-ink,var(--primary)))]",
+    /** It worked. */
+    success: "[--tone-fill:var(--success)] [--tone-ink:var(--success-foreground)] [--tone-hue:var(--success-ink)]",
+    /** A footgun: the reader can still proceed, but not blindly. */
+    warn: "[--tone-fill:var(--warn)] [--tone-ink:var(--warn-foreground)] [--tone-hue:var(--warn-ink)]",
+    /** It deletes something, or it already failed. */
+    destructive: "[--tone-fill:var(--destructive)] [--tone-ink:var(--destructive-foreground)] [--tone-hue:var(--destructive)]",
+};
+/**
+ * What every tone is worth once mixed, derived once here rather than eight times
+ * above. Declared before `TONE` in any class list, so `neutral` can override
+ * `--tone-line`.
+ *
+ * Expressed as variables rather than through Tailwind's `/10` modifier because
+ * the modifier's support for arbitrary custom properties is a moving target,
+ * while `color-mix` is what the modifier compiles to anyway — the same CSS, one
+ * layer less of trust.
+ *
+ * A hover moves the fill 18% toward `--hover-toward`, the extreme theme.css
+ * points away from the page: black on latte, white on espresso. The token
+ * carries the direction and the percentage carries the state. Mixing toward
+ * `--foreground` instead made the step as long as the gap between the fill and
+ * the ink, so a `primary` button moved 4.9 ΔL* on latte against 6.2 on espresso
+ * and read as no hover at all. Every tone now clears 6 ΔL* in both themes,
+ * measured in test/composition.test.ts. A `dark:` override here is what the
+ * package's own ESLint rule exists to prevent.
+ */
+export const TONE_SURFACE = [
+    /** A hairline, or a rule carrying the tone. */
+    "[--tone-line:color-mix(in_oklab,var(--tone-hue)_45%,transparent)]",
+    /** A panel's tint: large area, so barely there. */
+    "[--tone-veil:color-mix(in_oklab,var(--tone-hue)_5%,transparent)]",
+    /** A control's tint at rest. */
+    "[--tone-wash:color-mix(in_oklab,var(--tone-hue)_10%,transparent)]",
+    /** The same control under the pointer: twice the tint, so the step reads. */
+    "[--tone-wash-hover:color-mix(in_oklab,var(--tone-hue)_20%,transparent)]",
+    /** A filled control under the pointer. */
+    "[--tone-fill-hover:color-mix(in_oklab,var(--tone-fill),var(--hover-toward)_18%)]",
+].join(" ");
+/**
+ * A tone, as one class list. This is the only thing a component should need.
+ *
+ * It was two — `cn(TONE_SURFACE, TONE[tone])` — and the order was load-bearing
+ * in a way nothing enforced: the derived values have to be declared first so
+ * `muted` can override `--tone-line` with `--border`. Getting that backwards
+ * gave every quiet control a hairline washed out of its own ink, and the only
+ * thing standing between a caller and that bug was a comment. Two arguments
+ * whose order matters and whose values always travel together is one argument.
+ */
+export const toneClass = (tone) => `${TONE_SURFACE} ${TONE[tone]}`;
+/**
+ * The ink a nested element inherits, declared by whatever painted the surface
+ * under it. Two properties, one rule: paint a background, hand down its ink.
+ *
+ * `toneClass` alone is a palette, not a surface — a `Callout` spends the same
+ * seven values as a filled `Button` and tints at 5%, so the words inside it
+ * still sit on the page and still want the page's ink. Only a component that
+ * actually fills promotes `--tone-ink` to the inherited ink, and the type
+ * primitives read it with the page as their fallback. A tint that promotes
+ * nothing is therefore correct by default, which is the failure this replaces:
+ * `TypographyLabel` pinned `text-foreground`, won over the `text-primary-foreground`
+ * on the anchor around it, and printed 2.34:1 on a filled button.
+ *
+ * `--ink-muted` collapses to the ink itself, because a hue fill has no second
+ * rung: mixing the ink 20% toward `--primary` measures 4.22:1 on the
+ * espresso theme and 3.49:1 at 30%. Nothing on a filled control may be quieter
+ * than its label. Wanting two rungs is wanting a tinted surface.
+ */
+export const INK_ON_FILL = "[--ink:var(--tone-ink)] [--ink-muted:var(--tone-ink)]";
+/**
+ * The same contract for a surface the tones do not name: `--card`, `--popover`,
+ * a sidebar. These are tints of the page rather than hues, so both rungs
+ * survive and the pair is stated rather than collapsed.
+ */
+export const inkOnSurface = (ink, muted = "--muted-foreground") => `[--ink:var(${ink})] [--ink-muted:var(${muted})]`;
+/**
+ * What an unstated tone means, given how much ink the component is spending.
+ * Shared, because `Button` and `Badge` both need it and two copies of a default
+ * is how two components come to disagree about what saying nothing means.
+ *
+ * Filling a control in is how a page says *this is the action*, so a filled one
+ * with nothing else stated is the principal one; anything less is chrome until a
+ * call site says otherwise. Measured, not assumed: 244 of the 246 buttons across
+ * both apps that name a variant name `outline` or `ghost`, and every one wants
+ * the page's own ink.
+ */
+export const impliedTone = (variant) => variant == null || variant === "solid" ? "primary" : "muted";