Brand Identity Generator

Brand Identity Generator

Generate a complete BRAND-IDENTITY.md file for the user's project root — a single reference document that specifies every visual decision so AI tools never guess.

Two modes:

• Guided discovery (default) — Ask one question, propose a full identity, refine from reactions. The user never needs design vocabulary.
• Expert shortcut — Detect when the user already provides specific design tokens (hex codes, font names, spacing values). Acknowledge what they've specified, fill gaps with smart defaults, skip discovery.

The output is a project-level reference file, not a skill. Once generated, any AI tool (Claude Code, Lovable, Cursor, Replit) can read BRAND-IDENTITY.md and build consistent UI without repeated instructions.

Logo guidance, decision frameworks, and common branding mistakes are included at the end.

---

Discovery Process

Core principle: The user should never need to use design vocabulary. They react to your proposals. You do the heavy lifting.

Default Path (Guided Discovery)

Step 1 — Ask ONE question:

"What are you building and who is it for?"

That's it. One question. Do not ask about colors, fonts, or design preferences.

Step 2 — Select reference brands:

Based on their answer, select the 1-2 closest reference brands from the Reference Brand Library below. Use the "Best for" field to match.

Step 3 — Propose a complete identity in plain English:

Write a human-readable recommendation. Talk about feeling, not specs. Example tone:

"Your users are developers who'll have this open all day. Products that succeed in this space — like Linear and GitHub — use calm, minimal aesthetics because your users stare at this 8 hours a day. I'd go with a dark-compatible palette built around a single cool accent, tight spacing so information density is high, and geometric type that feels fast. Here's what I'd recommend and why..."

Then present a summary covering:

• Overall feel in plain words
• Which reference brands you're drawing from and why
• Color direction (warm/cool, light/dark, accent character)
• Typography character (not font names — "clean and precise" vs "warm and readable")
• Density and spacing feel
• Component personality (sharp and fast vs soft and friendly)

Do NOT present the full 12-section spec yet. Keep it conversational.

Step 4 — User reacts:

They might say things like:

• "Love it"
• "Warmer"
• "I hate green"
• "More like Notion"
• "Can we make it feel more premium?"
• "Less corporate"

Adjust and re-propose. This loop usually takes 1-3 rounds.

Step 5 — Generate the full BRAND-IDENTITY.md:

Once the user approves, generate the complete output using the Output Template below. Write it to the project root as BRAND-IDENTITY.md.

Expert Path

Detect when the user provides specific design tokens — hex codes, font names, radius values, spacing scales. Signs of an expert:

• They paste CSS custom properties or Tailwind config
• They name specific fonts ("Inter for headings, Source Sans for body")
• They provide hex codes
• They reference specific component libraries

When detected: 1. Acknowledge exactly what they've specified 2. Fill every gap with smart defaults that complement their choices 3. Skip the discovery conversation 4. Generate the full BRAND-IDENTITY.md 5. Still apply ALL enforced best practices (accessibility, responsive, etc.)

---

Reference Brand Library

25 brands across 7 categories. Use the "Feel" to describe brands to users. Use the "Design DNA" internally to derive specific values.

Minimal / Precise

Stripe

• Feel: Precise, confident, no wasted space
• Best for: Financial tools, APIs, B2B platforms
• Design DNA: Cool temperature | Moderate spacing | Moderate radius | Subtle shadows | Geometric type | Medium weight | High contrast

Linear

• Feel: Fast, quiet, stays out of your way
• Best for: Dev tools, productivity apps, task management
• Design DNA: Cool temperature | Moderate spacing | Moderate radius | Minimal shadows | Geometric type | Light weight | High contrast

Vercel

• Feel: Bold, dark, futuristic
• Best for: Technical platforms, dev tools, infrastructure
• Design DNA: Cool temperature | Moderate spacing | Sharp radius | No shadows | Geometric type | Heavy weight | High contrast

Superhuman

• Feel: Luxurious, dense, keyboard-driven
• Best for: Premium productivity, power-user tools
• Design DNA: Cool temperature | Dense spacing | Moderate radius | Subtle shadows | Geometric type | Medium weight | High contrast

Warm / Approachable

Notion

• Feel: Warm, inviting, like a blank notebook
• Best for: Creative tools, knowledge work, wikis
• Design DNA: Warm temperature | Spacious spacing | Moderate radius | Subtle shadows | Humanist type | Light weight | Moderate contrast

