# `branding.json` — schema `branding/v1`

A single JSON object. All fields are optional except `$schema` (which makes discovery recognize the file).
Unknown keys are allowed and preserved — treat this as an extensible brand record.

```jsonc
{
  "$schema": "branding/v1",          // REQUIRED. Marks the file as branding; other schemas are skipped.

  "name": "Café Aurora",             // brand display name; used in UI and can be woven into prompts

  "voice": "Warm and direct; short sentences; never exclamation marks.",
                                     // one sentence on how the brand WRITES — feed it into any copy you
                                     // generate (emails, posts, web), not just the visuals

  "draft": true,                     // OPTIONAL: set when the brand was PROPOSED by an agent rather than
                                     // gathered from real materials — a later rebrand may replace freely

  "colors": {                        // named colors → referenced by key elsewhere
    "bg": "#0b0b0d",                 //   conventional keys: bg, fg, accent, muted — but any key is fine
    "fg": "#f5f5f0",
    "accent": "#e0483d",
    "muted": "#8a8a82"
  },

  "fonts": {                         // named font roles
    "title": "Söhne",
    "body": "Inter",
    "mono": "Berkeley Mono"
    //  extra roles allowed, e.g. "handwriting": "Caveat"
  },

  "logo": {                          // workspace-relative paths (usually under files/)
    "light": "files/logo-light.svg", // logo for light backgrounds
    "dark": "files/logo-dark.svg"    // logo for dark backgrounds
    //  extra variants allowed, e.g. "mark": "files/logo-mark.svg"
  },

  "video": {                         // defaults for the video/audio editor (mvideo/v1 projects)
    "aspect": "9:16",                // "16:9" | "9:16" | "1:1" | "4:5" | "WIDTHxHEIGHT"
    "titleStyle": { "font": "title", "size": 72, "color": "fg", "weight": 700 },
    "lowerThird": { "font": "body", "size": 36, "color": "fg", "bg": "accent" }
  },

  "styles": {                        // named text/graphic styles → referenced as "brand/<key>"
    "title":   { "font": "title", "size": 72, "color": "fg", "weight": 700, "align": "center" },
    "subtitle":{ "font": "body",  "size": 40, "color": "muted" },
    "caption": { "font": "body",  "size": 32, "color": "muted" }
  }
}
```

## Field notes

| Field | Type | Notes |
|---|---|---|
| `$schema` | string | Must be `"branding/v1"`. Files with a different value are ignored by discovery. |
| `name` | string | Brand name. |
| `colors` | object | `key → CSS color`. Reference by key (`"accent"`), not raw hex, wherever possible. |
| `fonts` | object | `role → font family name`. Common roles: `title`, `body`, `mono`. |
| `logo` | object | `variant → workspace-relative path`. Common variants: `light`, `dark`. |
| `video` | object | Editor defaults. `aspect` sets project dimensions; `titleStyle`/`lowerThird` are style objects. |
| `styles` | object | `name → style object`. A style object references colors/fonts by their keys. Consumed as `brand/<name>`. |

## Style objects

A style object describes text/graphic styling by referencing brand keys so a rebrand cascades:

```json
{ "font": "title", "size": 72, "color": "fg", "weight": 700, "align": "center", "lineHeight": 1.1 }
```

- `font` → a key in `fonts` (falls back to a literal family name if not found).
- `color` / `bg` → a key in `colors` (falls back to a literal CSS color).
- `size` is in project pixels; other keys (`weight`, `align`, `lineHeight`, `letterSpacing`, `case`) are
  passed through to the renderer.

## Validity

- Must be a JSON **object** (not an array or scalar).
- Must parse as JSON. A malformed file is skipped by discovery (the next `branding.json` up wins).
- `$schema`, if present, must equal `branding/v1`. If omitted, the file is still accepted leniently, but
  writing it explicitly is strongly recommended.