---
name: Branding
description: Use BEFORE creating anything a company puts its name on — websites, landing pages, ad creatives, emails, documents, decks, social posts — and whenever the user asks to set up, change, or scope brand settings. Resolves the nearest branding.json; if none exists, gathers the brand from the user's website and connected accounts, then saves it for every future task.
version: 2
situations: brand kit, brand guidelines, brand colors, fonts, logo, house style, keep it on-brand, workspace branding, per-folder branding, rebrand, website, landing page, ad creatives, email template, newsletter, pitch deck, social post, marketing material
requires-secrets:
requires-packages:
---

# Branding

Brand settings live in a plain JSON file named **`branding.json`**. Any folder in the workspace can hold
one. When a tool needs the brand for a file, it finds the **nearest** `branding.json` by walking up from
that file's folder to the workspace root — the closest valid file wins. This lets one workspace hold
several brands (one per folder) while a workspace-root file is the default for everything else.

## The discovery / override rule

1. Start at the folder of the file being worked on (e.g. the video project, the image, the doc).
2. Look for `branding.json` there. If it's valid, **use it and stop.**
3. If not, move up one folder and look again.
4. Continue up to the workspace root. If nothing valid is found, there is no brand (tools fall back to
   their own defaults).
5. A file that fails to parse, or that declares a different `$schema`, is **skipped** — discovery keeps
   climbing rather than blanking the brand.

**To scope a change, put the file at the right level:**

```
workspace/
  branding.json            ← default brand for the whole workspace
  clients/
    acme/
      branding.json        ← overrides the default for everything under clients/acme/
      spot.mvideo.json     ← uses clients/acme/branding.json
    globex/
      promo.mvideo.json    ← no local file → uses workspace/branding.json
```

- Change the workspace-wide brand → edit the **root** `branding.json`.
- Give one client/project its own brand → create a `branding.json` **in that folder**.
- Nearest-wins is strict: a nested file **replaces** the ancestor, it does not merge with it. If you want
  a nested folder to keep most of the root brand, copy the root file down and edit the few keys you need.

## Creating or editing a brand

Write a `branding.json` following the schema in [reference/branding-schema.md](reference/branding-schema.md).
Always include `"$schema": "branding/v1"` so discovery recognizes it.

Minimal example:

```json
{
  "$schema": "branding/v1",
  "name": "Café Aurora",
  "colors": { "bg": "#0b0b0d", "fg": "#f5f5f0", "accent": "#e0483d", "muted": "#8a8a82" },
  "fonts": { "title": "Söhne", "body": "Inter", "mono": "Berkeley Mono" },
  "logo": { "light": "files/logo-light.svg", "dark": "files/logo-dark.svg" },
  "video": { "aspect": "9:16" },
  "styles": {
    "title": { "font": "title", "size": 72, "color": "fg", "weight": 700 },
    "caption": { "font": "body", "size": 32, "color": "muted" }
  }
}
```

## Referencing the brand

- **Colors/fonts:** reference by key (`"accent"`, `"title"`) rather than hardcoding hex/font names, so a
  rebrand updates everything at once.
- **Named styles:** other tools reference a style as `brand/<key>` — e.g. a video timeline text clip with
  `"style": "brand/title"` resolves against `styles.title` of the discovered brand.
- **Logos & other assets:** store as workspace-relative paths (usually under `files/`).

## Before creating ANYTHING branded

Websites, ad creatives, emails, documents, decks, social posts — anything a company or project puts its
name on. **Resolve the brand first, create second**: work produced off-brand gets thrown away and redone.

1. Resolve the nearest `branding.json` for the folder you're working in. Found one → use it, done.
2. None found → **gather one now** (below), then create the work with it. Don't ask the user to pick
   colors mid-task; gather once, save, and every future task inherits it.

## Gathering a brand from what already exists

The user almost always HAS a brand — on their website, their social profiles, their past materials. The
job is to collect it, not to make them dictate hex codes. Use everything already available before asking:

1. **Check what you already know.** Search the workspace for existing assets (logos under `files/`,
   colors in past projects, an old `branding.json` in another folder) and MEMORY.md for the company
   name/site. If Overblast is connected, call `overblast_status` — connected Instagram/Facebook/webchat
   accounts mean bios, handles and avatars you can name back to the user without asking.
2. **Ask ONE round of questions** with a \`\`\`00-ask block, prefilled with anything found in step 1:
   - the company/project website URL (or "none yet"),
   - social profiles worth pulling from (prefill from overblast_status when connected),
   - whether this brand is for EVERYTHING (workspace root) or one project/client (that folder),
   - anything non-negotiable (an exact hex, a mandated font).
3. **Pull the brand from the website** (needs the internet capability — ask to enable it if off):
   fetch the homepage, extract the palette (theme-color meta, CSS variables, dominant colors), the
   font families actually used, the logo URL (og:image / header img / favicon at worst), and the TONE —
   how they write, in one sentence. Save the logo into `files/`.
4. **Write `branding.json`** at the scope from step 2 (root for the default brand, the project folder
   for a client brand — the discovery rule above). Include `"$schema": "branding/v1"`, the extracted
   colors/fonts/logo, and put the tone sentence in a `"voice"` field so written material stays on-brand
   too.
5. **Show, don't list**: confirm with a one-line summary and a small swatch (generate a quick image of
   the palette + font names if media is available), and say where the file lives and how to change it.
   Then proceed with the ORIGINAL task using the new brand.

If the user genuinely has no brand yet, propose one (palette + font pairing + tone) from what the
project is, write it as a DRAFT brand, and mark it `"draft": true` so a later rebrand knows nothing
downstream is sacred.

## When asked to "keep it on-brand"

1. Resolve the brand for the folder you're working in (nearest `branding.json`).
2. If none exists, run the gathering flow above rather than guessing.
3. Feed the brand's colors/fonts/logo/styles into whatever you generate (images, video projects, docs),
   and its `voice` into whatever you write.