@supertype.ai/foundations 0.1.30 → 0.1.32

package/README.md

@@ -66,7 +66,7 @@ untagged git dependency resolves to a different commit on a fresh install.
 
 ```jsonc
 // package.json
-"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.30"
+"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.32"
 ```
 
 </details>

package/dist/blocks/accordion.js

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

package/dist/blocks/anchor.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentProps } from "react";
+import { type LinkBehavior } from "../href.js";
+/**
+ * An anchor whose destination is this package's decision rather than the call
+ * site's — and nothing else.
+ *
+ * `Button`, `Badge`, `Card` and `TypographyLink` all take an `href` and hand it
+ * to ../href.ts. What was left over was every anchor that is none of those: a
+ * thumbnail, a chip, a tooltip trigger, a footer row, an icon in a dialog
+ * header. One consumer had thirty-six, each writing `target="_blank"
+ * rel="noopener noreferrer"` out by hand, five of them missing the `rel`, four
+ * of them putting the pair on a router `Link` — which asks for a client
+ * navigation and a new tab in the same breath.
+ *
+ * No styling, deliberately. `TypographyLink` is the inline link and brings a
+ * weight, an ink and an underline with it, which is why it could not take these:
+ * they wrap something already drawn, and the only thing they have in common is
+ * where they go.
+ *
+ * Pass `external` for a same-origin path that is not a route — an `/api/…`
+ * redirect, a file endpoint. `Link` prefetches on viewport entry, so a signed-URL
+ * endpoint would mint one for a link nobody clicked. Call-site props land after
+ * the resolved ones, so a link needing a `rel` of its own can still say so.
+ */
+export declare function Anchor({ href, external, newTab, ...props }: Omit<ComponentProps<"a">, "href"> & LinkBehavior & {
+    href: string;
+}): import("react").JSX.Element;

package/dist/blocks/anchor.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { resolveLink } from "../href.js";
+/**
+ * An anchor whose destination is this package's decision rather than the call
+ * site's — and nothing else.
+ *
+ * `Button`, `Badge`, `Card` and `TypographyLink` all take an `href` and hand it
+ * to ../href.ts. What was left over was every anchor that is none of those: a
+ * thumbnail, a chip, a tooltip trigger, a footer row, an icon in a dialog
+ * header. One consumer had thirty-six, each writing `target="_blank"
+ * rel="noopener noreferrer"` out by hand, five of them missing the `rel`, four
+ * of them putting the pair on a router `Link` — which asks for a client
+ * navigation and a new tab in the same breath.
+ *
+ * No styling, deliberately. `TypographyLink` is the inline link and brings a
+ * weight, an ink and an underline with it, which is why it could not take these:
+ * they wrap something already drawn, and the only thing they have in common is
+ * where they go.
+ *
+ * Pass `external` for a same-origin path that is not a route — an `/api/…`
+ * redirect, a file endpoint. `Link` prefetches on viewport entry, so a signed-URL
+ * endpoint would mint one for a link nobody clicked. Call-site props land after
+ * the resolved ones, so a link needing a `rel` of its own can still say so.
+ */
+export function Anchor({ href, external, newTab, ...props }) {
+    const { Component, props: link } = resolveLink(href, { external, newTab });
+    return _jsx(Component, { ...link, ...props });
+}

package/dist/blocks/badge.d.ts

@@ -23,5 +23,7 @@ export declare function badgeVariants(props?: Parameters<typeof badge>[0]): stri
 export declare function Badge({ className, variant, tone, size, pill, render, href, external, newTab, ...props }: ComponentProps<"span"> & BadgeLook & LinkBehavior & {
     render?: ReactElement;
     href?: string;
+    /** A link that is not a navigation. See Button, which documents the pairing with `external`. */
+    download?: ComponentProps<"a">["download"];
 }): import("react").JSX.Element;
 export {};

package/dist/blocks/button.d.ts

@@ -1,3 +1,4 @@
+import { type ComponentProps } from "react";
 import { Button as ButtonPrimitive } from "@base-ui/react/button";
 import { type VariantProps } from "class-variance-authority";
 import { type LinkBehavior } from "../href.js";
