@supertype.ai/foundations 0.1.36 → 0.2.0

package/README.md

@@ -43,10 +43,13 @@ npx @supertype.ai/foundations init      # edits your CSS entry, prints the rest
 npx @supertype.ai/foundations doctor    # checks this app against everything below
 ```
 
-`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 preview the patch. Everything else it prints for you to paste is the font binding and the `llms.txt` lines for a coding agent.
+`init` edits one file: the CSS entry that imports Tailwind. It adds any missing
+imports and reorders the existing ones if needed. Run it with `--dry-run` first
+to preview the patch. It also prints the font bindings and the `llms.txt` snippet
+your coding agent should read.
 
-The steps performed by `init` are written out below anyway. See [the CLI](docs/cli.md) for the full list of checks and details.
+The steps performed by `init` are listed below. See [the CLI](docs/cli.md) for
+the full list of checks and details.
 
 ### 1. Add the package
 
@@ -74,7 +77,7 @@ 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.36"
+"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.2.0"
 ```
 
 </details>
@@ -89,10 +92,10 @@ untagged git dependency resolves to a different commit on a fresh install.
 
 That one line carries `tokens.css`, `theme.css`, `type.css` and `prose.css` in
 the order the cascade needs, and registers the package&rsquo;s own `@source` so
-Tailwind scans the components it ships. There is no path for you to work out and
-no order for you to keep: Tailwind v4 resolves `@source` relative to the file
-that declares it, so the package points at its own `dist/`, correctly, wherever
-it happens to be installed.
+Tailwind scans the components it ships. You do not need to work out a path or
+keep an order: Tailwind v4 resolves `@source` relative to the file that declares
+it, so the package points at its own `dist/`, correctly, wherever it happens to
+be installed.
 
 Add `@import "@supertype.ai/foundations/shiki.css";` after it only if you render
 code fences.
@@ -239,8 +242,8 @@ Two rules cover most of the API:
 `yarn example` (above) builds the package, syncs it in and starts the dev
 server. `yarn example:build` is what CI would run.
 
-It installs the package from a git tag rather than from the registry and updates
-it with `yarn sync`.
+It installs the package from a git tag rather than the registry and updates it
+with `yarn sync`.
 
 `/recipes` holds whole pages rather than single components: a marketing hero, a
 metrics panel, pricing tiers, a docs page, an article index, and examples of MDX-rendered pages. Each one lives in
@@ -268,19 +271,19 @@ package.
 
 ## Entry points
 
-| import                                                                | contains                                                                 | docs                                         |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
-| `@supertype.ai/foundations`                                           | all typography primitives, `cn`                                          | [Typography](docs/typography.md)             |
+| import                                                                | contains                                                                          | docs                                         |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------- |
+| `@supertype.ai/foundations`                                           | all typography primitives, `cn`                                                   | [Typography](docs/typography.md)             |
 | `@supertype.ai/foundations/blocks`                                    | `Button`, `Badge`, `Card`, `Callout`, `Steps`, `TabGroup`, `Accordion`, `SEGMENT` | [Blocks](docs/blocks.md)                     |
-| `@supertype.ai/foundations/mdx`                                       | `proseMdxComponents` — the MDX element map                               | [In MDX](docs/blocks.md#in-mdx)              |
-| `@supertype.ai/foundations/essay`                                     | the long-form shell, TOC, reading rail, post meta                        | [Essay](docs/essay.md)                       |
-| `@supertype.ai/foundations/seo`                                       | `createSeo(...)` — metadata + JSON-LD                                    | [Tooling](docs/tooling.md#seo-and-og-images) |
-| `@supertype.ai/foundations/og`                                        | `ogCard`, `OG_SIZE` — an element for `next/og`                           | [Tooling](docs/tooling.md#seo-and-og-images) |
-| `@supertype.ai/foundations/eslint`                                    | the design rules as ESLint selectors                                     | [Tooling](docs/tooling.md#lint-rules)        |
-| `@supertype.ai/foundations/rehype`                                    | `rehypeProseCode` — **build-time only**                                  | [In MDX](docs/blocks.md#in-mdx)              |
-| `@supertype.ai/foundations/contrast`                                  | token resolution + legibility checks, build-time only                    | [Tooling](docs/tooling.md#contrast-checks)   |
-| `./tokens.css` `./theme.css` `./type.css` `./prose.css` `./shiki.css` | the style layer                                                          | [Tokens and theming](#tokens-and-theming)    |
-| `foundations` (bin)                                                   | `init` and `doctor`                                                      | [The CLI](docs/cli.md)                       |
+| `@supertype.ai/foundations/mdx`                                       | `proseMdxComponents` — the MDX element map                                        | [In MDX](docs/blocks.md#in-mdx)              |
+| `@supertype.ai/foundations/essay`                                     | the long-form shell, TOC, reading rail, post meta                                 | [Essay](docs/essay.md)                       |
+| `@supertype.ai/foundations/seo`                                       | `createSeo(...)` — metadata + JSON-LD                                             | [Tooling](docs/tooling.md#seo-and-og-images) |
+| `@supertype.ai/foundations/og`                                        | `ogCard`, `OG_SIZE` — an element for `next/og`                                    | [Tooling](docs/tooling.md#seo-and-og-images) |
+| `@supertype.ai/foundations/eslint`                                    | the design rules as ESLint selectors                                              | [Tooling](docs/tooling.md#lint-rules)        |
+| `@supertype.ai/foundations/rehype`                                    | `rehypeProseCode` — **build-time only**                                           | [In MDX](docs/blocks.md#in-mdx)              |
+| `@supertype.ai/foundations/contrast`                                  | token resolution + legibility checks, build-time only                             | [Tooling](docs/tooling.md#contrast-checks)   |
+| `./tokens.css` `./theme.css` `./type.css` `./prose.css` `./shiki.css` | the style layer                                                                   | [Tokens and theming](#tokens-and-theming)    |
+| `foundations` (bin)                                                   | `init` and `doctor`                                                               | [The CLI](docs/cli.md)                       |
 
 ---
 
@@ -341,12 +344,12 @@ surfaces set body at different sizes: 13px in the product, 18px on `.editorial`.
 
 1. **The package owns its final classnames.** Retune with CSS custom properties
    (the `--text-*`, `--heading-weight`, the colour tokens) rather than by
-   patching classes. A property the package declares is read by the package —
-   `test/tokens-live.test.ts` fails on one that is not, because a knob that
-   turns nothing is worse than no knob at all.
+   patching classes. A property the package declares is read by the package; if a
+   knob turns nothing, `test/tokens-live.test.ts` fails on it; that is worse
+   than no knob at all.
 2. **No variant props on the MDX map.** Elements that MDX renders automatically
-   take no options, because there is no call site to make the choice. Components
-   you invoke by hand can have variants.
+   take no options. No call site exists to make the choice. Components you invoke
+   by hand can have variants.
 3. **Use the platform first, and a library only where it falls short.**
    `Disclosure` is a `<details>`/`<summary>` pair: no JavaScript, correct before
    hydration, and available to an MDX author. `Accordion` and `Tabs` use Base UI,
@@ -360,6 +363,38 @@ surfaces set body at different sizes: 13px in the product, 18px on `.editorial`.
 
 ---
 
+## Upgrading to 0.2
+
+Two entry points lost exports. Both had one function doing the work and several
+more standing beside it, and the extras are what a config got wrong.
+
+**`/eslint` is one function.** `designRules` assembles every rule, so replace
+`designConfig({ accents, weights })` with your own flat-config entry around it:
+
+```js
+{
+  files: ["app/**/*.tsx", "components/**/*.tsx"],
+  rules: {
+    "no-restricted-syntax": ["error", ...designRules({ accents: "the brand tints" })],
+  },
+}
+```
+
+`colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`,
+`surfaceAsInkRules` and `renamedTokenRules` are internal now. Spreading a subset
+was how a config came to be running four of the six sets, unaware of the other
+two, so the whole set is what the package hands out. `typography: false` still
+drops the type rules for a surface that sets its own ramp.
+
+**`/rehype` is `rehypeProseCode` and `PROSE_THEMES`.** `PROSE_LANGS` and
+`proseCodeOptions` are what that plugin is built from rather than things to pass.
+
+New in the same release: `CAP_TRIM` and `ON_FIRST_LINE` for lining a mark up with
+the words beside it, and `/optical`, which reads a face's metrics and names the
+rungs where a centred mark misses the letters.
+
+---
+
 ## In production
 
 Sites running the package:

package/dist/cjs/eslint.js

@@ -5,14 +5,7 @@
  * They see values, never the shape of a class list; a primitive fixes that.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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) => [
     `Literal[value=${pattern}]`,
@@ -182,26 +175,3 @@ function designRules({ accents, typography = true, ...type } = {}) {
         ...renamedTokenRules(),
     ];
 }
-/**
- * Every rule in one flat-config entry, ready to spread into eslint.config.js:
- *
- *   import { designConfig } from "@supertype.ai/foundations/eslint";
- *   export default [ ...designConfig({ accents: "the brand tints" }) ];
- *
- * One entry is not a detail. Flat config replaces a rule's options rather than
- * merging them, so two blocks covering overlapping files leave only the last
- * one's rules in effect. Combining them here is what stops a consumer losing
- * 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}"], ...options } = {}) {
-    return [
-        {
-            name: "@supertype.ai/foundations/design",
-            files,
-            rules: {
-                "no-restricted-syntax": ["error", ...designRules(options)],
-            },
-        },
-    ];
-}

package/dist/eslint.d.ts

@@ -7,41 +7,11 @@ export interface RestrictedSyntax {
     selector: string;
     message: string;
 }
-export interface ColourOptions {
+interface ColourOptions {
     /** Named in the message: "use a token" without naming one sends people hunting. */
     accents?: string;
 }
-/** Applies everywhere, marketing included — the tints exist for those pages. */
-export declare function colourRules({ accents, }?: ColourOptions): RestrictedSyntax[];
-/**
- * A token already knows what it does in the dark; `dark:` on one says the token
- * is wrong. Only the solid form is restricted — `dark:bg-destructive/20` against
- * a `/10` is the same token at the density a darker ground needs.
- */
-export declare function themeOverrideRules(): RestrictedSyntax[];
-/**
- * `--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[];
-/**
- * `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 linkRules(): RestrictedSyntax[];
-export interface TypographyOptions {
+interface TypographyOptions {
     /** Three-weight ramp. Off for editorial, where 700 is a register not a shout. */
     weights?: boolean;
     /** The rungs, named in the message, since they differ per consumer. */
