@supertype.ai/foundations 0.1.27 → 0.1.29

package/dist/blocks/segment.js

@@ -1,3 +1,4 @@
+import { FOCUS_RING } from "./focus.js";
 /**
  * The segmented picker, as one set of surfaces.
  *
@@ -9,29 +10,37 @@
  * class strings, which is exactly the kind of duplication that drifts the first time
  * someone retunes the palette.
  *
- * Some entries appear twice, once bare and once `data-active:`-prefixed. That is not
- * laziness: Tailwind generates a utility only if it appears literally in scanned source, so
- * prefixing at runtime would compile to classes that never got built. Writing both forms
- * side by side is the honest version, and it keeps the pair impossible to change by half.
- *
  * The active segment is deliberately flat — a card surface and a hairline, no shadow.
  * Elevation in this system means "this layer left the page plane" (see --elevation-* in
  * theme.css), and a segment sitting inside its own track has not.
+ *
+ * The other half of that: the segment stays on the page plane because the RAIL drops below
+ * it. The well is the shadow and the hairline, not a fill — the track is `bg-background`
+ * pressed in. A `--muted` rail cannot work, because `--muted` sits below `--card` in light
+ * and above it in dark, so a muted fill reads correct in one theme and inverted in the
+ * other, and `dark:` is what the package's own ESLint rule exists to stop.
  */
 export const SEGMENT = {
-    /** The rail a set of segments sits in. Surface only; each component owns its layout. */
-    track: "rounded-lg border border-border bg-muted/40 p-0.5",
+    /**
+     * The rail a set of segments sits in. Surface only; each component owns its layout.
+     *
+     * `rounded-md` over `activeSurface`'s `rounded-sm` is the 2px of `p-0.5`: concentric
+     * radii, so the segment's corner runs parallel to the rail's rather than across it.
+     */
+    track: "rounded-md border border-border bg-background p-0.5 shadow-recessed",
     /** Affordances every segment shares, whatever its shape or engine. */
-    item: "relative inline-flex items-center gap-1.5 font-medium outline-none transition-colors focus-visible:ring-3 focus-visible:ring-ring/50",
+    item: `relative inline-flex items-center gap-1.5 font-medium transition-colors ${FOCUS_RING}`,
     /** Selected: the ink lifts to full strength. */
     active: "text-foreground",
     /**
      * Unselected: quiet, but lighting its own surface on hover so the whole strip reads as
-     * reachable rather than only the segment already chosen.
+     * reachable rather than only the segment already chosen. It moves toward `activeSurface`
+     * and not toward the rail, so a hover previews being picked.
+     */
+    idle: "text-muted-foreground hover:bg-card/60 hover:text-foreground",
+    /**
+     * The flat surface marking the selection. One string, worn by both engines: the marketing
+     * picker slides it with `motion`, `Tabs` hands it to the element Base UI positions.
      */
-    idle: "text-muted-foreground hover:bg-muted/60 hover:text-foreground",
-    /** The flat surface marking the selection. */
-    activeSurface: "bg-card ring-1 ring-border",
-    /** `activeSurface`, for an engine that marks its own trigger with `data-active`. */
-    dataActiveSurface: "data-active:bg-card data-active:text-foreground data-active:ring-1 data-active:ring-border",
+    activeSurface: "rounded-sm bg-card ring-1 ring-border",
 };

package/dist/blocks/tabs.d.ts

@@ -1,32 +1,67 @@
 import { Tabs as TabsPrimitive } from "@base-ui/react/tabs";
 import type { ReactNode } from "react";
 import { type VariantProps } from "class-variance-authority";
+import { type Tone } from "../tone.js";
 declare function Tabs({ className, orientation, ...props }: TabsPrimitive.Root.Props): import("react").JSX.Element;
