brand_dna_extraction v1.0.0

name: brand_dna_extraction description: Extract a usable brand profile from a live site, covering voice, colours, type, imagery, values, and audience, with every field pinned to the page it came from and labelled observed, repeated, or inferred. Triggers when someone asks to extract, audit, document, or reverse-engineer a brand from a website, build a brand profile or style guide from an existing site, or capture a client's brand before writing or design work starts.

Brand DNA Extraction

Purpose

Turn a live website into one structured brand profile that writing and design work can actually run from: colours with roles and contrast results, type with families and sizes as written, imagery patterns with quoted alt text, voice coded on evidence, and values and audience separated into what the site states and what you infer. Every field carries its source page and a confidence label. A profile without pins is opinion in a tidy format, and downstream work built on it drifts.

The bundled extractor does the measuring. You do the judging. Scripts never code voice, values, or audience.

Workflow

1. Pick the page set. Homepage plus about, one offer or product page, one long article, and one utility page, as the site allows. Three pages minimum before anything gets called a brand pattern. One page earns a page profile, labelled as such. Full list in references/extraction-checklist.md.
2. Capture evidence. Save each page, or run the extractor in fetch mode per page: python3 scripts/extract_brand.py --fetch https://example.com/ --out evidence-home.json. For saved files: python3 scripts/extract_brand.py --url https://example.com/ --html home.html --css site.css --out evidence-home.json. The script is stdlib only, fetches with curl when asked, and writes identity meta, colour counts with selectors, font families, custom properties, headings, link and button text, image alt data, paragraph samples with sentence stats, and WCAG contrast ratios against white and black.
3. Cross-check across pages. A colour, font, or phrasing on one page is a lead. The same value on three pages, or in a stylesheet all sampled pages load, is the system. Mark single-page findings observed, cross-page findings repeated. Where two pages disagree, record the conflict. Never average it away.
4. Assign colour roles from selectors. Body background, body text, link, primary action, surface, muted. Use CSS custom property names when the site declares them, since a token name is the site naming its own colour. Keep light and dark schemes as two palettes when a prefers-color-scheme block or theme exists. Compute the contrast pairs a reader faces and flag informational text under 4.5:1. WCAG 1.4.3 sets 4.5:1 for normal text and 3:1 for large text at Level AA, and exempts logotypes and decoration, not dates or captions.
5. Record type as written. Family names, fallbacks, sizes, weights, and line heights in their original units, per role: body, headings, meta, code. For self-hosted fonts, record the @font-face family name and file URL exactly. A code name like "v" stays "v". If rendered values matter, confirm with getComputedStyle in a browser, which returns resolved values after stylesheets, classes, and inheritance settle.
6. Read imagery from the markup. Count images, count missing alt attributes, quote two alt texts, note recurring shapes from width and height attributes, and pull treatment rules out of the CSS, such as dark scheme filters or radius. Describe only images on the sampled pages.
7. Code the voice by hand. Collect at least six verbatim samples across two pages, headings and link text included. Score each of the four Nielsen Norman Group dimensions (formal to casual, serious to funny, respectful to irreverent, matter-of-fact to enthusiastic) as a point on the spectrum, with the quote that earned it. Write fixed traits as "X but not Y" pairs, the Mailchimp pattern, each backed by a quote. Voice stays fixed while tone flexes by context, so profile the voice and note tone shifts separately when pages differ.
8. Handle values and audience last, and keep them honest. Values come only from claims the site makes about itself, quoted, including stance pages the homepage links to. Audience splits in two: stated, quoted from the site's own description or about text, and inferred, two lines maximum, labelled, resting on named pages.
9. Assemble the profile on references/profile-schema.md, then run the final checks in references/extraction-checklist.md. Study references/worked-profile-sive-rs.md first if this is your first run. It is a complete profile built from a real small site, including a failing contrast pair, a missing theme colour, and a font known only by its code name.

Output Contract

One Markdown brand profile following references/profile-schema.md, in this order:

1. Header: site name, extraction date, every page URL sampled, and where the evidence pack lives.
2. Identity: site name, title pattern, meta description quoted exactly, Open Graph image with declared size, theme colour or not found, canonical pattern.
3. Colours: per scheme, each colour as hex with role, selector or element, count, and source, plus a contrast table for the pairs readers face, with pass or fail against AA stated plainly.
4. Typography: per role, family and fallbacks as written, size, weight, line height, and source, plus self-hosted font files.
5. Imagery: counts, missing alt count, two quoted alt texts, recurring shapes, treatment rules from CSS.
6. Voice: at least six quoted samples with page URLs, sentence stats, the four dimension marks each with its earning quote, and fixed traits as "X but not Y" pairs.
7. Values: quoted self-claims with sources, or "none stated".
8. Audience: stated and inferred kept apart, inferred labelled and capped at two lines.
9. Gaps and conflicts: every not found field, every cross-page disagreement, every check that could not run.

Plus the extractor evidence pack (JSON) saved beside the profile, so any number in the profile can be traced back to a run.

Operating Rules

1. No pin, no claim. Every factual field carries a page-level source URL. A claim you cannot pin gets cut or moves to the inferred section with its evidence named.
2. Never invent brand data. No guessed hex codes, no commercial font name substituted for a code name, no colour names presented as the brand's own unless the site uses them, no audience demographics the site never stated.
3. Declared beats rendered beats guessed. CSS values and meta tags are the evidence base. Screenshot eyedroppers pick up compression and anti-aliasing, so use them only to spot check, never as the source of a hex value.
4. A theme colour is a signal, not a verdict. MDN defines it as a suggested colour for the surrounding user interface. Record it, then check whether the palette backs it up before calling it primary.
5. Contrast failures get reported at full strength. A muted grey that fails AA on the brand background is a finding, not an embarrassment to soften. Note the exemption boundary honestly: logotypes and decoration are exempt under WCAG 1.4.3, informational text is not.
6. Quotes stay verbatim. Casing, punctuation, and fragments stay as published. Lowercase headings are data about the voice, so do not tidy them into title case.
7. Absence is a result. Not found, none stated, and not checked are three different statements. Use the right one, and say which pages the absence covers.
8. Respect the site. Fetch each page once, at normal browsing rate, and work from saved copies after that. This is reading a public site, not scraping it at volume.
9. Style law for the profile itself. No em dashes. Plain, direct sentences. If a line in the profile sounds like a press release, rewrite it before the profile ships.