@supertype.ai/foundations 0.1.29 → 0.1.31

package/llms.txt

@@ -5,8 +5,8 @@ content blocks, a long-form essay shell, token and theme CSS, and build-time
 tooling for SEO, OG cards, lint rules and contrast checks.
 
 This file is for coding agents working in an app that consumes the package. It
-covers what to import and the mistakes that do not produce an error. Full
-reference: https://github.com/supertypeai/foundations
+covers what to import, how the copy should read, and the mistakes that pass
+silently. Full reference: https://github.com/supertypeai/foundations
 
 ## Rules
 
@@ -21,6 +21,15 @@ reference: https://github.com/supertypeai/foundations
 4. **Use colour tokens, never literal colours.** `bg-card`, `text-foreground`,
    `border-border`. No hex values, no `bg-zinc-800`, no `dark:` overrides that
    swap one token for another.
+5. **Paint a surface, hand down its ink.** Any element you give a background
+   needs `INK_ON_FILL` (a tone fill) or 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
+   `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.
 
 ## Which component
 
@@ -40,6 +49,8 @@ reference: https://github.com/supertypeai/foundations
 | a number or metric | `TypographyStat` | root |
 | 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 |
 | a highlighted phrase | `TypographyHighlight` | root |
 | a button, or a link that looks like one | `Button` | `/blocks` |
 | a status label, count or chip | `Badge` | `/blocks` |
@@ -61,15 +72,15 @@ reference: https://github.com/supertypeai/foundations
 
 | import | exports |
 |---|---|
-| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone` |
-| `@supertype.ai/foundations/blocks` | `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Button`, `buttonVariants`, `Badge`, `badgeVariants`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `SEGMENT`. Types: `ButtonLook`, `BadgeLook`, `TabItem` |
+| `@supertype.ai/foundations` | `cn`, `TypographyH1`, `TypographyH2`, `TypographyH3`, `TypographyH4`, `TypographyEyebrow`, `TypographyP`, `TypographyMuted`, `TypographyProse`, `TypographyList`, `TypographyProseList`, `TypographyCaption`, `TypographySmall`, `TypographyLabel`, `TypographyStat`, `TypographyInlineCode`, `TypographyLink`, `TypographyHighlight`, `headingClass`, `headingFace`, `eyebrowClass`, `toneClass`, `impliedTone`, `resolveLink`, `isExternalHref`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `Tone`, `HighlightTone`, `LinkBehavior`, `ResolvedLink` |
+| `@supertype.ai/foundations/blocks` | `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`. Types: `ButtonLook`, `BadgeLook`, `TabItem` |
 | `@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 — spread this), `designConfig` (the same set wrapped as a flat-config entry). The five builders `colourRules`, `typographyRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are still exported, but spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
+| `@supertype.ai/foundations/eslint` | `designRules` (every rule as one array, the one to spread), `designConfig` (the same set wrapped as a flat-config entry). The builders `colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` are exported too, though spreading them by hand is how a consumer ends up missing one. Types: `FlatConfigEntry`, `DesignRuleOptions`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
 | `@supertype.ai/foundations/rehype` | `rehypeProseCode`, `proseCodeOptions`, `PROSE_LANGS`, `PROSE_THEMES`. Build-time only, must not resolve React |