@@ -6,7 +7,7 @@ declare const button: (props?: ({
     size?: "sm" | "xs" | "md" | "lg" | "xl" | null | undefined;
     icon?: boolean | null | undefined;
     pill?: boolean | null | undefined;
-    variant?: "link" | "solid" | "soft" | "outline" | "ghost" | null | undefined;
+    variant?: "solid" | "link" | "soft" | "outline" | "ghost" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ButtonLook = VariantProps<typeof button>;
 /**
@@ -28,5 +29,17 @@ export declare function buttonVariants(props?: Parameters<typeof button>[0]): st
  */
 export declare function Button({ className, variant, tone, size, icon, pill, render, nativeButton, href, external, newTab, ...props }: ButtonPrimitive.Props & ButtonLook & LinkBehavior & {
     href?: string;
+    /**
+     * The one anchor attribute the `href` branch has to name itself. A download
+     * is a link that is not a navigation, so it is the case `href` alone cannot
+     * express — and `render={<a download />}`, which is how every call site said
+     * it before, is exactly what `linkRules()` now flags. Card already takes it,
+     * off `ComponentProps<"a">`; Button and Badge are anchors here too.
+     *
+     * Pair it with `external` for a same-origin route. `Link` steps aside on the
+     * click, but it still prefetches the href on viewport entry, which for an
+     * export endpoint means running the export to throw the rows away.
+     */
+    download?: ComponentProps<"a">["download"];
 }): import("react").JSX.Element;
 export {};

package/dist/blocks/button.js

@@ -62,7 +62,7 @@ cn(FOCUS_RING, "focus-visible:border-ring"), "active:not-aria-[haspopup]:transla
         variant: {
             solid: `bg-(--tone-fill) text-(color:--tone-ink) hover:bg-(--tone-fill-hover) ${INK_ON_FILL}`,
             soft: "bg-(--tone-wash) text-(color:--tone-hue) hover:bg-(--tone-wash-hover)",
-            outline: "border-(color:--tone-line) bg-background text-(color:--tone-hue) hover:bg-(--tone-wash)",
+            outline: "border-(color:--tone-line) text-(color:--tone-hue) hover:bg-(--tone-wash)",
             ghost: "text-(color:--tone-hue) hover:bg-(--tone-wash)",
             // No box of its own: a button that reads as a link has to sit on the
             // text baseline, not on a 32px control's centre line.

package/dist/blocks/callout.js

@@ -12,6 +12,10 @@ import { TypographyCaption, TypographyLabel, TypographyMuted, TypographySmall, }
 // already drifted on the radius. Hand-rolled type styles are also exactly what the project's own
 // guidance forbids, and six copies is how a rule like that gets broken without anyone deciding to.
 //
+// The body is a slot, so it renders as a div in both densities. A caller passes a list, a
+// pair of paragraphs or a mono block of delivery errors, none of which may sit inside a <p>:
+// the parser closes it early and React reports a hydration error on a callout that looks fine.
+//
 // Deliberately not a shadcn Alert. Alert is a page-level, role="alert" affordance for something
 // that just happened; these are quiet, permanent explanations sitting inside a panel, and they
 // must not announce themselves to a screen reader every time a sheet opens.
@@ -30,7 +34,7 @@ const BOX = "border-(color:--tone-line) bg-(--tone-veil)";
 export function Callout({ icon: Icon, title, tone = "muted", density = "compact", bodyClassName, action, children, className, }) {
     const toned = toneClass(tone);
     if (density === "editorial") {
-        return (_jsxs("div", { className: cn("relative overflow-hidden rounded-lg border py-3.5 pl-5 pr-4", toned, BOX, className), children: [_jsx("span", { "aria-hidden": true, className: "absolute inset-y-0 left-0 w-[3px] bg-(--tone-line)" }), _jsxs("div", { className: "flex items-start gap-2.5", children: [Icon && (_jsx(Icon, { className: "mt-0.5 size-4 shrink-0 text-(color:--tone-hue)" })), _jsxs("div", { className: "flex min-w-0 flex-col gap-1", children: [title && (_jsx(TypographyLabel, { className: "text-(color:--tone-hue)", children: title })), _jsx(TypographyMuted, { className: cn("leading-relaxed", bodyClassName), children: children }), action && (_jsx("div", { className: "mt-1 flex items-center gap-1", children: action }))] })] })] }));
+        return (_jsxs("div", { className: cn("relative overflow-hidden rounded-lg border py-3.5 pl-5 pr-4", toned, BOX, className), children: [_jsx("span", { "aria-hidden": true, className: "absolute inset-y-0 left-0 w-[3px] bg-(--tone-line)" }), _jsxs("div", { className: "flex items-start gap-2.5", children: [Icon && (_jsx(Icon, { className: "mt-0.5 size-4 shrink-0 text-(color:--tone-hue)" })), _jsxs("div", { className: "flex min-w-0 flex-col gap-1", children: [title && (_jsx(TypographyLabel, { className: "text-(color:--tone-hue)", children: title })), _jsx(TypographyMuted, { as: "div", className: cn("leading-relaxed", bodyClassName), children: children }), action && (_jsx("div", { className: "mt-1 flex items-center gap-1", children: action }))] })] })] }));
     }
-    return (_jsxs("div", { className: cn("rounded-md border p-3", toned, BOX, className), children: [title && (_jsxs(TypographySmall, { className: "flex items-center gap-1.5 font-medium text-(color:--tone-hue)", children: [Icon && _jsx(Icon, { className: "size-3.5 shrink-0" }), title] })), _jsx(TypographyCaption, { className: cn("mt-1 block leading-relaxed", bodyClassName), children: children }), action && _jsx("div", { className: "mt-2 flex items-center gap-1", children: action })] }));
+    return (_jsxs("div", { className: cn("rounded-md border p-3", toned, BOX, className), children: [title && (_jsxs(TypographySmall, { className: "flex items-center gap-1.5 font-medium text-(color:--tone-hue)", children: [Icon && _jsx(Icon, { className: "size-3.5 shrink-0" }), title] })), _jsx(TypographyCaption, { as: "div", className: cn("mt-1 leading-relaxed", bodyClassName), children: children }), action && _jsx("div", { className: "mt-2 flex items-center gap-1", children: action })] }));
 }

package/dist/blocks/card.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { cn } from "../cn.js";
 import { FOCUS_RING } from "./focus.js";
-import { inkOnSurface, toneClass } from "../tone.js";
+import { INK_ON_CARD, toneClass } from "../tone.js";
 import { resolveLink } from "../href.js";
 /** Two columns from `sm` up: a pair reads as a set rather than two panels. */
 export function Cards({ className, children, ...props }) {
@@ -12,7 +12,7 @@ export function Cards({ className, children, ...props }) {
  * grid and `overflow-hidden` clips a bleed image cleanly. Padding is vertical
  * only — the horizontal inset belongs to the slots, so bands can run edge to edge.
  */
-const CARD_CLASS = `flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-border ${inkOnSurface("--card-foreground")} ` +
+const CARD_CLASS = `flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-border ${INK_ON_CARD} ` +
     "has-[>img:first-child]:pt-0 " +
     "*:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl";
 /**

package/dist/blocks/index.d.ts

@@ -1,6 +1,7 @@
 export { Cards, Card, CardHeader, CardTitle, CardDescription, CardContent, } from "./card.js";
 export { Disclosure, DisclosureGroup } from "./accordion.js";
 export { Accordion, AccordionItem, AccordionTrigger, AccordionContent, } from "./interactive-accordion.js";
+export { Anchor } from "./anchor.js";
 export { Callout } from "./callout.js";
 export { Button, buttonVariants, type ButtonLook } from "./button.js";
 export { Badge, badgeVariants, type BadgeLook } from "./badge.js";

package/dist/blocks/index.js

@@ -1,6 +1,7 @@
 export { Cards, Card, CardHeader, CardTitle, CardDescription, CardContent, } from "./card.js";
 export { Disclosure, DisclosureGroup } from "./accordion.js";
 export { Accordion, AccordionItem, AccordionTrigger, AccordionContent, } from "./interactive-accordion.js";
+export { Anchor } from "./anchor.js";
 export { Callout } from "./callout.js";
 export { Button, buttonVariants } from "./button.js";
 export { Badge, badgeVariants } from "./badge.js";

package/dist/contrast.d.ts

@@ -45,6 +45,13 @@ export interface LegibilityFailure {
     surface: string;
     ratio: number;
     required: number;
+    /**
+     * The token the pair was *supposed* to use, set only when it was undeclared
+     * and the cascade fell through to the next link of its `var()` chain. Without
+     * it a report reads as though the app chose `--primary-foreground` for its
+     * brand fill, when in truth it chose nothing and CSS chose for it.
+     */
+    via?: string;
 }
 /**
  * Every ink on every surface, both themes. Missing or non-literal tokens are

package/dist/contrast.js

@@ -3,6 +3,12 @@
  * and `.dark` separately measures an intention, and ssite shipped a `.dark` at a
  * healthy 15.7:1 while the page rendered white on white. Build-time only.
  */
+// The tone vocabulary, for the pairs it names. Value import, not just a type:
+// this file measures what `TONE` declares rather than keeping a second list of
+// it. tone.js resolves no React and imports nothing at runtime, so the bare-Node
+// contract this entry point owes still holds — `check-candidates` and the CLI
+// both import it from plain Node.
+import { TONE } from "./tone.js";
 /**
  * Specificity over what token blocks use. `:root` and `.dark` both score 1 —
  * the tie above. `:not(…)` contributes its argument's score, per spec.
@@ -290,17 +296,89 @@ const TERTIARY = ["--subtle-foreground"];
  * 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"],
+const ON_SURFACE = [
     ["--accent", "--accent-foreground"],
     ["--card", "--card-foreground"],
     ["--popover", "--popover-foreground"],
     ["--sidebar", "--sidebar-foreground"],
 ];
+/**
+ * Every cut a tone names, read off `TONE` instead of restated here.
+ *
+ * The tone rows used to be five hand-written pairs in the list above, which is
+ * the arrangement the comment on `tokenCuts` warns about: a palette checked
+ * against one taxonomy and declared from another drifts, and `brand` is the
+ * proof. It was in `TONE` from the day the vocabulary landed and never in this
+ * file, so the one tone whose tokens an app supplies was the one tone nothing
+ * measured.
+ *
+ * Parsed rather than shared as data because `TONE` has to stay a table of
+ * literal class strings — Tailwind scans this package as text and generates
+ * only the classes it can read, so a row assembled from a record would style
+ * nothing. Parsing the literal keeps one declaration; a second table would be
+ * the drift all over again.
+ */
+const TONE_CUT = /\[--tone-(fill|ink|hue):([^\]]*)\]/g;
+/**
+ * A cut's `var()` fallback chain, outermost first: `var(--brand,var(--primary))`
+ * is `["--brand", "--primary"]`. The order is the order CSS tries them in.
+ */
+const toneChains = (classes) => {
+    const chains = { fill: [], ink: [], hue: [] };
+    for (const [, cut, value] of classes.matchAll(TONE_CUT))
+        chains[cut] = [...value.matchAll(/--[a-z0-9-]+/g)].map((m) => m[0]);
+    return chains;
+};
+const TONE_CHAINS = Object.entries(TONE).map(([tone, classes]) => [tone, toneChains(classes)]);
+/** The pair a tone names, for the taxonomy `tokenCuts` reports. */
+const ON_FILL = [
+    ...TONE_CHAINS.map(([, c]) => [c.fill[0], c.ink[0]]),
+    ...ON_SURFACE,
+];
+/**
+ * A tone's label on a tone's fill, resolved the way a browser resolves it.
+ *
+ * `checkLegibility` skips a token it cannot find, and that is right: an app that
+ * declares no `--sidebar` has not failed a bar, it has declined a role. But a
+ * token missing *while its siblings are present* is a different animal. The tone
+ * still renders — `var(--brand-foreground,var(--primary-foreground))` simply
+ * moves to the next link — so the control is painted in a pair the app never
+ * chose and skipping it reads as a pass.
+ *
+ * That is how a bronze `--brand` shipped with a white label at 2.80:1: the fill
+ * was declared, the label was not, and nothing measured the pair that actually
+ * reached the screen. So this follows the chain to whichever link is really
+ * there, and measures that. An app declaring a whole tone is measured on its own
+ * tokens; one declaring none falls through to the package's, which are measured
+ * anyway; one declaring half hears about it in the only terms that matter, the
+ * two colours a reader is going to see.
+ */
+function checkToneCuts(css, { themes = ["light", "dark"] } = {}) {
+    const failures = [];
+    for (const theme of themes) {
+        const tokens = resolveTokens(css, theme);
+        const colorOf = (token) => parseColor(tokens[token] ?? "");
+        for (const [, chains] of TONE_CHAINS) {
+            const fill = chains.fill.find((token) => colorOf(token));
+            const ink = chains.ink.find((token) => colorOf(token));
+            if (!fill || !ink)
+                continue;
+            const ratio = contrast(colorOf(ink), colorOf(fill));
+            if (ratio >= 4.5)
+                continue;
+            failures.push({
+                theme,
+                ink,
+                surface: fill,
+                ratio,
+                required: 4.5,
+                // Only when the tone's own ink was not the one that answered.
+                ...(ink === chains.ink[0] ? {} : { via: chains.ink[0] }),
+            });
+        }
+    }
+    return failures;
+}
 /**
  * The cuts a token ships, read off the same three sets `checkSignals` measures.
  *
@@ -376,12 +454,18 @@ export function checkSignals(css, { themes = ["light", "dark"] } = {}) {
         }),
         ...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 })),
+        ...ON_SURFACE.flatMap(([fill, label]) => checkLegibility(css, { inks: [label], surfaces: [fill], themes })),
+        ...checkToneCuts(css, { themes }),
     ];
 }
 /** A one-line report per failure, for a test's assertion message. */
 export function formatFailures(failures) {
     return failures
-        .map((f) => `${f.theme}: ${f.ink} on ${f.surface} is ${f.ratio.toFixed(2)}:1, below ${f.required}:1`)
+        .map((f) => {
+        const measured = `${f.theme}: ${f.ink} on ${f.surface} is ${f.ratio.toFixed(2)}:1, below ${f.required}:1`;
+        return f.via
+            ? `${measured} — ${f.via} is not declared, so ${f.surface} took ${f.ink} from the fallback`
+            : measured;
+    })
         .join("\n");
 }

package/dist/index.d.ts

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

package/dist/index.js

@@ -3,7 +3,7 @@ export { cn } from "./cn.js";
 // 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";
+export { toneClass, impliedTone, INK_ON_FILL, INK_ON_CARD, INK_ON_POPOVER, INK_ON_SIDEBAR, inkOnSurfaceStyle, } 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.

package/dist/tone.d.ts

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 /**
  * One semantic colour vocabulary, for every component that carries meaning in a
  * hue: Button, Callout, TypographyLink. Before this there were three lists —
@@ -111,11 +112,30 @@ export declare const toneClass: (tone: Tone) => string;
  */
 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.
+ * The same contract for a surface the tones do not name. These are tints of the
+ * page rather than hues, so both rungs survive and the pair is stated rather
+ * than collapsed.
+ *
+ * Stated one constant at a time, and not built from an argument, for the reason
+ * `TONE` above is a table of literals: Tailwind reads this file as text and can
+ * only generate a class it can see. A class assembled at runtime is a class that
+ * was never generated — no error, no style, and the nested type quietly keeps
+ * the page's ink on a surface that is not the page. The set is closed because
+ * the set of surfaces the theme names is closed; a surface with no token is not
+ * a surface. For one the package does not name, see `inkOnSurfaceStyle`.
+ */
+export declare const INK_ON_CARD = "[--ink:var(--card-foreground)] [--ink-muted:var(--muted-foreground)]";
+export declare const INK_ON_POPOVER = "[--ink:var(--popover-foreground)] [--ink-muted:var(--muted-foreground)]";
+export declare const INK_ON_SIDEBAR = "[--ink:var(--sidebar-foreground)] [--ink-muted:var(--muted-foreground)]";
+/**
+ * The escape hatch, for an app painting a surface of its own.
+ *
+ * Properties rather than a class, because a class this function returned would
+ * have to be generated by a scanner that never saw it. Inline custom properties
+ * need no scanner at all, so this works for any token and cannot silently
+ * produce nothing. It replaces a version that returned a class string and did.
  */
-export declare const inkOnSurface: (ink: string, muted?: string) => string;
+export declare const inkOnSurfaceStyle: (ink: string, muted?: string) => CSSProperties;
 /**
  * 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

package/dist/tone.js

@@ -121,11 +121,30 @@ export const toneClass = (tone) => `${TONE_SURFACE} ${TONE[tone]}`;
  */
 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.
+ * The same contract for a surface the tones do not name. These are tints of the
+ * page rather than hues, so both rungs survive and the pair is stated rather
+ * than collapsed.
+ *
+ * Stated one constant at a time, and not built from an argument, for the reason
+ * `TONE` above is a table of literals: Tailwind reads this file as text and can
+ * only generate a class it can see. A class assembled at runtime is a class that
+ * was never generated — no error, no style, and the nested type quietly keeps
+ * the page's ink on a surface that is not the page. The set is closed because
+ * the set of surfaces the theme names is closed; a surface with no token is not
+ * a surface. For one the package does not name, see `inkOnSurfaceStyle`.
+ */
+export const INK_ON_CARD = "[--ink:var(--card-foreground)] [--ink-muted:var(--muted-foreground)]";
+export const INK_ON_POPOVER = "[--ink:var(--popover-foreground)] [--ink-muted:var(--muted-foreground)]";
+export const INK_ON_SIDEBAR = "[--ink:var(--sidebar-foreground)] [--ink-muted:var(--muted-foreground)]";
+/**
+ * The escape hatch, for an app painting a surface of its own.
+ *
+ * Properties rather than a class, because a class this function returned would
+ * have to be generated by a scanner that never saw it. Inline custom properties
+ * need no scanner at all, so this works for any token and cannot silently
+ * produce nothing. It replaces a version that returned a class string and did.
  */
-export const inkOnSurface = (ink, muted = "--muted-foreground") => `[--ink:var(${ink})] [--ink-muted:var(${muted})]`;
+export const inkOnSurfaceStyle = (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

package/dist/typography/paragraph.d.ts

@@ -11,12 +11,19 @@ declare const pVariants: (props?: ({
     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;
+/**
+ * `as` is here for the reason the caption has it, one step further on: a
+ * component that hands its body to a caller cannot know whether what arrives is
+ * a sentence or a list, and a paragraph may hold neither a list nor a div. The
+ * HTML parser closes the `<p>` early and React reports a hydration error, so
+ * every wrapper of that shape (`Callout` was the one) renders `as="div"`.
+ */
+export declare function TypographyP({ className, variant, tone, as, children, ...props }: WithAs<ParagraphVariants>): import("react").JSX.Element;
 /** A preset's props: its base's, minus the axes it has decided. `keyof Pins` reads
  * the exclusion off the pinned object the preset also spreads, so the two cannot
  * drift — `<TypographyMuted tone="default">` used to compile and un-mute it. */
 type Preset<Base, Pins> = Omit<Base, keyof Pins>;
-type ParagraphProps = ComponentProps<"p"> & ParagraphVariants;
+type ParagraphProps = WithAs<ParagraphVariants>;
 /** The UI rung in the secondary ink. */
 declare const MUTED: {
     readonly tone: "muted";

package/dist/typography/paragraph.js

@@ -25,8 +25,15 @@ const pVariants = cva("", {
     },
     defaultVariants: { variant: "ui", tone: "default" },
 });
-export function TypographyP({ className, variant, tone, children, ...props }) {
-    return (_jsx("p", { className: cn(pVariants({ variant, tone }), className), ...props, children: children }));
+/**
+ * `as` is here for the reason the caption has it, one step further on: a
+ * component that hands its body to a caller cannot know whether what arrives is
+ * a sentence or a list, and a paragraph may hold neither a list nor a div. The
+ * HTML parser closes the `<p>` early and React reports a hydration error, so
+ * every wrapper of that shape (`Callout` was the one) renders `as="div"`.
+ */
+export function TypographyP({ className, variant, tone, as = "p", children, ...props }) {
+    return (_jsx(TextAs, { as: as, className: cn(pVariants({ variant, tone }), className), ...props, children: children }));
 }
 /** The UI rung in the secondary ink. */
 const MUTED = { tone: "muted" };

package/llms.txt

@@ -22,8 +22,12 @@ silently. Full reference: https://github.com/supertypeai/foundations
    `border-border`. No hex values, no `bg-zinc-800`, no `dark:` overrides that
    swap one token for another.
 5. **Paint a surface, hand down its ink.** Any element you give a background
-   needs `INK_ON_FILL` (a tone fill) or `inkOnSurface(token)` (a tinted one), or
-   the type inside it keeps the page's ink and fails contrast silently.
+   needs `INK_ON_FILL` (a tone fill) or one of `INK_ON_CARD`, `INK_ON_POPOVER`,
+   `INK_ON_SIDEBAR` (a tinted one), or the type inside it keeps the page's ink
+   and fails contrast silently. Never build one of these class strings
+   yourself: Tailwind only generates a class it can read as text, so an
+   assembled one styles nothing. For a surface with no constant, spread
+   `inkOnSurfaceStyle(token)` into `style`.
 6. **Write the words like a person would.** See Writing copy below. It applies
    to every string a reader sees and to the comments you leave behind.
 
@@ -45,6 +49,7 @@ silently. Full reference: https://github.com/supertypeai/foundations
 | a number or metric | `TypographyStat` | root |
 | inline code | `TypographyInlineCode` | root |
 | a link | `TypographyLink` | root |
+| an anchor around something already drawn | `Anchor` | `/blocks` |
 | where an href goes, without a component | `resolveLink` | root |
 | a highlighted phrase | `TypographyHighlight` | root |
 | a button, or a link that looks like one | `Button` | `/blocks` |
@@ -68,14 +73,14 @@ silently. Full reference: https://github.com/supertypeai/foundations
 | import | exports |
 |---|---|
 | `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
-| `@supertype.ai/foundations/blocks` | `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Button`, `buttonVariants`, `Badge`, `badgeVariants`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `SEGMENT`. Types: `ButtonLook`, `BadgeLook`, `TabItem` |
+| `@supertype.ai/foundations/blocks` | `Anchor`, `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Button`, `buttonVariants`, `Badge`, `badgeVariants`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `SEGMENT`. Types: `ButtonLook`, `BadgeLook`, `TabItem` |
 | `@supertype.ai/foundations/mdx` | `proseMdxComponents` |
 | `@supertype.ai/foundations/essay` | `createEssay`, `EssayHeader`, `EssayLayout`, `EssaySection`, `EssayPullQuote`, `EssayFigure`, `EssayMovements`, `EssayDocument`, `EssayColumns`, `EssayAside`, `EssayBody`, `ReadingLayout`, `TableOfContents`, `ReadingRail`, `ReadingProgressBar`, `Rail`, `RailLink`, `PostMetaRow`, `PostDate`, `ReadTime`, `TagPills`, `MetaDot`, `formatPostDate`, `extractHeadings`, `readingTime`, `createSlugger`, `useReadingProgress`, `useScrollSpy`. Types: `TocHeading`, `EssayDecorations`, `EssayIndexEntry`, `EssayDocSection`, `EssayMovement`, `PostDateFormat` |
 | `@supertype.ai/foundations/seo` | `createSeo`. Types: `SeoConfig`, `ArticleAuthor`, `ArticleOptions`, `PageMetadata` |
 | `@supertype.ai/foundations/og` | `ogCard`, `OG_SIZE`. Types: `OgCardOptions` |
 | `@supertype.ai/foundations/eslint` | `designRules` (every rule as one array, the one to spread), `designConfig` (the same set wrapped as a flat-config entry). The builders `colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are exported too, though spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
 | `@supertype.ai/foundations/rehype` | `rehypeProseCode`, `proseCodeOptions`, `PROSE_LANGS`, `PROSE_THEMES`. Build-time only, must not resolve React |
-| `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1 — status hues, the categorical earth hues and the six chart series alike — tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill), `checkHairlines` (`--border` and `--input` at 1.4:1 on `--background` and `--card`, `--sidebar-border` on `--sidebar`: a rule is exempt from the ink and mark bars, but it still has to read as the same weight in both themes), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast` (WCAG ratio), `lc` (APCA lightness contrast: polarity-aware, for checking that an ink ramp is perceptually ordered rather than merely ordered by ratio), `tokenCuts` (which cuts a token ships: fill, the label printed on it, the hue as words, the taxonomy `checkSignals` measures against). Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
+| `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1 — status hues, the categorical earth hues and the six chart series alike — tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill: the tone rows are read off `TONE` and each cut is resolved along its `var()` fallback chain, so an app that declares `--brand` without `--brand-foreground` is measured on the label the cascade really reaches for rather than skipped), `checkHairlines` (`--border` and `--input` at 1.4:1 on `--background` and `--card`, `--sidebar-border` on `--sidebar`: a rule is exempt from the ink and mark bars, but it still has to read as the same weight in both themes), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast` (WCAG ratio), `lc` (APCA lightness contrast: polarity-aware, for checking that an ink ramp is perceptually ordered rather than merely ordered by ratio), `tokenCuts` (which cuts a token ships: fill, the label printed on it, the hue as words, the taxonomy `checkSignals` measures against). Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
 
 ## Props worth knowing
 
@@ -90,8 +95,12 @@ silently. Full reference: https://github.com/supertypeai/foundations
 - `TypographyLink`: `href` (required), `tone?: Tone` (default `muted`), `addArrow?`, `newTab?`. The href decides internal versus external.
 - `TypographyHighlight`: `tone?: HighlightTone`, one of `"primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, plus `seed?: number`. A separate type from `Tone` on purpose: this axis is categorical (which one it is) where `Tone` is semantic (what it means), the same split theme.css draws between the earth swatches and the status tokens.
 - `Card`: `href`, `title`, `description`, `icon`, `external`. An href makes the whole card a link.
+- `Anchor`: `href` (required), plus `external`/`newTab`. An unstyled anchor for a
+  link that is not typography and not a control — a thumbnail, a chip, a tooltip
+  trigger. It exists so `target`/`rel` are never written at a call site; `external`
+  is for a same-origin path that is not a route, which the router would prefetch.
 - `Tone` is the one semantic colour vocabulary, shared by `Button`, `Badge`, `Callout`, `TypographyLink` and `TabsList`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`. Seven tones, seven tokens, one to one, which is the bar for adding one. Four names map onto others: `neutral` and `foreground` are `muted`, the word the rest of the package uses; `accent` is `--primary`'s hover tint, so a washed `primary` renders the same thing; `info` is covered by the `success | warn | destructive` triad. `brand` falls back to `--primary` in an app that defines no `--brand`.
-- **Ink is handed down by whatever paints.** `toneClass(tone)` is a palette and sets no ink. A surface that fills adds `INK_ON_FILL`; a tinted one uses `inkOnSurface("--card-foreground")`. Both declare `--ink` and `--ink-muted`, which every type primitive reads, falling back to the page. Paint a background without them and a nested `TypographyLabel` prints `--foreground` on your fill, which measures 2.34:1 on `--primary`. On a hue fill `--ink-muted` equals `--ink`: a filled control has one ink, and wanting a second rung means wanting a tinted surface.
+- **Ink is handed down by whatever paints.** `toneClass(tone)` is a palette and sets no ink. A surface that fills adds `INK_ON_FILL`; a tinted one adds `INK_ON_CARD`, `INK_ON_POPOVER` or `INK_ON_SIDEBAR`, and one the package does not name spreads `inkOnSurfaceStyle(token)` into `style` rather than building a class. Both declare `--ink` and `--ink-muted`, which every type primitive reads, falling back to the page. Paint a background without them and a nested `TypographyLabel` prints `--foreground` on your fill, which measures 2.34:1 on `--primary`. On a hue fill `--ink-muted` equals `--ink`: a filled control has one ink, and wanting a second rung means wanting a tinted surface.
 - `Button`: `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` (default `solid`), `tone?: Tone` (defaults to `primary` on a solid button and `muted` on every other variant — filling a button in is how a page says this is the action), `size?: "xs" | "sm" | "md" | "lg" | "xl"` (default `md`), `icon?: boolean` for a square glyph box, `pill?: boolean` for full-round corners, `href` to make it a link, `render` for an element that is neither a button nor a link. Variant is how much ink it spends and tone is what the ink means, on separate axes, so a quiet delete is `variant="ghost" tone="destructive"`.
 - `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`, `href` for a badge that leads somewhere. Same axes and same spellings as `Button`, minus `link`, which belongs to things you click. `warning` and `supertype` were `tone="warn"` and `tone="brand"` under invented names.
 - `Callout`: `tone?: Tone`, `density?: "compact" | "editorial"`, `title`, `icon`, `action`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -82,7 +82,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/cjs-marker.mjs && node scripts/check-llms.mjs && node scripts/pins.mjs",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/cjs-marker.mjs && node scripts/check-candidates.mjs && node scripts/check-llms.mjs && node scripts/pins.mjs",
     "dev": "tsc -p tsconfig.json --watch",
     "test": "yarn build && vitest run",
     "test:watch": "vitest",

package/src/type.css

@@ -71,3 +71,33 @@
 .editorial.font-heading {
   font-weight: var(--heading-weight);
 }
+
+/* A glyph set beside words, sized and seated so it belongs to the line.
+
+   Two numbers, both read off the font rather than chosen. Lucide draws its ink
+   across 22 of its 24 grid units, so a 0.8em box puts that ink at 1.02 times the
+   cap height of whatever rung it sits beside.
+
+   The seat corrects a bias the browser introduces. Centring aligns a glyph on the
+   middle of the line box, and the line box is built from the font's ascent and
+   descent rounded to whole pixels, which lands its middle below the middle of the
+   capitals: 0.31px low at the 11px rung, 0.46px at the 10px, 0.50px at the 13px.
+   So a centred glyph is always seated slightly low, by an amount that changes with
+   the rung, which is why hand nudges get written one place at a time and never
+   generalise. Lifting by 0.035em takes it back onto the cap band across the ramp.
+
+   A box pinned in pixels cannot hold the first number either, because the band it
+   has to match moves with the rung. Twelve pixels is 1.39 times the cap height at
+   the 11px rung and 1.53 at the 10px one, so the glyph climbs over the ascenders
+   and hangs well under the baseline while every letter beside it rests on it.
+
+   For a glyph inline with words. A glyph that stands alone, in a button, a nav
+   rail or an avatar slot, has no band to answer to and keeps a fixed size.
+
+   The 22-of-24 figure is lucide's grid. An app on a different icon set wants a
+   different box for the same ratio. */
+@utility icon-inline {
+  width: 0.8em;
+  height: 0.8em;
+  translate: 0 -0.035em;
+}