---
name: brand-design
description: Use when a website URL needs to be turned into a brand-design package — a directory containing a tokenized DESIGN.md, light and dark logo files sourced from the site, and a description.md with company copy plus registered company details. Trigger phrases include "extract brand from <url>", "build a brand pack from <site>", "tokenize <site> design", "scrape brand assets", or any request that names a live URL and asks for design tokens, logos, and company description together.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - WebFetch
---

# brand-design

Turn one publicly-accessible website URL into a self-contained brand-design directory that downstream design, marketing, and document-generation skills can consume without re-visiting the source site.

The output shape is a brand workspace at `<brand_dir>/` containing the four artifacts defined in **Outcome contract** below. The contract is the format; any prior conforming brand pack on disk may be inspected as a reference, but no specific location is required.

## Outcome contract

The skill is **complete** when the target directory contains exactly these four artifacts at its root:

```
<output-dir>/
  DESIGN.md                  # tokenized design system, observed values
  <slug>-logo-light.png      # the light-coloured logo art (white/cream/pale pixels) — for placing on dark surfaces
  <slug>-logo-dark.png       # the dark-coloured logo art (black/navy/charcoal pixels) — for placing on light surfaces
  description.md             # company copy + official registration details
```

`<slug>` is the lowercase, hyphen-separated brand name — derived from the brand's own name, not its FQDN (e.g. `<brand>`, not `<brand>realestate.co.uk`). The slug is reused as the directory name unless the caller specifies otherwise — that is, the brand workspace is `<output-dir>/<slug>/` and these four files live at its root.

A sibling `properties/` directory may also be present at `<output-dir>/properties/` — it belongs to `property-extract` and **must not** be touched by this skill. Working files this skill creates (screenshots, intermediate JSON, snapshot dumps) must be cleaned up before reporting completion. The four artifacts above are the deliverable; nothing else this skill writes is "scratch" that survives.

## Inputs

Required: a URL. If only a brand name is given, decline and ask for the URL — there is no reliable way to disambiguate brand without the source of truth.

Optional: an output directory path. Default: `./<slug>/` in the caller's current working directory.

## Scope boundaries

| In scope | Out of scope |
|---|---|
| Public HTML/CSS sites renderable in a headless browser | Login-gated sites, paywalled content |
| Brand colour, type, spacing, motion, radius, shadow, layout tokens | Editorial/component-level patterns (defer to `design-systems:component-spec`) |
| Header logo, footer logo, favicon | Photography, iconography sets, illustrations |
| Company copy from Home + About + Footer + Contact pages | Blog content, case studies, full marketing copy library |
| UK Companies House-style registration details when present in the footer or `/legal`, `/terms`, `/privacy`, `/imprint` | Hunting for company details outside the site (no Companies House lookups, no LinkedIn) |
| Light + dark logos as the site itself ships them | Generating brand variants the brand has not authored — but a recoloured fallback is permitted with explicit provenance, see **Logo authenticity** |

If the site is JS-only and the headless browser cannot render it, stop and report `STATUS: BLOCKED` with the symptom — do not synthesise tokens from a blank page.

## Artifact contracts

### `DESIGN.md`

A three-tier (primitive → semantic → component) token spec produced from **observed computed styles**, not from CSS source guesses. Every value in tier 1 must be backed by a measurement at a real viewport.

The contract for this file is owned by `design-systems:tokenize`. Invoke that skill against the target URL and write its output to `<output-dir>/DESIGN.md`. Do not re-derive tokens here.

What the file must contain regardless of who generated it:

- A header noting the source URL and the date the tokens were captured.
- Inventory & method paragraph stating viewports inspected and how counts were obtained.
- Tier 1 primitives for: colour, alpha/scrim, typography (family, weights, size scale at desktop **and** mobile, line-height, letter-spacing), spacing, radius, shadow, motion, layout, breakpoints. Each row carries the observed count or `(proposed)` if the value is being introduced rather than extracted.
- Tier 2 semantic role mappings (text, surface, action, border, typography roles, spacing roles, motion roles).
- Tier 3 component tokens for at least: primary button, text input, card, hero, footer, header, banded section.
- A **Theme Mapping** section with the as-built theme **and** a proposed dark-theme block. Mark the dark theme as proposed if the site does not ship one.
- A **Divergences** block calling out every place the captured value disagrees with prior assumed/inherited token docs (if any) — wording: "Prior assumption / Actual live behaviour".
- A migration guide: ordered find/replace from raw values to tokens, plus behaviours-to-correct table.