-| `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1, tinted inks at 4.5:1, labels against their own fill), `resolveTokens`, `formatFailures`, `specificity`, `parseColor`, `luminance`, `contrast`, `tokenCuts` (which cuts a token ships — fill, the label printed on it, the hue as words; the taxonomy `checkSignals` measures). Types: `Rgb`, `Theme`, `LegibilityFailure`, `TokenCuts`. Build-time only |
+| `@supertype.ai/foundations/contrast` | `checkLegibility` (inks at 4.5:1), `checkSignals` (fills at 3:1 — status hues, the categorical earth hues and the six chart series alike — tinted inks at 4.5:1, `--subtle-foreground` at the 3:1 it is documented for, labels against their own fill: 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 |
 
 ## Props worth knowing
 
@@ -77,51 +88,104 @@ reference: https://github.com/supertypeai/foundations
 - `TypographyH2`: `variant?`, plus `divider?: boolean` for a rule underneath.
 - `TypographyP`: `variant?: "ui" | "prose"` (default `ui`), `tone?: "default" | "muted"`.
 - `TypographyMuted`, `TypographyProse`, `TypographyProseList` are presets. The
-  prop each one pins is removed from its type, so passing it will not compile.
+  prop each one pins is dropped from its type, so passing it fails to compile.
 - `TypographyCaption`, `TypographyLabel`, `TypographySmall`: `size?: "sm" | "xs" | "2xs" | "inherit"`, `as?`.
 - `TypographyEyebrow`: `tone?: "heading" | "label"`, `as?`.
 - `TypographyStat`: `size?: "inherit" | "card" | "panel" | "page" | "display"`, `figures?: "tabular" | "proportional"`. Keep tabular where a value updates in place.
-- `TypographyLink`: `href` (required), `tone?: Tone` (default `muted`), `addArrow?`, `newTab?`. Internal versus external is decided from the href.
-- `TypographyHighlight`: `tone?: HighlightTone` — `"primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, `seed?: number`. Deliberately NOT `Tone`: this axis is categorical (which one it is), not semantic (what it means), which is the same split theme.css draws between the earth swatches and the status tokens.
+- `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.
-- `Tone` — the one semantic colour vocabulary, shared by `Button`, `Callout` and `TypographyLink`: `"muted" | "primary" | "secondary" | "brand" | "success" | "warn" | "destructive"`, defaulting to `muted` everywhere except a solid `Button`. Seven tones, seven tokens, one to one — that is the bar for adding one. There is no `neutral` (that is `muted`, the word the rest of the package uses), no `foreground` (also `muted`), no `accent` (that is `--primary`'s hover tint, so a washed `primary` renders the same thing) and no `info` (`success | warn | destructive` is already the whole triad). `brand` falls back to `--primary` in an app that defines no `--brand`.
-- `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, `render` for the element to become. Variant is how much ink it spends; tone is what the ink means — separate axes, so a quiet delete is `variant="ghost" tone="destructive"`, not a `destructive` variant.
-- `Badge`: `variant?: "solid" | "soft" | "outline" | "ghost"` (default `solid`), `tone?: Tone`, `size?: "xs" | "sm"` (default `sm`), `pill?: boolean`. Same axes and same spellings as `Button`, minus `link` — a badge is not a link. There is no `warning` or `supertype` variant; those were `tone="warn"` and `tone="brand"` under invented names.
+- `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.
 - `Callout`: `tone?: Tone`, `density?: "compact" | "editorial"`, `title`, `icon`, `action`.
 - `DisclosureGroup`: `type?: "multiple" | "single"`, `defaultValue` (matches the title string).
-- `TabsList`: `variant?: "default" | "line"`, `tone?: Tone` (default `primary`) — the tone
-  inks the marker only: on `line` the underline and the active icon. The boxed track's
-  marker is deliberately flat, so a tone there paints nothing.
+- `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 />`); the trigger sizes and inks it. Reach for it
-  whenever the tabs are data — do not rebuild it over `Tabs`/`TabsTrigger`.
+  `icon` is an element (`<Icons.Mic />`) that the trigger sizes and inks. Reach for it
+  whenever the tabs are data, and compose `Tabs`/`TabsTrigger` by hand only for a shape
+  it cannot express.
+
+## Writing copy
+
+Every string a reader sees goes through this: page copy, section notes, button
+labels, callout titles, error messages, and the comments you leave in the file.
+Write the way a person writes when they know the subject and respect the reader's
+time.
+
+- **Say the thing.** State what is true and move on. Skip the setup sentence, the
+  restatement, and the closing summary of what you just said.
+- **Define forwards.** "A tone sets three variables and the component paints from
+  them" over "the component does not branch on the tone". Reach for a negative
+  only when the absence is the point.
+- **One em dash per page, at most.** Prefer a full stop, a comma, or a colon. The
+  same goes for a parenthetical aside mid-sentence.
+- **No arrow glyphs in prose.** Write "3.44:1 in light, 6.75:1 in dark" rather
+  than joining the two with an arrow. Where a UI genuinely points at something,
+  render a real icon.
+- **Watch the tacked-on clause.** "…, and it is the shape to reach for", "…, and
+  it exists so that…". The second half is usually the point: lead with it, or
+  make it its own sentence.
+- **Break the triples.** "X, Y, and Z" as a rhetorical flourish, three clauses
+  joined by "and", and the "not just A, but B" shape all read as machine prose.
+  Two items, or a list.
+- **Cut the throat-clearing.** No "it is worth noting", "it is important to",
+  "simply", "just", "of course", "in other words". No "this is not X, it is Y".
+- **Skip the rationale.** A note explains what the reader needs to use the thing.
+  Design history, near-misses, and the case for a decision go in the commit
+  message or the docs, not in the copy.
+- **Concrete over abstract.** Name the class, the prop, the file. "Five
+  components take the prop" beats "several components".
+- **Vary the sentences.** A paragraph of same-length clauses reads as generated
+  even when every sentence is true.
+- **Headings are labels.** "How it stays current", not "Why it cannot go stale".
+
+Code samples and commit messages stay conventional. This is about prose.
 
 ## Common mistakes
 
-- `<p className="text-sm text-muted-foreground">` — use `<TypographyMuted>`.
-- `<h2 className="text-lg font-semibold">` — use `<TypographyH2>`, or
-  `headingClass()` if you must pass classes to someone else's component.
+- `<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, not
-  variants. Write `variant="soft" tone="destructive"`, `variant="solid" tone="secondary"`.
-- `<Button size="icon-sm">` — there is one size ladder. Write `size="sm" icon`.
-- `<Badge variant="warning">` / `variant="supertype"` — tones, and misspelled ones.
+- `<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 were
-  removed when the tone lists merged. Write `tone="muted"` for the first two and
-  `tone="primary"` for the third.
-- An `<a>` or `<Link>` styled by hand to look like a button. Pass it as
-  `render={<Link href="/x" />}`; the anchor keeps its link semantics.
-- `<TypographyMuted tone="default">` — a type error. Use `TypographyP`.
+- `tone="neutral"`, `tone="foreground"` or `tone="accent"`: all three went when the
+  tone lists merged. Write `tone="muted"` for the first two, `tone="primary"` for
+  the third.
+- An `<a>` or `<Link>` styled by hand to look like a button, and equally
+  `render={<a href="/x" />}` or `render={<Link href="/x" />}` on anything that
+  takes an `href`. Write `<Button href="/x">`. `Button`, `Badge`, `Card` and
+  `TypographyLink` all take `href` and route it through one rule
+  (`resolveLink`): a scheme leaves the app and gets `target`/`rel`, a `#hash`
+  stays a plain anchor, everything else goes through the router's `Link` and
+  keeps the view transition. A hand-passed anchor skips all of that. `render` is
+  for an element that is genuinely not a link — and for `RailLink`, which takes a
+  router `Link` that way on purpose, since `essay/rail.tsx` has to import without
+  Next.
+- Exporting a constant from a `"use client"` module and importing it into a server
+  component. It crosses the boundary as a stub, not a string, so an `href` built that
+  way arrives as a function. Keep shared constants in a plain module.
+- `<TypographyMuted tone="default">`: a type error. Use `TypographyP`.
 - Binding fonts with `font.className` instead of `font.variable`. The className
   form sets `font-family` on the element and leaves the roles unresolved.
 - Omitting `@source '../node_modules/@supertype.ai/foundations/dist/**/*.js'` from
   the CSS entry. Tailwind then purges every class the package ships.
 - Omitting `@import "@supertype.ai/foundations/theme.css"`. `tokens.css` names the
   colour roles but holds no values, so the whole palette resolves to nothing.
