@supertype.ai/foundations 0.1.28 → 0.1.29

package/llms.txt

@@ -41,13 +41,16 @@ reference: https://github.com/supertypeai/foundations
 | inline code | `TypographyInlineCode` | root |
 | a link | `TypographyLink` | 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` |
 | a link card, or a grid of them | `Card`, `Cards` | `/blocks` |
 | an aside, warning or note | `Callout` | `/blocks` |
 | numbered instructions | `Steps`, `Step` | `/blocks` |
 | an FAQ or collapsible, no JS | `Disclosure`, `DisclosureGroup` | `/blocks` |
 | an animated accordion | `Accordion` (client) | `/blocks` |
-| tabbed content | `Tabs` or `TabGroup` (client) | `/blocks` |
+| tabbed content | `TabGroup` when the tabs are data, `Tabs` to compose by hand (client) | `/blocks` |
 | a long-form article page | `EssayHeader` + `EssayLayout` + `EssaySection` | `/essay` |
+| 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` |
 | page metadata and JSON-LD | `createSeo` | `/seo` |
@@ -58,15 +61,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`, `eyebrowClass`. Types: `TypographyTag`, `ParagraphVariants`, `ListProps`, `CaptionVariants`, `LabelVariants`, `StatVariants`, `LinkTone`, `HighlightTone` |
-| `@supertype.ai/foundations/blocks` | `Cards`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `Callout`, `Steps`, `Step`, `Disclosure`, `DisclosureGroup`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `TabGroup`, `Tab`, `SEGMENT` |
+| `@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/mdx` | `proseMdxComponents` |
-| `@supertype.ai/foundations/essay` | `createEssay`, `EssayHeader`, `EssayLayout`, `EssaySection`, `EssayPullQuote`, `EssayFigure`, `EssayMovements`, `EssayDocument`, `EssayColumns`, `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/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` | `designConfig` (the whole set as one flat-config entry), plus `colourRules`, `typographyRules`, `themeOverrideRules`, `surfaceAsInkRules`, `renamedTokenRules` for building your own. Types: `FlatConfigEntry`, `DesignConfigOptions`, `RestrictedSyntax`, `ColourOptions`, `TypographyOptions` |
+| `@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/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`. Types: `Rgb`, `Theme`, `LegibilityFailure`. Build-time only |
+| `@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 |
 
 ## Props worth knowing
 
@@ -78,20 +81,39 @@ reference: https://github.com/supertypeai/foundations
 - `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?: "foreground" | "primary" | "secondary"`, `addArrow?`, `newTab?`. Internal versus external is decided from the href.
-- `TypographyHighlight`: `tone?: "primary" | "success" | "ochre" | "terracotta" | "sage" | "fig"`, `seed?: number`.
+- `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.
 - `Card`: `href`, `title`, `description`, `icon`, `external`. An href makes the whole card a link.
-- `Callout`: `tone?: "muted" | "destructive" | "warn" | "accent"`, `density?: "compact" | "editorial"`, `title`, `icon`, `action`.
+- `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.
+- `Callout`: `tone?: Tone`, `density?: "compact" | "editorial"`, `title`, `icon`, `action`.
 - `DisclosureGroup`: `type?: "multiple" | "single"`, `defaultValue` (matches the title string).
-- `TabsList`: `variant?: "default" | "line"`.
+- `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.
+- `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`.
 
 ## 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.
-- Importing `Card` or `Callout` from `@supertype.ai/foundations`. They live in
-  `@supertype.ai/foundations/blocks`.
+- 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.
+  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`.
 - Binding fonts with `font.className` instead of `font.variable`. The className
   form sets `font-family` on the element and leaves the roles unresolved.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supertype.ai/foundations",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -117,6 +117,7 @@
     "next": "^15.5.7",
     "next-view-transitions": "^0.3.5",
     "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "typescript": "^5.7.0",
     "vitest": "4.1.11"
   },

package/src/theme.css

@@ -18,20 +18,31 @@
      other's, so the ink is what tells two swatches apart. checkSignals holds the
      fill to 3:1 and the ink to 4.5:1. */
   --color-terracotta: var(--terracotta);
