@supertype.ai/foundations 0.1.24

package/dist/typography/paragraph.d.ts

@@ -0,0 +1,157 @@
+import { type VariantProps } from "class-variance-authority";
+import type { ComponentProps, ReactNode } from "react";
+import { type WithAs } from "./as.js";
+/** The body layer: two axes and no more. A paragraph picks a rung and an ink; a
+ * caption is always secondary ink and picks a size. `lead` was a third rung a
+ * breakpoint away from `prose`, and its standfirst role is now the eyebrow's. */
+declare const pVariants: (props?: ({
+    variant?: "ui" | "prose" | null | undefined;
+    tone?: "default" | "muted" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type ParagraphVariants = VariantProps<typeof pVariants>;
+export declare function TypographyP({ className, variant, tone, children, ...props }: ComponentProps<"p"> & ParagraphVariants): import("react").JSX.Element;
+/** A preset's props: its base's, minus the axes it has decided. `keyof Pins` reads
+ * the exclusion off the pinned object the preset also spreads, so the two cannot
+ * drift — `<TypographyMuted tone="default">` used to compile and un-mute it. */
+type Preset<Base, Pins> = Omit<Base, keyof Pins>;
+type ParagraphProps = ComponentProps<"p"> & ParagraphVariants;
+/** The UI rung in the secondary ink. */
+declare const MUTED: {
+    readonly tone: "muted";
+};
+export declare function TypographyMuted(props: Preset<ParagraphProps, typeof MUTED>): import("react").JSX.Element;
+/** Reading-size body copy. `TypographyMuted` is the same ink one rung down. */
+declare const PROSE: {
+    readonly variant: "prose";
+    readonly tone: "muted";
+};
+export declare function TypographyProse(props: Preset<ParagraphProps, typeof PROSE>): import("react").JSX.Element;
+export type ListProps = ComponentProps<"ul"> & Pick<ParagraphVariants, "variant"> & {
+    ordered?: boolean;
+};
+export declare function TypographyList({ className, children, ordered, variant, ...props }: ListProps): import("react").JSX.Element;
+/**
+ * The reading rung, pinned. The name predates the axis and keeps every call site
+ * that already had it; `Preset` stops one re-opening the rung it names.
+ */
+declare const PROSE_LIST: {
+    readonly variant: "prose";
+};
+export declare function TypographyProseList(props: Preset<ListProps, typeof PROSE_LIST>): import("react").JSX.Element;
+/**
+ * Meta beside content: timestamps, counts, bylines, the key in a key-value row.
+ *
+ * Always the secondary ink and never a weight — a caption is secondary because
+ * it is muted, and 500 on top would have the colour and the weight arguing.
+ * `sm` is the default because meta is separated from body by ink, not size;
+ * the smaller rungs are a deliberate step down, not the norm.
+ *
+ * Leading is pinned per size rather than left to the rung. Plenty of captions
+ * are a wrapped sentence, and the ramp's tight setting sets those cramped —
+ * descenders nearly on the caps below. `leading-normal` writes `--tw-leading`,
+ * the variable the `text-*` step reads, so 1.5 wins at every rung.
+ *
+ * `inherit` is the parenthetical inside a heading, an eyebrow or a stat. It
+ * takes the size of whatever set it and resets the weight, because the only
+ * reason to sit there is to be quieter than the thing you qualify — and every
+ * container that sets a size for you sets a weight too.
+ */
+declare const captionVariants: (props?: ({
+    size?: "inherit" | "sm" | "xs" | "2xs" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type CaptionVariants = VariantProps<typeof captionVariants>;
+/**
+ * `as` covers the one thing that genuinely differs between call sites: whether
+ * the run is inline beside its subject or a block under it.
+ */
+export declare function TypographyCaption({ className, size, as, children, ...props }: WithAs<CaptionVariants>): import("react").JSX.Element;
+/**
+ * Small print set as a block: a note under the thing it annotates, rather than
+ * an aside inline with it. Same rung and same ink as the caption — small print
+ * is small because it is muted, and dropping it a rung as well is what made
+ * both apps hand-roll their own.
+ */
+declare const BLOCK: {
+    readonly as: "p";
+};
+export declare function TypographySmall(props: Preset<WithAs<CaptionVariants>, typeof BLOCK>): import("react").JSX.Element;
+/**
+ * The label role: a form label, a column header, the key a reader scans for.
+ * 500 is the only weight bump a dense surface needs below a heading.
+ *
+ * The rungs are the caption's, deliberately. A label and a caption are one pair
+ * — the key and the value, the name and the note — and a pair that cannot be set
+ * at one size is not a pair. Pinning the label to `sm` while the caption had an
+ * axis is what sent a key next to an `xs` value out to `font-medium text-xs` in
+ * a className, leaving the weight arguing with the rung it landed on.
+ *
+ * `as` is here for the same reason it is on `TypographyEyebrow`: a config panel
+ * names its sections at this size, and those names are the page's outline.
+ */
+declare const labelVariants: (props?: ({
+    size?: "inherit" | "sm" | "xs" | "2xs" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type LabelVariants = VariantProps<typeof labelVariants>;
+export declare function TypographyLabel({ className, size, as, children, ...props }: WithAs<LabelVariants>): import("react").JSX.Element;
+/**
+ * A numeric readout. Size and colour ride in via className per use.
+ *
+ * Tabular is right in a column and wrong in a headline, so it is an axis rather
+ * than a constant. Keep `tabular` anywhere a value updates in place.
+ */
+declare const statVariants: (props?: ({
+    size?: "inherit" | "display" | "card" | "panel" | "page" | null | undefined;
+    figures?: "tabular" | "proportional" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type StatVariants = VariantProps<typeof statVariants>;
+export declare function TypographyStat({ className, size, figures, children, ...props }: ComponentProps<"span"> & StatVariants): import("react").JSX.Element;
+/**
+ * A run of code inside a sentence: a command, a field name, a trigger.
+ *
+ * Everything is in `em`, not a rung: the chip has to sit in whatever size the
+ * sentence around it is set at, and the ramp differs per surface. The 0.9 is an
+ * optical correction — the mono face carries a taller x-height than the sans.
+ */
+export declare function TypographyInlineCode({ className, children, ...props }: ComponentProps<"code">): import("react").JSX.Element;
+/**
+ * A statement about the surface, not the link: `foreground` inside a paragraph,
+ * `primary` when the link is the point of the line, `secondary` for a note
+ * beneath a hero where `primary` would compete with the CTA beside it.
+ */
+declare const LINK_TONES: {
+    readonly foreground: "font-medium text-foreground";
+    readonly primary: "font-medium text-primary";
+    readonly secondary: "text-secondary-ink";
+};
+export type LinkTone = keyof typeof LINK_TONES;
+type TypographyLinkProps = Omit<ComponentProps<"a">, "href"> & {
+    href: string;
+    children: ReactNode;
+    tone?: LinkTone;
+    /** Defaults on for an off-site link. Turn it off for one that starts a flow the reader should stay in. */
+    newTab?: boolean;
+    /**
+     * A trailing arrow, for a link that ends a sentence and leads somewhere. The
+     * glyph follows the href: `↗` when the link leaves the site, `→` when it does
+     * not. That is the convention, and it is not a call site's to get wrong.
+     */
+    addArrow?: boolean;
+};
+/**
+ * The inline link.
+ *
+ * Internal and external are decided from the href, never at the call site: an
+ * href with a scheme renders a plain anchor and, if it is http(s), opens away
+ * with `rel="noopener noreferrer"`; everything else routes through the router's
+ * Link. `newTab` is the one override, for an off-site href that starts a flow
+ * the reader should stay in. Call-site props apply last, so a passed
+ * `target`/`rel` still wins.
+ *
+ * The router is `next-view-transitions`, imported rather than injected. Every
+ * project on this package is a Next app and wants the same link, and a factory
+ * bought router-agnosticism nobody used at the price of a component that could
+ * not be imported by name. One call site ended up on the unbound version that
+ * way and lost its decoration.
+ */
+export declare function TypographyLink({ href, children, tone, newTab, addArrow, className, ...props }: TypographyLinkProps): import("react").JSX.Element;
+export {};

package/dist/typography/paragraph.js

@@ -0,0 +1,229 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Link } from "next-view-transitions";
+import { cva } from "class-variance-authority";
+import { cn } from "../cn.js";
+import { TextAs } from "./as.js";
+/** The body layer: two axes and no more. A paragraph picks a rung and an ink; a
+ * caption is always secondary ink and picks a size. `lead` was a third rung a
+ * breakpoint away from `prose`, and its standfirst role is now the eyebrow's. */
+const pVariants = cva("", {
+    variants: {
+        /**
+         * `ui` is interface copy. `prose` is the reading rung, stated here and
+         * nowhere else — it had drifted to five copies once already. `--text-lg`
+         * resolves larger on an editorial subtree, by design.
+         */
+        variant: {
+            ui: "text-sm",
+            prose: "text-pretty text-lg leading-relaxed",
+        },
+        tone: {
+            default: "text-foreground",
+            muted: "text-muted-foreground",
+        },
+    },
+    defaultVariants: { variant: "ui", tone: "default" },
+});
+export function TypographyP({ className, variant, tone, children, ...props }) {
+    return (_jsx("p", { className: cn(pVariants({ variant, tone }), className), ...props, children: children }));
+}
+/** The UI rung in the secondary ink. */
+const MUTED = { tone: "muted" };
+export function TypographyMuted(props) {
+    return _jsx(TypographyP, { ...props, ...MUTED });
+}
+/** Reading-size body copy. `TypographyMuted` is the same ink one rung down. */
+const PROSE = { variant: "prose", tone: "muted" };
+export function TypographyProse(props) {
+    return _jsx(TypographyP, { ...props, ...PROSE });
+}
+/**
+ * A list, on the same rung axis as the paragraph beside it.
+ *
+ * The rung composes `pVariants` rather than restating one, so a list cannot
+ * drift from the copy it sits under. The old `proseClass` held that property for
+ * the prose rung alone.
+ *
+ * `variant` is here because a list is not always reading copy. A tier card or a
+ * bento cell sets its paragraphs in `ui`, and a list pinned to `prose` inside one
+ * lands two rungs above the sentence introducing it, with no prop to say so. Call
+ * sites answered that by hand-rolling `<ul className="list-disc text-sm">`, which
+ * is the shape this replaces.
+ *
+ * Tone stays pinned to `muted`: a list is body copy, secondary for the same
+ * reason the paragraph presets are, and a weight-or-ink argument at the marker
+ * is not a thing a call site should be able to start.
+ */
+const listClass = (variant, ordered) => cn("my-4 flex flex-col gap-1 pl-6 [&>li]:pl-1.5", ordered ? "list-decimal" : "list-disc", pVariants({ variant, tone: "muted" }));
+export function TypographyList({ className, children, ordered, variant, ...props }) {
+    const List = ordered ? "ol" : "ul";
+    return (_jsx(List, { className: cn(listClass(variant, ordered), className), ...props, children: children }));
+}
+/**
+ * The reading rung, pinned. The name predates the axis and keeps every call site
+ * that already had it; `Preset` stops one re-opening the rung it names.
+ */
+const PROSE_LIST = { variant: "prose" };
+export function TypographyProseList(props) {
+    return _jsx(TypographyList, { ...props, ...PROSE_LIST });
+}
+/**
+ * Meta beside content: timestamps, counts, bylines, the key in a key-value row.
+ *
+ * Always the secondary ink and never a weight — a caption is secondary because
+ * it is muted, and 500 on top would have the colour and the weight arguing.
+ * `sm` is the default because meta is separated from body by ink, not size;
+ * the smaller rungs are a deliberate step down, not the norm.
+ *
+ * Leading is pinned per size rather than left to the rung. Plenty of captions
+ * are a wrapped sentence, and the ramp's tight setting sets those cramped —
+ * descenders nearly on the caps below. `leading-normal` writes `--tw-leading`,
+ * the variable the `text-*` step reads, so 1.5 wins at every rung.
+ *
+ * `inherit` is the parenthetical inside a heading, an eyebrow or a stat. It
+ * takes the size of whatever set it and resets the weight, because the only
+ * reason to sit there is to be quieter than the thing you qualify — and every
+ * container that sets a size for you sets a weight too.
+ */
+const captionVariants = cva("text-muted-foreground", {
+    variants: {
+        size: {
+            sm: "text-sm leading-normal",
+            xs: "text-xs leading-normal",
+            "2xs": "text-2xs leading-normal",
+            inherit: "font-normal",
+        },
+    },
+    defaultVariants: { size: "sm" },
+});
+/**
+ * `as` covers the one thing that genuinely differs between call sites: whether
+ * the run is inline beside its subject or a block under it.
+ */
+export function TypographyCaption({ className, size, as, children, ...props }) {
+    return (_jsx(TextAs, { as: as, className: cn(captionVariants({ size }), className), ...props, children: children }));
+}
+/**
+ * Small print set as a block: a note under the thing it annotates, rather than
+ * an aside inline with it. Same rung and same ink as the caption — small print
+ * is small because it is muted, and dropping it a rung as well is what made
+ * both apps hand-roll their own.
+ */
+const BLOCK = { as: "p" };
+export function TypographySmall(props) {
+    return _jsx(TypographyCaption, { ...props, ...BLOCK });
+}
+/**
+ * The label role: a form label, a column header, the key a reader scans for.
+ * 500 is the only weight bump a dense surface needs below a heading.
+ *
+ * The rungs are the caption's, deliberately. A label and a caption are one pair
+ * — the key and the value, the name and the note — and a pair that cannot be set
+ * at one size is not a pair. Pinning the label to `sm` while the caption had an
+ * axis is what sent a key next to an `xs` value out to `font-medium text-xs` in
+ * a className, leaving the weight arguing with the rung it landed on.
+ *
+ * `as` is here for the same reason it is on `TypographyEyebrow`: a config panel
+ * names its sections at this size, and those names are the page's outline.
+ */
+const labelVariants = cva("font-medium text-foreground", {
+    variants: {
+        size: {
+            sm: "text-sm",
+            xs: "text-xs",
+            "2xs": "text-2xs",
+            /** Inside a heading or a chip, where the container has already set one. */
+            inherit: "",
+        },
+    },
+    defaultVariants: { size: "sm" },
+});
+export function TypographyLabel({ className, size, as, children, ...props }) {
+    return (_jsx(TextAs, { as: as, className: cn(labelVariants({ size }), className), ...props, children: children }));
+}
+/**
+ * A numeric readout. Size and colour ride in via className per use.
+ *
+ * Tabular is right in a column and wrong in a headline, so it is an axis rather
+ * than a constant. Keep `tabular` anywhere a value updates in place.
+ */
+const statVariants = cva("font-semibold tracking-tight", {
+    variants: {
+        /**
+         * Named rungs, because the ramp was reachable only by spelling a class. The
+         * three here are the ones call sites actually converged on: `display` is the
+         * figure a section is built around, `page` and `panel` ride the heading
+         * ladder so a stat and the heading beside it step together — and therefore
+         * retune together on an editorial surface, which a literal never would.
+         *
+         * `inherit` is the default and writes nothing: a stat inside a heading, a
+         * chip or a sentence takes the size that set it, and every existing call
+         * site keeps the size it passed.
+         */
+        size: {
+            inherit: "",
+            card: "text-h4",
+            panel: "text-h3",
+            page: "text-h1",
+            display: "text-6xl font-black",
+        },
+        figures: {
+            /** Even advances stop a value jittering as it refreshes. */
+            tabular: "tabular-nums",
+            /** A headline figure wants its drawn spacing: a lone 1 is not an 8. */
+            proportional: "proportional-nums",
+        },
+    },
+    defaultVariants: { size: "inherit", figures: "tabular" },
+});
+export function TypographyStat({ className, size, figures, children, ...props }) {
+    return (_jsx("span", { className: cn(statVariants({ size, figures }), className), ...props, children: children }));
+}
+/**
+ * A run of code inside a sentence: a command, a field name, a trigger.
+ *
+ * Everything is in `em`, not a rung: the chip has to sit in whatever size the
+ * sentence around it is set at, and the ramp differs per surface. The 0.9 is an
+ * optical correction — the mono face carries a taller x-height than the sans.
+ */
+export function TypographyInlineCode({ className, children, ...props }) {
+    return (_jsx("code", { className: cn("rounded-[3px] bg-foreground/[0.03] px-[0.3em] py-[0.1em] font-mono text-[0.9em] text-secondary-ink", className), ...props, children: children }));
+}
+/**
+ * A statement about the surface, not the link: `foreground` inside a paragraph,
+ * `primary` when the link is the point of the line, `secondary` for a note
+ * beneath a hero where `primary` would compete with the CTA beside it.
+ */
+const LINK_TONES = {
+    foreground: "font-medium text-foreground",
+    primary: "font-medium text-primary",
+    secondary: "text-secondary-ink",
+};
+const LINK_DECORATION = "underline decoration-dotted decoration-1 decoration-muted-foreground decoration-skip-ink-none underline-offset-2 hover:decoration-solid hover:decoration-current/70";
+const linkClass = (tone = "foreground", className) => cn(LINK_TONES[tone], LINK_DECORATION, className);
+/**
+ * The inline link.
+ *
+ * Internal and external are decided from the href, never at the call site: an
+ * href with a scheme renders a plain anchor and, if it is http(s), opens away
+ * with `rel="noopener noreferrer"`; everything else routes through the router's
+ * Link. `newTab` is the one override, for an off-site href that starts a flow
+ * the reader should stay in. Call-site props apply last, so a passed
+ * `target`/`rel` still wins.
+ *
+ * The router is `next-view-transitions`, imported rather than injected. Every
+ * project on this package is a Next app and wants the same link, and a factory
+ * bought router-agnosticism nobody used at the price of a component that could
+ * not be imported by name. One call site ended up on the unbound version that
+ * way and lost its decoration.
+ */
+export function TypographyLink({ href, children, tone = "foreground", newTab, addArrow, className, ...props }) {
+    const style = linkClass(tone, className);
+    const external = /^[a-z][a-z0-9+.-]*:/i.test(href);
+    const body = (_jsxs(_Fragment, { children: [children, addArrow && (_jsx("svg", { "aria-hidden": "true", className: "ml-1 inline size-3.5 align-middle", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: _jsx("path", { d: external ? "M7 17 17 7M7 7h10v10" : "M5 12h14M12 5l7 7-7 7" }) }))] }));
+    if (external) {
+        const away = newTab ?? href.startsWith("http");
+        return (_jsx("a", { href: href, className: style, ...(away ? { target: "_blank", rel: "noopener noreferrer" } : {}), ...props, children: body }));
+    }
+    return (_jsx(Link, { href: href, className: style, ...props, children: body }));
+}

package/llms.txt

@@ -0,0 +1,125 @@
+# @supertype.ai/foundations
+
+The shared design layer for Supertype's Next apps: typography primitives,
+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
+
+## 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. Do not
+   override 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.
+
+## Which component
+
+| you want | use | from |
+|---|---|---|
+| a page title | `TypographyH1` (add `variant="display"` on marketing pages) | root |
+| a section heading | `TypographyH2` (add `divider` for a rule under it) | root |
+| a subheading | `TypographyH3`, `TypographyH4` | root |
+| a kicker above a heading | `TypographyEyebrow` | root |
+| interface copy, 13px | `TypographyP` | root |
+| the same, secondary ink | `TypographyMuted` | root |
+| reading copy, 18px | `TypographyProse` | root |
+| a bulleted or numbered list | `TypographyList`, `TypographyProseList` | root |
+| a timestamp, count or value | `TypographyCaption` | root |
+| a form label or column header | `TypographyLabel` | root |
+| small print as a block | `TypographySmall` | root |
+| a number or metric | `TypographyStat` | root |
+| inline code | `TypographyInlineCode` | root |
+| a link | `TypographyLink` | root |
+| a highlighted phrase | `TypographyHighlight` | root |
+| 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` |
+| a long-form article page | `EssayHeader` + `EssayLayout` + `EssaySection` | `/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` |
+| an OG image | `ogCard`, `OG_SIZE` | `/og` |
+| to merge classnames | `cn` | root |
+
+## Entry points
+
+| 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/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/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/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 |
+
+## Props worth knowing
+
+- `TypographyH1`, `TypographyH3`: `variant?: "default" | "display"`.
+- `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.
+- `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`.
+- `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`.
+- `DisclosureGroup`: `type?: "multiple" | "single"`, `defaultValue` (matches the title string).
+- `TabsList`: `variant?: "default" | "line"`.
+
+## 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`.
+- `<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.
+- Adding a second `@custom-variant dark`. `tokens.css` already binds it.
+
+Run `npx foundations doctor` in the app to check the last four.
+
+## Surfaces
+
+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.
+- `.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.
+
+## Docs
+
+Read from `node_modules`, so these are absolute:
+
+- README: https://github.com/supertypeai/foundations#readme
+- Typography: https://github.com/supertypeai/foundations/blob/main/docs/typography.md
+- Blocks and MDX: https://github.com/supertypeai/foundations/blob/main/docs/blocks.md
+- The essay shell: https://github.com/supertypeai/foundations/blob/main/docs/essay.md
+- Build-time tooling: https://github.com/supertypeai/foundations/blob/main/docs/tooling.md
+- The CLI: https://github.com/supertypeai/foundations/blob/main/docs/cli.md

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@supertype.ai/foundations",
+  "version": "0.1.24",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "description": "Shared typography, prose, essay, and building blocks for Supertype projects.",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "typography",
+    "prose",
+    "essay",
+    "mdx",
+    "react",
+    "nextjs",
+    "tailwind",
+    "css",
+    "accessibility",
+    "contrast",
+    "eslint-plugin"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "bin",
+    "dist",
+    "llms.txt",
+    "src/*.css",
+    "LICENSE"
+  ],
+  "bin": {
+    "foundations": "./bin/foundations.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./blocks": {
+      "types": "./dist/blocks/index.d.ts",
+      "default": "./dist/blocks/index.js"
+    },
+    "./mdx": {
+      "types": "./dist/mdx.d.ts",
+      "default": "./dist/mdx.js"
+    },
+    "./essay": {
+      "types": "./dist/essay/index.d.ts",
+      "default": "./dist/essay/index.js"
+    },
+    "./seo": {
+      "types": "./dist/seo.d.ts",
+      "default": "./dist/seo.js"
+    },
+    "./contrast": {
+      "types": "./dist/contrast.d.ts",
+      "default": "./dist/contrast.js"
+    },
+    "./eslint": {
+      "types": "./dist/eslint.d.ts",
+      "require": "./dist/cjs/eslint.js",
+      "default": "./dist/eslint.js"
+    },
+    "./rehype": {
+      "types": "./dist/rehype.d.ts",
+      "default": "./dist/rehype.js"
+    },
+    "./tokens.css": "./src/tokens.css",
+    "./theme.css": "./src/theme.css",
+    "./type.css": "./src/type.css",
+    "./prose.css": "./src/prose.css",
+    "./shiki.css": "./src/shiki.css",
+    "./og": {
+      "types": "./dist/og.d.ts",
+      "default": "./dist/og.js"
+    }
+  },
+  "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",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "yarn build && vitest run",
+    "test:watch": "vitest",
+    "check:llms": "node scripts/check-llms.mjs",
+    "check:pins": "node scripts/pins.mjs",
+    "release": "node scripts/release.mjs",
+    "sync": "node scripts/sync.mjs",
+    "dev:sync": "node scripts/sync.mjs --watch",
+    "example": "node scripts/sync.mjs examples/site && yarn --cwd examples/site dev",
+    "example:install": "yarn --cwd examples/site install",
+    "example:build": "node scripts/sync.mjs examples/site && yarn --cwd examples/site build",
+    "example:pinned": "node scripts/pinned.mjs",
+    "example:static": "node scripts/sync.mjs examples/site && yarn --cwd examples/site build:static",
+    "prepublishOnly": "yarn build"
+  },
+  "dependencies": {
+    "@shikijs/rehype": "^2.3.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "shiki": "^2.3.2",
+    "tailwind-merge": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@base-ui/react": ">=1.4",
+    "next": ">=15",
+    "next-view-transitions": ">=0.3",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.4.1",
+    "@types/react": "^19.0.0",
+    "next": "^15.5.7",
+    "next-view-transitions": "^0.3.5",
+    "react": "^19.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "4.1.11"
+  },
+  "author": {
+    "name": "Samuel Chan",
+    "url": "https://supertype.ai/p/samuel"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/supertypeai/foundations.git"
+  },
+  "homepage": "https://github.com/supertypeai/foundations#readme",
+  "contributors": [
+    {
+      "name": "Supertype Pte. Ltd.",
+      "url": "https://supertype.ai"
+    }
+  ],
+  "bugs": {
+    "url": "https://github.com/supertypeai/foundations/issues"
+  }
+}

package/src/prose.css

@@ -0,0 +1,12 @@
+/* `code` fires for both an inline span and the <code> in a fence, and the
+   `language-*` class that tells them apart does not survive a host swapping in
+   its own code block. A child combinator knows what the component cannot. */
+
+:not(pre) > code {
+  border-radius: 0.25rem;
+  background-color: var(--muted);
+  padding: 0.125rem 0.375rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.85em;
+  color: var(--foreground);
+}