-- Using `Accordion` for a static FAQ. `Disclosure` needs no JavaScript.
+- Using `Accordion` for a static FAQ. `Disclosure` runs on the browser alone.
 - Adding a second `@custom-variant dark`. `tokens.css` already binds it.
 
 Run `npx foundations doctor` in the app to check the last four.
@@ -130,8 +194,8 @@ Run `npx foundations doctor` in the app to check the last four.
 
 Two classes change how everything renders, and both go on `<html>` or a subtree:
 
-- `.dark` re-points every colour token. It is bound by `tokens.css`, not by the
-  OS setting.
+- `.dark` re-points every colour token. `tokens.css` binds it to the class, so
+  the OS setting leaves it alone.
 - `.editorial` gives the heading role to the serif at weight 400 and retunes the
   whole heading ladder against an 18px body, instead of the product's 13px.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -82,7 +82,7 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/cjs-marker.mjs && node scripts/check-llms.mjs && node scripts/pins.mjs",
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/cjs-marker.mjs && node scripts/check-candidates.mjs && node scripts/check-llms.mjs && node scripts/pins.mjs",
     "dev": "tsc -p tsconfig.json --watch",
     "test": "yarn build && vitest run",
     "test:watch": "vitest",

package/src/theme.css

@@ -91,18 +91,35 @@
      both, so its label stays light in both. */
   --tint-foreground: hsl(0, 0%, 100%);
 
