# Wordmark

**Status:** rev-2 amended 2026-05-11 (uppercase V + larger trailing dot; operator-locked via amendment workshop Rounds 1–5). rev-1 authored 2026-05-04.

**Source spec:**
- `reference-visual-mockups.html` lines 246-298 (CSS spec; bookend wordmark composition)
- `reference-design-system.html` lines 1505-1530 (V SVG path + canonical instance markup)
- `assets/wordmark.svg` (production-ready single SVG asset; text-as-paths from real Inter Semibold)

---

## Purpose

The Vecreal wordmark is the company's primary brand identifier. It appears on:
- Cockpit title bar
- Marketing surfaces
- Pitch decks (slide-cover.md uses)
- Customer-facing product UI (Project Intelligence + Corporate Intelligence)
- Email signatures, social, etc.

The wordmark is the bookend composition: `[V SVG][ecreal text][dot]`. The V is a designed UPPERCASE chevron mark sized to Inter Semibold cap-height — it bookends the wordmark as an institutional opening letter. The trailing dot is the brand bookend punctuation in clay accent.

---

## Canonical asset

**Production use: `projects/vecreal/drafts/brand-atoms/assets/wordmark.svg`** (single SVG file; text-as-paths from real Inter Semibold; scalable; brand colors embedded with prefers-color-scheme dark mode override)

For React consumers, prefer inlining the SVG directly (allows CSS class theming). For HTML / static sites, `<img src="wordmark.svg">` works.

---

## Composition

The wordmark consists of THREE elements rendered inline:

1. **V SVG** — designed chevron mark in clay (`bk-v` class)
2. **"ecreal" letters** — Inter Semibold 600 typography (`bk-text` class)
3. **Trailing dot** — small clay circle (`bk-dot` class)

These three elements compose into one continuous visual unit. The V is uppercase, sized to match Inter Semibold cap-height (0.72em); reads as the bookend opening letter that institutionalizes the wordmark.

---

## Composition rules

| ID | Rule | Type |
|----|------|------|
| wordmark.do.1 | Use the V SVG path from `reference-design-system.html:1506-1507`; do NOT recreate from scratch | do |
| wordmark.do.2 | Render "ecreal" as text-as-paths from Inter Semibold (or via real `<text>` with Inter loaded; latter only when font-bundling is verified) | do |
| wordmark.do.3 | Trailing dot is `--bk-dot-size` (0.22em) circle in `--accent` / `--accent-bright` token | do |
| wordmark.do.4 | V is uppercase; cap-top aligns with Inter Semibold cap-height (0.72em); V tip at baseline | do |
| wordmark.do.5 | Letter spacing `-0.05em`; V-to-e gap `-0.13em`; dot margin-left `calc(0.04em + 2px)` from 'l' visible right edge | do |
| wordmark.dont.1 | Do NOT render "Vecreal" as standalone span text (the V is the SVG; "ecreal" is the text portion) | dont |
| wordmark.dont.2 | Do NOT add a separate V monogram element beside the wordmark; the V is BUILT INTO the wordmark | dont |
| wordmark.dont.3 | Do NOT use default browser font for "ecreal"; must use Inter Semibold (or text-as-paths) | dont |
| wordmark.dont.4 | Do NOT scale wordmark beyond brand-locked sizes (hero/xl/lg/md/sm/xs); custom sizes need brand approval | dont |
| wordmark.dont.5 | Do NOT alter colors beyond clay-light/clay-bright (V + dot) and text-primary/text-dark-primary (text); the wordmark colors are LOCKED | dont |

---

## Sizes

| Variant | Font-equivalent size | Use case |
|---------|----------------------|----------|
| size-hero | 96px | Splash / landing hero |
| size-xl | 64px | Marketing display |
| size-lg | 48px | Marketing hero |
| size-md | 32px | Headers / page titles |
| size-sm | 22px | Sidebar / titlebar |
| size-xs | 18px | Compact contexts (e.g., footer signatures) |

Cockpit title bar uses `size-sm` or custom width via SVG width attribute. For arbitrary sizing, set SVG `width` and aspect ratio is preserved (viewBox 7800×2048; aspect ~3.81:1).

---

## Color tokens

