Design system

The design language ranui is built from, and the complete catalog of the tokens that express it: every global --ran-* custom property the library declares, with its value in both themes. Components read these instead of hard-coding values, so overriding one token restyles everything that consumes it.

Four pages answer four different questions, and they are deliberately separate:

Use when you need the name or the value of a token (a colour role, a spacing step, an icon size, a shadow tier, an easing curve) or want to understand why the scales are shaped the way they are.

The language: Geist

ranui's tokens are based on Geist, Vercel's open-source design system. Every colour scale is a ladder of fixed jobs, one per step, not a set of shades to pick from: step 200 is not "a slightly darker gray", it is "the hover background". Once a step's job is fixed, choosing a colour for an interaction state is a lookup, not a judgement call.

ranui adopts that ladder as its --ran-* scales, layers semantic tokens on top, and ships Geist Sans / Geist Mono as the default typefaces.

Two layers

Layer 1: base palette. The raw scales below. Rarely consumed directly.

Layer 2: semantic tokens. --ran-color-* and friends, mapped onto layer 1. Consume this layer. Dark mode redefines only layer 1, so every semantic token flips through var() with no per-component dark overrides anywhere in the library.

--ran-gray-1000        →  #171717 (light)  /  #ededed (dark)     ← layer 1, flips
--ran-color-text       →  var(--ran-gray-1000)                    ← layer 2, follows
--ran-btn-color        →  var(--ran-color-text, …)                ← component token

That chain is the whole architecture: change a base step and it propagates everywhere; change a semantic token and it changes one role; change a component token and it changes one element.

Colour

The ladder

Every hue scale runs 100 → 1000, and each step has one fixed job:

Backgrounds

Gray — --ran-gray-100..1000

The scale behind text, borders and surfaces.

Gray alpha — --ran-gray-alpha-100..1000

Translucent, so it layers over any surface: the right choice for a scrim, a hover wash or a divider that must sit on unknown content.

Blue — --ran-blue-100..1000

Reserved for links and the focus ring.

Red — --ran-red-100..1000

Danger and errors.

Amber — --ran-amber-100..1000

Warnings.

Green — --ran-green-100..1000

Success.

Semantic colour tokens

The layer components actually read. Everything here resolves through the scales above, so it flips with the theme on its own.

--ran-color-primary-hover / -active are the two literals in the semantic layer: they step toward the page background rather than along a scale, so dark mode redefines them directly.

What each accent means

• Primary is monochrome: black-on-white in light, white-on-black in dark (the Geist brand tone, <r-button type="primary">). Text and icons on it use --ran-color-primary-text, which flips with it. There is no separate "contrast" token: primary is the highest-contrast action.
• Blue is reserved for links (--ran-color-link) and the focus ring. It is not an alternative primary.
• Green = success · amber = warning · red = danger. One meaning each.

There is no --ran-color-error; the token is --ran-color-danger. A var() naming a property that was never declared resolves to nothing and the entire declaration is dropped silently, which is why the wrong name is worth checking against this table rather than guessing.

Spacing

Gaps between things: padding, margin, gap. A 4px base unit with nine values, no more:

The number is the multiple of 4px, so the scale skips: there is no --ran-space-5. That is the point: a limited set is what produces a page's rhythm.

Sizing

An element's own dimensions: icon sizes, control heights, small square or rectangular controls.

This is a separate scale from spacing on purpose, and mixing them is a machine-checked error (sizing-scale). The two have different ranges and progressions (a 4px-doubling spacing scale produces awkward values for icon and control sizes), and a consumer must be able to retune one without disturbing the other: an icon getting bigger should not also widen every gap that happens to share its pixel value. Where a step coincides numerically with a spacing step (--ran-size-4 and --ran-space-6 are both 24px) that is coincidence, not aliasing.

