brand

# brand Point this skill at the current design and a brand kit, and it re-skins the design to that brand under the brand's **strict rules**. It operates on the **design in the current session**, and the restyle is **saved as its own `.imgly` file**. Single home for the brand workflow: the **role → token map**, the **restyle routine**, the **graded conformance pass**, and the brand **no-goes**. **Keep the source; restyle a copy.** A session holds one design and a restyle changes it in place (handbook §1), so take the source's `uri` first and `import` it — the restyle goes to the copy, and the source stays as it was: ``` export({ format: 'imgly' }) → SOURCE_URI (the un-branded original, kept) import({ source: { uri: SOURCE_URI } }) → a copy of it is the session edit(…) restyle + conform preview() → diff against the source's render export({ format: 'imgly' }) → the restyled edition, its own file ``` Both editions then exist. Skipping the first two steps means the un-branded original is gone the moment you restyle — and the source-parity diff the `judge` gate requires has nothing to compare against. It builds on things it does _not_ restate: handbook §6.1–§6.5 (the general typography / colour / hierarchy / composition / craft thresholds), the handbook's engine mechanics (the `text.font` declaration, fill specs, auto-reshape, `loadResources`, the content-area line-height conversion §6.1.3), and its two siblings. The brand kit's own `tokens.json` supplies the **values**; this skill supplies the **procedure**. **Scoring:** a restyle is judged with the `judge` skill — every applicable axis ≥ 8, no averaging, N/A = 10. The brand kit's `avoid` list + `do-dont/` gallery are an **additional** gate on top of the axes: a single hard `avoid` violation (a second colour used as structure, a banned button, a redrawn logo, a free-chosen colour) fails the restyle even if the axes would pass — include an "avoid-list" row in the judge scorecard. ## Reference files (load on demand) This `SKILL.md` is the always-needed spine: inputs, core principle, role map, workflow, restyle routine, conformance pass, the **brand conformance checklist**, no-goes. Two situational bodies live beside it: - **`reference/brandkit-spec.md`** — the canonical brand-kit **schema** (what `tokens.json` must contain, required-core vs optional sections, how the skill degrades when a section is absent). Read it when validating a kit or unsure what a token means. - **`reference/authoring.md`** — the **intake** mode: turning an _external_ brand (a guidelines PDF, a website/URL, a Figma file, or a raw asset dump) into a canonical `<kit>/` before applying — extraction per source form, the not-invent discipline, the avoid-list hard-stop, the font-subset trap. Read it whenever the kit isn't already a valid canonical folder. - **`reference/asset-loading.md`** — the **asset mechanics** (resolving brand fonts to a fetchable URI incl. the local-TTF → imported-`uri` bridge, the hex → 0-1 RGBA conversion, placing the wordmark SVG, recolouring monochrome icons, building the **kicker pill** on a text background, block-**opacity** vs colour-alpha, `text.color` vs colour-fill, the whole-block colour that flattens per-run colour). Unlike its two siblings this one is NOT situational — every restyle touches fonts, colours, or the logo, so it is required reading before the restyle routine; it lives beside the spine only to keep this entry document lean. ## localize / resize vs brand — the three surgeries The three sibling skills each change exactly one layer and hold the rest fixed: - **localize** — changes the **words** (+ the script's font); **snaps geometry** back to the reference. Any geometry move is drift. - **resize** — changes the **canvas**; **re-derives geometry** for the new aspect. Copy and style are held. - **brand** — changes the **style layer** (colour, type, logo, treatment) **by role**; **holds copy and composition**. Geometry moves only in the graded conformance pass, and only where a brand _rule_ requires it — never a free re-layout. Never confuse them: don't re-word or re-flow inside a brand pass (that's localize / resize), and if a brand genuinely needs a different _layout_ (not just a different skin), that is a **resize**, not a brand restyle — cross-ref and stop, don't silently re-compose. ## Inputs — what to restyle, into which brand, in which scheme Resolve these by the intake contract — derive, ask once, echo, invent nothing: `../handbook/intake.md`. **R** = required, no default; **A** = ask if underived; **D** = defaultable. | Parameter | Kind | Chips / values | Default | | ------------- | ------- | ------------------------------------------------------------------------- | --------------------------------- | | brand kit | **R** | the kits you can find · `Provide a brand source` · Other | **none — never invented** | | colour scheme | A | the chosen kit's `colorSchemes.approved` · `Decide automatically` · Other | the neutral / `paper` scheme | | source design | derived | — | the design in the current session | **1. The source** — the design in the current session. **Save it first** (`export({ format: 'imgly' })`) and keep the `uri`: a restyle preserves that design's geometry and copy — only the style layer changes — and the saved file is both the un-branded original and your reference for the parity diff. If the user means a design saved earlier, its `uri` IS `SOURCE_URI`: `open` it to `preview` and capture it, skip the first save, then `import` a copy to restyle. **2. The brand kit** — a folder the user points you at (`<kit>/`), holding `tokens.json` (+ `BRAND.md`, fonts, logos, icons, imagery, `do-dont/`). Parse `tokens.json` **first**; it is the machine-readable law. Validate it against `reference/brandkit-spec.md`. If no kit is named, **ask** — _**Which brand should this use?**_ — offering the kits you can find plus `Provide a brand source`. A brand is the user's own fact: there is no defaulting to "a sensible brand", and no proceeding on an inferred one. If what the user gives you is **not** a canonical kit yet — an external source (a guidelines PDF, a website/URL, a Figma file, or a raw asset dump), or a folder with no valid `tokens.json` — **scaffold it into the canonical shape first** (extract → map → `tokens.json` + `BRAND.md` + assets → validate), per **`reference/authoring.md`**, then apply against the new kit. Ask the user where the kit folder should live; it is theirs to keep and reuse. **If the required-core is incomplete, ask for the missing piece — don't stop, and don't guess.** Never fill a gap in a kit with a value of your own: not a colour, not a typeface, not a logo. Name what is missing and ask for exactly that, e.g. > The Acme kit has no display font — `typography.display` is empty, and I won't pick one for your > brand. > **Which font should headlines use?** `Provide a font file` · `Name a Google font` · > `Use the kit's body font` · Other **3. The scheme** — one **approved** `colorScheme` from `tokens.colorSchemes.approved`, chosen deliberately per `backgroundSelection` (default the neutral/`paper` scheme; use the full-bleed brand-colour scheme only for a deliberate hero). If the kit offers more than one approved scheme and nothing in the request implies which, ask — _**Which colour scheme?**_ — with the kit's own approved schemes as chips plus `Decide automatically`. Reading the chips from `tokens.json` is not invention; free-choosing a `(bg, text, accent)` triple is. **One scheme per piece** — never a `denied` combination. Then echo what you resolved in one line ("acme restyle, paper scheme (defaulted), 1 design") and run the Workflow. The restyling `edit` gets a `note` naming the brand and scheme (e.g. "acme restyle, paper scheme"). ## Core principle — re-skin by role, then conform to the brand's law A brand kit is not a palette swap — it is a **role system**. Restyling is two layers: - **Layer 1 — Restyle (always).** Classify each source block by its **design role**, then set its colour + font + treatment from the **brand token for that role** (background → scheme background; headline → display family; the one focal moment → accent; eyebrow → kicker style; …). Geometry unchanged. This is deterministic once roles are mapped. - **Layer 2 — Graded conformance.** Enforce the brand's structural law where it does **not** fight the source composition: kill every hard `avoid` / `denied` violation (non-negotiable), then apply the applicable structural rules (proportion, safe-area margins, kicker-as-pill, card shadow, signature device, size thresholds). A rule that would require re-laying-out the piece is out-of-scope — flag it (→ resize), don't force it. The brand's `avoid` list is the floor: **no restyle ships with a hard `avoid` violation**, even if every axis scores ≥ 8. ## Role → token map Classify by measurable role (as in the localize skill's block classification), then map: | Source block role | Brand token (from `tokens.json`) | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | full-bleed background | chosen `colorSchemes.approved[].background` | | headline / display / big number | `typography.display` family; text = scheme `text` (or `primary-foreground` on a colour field); **respect `headlineWeight`** — never exceed the brand's weight _at that size_ (a `typography.display.weightRule` may vary it by size) | | subline / lead / body | `typography.body` family; text = scheme `text` or `muted-foreground` | | the single focal moment (one accent) | scheme `accent` / `semanticColors.primary` — **one per piece**, but the `avoid` list wins (see the trap below): on a full-bleed brand-colour scheme the accent role often has **no valid target** — drop it, the field is the moment | | eyebrow / kicker | `elements.kicker` (pill shape + its text colour) — not a bare coloured label | | divider / rule | `elements.divider` (hairline) — never a coloured/second-colour stroke | | card / panel / tile | `shape` corner radius + `elevation` shadow — never a flat bordered box | | CTA | `elements.button` **only on interactive/mockup media**; on static media a CTA is text/URL | | logo / wordmark | `logo.variantsByBackground` picked by the chosen background — exact bundled SVG only; if the asset is `$meta.gaps`-flagged (trademark-locked / not fetched), skip or placeholder it, never invent/redraw | | monochrome icon | recolour its ink to the role colour (`reference/asset-loading.md`) | | photographic / product media | keep; grade per `imagery` if the brand specifies; never tint to a banned colour | Where the source has no block for an optional brand element (device, kicker), the conformance pass _may_ add it if it fits; where the brand kit lacks an optional token, skip that rule (graceful degradation — `reference/brandkit-spec.md`). **The scheme-accent trap — `avoid` overrides the scheme.** A `colorSchemes.approved` entry may list an `accent` the `avoid` list forbids in the context you're applying it (e.g. IMG.LY's `indigo-moment` lists a mint accent, but `avoid` bans mint text on an indigo field). When the scheme's accent and the `avoid` list conflict, **the `avoid` list wins**: apply **no** accent and let the full-bleed field be the moment. Do not add a mint (or any denied) accent just because the role map has an "accent" row — an empty accent role is correct here. **Non-hero archetypes.** The role map is written for a headline+subline hero, but many designs aren't one — a quote card is eyebrow / quote-as-display / attribution-caption with no "lead". Map by the _nearest_ role (quote → `typography.display`; attribution → `typography.body`/caption) and ignore rows with no matching block; don't invent a subline to satisfy `typography.pairing`. ## Workflow 1. **Load & validate the brand kit.** Parse `tokens.json`; read `avoid` + skim `do-dont/`. Resolve every needed font to a fetchable URI and `asset_add` the logo SVG(s) — **`reference/asset-loading.md`**. 2. **Read the source, and save it.** The design resolved in Inputs is the reference — its geometry and copy are what the restyle preserves. `preview` it now and `export({ format: 'imgly' })` it: that render is the only source render the parity diff in step 7 will have, and that file is the un-branded original. Then `import({ source: { uri: SOURCE_URI } })` — restyle the copy, never the source. 3. **Capture source roles + style.** Walk the scene; classify blocks by role; read each block's current colour / font / geometry (see routine). 4. **Pick one approved scheme** per piece (per `backgroundSelection`); pick the logo variant by the chosen background. 5. **Layer 1 — Restyle.** For each block set the brand token for its role — recolour, refont (unique `typeface.name`), apply radius/shadow/accent, swap the logo. **Re-map the accent runs in the same write** — a font/size change auto-reshapes with ranges preserved, but the whole-block role colour flattens per-character colour, so the accent runs go back on as `text.ranges` in that same `setProps`. Geometry untouched. 6. **Layer 2 — Graded conformance.** Fix every hard `avoid`/`denied` violation; apply the structural rules that fit the source (proportion ~ the brand's ratio, safe-area margins, kicker pill, card shadow, device placement, size thresholds). Flag any layout-level need as out-of-scope (→ resize). 7. **Judge against the source** — a restyle is a **source-derived variant**: diff this render against the source render you captured in step 2. Copy, geometry, and composition must be the source's; only the style layer moved. (Lost that render? `export({ format: 'imgly' })` the restyle for its `uri`, `open` the source, `preview` it, then `open` the restyle's `uri` to return.) Then run the `judge` skill with the brand `avoid`/`do-dont` added to the criteria; contrast ≥ 4.5:1 after every recolour. Fix anything < 8 or any hard violation. 8. **`loadResources` → `preview` → SAVE.** Preview the restyle — wrong face, lost colour, low contrast, and a banned tell only show in the render. Then `export({ format: 'imgly' })`: that file is the branded edition, and until it exists the restyle is not something the user has. Report both `uri`s — original and restyle.