foundations

KO | EN

gitlite — search

#redis #machine-learning #developer-tools #awesome-list #golang #nextjs #python #privacy #docker #git

(★ 9)

Elegant typography, prose, essay, and building blocks. Built for Next.JS + Shadcn + Tailwind.

파일 탐색기

ZIP 다운로드

- - ci.yml
  - docs.yml
- foundations.mjs
- - accordion.d.ts
  - accordion.js
  - anchor.d.ts
  - anchor.js
  - badge.d.ts
  - badge.js
  - bulletin.d.ts
  - bulletin.js
  - button.d.ts
  - button.js
  - callout.d.ts
  - callout.js
  - card.d.ts
  - card.js
  - colophon.d.ts
  - colophon.js
  - disclosure.d.ts
  - disclosure.js
  - focus.d.ts
  - focus.js
  - index.d.ts
  - index.js
  - interactive-accordion.d.ts
  - interactive-accordion.js
  - render-as.d.ts
  - render-as.js
  - segment.d.ts
  - segment.js
  - steps.d.ts
  - steps.js
  - tabs.d.ts
  - tabs.js
  - trim-labels.d.ts
  - trim-labels.js
- - eslint.js
  - package.json
- - contents.d.ts
  - contents.js
  - essay.d.ts
  - essay.js
  - index.d.ts
  - index.js
  - layout.d.ts
  - layout.js
  - rail.d.ts
  - rail.js
  - reading.d.ts
  - reading.js
  - scroll.d.ts
  - scroll.js
  - toc.d.ts
  - toc.js
- - align.d.ts
  - align.js
  - as.d.ts
  - as.js
  - header.d.ts
  - header.js
  - highlight.d.ts
  - highlight.js
  - index.d.ts
  - index.js
  - paragraph.d.ts
  - paragraph.js
  - trim.d.ts
  - trim.js
- cn.d.ts
- cn.js
- contrast.d.ts
- contrast.js
- eslint.d.ts
- eslint.js
- href.d.ts
- href.js
- index.d.ts
- index.js
- injection.d.ts
- injection.js
- mdx.d.ts
- mdx.js
- og.d.ts
- og.js
- optical.d.ts
- optical.js
- rehype.d.ts
- rehype.js
- seo.d.ts
- seo.js
- tone.d.ts
- tone.js
- blocks.md
- cli.md
- contributing.md
- essay.md
- tooling.md
- typography.md
- - .gitignore
  - next.config.ts
  - package.json
  - postcss.config.mjs
  - README.md
  - tsconfig.json
  - yarn.lock
- check-candidates.mjs
- check-llms.mjs
- cjs-marker.mjs
- consumers.mjs
- pinned.mjs
- pins.mjs
- release.mjs
- sync.mjs
- - accordion.tsx
  - anchor.tsx
  - badge.tsx
  - bulletin.tsx
  - button.tsx
  - callout.tsx
  - card.tsx
  - colophon.tsx
  - disclosure.tsx
  - focus.ts
  - index.ts
  - interactive-accordion.tsx
  - render-as.ts
  - segment.ts
  - steps.tsx
  - tabs.tsx
  - trim-labels.tsx
- - contents.tsx
  - essay.tsx
  - index.ts
  - layout.tsx
  - rail.tsx
  - reading.tsx
  - scroll.ts
  - toc.ts
- - align.ts
  - as.tsx
  - header.tsx
  - highlight.tsx
  - index.tsx
  - paragraph.tsx
- cn.ts
- contrast.ts
- eslint.ts
- href.ts
- index.css
- index.ts
- mdx.tsx
- og.tsx
- prose.css
- rehype.ts
- seo.ts
- shiki.css
- theme.css
- tokens.css
- tone.ts
- type.css
- - app.ts
  - next-view-transitions.ts
- - presets.tsx
- cli.test.ts
- composition.test.ts
- contrast.test.ts
- eslint-rules.test.ts
- essay-toc.test.ts
- heading-face.test.ts
- heading-ink.test.tsx
- href.test.tsx
- leading-ownership.test.tsx
- seo.test.ts
- slot-nesting.test.tsx
- tabs-attributes.test.tsx
- tokens-live.test.ts
- types.test.ts
.gitignore
LICENSE
llms.txt
package.json
README.md
tsconfig.cjs.json
tsconfig.json
tsconfig.typetest.json
vitest.config.ts
yarn.lock

