# Brand Atoms

Status: draft extraction from the canonical Vecreal HTML design system.  
Canonical visual reference: [reference-design-system.html](reference-design-system.html).

This folder gives AI agents a clean way to use the Vecreal design system without rereading a large HTML file on every UI task. The HTML remains the visual source of truth. The JSON and Markdown files are the short, structured layer for reasoning, implementation, and audit.

## Folder Structure

- [reference-design-system.html](reference-design-system.html) is the canonical visual reference for humans and visual QA. It covers brand identity, tokens, components, construction-domain patterns, composition demos, voice, accessibility, and operating principles.
- [reference-visual-mockups.html](reference-visual-mockups.html) is the companion visual mockup reference when present.
- [design-tokens.json](design-tokens.json) contains the locked token extraction from the first `:root` block plus color, typography, contrast, focus, and breakpoint metadata.
- [component-library/](component-library/) contains short component specs for UI pipeline stages. Each file names anatomy, variants, states, composition rules, do/don't rules, and provenance.
- [principles.md](principles.md), [brand-voice.md](brand-voice.md), [accessibility.md](accessibility.md), [iconography.md](iconography.md), and [known-gaps.md](known-gaps.md) are the cross-cutting reading layer.

## How Agents Should Use This

1. Start with [principles.md](principles.md). When a component detail and a principle disagree, the principle wins (source: section 07 — Design system principles).
2. Use [design-tokens.json](design-tokens.json) for colors, spacing, radii, motion, focus, shadows, typography, and breakpoints before inventing values (source: section 22 — Foundations; section 04 — Color; section 05 — Typography).
3. Use the component Markdown file for structure and behavior, then open [reference-design-system.html](reference-design-system.html) for exact visual fidelity (source: section 50 — Composition demos; section 21 — Design system components).
4. Use [brand-voice.md](brand-voice.md) for product copy. Keep text direct, specific, and calm (source: section 48 — Cross-cutting).
5. Check [known-gaps.md](known-gaps.md) before starting a new surface. If a pattern is listed there, design it explicitly instead of pretending the reference already covers it.

## Scope

These brand atoms live under `projects/vecreal/drafts/brand-atoms/` because the design system applies across Vecreal products, not only Construction PM. They are draft-operational, not foundation-class. UI agents can use them immediately, but owner-curated brand changes can still move faster than foundation policy changes.

## Provenance

These files were moved into this folder during WO-C25 (2026-05-02). The source files were untracked when the move ran, so Git history shows the move as the first commit referencing them.

Amendments are tracked in [CHANGELOG.md](CHANGELOG.md). Most recent: 2026-05-11 wordmark + favicon amendment (uppercase V, larger trailing dot, D-half contained app-icon).

## Hosted at design.vecreal.com (Cloudflare Pages)

This folder is the canonical brand reference and is published to `https://design.vecreal.com/` via Cloudflare Pages. Every push to `main` rebuilds the site automatically — if a locked state appears in this folder on `main`, it's live on the subdomain within ~30 seconds.

**Cloudflare Pages config:**
- Project name: `vecreal-design` (or whatever was used at setup time)
- Connected repository: `vecreal-lab/software-factory`
- Production branch: `main`
- Build command: *(empty)*
- Build output directory: `projects/vecreal/drafts/brand-atoms`
- Root directory: `/` (repository root)
- Custom domain: `design.vecreal.com`
- Framework preset: None

**Entry point:** `index.html` in this folder is the landing page. The major surfaces (`reference-design-system.html`, `reference-visual-mockups.html`, `CHANGELOG.md`) are tile-linked from there.

**No agent action required to deploy.** When the brand-atoms content changes on `main`, Cloudflare rebuilds. If a deploy fails or the site goes stale, check the Pages dashboard build log.