@supertype.ai/foundations 0.1.27 → 0.1.29

package/dist/essay/layout.d.ts

@@ -1,4 +1,5 @@
 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.
@@ -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,5 +1,6 @@
 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.
@@ -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/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/index.d.ts

@@ -1,2 +1,3 @@
 export { cn } from "./cn.js";
+export { toneClass, impliedTone, type Tone } from "./tone.js";
 export * from "./typography/index.js";

package/dist/index.js

@@ -1,4 +1,9 @@
 export { cn } from "./cn.js";
+// The semantic colour vocabulary. Exported from the root because typography
+// takes it too — a link has a tone, and it is 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 } from "./tone.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/seo.d.ts

@@ -76,9 +76,10 @@ export declare function createSeo(config: SeoConfig): {
                 "@type": string;
                 url: string;
             } | undefined;
-            "@type": string;
             name: string;
             url: string;
+            "@id"?: string | undefined;
+            "@type": string;
         };
         mainEntityOfPage: {
             "@type": string;
@@ -154,9 +155,10 @@ export declare function createSeo(config: SeoConfig): {
                 "@type": string;
                 url: string;
             } | undefined;
-            "@type": string;
             name: string;
             url: string;
+            "@id"?: string | undefined;
+            "@type": string;
         };
         author?: {
             jobTitle?: string | undefined;

package/dist/seo.js

@@ -7,11 +7,6 @@ export function createSeo(config) {
     const { baseUrl, siteName, defaultOgImage, logoUrl, articleBasePath = "notes", publisherUrl, trailingSlash = false, } = config;
     /** Resolves a possibly-relative URL against the site origin. */
     const absolute = (url) => url.startsWith("http") ? url : `${baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
-    /**
-     * Stable `@id` anchors for the site's core entities. Pages reference these
-     * rather than re-declaring an Organization node, so crawlers merge them into
-     * one entity instead of collecting near-duplicates.
-     */
     /**
      * A page route in the shape this site actually serves. A URL already carrying
      * a query, a fragment or a file extension is left alone — only a route gets
@@ -34,10 +29,24 @@ export function createSeo(config) {
             ...(author.jobTitle ? { jobTitle: author.jobTitle } : {}),
         };
     };
+    /**
+     * Stable `@id` anchors for the site's core entities. Pages reference these
+     * rather than re-declaring an Organization node, so crawlers merge them into
+     * one entity instead of collecting near-duplicates.
+     */
     const ORG_ID = `${baseUrl}/#organization`;
     const WEBSITE_ID = `${baseUrl}/#website`;
+    /**
+     * The publisher every Article and WebPage node points at. It carries `@id`
+     * only when the publisher is this site: without one, each page declares a
+     * fresh Organization and a crawler has no way to merge a corpus of them into
+     * the canonical entity the site emits once. A `publisherUrl` naming a
+     * different site gets no `@id` — `ORG_ID` is derived from `baseUrl`, so
+     * stamping it there would claim someone else's publisher as this one.
+     */
     const publisher = {
         "@type": "Organization",
+        ...(!publisherUrl || publisherUrl === baseUrl ? { "@id": ORG_ID } : {}),
         name: siteName,
         url: publisherUrl ?? baseUrl,
         ...(logoUrl

package/dist/tone.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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, and it is not 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)]";
+    /** 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(--tint-foreground)] [--tone-hue:var(--brand-ink,var(--primary))]";
+    /** It worked. */
+    readonly success: "[--tone-fill:var(--success)] [--tone-ink:var(--tint-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(--tint-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.
+ *
+ * `--tone-fill-hover` mixes toward `--foreground` rather than darkening by a
+ * fixed amount, so a filled control deepens on the light theme and lifts on the
+ * dark one from a single declaration. 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;
+/**
+ * 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,111 @@
+/**
+ * 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, and it is not 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)]",
+    /** 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(--tint-foreground)] [--tone-hue:var(--brand-ink,var(--primary))]",
+    /** It worked. */
+    success: "[--tone-fill:var(--success)] [--tone-ink:var(--tint-foreground)] [--tone-hue:var(--success-ink)]",
+    /** A footgun: the reader can still proceed, but not blindly. */
+    warn: "[--tone-fill:var(--warn)] [--tone-ink:var(--tint-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.
+ *
+ * `--tone-fill-hover` mixes toward `--foreground` rather than darkening by a
+ * fixed amount, so a filled control deepens on the light theme and lifts on the
+ * dark one from a single declaration. 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. */
+    "[--tone-wash-hover:color-mix(in_oklab,var(--tone-hue)_18%,transparent)]",
+    /** A filled control under the pointer. */
+    "[--tone-fill-hover:color-mix(in_oklab,var(--tone-fill)_88%,var(--foreground))]",
+].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]}`;
+/**
+ * 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";

package/dist/typography/header.d.ts

@@ -1,5 +1,35 @@
 import { type VariantProps } from "class-variance-authority";
 import { type WithAs } from "./as.js";
+/**
+ * The heading ladder. Four levels, one rung each.
+ *
+ * A heading does not pick its size — `--text-h1`…`--text-h4` in type.css do, and
+ * `.editorial` retunes all four together. That is the whole design: size is a
+ * property of the SURFACE, and level is the only thing a call site knows. When
+ * the rungs were shared with body copy the call site had to know both, which is
+ * how `larger` and `entry` appeared — variants whose entire job was to climb out
+ * of a rung that read fine in the product and landed under the paragraph on a
+ * marketing page. Retuning a surface now means editing two lines of CSS.
+ *
+ * `display` is a role rather than a size: the landing-page heading that has to
+ * outrank the same level in the docs. Size is all it changes — the slant it once
+ * carried turned out to be unwanted on every surface.
+ *
+ * Tailwind scans comments — never spell a class out here or it becomes a real
+ * utility.
+ */
+/**
+ * The heading face, stated once. Anything wearing it composes this rather than
+ * respelling it: a second literal here is a level that forked, and a literal
+ * weight beside the face survives into `.editorial` and synthesises the
+ * single-weight serif. viably asserts there is exactly one of these strings.
+ *
+ * Exported so a non-heading can ask for the face alone. `headingClass()` below is the whole
+ * h2 ramp — face, anchor offset, margin reset, rung — and is right only for something that
+ * IS a heading wearing another tag. A pull quote is not, and took the ramp anyway because
+ * the face had no door, arriving with a `scroll-m-20` for an anchor it does not have.
+ */
+export declare const headingFace = "font-heading font-[number:var(--heading-weight)]";
 declare const h1Variants: (props?: ({
     variant?: "default" | "display" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/typography/header.js

@@ -25,9 +25,14 @@ import { TextAs } from "./as.js";
  * respelling it: a second literal here is a level that forked, and a literal
  * weight beside the face survives into `.editorial` and synthesises the
  * single-weight serif. viably asserts there is exactly one of these strings.
+ *
+ * Exported so a non-heading can ask for the face alone. `headingClass()` below is the whole
+ * h2 ramp — face, anchor offset, margin reset, rung — and is right only for something that
+ * IS a heading wearing another tag. A pull quote is not, and took the ramp anyway because
+ * the face had no door, arriving with a `scroll-m-20` for an anchor it does not have.
  */
-const HEADING_FACE = "font-heading font-[number:var(--heading-weight)]";
-const HEADING_BASE = `scroll-m-20 ${HEADING_FACE} text-foreground`;
+export const headingFace = "font-heading font-[number:var(--heading-weight)]";
+const HEADING_BASE = `scroll-m-20 ${headingFace} text-foreground`;
 const h1Variants = cva(`${HEADING_BASE} tracking-tight`, {
     variants: {
         variant: {

package/dist/typography/highlight.d.ts

@@ -14,10 +14,10 @@ import type { ComponentProps } from "react";
 declare const MARKER_TONES: {
     readonly primary: "var(--primary)";
     readonly success: "var(--success)";
-    readonly ochre: "var(--ochre-foreground)";
-    readonly terracotta: "var(--terracotta-foreground)";
-    readonly sage: "var(--sage-foreground)";
-    readonly fig: "var(--fig-foreground)";
+    readonly ochre: "var(--ochre-ink)";
+    readonly terracotta: "var(--terracotta-ink)";
+    readonly sage: "var(--sage-ink)";
+    readonly fig: "var(--fig-ink)";
 };
 export type HighlightTone = keyof typeof MARKER_TONES;
 /**

package/dist/typography/highlight.js

@@ -15,10 +15,10 @@ import { cn } from "../cn.js";
 const MARKER_TONES = {
     primary: "var(--primary)",
     success: "var(--success)",
-    ochre: "var(--ochre-foreground)",
-    terracotta: "var(--terracotta-foreground)",
-    sage: "var(--sage-foreground)",
-    fig: "var(--fig-foreground)",
+    ochre: "var(--ochre-ink)",
+    terracotta: "var(--terracotta-ink)",
+    sage: "var(--sage-ink)",
+    fig: "var(--fig-ink)",
 };
 /** Wash density at a fraction of the theme's base alpha. */
 const ink = (weight) => `color-mix(in srgb, var(--marker) calc(var(--marker-alpha) * ${weight}), transparent)`;

package/dist/typography/paragraph.d.ts

@@ -1,12 +1,13 @@
 import { type VariantProps } from "class-variance-authority";
 import type { ComponentProps, ReactNode } from "react";
+import { type Tone } from "../tone.js";
 import { type WithAs } from "./as.js";
 /** The body layer: two axes and no more. A paragraph picks a rung and an ink; a
  * caption is always secondary ink and picks a size. `lead` was a third rung a
  * breakpoint away from `prose`, and its standfirst role is now the eyebrow's. */
 declare const pVariants: (props?: ({
     variant?: "ui" | "prose" | null | undefined;
-    tone?: "default" | "muted" | null | undefined;
+    tone?: "muted" | "default" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ParagraphVariants = VariantProps<typeof pVariants>;
 export declare function TypographyP({ className, variant, tone, children, ...props }: ComponentProps<"p"> & ParagraphVariants): import("react").JSX.Element;
@@ -113,21 +114,10 @@ export declare function TypographyStat({ className, size, figures, children, ...
  * optical correction — the mono face carries a taller x-height than the sans.
  */
 export declare function TypographyInlineCode({ className, children, ...props }: ComponentProps<"code">): import("react").JSX.Element;
-/**
- * A statement about the surface, not the link: `foreground` inside a paragraph,
- * `primary` when the link is the point of the line, `secondary` for a note
- * beneath a hero where `primary` would compete with the CTA beside it.
- */
-declare const LINK_TONES: {
-    readonly foreground: "font-medium text-foreground";
-    readonly primary: "font-medium text-primary";
-    readonly secondary: "text-secondary-ink";
-};
-export type LinkTone = keyof typeof LINK_TONES;
 type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & {
     href: string;
     children: ReactNode;
-    tone?: LinkTone;
+    tone?: Tone;
     /** Defaults on for an off-site link. Turn it off for one that starts a flow the reader should stay in. */
     newTab?: boolean;
     /**