@supertype.ai/foundations 0.1.29 → 0.1.30

package/dist/tone.js

@@ -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 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)]",
+    primary: "[--tone-fill:var(--primary)] [--tone-ink:var(--primary-foreground)] [--tone-hue:var(--primary-ink,var(--primary))]",
     /** The warm accent. `--secondary-ink` is its readable cut; the fill is not. */
     secondary: "[--tone-fill:var(--secondary)] [--tone-ink:var(--secondary-foreground)] [--tone-hue:var(--secondary-ink)]",
     /** The consumer's identity hue, if it defined one. Otherwise the principal one. */
-    brand: "[--tone-fill:var(--brand,var(--primary))] [--tone-ink:var(--tint-foreground)] [--tone-hue:var(--brand-ink,var(--primary))]",
+    brand: "[--tone-fill:var(--brand,var(--primary))] [--tone-ink:var(--brand-foreground,var(--primary-foreground))] [--tone-hue:var(--brand-ink,var(--primary-ink,var(--primary)))]",
     /** It worked. */
-    success: "[--tone-fill:var(--success)] [--tone-ink:var(--tint-foreground)] [--tone-hue:var(--success-ink)]",
+    success: "[--tone-fill:var(--success)] [--tone-ink:var(--success-foreground)] [--tone-hue:var(--success-ink)]",
     /** A footgun: the reader can still proceed, but not blindly. */
-    warn: "[--tone-fill:var(--warn)] [--tone-ink:var(--tint-foreground)] [--tone-hue:var(--warn-ink)]",
+    warn: "[--tone-fill:var(--warn)] [--tone-ink:var(--warn-foreground)] [--tone-hue:var(--warn-ink)]",
     /** It deletes something, or it already failed. */
     destructive: "[--tone-fill:var(--destructive)] [--tone-ink:var(--destructive-foreground)] [--tone-hue:var(--destructive)]",
 };
