@supertype.ai/foundations 0.1.29 → 0.1.30

package/dist/contrast.js

@@ -131,9 +131,7 @@ export function parseColor(value) {
     }
     const hex = input.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
     if (hex) {
-        const digits = hex[1].length === 3
-            ? [...hex[1]].map((d) => d + d).join("")
-            : hex[1];
+        const digits = hex[1].length === 3 ? [...hex[1]].map((d) => d + d).join("") : hex[1];
         return [
             parseInt(digits.slice(0, 2), 16),
             parseInt(digits.slice(2, 4), 16),
@@ -158,6 +156,47 @@ export function contrast(a, b) {
     const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
     return (hi + 0.05) / (lo + 0.05);
 }
+/**
+ * APCA lightness contrast (Lc), the perceptual measure WCAG 3 is built on.
+ *
+ * It sits beside `contrast` because the two answer different questions and an
+ * ink ramp needs both. A WCAG ratio is polarity-blind: it reports the same
+ * number whether the text is dark on light or light on dark, when in fact dark
+ * glyphs on a bright field thin out and light glyphs on a dark field bloat. That
+ * blindness is what lets a ramp be ordered by ratio and still read flat — viably
+ * shipped a `--muted-foreground` measuring 72.5 Lc in light and 52.1 in dark,
+ * the same verdict from `contrast` on both sides and twenty points apart to a
+ * reader.
+ *
+ * Lc also states the term a ratio cannot: legibility is contrast times size, so
+ * a floor here is what says an ink comfortable at 16px is or is not comfortable
+ * on the 13px rung a dense product actually spends.
+ *
+ * Returned absolute. It is signed by polarity in the specification, and every
+ * caller so far asks "is this legible", never "which way round is it".
+ */
+export function lc(text, background) {
+    // Screen luminance on APCA's own curve, which is not WCAG's: exponent 2.4 on
+    // the raw channel, with weights of its own.
+    const y = ([r, g, b]) => {
+        const v = 0.2126729 * (r / 255) ** 2.4 +
+            0.7151522 * (g / 255) ** 2.4 +
+            0.072175 * (b / 255) ** 2.4;
+        // Soft clamp near black, where the power curve stops modelling perception.
+        return v < 0.022 ? v + (0.022 - v) ** 1.414 : v;
+    };
+    const [yText, yBackground] = [y(text), y(background)];
+    // Two exponent pairs, one per polarity. This asymmetry is the whole reason Lc
+    // says something a ratio cannot.
+    const s = yBackground > yText
+        ? (yBackground ** 0.56 - yText ** 0.57) * 1.14
+        : (yBackground ** 0.65 - yText ** 0.62) * 1.14;
+    // Below the noise floor the two are the same colour as far as a reader is
+    // concerned, and the offset below would report a spurious 2.7.
+    if (Math.abs(s) < 0.1)
+        return 0;
+    return Math.abs(s > 0 ? (s - 0.027) * 100 : (s + 0.027) * 100);
+}
 const INKS = ["--foreground", "--muted-foreground", "--card-foreground"];
 const SURFACES = ["--background", "--card", "--muted"];
 /**
@@ -200,6 +239,16 @@ const FILLS = [
     "--stone",
     "--fig",
     "--cocoa",
+    // A chart series is a mark like any other, and docs/cli.md has always said so
+    // ("a status dot or a chart bar that cannot be picked out of its background").
+    // Leaving them out of this list is how the sand shipped at 2.18:1 in light and
+    // the taupe at 2.26:1 in dark: a promise in prose that nothing measured.
+    "--chart-1",
+    "--chart-2",
+    "--chart-3",
+    "--chart-4",
+    "--chart-5",
+    "--chart-6",
 ];
 /**
  * A fill has to separate from the page and from a card. Not from `--muted`: a
@@ -209,6 +258,7 @@ const FILLS = [
 const FILL_SURFACES = ["--background", "--card"];
 /** The same hues as words, at the bar body copy is held to. */
 const INKS_TINTED = [
+    "--primary-ink",
     "--success-ink",
     "--warn-ink",
     "--info-ink",
@@ -223,14 +273,29 @@ const INKS_TINTED = [
     "--fig-ink",
     "--cocoa-ink",
 ];
+/**
+ * The tertiary ink, at the 3:1 its own comment in theme.css claims for it —
+ * placeholders and disabled labels, never anything load-bearing. Held here
+ * rather than in `INKS` because 4.5:1 would fail a token that is correct; held
+ * *somewhere* because the sentence stating the bar was the only thing enforcing
+ * it, and light sits at 3.14:1 on --muted with nothing watching the gap.
+ */
+const TERTIARY = ["--subtle-foreground"];
 /**
  * shadcn's shape: `-foreground` is the label printed on the fill, so the pair is
  * measured against itself rather than against the page.
+ *
+ * `--success` and `--warn` joined the list when the tone table stopped making
+ * exceptions of them. A filled status control is a real thing, `Button
+ * tone="warn" variant="solid"` renders one, and white on amber measured 2.44:1
+ * on the dark theme for as long as the pair went unnamed here.
  */
 const ON_FILL = [
     ["--primary", "--primary-foreground"],
     ["--secondary", "--secondary-foreground"],
     ["--destructive", "--destructive-foreground"],
+    ["--success", "--success-foreground"],
+    ["--warn", "--warn-foreground"],
     ["--accent", "--accent-foreground"],
     ["--card", "--card-foreground"],
     ["--popover", "--popover-foreground"],
@@ -254,14 +319,63 @@ export function tokenCuts(token) {
         asInk: INKS_TINTED.find((ink) => ink === `${fill}-ink`),
     };
 }
+/**
+ * A hairline is neither ink nor a mark, so neither bar fits: WCAG exempts a
+ * decorative rule outright, and holding one to 3:1 would draw a box, not a
+ * border. What it owes is symmetry — the same rule has to read as the same
+ * weight in both themes, and it did not: the dark hairline was tuned by hand
+ * (L22's 1.34:1 on --card was rejected as too faint) while the light one was
+ * never measured at all and shipped under the value dark had turned down.
+ *
+ * 1.4:1 is that floor, set just under the pair the themes now agree on. Only
+ * --background and --card: a rule inside a `muted` well sits on a surface that
+ * is itself a wash, and 1.3:1 is the practical floor for that kind of well.
+ */
+const HAIRLINES = ["--border", "--input"];
+const HAIRLINE_SURFACES = ["--background", "--card"];
+/**
+ * The sidebar keeps its own pair, because a rule there is drawn on `--sidebar`
+ * and never on the page. Measuring it against `--background` would fail a border
+ * that is correct and pass one that is not.
+ */
+const SIDEBAR_HAIRLINE = [
+    "--sidebar-border",
+    "--sidebar",
+];
+/**
+ * The bar a rule owes, held apart from `checkSignals` because it is not a
+ * signal: nothing here carries meaning in its hue, it only has to be seen.
+ */
+export function checkHairlines(css, { themes = ["light", "dark"] } = {}) {
+    return [
+        ...checkLegibility(css, {
+            inks: HAIRLINES,
+            surfaces: HAIRLINE_SURFACES,
+            minimum: 1.4,
+            themes,
+        }),
+        ...checkLegibility(css, {
+            inks: [SIDEBAR_HAIRLINE[0]],
+            surfaces: [SIDEBAR_HAIRLINE[1]],
+            minimum: 1.4,
+            themes,
+        }),
+    ];
+}
 /**
  * The three bars a palette owes, run over the same engine as `checkLegibility`.
  * Without this the numbers in a theme's comments are claims, not measurements.
  */
 export function checkSignals(css, { themes = ["light", "dark"] } = {}) {
     return [
-        ...checkLegibility(css, { inks: FILLS, surfaces: FILL_SURFACES, minimum: 3, themes }),
+        ...checkLegibility(css, {
+            inks: FILLS,
+            surfaces: FILL_SURFACES,
+            minimum: 3,
+            themes,
+        }),
         ...checkLegibility(css, { inks: INKS_TINTED, themes }),
+        ...checkLegibility(css, { inks: TERTIARY, minimum: 3, themes }),
         ...ON_FILL.flatMap(([fill, label]) => checkLegibility(css, { inks: [label], surfaces: [fill], themes })),
     ];
 }

package/dist/eslint.d.ts

@@ -20,11 +20,27 @@ export declare function colourRules({ accents, }?: ColourOptions): RestrictedSyn
  */
 export declare function themeOverrideRules(): RestrictedSyntax[];
 /**
- * `--muted` is a fill at L92%, so `text-muted` is ~1.1:1 — invisible, and it
- * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
+ * `--muted` is a fill at L92%, so `text-muted` lands at ~1.1:1. Invisible, and
+ * it shipped at 17 sites. `text-background` stays legal: inverse ink is a real
+ * role.
  */
 export declare function surfaceAsInkRules(): RestrictedSyntax[];
 export declare function renamedTokenRules(): RestrictedSyntax[];
+/**
+ * `render={<a href="…" />}` on a component that takes an `href`. It reads as a
+ * styling choice and is a routing one: the cloned anchor skips the router, so
+ * the page fully reloads and the view transition is lost, and an off-site href
+ * never grows a `rel`. Button, Badge and Card each decide internal vs external
+ * from the href itself, so the anchor is never needed and cannot be right more
+ * often than the one shared rule is.
+ *
+ * Narrow on both axes, so it never fires on a line that is correct. Only those
+ * three components — `RailLink` deliberately takes a router element through
+ * `render`, because its module has to stay importable without Next. And only a
+ * bare `<a>`: `render={<Link/>}` is redundant beside `href` but it still routes,
+ * so it is not a bug.
+ */
+export declare function linkRules(): RestrictedSyntax[];
 export interface TypographyOptions {
     /** Three-weight ramp. Off for editorial, where 700 is a register not a shout. */
     weights?: boolean;
@@ -40,7 +56,7 @@ export interface TypographyOptions {
     /**
      * Flag a size class on a primitive that already owns a size axis. Off by
      * default for the same reason as `pairing`: it fails until the consumer has
-     * migrated, and the migration is the point.
+     * migrated, and that migration is the intended end state.
      */
     axis?: boolean;
 }
@@ -48,7 +64,7 @@ export declare function typographyRules({ weights, ramp, pairing, axis, }?: Typo
 /**
  * Every design rule, as one list.
  *
- * The five builders below it are still exported, and spreading them by hand is
+ * The builders below it are still exported, and spreading them by hand is
  * what both consumers were doing — one of them into a flat config, the other
  * into a legacy `.eslintrc`, and *both* of them had quietly left out
  * `renamedTokenRules`, so neither would have flagged a deprecated token name.

package/dist/eslint.js

@@ -39,22 +39,49 @@ export function themeOverrideRules() {
     return rule(`/(^| )dark:(${COLOUR_PREFIX})-(${TOKEN})($| )/`, "A `dark:` override on a token means the token is wrong — fix it in theme.css, where one change covers every call site, rather than here. Alpha variants (dark:bg-destructive/20) stay legal: those tune a wash's density, not the token.");
 }
 /**
- * `--muted` is a fill at L92%, so `text-muted` is ~1.1:1 — invisible, and it
- * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
+ * `--muted` is a fill at L92%, so `text-muted` lands at ~1.1:1. Invisible, and
+ * it shipped at 17 sites. `text-background` stays legal: inverse ink is a real
+ * role.
  */
 export function surfaceAsInkRules() {
     return rule("/(^| )(dark:|hover:|focus:|group-hover:)*text-(muted|card|popover|input)($| )/", "That is a surface token, not an ink — as text it has no defined contrast (text-muted measures ~1.1:1 on a light page). Use text-muted-foreground for secondary ink, text-subtle-foreground for tertiary, or text-card-foreground on a card.");
 }
 /**
  * `-foreground` means the label printed on a fill; `-ink` means the hue as
- * words. `warn-foreground` and the eight categorical `-foreground` tokens were
- * always inks, under the other name. The old spellings still resolve, so nothing
- * breaks on the day of the rename; this is what stops them surviving it.
+ * words. The eight categorical `-foreground` tokens were always inks, under the
+ * other name. The old spellings still resolve, so nothing breaks on the day of
+ * the rename; this is what stops them surviving it.
+ *
+ * `warn` left this list when the status tones gained real on-fill labels:
+ * `--warn-foreground` now means what its name says, the ink printed on the warn
+ * fill, and `Button tone="warn" variant="solid"` is what reads it.
  */
-const RENAMED_INKS = "warn|terracotta|ochre|moss|fern|sage|stone|fig|cocoa";
+const RENAMED_INKS = "terracotta|ochre|moss|fern|sage|stone|fig|cocoa";
 export function renamedTokenRules() {
     return rule(`/(^| )(dark:|hover:|focus:|group-hover:)*(text|bg|border|ring|fill|stroke|decoration)-(${RENAMED_INKS})-foreground($| )/`, "That is the deprecated name for the same hue's `-ink`. In this package `-foreground` is the label printed on a fill and `-ink` is the hue used as words, and none of these hues has a printed-on label — they are checked at 4.5:1 against the page, and printing one on its own fill measures about 1.2:1. Use `-ink`.");
 }
+/**
+ * `render={<a href="…" />}` on a component that takes an `href`. It reads as a
+ * styling choice and is a routing one: the cloned anchor skips the router, so
+ * the page fully reloads and the view transition is lost, and an off-site href
+ * never grows a `rel`. Button, Badge and Card each decide internal vs external
+ * from the href itself, so the anchor is never needed and cannot be right more
+ * often than the one shared rule is.
+ *
+ * Narrow on both axes, so it never fires on a line that is correct. Only those
+ * three components — `RailLink` deliberately takes a router element through
+ * `render`, because its module has to stay importable without Next. And only a
+ * bare `<a>`: `render={<Link/>}` is redundant beside `href` but it still routes,
+ * so it is not a bug.
+ */
+export function linkRules() {
+    return [
+        {
+            selector: 'JSXOpeningElement[name.name=/^(Button|Badge|Card)$/] > JSXAttribute[name.name="render"] > JSXExpressionContainer > JSXElement > JSXOpeningElement[name.name="a"]',
+            message: "Pass `href` instead of rendering an anchor. A cloned <a> bypasses the router (full page load, no view transition) and gets no rel on an off-site href; `href` routes through the package's one rule. `render` is for an element that is not a link.",
+        },
+    ];
+}
 export function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2xs 11 / text-xs 12 / text-sm 14 / text-base 16 and up", pairing = false, axis = false, } = {}) {
     return [
         // Alpha ink composites against whatever surface it lands on, so its
@@ -100,7 +127,7 @@ export function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2x
             ? [
                 {
                     selector: 'JSXElement:has(>JSXOpeningElement[name.name="TypographyP"]) ~ JSXElement > JSXOpeningElement[name.name="TypographyProseList"]',
-                    message: "A ui paragraph over a prose list splits one passage across two rungs. Promote the paragraph with TypographyProse, or drop the list to the paragraph's rung with TypographyList variant=\"ui\".",
+                    message: 'A ui paragraph over a prose list splits one passage across two rungs. Promote the paragraph with TypographyProse, or drop the list to the paragraph\'s rung with TypographyList variant="ui".',
                 },
             ]
             : []),
@@ -113,6 +140,7 @@ export function designRules({ accents, typography = true, ...type } = {}) {
     return [
         ...colourRules({ accents }),
         ...(typography ? typographyRules(type) : []),
+        ...linkRules(),
         ...themeOverrideRules(),
         ...surfaceAsInkRules(),
         ...renamedTokenRules(),
@@ -136,10 +164,7 @@ export function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], ...options } =
             name: "@supertype.ai/foundations/design",
             files,
             rules: {
-                "no-restricted-syntax": [
-                    "error",
-                    ...designRules(options),
-                ],
+                "no-restricted-syntax": ["error", ...designRules(options)],
             },
         },
     ];

package/dist/essay/layout.d.ts

@@ -5,7 +5,7 @@ import type { TocHeading } from "./toc.js";
  * 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

package/dist/essay/layout.js

@@ -6,7 +6,7 @@ import { ReadingRail } from "./reading.js";
  * 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

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/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,3 +1,4 @@
 export { cn } from "./cn.js";
-export { toneClass, impliedTone, type Tone } from "./tone.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,9 +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, and it is the same seven a button has.
+// 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 } from "./tone.js";
+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/tone.d.ts

@@ -30,8 +30,8 @@
  */
 /**
  * `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`.
+ * 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
@@ -47,15 +47,15 @@ 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)]";
+    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(--tint-foreground)] [--tone-hue:var(--brand-ink,var(--primary))]";
+    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(--tint-foreground)] [--tone-hue:var(--success-ink)]";
+    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(--tint-foreground)] [--tone-hue:var(--warn-ink)]";
+    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)]";
 };
@@ -70,9 +70,13 @@ export type Tone = keyof typeof TONE;
  * 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
+ * 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;
@@ -87,6 +91,31 @@ export declare const TONE_SURFACE: string;
  * 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