Brand Workflow

Create a visual identity system. Not a generic guidelines doc — an opinionated, applied identity.

Announce at start: "I'm using the brand skill to create a visual identity system."

This skill is user-interactive. Do NOT spawn agents for brand decisions.

Brand identity is the most subjective design work. Every choice must be driven by the user. The skill's job is to present excellent options and push against mediocrity — not to decide.

The 5 directions must be genuinely different. If they're all variations of "clean modern minimal", you've failed. Push across axes: warm/cool, serif/sans, dense/airy, bold/subtle, structured/organic.

Phase 0: Load References & Existing Context

Check for existing brand/design context:

ls docs/brand-system.md docs/design-context.md docs/vision.md 2>/dev/null

If brand-system.md exists:

AskUserQuestion:
  question: "You already have a brand system. What would you like to do?"
  header: "Existing brand"
  options:
    - label: "Evolve it"
      description: "Keep the core identity but refresh or extend it"
    - label: "Replace it"
      description: "Start fresh with a new identity"
    - label: "Review it"
      description: "Audit the current brand for issues or inconsistencies"

Check for fonts in the project (local fonts are premium — prefer them over Google Fonts):

# Check all common font locations — local fonts are a major asset
ls public/fonts/ src/fonts/ fonts/ app/fonts/ 2>/dev/null | head -30
# Also check nested font dirs (projects often organize by family)
find . -path '*/fonts/*' -name '*.otf' -o -name '*.ttf' -o -name '*.woff2' 2>/dev/null | head -30
# Check what's already loaded
grep -r "font-family\|@font-face\|next/font\|localFont\|google.*font" src/ app/ --include='*.{ts,tsx,css}' -l 2>/dev/null | head -10

If the project has local font files from premium foundries (Klim, Commercial Type, Grilli, etc.), these are a significant brand asset. Use them in the 5 directions rather than defaulting to Google Fonts. Document which fonts are available so you can reference them in the comparison page.

Phase 1: Gather References

Ask for visual references first. Images > adjectives.

AskUserQuestion:
  question: "Do you have visual references — screenshots of brands you admire, logos, fonts, color palettes, or anything that captures the feeling you want?"
  header: "References"
  options:
    - label: "Yes, let me share"
      description: "I have images, links, or files to share"
    - label: "I have ideas but no images"
      description: "I can describe what I'm going for"
    - label: "No idea yet"
      description: "Help me discover what I want"

If they share images: Read them using the Read tool. Analyze:

Dominant colors and palette character
Typography style (serif, sans, display, monospace)
Visual density (airy vs dense)
Mood (warm, cool, energetic, calm, luxurious, raw)
What makes each reference distinctive

If they describe verbally: Probe deeper. Don't accept adjectives alone:

"Modern" → "Modern like Apple (restrained, spatial) or modern like Stripe (technical, precise)?"
"Clean" → "Clean like Aesop (warm minimalism) or clean like Linear (cold precision)?"
"Professional" → "Law firm professional or design agency professional?"

If they need discovery: Ask about the world their product lives in:

AskUserQuestion:
  question: "If your product were a physical space, what would it feel like?"
  header: "Brand world"
  options:
    - label: "A gallery"
      description: "Curated, spacious, quiet authority. White walls, considered objects."
    - label: "A workshop"
      description: "Craft, tools, raw materials. Honest, functional, warm."
    - label: "A bookshop"
      description: "Editorial, layered, rich. Typography-forward, intellectual."
    - label: "A studio"
      description: "Creative, expressive, bold. Color-confident, dynamic."

Follow up with:

AskUserQuestion:
  question: "What must this brand NEVER feel like?"
  header: "Anti-references"
  options:
    - label: "Generic tech startup"
      description: "No Inter + blue + white cards + purple gradients"
    - label: "Corporate enterprise"
      description: "No gray suits, no stock photos, no committee decisions"
    - label: "Trendy/disposable"
      description: "No whatever's hot on Dribbble this month"
    - label: "Something else"
      description: "I'll describe what to avoid"

Phase 2: Brand Discovery

With references in hand, explore through conversation:

Who is this for? Not demographics — taste and expectations:

