# Brand Asset And Proofing Spec

This file captures the operating rules for Caldura v4 logo, wordmark, lockup,
proof, and comp generation. It exists because a small drift at one layer can
look like a design decision at the next layer.

Use `brand-artifact-viewer.html` as the organized local entry point for the
current assets, proofs, specs, comps, diagnostics, comparisons, and archive
references described here.

## Core Rule

Production assets own production geometry. Proofs and comps may show assets,
compare assets, and annotate assets, but they must not repair assets.

If a mark, wordmark, color, weight, baseline, glyph, or lockup position is
wrong, fix the token or generator layer, regenerate the asset, then regenerate
the proof. Do not compensate in a proof page or comp sheet.

## Standard Terms

Use these names consistently in file names, reviews, commits, and comments.

| Standard term | Purpose | Authority level |
|---|---|---|
| Design Tokens | Named color, type, motion, and variant values | Source |
| Asset Generator | Code that turns tokens/spec values into concrete files | Source |
| Production Assets | Deliverable SVG/PNG files in `assets/` | Source output |
| Direct Render | PNG made by opening a production SVG directly as a document | Render control |
| Mechanical Proof | Single-asset proof that must preserve the direct SVG document path | Render proof |
| System Reference Spec | One-view design-system page for judging relationships across brands | Design reference |
| Package Inventory Proof | Proof that real asset files exist and link correctly | Packaging check |
| Design Review Comp | Comparative or exploratory review artifact | Review surface |
| Diagnostic Proof | Temporary or retained proof for isolating one technical/design question | Debug/reference |
| Open Graph Social Preview | 1200 x 630 link-unfurl image for sharing contexts. Visible copy must be public-facing, not variant slugs. | Delivery asset |
| Locked Reference | Preserved accepted snapshot that must not be regenerated | Historical baseline |
| Archive | Preserved rejected or historical material | History |

Do not use `comp` as a generic synonym for every artifact. A comp supports
design judgment. A proof verifies a specific rendering or packaging claim. A
spec documents the system relationship.

## Layer 1: Design Tokens

Token files own color, typography stacks, motion posture, and variant naming.

Current adopted variants:

| Entity | Adopted variant |
|---|---|
| Parent / Caldura | `group/variant-parent` |
| Caldura Capital | `capital/variant-blue-institutional` |
| Caldura AI | `ai/variant-amber` |

Rules:

- Tokens should define the system values, not one-off page corrections.
- Entity colors must flow from tokens into generated assets and comp sheets.
- Font identity is vendored through `assets/shared/fonts/brand-fonts.css`.
- Review pages must not introduce remote Google Fonts or local-machine font
  dependencies.

## Layer 2: Asset Generator

`assets/generate-adopted-variant-assets.mjs` owns the technical production
asset geometry for adopted variants.

The generator is responsible for:

- Mark geometry.
- Wordmark font family, weight, size, color, and spacing.
- Lockup mark-to-wordmark spacing and vertical alignment.
- Tight production viewBoxes and production padding.
- Repo-relative `@font-face` declarations for live-text SVG assets.
- Favicons, social-preview files, and expected asset package population.

Rules:

- Do not hand-edit generated asset geometry in downstream SVGs.
- Do not fix a lockup by moving subparts in a proof page.
- Do not use proof-page CSS to correct mark position, text size, font weight,
  or colors in a generated lockup.
- If generated SVG text uses a multi-word family such as `Source Serif 4`, keep
  the family in CSS style form, not as an ambiguous SVG presentation shortcut.

## Layer 3: Production Assets

Production SVGs in `assets/**/marks`, `assets/**/wordmarks`, and
`assets/**/lockups` are the canonical source files for repo-local delivery.

Rules:

- A production lockup SVG must be meaningful when opened directly as a document.
- Production lockups should use tight mechanical viewBoxes with intentional
  padding. The whole lockup, not the mark alone, is the artboard subject.
- A mode-specific SVG may include its own background when the background is
  part of the asset mode. Transparent assets must be proofed on a stated
  proof background.
- Live-text SVGs are source assets. If the asset must travel outside this repo
  as a standalone brand file, export an outlined-text delivery copy rather than
  relying on repo-relative font files.

Direct SVG rendering is the glyph authority for live-text SVG assets. If an
SVG opened directly and a proof wrapper disagree on letterforms, the wrapper is
wrong until proven otherwise.

