---
name: reframe-brand
description: Use when the user mentions a brand name (Stripe, Linear, Airbnb, Vercel, Ferrari, Notion, Apple, GitHub, etc.), says "apply brand" / "rebrand" / "use X's style" / "make it feel like Y", OR the active scene has no DESIGN.md yet and you're about to write HTML. This skill carries brand-translation knowledge — how brand intent (vibe, not palette) becomes scene tokens, where brand fidelity usually drops, and the smells that mean "swapped colors, forgot everything else".
allowed-tools:
  - "mcp__reframe__reframe_design"
  - "mcp__reframe__reframe_edit"
  - "mcp__reframe__reframe_inspect"
  - "Read"
bus-context-types:
  - brand-load
  - brand-edit
  - brand-extract
bus-result-kinds:
  - edit-result
  - design-result
bus-streaming: false
---

# reframe-brand

**You are a brand engineer translating identity into tokens.** A brand is not a hex palette — it's weight, corners, motion, type voice, whitespace discipline, the whole pattern. The engine tokenizes whatever you hand it; your job is to make sure what you hand it is the full brand, not its color chip.

The `reframe_design` tool (action=`extract`) pulls 300+ line DESIGN.md files from the getdesign npm catalog (60+ brands cached in `.reframe/brands/<slug>/`). The scene's `brandFidelity` score measures how well its fills, typography, and component specs match those values. Your job is to **carry the brand fully** so that score stays high, not to guess colors from memory.

## DESIGN.md is the etalon — you walk it, you don't invent

DESIGN.md was designed as a **deterministic reference** so brand work is traversable, not guessed. The getdesign catalog parses a brand into 300+ lines of concrete values (hex, fonts, weights, OpenType tags, radii, shadows, button specs, motion). Once a DESIGN.md is loaded, every field in the compiled scene must trace back to a line in it. **If DESIGN.md doesn't say it, you don't decide it** — you surface the absence.

This is the skill's core discipline. The smells below are all species of the same failure: the scene silently diverged from DESIGN.md, either because a field was dropped in transit or because the skill invented where DESIGN.md was silent.

## The parse pipeline — DESIGN.md is prose; the audit reads a typed object

DESIGN.md is human-readable Markdown. The audit is machine code. The bridge is a **deterministic parser** at [packages/core/src/design-system/parser.ts](packages/core/src/design-system/parser.ts) that walks the 9-section standard (awesome-design-md format) and produces a typed [`DesignSystem`](packages/core/src/design-system/types.ts) object:

```
.reframe/brands/<slug>/DESIGN.md              (prose, 300+ lines)
        │
        ▼    packages/core/src/design-system/parser.ts  (regex + section markers — no LLM)
        ▼
DesignSystem { typography, colors, components, layout, depth, responsive }
        │
        ▼
brandFidelity audit checks scene fills/fonts/radii AGAINST this typed object
```

The 9 sections the parser expects:
1. Visual Theme & Atmosphere
2. Color Palette & Roles
3. Typography Rules
4. Component Stylings
5. Layout Principles
6. Depth & Elevation
7. Do's and Don'ts
8. Responsive Behavior
9. Agent Prompt Guide

**What the parser currently captures** (audit checks this):
- **Typography per role** — hero / title / subtitle / body / caption / disclaimer / button — with fontSize, fontWeight, lineHeight, letterSpacing, textTransform, **OpenType features** (`ss01`, `tnum`, `cv01`, …), and per-breakpoint overrides
- **Colors** — primary / background / text / accent + full role map + gradients
- **Components** — Button variants (style / states / shadow / radius), Card / Badge / Input / Nav specs
- **Layout** — spacing scale, grid, container widths
- **Depth** — shadow layers per elevation tier
- **Responsive breakpoints** — mobile / tablet / desktop overrides

**What is NOT captured** (blind spots the audit cannot check — handle manually):
- **Motion / timing / easing** — HTML doesn't express animation, and the parser currently drops motion specs. Flag as non-goal for static scenes.
- **Voice / tone / copy guidelines** — semantic, not structural; the audit is content-blind.
- **Philosophy prose** (Section 1) — mood and atmosphere read as guidance but don't parametrize the audit.
- **Interaction micro-behavior** — hover cursor changes, focus-ring details beyond the `InteractiveState` fields.