Basecamp

• Feel: Honest, unpretentious, handmade feel
• Best for: Small business tools, project management
• Design DNA: Warm temperature | Spacious spacing | Rounded radius | No shadows | Humanist type | Medium weight | Moderate contrast

Mailchimp

• Feel: Quirky, fun, doesn't take itself too seriously
• Best for: Small business marketing, email tools
• Design DNA: Warm temperature | Spacious spacing | Rounded radius | Subtle shadows | Humanist type | Medium weight | Moderate contrast

Canva

• Feel: Bright, encouraging, "you can do this"
• Best for: Creative tools for non-designers, visual editors
• Design DNA: Warm temperature | Moderate spacing | Rounded radius | Subtle shadows | Geometric type | Medium weight | High contrast

Collaborative / Social

Slack

• Feel: Friendly, colorful, energetic
• Best for: Team communication, workplace tools
• Design DNA: Warm temperature | Moderate spacing | Rounded radius | Subtle shadows | Humanist type | Medium weight | High contrast

Figma

• Feel: Playful, creative, multiplayer
• Best for: Design collaboration, real-time editing
• Design DNA: Neutral temperature | Moderate spacing | Rounded radius | Subtle shadows | Geometric type | Medium weight | High contrast

Loom

• Feel: Personal, casual, lightweight
• Best for: Async video, screen recording, communication
• Design DNA: Warm temperature | Spacious spacing | Rounded radius | Moderate shadows | Humanist type | Light weight | Moderate contrast

Discord

• Feel: Bold, youthful, expressive
• Best for: Community platforms, social features, gaming
• Design DNA: Cool temperature | Moderate spacing | Rounded radius | Moderate shadows | Geometric type | Heavy weight | High contrast

Trust / Authority

Plaid

• Feel: Trustworthy, institutional, safe
• Best for: Fintech infrastructure, banking integrations
• Design DNA: Cool temperature | Moderate spacing | Moderate radius | No shadows | Geometric type | Medium weight | High contrast

Gusto

• Feel: Approachable authority, grown-up but not stuffy
• Best for: HR, payroll, compliance tools
• Design DNA: Warm temperature | Spacious spacing | Rounded radius | Subtle shadows | Humanist type | Medium weight | Moderate contrast

Mercury

• Feel: Sleek, premium, quietly confident
• Best for: Business banking, financial dashboards
• Design DNA: Cool temperature | Spacious spacing | Moderate radius | Subtle shadows | Geometric type | Light weight | High contrast

Wise

• Feel: Transparent, clean, no-nonsense
• Best for: International finance, money transfer, transparent pricing
• Design DNA: Cool temperature | Spacious spacing | Moderate radius | No shadows | Geometric type | Light weight | High contrast

Calm / Wellness

Calm

• Feel: Soft, spacious, like a deep breath
• Best for: Meditation, wellness, self-care
• Design DNA: Warm temperature | Spacious spacing | Rounded radius | No shadows | Humanist type | Light weight | Low contrast

Headspace

• Feel: Warm, illustrated, gentle
• Best for: Mental health, habit tracking, guided experiences
• Design DNA: Warm temperature | Spacious spacing | Pill radius | No shadows | Geometric type | Medium weight | Low contrast

Apple Health

• Feel: Clinical but friendly, data-forward
• Best for: Health, fitness tracking, medical
• Design DNA: Neutral temperature | Moderate spacing | Rounded radius | No shadows | Geometric type | Light weight | Moderate contrast

Bold / Consumer

Spotify

• Feel: Dark, vibrant, high-energy
• Best for: Entertainment, media, content platforms
• Design DNA: Cool temperature | Moderate spacing | Pill radius | No shadows | Geometric type | Heavy weight | High contrast

Duolingo

• Feel: Playful, cartoonish, addictive
• Best for: Education, gamified experiences, learning
• Design DNA: Warm temperature | Spacious spacing | Rounded radius | Moderate shadows | Geometric type | Heavy weight | High contrast

Robinhood

• Feel: Simple, green, "investing is easy"
• Best for: Consumer fintech, simplified complex tools
• Design DNA: Neutral temperature | Spacious spacing | Moderate radius | No shadows | Geometric type | Light weight | Moderate contrast

Data / Dashboard

