@supertype.ai/foundations 0.1.28 → 0.1.30

package/dist/cjs/eslint.js

@@ -9,7 +9,9 @@ exports.colourRules = colourRules;
 exports.themeOverrideRules = themeOverrideRules;
 exports.surfaceAsInkRules = surfaceAsInkRules;
 exports.renamedTokenRules = renamedTokenRules;
+exports.linkRules = linkRules;
 exports.typographyRules = typographyRules;
+exports.designRules = designRules;
 exports.designConfig = designConfig;
 /** A className written as a plain string, or as a chunk of a template literal. */
 const classString = (pattern) => [
@@ -47,18 +49,48 @@ 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` was always the ink, under the other name.
+ * 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 = "terracotta|ochre|moss|fern|sage|stone|fig|cocoa";
 function renamedTokenRules() {
-    return rule("/(^| )(dark:|hover:|focus:|group-hover:)*(text|bg|border|ring|fill|stroke)-warn-foreground($| )/", "`warn-foreground` is the deprecated name for `warn-ink`. In this package `-foreground` is the label printed on a fill and `-ink` is the hue used as text; warn has no printed-on label, because orange carries white text at no lightness. Use warn-ink.");
+    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 [
@@ -105,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".',
                 },
             ]
             : []),
@@ -114,6 +146,16 @@ function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2xs 11 /
             : []),
     ];
 }
+function designRules({ accents, typography = true, ...type } = {}) {
+    return [
+        ...colourRules({ accents }),
+        ...(typography ? typographyRules(type) : []),
+        ...linkRules(),
+        ...themeOverrideRules(),
+        ...surfaceAsInkRules(),
+        ...renamedTokenRules(),
+    ];
+}
 /**
  * Every rule in one flat-config entry, ready to spread into eslint.config.js:
  *
@@ -126,20 +168,13 @@ function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2xs 11 /
  * half the set by accident. If you need a second scope, call this again with a
  * different `files` and no overlap.
  */
-function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], accents, weights, ramp, pairing, axis, } = {}) {
+function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], ...options } = {}) {
     return [
         {
             name: "@supertype.ai/foundations/design",
             files,
             rules: {
-                "no-restricted-syntax": [
-                    "error",
-                    ...colourRules({ accents }),
-                    ...typographyRules({ weights, ramp, pairing, axis }),
-                    ...themeOverrideRules(),
-                    ...surfaceAsInkRules(),
-                    ...renamedTokenRules(),
-                ],
+                "no-restricted-syntax": ["error", ...designRules(options)],
             },
         },
     ];

package/dist/contrast.d.ts

@@ -19,6 +19,26 @@ export declare function parseColor(value: string): Rgb | null;
 export declare function luminance([r, g, b]: Rgb): number;
 /** WCAG contrast ratio, 1:1 to 21:1. */
 export declare function contrast(a: Rgb, b: Rgb): number;
+/**
+ * APCA lightness contrast (Lc), the perceptual measure WCAG 3 is built on.
+ *
+ * It sits beside `contrast` because the two answer different questions and an
+ * ink ramp needs both. A WCAG ratio is polarity-blind: it reports the same
+ * number whether the text is dark on light or light on dark, when in fact dark
+ * glyphs on a bright field thin out and light glyphs on a dark field bloat. That
+ * blindness is what lets a ramp be ordered by ratio and still read flat — viably
+ * shipped a `--muted-foreground` measuring 72.5 Lc in light and 52.1 in dark,
+ * the same verdict from `contrast` on both sides and twenty points apart to a
+ * reader.
+ *
+ * Lc also states the term a ratio cannot: legibility is contrast times size, so
+ * a floor here is what says an ink comfortable at 16px is or is not comfortable
+ * on the 13px rung a dense product actually spends.
+ *
+ * Returned absolute. It is signed by polarity in the specification, and every
+ * caller so far asks "is this legible", never "which way round is it".
+ */
+export declare function lc(text: Rgb, background: Rgb): number;
 export interface LegibilityFailure {
     theme: Theme;
     ink: string;
@@ -36,6 +56,42 @@ export declare function checkLegibility(css: string, { minimum, inks, surfaces,
     surfaces?: string[] | undefined;
     themes?: Theme[] | undefined;
 }): LegibilityFailure[];
+/** What a token is: a surface or mark, a label printed on it, a hue used as words. */
+export interface TokenCuts {
+    /** The role itself — a surface, or a mark held to 3:1 against the page. */
+    fill: string;
+    /**
+     * The label printed *on* that fill. The only pair measured one against the
+     * other rather than against the page, which is why it is the only pair a
+     * swatch may print one on top of the other.
+     */
+    onFill?: string;
+    /**
+     * The same hue used as words, held to 4.5:1 against the page and never printed
+     * on the fill — there it measures about 1.2:1. Always `-ink`; the categorical
+     * hues shipped under `-foreground` until that was corrected, and the old names
+     * survive only as aliases the ESLint rules flag.
+     */
+    asInk?: string;
+}
+/**
+ * The cuts a token ships, read off the same three sets `checkSignals` measures.
+ *
+ * Exported because the alternative is every consumer keeping its own idea of
+ * which tokens are pairs — the docs site did, and got the categorical hues
+ * wrong, rendering `--ochre` as a lone square while its ink, the colour the
+ * marker highlight is painted with, appeared nowhere. A palette checked against
+ * one taxonomy and documented from another will drift, and the drift shows up as
+ * a page that is quietly wrong rather than a build that fails.
+ */
+export declare function tokenCuts(token: string): TokenCuts;
+/**
+ * The bar a rule owes, held apart from `checkSignals` because it is not a
+ * signal: nothing here carries meaning in its hue, it only has to be seen.
+ */
+export declare function checkHairlines(css: string, { themes }?: {
+    themes?: Theme[] | undefined;
+}): LegibilityFailure[];
 /**
  * The three bars a palette owes, run over the same engine as `checkLegibility`.
  * Without this the numbers in a theme's comments are claims, not measurements.

package/dist/contrast.js

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

package/dist/eslint.d.ts

@@ -20,15 +20,27 @@ export declare function colourRules({ accents, }?: ColourOptions): RestrictedSyn
  */
 export declare function themeOverrideRules(): RestrictedSyntax[];
 /**
- * `--muted` is a fill at L92%, so `text-muted` is ~1.1:1 — invisible, and it
- * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
+ * `--muted` is a fill at L92%, so `text-muted` lands at ~1.1:1. Invisible, and
+ * it shipped at 17 sites. `text-background` stays legal: inverse ink is a real
+ * role.
  */
 export declare function surfaceAsInkRules(): RestrictedSyntax[];
+export declare function renamedTokenRules(): RestrictedSyntax[];
 /**
- * `-foreground` means the label printed on a fill; `-ink` means the hue as
- * words. `warn-foreground` was always the ink, under the other name.
+ * `render={<a href="…" />}` on a component that takes an `href`. It reads as a
+ * styling choice and is a routing one: the cloned anchor skips the router, so
+ * the page fully reloads and the view transition is lost, and an off-site href
+ * never grows a `rel`. Button, Badge and Card each decide internal vs external
+ * from the href itself, so the anchor is never needed and cannot be right more
+ * often than the one shared rule is.
+ *
+ * Narrow on both axes, so it never fires on a line that is correct. Only those
+ * three components — `RailLink` deliberately takes a router element through
+ * `render`, because its module has to stay importable without Next. And only a
+ * bare `<a>`: `render={<Link/>}` is redundant beside `href` but it still routes,
+ * so it is not a bug.
  */
-export declare function renamedTokenRules(): RestrictedSyntax[];
+export declare function linkRules(): RestrictedSyntax[];
 export interface TypographyOptions {
     /** Three-weight ramp. Off for editorial, where 700 is a register not a shout. */
     weights?: boolean;
@@ -44,18 +56,40 @@ export interface TypographyOptions {
     /**
      * Flag a size class on a primitive that already owns a size axis. Off by
      * default for the same reason as `pairing`: it fails until the consumer has
-     * migrated, and the migration is the point.
+     * migrated, and that migration is the intended end state.
      */
     axis?: boolean;
 }
 export declare function typographyRules({ weights, ramp, pairing, axis, }?: TypographyOptions): RestrictedSyntax[];
+/**
+ * Every design rule, as one list.
+ *
+ * The builders below it are still exported, and spreading them by hand is
+ * what both consumers were doing — one of them into a flat config, the other
+ * into a legacy `.eslintrc`, and *both* of them had quietly left out
+ * `renamedTokenRules`, so neither would have flagged a deprecated token name.
+ * That is not a mistake either author made; it is what a five-name API costs
+ * every time somebody wires it up. Spread this instead, and a rule added here
+ * arrives in both apps on their next bump.
+ */
+export interface DesignRuleOptions extends ColourOptions, TypographyOptions {
+    /**
+     * Off for a surface that sets its own type ramp — a marketing page under
+     * `.editorial`, a mockup drawing the product at reduced scale. Everything
+     * about colour still applies: a deprecated token name is wrong on every
+     * surface, which is why this is a flag rather than an invitation to pick
+     * three of the five builders by hand.
+     */
+    typography?: boolean;
+}
+export declare function designRules({ accents, typography, ...type }?: DesignRuleOptions): RestrictedSyntax[];
 /** A flat-config entry, described structurally so the package needs no ESLint dependency. */
 export interface FlatConfigEntry {
     name: string;
     files: string[];
     rules: Record<string, unknown>;
 }
-export interface DesignConfigOptions extends ColourOptions, TypographyOptions {
+export interface DesignConfigOptions extends DesignRuleOptions {
     /** What the rules apply to. Narrow it to exclude generated or vendored code. */
     files?: string[];
 }
@@ -71,4 +105,4 @@ export interface DesignConfigOptions extends ColourOptions, TypographyOptions {
  * half the set by accident. If you need a second scope, call this again with a
  * different `files` and no overlap.
  */
-export declare function designConfig({ files, accents, weights, ramp, pairing, axis, }?: DesignConfigOptions): FlatConfigEntry[];
+export declare function designConfig({ files, ...options }?: DesignConfigOptions): FlatConfigEntry[];

package/dist/eslint.js

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

package/dist/essay/essay.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from "../cn.js";
-import { headingClass, TypographyEyebrow, TypographyH1, TypographyH2, TypographyH3, } from "../typography/header.js";
+import { headingFace, TypographyEyebrow, TypographyH1, TypographyH2, TypographyH3, } from "../typography/header.js";
 import { TypographyCaption, TypographyMuted, TypographyProse, } from "../typography/paragraph.js";
-import { EssayColumns } from "./layout.js";
+import { EssayAside, EssayBody, EssayColumns, PostMetaRow } from "./layout.js";
 import { TableOfContents } from "./contents.js";
 /** Pass-through: keeps the className the shell relies on for layout. */
 const PlainReveal = ({ children, className, }) => _jsx("div", { className: className, children: children });
@@ -31,19 +31,27 @@ const anchorIds = (sections) => {
 export function createEssay({ Reveal = PlainReveal, Glow = NoGlow, } = {}) {
     /** Left aligned: the eye has to reach the first line of prose either way. */
     function EssayHeader({ eyebrow, title, lede, byline, }) {
-        return (_jsxs("header", { className: "relative overflow-hidden pb-12 pt-16 sm:pt-24", children: [_jsx(Glow, { className: "-top-40 left-1/2 -translate-x-1/2", intensity: 0.16 }), _jsx(EssayColumns, { children: _jsxs(Reveal, { eager: true, className: "flex flex-col gap-6", children: [_jsx(TypographyEyebrow, { children: eyebrow }), _jsx(TypographyH1, { variant: "display", className: "text-balance", children: title }), lede && (_jsx(TypographyMuted, { className: "text-pretty text-xl leading-relaxed", children: lede })), byline && (_jsx(TypographyMuted, { className: "border-t border-border/60 pt-5 text-base", children: byline }))] }) })] }));
+        return (_jsxs("header", { className: "relative overflow-hidden pb-12 pt-16 sm:pt-24", children: [_jsx(Glow, { className: "-top-40 left-1/2 -translate-x-1/2", intensity: 0.16 }), _jsx(EssayColumns, { children: _jsxs(Reveal, { eager: true, className: "flex flex-col gap-6", children: [_jsx(TypographyEyebrow, { children: eyebrow }), _jsx(TypographyH1, { variant: "display", className: "text-balance", children: title }), lede && (_jsx(TypographyMuted, { className: "text-pretty text-xl leading-relaxed", children: lede })), byline && _jsx(PostMetaRow, { children: byline })] }) })] }));
     }
     /** The reading column, with the sticky index sitting in its left margin. */
     function EssayLayout({ index, children, }) {
-        return (_jsx(EssayColumns, { className: "pb-16 sm:pb-24", aside: _jsx("div", { className: "sticky top-24", children: _jsx(TableOfContents, { sections: index }) }), children: _jsx("div", { className: "flex flex-col gap-16 border-t border-border pt-12 @6xl:border-t-0 @6xl:pt-0", children: children }) }));
+        return (_jsx(EssayColumns, { className: "pb-16 sm:pb-24", aside: _jsx(EssayAside, { children: _jsx(TableOfContents, { sections: index }) }), children: _jsx(EssayBody, { className: "flex flex-col gap-16", children: children }) }));
     }
     /** The heading carries the anchor, offset so it lands under the sticky nav. */
     function EssaySection({ id, heading, children, }) {
         return (_jsx("section", { id: id, className: "scroll-mt-24", children: _jsxs(Reveal, { className: "flex flex-col gap-5", children: [_jsx(TypographyH2, { className: "text-balance", children: heading }), children] }) }));
     }
-    /** One per essay: a page with three of them has decided nothing. */
+    /**
+     * One per essay: a page with three of them has decided nothing.
+     *
+     * The face and a rung, not the whole `headingClass()` ramp — see `headingFace` in
+     * typography/header.tsx for why a non-heading takes one and not the other. `text-pretty`
+     * over `text-balance`: this is prose set large, so it fills the measure rather than being
+     * set in even lines like a headline. The rung is the section heading's, so one pull quote
+     * stands level with them and retunes with them under `.editorial`.
+     */
     function EssayPullQuote({ children }) {
-        return (_jsx(Reveal, { children: _jsx("blockquote", { className: cn(headingClass(), "text-balance border-l-2 border-primary/40 py-1 pl-6 leading-snug"), children: children }) }));
+        return (_jsx(Reveal, { children: _jsx("blockquote", { className: cn(headingFace, "text-h2 leading-snug text-foreground text-pretty", "border-l-2 border-primary/40 py-1 pl-6"), children: children }) }));
     }
     /** Generic on purpose: a page hands it anything; this decides only the fit. */
     function EssayFigure({ children, caption, }) {

package/dist/essay/index.d.ts

@@ -4,4 +4,4 @@ export { TableOfContents } from "./contents.js";
 export { createEssay, EssayHeader, EssayLayout, EssaySection, EssayPullQuote, EssayFigure, EssayMovements, EssayDocument, type EssayDecorations, type EssayIndexEntry, type EssayDocSection, type EssayMovement, } from "./essay.js";
 export { useReadingProgress, useScrollSpy } from "./scroll.js";
 export { ReadingProgressBar, ReadingRail } from "./reading.js";
-export { EssayColumns, MetaDot, PostMetaRow, PostDate, formatPostDate, type PostDateFormat, ReadTime, TagPills, } from "./layout.js";
+export { EssayColumns, EssayAside, EssayBody, ReadingLayout, MetaDot, PostMetaRow, PostDate, formatPostDate, type PostDateFormat, ReadTime, TagPills, } from "./layout.js";

package/dist/essay/index.js

@@ -6,4 +6,4 @@ export { createEssay,
 EssayHeader, EssayLayout, EssaySection, EssayPullQuote, EssayFigure, EssayMovements, EssayDocument, } from "./essay.js";
 export { useReadingProgress, useScrollSpy } from "./scroll.js";
 export { ReadingProgressBar, ReadingRail } from "./reading.js";
-export { EssayColumns, MetaDot, PostMetaRow, PostDate, formatPostDate, ReadTime, TagPills, } from "./layout.js";
+export { EssayColumns, EssayAside, EssayBody, ReadingLayout, MetaDot, PostMetaRow, PostDate, formatPostDate, ReadTime, TagPills, } from "./layout.js";