Design tokens

Every design decision in Apogee is a CSS variable. Components read tokens; they never own a colour or a size. Theming is an override in one place, not a find-and-replace across components.

Colour: hues × roles

Colour has two axes.

Hues name intent: primary (brand), neutral, critical, positive, warning.

Roles name what a colour is for. Every hue gets the same seven:

neutral adds a few more: --foreground-neutral-faded (secondary text), --background-page and -page-faded, --background-elevation-base, -raised, -overlay (surfaces by height), --background-disabled, --foreground-disabled, --border-disabled, and --background-inverted with --on-inverted (tooltips, badges on media).

One short name, the right role per utility

Tailwind’s namespaced theme keys map each role to the utility that needs it, so you type one hue name and get the correct role:

<button class="bg-primary text-on-primary hover:bg-primary-highlighted">Save</button>
<a class="text-primary">A link</a>
<div class="border border-primary-faded bg-primary-faded text-primary">A tinted callout</div>

Opacity modifiers like bg-primary/10 work on the alias forms; prefer the generated -faded roles, which were tuned for contrast.

Changing the brand

The colours are generated. Edit the five inputs in scripts/hues.mjs (a Tailwind colour name such as 'blue-700', a grey family such as 'slate', or an OKLCH object; see Color) and run:

npm run build:tokens      # rewrites the generated blocks in registry/tokens/theme.css
npm run check:contrast    # fails if any text or ring pair drops below AA

From a project that copied Apogee in, point both scripts at your files:

node node_modules/@ava-ui/apogee/scripts/build-tokens.mjs src/styles/apogee.css ./hues.mjs
node node_modules/@ava-ui/apogee/scripts/check-contrast.mjs src/styles/apogee.css

(hues.mjs is a copy of the package’s file with your values; apogee.css is the tokens file init wrote.) Every build records its inputs on one line at the end of the light block, /* hues {…} */. Leave out ./hues.mjs and the script regenerates from that line, so you can edit the values there instead. Never edit the lines between the @generated markers by hand; the next build overwrites them. The generator derives the dark theme, the faded tints, the hover steps and the on-colours, and the contrast gate measures every pair it produces, in both themes, with alpha composited over the page.

To override a single token at runtime (a client’s brand on one site), set the variable in your own CSS after the theme import and re-run the gate.

Dark mode

[data-theme="dark"] on any ancestor flips the generated block. Section’s theme prop uses it to recolour a band of the page. Surfaces step up in lightness with elevation in dark mode; shadows become a faint top highlight. See Dark mode.

Skins

A skin is an optional file that redefines three inert variables (--shadow-control, --highlight-control, --shadow-field) under [data-skin]. See Skins.

Elevation

Utilities: shadow-outline, shadow-raised, shadow-overlay.

Radius

Motion

See Motion for the wiring and the reduced-motion rule.

Responsive props

A few layout props accept a value per breakpoint instead of a single value: direction, gap, align, justify and wrap on Box and Stack; cols and gap on Grid; colSpan and rowSpan on GridItem; size on Text. Write { base: 'column', md: 'row' }; keys are Tailwind’s breakpoints (sm 640px, md 768px, lg 1024px, xl 1280px), mobile first.

Every other prop takes one value; use class with Tailwind’s md: prefixes for the rest. The classes behind responsive props are generated into utils/responsive-tables.ts so Tailwind sees each one.

Type and spacing

Three font stacks: --font-sans (body and UI), --font-mono (code), --font-serif (quotations; the device’s default serif). Override any of them in your own @theme.

Headings use fluid clamp() tokens (--text-display, --text-h1 … --text-h6). Page rhythm uses --spacing-gutter and --spacing-section-*. Component internals keep Tailwind’s fixed numeric scale. See Typography and Spacing.

Reference

Every variable the tokens file defines, read from the file at build time.