Datadog

• Feel: Dense, dark, information-rich
• Best for: Monitoring, infrastructure, observability
• Design DNA: Cool temperature | Dense spacing | Sharp radius | No shadows | Monospace-accented type | Medium weight | Moderate contrast

Mixpanel

• Feel: Clean data viz, chart-forward
• Best for: Analytics, reporting, metrics dashboards
• Design DNA: Cool temperature | Moderate spacing | Moderate radius | Subtle shadows | Geometric type | Light weight | Moderate contrast

Airtable

• Feel: Colorful, organized, approachable complexity
• Best for: Structured data, spreadsheet-like tools, databases
• Design DNA: Warm temperature | Moderate spacing | Rounded radius | Subtle shadows | Geometric type | Medium weight | High contrast

---

Output Template

This is the exact structure for the generated BRAND-IDENTITY.md. Every field must be filled — no optional sections, no "TBD," no placeholders. Every gap is an invitation for AI to fill with generic defaults. Leave no gaps.

````markdown

Brand Identity — [Product Name]

Generated by brand-identity-generator. This file is the single source of truth for all visual decisions.

Every AI tool building UI for this project should read this file first.

---

1. Brand Context

• Product: [What it is — one sentence]
• Audience: [Who uses it, in what context, how often, on what devices]
• Feel: [Plain-English feeling — 1-2 sentences]
• Reference brands: [1-2 brands] — [what to take from each, specifically]

---

2. Colors

Primary

Secondary Accent

Neutral Scale

Semantic Colors

Surface Colors

Dark Mode

[Either provide a full mapping for dark mode:]

[...complete mapping for every token above]

[Or explicitly opt out:]

Dark mode not supported. Do not generate dark mode variants.

---

3. Typography

Font Stack

• Headings: [Font Name], [fallback stack]
• Body: [Font Name], [fallback stack]
• Monospace: [Font Name], [fallback stack] (if applicable — omit if no code/data display)

Type Scale

Typography Rules

• Max line width: 65ch for body text, 45ch for narrow columns
• Min body size: 16px — never go smaller for body text
• Font loading: Use font-display: swap and <link rel="preload"> for custom fonts

---

4. Spacing & Layout

Base Unit

• Base: Xpx

Spacing Scale

All values are multiples of the base unit.

Component Padding

Breakpoints

Container

---

5. Shape & Elevation

Corner Radius Scale

Shadow Scale

Elevation Rules

• Use shadow for floating elements (dropdowns, modals, tooltips)
• Use border for inline elements (cards, inputs, dividers)
• Use background change for state changes (hover, selected)
• Never combine shadow + heavy border on the same element

Borders

---

6. Iconography

• Library: [Icon library name — e.g., Lucide, Heroicons, Phosphor]
• Style: [Outline / Solid / Duotone] — use ONE style consistently

Icon Sizes

Icon Rules

• Stroke weight: [X.X]px
• Color: inherits text color by default. Use currentColor.
• Never mix icon libraries. Pick one and use it everywhere.
• Icons in buttons go left of text. Icons in nav go left of label.

---

7. Animation & Motion

Default Transition

• Duration: [XXX]ms
• Easing: [easing function — e.g., cubic-bezier(0.4, 0, 0.2, 1)]

What Animates

• Button hover/active state changes
• Dropdown open/close
• Modal enter/exit
• Toast slide-in and fade-out
• Focus ring appearance
• Color and background-color transitions
• Accordion expand/collapse

What Does NOT Animate

• Page layouts or grid shifts
• Font size or weight changes
• Border-radius changes
• Box-shadow changes (except focus ring)
• Scroll position (use native smooth scroll)

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

• Always support prefers-reduced-motion
• No decorative animations unless explicitly specified in this document

---

8. Component Specs (Summary)

This section specifies the brand-level token values for key components. For detailed component behavior, patterns, and implementation guidance, see the ui-patterns skill.

Key Component Tokens

Specify values for these components using the brand tokens from sections above:

State coverage requirements:

• Interactive (Button, Input, Nav items): default, hover, active, focus, disabled, loading, error
• Container (Card, Modal): default, hover (if clickable), selected, disabled, loading (skeleton)
• Status (Badge, Toast): variant-based — not interactive-state-based
• Data (Table): row default, hover, selected, header, empty state, loading (skeleton)

