Three layers — primitives, semantic aliases, and component tokens — as DTCG JSON and CSS custom properties.
Caustica Design follows a 3-layer CSS custom property model aligned with DTCG 2025.10.
| Layer | Role | Examples |
|---|---|---|
| Primitives | Raw scales — color ramps, space, radius, motion | --ca-blue-500, --ca-space-4 |
| Semantic | Purpose aliases consumed by UI | --color-fg, --glass-border, --text |
| Component | Local APIs scoped to a class | --btn-bg, --panel-radius |
Theme by overriding semantic aliases only. Leave primitives stable so component tokens keep resolving through the same chain. See Theming.
| Path | Purpose |
|---|---|
tokens/*.tokens.json |
Portable W3C DTCG source (primitives, semantic, themes)
|
src/css/tokens/ |
Runtime CSS — primitives.css + semantic.css
|
src/css/components/*.css |
Component-local tokens (e.g. --btn-* on .btn)
|
Import via caustica-design/css (full) or caustica-design/css/foundation
(fonts + tokens + body chrome). Token JSON is also exported as
caustica-design/tokens.
Dark is the default on :root /
html[data-theme="dark"]. Light remaps the same names under
html[data-theme="light"].
--color-fg / --color-fg-muted — foreground--color-bg-deep / --color-bg-elevated — surfaces--color-system-blue — accent / primary actions--glass-surface, --glass-border, --glass-highlight
--text, --muted, --accent, --ok, --warn, --danger, --info
--ca-space-1 … --ca-space-24 — 4px-unit scale, key
N = N × 4px (see
Spacing)
The fastest brand remap is --ca-hue (and --ca-chroma) —
semantic OKLCH tokens follow. --ca-chroma: 0 is Ink (grayscale);
status hues stay colored. Glass frost / fill / edge use
--ca-blur-glass, --ca-glass-fill, and
--ca-glass-edge. Load those knobs in a host file after Caustica Design CSS
— see
Getting started → Brand palette
and
Glass knobs.
You can still override individual aliases. Preview both on
Examples → Colors
and
Examples → Glass.
/* After caustica-design/css or foundation */
:root {
--ca-hue: 192;
--ca-chroma: 1;
--ca-blur-glass: 24px;
--ca-glass-fill: 0.8;
--ca-glass-edge: 1.1;
}
/* Or remap a single semantic alias */
:root,
html[data-theme="dark"] {
--color-system-blue: oklch(0.58 0.17 264);
--color-accent: var(--color-system-blue);
--accent: var(--color-system-blue);
}
html[data-theme="light"] {
--color-system-blue: oklch(0.48 0.19 264);
--color-accent: var(--color-system-blue);
--accent: var(--color-system-blue);
}