## Layer 4: Direct Renders And Mechanical Proofs

Mechanical proofs answer one question: does the production asset render as the
production asset?

Examples:

- `comp-sheets/parent-lockup-mechanical-proof.html`
- `comp-sheets/capital-lockup-mechanical-proof.html`
- `comp-sheets/ai-lockup-mechanical-proof.html`
- matching `.png` proof renders

Rules:

- Mechanical proof pages may frame a single production SVG, but must not alter
  its internals.
- For live-text SVG lockups, do not use external SVG `<img>` as the typography
  proof path. Browser image rendering can take a different font path than a
  direct SVG document and can silently change glyphs.
- Use direct SVG document rendering, or an `iframe`/document-frame wrapper that
  preserves the direct SVG document path.
- For filled-background assets, the mechanical proof PNG should match the
  direct SVG PNG byte-for-byte.
- For transparent assets, use a documented proof background and judge against a
  direct render on the same background.
- Regenerate stale PNGs whenever the underlying asset or rendering method
  changes. Stale proof PNGs are not evidence.

## Layer 5: System Reference Specs

System specs are design review pages that show the relationship among entities.

Examples:

- `comp-sheets/brand-system-spec.html`
- `comp-sheets/brand-lockups-proof.html`

Rules:

- System specs can use live HTML/SVG composition when that is the accepted
  visual review surface.
- A system spec is not allowed to be the only place where production asset
  geometry is correct. If the production SVG differs, fix the generator.
- `brand-lockups-proof.html` is the locked visual review model for the current
  lockup design. It should keep its live-HTML font path unless and until the
  production lockup SVGs are locked as outlined or embedded-font assets.
- The locked visual reference in `_locked-reference/` must not be regenerated.

## Layer 6: Package Inventory Proofs

Packaging proofs answer a different question: is the adopted asset package
fully populated and linkable?

Example:

- `comp-sheets/adopted-variant-asset-proof.html`

Rules:

- Packaging proofs may show real files via image/link surfaces.
- Packaging proofs are not the typography or lockup alignment authority.
- If packaging proof output visually disagrees with a direct SVG render, first
  suspect the packaging renderer, stale PNGs, or missing font context.

## Layer 7: Design Review Comps

Comparison comps support design judgment. They are not production assets.

Rules:

- Active comparison comps may scale assets for review, but cannot change
  internal lockup geometry.
- Rejected directions should move to `_archive/` with enough naming/context to
  explain what was rejected.
- A comp sheet can summarize attributes, colors, weights, and variants, but it
  should reference production assets or structured spec data rather than
  hand-copying final geometry.

## Layer 8: Runtime Publication

Runtime publication is the hand-off from HEAT-canonical generator output to a
consumer repo's runtime delivery slot. Without this layer the system can ship
a perfect v4 asset that the live site never serves, because the consuming
metadata path is wired to a stale or legacy file name.

Example (current):

- `scripts/publish-v4-adopted-delivery.mjs` copies each adopted variant's
  `og/<ogFile>.{svg,png}` from `systems/v4/assets/` into the sister sites
  repo at `sites/public/brand/og/og-<runtimeSlug>.{svg,png}`, and copies the
  shared family favicon package from `systems/v4/assets/shared/favicon/`
  into `sites/public/brand/favicon/`. The adopted entity-to-variant mapping,
  the runtime slug, and the shared-asset declaration are all read from
  `systems/v4/assets/adopted-variants.mjs`, which is the single source of truth.

### Shared family-level assets

Not every delivery asset is variant-specific. Some assets belong to the
Caldura family as a whole and are consumed identically by all three sites:

- **Favicon**: the crucible "C" mark is the accepted family mark at favicon
  scale. It is deliberately decoupled from any per-entity variant and from
  the parent ring mark (locked per ADR-0007) — at 16px the "C = Caldura"
  cue dominates and that cue is stable across logo iterations. One shared
  SVG (mode-adaptive via internal `prefers-color-scheme` CSS) plus PNG
  fallbacks at the light polarity. Used by group, capital, and ai alike.

Shared assets live under `assets/shared/` and are declared in `adopted-variants.mjs`
as `shared.<asset>` blocks (not per-entity). The publish step copies them
once into a variant-agnostic runtime folder (`sites/public/brand/favicon/`,
not `sites/public/brand/favicon/<entity>/`).