### Debugging when a DESIGN.md field "doesn't count"

If you see a value clearly written in `.reframe/brands/<slug>/DESIGN.md` but `brandFidelity` doesn't penalize its absence in the scene, **the parser probably dropped it**. Check in this order:

1. **Section heading mismatch** — parser splits on `## N. Title` and matches keywords. If a brand's DESIGN.md uses a non-standard section name ("## Colours" vs "## Color Palette"), the section is skipped. Fix: rename the section or extend `findSection` keywords in `parser.ts`.
2. **Value format mismatch** — parser uses regex for hex, rgb, px values. A color written as `oklch(…)` or `hsl(…)` currently slips past the hex extractor. Fix: add the format to the extractor in `parser.ts`.
3. **Field not in `types.ts`** — if DESIGN.md mentions a field the `DesignSystem` type doesn't model (e.g. detailed motion specs), the parser has nowhere to put it. Fix: extend `types.ts` + parser + audit together.

When you catch a parser gap, the bug is in `packages/core/src/design-system/` — not in this skill. Log it, propose the fix, don't work around it by editing the DESIGN.md locally (that breaks other users of the same brand).

### Auto-diff as you go — catch parser drift AND FIX IT without being asked

**The skill's job is to enrich the etalon.** DESIGN.md → parsed `DesignSystem` is the deterministic spine that drives every brandFidelity judgment in the app. Every brand load is an opportunity to tighten that spine. When you catch a mismatch, the default is **fix the parser, not report it** — the skill improves the etalon as a side effect of normal work, and every session leaves the system slightly better calibrated.

This is the inverse of a "bug report" protocol. You don't queue drift for later; you close it now.

**Protocol — run every time you load a brand:**

1. After `reframe_design action=extract brand=<slug>`, `Read .reframe/brands/<slug>/DESIGN.md` and note the **concrete values** in the 9 sections that matter for this scene — hex codes, font weights, radii, button height/padding, shadows, OpenType tags.
2. Call `reframe_inspect` (or read the in-memory DesignSystem) and compare against the parsed fields.
3. Walk the comparison with this smell-list:
   - **Typography role present in prose, absent from `typography[role]`** → section-name mismatch or role keyword missing from parser's allowlist
   - **OpenType tag listed in DESIGN.md, empty `fontFeatures[]`** → regex didn't match the tag notation (`'ss01'` vs `ss01` vs `"ss01"`)
   - **Color written as `oklch(…)` / `hsl(…)` / CSS var, missing from `colors.roles`** → extractor is hex+rgb only
   - **Component spec (Card, Badge, Input, Nav) in prose but `components.<name>` undefined** → subsection keyword miss
   - **Per-breakpoint override described ("mobile: 32px") but `typographyBreakpoints[]` empty** → responsive parser didn't link role × breakpoint
   - **Motion / easing described but no field to hold it** → known `types.ts` gap, NOT a parser bug; flag for the user as "worth modeling?" (architectural decision, not a drop-in fix)
4. **Default action: patch the parser.** For every drift that has an obvious mechanical fix (keyword expansion, regex extension, extractor addition), immediately:
   - Read the relevant section of `packages/core/src/design-system/parser.ts` (or `types.ts` if a new field on the model is needed)
   - Apply a minimal edit — ideally ≤ 10 lines total
   - Re-run `reframe_design extract` on the same brand to confirm the field now parses
   - Add a row to the smell table documenting the drift + the parser change that closed it
   - Tell the user in one sentence what you found and fixed. Don't ask permission for small mechanical patches — patch, verify, move on.
5. **Escalate, don't patch, when:** the fix requires a new `types.ts` field (architectural change that ripples to audit + exporter), the fix would touch more than ~20 lines, the parser change could break another brand already passing, or you can't verify with the currently-loaded brand alone. In those cases: report the drift, propose the fix, wait for the user.
6. **Never edit the DESIGN.md to hide the symptom** — it masks the bug for every other user of that brand. The DESIGN.md is the etalon; the parser catches up to it, not the other way around.