@@ -69,9 +69,13 @@ export const 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 const TONE_SURFACE = [
@@ -81,10 +85,10 @@ export const TONE_SURFACE = [
     "[--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)]",
+    /** The same control under the pointer: twice the tint, so the step reads. */
+    "[--tone-wash-hover:color-mix(in_oklab,var(--tone-hue)_20%,transparent)]",
     /** A filled control under the pointer. */
-    "[--tone-fill-hover:color-mix(in_oklab,var(--tone-fill)_88%,var(--foreground))]",
+    "[--tone-fill-hover:color-mix(in_oklab,var(--tone-fill),var(--hover-toward)_18%)]",
 ].join(" ");
 /**
  * A tone, as one class list. This is the only thing a component should need.
@@ -97,6 +101,31 @@ export const TONE_SURFACE = [
  * whose order matters and whose values always travel together is one argument.
  */
 export const toneClass = (tone) => `${TONE_SURFACE} ${TONE[tone]}`;
+/**
+ * The ink a nested element inherits, declared by whatever painted the surface
+ * under it. Two properties, one rule: paint a background, hand down its ink.
+ *
+ * `toneClass` alone is a palette, not a surface — a `Callout` spends the same
+ * seven values as a filled `Button` and tints at 5%, so the words inside it
+ * still sit on the page and still want the page's ink. Only a component that
+ * actually fills promotes `--tone-ink` to the inherited ink, and the type
+ * primitives read it with the page as their fallback. A tint that promotes
+ * nothing is therefore correct by default, which is the failure this replaces:
+ * `TypographyLabel` pinned `text-foreground`, won over the `text-primary-foreground`
+ * on the anchor around it, and printed 2.34:1 on a filled button.
+ *
+ * `--ink-muted` collapses to the ink itself, because a hue fill has no second
+ * rung: mixing the ink 20% toward `--primary` measures 4.22:1 on the
+ * espresso theme and 3.49:1 at 30%. Nothing on a filled control may be quieter
+ * than its label. Wanting two rungs is wanting a tinted surface.
+ */
+export const INK_ON_FILL = "[--ink:var(--tone-ink)] [--ink-muted:var(--tone-ink)]";
+/**
+ * The same contract for a surface the tones do not name: `--card`, `--popover`,
+ * a sidebar. These are tints of the page rather than hues, so both rungs
+ * survive and the pair is stated rather than collapsed.
+ */
+export const inkOnSurface = (ink, muted = "--muted-foreground") => `[--ink:var(${ink})] [--ink-muted:var(${muted})]`;
 /**
  * What an unstated tone means, given how much ink the component is spending.
  * Shared, because `Button` and `Badge` both need it and two copies of a default

package/dist/typography/header.d.ts

@@ -59,8 +59,8 @@ declare const eyebrowVariants: (props?: ({
 /**
  * The eyebrow's ramp as a class, for a caller that cannot render our element —
  * a dialog title primitive, a motion element. Same escape hatch as
- * `headingClass`, and it exists so that a consumer needing the class does not
- * hand-roll a second copy of it that then drifts from the component.
+ * `headingClass`. It exists so a consumer needing the class can take ours rather
+ * than hand-rolling a copy that drifts from the component.
  */
 export declare const eyebrowClass: (tone?: VariantProps<typeof eyebrowVariants>["tone"]) => string;
 /**

package/dist/typography/header.js

@@ -32,7 +32,7 @@ import { TextAs } from "./as.js";
  * the face had no door, arriving with a `scroll-m-20` for an anchor it does not have.
  */
 export const headingFace = "font-heading font-[number:var(--heading-weight)]";
-const HEADING_BASE = `scroll-m-20 ${headingFace} text-foreground`;
+const HEADING_BASE = `scroll-m-20 ${headingFace} text-[color:var(--ink,var(--foreground))]`;
 const h1Variants = cva(`${HEADING_BASE} tracking-tight`, {
     variants: {
         variant: {
@@ -98,7 +98,7 @@ const eyebrowVariants = cva("block uppercase tracking-wider", {
              * Primary ink, stated not inherited — an eyebrow names the section under it,
              * and one that turns red from its surroundings is not a heading.
              */
-            heading: "text-xs font-semibold text-foreground",
+            heading: "text-xs font-semibold text-[color:var(--ink,var(--foreground))]",
             /** Stat cards invert it: the figure is the headline, so the label yields. */
             label: "text-2xs font-medium text-accent-foreground",
         },
@@ -108,8 +108,8 @@ const eyebrowVariants = cva("block uppercase tracking-wider", {
 /**
  * The eyebrow's ramp as a class, for a caller that cannot render our element —
  * a dialog title primitive, a motion element. Same escape hatch as
- * `headingClass`, and it exists so that a consumer needing the class does not
- * hand-roll a second copy of it that then drifts from the component.
+ * `headingClass`. It exists so a consumer needing the class can take ours rather
+ * than hand-rolling a copy that drifts from the component.
  */
 export const eyebrowClass = (tone) => eyebrowVariants({ tone });
 /**

package/dist/typography/highlight.d.ts

@@ -5,8 +5,7 @@ import type { ComponentProps } from "react";
  * hue for nothing. That is why the earth tones enter as `-foreground`: those are
  * the ink-grade pair, mixed to hold at text weight in both themes.
  *
- * Emphasis, never status. Warn and info and destructive are absent on purpose —
- * a swipe of red under a phrase says less than the words do.
+ * Emphasis, never status. Warn and info and destructive are absent on purpose.
  *
  * The four earth tones are one palette, not a menu: each is a different hue,
  * because two a reader cannot tell apart are one tone with two names.
@@ -24,6 +23,8 @@ export type HighlightTone = keyof typeof MARKER_TONES;
  * Marker highlight for inline text. Painted as the run's own background, never a
  * mask — a mask would shave the glyph tops. `luminosity` lets letters borrow the
  * marker's hue while keeping their own lightness, so contrast holds in both themes.
+ * That lightness comes from `--marker-ink`, a deepened `--foreground`, so the run
+ * still reads as the emphasised one rather than sinking into its own wash.
  */
 export declare function TypographyHighlight({ tone, seed, className, style, children, ...props }: ComponentProps<"span"> & {
     tone?: HighlightTone;

package/dist/typography/highlight.js

@@ -6,8 +6,7 @@ import { cn } from "../cn.js";
  * hue for nothing. That is why the earth tones enter as `-foreground`: those are
  * the ink-grade pair, mixed to hold at text weight in both themes.
  *
- * Emphasis, never status. Warn and info and destructive are absent on purpose —
- * a swipe of red under a phrase says less than the words do.
+ * Emphasis, never status. Warn and info and destructive are absent on purpose.
  *
  * The four earth tones are one palette, not a menu: each is a different hue,
  * because two a reader cannot tell apart are one tone with two names.
@@ -41,7 +40,8 @@ const DABS = [
 // Integer-only: `Math.sin` is implementation-defined, so Node and the browser
 // disagreed in the last bits and the swipe hydrated as a mismatch.
 const hash = (seed, i) => {
-    let h = Math.imul(seed ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul(i + 0x165667b1, 0xc2b2ae35);
+    let h = Math.imul(seed ^ 0x9e3779b9, 0x85ebca6b) ^
+        Math.imul(i + 0x165667b1, 0xc2b2ae35);
     h ^= h >>> 15;
     h = Math.imul(h, 0x2545f491);
     h ^= h >>> 13;
@@ -88,11 +88,17 @@ const markerFill = (seed) => {
  * Marker highlight for inline text. Painted as the run's own background, never a
  * mask — a mask would shave the glyph tops. `luminosity` lets letters borrow the
  * marker's hue while keeping their own lightness, so contrast holds in both themes.
+ * That lightness comes from `--marker-ink`, a deepened `--foreground`, so the run
+ * still reads as the emphasised one rather than sinking into its own wash.
  */
 export function TypographyHighlight({ tone = "primary", seed = 3, className, style, children, ...props }) {
-    return (_jsx("span", { className: cn("isolate inline px-[0.3em] py-[0.06em]", "[-webkit-box-decoration-break:clone] [box-decoration-break:clone]", "[--marker-alpha:44%] dark:[--marker-alpha:58%]", className), style: {
+    return (_jsx("span", { className: cn("isolate inline px-[0.3em] py-[0.06em]", "[-webkit-box-decoration-break:clone] [box-decoration-break:clone]", "[--marker-alpha:44%] dark:[--marker-alpha:58%]", 
+        // The blend keeps a glyph's lightness and nothing else, so a run over the
+        // wash reads flatter than the same words beside it. Pushing the lightness
+        // past --foreground buys that punch back without touching the hue borrow.
+        "[--marker-ink:color-mix(in_oklab,var(--foreground)_85%,black)]", "dark:[--marker-ink:color-mix(in_oklab,var(--foreground)_88%,white)]", className), style: {
             "--marker": MARKER_TONES[tone],
             backgroundImage: markerFill(seed),
             ...style,
-        }, ...props, children: _jsx("span", { className: "[mix-blend-mode:luminosity]", children: children }) }));
+        }, ...props, children: _jsx("span", { className: "text-(color:--marker-ink) [mix-blend-mode:luminosity]", children: children }) }));
 }

package/dist/typography/paragraph.d.ts

@@ -1,3 +1,4 @@
+import { type LinkBehavior } from "../href.js";
 import { type VariantProps } from "class-variance-authority";
 import type { ComponentProps, ReactNode } from "react";
 import { type Tone } from "../tone.js";
@@ -101,7 +102,7 @@ export declare function TypographyLabel({ className, size, as, children, ...prop
  * than a constant. Keep `tabular` anywhere a value updates in place.
  */
 declare const statVariants: (props?: ({
-    size?: "inherit" | "display" | "card" | "panel" | "page" | null | undefined;
+    size?: "inherit" | "page" | "display" | "card" | "panel" | null | undefined;
     figures?: "tabular" | "proportional" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type StatVariants = VariantProps<typeof statVariants>;
@@ -114,28 +115,24 @@ 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;
-type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & {
+type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & LinkBehavior & {
     href: string;
     children: ReactNode;
     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;
     /**
      * A trailing arrow, for a link that ends a sentence and leads somewhere. The
      * glyph follows the href: `↗` when the link leaves the site, `→` when it does
-     * not. That is the convention, and it is not a call site's to get wrong.
+     * not. The href picks it, so a call site never has to.
      */
     addArrow?: boolean;
 };
 /**
  * The inline link.
  *
- * Internal and external are decided from the href, never at the call site: an
- * href with a scheme renders a plain anchor and, if it is http(s), opens away
- * with `rel="noopener noreferrer"`; everything else routes through the router's
- * Link. `newTab` is the one override, for an off-site href that starts a flow
- * the reader should stay in. Call-site props apply last, so a passed
- * `target`/`rel` still wins.
+ * Internal and external are decided from the href, never at the call site —
+ * ../href.ts holds that decision, and Button, Badge and Card make the same one.
+ * `newTab` and `external` are the overrides. Call-site props apply last, so a
+ * passed `target`/`rel` still wins.
  *
  * The router is `next-view-transitions`, imported rather than injected. Every
  * project on this package is a Next app and wants the same link, and a factory
@@ -143,5 +140,5 @@ type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & {
  * not be imported by name. One call site ended up on the unbound version that
  * way and lost its decoration.
  */
-export declare function TypographyLink({ href, children, tone, newTab, addArrow, className, ...props }: TypographyLinkProps): import("react").JSX.Element;
+export declare function TypographyLink({ href, children, tone, external: leavesApp, newTab, addArrow, className, ...props }: TypographyLinkProps): import("react").JSX.Element;
 export {};

package/dist/typography/paragraph.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Link } from "next-view-transitions";
+import { resolveLink } from "../href.js";
 import { cva } from "class-variance-authority";
 import { cn } from "../cn.js";
 import { toneClass } from "../tone.js";
@@ -19,8 +19,8 @@ const pVariants = cva("", {
             prose: "text-pretty text-lg leading-relaxed",
         },
         tone: {
-            default: "text-foreground",
-            muted: "text-muted-foreground",
+            default: "text-[color:var(--ink,var(--foreground))]",
+            muted: "text-[color:var(--ink-muted,var(--muted-foreground))]",
         },
     },
     defaultVariants: { variant: "ui", tone: "default" },
@@ -34,7 +34,10 @@ export function TypographyMuted(props) {
     return _jsx(TypographyP, { ...props, ...MUTED });
 }
 /** Reading-size body copy. `TypographyMuted` is the same ink one rung down. */
-const PROSE = { variant: "prose", tone: "muted" };
+const PROSE = {
+    variant: "prose",
+    tone: "muted",
+};
 export function TypographyProse(props) {
     return _jsx(TypographyP, { ...props, ...PROSE });
 }
@@ -86,7 +89,7 @@ export function TypographyProseList(props) {
  * reason to sit there is to be quieter than the thing you qualify — and every
  * container that sets a size for you sets a weight too.
  */
-const captionVariants = cva("text-muted-foreground", {
+const captionVariants = cva("text-[color:var(--ink-muted,var(--muted-foreground))]", {
     variants: {
         size: {
             sm: "text-sm leading-normal",
@@ -127,7 +130,7 @@ export function TypographySmall(props) {
  * `as` is here for the same reason it is on `TypographyEyebrow`: a config panel
  * names its sections at this size, and those names are the page's outline.
  */
-const labelVariants = cva("font-medium text-foreground", {
+const labelVariants = cva("font-medium text-[color:var(--ink,var(--foreground))]", {
     variants: {
         size: {
             sm: "text-sm",
@@ -188,11 +191,11 @@ export function TypographyStat({ className, size, figures, children, ...props })
  * optical correction — the mono face carries a taller x-height than the sans.
  */
 export function TypographyInlineCode({ className, children, ...props }) {
-    return (_jsx("code", { className: cn("rounded-[3px] bg-foreground/[0.03] px-[0.3em] py-[0.1em] font-mono text-[0.9em] text-secondary-ink", className), ...props, children: children }));
+    return (_jsx("code", { className: cn("rounded-[3px] bg-current/[0.06] px-[0.3em] py-[0.1em] font-mono text-[0.9em] text-[color:var(--ink,var(--secondary-ink))]", className), ...props, children: children }));
 }
 /**
  * A statement about the surface, not the link: `muted` inside a paragraph,
- * `primary` when the link is the point of the line, `secondary` for a note
+ * `primary` when the link is the main thing on the line, `secondary` for a note
  * beneath a hero where `primary` would compete with the CTA beside it. The other
  * four come free, and a link inside a warning should be able to say so.
  *
@@ -203,17 +206,22 @@ export function TypographyInlineCode({ className, children, ...props }) {
  * `font-medium`, which read as a lighter link rather than a differently-coloured
  * one.
  */
+const INHERITED_INK = "text-[color:var(--ink,var(--foreground))]";
 const LINK_DECORATION = "underline decoration-dotted decoration-1 decoration-muted-foreground decoration-skip-ink-none underline-offset-2 hover:decoration-solid hover:decoration-current/70";
-const linkClass = (tone = "muted", className) => cn(toneClass(tone), "font-medium text-(color:--tone-hue)", LINK_DECORATION, className);
+/**
+ * No tone stated means "read the surface": the ink comes from whatever painted
+ * the ground, which on a page is `--foreground` and inside a filled control is
+ * that control's label ink. The old default spelled this `muted`, whose hue is
+ * `--foreground` — identical on a page, and 2.28:1 on a filled button.
+ */
+const linkClass = (tone, className) => cn(tone ? cn(toneClass(tone), "text-(color:--tone-hue)") : INHERITED_INK, "font-medium", LINK_DECORATION, className);
 /**
  * The inline link.
  *
- * Internal and external are decided from the href, never at the call site: an
- * href with a scheme renders a plain anchor and, if it is http(s), opens away
- * with `rel="noopener noreferrer"`; everything else routes through the router's
- * Link. `newTab` is the one override, for an off-site href that starts a flow
- * the reader should stay in. Call-site props apply last, so a passed
- * `target`/`rel` still wins.
+ * Internal and external are decided from the href, never at the call site —
+ * ../href.ts holds that decision, and Button, Badge and Card make the same one.
+ * `newTab` and `external` are the overrides. Call-site props apply last, so a
+ * passed `target`/`rel` still wins.
  *
  * The router is `next-view-transitions`, imported rather than injected. Every
  * project on this package is a Next app and wants the same link, and a factory
@@ -221,13 +229,12 @@ const linkClass = (tone = "muted", className) => cn(toneClass(tone), "font-mediu
  * not be imported by name. One call site ended up on the unbound version that
  * way and lost its decoration.
  */
-export function TypographyLink({ href, children, tone = "muted", newTab, addArrow, className, ...props }) {
+export function TypographyLink({ href, children, tone = "muted", external: leavesApp, newTab, addArrow, className, ...props }) {
     const style = linkClass(tone, className);
-    const external = /^[a-z][a-z0-9+.-]*:/i.test(href);
+    const { Component, props: link, external } = resolveLink(href, {
+        external: leavesApp,
+        newTab,
+    });
     const body = (_jsxs(_Fragment, { children: [children, addArrow && (_jsx("svg", { "aria-hidden": "true", className: "ml-1 inline size-3.5 align-middle", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: external ? "M7 17 17 7M7 7h10v10" : "M5 12h14M12 5l7 7-7 7" }) }))] }));
-    if (external) {
-        const away = newTab ?? href.startsWith("http");
-        return (_jsx("a", { href: href, className: style, ...(away ? { target: "_blank", rel: "noopener noreferrer" } : {}), ...props, children: body }));
-    }
-    return (_jsx(Link, { href: href, className: style, ...props, children: body }));
+    return (_jsx(Component, { className: style, ...link, ...props, children: body }));
 }

package/llms.txt

@@ -5,8 +5,8 @@ content blocks, a long-form essay shell, token and theme CSS, and build-time
 tooling for SEO, OG cards, lint rules and contrast checks.
 
 This file is for coding agents working in an app that consumes the package. It
-covers what to import and the mistakes that do not produce an error. Full
-reference: https://github.com/supertypeai/foundations
+covers what to import, how the copy should read, and the mistakes that pass
+silently. Full reference: https://github.com/supertypeai/foundations
 
 ## Rules
 
@@ -21,6 +21,11 @@ reference: https://github.com/supertypeai/foundations
 4. **Use colour tokens, never literal colours.** `bg-card`, `text-foreground`,
    `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.
+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.
 
 ## Which component
 
@@ -40,6 +45,7 @@ reference: https://github.com/supertypeai/foundations
 | a number or metric | `TypographyStat` | root |
 | inline code | `TypographyInlineCode` | root |
 | a link | `TypographyLink` | root |
+| 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` |
 | a status label, count or chip | `Badge` | `/blocks` |
@@ -61,15 +67,15 @@ 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`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone` |
+| `@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/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 — spread this), `designConfig` (the same set wrapped as a flat-config entry). The five builders `colourRules`, `typographyRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are still exported, but spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
+| `@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, tinted inks at 4.5:1, labels against their own fill), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast`, `tokenCuts` (which cuts a token ships — fill, the label printed on it, the hue as words; the taxonomy `checkSignals` measures). 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), `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
 
@@ -77,51 +83,100 @@ reference: https://github.com/supertypeai/foundations
 - `TypographyH2`: `variant?`, plus `divider?: boolean` for a rule underneath.
 - `TypographyP`: `variant?: "ui" | "prose"` (default `ui`), `tone?: "default" | "muted"`.
 - `TypographyMuted`, `TypographyProse`, `TypographyProseList` are presets. The
-  prop each one pins is removed from its type, so passing it will not compile.
+  prop each one pins is dropped from its type, so passing it fails to compile.
 - `TypographyCaption`, `TypographyLabel`, `TypographySmall`: `size?: "sm" | "xs" | "2xs" | "inherit"`, `as?`.
 - `TypographyEyebrow`: `tone?: "heading" | "label"`, `as?`.
 - `TypographyStat`: `size?: "inherit" | "card" | "panel" | "page" | "display"`, `figures?: "tabular" | "proportional"`. Keep tabular where a value updates in place.
-- `TypographyLink`: `href` (required), `tone?: Tone` (default `muted`), `addArrow?`, `newTab?`. Internal versus external is decided from the href.
-- `TypographyHighlight`: `tone?: HighlightTone` — `"primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, `seed?: number`. Deliberately NOT `Tone`: this axis is categorical (which one it is), not semantic (what it means), which is the same split theme.css draws between the earth swatches and the status tokens.
+- `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.
-- `Tone` — the one semantic colour vocabulary, shared by `Button`, `Callout` and `TypographyLink`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`. Seven tones, seven tokens, one to one — that is the bar for adding one. There is no `neutral` (that is `muted`, the word the rest of the package uses), no `foreground` (also `muted`), no `accent` (that is `--primary`'s hover tint, so a washed `primary` renders the same thing) and no `info` (`success | warn | destructive` is already the whole triad). `brand` falls back to `--primary` in an app that defines no `--brand`.
-- `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, `render` for the element to become. Variant is how much ink it spends; tone is what the ink means — separate axes, so a quiet delete is `variant="ghost" tone="destructive"`, not a `destructive` variant.
-- `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`. Same axes and same spellings as `Button`, minus `link` — a badge is not a link. There is no `warning` or `supertype` variant; those were `tone="warn"` and `tone="brand"` under invented names.
+- `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.
+- `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`.
 - `DisclosureGroup`: `type?: "multiple" | "single"`, `defaultValue` (matches the title string).
-- `TabsList`: `variant?: "default" | "line"`, `tone?: Tone` (default `primary`) — the tone
-  inks the marker only: on `line` the underline and the active icon. The boxed track's
-  marker is deliberately flat, so a tone there paints nothing.
+- `TabsList`: `variant?: "default" | "line"`, `tone?: Tone` (default `primary`). The tone
+  inks the marker alone, which on `line` means the underline and the active icon. The
+  boxed track keeps its marker flat, so a tone there paints nothing.
 - `TabGroup`: `tabs: readonly TabItem[]` (`{ value, label, icon?, content }`), `defaultValue?`,
   `value?`, `onValueChange?`, `variant?`, `tone?`, `iconPosition?: "inline-start" | "inline-end"`.
-  `icon` is an element (`<Icons.Mic />`); the trigger sizes and inks it. Reach for it
-  whenever the tabs are data — do not rebuild it over `Tabs`/`TabsTrigger`.
+  `icon` is an element (`<Icons.Mic />`) that the trigger sizes and inks. Reach for it
+  whenever the tabs are data, and compose `Tabs`/`TabsTrigger` by hand only for a shape
+  it cannot express.
+
+## Writing copy
+
+Every string a reader sees goes through this: page copy, section notes, button
+labels, callout titles, error messages, and the comments you leave in the file.
+Write the way a person writes when they know the subject and respect the reader's
+time.
+
+- **Say the thing.** State what is true and move on. Skip the setup sentence, the
+  restatement, and the closing summary of what you just said.
+- **Define forwards.** "A tone sets three variables and the component paints from
+  them" over "the component does not branch on the tone". Reach for a negative
+  only when the absence is the point.
+- **One em dash per page, at most.** Prefer a full stop, a comma, or a colon. The
+  same goes for a parenthetical aside mid-sentence.
+- **No arrow glyphs in prose.** Write "3.44:1 in light, 6.75:1 in dark" rather
+  than joining the two with an arrow. Where a UI genuinely points at something,
+  render a real icon.
+- **Watch the tacked-on clause.** "…, and it is the shape to reach for", "…, and
+  it exists so that…". The second half is usually the point: lead with it, or
+  make it its own sentence.
+- **Break the triples.** "X, Y, and Z" as a rhetorical flourish, three clauses
+  joined by "and", and the "not just A, but B" shape all read as machine prose.
+  Two items, or a list.
+- **Cut the throat-clearing.** No "it is worth noting", "it is important to",
+  "simply", "just", "of course", "in other words". No "this is not X, it is Y".
+- **Skip the rationale.** A note explains what the reader needs to use the thing.
+  Design history, near-misses, and the case for a decision go in the commit
+  message or the docs, not in the copy.
+- **Concrete over abstract.** Name the class, the prop, the file. "Five
+  components take the prop" beats "several components".
+- **Vary the sentences.** A paragraph of same-length clauses reads as generated
+  even when every sentence is true.
+- **Headings are labels.** "How it stays current", not "Why it cannot go stale".
+
+Code samples and commit messages stay conventional. This is about prose.
 
 ## Common mistakes
 
-- `<p className="text-sm text-muted-foreground">` — use `<TypographyMuted>`.
-- `<h2 className="text-lg font-semibold">` — use `<TypographyH2>`, or
-  `headingClass()` if you must pass classes to someone else's component.
+- `<p className="text-sm text-muted-foreground">`: use `<TypographyMuted>`.
+- `<h2 className="text-lg font-semibold">`: use `<TypographyH2>`, or
+  `headingClass()` to pass classes into someone else's component.
 - Importing `Card`, `Callout` or `Button` from `@supertype.ai/foundations`. They
   live in `@supertype.ai/foundations/blocks`.
-- `<Button variant="destructive">` or `variant="secondary"` — those are tones, not
-  variants. Write `variant="soft" tone="destructive"`, `variant="solid" tone="secondary"`.
-- `<Button size="icon-sm">` — there is one size ladder. Write `size="sm" icon`.
-- `<Badge variant="warning">` / `variant="supertype"` — tones, and misspelled ones.
+- `<Button variant="destructive">` or `variant="secondary"`: those are tones.
+  Write `variant="soft" tone="destructive"`, `variant="solid" tone="secondary"`.
+- `<Button size="icon-sm">`: one size ladder. Write `size="sm" icon`.
+- `<Badge variant="warning">` or `variant="supertype"`: tones, and misspelled ones.
   Write `variant="outline" tone="warn"` and `variant="solid" tone="brand"`.
-- `tone="neutral"`, `tone="foreground"` or `tone="accent"` — all three were
-  removed when the tone lists merged. Write `tone="muted"` for the first two and
-  `tone="primary"` for the third.
-- An `<a>` or `<Link>` styled by hand to look like a button. Pass it as
-  `render={<Link href="/x" />}`; the anchor keeps its link semantics.
-- `<TypographyMuted tone="default">` — a type error. Use `TypographyP`.
+- `tone="neutral"`, `tone="foreground"` or `tone="accent"`: all three went when the
+  tone lists merged. Write `tone="muted"` for the first two, `tone="primary"` for
+  the third.
+- An `<a>` or `<Link>` styled by hand to look like a button, and equally
+  `render={<a href="/x" />}` or `render={<Link href="/x" />}` on anything that
+  takes an `href`. Write `<Button href="/x">`. `Button`, `Badge`, `Card` and
+  `TypographyLink` all take `href` and route it through one rule
+  (`resolveLink`): a scheme leaves the app and gets `target`/`rel`, a `#hash`
+  stays a plain anchor, everything else goes through the router's `Link` and
+  keeps the view transition. A hand-passed anchor skips all of that. `render` is
+  for an element that is genuinely not a link — and for `RailLink`, which takes a
+  router `Link` that way on purpose, since `essay/rail.tsx` has to import without
+  Next.
+- Exporting a constant from a `"use client"` module and importing it into a server
+  component. It crosses the boundary as a stub, not a string, so an `href` built that
+  way arrives as a function. Keep shared constants in a plain module.
+- `<TypographyMuted tone="default">`: a type error. Use `TypographyP`.
 - Binding fonts with `font.className` instead of `font.variable`. The className
   form sets `font-family` on the element and leaves the roles unresolved.
 - Omitting `@source '../node_modules/@supertype.ai/foundations/dist/**/*.js'` from
   the CSS entry. Tailwind then purges every class the package ships.
 - Omitting `@import "@supertype.ai/foundations/theme.css"`. `tokens.css` names the
   colour roles but holds no values, so the whole palette resolves to nothing.
-- Using `Accordion` for a static FAQ. `Disclosure` needs no JavaScript.
+- Using `Accordion` for a static FAQ. `Disclosure` runs on the browser alone.
 - Adding a second `@custom-variant dark`. `tokens.css` already binds it.
 
 Run `npx foundations doctor` in the app to check the last four.
@@ -130,8 +185,8 @@ Run `npx foundations doctor` in the app to check the last four.
 
 Two classes change how everything renders, and both go on `<html>` or a subtree:
 
-- `.dark` re-points every colour token. It is bound by `tokens.css`, not by the
-  OS setting.
+- `.dark` re-points every colour token. `tokens.css` binds it to the class, so
+  the OS setting leaves it alone.
 - `.editorial` gives the heading role to the serif at weight 400 and retunes the
   whole heading ladder against an 18px body, instead of the product's 13px.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "license": "MIT",
   "publishConfig": {
     "access": "public",