--- 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 ", "build a brand pack from ", "tokenize 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 `/` 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: ``` / DESIGN.md # tokenized design system, observed values -logo-light.png # the light-coloured logo art (white/cream/pale pixels) — for placing on dark surfaces -logo-dark.png # the dark-coloured logo art (black/navy/charcoal pixels) — for placing on light surfaces description.md # company copy + official registration details ``` `` is the lowercase, hyphen-separated brand name — derived from the brand's own name, not its FQDN (e.g. ``, not `realestate.co.uk`). The slug is reused as the directory name unless the caller specifies otherwise — that is, the brand workspace is `//` and these four files live at its root. A sibling `properties/` directory may also be present at `/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: `.//` 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 `/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 ``), 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 `` 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. ### `-logo-light.png` and `-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 | |---|---|---| | `-logo-light.png` | light/white/cream/pale pixels | dark surfaces (back-page hero, dark masthead) | | `-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. - `-logo-light.png` (light-coloured art) must render crisply against a dark/ink target surface. `-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 `` 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: `-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 `` / `` 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 `/`. 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 `/` (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 `` | 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 (`realestate-logo.png` instead of `-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.