+/**
+ * Surfaces come from SEGMENT, so this and marketing/segmented-control cannot drift: a
+ * reader who meets the picker on a docs page and again on the usage dashboard should not
+ * have to learn it twice. Layout stays local, since only this one has orientation to serve.
+ *
+ * Each variant states its own box, rather than sharing a base tuned for the boxed track
+ * that `line` then had to undo at the call site.
+ */
 declare const tabsListVariants: (props?: ({
     variant?: "line" | "default" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-declare function TabsList({ className, variant, ...props }: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants>): import("react").JSX.Element;
+/**
+ * `tone` inks the marker, and only the marker. On `line` that is the underline and the
+ * active tab's icon; the boxed track's marker is a card surface and a hairline, which
+ * SEGMENT keeps deliberately flat, so a tone there would be a colour with nothing to
+ * paint. The label stays `--foreground` in both: it is read, not signalled.
+ */
+declare function TabsList({ className, variant, tone, children, ...props }: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants> & {
+    tone?: Tone;
+}): import("react").JSX.Element;
 declare function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props): import("react").JSX.Element;
 declare function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props): import("react").JSX.Element;
+/** One tab, whole: what it is called, what marks it, and what it shows. */
+export type TabItem = {
+    /** Stable across a relabel — it is what `defaultValue` and `onValueChange` speak. */
+    value: string;
+    label: ReactNode;
+    /**
+     * An element — `<Icons.Mic />`, `<PriceChip />` — sized and inked by the trigger.
+     *
+     * 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.
+     */
+    icon?: ReactNode;
+    content: ReactNode;
+};
 /**
-* The declarative shorthand: `items` plus a `<Tab>` per panel. `TabGroup` is to
- * `Tabs` what `DisclosureGroup` is to `Accordion` — the shape you reach for when
- * the tabs are data, and what an MDX author writes as `<Tabs>`.
+ * 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.
  *
- * A caller passing data has no value to bind, so children pair with `items`
- * **by position** — `value` on a `<Tab>` is for readability and is not matched,
- * since matching would silently drop a panel on an edited label. 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.
+ * 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
+ * `items`-plus-children shape lives in the MDX map, the only thing that speaks it.
  */
-export declare function TabGroup({ items, children, className, }: {
-    items: string[];
-    children: ReactNode;
-    className?: string;
-}): import("react").JSX.Element;
-/** `value` names the panel at the call site; it is not used for matching. */
-export declare function Tab({ children }: {
+export declare function TabGroup({ tabs, defaultValue, value, onValueChange, variant, tone, iconPosition, className, }: {
+    tabs: readonly TabItem[];
+    /** Defaults to the first tab, since a picker with nothing picked is not a state. */
+    defaultValue?: string;
+    /** Pass with `onValueChange` to drive it from outside. */
     value?: string;
-    children: ReactNode;
+    onValueChange?: (value: string) => void;
+    variant?: VariantProps<typeof tabsListVariants>["variant"];
+    tone?: Tone;
+    iconPosition?: "inline-start" | "inline-end";
+    className?: string;
 }): import("react").JSX.Element;
 export { Tabs, TabsList, TabsTrigger, TabsContent };

package/dist/blocks/tabs.js

@@ -1,8 +1,9 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Tabs as TabsPrimitive } from "@base-ui/react/tabs";
 import { cva } from "class-variance-authority";
 import { cn } from "../cn.js";
+import { toneClass } from "../tone.js";
 import { SEGMENT } from "./segment.js";
 function Tabs({ className, orientation = "horizontal", ...props }) {
     return (_jsx(TabsPrimitive.Root, { "data-slot": "tabs", "data-orientation": orientation, className: cn(
@@ -12,58 +13,106 @@ function Tabs({ className, orientation = "horizontal", ...props }) {
         // flex container and laid its panels out beside the tab strip.
         "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col", className), ...props }));
 }
-// Surfaces come from SEGMENT, so this and marketing/segmented-control cannot drift: a
-// reader who meets the picker on a docs page and again on the usage dashboard should not
-// have to learn it twice. Layout stays local, since only this one has orientation to serve.
-const tabsListVariants = cva("group/tabs-list inline-flex h-8 w-fit items-center justify-center text-muted-foreground data-[variant=line]:rounded-none", {
+/**
+ * Surfaces come from SEGMENT, so this and marketing/segmented-control cannot drift: a
+ * reader who meets the picker on a docs page and again on the usage dashboard should not
+ * have to learn it twice. Layout stays local, since only this one has orientation to serve.
+ *
+ * Each variant states its own box, rather than sharing a base tuned for the boxed track
+ * that `line` then had to undo at the call site.
+ */
+const tabsListVariants = cva("group/tabs-list inline-flex w-fit items-center text-muted-foreground", {
     variants: {
         variant: {
-            default: SEGMENT.track,
-            line: "gap-1 border-0 bg-transparent",
+            /** The boxed track: one fixed-height rail, segments splitting it evenly. */
+            default: cn(SEGMENT.track, "h-8 justify-center"),
+            /**
+             * A strip of labels over a rule. Free to wrap, so no fixed height — and `pb-2` is
+             * the marker's own room (6px offset plus its 2px), so the list's box contains
+             * everything the list draws and the gaps below measure from the right edge. The
+             * row gap clears the same 8px, or a wrapped row wears the rule above it.
+             */
+            line: "flex-wrap justify-start gap-x-1 gap-y-3 rounded-none border-0 bg-transparent pb-2",
         },
     },
     defaultVariants: {
         variant: "default",
     },
 });
-function TabsList({ className, variant = "default", ...props }) {
-    return (_jsx(TabsPrimitive.List, { "data-slot": "tabs-list", "data-variant": variant, className: cn(tabsListVariants({ variant }), className), ...props }));
+/**
+ * The marker: one element, positioned by Base UI from `--active-tab-left/top/width/height`
+ * on the list, dressed by the variant it is in. It outlives the selection, so it carries
+ * the answer from the old tab to the new instead of being destroyed and rebuilt.
+ *
+ * `data-activation-direction` is `none` before anything is picked, and that is the one case
+ * that must not animate — without the guard every strip on the page slides in from its left
+ * edge on hydration.
+ */
+const tabsIndicatorVariants = cva("pointer-events-none absolute left-0 top-0 w-(--active-tab-width) transition-[translate,width] duration-200 ease-out data-[activation-direction=none]:transition-none motion-reduce:transition-none", {
+    variants: {
+        variant: {
+            /** The pill, on the page plane. The rail below it is what carries the depth. */
+            default: cn(SEGMENT.activeSurface, "h-(--active-tab-height) translate-x-(--active-tab-left) translate-y-(--active-tab-top)"),
+            /**
+             * A rule under the label, clear of the descenders, in the list's tone. The 6px
+             * offset plus its own 2px is the `pb-2` the line list reserves — the two are one
+             * measurement, and changing either alone puts the rule back outside its box.
+             */
+            line: "h-0.5 translate-x-(--active-tab-left) translate-y-[calc(var(--active-tab-top)+var(--active-tab-height)+6px)] rounded-full bg-(--tone-hue)",
+        },
+    },
+    defaultVariants: { variant: "default" },
+});
+/**
+ * `tone` inks the marker, and only the marker. On `line` that is the underline and the
+ * active tab's icon; the boxed track's marker is a card surface and a hairline, which
+ * SEGMENT keeps deliberately flat, so a tone there would be a colour with nothing to
+ * paint. The label stays `--foreground` in both: it is read, not signalled.
+ */
+function TabsList({ className, variant = "default", tone = "primary", children, ...props }) {
+    return (_jsxs(TabsPrimitive.List, { "data-slot": "tabs-list", "data-variant": variant, className: cn("relative", toneClass(tone), tabsListVariants({ variant }), className), ...props, children: [_jsx(TabsPrimitive.Indicator, { renderBeforeHydration: true, className: tabsIndicatorVariants({ variant }) }), children] }));
 }
 function TabsTrigger({ className, ...props }) {
-    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn(SEGMENT.item, SEGMENT.dataActiveSurface, "rounded-md text-muted-foreground hover:text-foreground", 
-        // A trigger fills its share of the track and may carry an icon, neither of which a
-        // standalone picker button has to do.
-        "h-[calc(100%-1px)] flex-1 justify-center px-1.5 py-0.5 text-sm whitespace-nowrap disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", 
-        // The idle hover, scoped to the boxed variant. Spelled out rather than
-        // interpolated: an interpolated class is invisible to Tailwind's scanner and would
-        // compile to nothing at all.
-        "group-data-[variant=default]/tabs-list:not-data-active:hover:bg-muted/60", 
-        // The line variant wears no surface at all; the underline below is its whole signal.
-        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent group-data-[variant=line]/tabs-list:data-active:ring-0", 
-        // That underline carries the accent rather than plain ink, so it reads as the
-        // brand's marker and not as a bold rule.
-        "after:absolute after:inset-x-0 after:bottom-[-5px] after:h-0.5 after:bg-primary after:opacity-0 after:transition-opacity group-data-[variant=line]/tabs-list:data-active:after:opacity-100", className), ...props }));
+    return (_jsx(TabsPrimitive.Tab, { "data-slot": "tabs-trigger", className: cn(SEGMENT.item, 
+        // Ink only — the surface and the underline belong to the indicator. The radius is
+        // for the hover wash, and matches the marker that wash previews.
+        "rounded-sm text-muted-foreground hover:text-foreground data-active:text-foreground", "px-1.5 py-0.5 text-sm whitespace-nowrap disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4", 
+        // An icon sits inside the label's gap, so the padding on that side comes off.
+        // `TabGroup` writes the `data-icon` these two read.
+        "has-data-[icon=inline-start]:pl-1 has-data-[icon=inline-end]:pr-1", 
+        // Filling the track is the boxed variant's business; a line tab is as wide as its
+        // label. The variant is read off the list's `data-variant` rather than taken as a
+        // prop, so a caller states it once on `TabsList` and not on every trigger.
+        // Selectors are spelled out, never interpolated: Tailwind's scanner cannot see an
+        // interpolated class and would compile nothing.
+        "group-data-[variant=default]/tabs-list:h-full group-data-[variant=default]/tabs-list:flex-1 group-data-[variant=default]/tabs-list:justify-center", 
+        // Hover moves toward the marker's surface, so it previews the selection.
+        "group-data-[variant=default]/tabs-list:not-data-active:hover:bg-card/60", 
+        // The active icon takes the ink the marker is drawn in.
+        "group-data-[variant=line]/tabs-list:data-active:[&_[data-icon]]:text-(color:--tone-hue)", className), ...props }));
 }
 function TabsContent({ className, ...props }) {
     return (_jsx(TabsPrimitive.Panel, { "data-slot": "tabs-content", className: cn("flex-1 text-sm outline-none", className), ...props }));
 }
+/** `data-icon` is the hook the trigger's padding and tone selectors read. */
+function TabIconSlot({ icon, position, }) {
+    return (_jsx("span", { "data-icon": position, className: "flex items-center transition-colors [&_svg]:size-4 [&_svg]:shrink-0", children: icon }));
+}
 /**
-* The declarative shorthand: `items` plus a `<Tab>` per panel. `TabGroup` is to
- * `Tabs` what `DisclosureGroup` is to `Accordion` — the shape you reach for when
- * the tabs are data, and what an MDX author writes as `<Tabs>`.
+ * 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.
  *
- * A caller passing data has no value to bind, so children pair with `items`
- * **by position** — `value` on a `<Tab>` is for readability and is not matched,
- * since matching would silently drop a panel on an edited label. 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.
+ * 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
+ * `items`-plus-children shape lives in the MDX map, the only thing that speaks it.
  */
-export function TabGroup({ items, children, className, }) {
-    const panels = Array.isArray(children) ? children : [children];
-    return (_jsxs(Tabs, { defaultValue: 0, className: cn("my-6", className), children: [_jsx(TabsList, { children: items.map((label, i) => (_jsx(TabsTrigger, { value: i, children: label }, label))) }), panels.map((panel, i) => (_jsx(TabsContent, { value: i, className: "pt-2 text-muted-foreground", children: panel }, i)))] }));
-}
-/** `value` names the panel at the call site; it is not used for matching. */
-export function Tab({ children }) {
-    return _jsx(_Fragment, { children: children });
+export function TabGroup({ tabs, defaultValue, value, onValueChange, variant, tone, iconPosition = "inline-start", className, }) {
+    return (
+    // The handler is adapted rather than wrapped when absent: an arrow declared
+    // unconditionally is a function crossing the server boundary on every page that
+    // renders tabs without one.
+    _jsxs(Tabs, { defaultValue: defaultValue ?? tabs[0]?.value, value: value, onValueChange: onValueChange && ((next) => onValueChange(String(next))), className: cn("my-6", className), children: [_jsx(TabsList, { variant: variant, tone: tone, children: tabs.map(({ value: tabValue, label, icon }) => (_jsxs(TabsTrigger, { value: tabValue, children: [icon && iconPosition === "inline-start" && (_jsx(TabIconSlot, { icon: icon, position: "inline-start" })), label, icon && iconPosition === "inline-end" && (_jsx(TabIconSlot, { icon: icon, position: "inline-end" }))] }, tabValue))) }), tabs.map(({ value: tabValue, content }) => (_jsx(TabsContent, { value: tabValue, className: "pt-2 text-muted-foreground", children: content }, tabValue)))] }));
 }
 export { Tabs, TabsList, TabsTrigger, TabsContent };

package/dist/cjs/eslint.js

@@ -10,6 +10,7 @@ exports.themeOverrideRules = themeOverrideRules;
 exports.surfaceAsInkRules = surfaceAsInkRules;
 exports.renamedTokenRules = renamedTokenRules;
 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) => [
@@ -55,10 +56,13 @@ function surfaceAsInkRules() {
 }
 /**
  * `-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. `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.
  */
+const RENAMED_INKS = "warn|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`.");
 }
 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 [
@@ -114,6 +118,15 @@ function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2xs 11 /
             : []),
     ];
 }
