@supertype.ai/foundations 0.1.29 → 0.1.31

package/README.md

@@ -4,8 +4,9 @@
 [![npm](https://img.shields.io/npm/v/%40supertype.ai%2Ffoundations?logo=npm&color=cb3837)](https://www.npmjs.com/package/@supertype.ai/foundations)
 [![license](https://img.shields.io/npm/l/%40supertype.ai%2Ffoundations?color=blue)](LICENSE)
 
-[The foundations philosophy](https://supertypeai.github.io/foundations/philosophy/) lays out the Raison d'être better, but the crux is that it is a reusable design system that binds typography primitives, content blocks, the long-form essay shell, the token and theme CSS, and the build-time tooling that keep baseline quality high (SEO, OG cards, lint rules, contrast
-checks) in a single package. Used by Supertype's own projects like [Viably work operating system](https://viably.app) and [supertype.ai](https://supertype.ai), it is also MIT-licensed and available for any Next.js 15+ project built atop Tailwind and Shadcn.
+[The foundations philosophy](https://supertypeai.github.io/foundations/philosophy/) explains the reasoning in more detail, but the short version is simple: this is a reusable design system for typography primitives, content blocks, the long-form essay shell, token and theme CSS, and the build-time tooling that keeps the baseline consistent. That includes SEO, OG cards, lint rules, and contrast checks.
+
+It is used in Supertype projects like [Viably work operating system](https://viably.app) and [supertype.ai](https://supertype.ai), and it is MIT-licensed for any Next.js 15+ app built on Tailwind and Shadcn.
 
 ```sh
 yarn add @supertype.ai/foundations
@@ -31,11 +32,11 @@ yarn example:install   # once, to install Next, the peers and the package
 yarn example           # then open http://localhost:3000
 ```
 
-[`examples/site`](examples/site) renders every component along with the code, and include whole-page [recipes](examples/site/app/_recipes) to copy into your project. Comes with the `dark` and `.editorial` switches.
+[`examples/site`](examples/site) renders every component with the code next to it, and includes whole-page [recipes](examples/site/app/_recipes) you can copy into your project. It also includes the `dark` and `.editorial` switches.
 
 ## Initialization and Diagnostics
 
-This package also ships a CLI that writes the CSS for you and checks the rest:
+This package includes a CLI that writes the CSS for you and checks the rest:
 
 ```sh
 npx @supertype.ai/foundations init      # edits your CSS entry, prints the rest
@@ -43,7 +44,7 @@ npx @supertype.ai/foundations doctor    # checks this app against everything bel
 ```
 
 `init` edits one file: the CSS entry that imports Tailwind. It adds the imports
-you are missing and reorders anything that is out of place. Run it with `--dry-run` first to see the patch. Everything else it prints for you to paste (the font binding, and the `llms.txt` lines for a coding agent).
+you are missing and reorders anything that is out of place. Run it with `--dry-run` first to preview the patch. Everything else it prints for you to paste is the font binding and the `llms.txt` lines for a coding agent.
 
 The steps performed by `init` are written out below anyway. See [the CLI](docs/cli.md) for the full list of checks and details.
 
@@ -59,13 +60,13 @@ Peers are React 19+, Next 15+, `next-view-transitions` 0.3+ and `@base-ui/react`
 <details>
 <summary>Installing from a git tag instead</summary>
 
-Every release is tagged as well as published, so a commit can be installed
-directly — useful for trying an unreleased fix. Pin a tag, never `#main`: an
-untagged git dependency re-resolves to a different commit on any fresh install.
+Every release is tagged and published, so a commit can be installed directly
+when you want to try an unreleased fix. Pin a tag rather than `#main`: an
+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.29"
+"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.1.31"
 ```
 
 </details>
@@ -85,15 +86,16 @@ untagged git dependency re-resolves to a different commit on any fresh install.
 ```
 
 **The `@source` line is required.** Tailwind does not scan `node_modules` by
-default, so without it every class is purged and the components
-render with no styles at all.
+default, so without it the package&rsquo;s classes get purged and the
+components render without styles.
 
-**`theme.css` is required.** `tokens.css` names the colour roles; `theme.css` is
-what gives them values. Without it color utility can't be resolved, so the page renders unpainted with no error. It also carries
-`--secondary-ink`, `--subtle-foreground`, the four earth tones the marker
-highlight uses, and the `accordion-down` and `accordion-up` keyframes. Skip it
-only if you declare every role yourself; `foundations doctor` fails when neither
-is true.
+**`theme.css` is required.** `tokens.css` names the colour roles, and
+`theme.css` gives them values. Without it, the colour utilities cannot be
+resolved, so the page renders unpainted without an obvious error. It also
+carries `--secondary-ink`, `--subtle-foreground`, the four earth tones used
+for marker highlights, and the `accordion-down` and `accordion-up` keyframes.
+Skip it only if you declare every role yourself; `foundations doctor` fails if
+neither path is true.
 
 ### 3. Bind the fonts
 
@@ -112,8 +114,10 @@ const serif = Average({ variable: "--font-average", weight: "400", subsets: ["la
 <html className={`${sans.variable} ${mono.variable} ${serif.variable} font-sans`}>
 ```
 
-**Bind with `.variable`, never `.className`.** A className sets `font-family` on
-the element itself and leaves the roles unresolved, causing a mismatch where the page renders one typeface while every `font-sans` and `font-heading` utility on it renders another.
+**Bind with `.variable`, never `.className`.** A className sets `font-family`
+on the element itself and leaves the roles unresolved, which causes a mismatch
+where the page renders one typeface while the `font-sans` and `font-heading`
+utilities render another.
 
 ### 4. Check the wiring
 
@@ -213,9 +217,9 @@ only from this package, so you can paste it into your app and it compiles.
 
 ## For coding agents
 
-The package ships an `llms.txt` with the public API, the rules, and the mistakes
-that do not produce an error. Point your agent at it once and it stops
-hand-writing `text-sm text-muted-foreground` where a primitive exists:
+The package includes an `llms.txt` with the public API, the rules, and the
+mistakes that do not produce an error. Point your agent at it once and it stops
+writing `text-sm text-muted-foreground` where a primitive already exists:
 
 ```md
 <!-- CLAUDE.md, AGENTS.md, or your agent's equivalent -->

package/bin/foundations.mjs

@@ -518,9 +518,9 @@ const checkContrast = async (appRoot) => {
   const cssFile = findCssEntry(appRoot);
   if (!cssFile) return out;
 
-  let checkLegibility, checkSignals, formatFailures;
+  let checkLegibility, checkSignals, checkHairlines, formatFailures;
   try {
-    ({ checkLegibility, checkSignals, formatFailures } = await import(
+    ({ checkLegibility, checkSignals, checkHairlines, formatFailures } = await import(
       join(pkgRoot, "dist/contrast.js")
     ));
   } catch {
@@ -533,6 +533,9 @@ const checkContrast = async (appRoot) => {
   const groups = [
     ["error", "structural ink below 4.5:1", checkLegibility(css)],
     ["warn", "mark or tinted ink below its bar", checkSignals(css)],
+    // A rule owes no WCAG bar, so this can never be an error. It is here because
+    // an app that retints --border almost always retints one theme.
+    ["warn", "hairline too faint to read as a rule", checkHairlines(css)],
   ];
 
   for (const [level, title, failures] of groups) {

package/dist/blocks/accordion.js

@@ -1,6 +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 { INK_ON_CARD } from "../tone.js";
 /**
  * A disclosure group: `<details>`/`<summary>`, no JS, correct before hydration.
  *
@@ -55,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", 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

@@ -1,5 +1,6 @@
 import type { ComponentProps, ReactElement } from "react";
 import { type VariantProps } from "class-variance-authority";
+import { type LinkBehavior } from "../href.js";
 declare const badge: (props?: ({
     tone?: "muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive" | null | undefined;
     size?: "sm" | "xs" | null | undefined;
@@ -9,7 +10,8 @@ declare const badge: (props?: ({
 export type BadgeLook = VariantProps<typeof badge>;
 export declare function badgeVariants(props?: Parameters<typeof badge>[0]): string;
 /**
- * A `span` unless `render` says otherwise — cloned rather than run through a
+ * A `span`, an anchor when given an `href` — a tag pill leading to its listing —
+ * and whatever `render` says otherwise — cloned rather than run through a
  * `useRender` hook, which is what viably's badge did. A hook would make every
  * badge in the tree a client component to serve the one call site that renders
  * an anchor, and a badge is a label: it should cost nothing on the server. This
@@ -18,7 +20,10 @@ export declare function badgeVariants(props?: Parameters<typeof badge>[0]): stri
  * The `[a]:hover` rules above light up on their own when an anchor is the parent
  * or the rendered element.
  */
-export declare function Badge({ className, variant, tone, size, pill, render, ...props }: ComponentProps<"span"> & BadgeLook & {
+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/badge.js

@@ -2,8 +2,9 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { cva } from "class-variance-authority";
 import { cn } from "../cn.js";
 import { renderAs } from "./render-as.js";
+import { resolveLink } from "../href.js";
 import { FOCUS_RING } from "./focus.js";
-import { TONE, TONE_SURFACE, impliedTone } from "../tone.js";
+import { INK_ON_FILL, TONE, TONE_SURFACE, impliedTone } from "../tone.js";
 // ---------------------------------------------------------------------------
 // A label that is not a control. Same two axes as Button, and for the same
 // reason: the two apps had each grown their own list, and the lists disagreed
@@ -44,7 +45,7 @@ const badge = cva(cn("inline-flex w-fit shrink-0 items-center justify-center gap
         },
         pill: { true: "rounded-full", false: "" },
         variant: {
-            solid: "bg-(--tone-fill) text-(color:--tone-ink) [a]:hover:bg-(--tone-fill-hover)",
+            solid: `bg-(--tone-fill) text-(color:--tone-ink) [a]:hover:bg-(--tone-fill-hover) ${INK_ON_FILL}`,
             soft: "bg-(--tone-wash) text-(color:--tone-hue) [a]:hover:bg-(--tone-wash-hover)",
             outline: "border-(color:--tone-line) text-(color:--tone-hue) [a]:hover:bg-(--tone-wash)",
             ghost: "text-(color:--tone-hue) hover:bg-(--tone-wash)",
@@ -56,7 +57,8 @@ export function badgeVariants(props = {}) {
     return badge({ tone: props?.tone ?? impliedTone(props?.variant), ...props });
 }
 /**
- * A `span` unless `render` says otherwise — cloned rather than run through a
+ * A `span`, an anchor when given an `href` — a tag pill leading to its listing —
+ * and whatever `render` says otherwise — cloned rather than run through a
  * `useRender` hook, which is what viably's badge did. A hook would make every
  * badge in the tree a client component to serve the one call site that renders
  * an anchor, and a badge is a label: it should cost nothing on the server. This
@@ -65,7 +67,7 @@ export function badgeVariants(props = {}) {
  * The `[a]:hover` rules above light up on their own when an anchor is the parent
  * or the rendered element.
  */
-export function Badge({ className, variant, tone, size, pill, render, ...props }) {
+export function Badge({ className, variant, tone, size, pill, render, href, external, newTab, ...props }) {
     const resolved = tone ?? impliedTone(variant);
     const classes = cn(badge({ variant, tone: resolved, size, pill, className }));
     const marks = {
@@ -73,6 +75,10 @@ export function Badge({ className, variant, tone, size, pill, render, ...props }
         "data-variant": variant ?? "solid",
         "data-tone": resolved,
     };
+    if (href !== undefined) {
+        const { Component, props: link } = resolveLink(href, { external, newTab });
+        return (_jsx(Component, { ...marks, ...link, className: classes, ...props }));
+    }
     const as = renderAs(render, classes, { ...marks, ...props });
     if (as)
         return as;

package/dist/blocks/button.d.ts

@@ -1,5 +1,7 @@
+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";
 declare const button: (props?: ({
     tone?: "muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive" | null | undefined;
     size?: "sm" | "xs" | "md" | "lg" | "xl" | null | undefined;
@@ -15,10 +17,29 @@ export type ButtonLook = VariantProps<typeof button>;
  */
 export declare function buttonVariants(props?: Parameters<typeof button>[0]): string;
 /**
- * A non-`<button>` render element bypasses the primitive on purpose: Base UI
+ * `href` makes the button a link — the anchor is the button, and where the href
+ * goes is ../href.ts's decision, not the call site's. `render={<a href="…" />}`
+ * did this before, and got a bare anchor: no router, so a CTA reloaded the page
+ * and lost the view transition, and an off-site href never grew a `rel`.
+ *
+ * Either way a non-`<button>` element bypasses the primitive on purpose: Base UI
  * always stamps `type="button"` or `role="button"`, and the latter drops an
- * anchor out of screen-reader link navigation. Cloning gives it the classes and
- * nothing else.
+ * anchor out of screen-reader link navigation. `render` remains for an element
+ * that is genuinely neither — a `<label>`, a menu item.
  */
-export declare function Button({ className, variant, tone, size, icon, pill, render, nativeButton, ...props }: ButtonPrimitive.Props & ButtonLook): import("react").JSX.Element;
+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

@@ -4,8 +4,9 @@ import { Button as ButtonPrimitive } from "@base-ui/react/button";
 import { cva } from "class-variance-authority";
 import { cn } from "../cn.js";
 import { renderAs } from "./render-as.js";
+import { resolveLink } from "../href.js";
 import { FOCUS_RING } from "./focus.js";
-import { TONE, TONE_SURFACE, impliedTone } from "../tone.js";
+import { INK_ON_FILL, TONE, TONE_SURFACE, impliedTone } from "../tone.js";
 // ---------------------------------------------------------------------------
 // The control both apps were re-declaring. viably and ssite each carried their
 // own `cva` with its own variant list — `default | secondary | accent |
@@ -59,7 +60,7 @@ cn(FOCUS_RING, "focus-visible:border-ring"), "active:not-aria-[haspopup]:transla
         /** Full-round corners. Marketing surfaces; also every filter chip. */
         pill: { true: "rounded-full", false: "" },
         variant: {
-            solid: "bg-(--tone-fill) text-(color:--tone-ink) hover:bg-(--tone-fill-hover)",
+            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)",
             ghost: "text-(color:--tone-hue) hover:bg-(--tone-wash)",
@@ -91,12 +92,17 @@ export function buttonVariants(props = {}) {
     return button({ tone: props?.tone ?? impliedTone(props?.variant), ...props });
 }
 /**
- * A non-`<button>` render element bypasses the primitive on purpose: Base UI
+ * `href` makes the button a link — the anchor is the button, and where the href
+ * goes is ../href.ts's decision, not the call site's. `render={<a href="…" />}`
+ * did this before, and got a bare anchor: no router, so a CTA reloaded the page
+ * and lost the view transition, and an off-site href never grew a `rel`.
+ *
+ * Either way a non-`<button>` element bypasses the primitive on purpose: Base UI
  * always stamps `type="button"` or `role="button"`, and the latter drops an
- * anchor out of screen-reader link navigation. Cloning gives it the classes and
- * nothing else.
+ * anchor out of screen-reader link navigation. `render` remains for an element
+ * that is genuinely neither — a `<label>`, a menu item.
  */
-export function Button({ className, variant, tone, size, icon, pill, render, nativeButton, ...props }) {
+export function Button({ className, variant, tone, size, icon, pill, render, nativeButton, href, external, newTab, ...props }) {
     const resolved = tone ?? impliedTone(variant);
     const classes = cn(button({ variant, tone: resolved, size, icon, pill, className }));
     // The resolved axes, stamped: a child can style off its parent's tone, and a
@@ -106,6 +112,10 @@ export function Button({ className, variant, tone, size, icon, pill, render, nat
         "data-variant": variant ?? "solid",
         "data-tone": resolved,
     };
+    if (href !== undefined) {
+        const { Component, props: link } = resolveLink(href, { external, newTab });
+        return (_jsx(Component, { ...marks, ...link, className: classes, ...props }));
+    }
     // `render.type !== "button"`: a plain <button/> still goes through the primitive, which
     // is what supplies the native semantics.
     const as = isValidElement(render) && render.type === "button"

package/dist/blocks/card.d.ts

@@ -1,4 +1,5 @@
 import type { ComponentProps, ReactNode } from "react";
+import { type LinkBehavior } from "../href.js";
 /** Two columns from `sm` up: a pair reads as a set rather than two panels. */
 export declare function Cards({ className, children, ...props }: ComponentProps<"div">): import("react").JSX.Element;
 export declare function CardHeader({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
@@ -18,17 +19,15 @@ type CardShorthand = {
     title?: ReactNode;
     description?: ReactNode;
     icon?: ReactNode;
-    /** Override the scheme sniff: an absolute URL home, or a relative one away. */
-    external?: boolean;
 };
 /**
  * Takes either shape: `title`/`href` fills the header, or compose the slots
  * directly. Unrecognised props pass through — MDX authors reach for the whole
- * HTML surface. An href with a scheme leaves the app; the rest route through
- * the router's Link.
+ * HTML surface. Where the href goes is ../href.ts's call, the same one Button
+ * and TypographyLink make.
  */
-export declare function Card({ href, className, external, title, description, icon, children, ...rest }: CardShorthand & {
+export declare function Card({ href, className, external, newTab, title, description, icon, children, ...rest }: CardShorthand & LinkBehavior & {
     href?: string;
     children?: ReactNode;
-} & Omit<ComponentProps<"a">, keyof CardShorthand | "href" | "children">): import("react").JSX.Element;
+} & Omit<ComponentProps<"a">, keyof CardShorthand | keyof LinkBehavior | "href" | "children">): import("react").JSX.Element;
 export {};

package/dist/blocks/card.js

@@ -1,8 +1,8 @@
 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 { toneClass } from "../tone.js";
-import { Link } from "next-view-transitions";
+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 }) {
     return (_jsx("div", { className: cn("my-6 grid gap-4 sm:grid-cols-2", className), ...props, children: children }));
@@ -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 " +
+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";
 /**
@@ -49,10 +49,10 @@ export function CardContent({ className, ...props }) {
 /**
  * Takes either shape: `title`/`href` fills the header, or compose the slots
  * directly. Unrecognised props pass through — MDX authors reach for the whole
- * HTML surface. An href with a scheme leaves the app; the rest route through
- * the router's Link.
+ * HTML surface. Where the href goes is ../href.ts's call, the same one Button
+ * and TypographyLink make.
  */
-export function Card({ href, className, external, title, description, icon, children, ...rest }) {
+export function Card({ href, className, external, newTab, title, description, icon, children, ...rest }) {
     const header = title || description || icon ? (_jsxs(CardHeader, { children: [icon || title ? (
             // The icon sits on the title's line and is its mark; stacked, it read as a
             // decoration the title happened to follow. `gap-2` is a gap between two
@@ -67,10 +67,6 @@ export function Card({ href, className, external, title, description, icon, chil
     if (!href) {
         return (_jsx("div", { className: cn(CARD_CLASS, className), ...shared, ...rest, children: body }));
     }
-    const leavesApp = external ?? /^[a-z][a-z0-9+.-]*:/i.test(href);
-    const classes = cn(CARD_CLASS, CARD_LINK_CLASS, className);
-    if (leavesApp) {
-        return (_jsx("a", { href: href, className: classes, target: "_blank", rel: "noopener noreferrer", ...shared, ...rest, children: body }));
-    }
-    return (_jsx(Link, { href: href, className: classes, ...shared, ...rest, children: body }));
+    const { Component, props: link } = resolveLink(href, { external, newTab });
+    return (_jsx(Component, { className: cn(CARD_CLASS, CARD_LINK_CLASS, className), ...link, ...shared, ...rest, children: body }));
 }

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/blocks/tabs.d.ts

@@ -36,17 +36,17 @@ export type TabItem = {
      * An element and not a component, which this briefly also took. `TabGroup` is a client
      * component, so a component reference handed to it from a server page is a function
      * crossing the RSC boundary, which React refuses at render; an element is already
-     * rendered and crosses fine. One accepted shape also spares the slot a branch, and it
-     * is the shape `Card`'s `icon` has always taken.
+     * rendered and crosses fine. One accepted shape also spares the slot a branch, and
+     * matches what `Card`'s `icon` has always taken.
      */
     icon?: ReactNode;
     content: ReactNode;
 };
 /**
  * The declarative shorthand: the tabs as data. `TabGroup` is to `Tabs` what
- * `DisclosureGroup` is to `Accordion`, and it is the shape to reach for — an app that
- * rebuilds it over the primitives ends up re-adding the icon, the change handler and the
- * stable value by hand.
+ * `DisclosureGroup` is to `Accordion`: the shape to reach for. An app that rebuilds it
+ * over the primitives ends up re-adding the icon, the change handler and the stable value
+ * by hand.
  *
  * Everything below the adapter is the same component the product surfaces use, so a tab
  * strip in the docs and one on a dashboard behave identically. The positional

package/dist/blocks/tabs.js

@@ -100,9 +100,9 @@ function TabIconSlot({ icon, position, }) {
 }
 /**
  * The declarative shorthand: the tabs as data. `TabGroup` is to `Tabs` what
- * `DisclosureGroup` is to `Accordion`, and it is the shape to reach for — an app that
- * rebuilds it over the primitives ends up re-adding the icon, the change handler and the
- * stable value by hand.
+ * `DisclosureGroup` is to `Accordion`: the shape to reach for. An app that rebuilds it
+ * over the primitives ends up re-adding the icon, the change handler and the stable value
+ * by hand.
  *
  * Everything below the adapter is the same component the product surfaces use, so a tab
  * strip in the docs and one on a dashboard behave identically. The positional

package/dist/cjs/eslint.js

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