What do they already use? (informs visual language they'll find familiar)
What would surprise and delight them?
What would make them distrust you?

What's the brand's core tension? Great brands hold a tension:

Accessible expertise (smart but not intimidating)
Playful precision (fun but not unserious)
Raw refinement (honest but not crude)
Warm authority (trustworthy but not cold)

Identify the tension and use it to anchor the 5 directions.

Phase 3: Generate 5 Directions

Generate 5 genuinely different brand directions. Each explores a different axis while staying true to the references.

Direction Structure

For each direction, define:

### Direction [N]: [Evocative Name]

**Personality:** [One sentence capturing the tension]

**Palette:**
| Role | Color | OKLCH | Hex |
|------|-------|-------|-----|
| Brand | [name] | oklch(...) | #... |
| Accent | [name] | oklch(...) | #... |
| Surface | [name] | oklch(...) | #... |
| Text | [name] | oklch(...) | #... |
| Muted | [name] | oklch(...) | #... |

**Typography:**
- Display: [font] — [why this font for this direction]
- Body: [font] — [why]
- Mono: [font]

**Visual character:** [border radius, shadow style, line weight, density]

**Mood image prompt:** [detailed motif prompt for this direction]

Direction Diversity Rules

The 5 directions MUST vary across these axes:

Temperature: At least one warm, one cool
Typography: At least one serif-led, one sans-led
Density: At least one airy, one dense
Energy: At least one calm, one energetic
Surprise: At least one that pushes the user's comfort zone

Generate Mood Images

For each direction, run motif to generate atmospheric mood images — NOT logos or marks. Mood images should evoke the feeling of the direction (a greenhouse, a letterpress studio, a material palette) without attempting to render wordmarks, monograms, or brand names. AI-generated text in logos is unusable and wastes the user's time.

# GOOD: atmospheric, no text
motif "warm greenhouse interior, morning light through glass, terracotta pots, fern fronds, editorial photography" --landscape

# BAD: attempts a logo — will produce garbled text
motif "Acme Corp logo, botanical leaf mark, clean vector" --square

For each direction, run motif:

motif "[atmospheric scene evoking this direction's mood — NO brand names, NO text, NO logos]" --landscape

Present to User — COMPARISON PAGE IS MANDATORY

You MUST build a live comparison page. Do NOT present directions as markdown tables in the conversation. The user cannot evaluate typography and color from text descriptions — they need to SEE real fonts rendered at real sizes with real colors in the browser.

If the project has Next.js or Vite (check for this — most projects do):

Generate a comparison page at app/brand-explore/page.tsx (Next.js) or brand-explore.html (Vite/static). This page MUST:

Load actual project fonts — check app/fonts/, public/fonts/, src/fonts/ for local font files first. Use next/font/local or @font-face to load them. Only fall back to Google Fonts if the project has no local fonts. Premium local fonts (Canela, Schnyder, Lyon Display, etc.) are far more distinctive than Google Fonts — use them.
Render color swatches as filled divs with hex/oklch labels
Render type specimens at three scales: display headline, body paragraph, and small caption/label. Use the actual font proposed for each direction, not a placeholder.
Include the mood image for each direction (from motif)
Show a mini component preview — at minimum a button and a card in each direction's colors/type
Be self-contained — all styles inline or in a <style> block, no external dependencies beyond fonts

Tell the user to open the page in the browser before asking them to pick.

Fallback (no framework): Present directions as an HTML file the user can open directly, or use Chrome MCP to render specimens and screenshot them. Markdown tables in conversation are a LAST resort.

AskUserQuestion:
  question: "Which direction resonates most?"
  header: "Pick a direction"
  options:
    - label: "[Direction 1 name]"
      description: "[One-line personality summary]"
    - label: "[Direction 2 name]"
      description: "[One-line personality summary]"
    - label: "[Direction 3 name]"
      description: "[One-line personality summary]"
    - label: "Mix elements"
      description: "I want to combine parts from different directions"

Phase 4: Refine & Deepen

Take the chosen direction and build it out:

4.1 Full Color System

Generate complete shade scales (50-900) in OKLCH:

brand-50:  oklch(0.97 0.02 [hue])
brand-100: oklch(0.93 0.04 [hue])
brand-200: oklch(0.87 0.07 [hue])
brand-300: oklch(0.78 0.10 [hue])
brand-400: oklch(0.68 0.13 [hue])
brand-500: oklch(0.58 0.15 [hue])  ← base
brand-600: oklch(0.50 0.14 [hue])
brand-700: oklch(0.42 0.12 [hue])
brand-800: oklch(0.33 0.10 [hue])
brand-900: oklch(0.25 0.08 [hue])

Plus:

Tinted neutrals — grays with a hint of the brand hue
Dark mode palette — not inverted, rebalanced for dark surfaces
Semantic colors — success, warning, error, info (harmonized with brand)

4.2 Typography System

Full type scale with clamp() for fluid sizing
Weight assignments per context (headline, body, label, caption)
Tracking adjustments per size (tighter for large, looser for small/caps)
Line height ratios (decreasing as size increases)
Font loading strategy (font-display, fallback stack)

4.3 Visual Character

Border radius tokens (none/sm/md/lg/full)
Shadow style and elevation scale
Line weight for borders, dividers, icons
Density (component padding, gap defaults)
Motion personality (still/subtle/expressive, spring params if applicable)

4.4 Test the System

Show the brand applied to common patterns:

A card component
A button set (primary, secondary, ghost)
A navigation bar
A form with inputs
Dark mode variants

Use Chrome MCP to screenshot if available.

AskUserQuestion:
  question: "How does this feel applied to real UI?"
  header: "Brand check"
  options:
    - label: "Feels right"
      description: "This is the brand. Let's finalize."
    - label: "Needs adjustment"
      description: "Close but some things need tweaking"
    - label: "Too [something]"
      description: "I'll tell you what needs to change"

Phase 5: Generate Assets

Auto-generate brand assets using motif. If motif is not available, provide detailed prompts and instructions.

# Check if motif is available
which motif 2>/dev/null

If motif is available:

AI image generation CANNOT produce usable logos or wordmarks. Generated text is garbled, letterforms are inconsistent, and the results look amateur. Do NOT attempt to generate logos, wordmarks, or monograms with motif.

Instead, use motif for atmospheric and textural assets where AI excels:

# OG image — atmospheric, NO text
motif "[brand mood scene], [brand colors], editorial photography, atmospheric" --og

# Hero/mood image — NO text, NO logos
motif "[brand world scene], [brand colors], [visual texture]" --landscape

# Texture/pattern — abstract, useful as backgrounds
motif "abstract [brand texture], [brand colors], subtle, seamless feel" --square

For logos, wordmarks, and monograms — build these as SVG components in code or as hand-crafted SVG files. Code-built SVGs are:

Infinitely scalable
Editable (colors, sizes via props)
Crisp at every resolution
Version-controllable

If the brand needs a botanical mark, illustrative monogram, or symbolic icon, build it with SVG path commands. Simple, geometric marks are achievable in code. Complex illustrated marks should be flagged as needing a designer.

If motif is NOT available:

Provide atmospheric prompts for the user to run manually. For logos/marks, build SVG in code.

Additional assets to create:

Logo/mark: SVG component (React) or standalone .svg file — built in code
Favicon: SVG favicon (scales perfectly, supports dark mode via prefers-color-scheme)
OG image: Use Satori (@vercel/og) to generate dynamic OG images from the brand tokens — this produces crisp text using actual fonts, unlike motif

Phase 6: Produce Outputs

1. Brand System Document

Write to docs/brand-system.md with the full brand system (see spec for structure).

2. Design Tokens

Detect the project's CSS setup and generate appropriate tokens:

Tailwind v4 (CSS @theme):

@theme {
  --color-brand-50: oklch(0.97 0.02 250);
  /* ... full scale ... */
  --font-display: "Lyon Display", serif;
  --font-body: "Untitled Sans", sans-serif;
  --font-mono: "Geist Mono", monospace;
  /* ... spacing, shadows, radii ... */
}

Tailwind v3 (config):

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        brand: { 50: '...', /* ... */ },
      },
      fontFamily: {
        display: ['Lyon Display', 'serif'],
        // ...
      },
    },
  },
}