**Why this matters.** The parser is deterministic but the brand catalog evolves — getdesign updates a brand upstream, new brands are added, someone writes `oklch(…)` for the first time. Without this protocol, gaps sit silent for months: fidelity reports 0.92, scene looks "close enough", user never finds out the brand's accent is `oklch(0.65 0.3 250)` and not the fallback `#0071e3`. The skill is the only layer comparing prose against types — be that layer actively, not passively.

**Budget.** A drift scan on a previously-verified brand is < 15 s. A mechanical parser patch is < 5 min. If a single brand load routinely triggers 30 min of parser work, compress — keep a per-brand `verified on <date> / parser hash <X>` note in the smell table and skip re-scan unless the hash changed. The goal is a self-improving system, not a QA loop that blocks every design task.

**Catalog-wide runs are NOT this skill's job.** When the user asks "audit all 60+ brands" / "harden the parser against the whole catalog", that's multi-state orchestrator work, not specialist work — the orchestrator (see `CLAUDE.md § Orchestration → Parallel fix-in-bucket`) drives the parallel-bucket shape and calls this skill's single-brand Auto-diff protocol per bucket. Don't re-implement the parallel machinery here.

## Carrier contract — DESIGN.md → compiled scene

Ten load-bearing axes that MUST flow from DESIGN.md into the rendered scene. Each has a known drop-path (the common way fidelity is lost in transit) and a verification probe. Walk this contract before declaring a brand "applied".

| Axis | Where in DESIGN.md | Common drop | Verification |
|---|---|---|---|
| **1. Palette roles** (primary, secondary, semantic, neutrals) | Colors § | Hex hardcoded into scene, not bound to tokens → `brandFidelity` tanks on later edit | `reframe_inspect` → check `meta.tokenBindings.fill` set on fills |
| **2. Type family** (primary + mono) | Typography § | Missing Google Fonts `<link>` → browser falls back to Inter silently | First text node's computed `fontFamily` == DESIGN.md primary |
| **3. Weight ladder** (e.g. 400 / 510 / 590 / 700) | Typography.weights | Collapsed to 400/700 because the intermediate weights felt "too much" | Count distinct `fontWeight` values across scene ≥ ladder size |
| **4. OpenType features** (ss01, tnum, cv11, …) | Typography.font-feature-settings | NOT applied to every text node (most-forgotten detail) | `probe selector:* all:true` check any non-`normal` `font-feature-settings` |
| **5. Corner scale** (cards vs buttons vs pills have different radii) | Radius § / components.*.radius | Every container gets same radius → corner inflation | `cornerRadius` stdev across frames > 0; cards ≠ buttons ≠ pills |
| **6. Shadow scale** (elevation tiers) | Shadows § | Every card gets the same shadow, or all shadows stripped (flat) | Distinct shadow intensities used; primary emphasis has stronger shadow |
| **7. Button spec** (height, paddingX, radius, weight) | components.button | 36 × 12 defaults because audit wasn't checked | Every button/CTA matches DESIGN.md `minHeight` + `paddingX` + `radius` |
| **8. Spacing rhythm** (4/8/12/16 scale or brand-specific) | Spacing § / layout.grid | Ad-hoc px values (11, 13, 17) because the unit wasn't adopted | All padding/gap values are multiples of brand spacing unit |
| **9. Single-accent discipline** | Colors.accent | 3+ high-saturation accents creep in because the code eats colors freely | Count fills with saturation > 0.65; group by hue; should be ≤ 1 primary + 1 secondary |
| **10. Voice / tone** (when DESIGN.md specifies it) | Voice § / Copy guidelines | Generic AI-gen copy overrides brand voice — Stripe's precise prose becomes marketing-speak | Read copy voice vs DESIGN.md Voice section; mismatch = silent drift |

**Rule:** before calling `reframe_inspect brandFidelity`, re-walk this table on the compiled scene. Fidelity score tells you how bad it is; the contract tells you which axis broke.

## Vocalise the brand before writing — one sentence the user can redirect cheaply

After `reframe_design action=extract brand=<slug>` lands and you've Read the cached `.reframe/brands/<slug>/DESIGN.md`, **before any HTML or `reframe_compile` call**, state the system you'll bind в **one sentence**: the dominant background, the single accent (with hex), the display + body type pairing, and the load-bearing posture rule (corner scale / shadow philosophy / accent budget).

Examples of correct vocalise:

- "Warm cream background `#fdf3e8`, single terracotta accent `#cf6a5f`, Tiempos Headline display + Söhne body, gentle 14px radii on cards." (warm-soft)
- "Off-white `#f9f4ec` paper, single warm rust `#c64e31` accent used at most twice, Iowan Old Style display + system sans body, hairline borders + 0px radii — no shadows ever." (editorial-monocle)
- "Stripe — `#0a2540` near-black surface, `#635bff` purple primary accent + `#00d4ff` cyan secondary, Sohne-Var weight ladder 400/510/590/700, 8px button radius, soft 0 1px 3px elevation tier." (Stripe brand load)

Why: the user reads the sentence and either says "yes, build" or "no — make the accent rust not blue" before you've spent 30 seconds writing HTML. A wrong direction caught at vocalise is 10× cheaper than one caught after compile + inspect + critic. The vocalise sentence is also the first thing `reframe-critic` cites when judging brand fidelity post-compile — so it's not just a checkpoint, it's the contract you're binding against.

**Rule:** vocalise once per brand load. Don't vocalise on every edit; once the user accepts the system, it's locked until they ask to rebrand.

**When to skip vocalise:** the user explicitly says "skip the recap, just build" / "I know the brand, go" / they're в the middle of an iteration (mid-edit on already-vocalised scene). Otherwise — even on quick scenes — vocalise. The sentence is small; the redirect-cost it saves is large.

## When DESIGN.md is silent — don't fill it

The getdesign catalog varies:

- **Thorough brands** (Stripe, Linear, Airbnb, Vercel, Apple) — 300+ lines, every axis covered. Walk the contract, trust each field.
- **Thin brands** (smaller or newer) — 100–150 lines, often missing motion, OpenType, component specs (button/card/input), spacing scale.

When an axis is absent from DESIGN.md, the only correct moves:

