# Caldura v4 — Token surface

Reference of the public CSS custom properties (tokens) the v4 design system declares. Tokens organize into four tiers:

- **Tier 0 — Variant** (`.caldura-<entity>.variant-X`) — wrapper-scoped overrides per variant.
- **Tier 1 — Foundation** (`:root`) — atomic brand decisions shared across all entities and variants.
- **Tier 2 — Deck semantic** — deck-context tokens, declared per variant (paper / cream / dark grounds resolve their own values).
- **Tier 3 — Component** (inside component selector) — module-local component tokens.

Tokens in this doc are the **public surface** — names are stable across v4. Values may move during the v4 cycle until one Capital variant commits, but names are committed.

---

## Tier 1 — Foundation tokens (`:root`)

Declared in `code/shared/tokens-foundation.css`. Always available regardless of which variant is active.

### Page grounds

| Token | Hex (RGB) | Role |
|------|----------|------|
| `--bg-base-dark` | `#1A1210` (26 18 16) | warm-black, default dark ground for AI and v31-baseline |
| `--bg-base-light` | `#EAE2D6` (234 226 214) | warm cream, default ground for Capital warm variants |
| `--bg-base-paper` | `#F8F6F0` (248 246 240) | paper-white, default ground for variant-blue-institutional only |
| `--bg-surface-{dark,light,paper}` | various | surface elevation one step above ground |
| `--bg-surface-hover-{dark,light,paper}` | various | hover state |

Each variant resolves `--bg-base` to one of these by assigning `var(--bg-base-<mode>)`.

### Text

| Token | Hex | Role |
|------|----|------|
| `--text-primary-dark` | `#F5F0EB` | 16:1 contrast on warm-black |
| `--text-primary-light` | `#1A1210` | 16:1 contrast on cream and paper-white |
| `--text-secondary-dark` | `#A89888` | 6.5:1 on warm-black |
| `--text-secondary-light` | `#6B5D52` | on cream and paper-white |
| `--text-tertiary-dark` | `#94806E` | 5.0:1 on warm-black (v3.1 audit-corrected) |
| `--text-tertiary-light` | `#6F5C4C` | 5.0:1 on cream (v3.1 audit-corrected) |

### Borders

`--border-{dark,light,paper}`, `--border-hover-{dark,light,paper}` — surface borders per mode.

### Parent gold

| Token | Hex | Role |
|------|----|------|
| `--gold-parent-dark` | `#D4920A` | parent cross-reference accent on dark grounds |
| `--gold-parent-light` | `#9C6D08` | parent cross-reference accent on cream / paper-white |

`group/variant-parent` resolves its active `--accent` to a darker old-gold
bronze (`#765B12`) for the Caldura.com wordmark and hub UI. This is the parent
surface color, while `--gold-parent-*` remains the cross-reference token on
entity surfaces.

### Typography

| Token | Value |
|------|-------|
| `--font-display` | `"Source Serif 4", "Source Serif Pro", Georgia, "Times New Roman", serif` |
| `--font-body` | `"Inter Variable", Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` |
| `--font-mono` | `"JetBrains Mono", "SF Mono", Menlo, monospace` |

Fonts vendored in `_brand/fonts/`; @font-face declarations in `_brand/fonts/fonts.css`.

### Motion timing

`--motion-fast` (150ms), `--motion-medium` (240ms), `--motion-slow` (500ms), `--motion-breath` (3s), `--motion-entrance` (1.5s).

---

## Tier 0 — Variant tokens (`.caldura-<entity>.variant-X`)

Each variant's `tokens.css` declares the following set. The wrapper class scope shadows them for content inside.

### Resolved mode tokens (all variants)

| Token | Resolves to |
|------|--------------|
| `--bg-base` | one of `--bg-base-{dark,light,paper}` |
| `--bg-surface`, `--bg-surface-hover` | one of `--bg-surface-{dark,light,paper}` |
| `--text-primary`, `--text-secondary`, `--text-tertiary` | one of `--text-{primary,secondary,tertiary}-{dark,light}` |
| `--border`, `--border-hover` | one of `--border-{dark,light,paper}` |

### Variant identity

| Token | Role |
|------|------|
| `--accent` | the variant's primary accent — used by Horizon mark, wordmark suffix, chevron tinting, deck-kpi hero, link color, focus ring |
| `--accent-light` | a lighter complement for hover states and color-mix bases |
| `--accent-secondary` (warm-steel only) | the heat-retention amber used on links, footer rule, endcap dots |
| `--accent-secondary-light` (warm-steel only) | dark-mode complement of `--accent-secondary` |
| `--subtle` | very-low-saturation tint of the accent, used for subtle background washes |
| `--focus-ring` | focus outline color |