@@ -63,7 +33,6 @@ export interface TypographyOptions {
      *  adopting it has a backlog to clear first. */
     leading?: boolean;
 }
-export declare function typographyRules({ weights, ramp, pairing, axis, leading, }?: TypographyOptions): RestrictedSyntax[];
 /**
  * Every design rule, as one list.
  *
@@ -86,26 +55,4 @@ export interface DesignRuleOptions extends ColourOptions, TypographyOptions {
     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 DesignRuleOptions {
-    /** What the rules apply to. Narrow it to exclude generated or vendored code. */
-    files?: string[];
-}
-/**
- * Every rule in one flat-config entry, ready to spread into eslint.config.js:
- *
- *   import { designConfig } from "@supertype.ai/foundations/eslint";
- *   export default [ ...designConfig({ accents: "the brand tints" }) ];
- *
- * One entry is not a detail. Flat config replaces a rule's options rather than
- * merging them, so two blocks covering overlapping files leave only the last
- * one's rules in effect. Combining them here is what stops a consumer losing
- * 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, ...options }?: DesignConfigOptions): FlatConfigEntry[];
+export {};

package/dist/eslint.js

@@ -12,7 +12,7 @@ const rule = (pattern, message) => classString(pattern).map((selector) => ({ sel
 const VARIANTS = "(dark:|hover:|focus:|group-hover:|active:|disabled:|sm:|md:|lg:|xl:)*";
 const PALETTE = "(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)";
 /** Applies everywhere, marketing included — the tints exist for those pages. */