Plain CSS:

:root {
  --brand-50: oklch(0.97 0.02 250);
  /* ... */
}

3. Assets Directory

Save generated assets:

public/brand/
├── logo.png
├── logo-dark.png (reversed for dark backgrounds)
├── roundel.png
├── og-template.png
├── favicon.svg
├── hero.png
└── palette.png

4. Brand Page (optional)

AskUserQuestion:
  question: "Want me to create a /brand page in your project that showcases the identity system?"
  header: "Brand page"
  options:
    - label: "Yes, create it"
      description: "A beautiful page showing palette, typography, logo usage, and component examples"
    - label: "No, the docs are enough"
      description: "The brand-system.md and tokens are sufficient"

If yes, generate a page at app/brand/page.tsx (or equivalent) that displays:

Logo and wordmark with clear space rules
Full color palette with swatches and values
Typography specimens at all scales
Component examples in brand colors
Dark mode toggle
Do/don't examples for brand application

5. Clean Up

If a comparison page was generated in Phase 3, offer to remove it:

AskUserQuestion:
  question: "Remove the brand-explore comparison page?"
  header: "Cleanup"
  options:
    - label: "Remove it"
      description: "Delete the temporary comparison page"
    - label: "Keep it"
      description: "Keep it around for reference"

The Taste Engine

The taste engine is not a hardcoded list — it draws from the references loaded in Phase 0. The key principle: challenge generic choices with curated alternatives from the references.

Typography Taste

Consult references/brand-identity.md for:

The "Never use for brand identity" list
Recommended brand fonts with character descriptions and use cases
Commercial foundries for premium projects
Font pairing principles

Consult references/typography-opentype.md for:

Tracking adjustments per context (tighter for display, looser for all-caps)
Font loading strategy decisions
OpenType features that add typographic polish

The brand typography principle: brand-identity.md separates UI fonts from brand fonts. UI fonts (Inter, Geist, DM Sans) disappear — they're excellent for body text. Brand fonts (display, headlines, wordmarks) must express personality. When a user picks a UI font for brand identity, present alternatives from brand-identity.md with their character descriptions. Don't block the choice — explain the distinction and offer refined alternatives.

Color Taste