Better foundations

Install

Install it with three commands: add the package, initialize the CSS, and run the wiring check.

yarn add @supertype.ai/foundations
npx foundations init      # adds and reorders the CSS imports, prints the rest
npx foundations doctor    # checks the wiring

After a version bump, npx foundations upgrade moves the code the release changed. Upgrading lists what each release changes.

Every release is tagged and published, so you can pin a specific commit ahead of the next release.

Here is what init writes. This site uses the same block, unchanged:

/* app/global.css */
@import "tailwindcss";
@import "@supertype.ai/foundations/tokens.css";
@import "@supertype.ai/foundations/theme.css";
@import "@supertype.ai/foundations/type.css";
@import "@supertype.ai/foundations/prose.css";
@import "@supertype.ai/foundations/shiki.css";

@source '../node_modules/@supertype.ai/foundations/dist/**/*.js';

Fonts are the one part you wire up yourself. next/font runs in your app and hashes its variable names at build time, so the binding belongs in your layout:

// app/layout.tsx
import { Ubuntu_Sans, Ubuntu_Sans_Mono, Average } from "next/font/google";

const sans = Ubuntu_Sans({
  variable: "--font-ubuntu-sans",
  subsets: ["latin"],
});
const mono = Ubuntu_Sans_Mono({
  variable: "--font-ubuntu-sans-mono",
  subsets: ["latin"],
});
const serif = Average({
  variable: "--font-average",
  weight: "400",
  subsets: ["latin"],
});

const fonts = `${sans.variable} ${mono.variable} ${serif.variable}`;

<html className={`${fonts} font-sans`}>

If you use a coding agent

The package ships an llms.txt alongside its dist/: the public API, the rules, and the common mistakes that tend to sneak into a build. One line is enough to point an agent at it, so it stops generating text-sm text-muted-foreground when a primitive already exists.

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

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

Coding agents covers what is in the file, how it stays current, and the lint rules and doctor run that catch what it misses.

Legibility with mathematical rigor

WCAG is good for compliance. If you swap the ink and the ground, the number stays the same, but on screen the feeling changes: dark letters on a bright field can look thinner, and light letters on a dark field can feel heavier. The two samples below carry the same ratio to a tenth, both pass AA, and still read a little apart.

The package measures its palette twice. contrast answers the compliance question, and lc answers the design one: whether your secondary ink is meaningfully quieter than your primary, and whether it still feels that way in dark mode. Both read the resolved cascade, so what gets measured is the page a browser actually paints.

checkLegibility and checkSignals hold those floors across both themes in CI. Every figure above was computed at build time from the stylesheet this site installs, including the two ratios in that row: the same tertiary ink measures 3.44:1 in light and 6.75:1 in dark, and reads 59.5 Lc against 47.8. Two measures has the maths and the call sites.

What is in here

The written reference lives in the repo: the README and docs.

In production

Sites running the package. Both install it from a tag, the way the instructions above describe, so you are seeing these components at full size on real content.