+  /* Which way a control moves under the pointer: away from the page, so it
+     deepens on latte and lifts on espresso. How far is the state's own
+     business, and hover spends 18%.
 
-  /* Status, on the same two-token rule as the categorical set below: the fill is
-     a mark (3:1), the ink is the same hue as words (4.5:1). Nothing prints a
-     label on a status fill — orange cannot carry white text at any lightness. */
-  --success: hsl(142 75% 31%);
+     The extreme rather than `--foreground`, because mixing toward an ink that
+     already sits near the fill gives a step the size of the gap between them:
+     `--primary` moved 4.9 ΔL* on latte against 6.2 on espresso from the same
+     declaration, and read as no hover at all. Against black and white every
+     tone clears 6 ΔL* in both themes. */
+  --hover-toward: hsl(0, 0%, 0%);
+
+
+  /* Status, on the same three-cut rule as every other tone: the fill is a mark
+     (3:1), the `-ink` is that hue used as words (4.5:1), and the `-foreground`
+     is the label printed on the fill (4.5:1 against it). A filled status
+     control is a real thing — `Button tone="warn" variant="solid"` — so the
+     pair is measured rather than assumed. checkSignals holds all three. */
+  --success: hsl(142 75% 29%);
   --success-ink: hsl(142 68% 28%);
+  /* White clears 4.94:1 here. At the old 31% it measured 4.42:1, which passed
+     nothing and shipped anyway, because no component was checked against it. */
+  --success-foreground: var(--tint-foreground);
   /* Was 52%, which measured 2.27:1 on latte — a dot you could not see. */
   --warn: hsl(30 100% 43%);
   --warn-ink: hsl(22 85% 36%);
-  /* Deprecated: --warn-foreground was always this ink, under shadcn's name for
-     the opposite thing. Use --warn-ink; the ESLint rules flag the old name. */
-  --warn-foreground: var(--warn-ink);
+  /* The label on the warn fill, and one value for both themes: amber is a mark
+     in each, so the ink that reads on it is deep in each. 4.84:1 on latte,
+     6.70:1 on espresso. White measured 3.37:1 and 2.44:1. */
+  --warn-foreground: hsl(30 25% 12%);
   --info: hsl(211 80% 43%);
   --info-ink: hsl(211 80% 40%);
   /* Danger ships as an ink only: a vivid brick red harmonised toward terracotta. */
@@ -153,6 +170,12 @@
   --popover-foreground: hsl(30 14% 12%);
   --primary: hsl(133 11% 33%); /* #4A5D4E */
   --primary-foreground: hsl(0 0% 100%);
+  /* The third cut, the one `--secondary` and every status hue already shipped.
+     A fill is a mark and words are read, so one value doing both jobs is tuned
+     for neither — and that is why the espresso CTA measured Lc 48.9 against
+     this theme's 89.3. On latte the two happen to coincide, so this is an
+     alias here and a value of its own under .dark. */
+  --primary-ink: var(--primary);
   /* Three tokens, because the accent pulls opposite ways: fill, the label on it,
      and the accent as text. Tuning any one for another sinks the third. */
   --secondary: hsl(14, 67%, 72%);
@@ -167,13 +190,23 @@
   --accent-foreground: hsl(133 11% 33%);
   --destructive: hsl(0 50% 36%);
   --destructive-foreground: hsl(0 0% 98%);