1. **Surface the absence** to the user in plain language — "DESIGN.md doesn't specify button radius; pick 8 px or extend the file?"
2. **Edit the DESIGN.md** (it's a file on disk at `.reframe/brands/<slug>/DESIGN.md`) if the user gives you a value — persist for the next session.
3. **Mark the scene as partial-fidelity** so `reframe-critic` doesn't penalize an axis DESIGN.md never defined.

Never fill from memory. "Stripe's button radius is 8 px" sounds confident but is exactly the kind of invention DESIGN.md exists to prevent.

## Smell table — brand fidelity regressions

| Smell | Means | Probe | Fix |
|---|---|---|---|
| `#635bff` hardcoded, no token | Stripe color used as literal, not via `color.primary` | Grep compiled HTML for exact brand hex; check if `meta.tokenBindings.fill` is set | `reframe_edit` autoBindTokens or re-tokenize via `defineTokens` |
| No `font-feature-settings` in any text node | OpenType features dropped | `probe selector: '*'` all=true, check any computedStyle has non-`normal` font-feature | Re-read DESIGN.md OpenType section, re-compile with features on each text element |
| Scene uses `Inter` but brand is Söhne/Geist/Cabinet | Wrong type family for brand | First text node's `fontFamily` vs DESIGN.md Typography.primary | Swap fontFamily, load Google Font via link or note self-host requirement |
| 3+ high-saturation accents in one scene | Brand drift — single-accent rule broken | Count SOLID fills with saturation > 0.65; group by hue bucket | Demote extras to muted variants or token them as `color.muted-*` |
| All buttons `height: 36px` but brand spec says 48 | Minimum height regression | Walk button/CTA nodes, compare height to DESIGN.md `components.button.minHeight` | `reframe_edit update height: 48` on affected nodes |
| `brandFidelity` dropped below 0.80 after edit | Edit undid tokenization | Run `reframe_inspect` → compare `brandFidelity` before vs after | `autoBindTokens` pass then re-check |
| All corner radii identical | Corner inflation, brand has scale | `cornerRadius` stdev across frames == 0 | Apply per-semantic: cards from `radius.md`, buttons from `button.radius`, pills 9999 |
| Brand dark but scene has `#000` backgrounds | Wrong black — brand specifies `#0a0a0f` etc. | Grep `#000000` in fills | Replace with brand-specific dark (check DESIGN.md Colors.background) |
| Extract returns "Could not load" / timeouts | npm registry unreachable OR slug misspelled | Check `.reframe/brands/<slug>/` exists; try `action: "list"` | If offline: use cached brands only; if slug wrong: fuzzy-match from catalog |

## Canonical flows

- **Apply brand to a new scene** — `reframe_design action=extract brand=<slug>` → Read `.reframe/brands/<slug>/DESIGN.md` → write HTML with the loaded values → `reframe_compile` → check `brandFidelity`
- **Rebrand in place (keep structure, swap tokens)** — `reframe_design action=extract brand=<new-slug>` → `reframe_edit defineTokens` with new brand tokens + `rebrand: true` flag → re-inspect `brandFidelity`
- **Theme mode toggle (light↔dark within same brand)** — `reframe_edit setMode` — no re-extract needed if tokens already defined
- **Custom brand (user has spec)** — Write DESIGN.md manually to `.reframe/brands/<slug>/DESIGN.md`, then apply via tokenize + autoBind
- **Fuzzy reference** — user says "make it feel like GitHub" → `reframe_design action=list search=github` → pick slug → extract

## Anti-patterns

- **Swapping just the background color and calling it "rebranded"** — brand = palette + typography + corners + shadows + motion. If only bg changed, you did color work, not brand work.
- **Generating HTML before loading DESIGN.md** — the engine can't infer brand from a slug. Read first or decline brand-fidelity critique.
- **Mixing brands in one scene** — Stripe's type with Linear's colors = a slop chimera. One brand per scene (or use `reframe_edit rotateColors` for variation, not cross-brand mixing).
- **Filling missing DESIGN.md fields from memory** — DESIGN.md doesn't mention Stripe's exact letter-spacing? Don't guess from recall. Say the field is missing.
- **Regenerating HTML for a rebrand** — rebrand is a token swap (setMode/defineTokens). Regeneration destroys the user's layout for no gain.

## Tools to reach for

- `reframe_design action=extract brand=<slug>` — pull DESIGN.md + cache it in `.reframe/brands/<slug>/`
- `reframe_design action=list [search=X]` — browse 60+ brands, filter by keyword
- `Read .reframe/brands/<slug>/DESIGN.md` — ALWAYS read after extract before any HTML work
- `reframe_edit defineTokens` — tokenize scene colors/type/spacing from DESIGN.md values
- `reframe_edit autoBindTokens` — bind raw fills to the matching tokens after the fact
- `reframe_edit rebrand` (or defineTokens with `rebrand: true`) — swap active brand without regenerating
- `reframe_edit setMode` — switch light↔dark within the same token collection
- `reframe_inspect` — read `brandFidelity` score (0–1) + see which nodes carry token bindings

## Gotchas

- **Catalog timeout offline** — `action: list` spawns `npx getdesign` which needs network. If `ETIMEDOUT`, fall back to `.reframe/brands/` cache contents.
- **DESIGN.md completeness varies** — some brands have exhaustive specs (Stripe, Linear); others are thin (smaller brands). If thin, surface that to the user before generating — don't overcommit.
- **Brand palette roles differ** — `primary` in one brand is a CTA color, in another it's a background anchor. Read the DESIGN.md's intent line, not the hex.
- **First extract is network + parse (~3–5s)**; subsequent loads are local (cached in `.reframe/brands/`). Once cached, re-extracts are only needed when the brand itself changed upstream.
- **`brandFidelity` is 0.0 when no brand is loaded** — not a failure; just means the scene has no brand context. Only treat `brandFidelity` < 0.6 as a regression when a brand IS active.

## When NOT to use this skill

- User says "something minimal" / "modern" / "clean" with no brand name → this is a **mood**, not a brand. Route to `reframe-design` with the adjective embedded.
- User wants to design from scratch without brand ("make a landing page, no specific brand") → go straight to `reframe-design` with `brandFidelity` ignored.
- User asks for multi-page site with one brand → `reframe-site-loop` freezes brand on turn 1; you come back to load DESIGN.md once, then step aside.

## Growing the smell table

When you catch a brand drift pattern a future session would miss:

1. Name the signature ("type weight ladder collapsed", "single-accent rule broken")
2. Write the probe (grep / brandFidelity delta / token binding check)
3. Write the fix
4. Add a row

A brand skill that knows 20 common drift patterns is worth more than a brand skill that re-discovers them each session.