@supertype.ai/foundations 0.1.28 → 0.1.30

package/dist/typography/header.d.ts

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

@@ -25,9 +25,14 @@ import { TextAs } from "./as.js";
  * respelling it: a second literal here is a level that forked, and a literal
  * weight beside the face survives into `.editorial` and synthesises the
  * single-weight serif. viably asserts there is exactly one of these strings.
+ *
+ * Exported so a non-heading can ask for the face alone. `headingClass()` below is the whole
+ * h2 ramp — face, anchor offset, margin reset, rung — and is right only for something that
+ * IS a heading wearing another tag. A pull quote is not, and took the ramp anyway because
+ * the face had no door, arriving with a `scroll-m-20` for an anchor it does not have.
  */
-const HEADING_FACE = "font-heading font-[number:var(--heading-weight)]";
-const HEADING_BASE = `scroll-m-20 ${HEADING_FACE} text-foreground`;
+export const headingFace = "font-heading font-[number:var(--heading-weight)]";
+const HEADING_BASE = `scroll-m-20 ${headingFace} text-[color:var(--ink,var(--foreground))]`;
 const h1Variants = cva(`${HEADING_BASE} tracking-tight`, {
     variants: {
         variant: {
@@ -93,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",
         },
@@ -103,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.
@@ -14,16 +13,18 @@ import type { ComponentProps } from "react";
 declare const MARKER_TONES: {
     readonly primary: "var(--primary)";
     readonly success: "var(--success)";
-    readonly ochre: "var(--ochre-foreground)";
-    readonly terracotta: "var(--terracotta-foreground)";
-    readonly sage: "var(--sage-foreground)";
-    readonly fig: "var(--fig-foreground)";
+    readonly ochre: "var(--ochre-ink)";
+    readonly terracotta: "var(--terracotta-ink)";
+    readonly sage: "var(--sage-ink)";
+    readonly fig: "var(--fig-ink)";
 };
 export type HighlightTone = keyof typeof MARKER_TONES;
 /**
  * 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.
@@ -15,10 +14,10 @@ import { cn } from "../cn.js";
 const MARKER_TONES = {
     primary: "var(--primary)",
     success: "var(--success)",
-    ochre: "var(--ochre-foreground)",
-    terracotta: "var(--terracotta-foreground)",
-    sage: "var(--sage-foreground)",
-    fig: "var(--fig-foreground)",
+    ochre: "var(--ochre-ink)",
+    terracotta: "var(--terracotta-ink)",
+    sage: "var(--sage-ink)",
+    fig: "var(--fig-ink)",
 };
 /** Wash density at a fraction of the theme's base alpha. */
 const ink = (weight) => `color-mix(in srgb, var(--marker) calc(var(--marker-alpha) * ${weight}), transparent)`;
@@ -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,12 +1,14 @@
+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";
 import { type WithAs } from "./as.js";
 /** The body layer: two axes and no more. A paragraph picks a rung and an ink; a
  * caption is always secondary ink and picks a size. `lead` was a third rung a
  * breakpoint away from `prose`, and its standfirst role is now the eyebrow's. */
 declare const pVariants: (props?: ({
     variant?: "ui" | "prose" | null | undefined;
-    tone?: "default" | "muted" | null | undefined;
+    tone?: "muted" | "default" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ParagraphVariants = VariantProps<typeof pVariants>;
 export declare function TypographyP({ className, variant, tone, children, ...props }: ComponentProps<"p"> & ParagraphVariants): import("react").JSX.Element;
@@ -100,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>;
@@ -113,39 +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;
-/**
- * A statement about the surface, not the link: `foreground` inside a paragraph,
- * `primary` when the link is the point of the line, `secondary` for a note
- * beneath a hero where `primary` would compete with the CTA beside it.
- */
-declare const LINK_TONES: {
-    readonly foreground: "font-medium text-foreground";
-    readonly primary: "font-medium text-primary";
-    readonly secondary: "text-secondary-ink";
-};
-export type LinkTone = keyof typeof LINK_TONES;
-type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & {
+type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & LinkBehavior & {
     href: string;
     children: ReactNode;
-    tone?: LinkTone;
-    /** Defaults on for an off-site link. Turn it off for one that starts a flow the reader should stay in. */
-    newTab?: boolean;
+    tone?: Tone;
     /**
      * 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
@@ -153,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,7 +1,8 @@
 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";
 import { TextAs } from "./as.js";
 /** The body layer: two axes and no more. A paragraph picks a rung and an ink; a
  * caption is always secondary ink and picks a size. `lead` was a third rung a
@@ -18,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" },
@@ -33,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 });
 }
@@ -85,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",
@@ -126,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",
@@ -187,29 +191,37 @@ 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: `foreground` inside a paragraph,
- * `primary` when the link is the point of the line, `secondary` for a note
- * beneath a hero where `primary` would compete with the CTA beside it.
+ * A statement about the surface, not the link: `muted` inside a paragraph,
+ * `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.
+ *
+ * This was `foreground | primary | secondary`, a private list whose first member
+ * was "no meaning at all" spelled a third way — `foreground` here, `muted` in
+ * Callout, `default` on a button. Now it is ../tone.ts, the same seven the other
+ * two take, and the weight is uniform: `secondary` alone used to skip
+ * `font-medium`, which read as a lighter link rather than a differently-coloured
+ * one.
  */
-const LINK_TONES = {
-    foreground: "font-medium text-foreground",
-    primary: "font-medium text-primary",
-    secondary: "text-secondary-ink",
-};
+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 = "foreground", className) => cn(LINK_TONES[tone], 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
@@ -217,13 +229,12 @@ const linkClass = (tone = "foreground", className) => cn(LINK_TONES[tone], LINK_
  * 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 = "foreground", 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,14 +45,18 @@ 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` |
 | a link card, or a grid of them | `Card`, `Cards` | `/blocks` |
 | an aside, warning or note | `Callout` | `/blocks` |
 | numbered instructions | `Steps`, `Step` | `/blocks` |
 | an FAQ or collapsible, no JS | `Disclosure`, `DisclosureGroup` | `/blocks` |
 | an animated accordion | `Accordion` (client) | `/blocks` |
-| tabbed content | `Tabs` or `TabGroup` (client) | `/blocks` |
+| tabbed content | `TabGroup` when the tabs are data, `Tabs` to compose by hand (client) | `/blocks` |
 | a long-form article page | `EssayHeader` + `EssayLayout` + `EssaySection` | `/essay` |
+| an article whose body is prose or MDX | `EssayHeader` + `ReadingLayout` | `/essay` |
 | a post meta row (date, read time, tags) | `PostMetaRow` and friends | `/essay` |
 | a table of contents | `TableOfContents`, `ReadingRail` | `/essay` |
 | page metadata and JSON-LD | `createSeo` | `/seo` |
@@ -58,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`, `eyebrowClass`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `LinkTone`, `HighlightTone` |
-| `@supertype.ai/foundations/blocks` | `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `Tab`, `SEGMENT` |
+| `@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`, `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/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` | `designConfig` (the whole set as one flat-config entry), plus `colourRules`, `typographyRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` for building your own. Types: `FlatConfigEntry`, `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`. Types: `Rgb`, `Theme`, `LegibilityFailure`. 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
 
@@ -74,32 +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?: "foreground" | "primary" | "secondary"`, `addArrow?`, `newTab?`. Internal versus external is decided from the href.
-- `TypographyHighlight`: `tone?: "primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, `seed?: number`.
+- `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.
-- `Callout`: `tone?: "muted" | "destructive" | "warn" | "accent"`, `density?: "compact" | "editorial"`, `title`, `icon`, `action`.
+- `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"`.
+- `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 />`) 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.
-- Importing `Card` or `Callout` from `@supertype.ai/foundations`. They live in
-  `@supertype.ai/foundations/blocks`.
-- `<TypographyMuted tone="default">` — a type error. Use `TypographyP`.
+- `<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.
+  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 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.
@@ -108,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.28",
+  "version": "0.1.30",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -117,6 +117,7 @@
     "next": "^15.5.7",
     "next-view-transitions": "^0.3.5",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.7.0",
     "vitest": "4.1.11"
   },