@candlelight-ds/tokens

The Candlelight token sheet — stage/ink ladders, voice colors, the fill ramp, structure, motion, and machined physicality — as plain CSS custom properties, with an optional Tailwind v4 theme layer.

Tokens are the part of Candlelight you do not copy in and own: they are law. The fill-ramp alphas, radii/shadow/z scales, durations, and the one ease are the system (spec §2.9); this package exists so they arrive exact and stay exact. The package's tests fail if a value drifts.

Install

pnpm add @candlelight-ds/tokens

Use — Tailwind v4

/* your global stylesheet */
@import "tailwindcss";
@import "@candlelight-ds/tokens/tailwind.css";

You get the tokens, the structural/motion physics, and the utility API — the utility names are the system's API, and every scale is a closed set:

• Color: bg-stage, bg-surface-2, text-ink, text-ink-mute, border-hairline, bg-fill-hover, bg-fill-selected, text-brass, …
• Radius (closed): rounded-cap (4px chamfer) · rounded-sm (8px controls) · rounded-md (16px panels) · rounded-lg (24px shell). Tailwind's default radius steps are wiped; rounded-[Npx] is lint-banned.
• Type (closed): text-nano 9 · text-micro 10 · text-eyebrow 11 · text-tooltip 11.5 · text-meta 12 · text-body 13 · text-body-lg 14 · text-title 15 · text-overlay-title 18 · text-heading 20 · text-heading-lg 28 · text-marquee 68 (bundled: weight 400, −0.04em, lh 1). Sizes only — weight/leading/case stay at the call site.
• Tracking: tracking-chip 0.16em · tracking-label 0.18em · tracking-eyebrow 0.22em · tracking-title −0.01em.
• Z ladder: z-surface / z-rail / z-float / z-overlay / z-announce. 999 does not exist.
• Motion: duration-instant 120 · duration-ui 150 · duration-sheet 150 · duration-scene 2500 · ease-stage.
• Elevation: shadow-raise / shadow-float / shadow-stage.

Changing a token in this package cascades through every consumer of these names; @candlelight-ds/eslint-plugin bans the arbitrary-literal escape hatches (rounded-[…], z-[…], text-[Npx], tracking-[…], duration-[…]) so the scales stay closed.

Set the type family (one family, every role — spec §2.6) by defining --font-inter, e.g. with next/font:

const inter = Inter({ variable: "--font-inter", subsets: ["latin"] });

Use — any other stack

@import "@candlelight-ds/tokens"; /* tokens.css + structural.css */

Plain CSS custom properties (var(--stage), var(--fill-hover), …) plus the normative structural classes (.animate-stage-rise, .skeleton, .key-cue, .sheet-panel, …). Reproduce the Tailwind utility names in your styling system; the names are the contract components are written against.

Re-theming (spec §2.9)

May change: the accent triad's hue (keep the ΔL relationships between base/hot/deep), the --live/--ready/--warn hues (keep contrast against surfaces). Must not change: everything else — stage/ink lightness relationships, fill-ramp alphas, radii/shadow/z scales, durations/ease, spacing scale (4/8/12/16/20/24/32).

Full specification: the Candlelight spec.