-  /* Soft beige-grey, to keep a rule un-intrusive. */
-  --border: hsl(40 15% 88%); /* #E3DFD8 */
+  /* Soft beige-grey, to keep a rule un-intrusive — but a rule still has to be
+     seen. L88 measured 1.20:1 on --background and 1.29:1 on --card, below the
+     1.34:1 the dark twin at L22 was rejected for, so the light theme shipped the
+     fainter hairline of the two. L80 puts --card at 1.56:1, within a point of
+     the dark theme's 1.57:1, so the same border reads the same weight in both. */
+  --border: hsl(40 15% 80%); /* #CFC8BA */
   --input: var(--border);
   --ring: hsl(133 11% 33%); /* the brand green */
+  /* A series is a fill: docs/cli.md promises every one of them clears 3:1 on the
+     page and on a card, and until `checkSignals` measured them two did not. The
+     sand was the worst in the palette at 2.18:1 — a 43° hue on a 43° ground, the
+     same colour 36 points apart in lightness. Saturation rises as it darkens, or
+     it lands as mud rather than as sand. The six stay 17.1 ΔE76 apart at their
+     closest (chart-4 against chart-6), which is where the floor sat before. */
   --chart-1: hsl(133 18% 45%);
-  --chart-2: hsl(14 47% 59%);
-  --chart-3: hsl(43 33% 60%);
+  --chart-2: hsl(14 47% 56%); /* 2.98:1 at L59 */
+  --chart-3: hsl(43 45% 42%); /* 2.18:1 at 33% L60 */
   --chart-4: hsl(200 20% 50%);
   --chart-5: hsl(30 12% 40%);
   /* A muted teal: the one cool hue the warm set leaves open, and far enough from
@@ -191,21 +224,27 @@
     inset 0 1px 3px hsl(30 18% 12% / 0.07),
     inset 0 0 0 1px hsl(30 18% 12% / 0.03);
   --sidebar: hsl(40 25% 94%); /* #F5F2EC */
-  --sidebar-foreground: hsl(0 0% 25%);
+  /* Warm-keyed like every other ink here. It shipped as hsl(0 0% 25%), the one
+     neutral grey in the light theme, on a surface hued at 40° — the same cold
+     read L146 rules out for --foreground. Same lightness step, 9.43:1. */
+  --sidebar-foreground: hsl(30 12% 24%);
   --sidebar-primary: hsl(133 11% 33%);
   --sidebar-primary-foreground: hsl(0 0% 100%);
   --sidebar-accent: hsl(133 15% 88%);
   --sidebar-accent-foreground: hsl(133 11% 25%);
