Vital

A lumen is two things: a unit of light, and the interior channel of a vessel. That pun is the system's whole motion theme — everything that moves in Lumen is light and cells moving through the body's channels. Not a metaphor applied to the components; the rule the components are derived from.

Every waiting surface is a view of the same channel:

One tempo, two meters

Every duration in the language is a stated multiple of one pulse — --vital-tempo (1.25s, a resting heart). The cardiac rhythms and the wait-light run on the pulse; the respiratory rhythms run in triple meter over it. That shared heartbeat — not a shared color, not a shared easing — is what makes six rhythms and four light-scales read as one organism.

Retuning the organism is one token. The truth script enforces the timeline: TEMPO in TypeScript must equal --vital-tempo, the light's durations must derive from it, and the registry may hold only beat multiples from these two meters — a third meter needs a ruling, not a commit.

The six rhythms

All interior, all involuntary — motions a channel can actually make. Rendered live from the package registry; change the register and the same rhythms dial up and down.

Presence — how much the system shows up

A loader that looks identical prefetching in the background and blocking the screen is lying about one of those situations. Presence is the dial: one rhythm, four registers, scaling amplitude, bloom, tempo, and the field's density off one variable (--vital-amp, multiplied into every keyframe).

Presence cascades through [data-presence], so a whole region dials at once. Paired with the timing contract, a wait that goes long changes its bearing, not just its words:

const { pending, long } = usePending(active);

<Loader rhythm="heartbeat" presence={long ? 'urgent' : 'attentive'} />

Variance — why it reads alive

A loop that repeats exactly is a machine. A living rhythm wanders: real hearts have heart-rate variability, and its absence is a clinical warning sign. So the system's pulse wanders — every registered element drifts ±8% along a slow, deterministic curve, each starting at its own phase, and no two loaders on a screen ever tick together.

Toggle variance off in the zoo above and the grid snaps into lockstep. Nothing else changes. That difference is the whole argument.

Components that own their presence (Loader) drive themselves. For everything else — a Skeleton, a Beam, a Spinner rendered on the server — mount VitalRoot once and it adopts every [data-vital] element beneath it:

import { VitalRoot } from 'lumen/react';

<VitalRoot>
  <App />
</VitalRoot>

The field — the channel, radiant

At urgent the light doesn't stay inside the cells: it scatters. Systole throws light outward, diastole draws it home — and it is genuinely one clock: the field phase-locks to the first cell's real Animation.currentTime, wander included, and reads its accents from the same registry beat map the keyframes encode. Canvas and CSS land their energy on the same instant.

The palette obeys the transillumination law the tokens already state — light through blood deepens, it doesn't bleach: the scatter is the warm ramp only (--glow → --primary → --primary-text), thinning as it deepens. No cool flecks (data's color), no camera bokeh — this is the same light as the sweep, the beam, and the spinner, one scale up. It overflows the mark's box deliberately (hero use), stays out of the accessibility tree, and paints one still frame under reduced motion.

The arrival — the wait's ending

The contract is meticulous about a wait's beginning (180/420ms) and its escalation (long → urgent). The arrival owns the third beat: when the wait resolves, the cells glide to rest on the vessel line, the field draws its light home, and only then does the answer rise in on the exhale. One gesture, one duration — --duration-settle, ×0.32 of the tempo, so even the ending sits on the timeline.

Arrival choreographs it: placeholder while pending, the settle handshake when the wait resolves, then the enter. Placeholders with nothing to land (skeletons, spinners) skip straight to the rise — the common fast path costs nothing over the old instant swap. And content that was never waited for never animates: a page of Arrivals doesn't ripple on load, because motion is earned by a signal.

const { pending, long } = usePending(isLoading);

<Arrival pending={pending} placeholder={<Loader size={40} presence={long ? 'urgent' : 'attentive'} />}>
  <Reading data={data} />
</Arrival>

A custom placeholder can join the handshake with useSettle:

const { settling, onSettled } = useSettle();
React.useEffect(() => {
  if (settling) playMyExit().then(onSettled);
}, [settling, onSettled]);

Under reduced motion there is nothing to land and nothing rises — the answer simply appears, and a settler that can't play its landing counts as landed.

Reduced motion

Every animation lives inside a prefers-reduced-motion: no-preference guard — enforced by the truth script, which fails the build if one escapes. Under reduced motion the cells settle onto the vessel line, the field paints one still frame, and the driver never starts. Presence still reads: urgent's bloom is visible even at rest.

API

import {
  Loader, Arrival, useSettle, VitalRoot, VitalField,
  RHYTHMS, PRESENCE, TEMPO, useVital,
} from 'lumen/react';

<Loader rhythm="perfuse" presence="resting" />
<Loader size={44} presence="urgent" />          {/* the scatter comes along */}
<Loader rhythm="heartbeat" variance={0} />      {/* opt out: a true metronome */}

// drive your own element with the language
const vital = useVital({ presence: 'attentive' });
<svg ref={vital} data-rhythm="breath">…</svg>

RHYTHMS is the registry — id, name, meter, beat multiple, per-cell lags, and the beat map (accents) that both the keyframes and the field read. The truth script checks every entry has real keyframes behind it and that every duration sits on the tempo timeline, so the theme can't drift apart one commit at a time.

→ Loading — the ladder and the timing contract · Animation — the motion families · The loader zoo — the sketchbook