Light surfaces:
- V + dot: `--clay-light` (#A05847)
- Text: `--text-primary` (dark text on light)

Dark surfaces:
- V + dot: `--clay-bright` (#C68070)
- Text: `--text-dark-primary` (#f7f8f8)

The canonical `assets/wordmark.svg` includes a `<style>` block with both light and dark via `prefers-color-scheme` media query. Consumers can override via parent CSS class or by inline-styling the bk-* class fills.

---

## Operator-tuning history

- 2026-05-04 initial migration: bookend CSS spec + V SVG markup migrated from `docs/brand/` HTML reference into `brand-atoms/` (without `wordmark.md` canonical spec doc — gap)
- 2026-05-04 cockpit Gate 3 v2-operator review: gap surfaced; FactoryShell.tsx had improvised `<span>Vecreal</span>` rendering causing visible "V then Vecreal" duplication; operator instructed conversion to single SVG asset
- 2026-05-04 SVG asset authored: Python `fontTools.pens.svgPathPen` extracted Inter Semibold "ecreal" glyph paths; composed with V SVG + dot
- 2026-05-04 first build (V height 0.56em, dot 0.04em from advance-end): operator visual review found V tip floating above baseline + dot too far
- 2026-05-04 second build (V height x-height = 0.546em, V tip at visual curve max, dot 0.04em from VISIBLE edge): operator found V good, dot too close
- 2026-05-04 third build (V unchanged, dot at half-revert midpoint): operator approval — rev-1 locked
- 2026-05-11 rev-2 amendment workshop (Rounds 1–5): operator drove uppercase-V decision on strategic grounds (matches text usage "Vecreal", monogram alignment, institutional positioning, GC vocabulary, AI-startup differentiation, longevity). Locked values: V height 0.56em → 0.72em (cap-height), V-to-e margin -0.07em → -0.13em, dot size 0.18em → 0.22em, dot margin-left 0.04em → calc(0.04em + 2px). Inter Semibold glyph paths and V path geometry unchanged; only scale + spacing + dot size shifted.
- 2026-05-11 SVG viewBox fix: prior versioning bug — viewBox height 1700 ≠ Inter upm 2048 — caused SVG to render ~22% larger than CSS at the same height. Corrected to viewBox -50 -1536 7800 2048 (1em = 2048u). Verified pixel-for-pixel parity with CSS bk-wordmark in the translation-review.html sweep. Operator approval: "Ok looks good. Matches."

---

## Component spec compliance

Per WO-C31 Q5 + work-order-template.yml `component_spec_compliance` schema, any consumer of this wordmark spec emits a per-rule receipt block:

```yaml
component_spec_compliance:
  - spec: projects/vecreal/drafts/brand-atoms/component-library/wordmark.md
    rules:
      - rule_id: wordmark.do.1
        rule_text: Use the V SVG path from reference-design-system.html:1506-1507
        rule_type: do
        compliance_state: pass
        file_evidence: vendor/superset-sh/apps/desktop/src/renderer/components/FactoryShell/FactoryShell.tsx:14-72
      - rule_id: wordmark.dont.2
        rule_text: Do NOT add a separate V monogram element beside the wordmark
        rule_type: dont
        compliance_state: pass
        file_evidence: vendor/superset-sh/apps/desktop/src/renderer/components/FactoryShell/FactoryShell.tsx
      # ... etc
```

DECK_REVIEWER + UIUX_VALIDATION audit wordmark consumption per these rules.

---

## Cross-references

- `assets/wordmark.svg` (production asset)
- `reference-visual-mockups.html` lines 246-298 (CSS spec source)
- `reference-design-system.html` lines 1505-1530 (V SVG markup source)
- `principles.md` (95/5 color discipline; wordmark uses clay accent)
- `design-tokens.json` (--clay-light / --clay-bright / --text-primary / --text-dark-primary / --accent / --accent-bright tokens)
- `iconography.md` (V monogram patterns; this wordmark is the LOCKED bookend variant)
- `WO-C26.3` Gate 3 v2-operator findings F2 (origin of canonical asset authoring)
- `WO-C31` validator-at-every-gate (component_spec_compliance enforcement)
- `runs/wordmark-build/build.py` (deterministic SVG composer; rerun for future Inter version updates)

---

## Lock signature

This spec is LOCKED at rev-2 (amended 2026-05-11). Future amendments require:
- Operator-attestation (Path A operator-only OR Path B substage-discovered + AUDIT signoff)
- Updates to `assets/wordmark.svg` (text-as-paths regeneration only when Inter font version bumps; geometry / scale / spacing changes can be hand-edited directly into the SVG header alongside this spec)
- Cross-reference updates in this doc

Closes brand atom migration gap. Updates `known-gaps.md` to note this gap is now closed.