-  --sidebar-border: hsl(40 15% 88%);
+  /* A sidebar rule sits on --sidebar, not the page, and that surface is lighter
+     than --background — so it needs 2 points more than --border to read the same
+     (1.49:1, against the dark twin's 1.49:1). */
+  --sidebar-border: hsl(40 15% 77%);
   --sidebar-ring: hsl(133 11% 33%);
 }
 
 .dark {
+  --hover-toward: hsl(0, 0%, 100%);
   /* --success does not flip: the same green clears 3:1 on espresso as on latte. */
   --success-ink: hsl(142 55% 58%);
   --warn: hsl(30 90% 55%);
   --warn-ink: hsl(33 60% 72%);
-  --warn-foreground: var(--warn-ink);
   --info: hsl(211 75% 60%);
   --info-ink: hsl(211 75% 64%);
   /* Soft terracotta-red. The light cut measured ~2.9:1 on espresso and read muddy. */
@@ -248,8 +287,14 @@
   --card-foreground: hsl(43 20% 92%);
   --popover: hsl(30 8% 14%);
   --popover-foreground: hsl(43 20% 92%);
-  --primary: hsl(133 18% 58%); /* #7A9E7E */
-  --primary-foreground: hsl(30 10% 13%);
+  /* Split in two, so each cut is tuned for its own job. The fill takes a white
+     label at Lc 83.0 against latte's 89.3, and still clears 3:1 as a mark on
+     espresso (3.36:1). The ink reads as words at Lc 73.8 against latte's 79.1.
+     Both sit inside the 15 Lc the themes are held to; the single token they
+     replace sat 30 Lc adrift on both counts. */
+  --primary: hsl(133 34% 34%);
+  --primary-foreground: var(--tint-foreground);
+  --primary-ink: hsl(133 26% 76%);
   /* Espresso twin: the fill darkens under a white label, the ink lifts as text. */
   --secondary: hsl(14, 64%, 37%);
   --secondary-foreground: hsl(0 0% 100%);
@@ -264,8 +309,12 @@
   --accent: hsl(133 12% 20%);
   --accent-foreground: hsl(133 18% 78%);
   /* Overwhelmingly an ink: sixty `text-destructive` sites, no fill carrying text.
-     The light value measured 2.08:1 here — a colour, not words. */
-  --destructive: hsl(0 65% 67%);
+     The light value measured 2.08:1 here — a colour, not words.
+     L67 read 4.48:1 on --muted, which is AA to two decimal places and under it
+     to three, on a surface with several hundred call sites. L68 is the smallest
+     step that clears with room to spare (4.64:1) rather than landing back on the
+     line; --background and --card, already clear, rise with it. */
+  --destructive: hsl(0 65% 68%);
   /* The ink is light here, so anything printed on it must be dark. Nothing does
      today; white would arm a 1.3:1 trap for whoever tries first. */
   --destructive-foreground: hsl(30 10% 10%);
@@ -278,7 +327,9 @@
   --chart-2: hsl(14 45% 55%);
   --chart-3: hsl(43 20% 70%);
   --chart-4: hsl(200 15% 55%);
-  --chart-5: hsl(30 8% 35%);
+  /* The espresso twin of the light sand: 2.26:1 on --card, the same failure the
+     light theme carried, in the theme that usually gets tuned first. */
+  --chart-5: hsl(30 8% 46%);
   --chart-6: hsl(178 30% 52%);
   /* A warm tint reads as haze on espresso: deep black, more spread. */
   --elevation-raised:
@@ -295,7 +346,9 @@
   --sidebar-primary-foreground: hsl(133 20% 10%);
   --sidebar-accent: hsl(30 8% 19%);
   --sidebar-accent-foreground: hsl(43 20% 85%);
-  --sidebar-border: hsl(30 8% 20%);
+  /* L20 measured 1.28:1 on --sidebar, the same too-faint rule the light theme
+     shipped. L24 is the twin of the light 1.49:1. */
+  --sidebar-border: hsl(30 8% 24%);
   --sidebar-ring: hsl(133 18% 58%);
 }
 

package/src/tokens.css

@@ -15,6 +15,7 @@
   --color-popover-foreground: var(--popover-foreground);
   --color-primary: var(--primary);
   --color-primary-foreground: var(--primary-foreground);
+  --color-primary-ink: var(--primary-ink);
   --color-secondary: var(--secondary);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-muted: var(--muted);
@@ -25,18 +26,18 @@
   --color-destructive-foreground: var(--destructive-foreground);
 
   /* Named for meaning, not hue: a `success` a project renders blue still reads
-     right. Each status hue ships twice — the fill is a mark, the ink is words. */
+     right. The fill is a mark, the ink is words, the foreground is the label
+     printed on the fill. */
   --color-success: var(--success);
   --color-success-ink: var(--success-ink);
+  --color-success-foreground: var(--success-foreground);
   --color-warn: var(--warn);
   --color-warn-ink: var(--warn-ink);
+  --color-warn-foreground: var(--warn-foreground);
   --color-info: var(--info);
   --color-info-ink: var(--info-ink);
   --color-danger: var(--danger);
 
-  /* Deprecated: this was always an ink. Use `warn-ink`. */
-  --color-warn-foreground: var(--warn-foreground);
-
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);

package/src/type.css

@@ -39,7 +39,7 @@
 
 @layer base {
   :root {
-    /* 680, not 600: Ubuntu Sans steps 500→600 by 9.3% where Geist stepped 11.9%,
+    /* 680, not 600: Ubuntu Sans steps 500 to 600 by 9.3% where Geist stepped 11.9%,
        and panel titles stopped separating from the labels inside them. */
     --heading-weight: 680;
   }