The per-variant favicon package under `assets/<entity>/<variant>/favicon/`
remains in the generator output as a variant-package completeness proof,
but is not what production serves.

Rules:

- A consumer's runtime delivery file is a mirror of a generator output. Do
  not hand-edit a published file in the consumer repo. If it is wrong, fix
  the token or generator layer, regenerate, then re-publish.
- Runtime slugs are variant-agnostic and entity-named on the consumer side
  (e.g. `og-parent.png`, not `og-parent-light.png`) so that swapping the
  adopted variant does not require URL changes in the consuming app.
- The mapping from entity to adopted variant and from entity to runtime slug
  lives in `adopted-variants.mjs`. Generator, validator, publish script, and any
  consumer-side adopted-class wiring (e.g. `layout.tsx` body class) should
  derive from that single declaration rather than re-stating it.
- A publish script must verify its sources exist before writing destinations;
  a stale or missing source should fail loudly rather than partially publish.
- Validator passes are a precondition to publication. Do not publish unvalidated
  generator output.

## Current Inventory

This is the active Caldura v4 brand stack as of the current design-review
baseline.

| Layer | Active files | Current status |
|---|---|---|
| Design Tokens | `code/group/variant-parent/tokens.css`; `code/capital/variant-blue-institutional/tokens.css`; `code/ai/variant-amber/tokens.css`; `assets/shared/fonts/brand-fonts.css` | Adopted variant values are present and validated. |
| Asset Generator | `assets/generate-adopted-variant-assets.mjs`; `assets/validate-adopted-variant-assets.mjs` | Generator owns asset geometry; validator now guards against mechanical proof `<img>` regressions. |
| Production Assets: Parent | `assets/group/variant-parent/marks/ring-parent-light.svg`; `wordmarks/caldura-parent-light-wordmark.svg`; `lockups/caldura-parent-light-static.svg`; `favicon/*`; `og/*` | Populated. Parent lockup is transparent, so proof background must be stated. |
| Production Assets: Capital | `assets/capital/variant-blue-institutional/horizon-mark.svg`; `wordmarks/*paper*`; `wordmarks/*dark*`; `lockups/*paper.svg`; `lockups/*dark.svg`; `favicon/*`; `og/*` | Populated. Paper lockup direct render and mechanical proof match by hash. |
| Production Assets: AI | `assets/ai/variant-amber/bloom-mark.svg`; `wordmarks/*dark*`; `wordmarks/*light*`; `lockups/*static.svg`; `lockups/*animated.svg`; `favicon/*`; `og/*` | Populated. Dark static lockup direct render and mechanical proof match by hash. |
| Favicons + Social Previews | `assets/**/favicon/*`; `assets/**/og/*` | Delivery assets for browser tabs, Apple/PWA icons, and link unfurls. Social-preview PNGs should be browser-rendered, not ImageMagick-rendered, when live SVG text is involved. |
| Direct Renders | `comp-sheets/parent-lockup-direct-svg.png`; `capital-lockup-direct-svg.png`; `ai-lockup-direct-svg.png` | Render controls for isolated production SVG inspection. |
| Mechanical Proofs | `comp-sheets/parent-lockup-mechanical-proof.html/.png`; `capital-lockup-mechanical-proof.html/.png`; `ai-lockup-mechanical-proof.html/.png` | Fixed to use document-frame rendering, not external SVG `<img>`. |
| System Reference Specs | `comp-sheets/brand-system-spec.html/.png`; `brand-lockups-proof.html/.png`; `brand-lockup-spec.mjs`; `generate-brand-lockups-proof.mjs` | Current design reference surfaces. They use live HTML/SVG composition by design. |
| Locked Reference | `comp-sheets/_locked-reference/brand-lockups-proof.accepted-locked.png` | Preserved accepted snapshot. Do not regenerate. |
| Package Inventory Proof | `comp-sheets/adopted-variant-asset-proof.html/.png`; `render-comps.sh` | Uses `<img>` intentionally to verify real files are populated and linkable. Not glyph authority. |
| Design Review Comps | `parent-light-logo-wordmark-comp-sheet.png`; `capital-blue-institutional-logo-wordmark-comp-sheet.html/.png`; `ai-amber-logo-wordmark-comp-sheet.png`; `brand-static-logo-overview.html/.png`; `brand-parent-site-light-comp.html` | Review surfaces only; should not repair production geometry. |
| Diagnostic Proofs | `source-serif-4-type-proof.html/.png`; `bloom-mark-height-comparison.html/.png` (AI-only — parent uses the ring per ADR-0007) | Retained because they answer specific font/mark-position questions. Not production assets. |
| Active Comparisons | `comp-sheets/top-level-variant-comparisons/*` | Still-live comparison history for top-level variant review. |
| Archive | `comp-sheets/_archive/*` | Rejected or historical material. |
| Adopted Declaration | `assets/adopted-variants.mjs` | Single source of truth for entity → adopted variant, OG filename, runtime slug, and shared family-level assets. Consumed by generator, validator, and publish script. |
| Shared Family Assets | `assets/shared/favicon/*`; `assets/shared/fonts/*` | Caldura-family-level assets used identically by all three sites. The favicon mark (crucible-C, mode-adaptive) is decoupled from per-entity variants and from in-progress logo work. |
| Runtime Publication | `../../scripts/publish-v4-adopted-delivery.mjs`; published into `sites/public/brand/og/og-<runtimeSlug>.{svg,png}` and `sites/public/brand/favicon/*` | Mirrors adopted-variant OG output and shared family favicon into the consumer site's runtime delivery slots. Published files must not be hand-edited in the consumer repo. |