The naming convention is `--ds-{category}-{property}-{variant}-{state}` unless the site already ships a brand-prefixed convention, in which case adopt the existing prefix and note it.

#### Optional: `## Type roles` block (for branded brochures)

When the brand is the source for a property brochure run, the `property-brochure` skill's branded register applies the DESIGN.md's palette and font tokens automatically. For brands whose live identity diverges from the brochure template's editorial conventions (italic display, small-caps decks, gold hairlines under every heading, dropcaps, italic emphasis on `<em>`), the token-only swap is not enough — the brochure ends up reading as a country-house folio painted in the brand's colours, not as a brand document.

To close that, declare an optional `## Type roles` block in the DESIGN.md. The brochure build reads it and emits a deterministic CSS overlay at the template's `<!-- BRAND_TYPE_ROLES_OVERRIDE_SLOT -->` sentinel. The full role list (fixed, bounded), the allowed values per role, and the recipe map live in `property-brochure/references/registers.md → Type-role overrides` and `property-brochure/references/build.md → Type-role overlay generation`.

Format — one role per line, `role: value`, or a Markdown table:

```markdown
## Type roles

| Role | Value |
|---|---|
| `display-headline-style` | `normal` |
| `display-em-style` | `italic` |
| `display-letterspacing` | `medium` |
| `deck-family` | `sans` |
| `deck-case` | `sentence` |
| `subtitle-family` | `sans-tracked-caps` |
| `caption-family` | `sans` |
| `caption-em-style` | `weight-shift` |
| `dropcap` | `hidden` |
| `hairline-rules` | `eyebrow-only` |
| `body-em-style` | `weight-shift` |
| `folio-em-style` | `weight-shift` |
| `backpage-em-style` | `weight-shift` |
```

Omitted roles inherit the template default. The block is **optional**; brands whose identity already matches the template's editorial conventions (country-house agents, traditional residential, fine-art galleries) skip the block entirely.

How to decide which values to set, given the brand audit you've already done:

| Observation on the live site | Maps to role |
|---|---|
| Display headlines render upright (no `font-style: italic`) | `display-headline-style: normal` |
| Display family is a humanist sans (Montserrat, Inter, Söhne) | `display-letterspacing: medium` |
| Display family is a geometric/grotesque sans (Helvetica, Roboto Mono) | `display-letterspacing: tight` |
| The display family is a serif with an italic cut (Playfair Display, Cormorant Garamond, Lora, EB Garamond, etc.) AND the site visibly uses italic emphasis on em runs | `display-em-style: italic` (affirmative — emits no override; the template's natural italic is what the brand wants). DO NOT set `weight-shift` or `normal` for these brands; both destroy the natural italic and ship a flattened, sans-looking emphasis style. |
| The site never italicises anything (display family is a sans, or visibly suppresses italic) | `display-em-style`, `body-em-style`, `caption-em-style`, `folio-em-style`, `backpage-em-style` → `weight-shift` (preferred) or `normal` |
| All body running text is sans-serif | `deck-family: sans`, `caption-family: sans` |
| Captions and labels share the body family | `caption-family: sans` |
| No dropcaps anywhere on the site | `dropcap: hidden` |
| Site uses bold sans for initial-cap accents (e.g. magazine-style hero pull-letters) | `dropcap: ink-bold-sans` |
| Decorative gold/accent rules appear only beside small labels, not under headings | `hairline-rules: eyebrow-only` (or `hidden` if no rules at all) |
| Subtitles use letter-spaced uppercase sans | `subtitle-family: sans-tracked-caps` |

If the brand's identity has no observable signal either way for a role, leave it omitted — the template default applies.


### `<slug>-logo-light.png` and `<slug>-logo-dark.png`

Two PNGs of the wordmark/lockup as the brand uses it. **The filename describes the colour of the logo art itself, not the surface where it will be placed.** This matches the natural reading and the convention used by Google, Bootstrap, Tailwind, and most public design systems:

| Filename | Art colour | Place it on |
|---|---|---|
| `<slug>-logo-light.png` | light/white/cream/pale pixels | dark surfaces (back-page hero, dark masthead) |
| `<slug>-logo-dark.png` | dark/black/navy/charcoal pixels | light surfaces (TOC, index.html nav, paper backgrounds) |

So if you open `donnavincent-logo-light.png` and see white text, that is correct — it's the light-coloured variant. If you open `donnavincent-logo-dark.png` and see white text, the file was misnamed by an earlier run; rename it.

Acceptance criteria:

- File format: PNG with alpha. Even if the source is SVG, also write a rasterised PNG at 2× the rendered header height for downstream document-generation skills that don't accept SVG.
- `<slug>-logo-light.png` (light-coloured art) must render crisply against a dark/ink target surface. `<slug>-logo-dark.png` (dark-coloured art) must render crisply against a paper/white target surface. **Verify by opening the file:** light-art file should look almost invisible against a white IDE background; dark-art file should look almost invisible against a dark IDE background. If either is "invisible against the wrong surface," the file is right; if either is invisible against the *correct* surface, the names are swapped.
- No surrounding chrome. The crop is the logo itself plus the brand's intended whitespace — not a slice of the navigation bar.
- Aspect ratio matches the source. Do not stretch.

#### Logo authenticity

Provenance must be honest. The two acceptable origins, in priority order:

1. **Authored** — the brand ships two distinct logo files (one in each colour register). Use both verbatim from their `<img src>` URLs (or inline SVG, rasterised). This is the only origin that may be silently saved.
2. **Recoloured derivative** — the brand ships only one logo. The second file is generated by recolouring (typically inverting fill from `--ds-color-ink-900` to `--ds-color-paper-0`, or vice versa). When this happens:
   - Append a single line at the bottom of `description.md` under a `## Asset notes` heading: `<slug>-logo-light.png is a recoloured derivative — the source site ships one dark-coloured logo only.` (Or vice versa, whichever was synthesised.)
   - Do not invent shape changes, glows, or stroke variants. Only fill colour may be inverted.

A photographic crop of the logo from a screenshot is **not** acceptable — the result has anti-aliased edges against a non-transparent background. Always pull the asset from `<img src>` / `<svg>` and rasterise on a transparent canvas.

### `description.md`

Plain Markdown, no frontmatter. Structure:

1. Brand name on its own line.
2. The brand's own tagline / one-liner from the homepage hero.
3. Vision / "about us" paragraph(s) verbatim from the homepage and About page. Keep paragraph breaks. Do not paraphrase.
4. Service-area or coverage paragraph if the brand has one (common for property, legal, healthcare, trades).
5. A short list of value-prop bullets if the homepage uses them (e.g. "Personal Service / Transparent Communication / …"). Keep them as a flat list, one per line, no bullet character.
6. The closing call-to-action paragraph from the homepage or contact page.
7. Brand name again as a divider.
8. **Official details block** — extracted from the footer, terms, privacy, or imprint page. Each on its own line, label first:
   - `Registered Office: …`
   - `Registered Company Number: …` (UK) or `Company Registration Number: …` (other)
   - `VAT Registration Number: …` (if shown)
   - Any regulator-issued numbers shown publicly (FCA, ICO, RICS, ARLA, Bar Council, etc.)
9. The source URL on the final line.

Capture rules:

- **Verbatim** — preserve the brand's punctuation, capitalisation, and Oxford comma habits. This file is the source of truth for downstream brochures, decks, and emails; paraphrasing introduces drift.
- If a section is missing from the site, omit it. Do not invent placeholders.
- If the company is non-UK, replace UK-specific labels with the local equivalents (`Handelsregister`, `SIRET`, `EIN`, `ABN`, etc.) — but only if those labels appear on the site.
- Do not include phone numbers, email addresses, or contact form URLs unless they appear in the official-details footer block. Marketing contact details belong in a separate brand asset, not this file.

## How tokens, logos, and copy fit together

These three artifacts are not independent — they cross-reference:

- `description.md`'s "Asset notes" line records when `*-light.png` or `*-dark.png` was synthesised rather than authored.
- `DESIGN.md`'s ink and paper primitives are the colours used to fill any synthesised logo variant. `*-logo-light.png` (light-coloured art) takes its fill from `--ds-color-paper-0`. `*-logo-dark.png` (dark-coloured art) takes its fill from `--ds-color-ink-900`.
- `DESIGN.md`'s `--ds-color-action-primary-bg` is usually the same accent that appears in the brand's logo. A mismatch is a useful sanity check — if they disagree, re-inspect the logo source.

After all three artifacts are written, do a final consistency pass: open each file and confirm the cross-references are consistent.

## Process — high level

The skill orchestrates three smaller capabilities and a final assembly. Each is a **what**, not a **how**:

1. **Tokenize.** Drive `design-systems:tokenize` (or its equivalent) against the URL at desktop (1440×900) and mobile (500×700) viewports. Output → `DESIGN.md`.
2. **Extract logos.** From a rendered page, locate the brand-mark element in the header (light surface) and the footer (dark surface). Pull each via its source URL or inline SVG markup. Rasterise SVG to PNG with a transparent background. If only one origin exists, generate the other as a recoloured derivative and record the provenance.
3. **Capture copy.** Visit the homepage, About page, and footer/legal page. Extract the sections enumerated in the `description.md` contract above. Preserve verbatim text.
4. **Assemble.** Write the four artifacts to `<output-dir>/`. Run the cross-reference consistency pass. Delete any working files.

The skill does **not** prescribe which browser tool to use. Where multiple are available (gstack `browse`, Chrome DevTools MCP, Playwright MCP), pick whichever is already wired in the current environment. Token capture in particular benefits from Chrome DevTools because computed styles and `@media` rules are first-class there.

## Reference standard

The four artifact contracts above (DESIGN.md tier-1/2/3 token spec, the two PNG logo files with filename describing the art colour, `description.md` with the official-details block) are the contract. If a prior conforming brand pack exists on disk at any `<brand_dir>/` (look for the four artifacts in the layout shown in **Outcome contract**), inspect it as a worked example. A delivered package that diverges substantially in structure from those contracts is wrong, even if the content is accurate.

## Common mistakes

| Mistake | Why it's wrong |
|---|---|
| Saving a screenshot crop instead of pulling `<img src>` | Crops carry the surrounding background colour as anti-aliased noise. The PNG must be transparent on the logo's negative space. |
| Synthesising a dark logo silently | Downstream consumers will treat a derivative as authoritative. Provenance is mandatory. |
| Paraphrasing the homepage hero into "punchier" copy | `description.md` is the source of truth for the brand's voice. The brand's words, not yours. |
| Inventing token values that the site doesn't use | Token tier 1 is **observed**. `(proposed)` is for tier-2/3 values that fill an obvious gap, not for guesses about what the brand wants. |
| Including blog posts or case studies in `description.md` | The file is identity, not editorial. |
| Naming files after the FQDN (`<brand>realestate-logo.png` instead of `<brand>-logo.png`) | Slug is the brand name, not the full domain. |
| Skipping the mobile viewport during token capture | Type scale and section padding both differ at mobile. A desktop-only tokenization is incomplete. |
| Generating the dark theme block in `DESIGN.md` from imagination | If the site is light-only, the dark theme is an **inversion derived from the primitives**, marked "proposed", not a parallel design system. |
| Embedding the company description inside `DESIGN.md` | The artifacts are separable on purpose. Each file has one job. |

## Completion criteria

Report `DONE` only after:

- All four files exist at the expected paths and only those files.
- `DESIGN.md` references the source URL and capture date in its first paragraph.
- Both logo PNGs render correctly on their target surfaces (a quick eyeball at 64px height is sufficient — no chrome, no surrounding nav).
- `description.md` contains, at minimum, the brand name, the homepage hero copy, and any registration numbers visible on the site.
- If a recoloured logo was synthesised, the `## Asset notes` line is present in `description.md`.
- Working files (HTML dumps, snapshot JSON, intermediate screenshots) are removed.

If any of those are not true, report `DONE_WITH_CONCERNS` and list each gap.

## When NOT to use this skill

- The user wants a **proposed** brand identity for a product that doesn't have a site yet → use `brand-pack` or `design-consultation` instead. Those generate; this one extracts.
- The user wants a fresh DESIGN.md only → call `design-systems:tokenize` directly; the wrapper here is overkill.
- The user wants a full visual audit, hover states, and component inventory → `plan-design-review` or `design-review` go deeper than this skill is scoped for.
