Getting started#

Pipeline#

1. 1Token filesDTCG-format JSON. The single source of truth, edited by hand. src/tokens/**/*.json
2. 2Primitive tokensRaw palette and type values, emitted as --ref-*. Never used by components. primitive/
3. 3Semantic tokensPurpose-named roles built only from primitives. This is the layer a theme changes. semantic/themes/
4. 4Component tokensPer-component tokens built from semantic tokens first, primitives only where nothing semantic fits. Shared by every theme. component/
5. 5CSS outputStyle Dictionary resolves the references: one :root block, plus a [data-theme] block per theme for the semantic tier. tokens.generated.css

213 primitives, 10 semantic tokens, 63 component tokens, 10 themes.

One value, followed through every tier. A theme swaps the primitive a semantic role points at; component tokens never change, they just inherit.

"lime": {
  "600": { "$value": "oklch(0.5246 0.1566 136.19)" }
}

"accent": {
  "default": { "$value": "{color.lime.600}" }
}

"page": {
  "accent": { "$value": "{semantic.accent.default}" }
}

:root {
  --ref-color-lime-600: oklch(0.5246 0.1566 136.19);
  --accent: var(--ref-color-lime-600);
  --page-accent: var(--accent);
}

Tiers and naming#

Each tier is built only from the one below it, which keeps the set small and the theming in one place:

1. Primitives hold raw values (--ref-color-lime-600) and are never used by components.
2. Semantic tokens name a purpose (--surface, --content-muted, --primary) and are built only from primitives. A theme sets them once for each region (the light canvas and the dark inverse region, marked with data-region="inverse") under the same names; the muted, subtle and on-color variants are derived from those bases in shared files.
3. Component tokens are named --component-part (--card-border, --nav-link-label) and are built from semantic tokens first; because they are re-resolved inside every region, a component restyles itself wherever it is placed; a primitive is used only where no semantic role fits, and the build reports each one.
4. Variants are computed; a change of role is a token. A component applies a shift of the same color on top of the token itself: an opacity with Tailwind's modifier (text-page-text/75), or the accent shifted darker on hover (accentLink in src/lib/variants.ts). A hover that swaps to a different base role is a token (--button-bg-hover, --button-text-hover, --button-ghost-text-hover, --button-outline-text-hover, --emphasis-toggle-text-hover). A theme only has to think about its base colors, and the contrast check measures the same variants.

Tokens#

Every kind of token below is documented the same way: the primitive scale you pick from, and the semantic variables that choice sets and that components read. Color is defined per theme in the token files; type sizes, line heights, weight, tracking and elevation are tokens in the pipeline above; the rest (fonts, radius, border thickness, both shapes and density) are runtime settings defined in TypeScript and written onto <html> by the dev bar. The primitives are read from those same lists and the semantic values are live, so change a setting in the dev bar and watch them move.

Color#

Every color is an oklch() value. Primitives are the raw ramps; semantic tokens are the purpose-named roles a theme points at them, once per region; component tokens, documented with each component below, are what components actually read.

Default: the Default theme · Used by: every component, through its own tokens

Fonts#

Twelve families, three each of sans-serif, serif, display and handwritten, each loaded once in layout.tsxon its own variable. Any of them can be the heading; only the sans-serif and serif ones can be the body: choosing one repoints the matching semantic role at it. The heading also has weight and tracking tokens (in the pipeline), which a font can override, for example single-weight fonts use 400 so headings don't fake a bold.

Type sizes#

Nine steps, each a primitive in the pipeline (font.size.*) and a semantic --text-* token. The Type tab multiplies the whole scale, so every text-* class follows.

• --text-xs0.75rem

  Tokens turn design decisions into data.

• --text-sm0.875rem

  Tokens turn design decisions into data.

• --text-base1rem

  Tokens turn design decisions into data.

• --text-lg1.125rem

  Tokens turn design decisions into data.

• --text-xl1.25rem

  Tokens turn design decisions into data.

• --text-2xl1.5rem

  Tokens turn design decisions into data.

• --text-3xl1.875rem

  Tokens turn design decisions into data.

• --text-4xl2.25rem

  Tokens turn design decisions into data.

• --text-5xl3rem

  Tokens turn design decisions into data.

Line height#

Each step has a paired line height (a primitive, font.line-height.*), and the named leading-* values sit alongside. One multiplier scales them all.

Border radius#

Picking a size treats it as the new lgand scales the rest by Tailwind's own ratios, so every rounded-* utility responds with no component changes.

Button shape#

Square, rounded or pill. Rounded follows the radius scale (lg, and a smaller step for small sizes). The Button's default shape reads these.

Accent shape#

The shape of small accents: avatars, timeline markers, the eyebrow dot, the dev bar, and any Button with shape="accent". Components use rounded-(--radius-accent), so a plain rounded-full stays a real circle.

Elevation#

Five shadow tiers, each a primitive in the pipeline (elevation.*). --elevation is the semantic token pointing at the active one, and components read it with shadow-elevation, so the dialogs and the dev bar follow the setting with no component changes.

Border thickness#

Border widths compile to literal pixels, so thickness is its own variable that components read with border-(length:--border-width). --border-on is 1 or 0 so layout that only exists to make room for a line can collapse with it.

Density#

Two multipliers, horizontal and vertical, on Tailwind's spacing unit. spacing.css re-declares every spacing utility against them, so no component changes; at 1 on both axes the output is identical. Wrap anything that should ignore the setting in .spacing-fixed (the dev bar and /resume do).

Components#

Every component on the site, grouped as foundations, primitives, patterns, sections and tools. Each has a live preview, the source files that implement it, the tokens it owns, and any tokens it borrows from other components (found by scanning its source at build time), which are candidates for tokens of its own. Component tokens are built from semantic tokens first, and from primitives only where no semantic role fits (today: 2). Components apply their own hover, focus and transparency variants on top, so those are not listed. These files are the same for every theme; switch themes and type settings in the dev bar to see each component respond.

Beyond the tokens#

A token set is the start of a system, not the whole of one. This is what surrounds it here, and what it leaves out.

Testing#

The theming contract is tested where it can break. Expected values are never copied into a test: they are read from the generated manifest (src/lib/tokens.generated.json), so a test cannot drift from the tokens. Colors are compared by painting both on a 1x1 canvas, because a browser rounds the serialization of a relative-color formula. Run them with pnpm test:unit and pnpm test:e2e.

Left out on purpose#