-  --color-terracotta-foreground: var(--terracotta-foreground);
+  --color-terracotta-ink: var(--terracotta-ink);
   --color-ochre: var(--ochre);
-  --color-ochre-foreground: var(--ochre-foreground);
+  --color-ochre-ink: var(--ochre-ink);
   --color-moss: var(--moss);
-  --color-moss-foreground: var(--moss-foreground);
+  --color-moss-ink: var(--moss-ink);
   --color-fern: var(--fern);
-  --color-fern-foreground: var(--fern-foreground);
+  --color-fern-ink: var(--fern-ink);
   --color-sage: var(--sage);
-  --color-sage-foreground: var(--sage-foreground);
+  --color-sage-ink: var(--sage-ink);
   --color-stone: var(--stone);
-  --color-stone-foreground: var(--stone-foreground);
+  --color-stone-ink: var(--stone-ink);
   --color-fig: var(--fig);
-  --color-fig-foreground: var(--fig-foreground);
+  --color-fig-ink: var(--fig-ink);
   --color-cocoa: var(--cocoa);
+  --color-cocoa-ink: var(--cocoa-ink);
+
+  /* Deprecated aliases. Registered so an unmigrated call site keeps rendering;
+     the ESLint rules flag it so it does not stay unmigrated. */
+  --color-terracotta-foreground: var(--terracotta-foreground);
+  --color-ochre-foreground: var(--ochre-foreground);
+  --color-moss-foreground: var(--moss-foreground);
+  --color-fern-foreground: var(--fern-foreground);
+  --color-sage-foreground: var(--sage-foreground);
+  --color-stone-foreground: var(--stone-foreground);
+  --color-fig-foreground: var(--fig-foreground);
   --color-cocoa-foreground: var(--cocoa-foreground);
 
   --color-chart-1: var(--chart-1);
@@ -57,11 +68,19 @@
   --shadow-recessed: var(--elevation-recessed);
 
   /* Additive scale off a 10px `lg` — fixed pixel offsets, so no oddball values a
-     multiplicative scale would produce. `rounded-full` stays a pill. */
+     multiplicative scale would produce. `rounded-full` stays a pill.
+
+     The container rung was +4px, the one step in the run that was not 2, and 14px
+     on a card read softer than anything else the package draws — a panel rounder
+     than the button sitting inside it. At +2 the run below the marketing sizes is
+     6 / 8 / 10 / 12, evenly spaced, and the jump to `2xl` is left to say what it
+     was always meant to: this one is a feature card, not a container. Card,
+     Accordion, and the MDX pre/img/table frames all step down together, which is
+     the point of moving the token rather than the five call sites. */
   --radius-sm: calc(var(--radius) - 4px); /* 6px */
   --radius-md: calc(var(--radius) - 2px); /* 8px  — inputs, menus, small controls */
   --radius-lg: var(--radius); /* 10px — buttons, default control */
-  --radius-xl: calc(var(--radius) + 4px); /* 14px — cards */
+  --radius-xl: calc(var(--radius) + 2px); /* 12px — cards, panels, framed blocks */
   --radius-2xl: calc(var(--radius) + 8px); /* 18px — marketing feature cards */
   --radius-3xl: calc(var(--radius) + 12px); /* 22px */
   --radius-4xl: calc(var(--radius) + 16px); /* 26px */
@@ -89,23 +108,40 @@
   /* Danger ships as an ink only: a vivid brick red harmonised toward terracotta. */
   --danger: hsl(5 72% 43%);
 
-  /* Latte-warm greens, clays and stone. Both cuts of each hue, light theme. */
+  /* Latte-warm greens, clays and stone. Both cuts of each hue, light theme.
+     `-ink`, not `-foreground`: in this package `-foreground` is the label printed
+     on a fill and `-ink` is the hue used as words, and these are the latter —
+     `checkSignals` holds them to 4.5:1 against the page, and printing one on its
+     own fill measures about 1.2:1. They shipped under the wrong suffix for long
+     enough that a docs page believed it and rendered them as bare squares. The
+     old names are kept below as aliases; the ESLint rules flag them. */
   --terracotta: hsl(10 54% 60%);
