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, --danger, --ok--ca-space-1 … --ca-space-24 — 4px-unit scale, key
N = N × 4px (see
Spacing)
Brand a host app by remapping semantic names after Caustica Design CSS loads — not by editing primitive scales.
/* After caustica-design/css or foundation */
: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);
}