`group/variant-parent` also shadows the legacy cross-brand tokens
`--accent-group`, `--accent-capital`, `--accent-ai`, `--subtle-*`, and
`--bloom-inner-*` so parent hub surfaces can render the Caldura, Capital, and
AI lockups together without custom one-off color declarations.

### CTA pair

| Token | Role |
|------|------|
| `--cta-bg` | CTA button fill (often distinct from `--accent` — see contrast notes per variant) |
| `--cta-text` | CTA button text color, AAA-tested against `--cta-bg` for branded action buttons |

### Type weights

| Token | Role |
|------|------|
| `--weight-display` | display face weight (e.g., hero, h1) |
| `--weight-h1` | headline weight |
| `--weight-body` | body copy weight |
| `--weight-wordmark` | lockup family-name weight (`"Caldura"`). Shared connected-brand default is 500 so Parent, Capital, and AI keep the same family-name voice. |
| `--weight-suffix` | lockup entity-suffix weight (`" Capital"`, `" AI"`). Shared connected-brand default is 400 so the entity arm reads as a lighter qualifier to the Caldura family name. |
| `--letter-spacing-display` | tracking on the display face |

### Motion gating

| Token | Role |
|------|------|
| `--motion-mode` | conceptual flag (0 = still, 1 = full motion) |
| `--motion-play-state` | concrete CSS value (`paused` or `running`) — entrance.css and section-motifs.css read this |

### Density and texture

| Token | Role |
|------|------|
| `--density` | string label (`editorial`, `workshop`, `default`) — informational, may drive component padding |
| `--paper-texture-opacity` | numeric, 0 disables paper grain; warm variants set to 0.035 |

### Deck Tier-2 tokens (declared per variant for the active mode)

| Token | Role |
|------|------|
| `--deck-display-text` | hero / wordmark text color in deck contexts |
| `--deck-subtitle-muted` | subtitle / muted text color |
| `--deck-chrome-text` | deck chrome text (footer, slide-number) |
| `--deck-kpi-hero` | KPI value color (computed via color-mix on `--accent`) |
| `--deck-highlight-bg` | deck highlight band background |
| `--deck-section-band` | section divider band background |

These were previously declared globally and switched by `@media (prefers-color-scheme)`. As of 2026-05-14 they're variant-scoped to prevent system-mode / variant-mode mismatch bugs.

---

## Tier 3 — Component tokens (inside component selectors)

Declared in `code/shared/deck-components.css`. Each component reads variant tokens and exposes its own scoped tokens for visual customization.

### `.chevron`

| Token | Computed from |
|------|----------------|
| `--step-bg` | `color-mix(in srgb, rgb(var(--accent)) 15%, rgb(var(--bg-base)))` |
| `--step-bg-alt` | `color-mix(in srgb, rgb(var(--accent)) 10%, rgb(var(--bg-base)))` |
| `--step-text` | `var(--deck-display-text)` |

### `.deck-table`

| Token | Computed from |
|------|----------------|
| `--row-alt-bg` | `color-mix(in srgb, rgb(var(--accent)) 8%, transparent)` |
| `--cell-border` | `color-mix(in srgb, rgb(var(--accent)) 35%, rgb(var(--bg-base)))` |

### `.matrix`

| Token | Computed from |
|------|----------------|
| `--hero-bg` | `color-mix(in srgb, rgb(var(--accent)) 18%, rgb(var(--bg-base)))` |
| `--hero-border` | `rgb(var(--accent))` |

### `.deck-kpi`

| Token | Computed from |
|------|----------------|
| `--tile-bg` | `color-mix(in srgb, rgb(var(--accent)) 12%, rgb(var(--bg-base)))` |
| `--tile-text` | `var(--deck-kpi-hero)` |
| `--tile-label` | `var(--deck-subtitle-muted)` |

### `.deck-bullets`

| Token | Computed from |
|------|----------------|
| `--marker` | `rgb(var(--accent-light))` |

### `.deck-badge`

| Token | Computed from |
|------|----------------|
| `--bg` | `rgb(var(--bg-surface))` |
| `--border` | `rgb(var(--border))` |
| `--text` | `var(--deck-display-text)` |

---

## What's NOT in the public token surface

- Internal CSS variables in animation `@keyframes` — those aren't tokens, they're implementation.
- Per-component layout values (padding, margin, gap) — those live in CSS rules, not as tokens, because a consuming surface might choose to override component layout entirely.
- Compare-page styling tokens — `compare/*.html` files contain their own inline CSS for review chrome and are not part of the design system surface.