-  --terracotta-foreground: hsl(10 72% 40%);
+  --terracotta-ink: hsl(10 72% 40%);
   --ochre: hsl(44 60% 42%);
-  --ochre-foreground: hsl(44 78% 27%);
+  --ochre-ink: hsl(44 78% 27%);
   --moss: hsl(68 42% 41%);
-  --moss-foreground: hsl(68 60% 26%);
+  --moss-ink: hsl(68 60% 26%);
   --fern: hsl(133 30% 47%);
-  --fern-foreground: hsl(133 48% 30%);
+  --fern-ink: hsl(133 48% 30%);
   --sage: hsl(168 28% 47%);
-  --sage-foreground: hsl(168 46% 29%);
+  --sage-ink: hsl(168 46% 29%);
   --stone: hsl(202 24% 55%);
-  --stone-foreground: hsl(202 42% 36%);
+  --stone-ink: hsl(202 42% 36%);
   --fig: hsl(332 32% 61%);
-  --fig-foreground: hsl(332 50% 43%);
+  --fig-ink: hsl(332 50% 43%);
   --cocoa: hsl(20 16% 56%);
-  --cocoa-foreground: hsl(20 34% 39%);
+  --cocoa-ink: hsl(20 34% 39%);
+
+  /* Deprecated: these were always the ink, under shadcn's name for the opposite
+     thing. Use `-ink`; the ESLint rules flag the old name. */
+  --terracotta-foreground: var(--terracotta-ink);
+  --ochre-foreground: var(--ochre-ink);
+  --moss-foreground: var(--moss-ink);
+  --fern-foreground: var(--fern-ink);
+  --sage-foreground: var(--sage-ink);
+  --stone-foreground: var(--stone-ink);
+  --fig-foreground: var(--fig-ink);
+  --cocoa-foreground: var(--cocoa-ink);
 
   --background: hsl(43 33% 96%); /* #FAF8F3 */
   /* Near-black keyed to the latte hue, not a neutral #333: grey reads cold over
@@ -177,21 +213,29 @@
 
   /* Espresso twins: fills darken and inks lift to hold the same two bars. */
   --terracotta: hsl(10 54% 47%);
-  --terracotta-foreground: hsl(10 66% 66%);
+  --terracotta-ink: hsl(10 66% 66%);
   --ochre: hsl(44 60% 33%);
-  --ochre-foreground: hsl(44 72% 45%);
+  --ochre-ink: hsl(44 72% 45%);
   --moss: hsl(68 42% 32%);
-  --moss-foreground: hsl(68 54% 43%);
+  --moss-ink: hsl(68 54% 43%);
   --fern: hsl(133 30% 37%);
-  --fern-foreground: hsl(133 42% 49%);
+  --fern-ink: hsl(133 42% 49%);
   --sage: hsl(168 28% 37%);
-  --sage-foreground: hsl(168 40% 49%);
+  --sage-ink: hsl(168 40% 49%);
   --stone: hsl(202 24% 42%);
-  --stone-foreground: hsl(202 36% 60%);
+  --stone-ink: hsl(202 36% 60%);
   --fig: hsl(332 32% 49%);
-  --fig-foreground: hsl(332 44% 67%);
+  --fig-ink: hsl(332 44% 67%);
   --cocoa: hsl(20 16% 44%);
-  --cocoa-foreground: hsl(20 28% 62%);
+  --cocoa-ink: hsl(20 28% 62%);
+  --terracotta-foreground: var(--terracotta-ink);
+  --ochre-foreground: var(--ochre-ink);
+  --moss-foreground: var(--moss-ink);
+  --fern-foreground: var(--fern-ink);
+  --sage-foreground: var(--sage-ink);
+  --stone-foreground: var(--stone-ink);
+  --fig-foreground: var(--fig-ink);
+  --cocoa-foreground: var(--cocoa-ink);
 
   /* 4 points of lightness at L10 reads flat where the same 4 at L96 reads raised;
      ssite wrote `bg-card dark:bg-muted` at 109 sites before the ground dropped.