## Rendering Workflow

Use this order when changing the brand system:

1. Update tokens, structured spec data, or the asset generator.
2. Regenerate adopted assets.
3. Validate adopted asset package population.
4. Render direct SVG PNGs for isolated asset inspection.
5. Render mechanical proofs from the direct-document proof path.
6. Confirm direct and mechanical renders match where they should.
7. Regenerate system specs and comparison comps.
8. Compare to the locked reference only after the lower tiers are clean.
9. Publish adopted-variant delivery assets into consumer repos. Only after
   the validator passes.

Recommended commands from the repo root:

```sh
node systems/v4/assets/generate-adopted-variant-assets.mjs
node systems/v4/assets/validate-adopted-variant-assets.mjs
powershell -ExecutionPolicy Bypass -File systems/v4/comp-sheets/render-comps.sh
node scripts/publish-v4-adopted-delivery.mjs
```

Use Chrome with a font-load delay when rendering PNGs from HTML:

```sh
chrome --headless=new --disable-gpu --hide-scrollbars --disable-cache --virtual-time-budget=7000 ...
```

## Known Failure Modes

| Failure | Symptom | Correct fix |
|---|---|---|
| SVG rendered through `<img>` | Different C/glyph shapes from direct SVG | Use direct SVG document render or iframe proof path |
| Stale PNG proof | Old letterforms or scale survive after SVG fix | Regenerate proof PNGs and compare hashes |
| Proof-layer adjustment | One comp looks right while production asset remains wrong | Move fix to generator/tokens |
| Remote or local fonts | Machine-dependent letterforms or timing | Use vendored `assets/shared/fonts` |
| Presentation-attribute font family | Multi-word family falls back in SVG text | Use CSS `font-family:'Source Serif 4', ...` |
| Transparent asset background | Hash/visual mismatch caused by page background | Set and document the proof background |
| Comp sheet as source of truth | Asset package drifts from accepted design | Reconcile generator against locked reference |
| Stale runtime delivery slot | Live site serves an older asset polarity or palette than the canonical v4 output | Wire the consumer slot to a publish step that reads `adopted-variants.mjs`; never hand-edit the published file |

## Acceptance Checks

Before committing logo/wordmark work:

- Adopted variants are populated in `assets/`.
- Validator passes.
- Production SVGs open directly and show the expected letterforms.
- Mechanical proof pages do not use `<img>` for live-text SVG typography proof.
- Filled-background direct and mechanical PNGs match by hash.
- Transparent assets are compared on a stated proof background.
- System spec and lockup proof are regenerated from structured data, not
  hand-adjusted copies.
- `_locked-reference/brand-lockups-proof.accepted-locked.png` remains untouched.
- Adopted-variant delivery assets are re-published to consumer runtime slots
  via `scripts/publish-v4-adopted-delivery.mjs` whenever OG output changes.