+function designRules({ accents, typography = true, ...type } = {}) {
+    return [
+        ...colourRules({ accents }),
+        ...(typography ? typographyRules(type) : []),
+        ...themeOverrideRules(),
+        ...surfaceAsInkRules(),
+        ...renamedTokenRules(),
+    ];
+}
 /**
  * Every rule in one flat-config entry, ready to spread into eslint.config.js:
  *
@@ -126,7 +139,7 @@ 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",
@@ -134,11 +147,7 @@ function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], accents, weights, ramp
             rules: {
                 "no-restricted-syntax": [
                     "error",
-                    ...colourRules({ accents }),
-                    ...typographyRules({ weights, ramp, pairing, axis }),
-                    ...themeOverrideRules(),
-                    ...surfaceAsInkRules(),
-                    ...renamedTokenRules(),
+                    ...designRules(options),
                 ],
             },
         },

package/dist/contrast.d.ts

@@ -36,6 +36,35 @@ 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 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

@@ -214,14 +214,14 @@ const INKS_TINTED = [
     "--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",
 ];
 /**
  * shadcn's shape: `-foreground` is the label printed on the fill, so the pair is
@@ -236,6 +236,24 @@ const ON_FILL = [
     ["--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`),
+    };
+}
 /**
  * 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/eslint.d.ts

@@ -24,10 +24,6 @@ export declare function themeOverrideRules(): RestrictedSyntax[];
  * shipped at 17 sites. `text-background` is absent: inverse ink is a real role.
  */
 export declare function surfaceAsInkRules(): 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.
