# Caldura Design System v4 — design-review baseline

**Status: design-review baseline · not production-ready**

The v4 design system is in active development, but the current HEAT baseline
has adopted one parent, one Capital, and one AI variant for continued review:
`group/variant-parent`, `capital/variant-blue-institutional`, and
`ai/variant-amber`. Older comparison variants remain in the repo as review
history and alternatives, not as the current adopted direction.

Production today: `systems/v3.1/`.

## What's in this folder

| File / folder | What it is |
|---|---|
| `caldura-v4-strategic-brief-2026-05-11.md` | Why v4 exists, what it explores, the eight directional moves |
| `caldura-v4-architecture-2026-05-11.md` | How v4 is organized — variant tiers, motion gates, consume pattern |
| `voice-in-interface-2026-05-14.md` | Microcopy register per entity (Capital institutional-peer vs AI workshop-direct) |
| `CHANGELOG.md` | The v4 evolution log |
| `brand-artifact-viewer.html` | Organized local viewer for current assets, proofs, specs, comps, diagnostics, comparisons, and archive references |
| `brand-asset-proofing-spec.md` | Operating rules for tokens, generated SVG assets, mechanical proofs, system specs, and comps |
| `code/shared/` | Tier 1 / 2 / 3 CSS — foundation tokens, deck tokens, components, motion, motifs |
| `code/group/variant-parent/` | Caldura Group parent-light — warm cream hub, bronze parent mark, cross-brand portal |
| `code/ai/variant-amber/` | Current AI direction — dark amber, nuanced motion, Source Serif 4 connected wordmark |
| `code/ai/variant-builder/` | AI · builder (workshop / founder energy, radiating coral, full motion) |
| `code/ai/variant-lab/` | AI · lab (considered AI-lab, muted coral, still, editorial density) |
| `code/capital/variant-warm-distinctive/` | Candidate A — burnt amber on cream, still, Horizon |
| `code/capital/variant-warm-steel/` | Candidate B — slate-navy on cream with amber heat-retention, still, Horizon |
| `code/capital/variant-blue-institutional/` | Current Capital direction — deep navy on paper-white, monochromatic, still, Horizon |
| `code/capital/variant-v31-baseline/` | Frozen v3.1 Capital translated into v4 architecture (reference only, not a candidate) |
| `assets/` | Marks, lockups, social-preview images, and favicons per variant |
| `compare/` | Side-by-side rendering surfaces for LP review |
| `comp-sheets/` | Current logo / wordmark comp sheets, active top-level comparisons, and archived rejected explorations |

## Current adopted variants

- **Parent / Caldura:** `group/variant-parent` — warm cream hub, bronze parent ring mark (outer-heavy, inner-air), static parent lockup, child wayfinding accents for Capital and AI.
- **Caldura Capital:** `capital/variant-blue-institutional` — deep navy `#1B365D` on paper-white `#F8F6F0`, Horizon mark, static lockup, wordmark family 500 / suffix 400.
- **Caldura AI:** `ai/variant-amber` — warm-black dark default, amber `#E8A24C`, Bloom mark, static assets plus animated AI-only lockups, wordmark family 500 / suffix 400.

The older Capital variants (`warm-distinctive`, `warm-steel`, `v31-baseline`)
and older AI variants (`builder`, `lab`) remain available as comparison and
history.

## Parent group variant

`group/variant-parent` is the canonical `caldura.com` hub expression.
It uses warm cream, quieter old-gold bronze, a calmer Bloom mark, and explicit
child accents for Capital navy and AI amber. Its role is architectural: frame
the two operating brands without becoming a third competing entity palette.

## Status check on v4 readiness

| Concern | Status |
|---|---|
| Token contract | Complete — all variants declare CTA, deck Tier-2, and motion tokens explicitly |
| WCAG AA across the system | All 10 variant × mode pairs pass; 3 v4 Capital candidates hit AAA on default mode |
| Adopted asset packages | Complete for parent-light, blue-institutional, and amber (marks, wordmarks, lockups, social previews, favicons) |
| Compare surfaces | Complete (`compare/index.html`, `compare/capital.html`, plus 5 standalone) |
| Reviewer guidance | `compare/README.md` scopes useful feedback at this stage |
| One Capital variant committed | Current review baseline uses `variant-blue-institutional` |
| v4 spec doc | Current reference comps live in `comp-sheets/` |
| Production-readiness | Not yet — preview only |

## Publish review viewer

Run this from the HEAT repo root to sync the current v4 review bundle into
the Caldura sites repo:

```sh
node scripts/sync-v4-brand-viewer-to-sites.mjs
```

The script copies `systems/v4/` to
`../sites/public/brand-system/v4/` and verifies the local references in
`brand-artifact-viewer.html`. In the sites app, the public entrypoint is:

```txt
/brand-system/v4/brand-artifact-viewer.html
```