# CDN으로 사용하기

jsDelivr

jsDelivr는 공개 GitHub 리포지토리를 별도 설정 없이 CDN으로 즉시 서빙합니다. 버전과 파일을 고르면 웹페이지에 바로 붙일 수 있는 링크와 예시 코드가 만들어집니다.

버전

파일

링크

예시

# 프로젝트 배지

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[The foundations philosophy](https://supertypeai.github.io/foundations/philosophy/) explains the reasoning in more detail, but the short version is simple: this is a reusable design system for typography primitives, content blocks, the long-form essay shell, token and theme CSS, and the build-time tooling that keeps the baseline consistent. That includes SEO, OG cards, lint rules, and contrast checks.

It is used in Supertype projects like [Viably work operating system](https://viably.app) and [supertype.ai](https://supertype.ai), and it is MIT-licensed for any Next.js 15+ app built on Tailwind and Shadcn.

```sh
yarn add @supertype.ai/foundations
```

**Start here:** [Install](#install), then [Your first page](#your-first-page).

**Reference:** [Typography](docs/typography.md) · [Blocks](docs/blocks.md) ·
[The essay shell](docs/essay.md) · [Build-time tooling](docs/tooling.md) ·
[The CLI](docs/cli.md)

**Working on the package itself:** [Contributing](docs/contributing.md), for
local iteration against a consumer and for releasing.

Like the project? ⭐ Star it on [GitHub](https://github.com/supertypeai/foundations)

## See it running

Check out: [the documentation site](https://supertypeai.github.io/foundations/), or alternatively run the example site locally:

```sh
yarn example:install   # once, to install Next, the peers and the package
yarn example           # then open http://localhost:3000
```

[`examples/site`](examples/site) renders every component with the code next to it, and includes whole-page [recipes](examples/site/app/_recipes) you can copy into your project. It also includes the `dark` and `.editorial` switches.

## Initialization and Diagnostics

This package includes a CLI that writes the CSS for you and checks the rest:

```sh
npx @supertype.ai/foundations init      # edits your CSS entry, prints the rest
npx @supertype.ai/foundations doctor    # checks this app against everything below
```

`init` edits one file: the CSS entry that imports Tailwind. It adds any missing
imports and reorders the existing ones if needed. Run it with `--dry-run` first
to preview the patch. It also prints the font bindings and the `llms.txt` snippet
your coding agent should read.

The steps performed by `init` are listed below. See [the CLI](docs/cli.md) for
the full list of checks and details.

### 1. Add the package

```sh
yarn add @supertype.ai/foundations
# or: npm install @supertype.ai/foundations
```

Peers are **Tailwind 4+**, React 19+, Next 15+, `next-view-transitions` 0.3+ and
`@base-ui/react` 1.4+.

**Tailwind v4 is required, not preferred.** `tokens.css` declares
`@custom-variant` and `@theme inline`, and the `@source` line below is v4-only
syntax; on v3 they are parse errors. If you are still on v3, run
[`npx @tailwindcss/upgrade`](https://tailwindcss.com/docs/upgrade-guide) first —
`foundations init` will tell you so rather than writing a block your build
cannot parse.

<details>
<summary>Installing from a git tag instead</summary>

Every release is tagged and published, so a commit can be installed directly
when you want to try an unreleased fix. Pin a tag rather than `#main`: an
untagged git dependency resolves to a different commit on a fresh install.

```jsonc
// package.json
"@supertype.ai/foundations": "https://github.com/supertypeai/foundations.git#v0.2.3"
```

</details>

### 2. Import the CSS

```css
/* app/globals.css */
@import "tailwindcss";
@import "@supertype.ai/foundations";
```

That one line carries `tokens.css`, `theme.css`, `type.css` and `prose.css` in
the order the cascade needs, and registers the package&rsquo;s own `@source` so
Tailwind scans the components it ships. You do not need to work out a path or
keep an order: Tailwind v4 resolves `@source` relative to the file that declares
it, so the package points at its own `dist/`, correctly, wherever it happens to
be installed.

Add `@import "@supertype.ai/foundations/shiki.css";` after it only if you render
code fences.

<details>
<summary>Importing the parts separately</summary>

The granular entry points are still exported and still supported, for the app
that paints every colour role itself and wants `tokens.css` without `theme.css`.
Taking them means owning the order and the scan path yourself:

```css
/* app/globals.css */
@import "tailwindcss";
@import "@supertype.ai/foundations/tokens.css"; /* structural tokens + dark variant */
@import "@supertype.ai/foundations/theme.css"; /* the house palette */
@import "@supertype.ai/foundations/type.css"; /* the type ramp + font roles */
@import "@supertype.ai/foundations/prose.css"; /* inline-code rule */

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

**The `@source` line is required in this form.** Tailwind does not scan
`node_modules` by default, so without it the package&rsquo;s classes get purged
and the components render without styles. The path is relative to your CSS file,
so it changes with your layout — and in a workspace, where the package hoists to
the repo root, `../node_modules` is not where it lives.

**`theme.css` is required.** `tokens.css` names the colour roles, and
`theme.css` gives them values. Without it, the colour utilities cannot be
resolved, so the page renders unpainted without an obvious error. It also
carries `--secondary-ink`, `--subtle-foreground`, the four earth tones used
for marker highlights, and the `accordion-down` and `accordion-up` keyframes.
Skip it only if you declare every role yourself; `foundations doctor` fails if
neither path is true.

</details>

### 3. Bind the fonts

The package cannot load the typefaces for you. `next/font` runs in your app and
generates hashed variable names at build time, so each app loads the three fonts
and binds them to the roles `type.css` expects:

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

<html className={`${sans.variable} ${mono.variable} ${serif.variable} font-sans`}>
```

**Bind with `.variable`, never `.className`.** A className sets `font-family`
on the element itself and leaves the roles unresolved, which causes a mismatch
where the page renders one typeface while the `font-sans` and `font-heading`
utilities render another.

### 4. Check the wiring

```sh
npx foundations doctor
```

It reads your CSS entry, your root layout and the installed tree, then reports
on import order, the `@source` path, the font bindings and the peer versions. It
exits non-zero on a real problem, so it works as a CI step too. Every check and
what it catches is listed in [the CLI](docs/cli.md).

---

## Your first page

```tsx
import {
  TypographyH1,
  TypographyH2,
  TypographyProse,
  TypographyEyebrow,
  TypographyLink,
  TypographyCaption,
} from "@supertype.ai/foundations";
import { Card, Cards, Callout } from "@supertype.ai/foundations/blocks";

export default function Page() {
  return (
    <main className="mx-auto max-w-3xl px-6 py-16">
      <TypographyEyebrow>Guides</TypographyEyebrow>
      <TypographyH1 variant="display" className="mt-2 text-balance">
        Getting data out of Postgres
      </TypographyH1>
      <TypographyProse className="mt-4">
        Three approaches, ordered by how much of your schema they need to know.
      </TypographyProse>

<TypographyH2 divider className="mt-12">
        Approaches
      </TypographyH2>

<Callout tone="warn" title="Before you start" className="mt-8">
        Replication slots hold WAL until they are consumed. An abandoned slot
        fills the disk — see{" "}
        <TypographyLink href="/ops/slots" addArrow>
          slot hygiene
        </TypographyLink>
        .
      </Callout>

<TypographyCaption as="p" className="mt-8">
        Last reviewed March 2026
      </TypographyCaption>
    </main>
  );
}
```

Two rules cover most of the API:

- **Do not write type styles by hand.** A paragraph carrying
  `text-sm text-muted-foreground` is `<TypographyMuted>`. Using the primitives
  keeps a size and a colour from drifting apart across a few hundred call sites.
- **Retune with CSS variables, not classes.** The package owns its own
  classnames. Change a `--text-*`, `--heading-weight`, or a colour specification in `theme.css` to retune the whole package. Read [Tokens and theming](#tokens-and-theming) for full instructions.

---

## The example site

`yarn example` (above) builds the package, syncs it in and starts the dev
server. `yarn example:build` is what CI would run.

It installs the package from a git tag rather than the registry and updates it
with `yarn sync`.

`/recipes` holds whole pages rather than single components: a marketing hero, a
metrics panel, pricing tiers, a docs page, an article index, and examples of MDX-rendered pages. Each one lives in
[`app/_recipes/`](examples/site/app/_recipes) as a complete file that imports
only from this package, so you can paste it into your app and it compiles.

---

## For coding agents

The package includes an `llms.txt` with the public API, the rules, and the
mistakes that do not produce an error. Point your agent at it once and it stops
writing `text-sm text-muted-foreground` where a primitive already exists:

```md

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

`yarn build` fails if an export is missing from it, so it cannot fall behind the
package.

---

## Entry points

| import                                                                | contains                                                                          | docs                                         |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------- |
| `@supertype.ai/foundations`                                           | all typography primitives, `cn`                                                   | [Typography](docs/typography.md)             |
| `@supertype.ai/foundations/blocks`                                    | `Button`, `Badge`, `Card`, `Callout`, `Steps`, `TabGroup`, `Accordion`, `SEGMENT` | [Blocks](docs/blocks.md)                     |
| `@supertype.ai/foundations/mdx`                                       | `proseMdxComponents` — the MDX element map                                        | [In MDX](docs/blocks.md#in-mdx)              |
| `@supertype.ai/foundations/essay`                                     | the long-form shell, TOC, reading rail, post meta                                 | [Essay](docs/essay.md)                       |
| `@supertype.ai/foundations/seo`                                       | `createSeo(...)` — metadata + JSON-LD                                             | [Tooling](docs/tooling.md#seo-and-og-images) |
| `@supertype.ai/foundations/og`                                        | `ogCard`, `OG_SIZE` — an element for `next/og`                                    | [Tooling](docs/tooling.md#seo-and-og-images) |
| `@supertype.ai/foundations/eslint`                                    | the design rules as ESLint selectors                                              | [Tooling](docs/tooling.md#lint-rules)        |
| `@supertype.ai/foundations/rehype`                                    | `rehypeProseCode` — **build-time only**                                           | [In MDX](docs/blocks.md#in-mdx)              |
| `@supertype.ai/foundations/contrast`                                  | token resolution + legibility checks, build-time only                             | [Tooling](docs/tooling.md#contrast-checks)   |
| `./tokens.css` `./theme.css` `./type.css` `./prose.css` `./shiki.css` | the style layer                                                                   | [Tokens and theming](#tokens-and-theming)    |
| `foundations` (bin)                                                   | `init` and `doctor`                                                               | [The CLI](docs/cli.md)                       |

---

## Tokens and theming

`tokens.css` names the structural roles and nothing else: `--background`,
`--foreground`, `--card`, `--muted`, `--primary`, `--border` and `--ring`, plus
the status set. They are named for meaning rather than hue, so a project that
renders `success` in blue still reads correctly. It holds no values, so there is
only ever one palette in play.

Each status hue ships twice, on the same rule as the categorical tints:
`--success`, `--warn` and `--info` are **fills**, held to 3:1 against the page
and a card; `--success-ink`,
`--warn-ink` and `--info-ink` are the same hues as **text**, held to 4.5:1.
`--danger` ships as an ink only. `--destructive` keeps shadcn's shape, where
`--destructive-foreground` is the label printed on the fill — that is what
`-foreground` means throughout, and `-ink` means the hue used as words.
`checkSignals` in `@supertype.ai/foundations/contrast` measures all of them and fails if any are below the threshold.

`tokens.css` also binds the `dark:` variant to the `.dark` class. Do not skip
that import: Tailwind v4 otherwise follows the OS setting and quietly ignores
your toggle.

`theme.css` gives those roles the latte and espresso palette, and adds the
editorial inks (`--secondary-ink`, `--subtle-foreground`, and the ochre,
terracotta, sage and fig pairs) along with the elevation shadows.

**No brand colours in the package.** Structural tokens only, with brand colours
left to the app. To repaint, override the raw variables after the imports rather
than patching the utilities:

```css
:root {
  --primary: hsl(24 60% 42%);
}
.dark {
  --primary: hsl(24 70% 62%);
}
```

### `.editorial`

`type.css` names three font roles (`--font-sans`, `--font-mono` and
`--font-heading`) and the weight that goes with the heading face. `.editorial`
gives the heading role to the serif and drops the weight to 400.

```tsx
<div className="editorial">…</div>   {/* or on <html> for an editorial site */}
```

Heading sizes are a _ratio_ to the body text under them, and the two
surfaces set body at different sizes: 13px in the product, 18px on `.editorial`. Scope the class to whichever surfaces should be editorial, whether that is a marketing and docs section or the whole site.

---

## Design rules

1. **The package owns its final classnames.** Retune with CSS custom properties
   (the `--text-*`, `--heading-weight`, the colour tokens) rather than by
   patching classes. A property the package declares is read by the package; if a
   knob turns nothing, `test/tokens-live.test.ts` fails on it; that is worse
   than no knob at all.
2. **No variant props on the MDX map.** Elements that MDX renders automatically
   take no options. No call site exists to make the choice. Components you invoke
   by hand can have variants.
3. **Use the platform first, and a library only where it falls short.**
   `Disclosure` is a `<details>`/`<summary>` pair: no JavaScript, correct before
   hydration, and available to an MDX author. `Accordion` and `Tabs` use Base UI,
   since animation and managed selection are beyond what the platform gives you.
4. **No brand colours.** Structural tokens only, with brand colours left to the
   app.
5. **Put structure in CSS rather than the component map.** A host framework can
   substitute its own element and strip the classes off it, but it cannot strip a
   child combinator. Both the Shiki theming and the inline-code rule rely on
   this.

---

## Upgrading to 0.2

Two entry points lost exports. Both had one function doing the work and several
more standing beside it, and the extras are what a config got wrong.

**`/eslint` is one function.** `designRules` assembles every rule, so replace
`designConfig({ accents, weights })` with your own flat-config entry around it:

```js
{
  files: ["app/**/*.tsx", "components/**/*.tsx"],
  rules: {
    "no-restricted-syntax": ["error", ...designRules({ accents: "the brand tints" })],
  },
}
```

`colourRules`, `typographyRules`, `linkRules`, `themeOverrideRules`,
`surfaceAsInkRules` and `renamedTokenRules` are internal now. Spreading a subset
was how a config came to be running four of the six sets, unaware of the other
two, so the whole set is what the package hands out. `typography: false` still
drops the type rules for a surface that sets its own ramp.

**`/rehype` is `rehypeProseCode` and `PROSE_THEMES`.** `PROSE_LANGS` and
`proseCodeOptions` are what that plugin is built from rather than things to pass.

New in the same release: `CAP_TRIM` and `ON_FIRST_LINE` for lining a mark up with
the words beside it. `Button` and `TabsTrigger` apply the trim to their own labels,
so a control lines up without the call site knowing the rule. The third case needs
no export: a mark set inside a run of words takes `align-middle`, which centres it
on the baseline plus half an x-height at whatever size the run is set in. Reach for
one of the three rather than a top margin, which fits one rung and misses the rest.

---

## In production

Sites running the package:

- [supertype.ai](https://supertype.ai) — Supertype, a regional-leading analytics engineering and data science consulting firm.
- [viably.app](https://viably.app) — Viably, an observability-first business operating system and CRM for automation-obsessed teams.

## ![](https://assets.viably.app/app_assets/screen/usage_dark.webp)

## License

Published to npm as
[`@supertype.ai/foundations`](https://www.npmjs.com/package/@supertype.ai/foundations),
and installable from this repository by tag. The MIT grant covers using,
modifying and redistributing it either way.

foundations

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

# 프로젝트 배지

Was this content helpful?

Recent Feedback

foundations

오너의 다른 레포

파일 탐색기

# CDN으로 사용하기

# 프로젝트 배지

Was this content helpful?

Recent Feedback

Download README