- */
 export declare function renamedTokenRules(): RestrictedSyntax[];
 export interface TypographyOptions {
     /** Three-weight ramp. Off for editorial, where 700 is a register not a shout. */
@@ -49,13 +45,35 @@ export interface TypographyOptions {
     axis?: boolean;
 }
 export declare function typographyRules({ weights, ramp, pairing, axis, }?: TypographyOptions): RestrictedSyntax[];
+/**
+ * Every design rule, as one list.
+ *
+ * The five 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 +89,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

@@ -47,10 +47,13 @@ export function surfaceAsInkRules() {
 }
 /**
  * `-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. `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.
  */
+const RENAMED_INKS = "warn|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`.");
 }
 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 [
@@ -106,6 +109,15 @@ export function typographyRules({ weights = false, ramp = "text-3xs 10 / text-2x
             : []),
     ];
 }
+export function designRules({ accents, typography = true, ...type } = {}) {
+    return [
+        ...colourRules({ accents }),
+        ...(typography ? typographyRules(type) : []),
+        ...themeOverrideRules(),
+        ...surfaceAsInkRules(),
+        ...renamedTokenRules(),
+    ];
+}
 /**
  * Every rule in one flat-config entry, ready to spread into eslint.config.js:
  *
@@ -118,7 +130,7 @@ 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",
@@ -126,11 +138,7 @@ export function designConfig({ files = ["**/*.{ts,tsx,js,jsx}"], accents, weight
             rules: {
                 "no-restricted-syntax": [
                     "error",
-                    ...colourRules({ accents }),
-                    ...typographyRules({ weights, ramp, pairing, axis }),
-                    ...themeOverrideRules(),
-                    ...surfaceAsInkRules(),
-                    ...renamedTokenRules(),
+                    ...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";