---

9. Anti-Patterns

These are explicitly banned. Any AI tool reading this file should treat these as hard rules.

1. No gratuitous gradients — Solid colors only unless explicitly specified above 2. No text shadows — Never apply shadow to text elements 3. No stock photography — Use icons, illustrations, or user-generated content instead 4. No AI-generated hero images — They look generic and undermine trust 5. No decorative borders — Borders serve structure (separation, containment), not decoration 6. Never mix icon libraries — Use [specified library] exclusively 7. No color as sole indicator — Always pair color with text, icon, or pattern (accessibility requirement) 8. No placeholder-only labels — Every input needs a visible label above it; placeholders are supplemental 9. No pure black (#000000) backgrounds — Use [neutral-950 hex] instead 10. No pure white (#FFFFFF) on dark backgrounds — Use [neutral-50 hex] for softer contrast 11. No more than 2 font families — Heading + body (+ mono if needed for code) 12. No font sizes below 12px — Caption and overline can go to 12px but never smaller 13. No horizontal scrolling — Content must fit viewport width at every breakpoint 14. [Brand-specific anti-pattern based on chosen reference — e.g., "No rounded corners over Xpx" for a Stripe-like brand, or "No dark mode" for a Calm-like brand] 15. [Brand-specific anti-pattern] 16. [Brand-specific anti-pattern]

---

10. Accessibility (Enforced)

These are not suggestions. They are requirements. Every component and page must comply.

Color Contrast (WCAG 2.1 AA)

• Normal text (< 24px / < 18.66px bold): 4.5:1 minimum contrast ratio
• Large text (>= 24px / >= 18.66px bold): 3:1 minimum contrast ratio
• UI components and graphical objects: 3:1 minimum

Contrast Ratios for This Brand

Interactive Elements

• Focus indicators on ALL interactive elements (buttons, links, inputs, selects, checkboxes)
• Focus ring: 2px solid [primary hex], 2px offset — visible on both light and dark backgrounds
• Touch targets: minimum 44x44px on all interactive elements
• Color not sole indicator: Never use color alone to communicate state. Pair with icon, text, or pattern.

Forms

• Visible labels above every input (not placeholder-only)
• Error messages appear below the field with icon + text (not color alone)
• Required fields marked with text "(required)" — not asterisk only
• Autocomplete attributes on all standard fields (name, email, address, etc.)

Structure

• Heading hierarchy: h1 > h2 > h3 > h4 — never skip levels
• Skip navigation link as first focusable element on every page
• Landmark roles: main, nav, footer, aside — used correctly
• Alt text: All meaningful images have descriptive alt text. Decorative images use alt=""
• Language attribute: <html lang="en"> (or appropriate language)

---

11. Responsive Design (Enforced)

Approach

• Mobile-first: Base styles are mobile. Layer up with min-width media queries.

Breakpoints

Fluid Typography

Use clamp() for responsive type sizing:

--font-display: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
--font-h1: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
--font-h2: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
--font-h3: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
--font-body-lg: clamp(X.Xrem, Xvw + Xrem, X.Xrem);

Mobile Requirements

• No horizontal scroll at any viewport width
• Touch targets: 44px minimum on mobile
• Input font size: 16px minimum (prevents iOS zoom)
• Thumb-friendly zones for primary actions

Navigation Transformation

• Desktop (>= [lg breakpoint]): [sidebar/topnav as specified in component specs]
• Tablet ([md] to [lg]): [collapsed sidebar / topnav with overflow menu]
• Mobile (< [md]): [hamburger menu / bottom tab bar / drawer nav]

Images

• max-width: 100% on all images
• Use srcset and sizes for responsive images
• Provide WebP with fallback
• Lazy load below-the-fold images: loading="lazy"

Container

• Max width: [xl container max-width]
• Auto side margins for centering
• Horizontal padding: [space-4] on mobile, [space-6] on desktop

````

---

12. Application Examples

These examples use actual values from the sections above — not placeholders. They show how the system comes together in real components.

For each example, provide both CSS custom properties AND Tailwind utility classes.

Example format (follow this pattern for all 8):

Primary + secondary button side by side:

/* CSS Custom Properties */
.btn-primary {
  background-color: var(--color-primary);        /* #XXXXXX from Section 2 */
  color: var(--color-primary-text);               /* #XXXXXX from Section 8 Button table */
  padding: var(--space-3) var(--space-5);          /* Xpx Xpx from Section 4 */
  border-radius: var(--radius-default);            /* Xpx from Section 5 */
  font-weight: var(--font-weight-button);          /* XXX from Section 8 */
  font-size: var(--font-body);                     /* 1rem from Section 3 */
  height: Xpx;                                     /* from Section 8 */
  transition: background-color var(--transition-duration) var(--transition-easing);
}
.btn-primary:hover { background-color: #XXXXXX; }  /* from Section 8 Hover row */
.btn-primary:focus-visible {
  outline: 2px solid #XXXXXX;                      /* from Section 8 Focus row */
  outline-offset: 2px;
}

<!-- Tailwind -->
<div class="flex gap-[Xpx]">
  <button class="bg-[#XXXXXX] text-[#XXXXXX] px-[Xpx] py-[Xpx] rounded-[Xpx] font-[XXX] h-[Xpx] hover:bg-[#XXXXXX] focus-visible:outline-2 focus-visible:outline-[#XXXXXX] focus-visible:outline-offset-2">
    Primary Action
  </button>
  <button class="bg-[#XXXXXX] text-[#XXXXXX] border border-[#XXXXXX] px-[Xpx] py-[Xpx] rounded-[Xpx] font-[XXX] h-[Xpx] hover:bg-[#XXXXXX]">
    Secondary Action
  </button>
</div>

Required examples (follow the format above for each):

1. Primary + secondary button side by side — button variants with correct spacing 2. Card with heading, body text, and action button — card, typography, and button integration 3. Form with label, input, helper text, and error state — form field in both valid and error states 4. Page header with logo area, navigation, and CTA button — nav and layout integration 5. Data table row with status badge and action buttons — table, badge, and button together 6. Empty state with icon, message, and CTA — empty state pattern with correct spacing 7. Error state (inline field error + full-page error) — both error display variants 8. Modal with header, body content, and action buttons — modal with correct padding and button placement

Every value in these examples must come from a specific section above. No invented values.

---

Logo Guidance

MVP Logo

• Use text-only for MVP. Your product name in your heading font at display weight is a logo.
• Create a simple favicon: first letter of your product on your primary color background.
• Use an SVG for crispness at all sizes.

Versions Needed

When to Invest in a Real Logo

• After product-market fit (not before)
• When you're embarrassed showing the text logo to potential customers
• When you have budget for a designer ($500-2000 range)
• Never let logo design block your launch

---

What You Decide vs. What AI Implements

Rule: You describe the destination. AI drives.

---

Common Mistakes

---

Quality Gate

Before writing the final BRAND-IDENTITY.md, verify every item:

• [ ] All 12 sections fully populated — no "TBD," no placeholders, no empty cells
• [ ] Every color pairing listed in Section 10 passes WCAG 2.1 AA (4.5:1 for normal text, 3:1 for large text)
• [ ] All component states specified (default, hover, active, focus, disabled, loading, error as applicable)
• [ ] Anti-patterns list has 16+ items including at least 3 brand-specific entries
• [ ] Fluid typography clamp() values produce correct sizes at 320px and 1440px viewport widths
• [ ] Spacing scale is internally consistent (based on base unit, no arbitrary jumps)
• [ ] Application examples in Section 12 use actual hex values, spacing, and font specs — not placeholders
• [ ] Font loading strategy specified (font-display: swap, preload)
• [ ] Dark mode either fully mapped (every token) or explicitly opted out with the exact phrase "Dark mode not supported. Do not generate dark mode variants."
• [ ] All accessibility requirements from Section 10 are present and filled in
• [ ] Contrast ratio table has at least 8 pairings calculated
• [ ] Touch targets specified as 44px minimum in both Section 10 and Section 11
• [ ] Breakpoint values are consistent between Section 4 and Section 11
• [ ] Icon library specified and "never mix" rule included
• [ ] Reduced motion CSS included in Section 7

---

Related Skills

Once the brand identity is generated, these skills use the tokens to build the actual UI:

• beautify — How to apply these tokens beautifully (visual hierarchy, whitespace, composition)
• ui-patterns — Component implementation and page layouts using these tokens
• motion-polish — Animation timing and micro-interactions that match the brand personality
• design-review — Quality gate to audit whether the UI correctly implements this identity