Setup

Coding agents

A new agent usually writes text-sm text-muted-foreground until it learns the primitive exists. This package ships a summary for that, plus two checks that catch the gaps the summary misses.

The one line

llms.txt installs alongside dist/. Reference it from whatever file your agent reads at the start of a session:

# CLAUDE.md, AGENTS.md, or your agent's equivalent

@node_modules/@supertype.ai/foundations/llms.txt

npx foundations init prints this line for you to paste. The file it belongs in is yours.

What is in the file

206 lines, in 9 sections: Rules, Which component, Entry points, Props worth knowing, Writing copy, Common mistakes, Surfaces, Upgrading from 0.3, Docs. It is written for a first-time agent, so it leads with the rules and gets to the API afterward.

## Rules

1. **Never write type styles by hand.** If you are about to write `text-sm`,
   `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 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 that gets a background
   needs `INK_ON_FILL` (a tone fill) or `style={inkOnSurfaceStyle("--card-foreground")}`
   (any other surface: `--card`, `--popover`, `--sidebar` or your own), or the text
   inside it keeps the page's ink and fails contrast silently. `Card` and
   `Bulletin` already do it for the card.
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.

Then a table mapping what you want to the component that does it, the entry point each one ships from, and the props worth knowing. A section on writing copy sets the register for the words themselves, and one on common mistakes covers what goes through silently:

## Common mistakes

- `<p className="text-sm text-muted-foreground">`: use `<TypographyMuted>`.
- `<h2 className="text-lg font-semibold">`: use `<TypographyH2>`, or `headingClass()`.
  Lint enforces this on `<p>` and `<h1>`-`<h6>`, where the tag says the content is text.
- 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 className="bg-primary text-background">` or `<Button variant="ghost" className="text-muted-foreground">`: a fill or ink written past the tone axis, which is the one pair nothing measures. Write `variant="solid" tone="brand"`, `variant="ghost" tone="muted"`. Lint enforces this on `Button` and `Badge` once a consumer passes `designRules({ tone: true })`.
- `<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`.
- Writing the style layer out by hand. `@import "@supertype.ai/foundations";` after `@import "tailwindcss";` is the whole of it.
- Adding a second `@custom-variant dark`. `tokens.css` already binds it.
- `<TypographyCaption className="flex items-center gap-1"><Icons.Clock className="size-3" /> 44d ago</TypographyCaption>`, or an icon in a wrapper beside the words: a glyph centred on a line box, or pushed down a pixel, is right at one rung and wrong at the rest. Write `<TypographyCaption mark={<Icons.Clock />}>44d ago</TypographyCaption>`.
- `<Icons.Check className="inline h-4 w-4 align-middle" />` or `-mt-0.5` on an inline icon. Pass it as the words' `mark`, or wrap it in `<Mark>` inside a sentence.
- `<Badge><Icons.Mail className="size-3" />CC</Badge>`: the badge sizes its glyph. Drop the class.
- `<div className="flex items-center gap-2"><span>WhatsApp</span><TypographyStat size="2xs">+62…</TypographyStat></div>`: words at two sizes line up on their baseline. Write `items-baseline`.
- `text-[10rem]` for a display ornament. The ramp goes to `text-9xl`; past that, name the size in CSS so something else can share it.

Run `npx foundations doctor` in the app to check the font binding, the style layer and the dark variant.

How it stays current

The prose is hand-written, since the guidance is the useful part. Coverage is mechanical: a build-time check walks the real exports of every entry point and fails the build when a name is missing from the file.

yarn build runs the check across all 9 entry points in the exports map and reports the count it covered, so every component that ships appears here. Judging whether the advice still holds stays a human job, so keep the guidance short enough to re-read.

The lint rules

An agent can miss the summary. The same design rules ship as ESLint selectors from @supertype.ai/foundations/eslint, which fail a build where the summary only advises:

// eslint.config.js
import { designRules } from "@supertype.ai/foundations/eslint";

export default [
  {
    files: ["app/**/*.tsx", "components/**/*.tsx"],
    rules: {
      "no-restricted-syntax": [
        "error",
        ...designRules({ accents: "the brand tints", weights: true }),
      ],
    },
  },
];

An agent reaches for a utility class before a primitive, so the rules are written around that habit. They catch hand-rolled colour (bg-zinc-800, a hex, a dark: override of a token), a type style written out on a <p> where a primitive exists, a size class on a component that owns its size, a surface token printed as ink, and a margin nudging an icon into line. Plain data, no plugin, ESM and CommonJS builds both. The philosophy page has the full set and why each one is there. See the tooling docs.

doctor in CI

The wiring an agent gets wrong sits outside the JSX. A missing @source line, imports in the wrong order, a font bound with .className: all silent, all invisible to a linter.

- run: npx foundations doctor

Three layers

llms.txt tells the agent what to write. The lint rules catch what it wrote anyway. doctor checks the wiring both of them are blind to, and exits non-zero on a real problem.