Aster UI / Guides

Themes

Every element styles itself only through --aster- custom properties: the token contract. A theme (an identity) is one complete set of values for those tokens, and nothing else: no selectors for elements, no overrides of their rules. Two ship: Lamplight (warm, lit, serif figures) and Harbour (cool, rounded, calm), which was written from this guide alone. The guide is enough to write another.

A theme file

@layer aster.identity {
  :root[data-identity="harbour"] {
    --aster-font-ui: "Inter", system-ui, sans-serif;
    /* … every token in the tables below … */
    color-scheme: light;
  }

  :root[data-identity="harbour"][data-scheme="dark"] {
    /* only the tokens that change in the dark */
    color-scheme: dark;
  }
}

• The light rule defines every token. The checker lists any that are missing.
• The dark rule overrides only what changes. Colours mostly; type, shape and motion usually stay. Dark is its own design, not an inversion: surfaces get lighter as they rise (page darkest, surface lighter), and the accent gets lighter to keep its contrast. In the tables below, an empty dark cell means the light value applies.
• var() resolves where it's used. A token defined as var(--aster-accent), or built on one with oklch(from var(…) …), follows that token into the dark scheme without being restated. Lamplight restates e1 to e3 in the dark only because their shadow strengths change.
• Put it in the aster.identity layer. The layers run aster.identity, aster.base, aster.elements, app, so a theme never outranks an element's own rules and an app's styles outrank both.
• Any CSS colour syntax works, and a token can derive from another: --aster-focus: oklch(from var(--aster-accent) l c h / .7). The checker evaluates hex, rgb(), oklch() (relative too), color-mix(in srgb, …) and var(); anything else it reports as unchecked, not wrong.
• Fonts are the page's job. A theme names typefaces and the page loads them, so end every stack with a generic family (system-ui, sans-serif). Weights between the named ones (450) suit variable fonts; system fonts round them. Line heights from 1.35 to 1.6 fit the layouts, and body sizes from 12px to 15px fit the controls, whose heights come from density.
• Shadows are tokens too. e1 to e3 are whole box-shadow values, usually starting with var(--aster-ring) (and var(--aster-highlight) in a lit theme): a lit theme layers soft shadows tinted from shadow (Lamplight), a flat one uses the hairline ring alone and keeps a real shadow only for floating things. Avatars also use highlight on its own, so a flat theme sets it to 0 0 #0000.
• Identity colours (people's and projects' dots and avatars) take their hue from data and identity-l and identity-c from the theme. Keep them mid-light and moderately saturated (about 58–70% and .1) so every hue reads against surface; mark-ring outlines them for the palest hues. Dark usually raises the lightness.
• text-3 may equal text-2. It's the quietest text (column headers, figure labels, timestamps), but still text people read, so it needs 4.5:1 like the others; a theme needn't have a third tier.
• The lamp is Lamplight's. Another theme sets glow to 0, lamp-bulb to transparent, and backdrop and frame to plain page and surface.

Where a theme lives

A theme is one CSS file the page links. In this repository the themes live in packages/elements/src/styles/; bun run site copies them to lib/themes/ beside aster-ui.css, and the demo imports them in apps/aster/src/styles.css and lists them in apps/aster/src/themes.ts for its theme menu.

Loading a theme

Link the theme before aster-ui.css, then name it on the root:

<link rel="stylesheet" href="lib/themes/harbour.css">
<link rel="stylesheet" href="lib/aster-ui.css">
<html data-identity="harbour">

data-scheme="dark" on the root picks the dark scheme, and data-density (compact, standard, comfortable) the density. Density belongs to the person, not the theme: its tokens (--aster-ctl, --aster-ctl-tight, --aster-pad-y, --aster-row-y, --aster-pad, --aster-gap) come from aster-ui.css, and a theme doesn't set them.

Lamplight is the default identity: its rule is plain :root, so a page with no data-identity gets it. A theme that should be the default can do the same.

Checking a theme

bun run theme-check path/to/harbour.css   # in this repository
bunx aster-theme-check path/to/harbour.css   # where @getaster/elements is installed

For each identity in the file, in both schemes, it checks:

1. Every token is defined, and none is unknown (a misspelt token would silently fall back to another theme's value).
2. Contrast, by WCAG 2: 4.5:1 for text, 3:1 for marks, focus and indicators. Translucent colours are composited over what they sit on.

It exits with 1 if anything fails, so it can run in CI. Only these colour pairs are measured; the other tokens (shadows, scrim, press, mark-ring, toast-mark, type, shape and motion) are checked for presence and spelling. The demo's browser tests run axe over its screens in each theme, which measures the text as it's actually drawn.

Starting from a palette

1. Copy the theme closest in spirit: Harbour for a cool, rounded look, Lamplight for a lit, layered one.
2. Set the surfaces from your neutrals: page the darkest in light, surface the lightest, sunk between (inside fields), pane for the sidebar.
3. Set text, text-2 and text-3 from your darkest neutrals, and check.
4. Choose one accent that acts (buttons, links, selection). A second brand colour can be the indicator, which only marks where to look.
5. Run the checker, adjust lightness until it passes, then do the dark rule the same way.
6. Look at every screen in both schemes; the checker can't judge taste.

The tokens

Type

Surfaces

Text

Edges

Accent

Status

Identity colours

Elevation

Shape

Motion

Toasts

The lamp