-export function colourRules({ accents = "a brand accent", } = {}) {
+function colourRules({ accents = "a brand accent", } = {}) {
     return [
         ...rule(`/(^| )${VARIANTS}(text|bg|border|ring|from|to|via|fill|stroke|divide|outline|placeholder|shadow|decoration|accent|caret)-${PALETTE}-\\d+/`, `Raw Tailwind palette. Use a token — text-foreground / text-muted-foreground / text-subtle-foreground, bg-background / bg-card / bg-muted, border-border — a status token (success, warn, destructive), or ${accents}.`),
         // Split by prefix: alpha on a fill is a scrim (the effect), on ink or a
@@ -35,7 +35,7 @@ const COLOUR_PREFIX = "text|bg|border|ring|from|to|via|fill|stroke|divide|placeh
  * is wrong. Only the solid form is restricted — `dark:bg-destructive/20` against
  * a `/10` is the same token at the density a darker ground needs.
  */
-export function themeOverrideRules() {
+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.");
 }
 /**
@@ -43,7 +43,7 @@ export function themeOverrideRules() {
  * it shipped at 17 sites. `text-background` stays legal: inverse ink is a real
  * role.
  */
-export function surfaceAsInkRules() {
+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."),
         // The three fills with no legitimate use as a foreground, glyph or word.
@@ -70,7 +70,7 @@ export function surfaceAsInkRules() {
  * 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() {
+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`.");
 }
 /**
@@ -87,7 +87,7 @@ export function renamedTokenRules() {
  * bare `<a>`: `render={<Link/>}` is redundant beside `href` but it still routes,
  * so it is not a bug.
  */
-export function linkRules() {
+function linkRules() {
     return [
         {
             selector: 'JSXOpeningElement[name.name=/^(Button|Badge|Card)$/] > JSXAttribute[name.name="render"] > JSXExpressionContainer > JSXElement > JSXOpeningElement[name.name="a"]',
@@ -95,7 +95,7 @@ export function linkRules() {
         },
     ];
 }
-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, leading = false, } = {}) {
+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, leading = false, } = {}) {
     return [
         // Alpha ink composites against whatever surface it lands on, so its
         // contrast is unmeasurable. The ink tokens are measured.
@@ -172,26 +172,3 @@ export function designRules({ accents, typography = true, ...type } = {}) {
         ...renamedTokenRules(),
     ];
 }
-/**
- * Every rule in one flat-config entry, ready to spread into eslint.config.js:
- *
- *   import { designConfig } from "@supertype.ai/foundations/eslint";
- *   export default [ ...designConfig({ accents: "the brand tints" }) ];
- *
- * One entry is not a detail. Flat config replaces a rule's options rather than
- * merging them, so two blocks covering overlapping files leave only the last
- * one's rules in effect. Combining them here is what stops a consumer losing
- * 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}"], ...options } = {}) {
-    return [
-        {
-            name: "@supertype.ai/foundations/design",
-            files,
-            rules: {
-                "no-restricted-syntax": ["error", ...designRules(options)],
-            },
-        },
-    ];
-}

package/dist/optical.d.ts

@@ -0,0 +1,56 @@
+/**
+ * How far a centred mark misses the letters, per rung of a type ramp.
+ *
+ * `items-center` centres boxes, and the box is the line box: leading, ascent and
+ * descent, only some of which the letters use. The mark beside a label therefore
+ * centres on the font's box rather than on the band of ink a reader sees, and
+ * whether those two agree is a property of the font, not of the design.
+ *
+ * The whole tool is one line of arithmetic, and the rounding is the reason it is
+ * worth shipping. Ratios alone give one constant tilt for a face, 0.0235em for
+ * Ubuntu Sans, which reads as every rung being equally out. Browsers quantise
+ * ascent, descent and cap height to whole pixels before they lay a line out, and
+ * rounded, that same face is half a pixel out at 11px, flat at 13px and half a
+ * pixel out again at 22px. The rendered pages agree, so the rounding is what
+ * separates a rung that needs the trim from one where it buys nothing.
+ *
+ * Build-time only, and only as good as the metrics handed to it. Verify cap
+ * height against the browser rather than a table: `next/font` ships 693 for
+ * Ubuntu Sans where canvas measures 727, and the wrong one flips the answer at
+ * every rung.
+ */
+/** A font's vertical metrics, in font units. The four numbers every metrics
+ *  table carries, `next/font`'s and capsize's alike. */
+export interface FontMetrics {
+    unitsPerEm: number;
+    ascent: number;
+    descent: number;
+    capHeight: number;
+}
+/** One step of a ramp: the name an app knows it by, and its size in px. */
+export interface TypeRung {
+    name: string;
+    fontSize: number;
+}
+export interface OpticalOffset extends TypeRung {
+    /** How far below the cap band's centre a centred mark sits, in px. Positive is
+     *  low, which is the direction rounding takes it. */
+    offset: number;
+    /** The same miss against the height of the letters it misses. Half a pixel is
+     *  a twelfth of an 11px cap band and a thirty-second of a 36px one, so this is
+     *  the number that says whether a reader sees it. */
+    share: number;
+}
+/**
+ * Every rung whose centred mark misses the letters by enough to see, worst first.
+ *
+ * A rung that comes back is one where an icon, a badge or a swatch set beside the
+ * text with `items-center` wants `CAP_TRIM` on the text to land on it. Most rungs
+ * of a ramp are half a pixel out, so the pixel is not the question: `tolerance` is
+ * a share of the cap band, and 0.05 is where a miss stops reading as a rounding
+ * artefact and starts reading as two things that do not line up. Raise it for a
+ * surface that only sets headlines, lower it to see the whole ramp.
+ */
+export declare function checkOptical(metrics: FontMetrics, rungs: readonly TypeRung[], { tolerance }?: {
+    tolerance?: number;
+}): OpticalOffset[];

package/dist/optical.js

@@ -0,0 +1,56 @@
+/**
+ * How far a centred mark misses the letters, per rung of a type ramp.
+ *
+ * `items-center` centres boxes, and the box is the line box: leading, ascent and
+ * descent, only some of which the letters use. The mark beside a label therefore
+ * centres on the font's box rather than on the band of ink a reader sees, and
+ * whether those two agree is a property of the font, not of the design.
+ *
+ * The whole tool is one line of arithmetic, and the rounding is the reason it is
+ * worth shipping. Ratios alone give one constant tilt for a face, 0.0235em for
+ * Ubuntu Sans, which reads as every rung being equally out. Browsers quantise
+ * ascent, descent and cap height to whole pixels before they lay a line out, and
+ * rounded, that same face is half a pixel out at 11px, flat at 13px and half a
+ * pixel out again at 22px. The rendered pages agree, so the rounding is what
+ * separates a rung that needs the trim from one where it buys nothing.
+ *
+ * Build-time only, and only as good as the metrics handed to it. Verify cap
+ * height against the browser rather than a table: `next/font` ships 693 for
+ * Ubuntu Sans where canvas measures 727, and the wrong one flips the answer at
+ * every rung.
+ */
+const px = (value, fontSize, unitsPerEm) => Math.round((value * fontSize) / unitsPerEm);
+/**
+ * The gap between the line box's centre and the cap band's, at one size.
+ *
+ * Half-leading cancels, so line height does not appear: a rung that is out stays
+ * out however loosely it is set, and no retune of the ramp's leading fixes it.
+ * Paint rounds the baseline a second time, in the same direction, so treat this
+ * as the floor of the error rather than the whole of it.
+ */
+function capBandOffset(metrics, fontSize) {
+    const ascent = px(metrics.ascent, fontSize, metrics.unitsPerEm);
+    const descent = px(metrics.descent, fontSize, metrics.unitsPerEm);
+    const capHeight = px(metrics.capHeight, fontSize, metrics.unitsPerEm);
+    return capHeight / 2 - (ascent - descent) / 2;
+}
+/**
+ * Every rung whose centred mark misses the letters by enough to see, worst first.
+ *
+ * A rung that comes back is one where an icon, a badge or a swatch set beside the
+ * text with `items-center` wants `CAP_TRIM` on the text to land on it. Most rungs
+ * of a ramp are half a pixel out, so the pixel is not the question: `tolerance` is
+ * a share of the cap band, and 0.05 is where a miss stops reading as a rounding
+ * artefact and starts reading as two things that do not line up. Raise it for a
+ * surface that only sets headlines, lower it to see the whole ramp.
+ */
+export function checkOptical(metrics, rungs, { tolerance = 0.05 } = {}) {
+    return rungs
+        .map((rung) => {
+        const offset = capBandOffset(metrics, rung.fontSize);
+        const capHeight = px(metrics.capHeight, rung.fontSize, metrics.unitsPerEm);
+        return { ...rung, offset, share: Math.abs(offset) / capHeight };
+    })
+        .filter((rung) => rung.share > tolerance)
+        .sort((a, b) => b.share - a.share);
+}

package/dist/rehype.d.ts

@@ -1,18 +1,6 @@
 import rehypeShiki, { type RehypeShikiOptions } from "@shikijs/rehype";
-/**
- * Explicit rather than Shiki's full set — every grammar is build-time parsing.
- * Anything unlisted falls back to `text`: content uses labels that are not real
- * grammars (`tree`, `spark-defaults`), and dying over a fence label is a bad trade.
- */
-export declare const PROSE_LANGS: readonly ["bash", "csv", "diff", "docker", "json", "python", "sql", "toml", "tsx", "typescript", "javascript", "yaml"];
 export declare const PROSE_THEMES: {
     readonly light: "github-light";
     readonly dark: "github-dark";
 };
-/**
- * `defaultColor: false` emits `--shiki-light` / `--shiki-dark` per token instead
- * of a baked colour, so one compiled document serves both themes; `shiki.css`
- * maps them. A `[plugin, options]` tuple, so it drops into `rehypePlugins`.
- */
-export declare const proseCodeOptions: RehypeShikiOptions;
 export declare const rehypeProseCode: [typeof rehypeShiki, RehypeShikiOptions];

package/dist/rehype.js

@@ -4,7 +4,7 @@ import rehypeShiki, {} from "@shikijs/rehype";
  * Anything unlisted falls back to `text`: content uses labels that are not real
  * grammars (`tree`, `spark-defaults`), and dying over a fence label is a bad trade.
  */
-export const PROSE_LANGS = [
+const PROSE_LANGS = [
     "bash",
     "csv",
     "diff",
@@ -27,7 +27,7 @@ export const PROSE_THEMES = {
  * of a baked colour, so one compiled document serves both themes; `shiki.css`
  * maps them. A `[plugin, options]` tuple, so it drops into `rehypePlugins`.
  */
-export const proseCodeOptions = {
+const proseCodeOptions = {
     themes: PROSE_THEMES,
     defaultColor: false,
     langs: [...PROSE_LANGS],

package/dist/typography/align.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Lining a mark up with the words beside it, from either side.
+ *
+ * `items-center` centres boxes, and a line box is not the letters: it holds the
+ * leading, the ascent and the descent, whatever the string uses of them. There
+ * are two ways to close that gap and they apply to opposite elements. `CAP_TRIM`
+ * shrinks the text to its ink, for a row whose items are all on one line.
+ * `ON_FIRST_LINE` grows the mark to one line, for a row whose text runs on and
+ * whose mark belongs to the name at the top of it.
+ *
+ * Reach for one or the other, never both on the same row.
+ */
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export declare const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";
+/**
+ * A box one line tall with the mark centred in it, for a mark that belongs to the
+ * first line of something taller.
+ *
+ * The row is `items-start`, so its own height is whatever the text grew to and
+ * centring on it would drop the mark into the middle of a paragraph. This gives
+ * the mark the first line's height instead, which is the thing it names. It goes
+ * on a wrapper rather than the mark: a height on the mark itself would stretch
+ * the glyph rather than move it.
+ *
+ * `1lh` resolves against the wrapper's own inherited leading, so a first line set
+ * at a rung the row does not share wants that rung on the wrapper too. The
+ * alternative is what this replaces, a top margin holding the mark down by a
+ * number that is right at one pairing of rung and mark size and silently wrong at
+ * every other.
+ */
+export declare const ON_FIRST_LINE = "flex h-[1lh] shrink-0 items-center";

package/dist/typography/align.js

@@ -0,0 +1,57 @@
+/**
+ * Lining a mark up with the words beside it, from either side.
+ *
+ * `items-center` centres boxes, and a line box is not the letters: it holds the
+ * leading, the ascent and the descent, whatever the string uses of them. There
+ * are two ways to close that gap and they apply to opposite elements. `CAP_TRIM`
+ * shrinks the text to its ink, for a row whose items are all on one line.
+ * `ON_FIRST_LINE` grows the mark to one line, for a row whose text runs on and
+ * whose mark belongs to the name at the top of it.
+ *
+ * Reach for one or the other, never both on the same row.
+ */
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";
+/**
+ * A box one line tall with the mark centred in it, for a mark that belongs to the
+ * first line of something taller.
+ *
+ * The row is `items-start`, so its own height is whatever the text grew to and
+ * centring on it would drop the mark into the middle of a paragraph. This gives
+ * the mark the first line's height instead, which is the thing it names. It goes
+ * on a wrapper rather than the mark: a height on the mark itself would stretch
+ * the glyph rather than move it.
+ *
+ * `1lh` resolves against the wrapper's own inherited leading, so a first line set
+ * at a rung the row does not share wants that rung on the wrapper too. The
+ * alternative is what this replaces, a top margin holding the mark down by a
+ * number that is right at one pairing of rung and mark size and silently wrong at
+ * every other.
+ */
+export const ON_FIRST_LINE = "flex h-[1lh] shrink-0 items-center";

package/dist/typography/index.d.ts

@@ -2,3 +2,4 @@ export type { TypographyTag } from "./as.js";
 export * from "./header.js";
 export * from "./paragraph.js";
 export * from "./highlight.js";
+export * from "./align.js";

package/dist/typography/index.js

@@ -1,3 +1,4 @@
 export * from "./header.js";
 export * from "./paragraph.js";
 export * from "./highlight.js";
+export * from "./align.js";

package/dist/typography/trim.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export declare const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";

package/dist/typography/trim.js

@@ -0,0 +1,28 @@
+/**
+ * The optical box: cap top to baseline, with the leading either side removed.
+ *
+ * A line box reserves room for the ascenders and descenders a string may not
+ * use, so `items-center` beside an icon centres that reservation rather than
+ * the letters. On an 11px uppercase label the mark next to it renders about a
+ * pixel low, which is a whole device pixel against an eight pixel cap band.
+ * Trimming makes the element as tall as its own ink, so the row centres what
+ * the reader actually sees.
+ *
+ * Two things follow. It goes on the text element, since `text-box` is not
+ * inherited and a row cannot hand it down. And it shortens that element, so a
+ * row of trimmed text needs a height floor of its own: without one, the card
+ * whose label carries no mark sits shorter than the three beside it and its
+ * figure rides high. Chrome and Safari trim, and a browser that does not know
+ * `text-box` keeps the untrimmed box, which is the behaviour of every consumer
+ * today.
+ *
+ * Never on a string that also clips. The bottom edge is the baseline, so
+ * descenders sit outside the box, and `truncate` or any other overflow hidden
+ * cuts the tails off every g and p in it.
+ *
+ * Uppercase is where it pays. A cap band fills half of an 11px line box and the
+ * mark beside it lands a whole device pixel low, where 13px mixed case measures
+ * the same trimmed or not: ascenders reach the top of the line box on their own,
+ * so there is little leading left to take.
+ */
+export const CAP_TRIM = "[text-box:trim-both_cap_alphabetic]";

package/llms.txt

@@ -14,19 +14,18 @@ silently. Full reference: https://github.com/supertypeai/foundations
    `text-xs`, `font-medium`, `leading-tight`, `text-muted-foreground` or similar
    on a text element, there is a primitive for it. Use that instead.
 2. **Retune with CSS variables, not classes.** The package owns its classnames.
-   Change a `--text-*` rung, `--heading-weight` or a colour token. Do not
-   override the package's utilities.
+   Change a `--text-*` rung, `--heading-weight` or a colour token instead of
+   overriding the package's utilities.
 3. **Import from the right entry point.** `blocks`, `essay`, `mdx`, `seo`, `og`,
    `eslint`, `rehype` and `contrast` are subpaths, not part of the root barrel.
 4. **Use colour tokens, never literal colours.** `bg-card`, `text-foreground`,
    `border-border`. No hex values, no `bg-zinc-800`, no `dark:` overrides that
    swap one token for another.
-5. **Paint a surface, hand down its ink.** Any element you give a background
+5. **Paint a surface, hand down its ink.** Any element that gets a background
    needs `INK_ON_FILL` (a tone fill) or one of `INK_ON_CARD`, `INK_ON_POPOVER`,
-   `INK_ON_SIDEBAR` (a tinted one), or the type inside it keeps the page's ink
-   and fails contrast silently. Never build one of these class strings
-   yourself: Tailwind only generates a class it can read as text, so an
-   assembled one styles nothing. For a surface with no constant, spread
+   `INK_ON_SIDEBAR` (a tinted surface), or the text inside it keeps the page's ink
+   and fails contrast silently. Tailwind only generates a class it can read as
+   text, so a built string styles nothing. For a surface without a constant, spread
    `inkOnSurfaceStyle(token)` into `style`.
 6. **Write the words like a person would.** See Writing copy below. It applies
    to every string a reader sees and to the comments you leave behind.
@@ -50,7 +49,7 @@ silently. Full reference: https://github.com/supertypeai/foundations
 | inline code | `TypographyInlineCode` | root |
 | a link | `TypographyLink` | root |
 | an anchor around something already drawn | `Anchor` | `/blocks` |
-| where an href goes, without a component | `resolveLink` | root |
+| where an `href` goes, without a component | `resolveLink` | root |
 | a highlighted phrase | `TypographyHighlight` | root |
 | a button, or a link that looks like one | `Button` | `/blocks` |
 | a status label, count or chip | `Badge` | `/blocks` |
@@ -67,6 +66,7 @@ silently. Full reference: https://github.com/supertypeai/foundations
 | an article whose body is prose or MDX | `EssayHeader` + `ReadingLayout` | `/essay` |
 | a post meta row (date, read time, tags) | `PostMetaRow` and friends | `/essay` |
 | a table of contents | `TableOfContents`, `ReadingRail` | `/essay` |
+| where a centred mark lands on a rung | `checkOptical` | `/optical` |
 | page metadata and JSON-LD | `createSeo` | `/seo` |
 | an OG image | `ogCard`, `OG_SIZE` | `/og` |
 | to merge classnames | `cn` | root |
@@ -75,15 +75,16 @@ silently. Full reference: https://github.com/supertypeai/foundations
 
 | import | exports |
 |---|---|
-| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
+| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`, `CAP_TRIM`, `ON_FIRST_LINE`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
 | `@supertype.ai/foundations/blocks` | `Anchor`, `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Button`, `buttonVariants`, `Badge`, `badgeVariants`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `SEGMENT`, `Bulletin`, `Ribbon`, `EDITORIAL_INKS`, `Colophon`, `BuiltWithFoundations`, `FoundationsMark`, `FOUNDATIONS_URL`. Types: `ButtonLook`, `BadgeLook`, `TabItem`, `BulletinProps`, `BulletinPoint`, `RibbonHue`, `ColophonProps` |
 | `@supertype.ai/foundations/mdx` | `proseMdxComponents` |
 | `@supertype.ai/foundations/essay` | `createEssay`, `EssayHeader`, `EssayLayout`, `EssaySection`, `EssayPullQuote`, `EssayFigure`, `EssayMovements`, `EssayDocument`, `EssayColumns`, `EssayAside`, `EssayBody`, `ReadingLayout`, `TableOfContents`, `ReadingRail`, `ReadingProgressBar`, `Rail`, `RailLink`, `PostMetaRow`, `PostDate`, `ReadTime`, `TagPills`, `MetaDot`, `formatPostDate`, `extractHeadings`, `readingTime`, `createSlugger`, `useReadingProgress`, `useScrollSpy`. Types: `TocHeading`, `EssayDecorations`, `EssayIndexEntry`, `EssayDocSection`, `EssayMovement`, `PostDateFormat` |
 | `@supertype.ai/foundations/seo` | `createSeo`. Types: `SeoConfig`, `ArticleAuthor`, `ArticleOptions`, `PageMetadata` |
 | `@supertype.ai/foundations/og` | `ogCard`, `OG_SIZE`. Types: `OgCardOptions` |
-| `@supertype.ai/foundations/eslint` | `designRules` (every rule as one array, the one to spread), `designConfig` (the same set wrapped as a flat-config entry). The builders `colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are exported too, though spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
-| `@supertype.ai/foundations/rehype` | `rehypeProseCode`, `proseCodeOptions`, `PROSE_LANGS`, `PROSE_THEMES`. Build-time only, must not resolve React |
-| `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1 — status hues, the categorical earth hues and the six chart series alike — tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill: the tone rows are read off `TONE` and each cut is resolved along its `var()` fallback chain, so an app that declares `--brand` without `--brand-foreground` is measured on the label the cascade really reaches for rather than skipped), `checkHairlines` (`--border` and `--input` at 1.4:1 on `--background` and `--card`, `--sidebar-border` on `--sidebar`: a rule is exempt from the ink and mark bars, but it still has to read as the same weight in both themes), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast` (WCAG ratio), `lc` (APCA lightness contrast: polarity-aware, for checking that an ink ramp is perceptually ordered rather than merely ordered by ratio), `tokenCuts` (which cuts a token ships: fill, the label printed on it, the hue as words, the taxonomy `checkSignals` measures against). Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
+| `@supertype.ai/foundations/eslint` | `designRules`: every rule as one array, to spread into a `no-restricted-syntax` entry. The set is assembled inside, so it cannot drift. Types: `DesignRuleOptions`, `RestrictedSyntax` |
+| `@supertype.ai/foundations/optical` | `checkOptical`: each rung of a ramp whose centred mark misses the letters by enough to see, worst first. Types: `FontMetrics`, `TypeRung`, `OpticalOffset`. Build-time only |
+| `@supertype.ai/foundations/rehype` | `rehypeProseCode`, `PROSE_THEMES`. Build-time only, must not resolve React |
+| `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1, tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill), `checkHairlines` (`--border` and `--input` at 1.4:1 on `--background` and `--card`, `--sidebar-border` on `--sidebar`), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast` (WCAG ratio), `lc` (APCA lightness contrast), `tokenCuts`. Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
 
 ## Props worth knowing
 
@@ -93,110 +94,74 @@ silently. Full reference: https://github.com/supertypeai/foundations
 - `TypographyMuted`, `TypographyProse`, `TypographyProseList` are presets. The
   prop each one pins is dropped from its type, so passing it fails to compile.
 - `TypographyCaption`, `TypographyLabel`, `TypographySmall`: `size?: "sm" | "xs" | "2xs" | "inherit"`, `as?`.
-- `TypographyEyebrow`: `tone?: "heading" | "label" | "muted" | "subtle"`, `size?: "sm" | "xs" | "2xs" | "3xs"`, `as?`. Each tone carries the rung it is usually set at and `size` overrides it, so omitting it changes nothing. Reach for `muted` for the uppercase micro-label a dense product sets over a group of controls, and `subtle` for a column head or rail marker read on the way past — that shape hand-rolled is the most common way an app ends up spelling type classes.
-- `TypographyStat`: `size?: "inherit" | "3xs" | "2xs" | "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "card" | "panel" | "section" | "page" | "display"`, `figures?: "tabular" | "proportional"`, `tone?: "default" | "muted"`. Two ladders in one axis: the rung names are the body ramp, for a figure beside interface copy it should step with, and the surface names ride the heading ladder, for a figure that is the headline. `tone="muted"` is the qualifier after a figure, "of 2,000" beside "1,284": still tight, no longer competing. Keep tabular where a value updates in place.
-- `TypographyLink`: `href` (required), `tone?: Tone` (default `muted`), `addArrow?`, `newTab?`. The href decides internal versus external.
-- `TypographyHighlight`: `tone?: HighlightTone`, one of `"primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, plus `seed?: number`. A separate type from `Tone` on purpose: this axis is categorical (which one it is) where `Tone` is semantic (what it means), the same split theme.css draws between the earth swatches and the status tokens.
-- `Card`: `href`, `title`, `description`, `icon`, `external`. An href makes the whole card a link.
-- `Anchor`: `href` (required), plus `external`/`newTab`. An unstyled anchor for a
-  link that is not typography and not a control — a thumbnail, a chip, a tooltip
-  trigger. It exists so `target`/`rel` are never written at a call site; `external`
-  is for a same-origin path that is not a route, which the router would prefetch.
-- `Tone` is the one semantic colour vocabulary, shared by `Button`, `Badge`, `Callout`, `TypographyLink` and `TabsList`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`. Seven tones, seven tokens, one to one, which is the bar for adding one. Four names map onto others: `neutral` and `foreground` are `muted`, the word the rest of the package uses; `accent` is `--primary`'s hover tint, so a washed `primary` renders the same thing; `info` is covered by the `success | warn | destructive` triad. `brand` falls back to `--primary` in an app that defines no `--brand`.
-- **Ink is handed down by whatever paints.** `toneClass(tone)` is a palette and sets no ink. A surface that fills adds `INK_ON_FILL`; a tinted one adds `INK_ON_CARD`, `INK_ON_POPOVER` or `INK_ON_SIDEBAR`, and one the package does not name spreads `inkOnSurfaceStyle(token)` into `style` rather than building a class. Both declare `--ink` and `--ink-muted`, which every type primitive reads, falling back to the page. Paint a background without them and a nested `TypographyLabel` prints `--foreground` on your fill, which measures 2.34:1 on `--primary`. On a hue fill `--ink-muted` equals `--ink`: a filled control has one ink, and wanting a second rung means wanting a tinted surface.
-- `Button`: `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` (default `solid`), `tone?: Tone` (defaults to `primary` on a solid button and `muted` on every other variant — filling a button in is how a page says this is the action), `size?: "xs" | "sm" | "md" | "lg" | "xl"` (default `md`), `icon?: boolean` for a square glyph box, `pill?: boolean` for full-round corners, `href` to make it a link, `render` for an element that is neither a button nor a link. Variant is how much ink it spends and tone is what the ink means, on separate axes, so a quiet delete is `variant="ghost" tone="destructive"`.
-- `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`, `href` for a badge that leads somewhere. Same axes and same spellings as `Button`, minus `link`, which belongs to things you click. `warning` and `supertype` were `tone="warn"` and `tone="brand"` under invented names.
+- `TypographyEyebrow`: `tone?: "heading" | "label" | "muted" | "subtle"`, `size?: "sm" | "xs" | "2xs" | "3xs"`, `as?`. Each tone carries the rung it is usually set at and `size` overrides it, so omitting it changes nothing. Use `muted` for the uppercase micro-label over a group of controls, and `subtle` for a column head or rail marker read on the way past.
+- `TypographyStat`: `size?: "inherit" | "3xs" | "2xs" | "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "card" | "panel" | "section" | "page" | "display"`, `figures?: "tabular" | "proportional"`, `tone?: "default" | "muted"`.
+- `TypographyLink`: `href` (required), `tone?: Tone` (default `muted`), `addArrow?`, `newTab?`. The `href` decides whether the link is internal or external.
+- `TypographyHighlight`: `tone?: HighlightTone`, one of `"primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, plus `seed?: number`.
+- `Card`: `href`, `title`, `description`, `icon`, `external`. An `href` makes the whole card a link.
+- `Anchor`: `href` (required), plus `external`/`newTab`.
+- `Tone` is the semantic colour vocabulary shared by `Button`, `Badge`, `Callout`, `TypographyLink` and `TabsList`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`.
+- **`CAP_TRIM` centres a mark on the letters.** `items-center` centres line boxes, which reserve room for ascenders and descenders the string may not use. Put `CAP_TRIM` on the text element, never on the row.
+- **`ON_FIRST_LINE` is the same fix from the mark's side.** For rows where a mark names the first line, use `items-start` and `ON_FIRST_LINE` so the mark sits in a wrapper one line tall.
+- **Ink is handed down by whatever paints.** `toneClass(tone)` is a palette and sets no ink. A filled surface adds `INK_ON_FILL`; a tinted one adds `INK_ON_CARD`, `INK_ON_POPOVER` or `INK_ON_SIDEBAR`. If a surface does not declare them, spread `inkOnSurfaceStyle(token)` into `style` instead of building a class.
+- `Button`: `variant?: "solid" | "soft" | "outline" | "ghost" | "link"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm" | "md" | "lg" | "xl"` (default `md`), `icon?: boolean`, `pill?: boolean`, `href` to make it a link, `render` for an element that is neither a button nor a link.
+- `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`, `href` for a badge that leads somewhere.
 - `Callout`: `tone?: Tone`, `density?: "compact" | "editorial"`, `title`, `icon`, `action`.
-- `Bulletin`: the panel shape with no copy in it — `variant?: "card" | "line"` (default `card`), `accent` (drawn along the top edge, full width, before the padding; `<Ribbon />` is the one that ships), `eyebrow`, `headline`, `lede`, `points` (a `BulletinPoint[]` of `{ title, body, mark?, ink? }`, where `mark` and `ink` are class names like `bg-fern`/`text-fern-ink`; one point takes the width, two or more go two-up from `sm`), `action` (the control on the footer rule), `footnote` (the line opposite it), `children` (under the rule) and `className`. Every slot is optional and an omitted one renders nothing, so the same component covers a credits panel and a headline with one button under it. Reach for it for an announcement, a release note, a status bulletin. `Ribbon` takes `hues?: RibbonHue[]` (default `EDITORIAL_INKS`, the eight categorical hues as data) and states no size of its own — the caller passes `h-1.5 w-full` on a panel and `h-1 min-w-20 flex-1 rounded-full` in a row.
-- `Colophon`: `Bulletin` with this package's words in it, and the words are not props. `variant?: "card" | "line"` (default `card`), plus `label` (the link's words, for translation) and `children` (the consumer's own credit, rendered under the rule on `card`). A compact statement block for a page (`card`) or a footer row (`line`). There is nothing to configure, so `<Colophon />` is the whole call. Its copy is deliberately not props: this is the package's only content component — every other block is an empty container whose words come from the call site — which makes it a mark rather than a block, and a mark every site rewrites is not a mark. An app wanting to say something in its own words wants a `Card`. It draws the eight categorical hues and inks two of them, all declared in theme.css: an app that imported tokens.css alone renders a panel with an invisible ribbon and no error.
-- **`Colophon` or `BuiltWithFoundations`.** A colophon is a block with something to say and needs a place to say it — a credits page, an about page, the foot of a long article. `BuiltWithFoundations` is one item in a row somebody else laid out, beside a privacy link and a copyright line, and says only where the site came from. The test is what the surface is for: somewhere with its own columns already takes the link, and somewhere the block itself is being placed takes the colophon. There is no `Colophon` variant rendering the link alone, since that would be a second name for a component that already has one. `BuiltWithFoundations` is a `Button variant="outline" size="sm"` with an `href`, so it sits on the same hairline and the same radius rung as every other control on the page. `FoundationsMark` is the eight-hue chip alone and `FOUNDATIONS_URL` the bare href.
+- `Bulletin`: `variant?: "card" | "line"` (default `card`), `accent`, `eyebrow`, `headline`, `lede`, `points`, `action`, `footnote`, `children`, `className`.
 - `DisclosureGroup`: `type?: "multiple" | "single"`, `defaultValue` (matches the title string).
-- `TabsList`: `variant?: "default" | "line"`, `tone?: Tone` (default `primary`). The tone
-  inks the marker alone, which on `line` means the underline and the active icon. The
-  boxed track keeps its marker flat, so a tone there paints nothing.
-- `TabGroup`: `tabs: readonly TabItem[]` (`{ value, label, icon?, content }`), `defaultValue?`,
-  `value?`, `onValueChange?`, `variant?`, `tone?`, `iconPosition?: "inline-start" | "inline-end"`.
-  `icon` is an element (`<Icons.Mic />`) that the trigger sizes and inks. Reach for it
-  whenever the tabs are data, and compose `Tabs`/`TabsTrigger` by hand only for a shape
-  it cannot express.
+- `TabsList`: `variant?: "default" | "line"`, `tone?: Tone` (default `primary`).
+- `TabGroup`: `tabs: readonly TabItem[]` (`{ value, label, icon?, content }`), `defaultValue?`, `value?`, `onValueChange?`, `variant?`, `tone?`, `iconPosition?: "inline-start" | "inline-end"`.
 
 ## Writing copy
 
 Every string a reader sees goes through this: page copy, section notes, button
-labels, callout titles, error messages, and the comments you leave in the file.
-Write the way a person writes when they know the subject and respect the reader's
-time.
-
-- **Say the thing.** State what is true and move on. Skip the setup sentence, the
-  restatement, and the closing summary of what you just said.
-- **Define forwards.** "A tone sets three variables and the component paints from
-  them" over "the component does not branch on the tone". Reach for a negative
-  only when the absence is the point.
-- **One em dash per page, at most.** Prefer a full stop, a comma, or a colon. The
-  same goes for a parenthetical aside mid-sentence.
-- **No arrow glyphs in prose.** Write "3.44:1 in light, 6.75:1 in dark" rather
-  than joining the two with an arrow. Where a UI genuinely points at something,
-  render a real icon.
-- **Watch the tacked-on clause.** "…, and it is the shape to reach for", "…, and
-  it exists so that…". The second half is usually the point: lead with it, or
-  make it its own sentence.
-- **Break the triples.** "X, Y, and Z" as a rhetorical flourish, three clauses
-  joined by "and", and the "not just A, but B" shape all read as machine prose.
-  Two items, or a list.
-- **Cut the throat-clearing.** No "it is worth noting", "it is important to",
-  "simply", "just", "of course", "in other words". No "this is not X, it is Y".
-- **Skip the rationale.** A note explains what the reader needs to use the thing.
-  Design history, near-misses, and the case for a decision go in the commit
-  message or the docs, not in the copy.
-- **Concrete over abstract.** Name the class, the prop, the file. "Five
-  components take the prop" beats "several components".
-- **Vary the sentences.** A paragraph of same-length clauses reads as generated
-  even when every sentence is true.
-- **Headings are labels.** "How it stays current", not "Why it cannot go stale".
-
-Code samples and commit messages stay conventional. This is about prose.
+labels, callout titles, error messages, and comments in the code. Write as a
+person would: direct, clear, and respectful of the reader's time.
+
+- **Say the thing.** State what is true and move on. Skip the setup sentence and
+  the closing summary of what you just said.
+- **Define forwards.** Prefer a direct description over a negative form unless the
+  absence is the point.
+- **One em dash per page, at most.** Prefer a full stop, a comma, or a colon.
+- **No arrow glyphs in prose.** Write “3.44:1 in light, 6.75:1 in dark” instead of
+  joining the two with an arrow.
+- **Lead with the point.** If a clause explains the reason, put it up front or make
+  it its own sentence.
+- **Cut the AI scaffolding.** Avoid “it is not…”, “there is no…”, “this is not…”,
+  “what this does is…”, “the reason is…”, and “because a…” patterns when a
+  direct statement does the work.
+- **Write the actual rule.** Prefer “Badges are labels, not links” to “This is not
+  a link, because a badge is not a link.” Prefer “One function builds the set” to
+  “There is one function because the package builds the whole set in one place.”
+- **Break the triples.** Long “X, Y, and Z” rhythms read like machine prose.
+- **Cut the throat-clearing.** Avoid “it is worth noting”, “it is important to”,
+  “simply”, “just”, “of course”, and “in other words”.
+- **Skip the rationale.** Explain what the reader needs to use, not the design
+  history behind it.
+- **Concrete over abstract.** Name the class, the prop, or the file.
+- **Vary the sentences.** A paragraph of same-length clauses reads as generated.
+- **Headings are labels.** “How it stays current” is clearer than “Why it cannot go stale”.
+
+Code samples and commit messages should stay conventional. This is about prose.
 
 ## Common mistakes
 
 - `<p className="text-sm text-muted-foreground">`: use `<TypographyMuted>`.
-- `<h2 className="text-lg font-semibold">`: use `<TypographyH2>`, or
-  `headingClass()` to pass classes into someone else's component.
-- Importing `Card`, `Callout` or `Button` from `@supertype.ai/foundations`. They
-  live in `@supertype.ai/foundations/blocks`.
-- `<Button variant="destructive">` or `variant="secondary"`: those are tones.
-  Write `variant="soft" tone="destructive"`, `variant="solid" tone="secondary"`.
+- `<h2 className="text-lg font-semibold">`: use `<TypographyH2>`, or `headingClass()`.
+- Importing `Card`, `Callout` or `Button` from `@supertype.ai/foundations`. They live in `@supertype.ai/foundations/blocks`.
+- `<Button variant="destructive">` or `variant="secondary"`: those are tones. Write `variant="soft" tone="destructive"`, `variant="solid" tone="secondary"`.
 - `<Button size="icon-sm">`: one size ladder. Write `size="sm" icon`.
-- `<Badge variant="warning">` or `variant="supertype"`: tones, and misspelled ones.
-  Write `variant="outline" tone="warn"` and `variant="solid" tone="brand"`.
-- `tone="neutral"`, `tone="foreground"` or `tone="accent"`: all three went when the
-  tone lists merged. Write `tone="muted"` for the first two, `tone="primary"` for
-  the third.
-- An `<a>` or `<Link>` styled by hand to look like a button, and equally
-  `render={<a href="/x" />}` or `render={<Link href="/x" />}` on anything that
-  takes an `href`. Write `<Button href="/x">`. `Button`, `Badge`, `Card` and
-  `TypographyLink` all take `href` and route it through one rule
-  (`resolveLink`): a scheme leaves the app and gets `target`/`rel`, a `#hash`
-  stays a plain anchor, everything else goes through the router's `Link` and
-  keeps the view transition. A hand-passed anchor skips all of that. `render` is
-  for an element that is genuinely not a link — and for `RailLink`, which takes a
-  router `Link` that way on purpose, since `essay/rail.tsx` has to import without
-  Next.
-- Exporting a constant from a `"use client"` module and importing it into a server
-  component. It crosses the boundary as a stub, not a string, so an `href` built that
-  way arrives as a function. Keep shared constants in a plain module.
+- `<Badge variant="warning">` or `variant="supertype"`: tones, and misspelled ones. Write `variant="outline" tone="warn"` and `variant="solid" tone="brand"`.
+- `tone="neutral"`, `tone="foreground"` or `tone="accent"`: all three were replaced when the tone lists merged. Write `tone="muted"` for the first two, `tone="primary"` for the third.
+- Hand-styling an `<a>` or `<Link>` to look like a button. Write `<Button href="/x">` instead.
+- Exporting a constant from a `"use client"` module and importing it into a server component.
 - `<TypographyMuted tone="default">`: a type error. Use `TypographyP`.
-- Binding fonts with `font.className` instead of `font.variable`. The className
-  form sets `font-family` on the element and leaves the roles unresolved.
-- Writing the style layer out by hand. `@import "@supertype.ai/foundations";` after
-  `@import "tailwindcss";` is the whole of it: it carries tokens, theme, type and
-  prose in order and registers the package's own `@source`. Split into the granular
-  imports, an app owns the order, the palette and the scan path — and a wrong
-  `@source` path purges every class the package ships, silently.
-- Using `Accordion` for a static FAQ. `Disclosure` runs on the browser alone.
+- Binding fonts with `font.className` instead of `font.variable`.
+- Writing the style layer out by hand. `@import "@supertype.ai/foundations";` after `@import "tailwindcss";` is the whole of it.
+- Using `Accordion` for a static FAQ. `Disclosure` is the browser-native version.
 - Adding a second `@custom-variant dark`. `tokens.css` already binds it.
 
-Run `npx foundations doctor` in the app to check the font binding, the style layer
-and the dark variant.
+Run `npx foundations doctor` in the app to check the font binding, the style layer and the dark variant.
 
 ## Surfaces
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.36",
+  "version": "0.2.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -68,6 +68,10 @@
       "require": "./dist/cjs/eslint.js",
       "default": "./dist/eslint.js"
     },
+    "./optical": {
+      "types": "./dist/optical.d.ts",
+      "default": "./dist/optical.js"
+    },
     "./rehype": {
       "types": "./dist/rehype.d.ts",
       "default": "./dist/rehype.js"
@@ -89,6 +93,7 @@
     "test": "yarn build && vitest run",
     "test:watch": "vitest",
     "check:llms": "node scripts/check-llms.mjs",
+    "check:consumers": "node scripts/consumers.mjs",
     "check:pins": "node scripts/pins.mjs",
     "release": "node scripts/release.mjs",
     "sync": "node scripts/sync.mjs",