/generate-ui-from-brand

name: generate-ui-from-brand
description: Pipeline from a URL or DESIGN.md to tokens, decisions and a UI spec. Use when building UI for an existing brand, auditing a design system or fixing visual inconsistency.
metadata:
  priority: 9
  requires: "dembrandt>=0.23.1"
  docs:
    - "https://dembrandt.com"
    - "https://www.npmjs.com/package/dembrandt"
  promptSignals:
    phrases:
      - "build ui for"
      - "match this brand"
      - "generate ui from"
      - "design system from"
      - "extract and build"
      - "design.md"
      - "brand tokens"
      - "audit design system"
      - "multi-brand"
      - "white-label"
      - "token governance"
      - "consolidate design system"
      - "deprecate component"
      - "deprecate old styles"
      - "pages from different eras"
retrieval:
  aliases:
    - generate ui from brand
    - brand to ui
    - design system pipeline
    - token to component
    - brand audit
    - multi-brand theming
    - white-label
    - token governance
    - design system consolidation
    - component deprecation
  intents:
    - build ui matching an existing brand
    - turn a url into a ui spec
    - audit and fix design system
    - generate design tokens and apply ux rules
    - refactor inconsistent design
    - build many brands from one token system
    - consolidate tokens across brands
    - deprecate unused components
    - migrate old pages to the current design
    - promote a repeated style into a pattern
  examples:
    - build a UI that matches stripe.com
    - generate a UI spec from this brand
    - audit this design system and tell me what to fix
    - I have a DESIGN.md, turn it into a component structure
    - I build sites for many brands, how do I keep tokens consistent
    - which components should we deprecate

generate-ui-from-brand

**Type:** Pipeline / Orchestrator **Input:** URL or existing DESIGN.md **Output:** Actionable UI spec with decisions made

---

Step 1 — Extract

**If a URL is provided and Dembrandt MCP is available:**

All MCP extraction tools are async — they return a `job_id` immediately. Poll `get_job_status` until `status` is `"completed"`, then read `result`.

{ job_id } = get_design_tokens({ url })
{ result } = get_job_status({ job_id })   // repeat until status === "completed"

Run these in sequence (each extraction launches a browser):

get_design_tokens, get_color_palette, get_typography, get_component_styles, get_spacing

**If Dembrandt MCP is not available, run CLI:**

npx dembrandt <url> --design-md --crawl 3

**If DESIGN.md already exists:** parse it directly — skip extraction.

---

Step 2 — Normalize Tokens

Do not use raw extracted values directly. Map them to a semantic system first.

Colours

Identify the role of each extracted colour:

| Role | Token | How to identify | |---|---|---| | `color-primary` | Main brand colour | Used on primary buttons, links, key interactive elements | | `color-secondary` | Supporting brand colour | Used on secondary actions, accents | | `color-surface` | Background | Page or card background | | `color-surface-raised` | Elevated surface | Cards, panels, modals | | `color-border` | Border / divider | Input borders, separators | | `color-text` | Primary text | Body copy | | `color-text-secondary` | Secondary text | Labels, metadata, captions | | `color-error` | Error state | Red — do not assign to any other role | | `color-warning` | Warning state | Orange/amber — do not assign to any other role | | `color-success` | Success state | Green — do not assign to any other role |

**Decision rule:** if the extracted palette has more than 2 brand colours competing for `color-primary`, pick the one with highest usage on interactive elements.

Typography

Map extracted sizes to a scale. Verify ratio coherence — if sizes do not follow a consistent ratio, round them to the nearest modular scale step (base 16px, ratio 1.25 recommended).

| Token | Min size | Role | |---|---|---| | `text-base` | 16px | Body copy — never below 16px | | `text-sm` | 14px | Labels, captions — use sparingly | | `text-lg` | 20px | Lead paragraph | | `text-h4` | 25px | Section subheading | | `text-h3` | 31px | Section heading | | `text-h2` | 39px | Page subheading | | `text-h1` | 49px | Page heading | | `text-display` | 61px | Hero / landing only |

**Decision rule:** if extracted body text is below 16px, override to 16px.

Spacing

Identify the base spacing unit from the most common small margin/padding value. Derive a scale:

base = extracted smallest recurring value (usually 4px or 8px)
scale = base × 1, 2, 3, 4, 6, 8, 12, 16

Border Radius

Extract the most common radius value used on interactive elements (buttons, inputs). This becomes `--radius-button` — applied uniformly to all buttons regardless of variant.

---

Step 3 — Apply UX Decisions

With normalized tokens, make the following decisions explicitly. Do not leave these open:

Visual Hierarchy

• Identify the single primary action for the UI being built
• Assign `color-primary` to that action only
• All other actions use neutral or outlined styles
• Apply `cursor: pointer` to all interactive elements

Gestalt Grouping

• Define spacing between related elements (tight: `space-2`) and between groups (loose: `space-6` or `space-8`)
• Confirm that related controls will be co-located in the layout

Accessibility (WCAG 2.2 AA)

Run contrast check on normalized tokens:

• `color-text` on `color-surface`: must be ≥ 4.5:1
• `color-text-secondary` on `color-surface`: must be ≥ 4.5:1
• `color-primary` on white/surface (button label): must be ≥ 4.5:1

If any fail, darken or lighten the token to meet the threshold. Document the adjustment.

Error / Status Colours

• Confirm `color-error` is red and used only for errors
• Confirm `color-warning` is orange/amber and used only for warnings
• If the brand uses orange as a primary colour, it cannot double as a warning — a distinct