A genuinely one-off dimension that no other component shares (a menu's min-width, say) stays a plain component token with its own literal fallback rather than being forced onto a step.

Typography

Type is organised by role, and the role fixes font, size, weight and line-height together:

Two tokens exist only to make a role land correctly:

Geist caps weight at 600 (semibold). Emphasis comes from size and spacing, not from a heavier face. There is no --ran-text-copy-3: the 12px step is --ran-text-label-3.

Fonts

ranui self-hosts both faces (variable weight 100–900, SIL OFL 1.1), so one import loads them with no CDN dependency:

import 'ranui/fonts'; // bundlers

<link rel="stylesheet" href="…/ranui/dist/fonts/fonts.css" />

Without it the tokens fall back to system font stacks; everything still works, just without the Geist faces.

Radius

Elevation

Shadow is a role, not decoration. Pick the tier by what the element is. Dark mode replaces all three, because a shadow tuned for a white page disappears on a black one.

Borderless overlays rely on the shadow alone for separation, so the overlay tiers carry real weight; an overlay falling back to the raised tier looks flat and pinned to the page.

Stacking

Floating overlays portal to <body>, so they need an explicit tier:

The ladder starts at 1000 so it clears ordinary page chrome (nav bars and backdrops normally live in the tens). Override a tier on :root, or per component (--ran-dropdown-host-z-index, --ran-modal-root-z-index, --ran-message-z-index), never with !important.

Motion

The spring family is distilled from tuned SwiftUI springs (response/damping reduced to a single-overshoot bézier).

Pair these with motion properties only: transform, opacity, box geometry. Palette properties (background-color, color, border-color, box-shadow, fill, stroke) deliberately carry no default transition, because CSS cannot tell an interaction apart from a theme flip: any fade you add to a colour also fires when light↔dark switches. Every component still exposes a --ran-*-transition hook if you want to opt back in.

Focus

The ring is two layers: a background-coloured inner ring and a blue outer one, so it stays visible on any surface, and it stays blue rather than following the now-monochrome primary.

--ran-focus-ring-inverse-color is deliberately not redefined in dark mode: it exists for a component whose own surface is fixed-dark regardless of page theme (r-player's control bar, over arbitrary video), and that surface does not change when the page does.

Skin primitives

The few structural values components share that are not colour, size or type. Kept minimal on purpose: this layer used to be much larger and most of it was removed with the theme packs.

What dark mode redefines

data-ran-theme="dark" on <html> (or on any subtree, see theming) redefines the base palette and nothing else, with three exceptions that cannot resolve through a scale:

• the whole of layer 1: every step of gray, gray-alpha, blue, red, amber, green, and both backgrounds;
• --ran-color-bg-elevated, which points at --ran-gray-100 in dark so a card lifts off a black page instead of vanishing into it;
• --ran-color-primary-hover / -active, which are literals rather than scale references;
• all three shadow tiers, retuned for a dark ground.

Everything else (every other semantic token, every size, every duration) is defined once.

Component tokens

Below the semantic layer, every component exposes its own hooks, named:

--ran-{component}-{element}[-{state}]-{property}

for example --ran-btn-hover-background, --ran-select-search-active-border-width. They default to semantic tokens: var(--ran-btn-background, var(--ran-color-primary, #171717)), so overriding a semantic token reaches all of them, and overriding a component token narrows the change to one element.

The full generated list is style-tokens-public.md in the repository; the per-element API is here. For how to apply them, see Theming.

Using tokens in your own CSS

.panel {
  background: var(--ran-color-bg-elevated);
  color: var(--ran-color-text);
  border: var(--ran-skin-border-width) var(--ran-skin-border-style) var(--ran-color-border);
  border-radius: var(--ran-radius-md);
  padding: var(--ran-space-4);
  box-shadow: var(--ran-shadow-elevated);
}

Three rules keep that dark-safe:

1. No raw hex for anything that should follow the theme.
2. A fallback must name a token that flips: var(--ran-color-text, var(--ran-gray-1000)), never var(--ran-color-text, #171717).
3. A fallback must name a token that exists, or the declaration is dropped and the element silently keeps whatever it inherited.

Every global token the library declares is listed on this page, and a unit test fails if one is added without being documented here. Component-scoped tokens are generated separately, in style-tokens-public.md.