Use this skill when the user needs to create a visual brand identity for their product. Generates a comprehensive BRAND-IDENTITY.md file for the project root. Covers colors, typography, spacing, components, accessibility, and responsive design — with no gaps for AI to fill with generic defaults.
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:
Acknowledge exactly what they've specified
Fill every gap with smart defaults that complement their choices
Skip the discovery conversation
Generate the full BRAND-IDENTITY.md
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
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.
# 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
| State | Hex | Usage |
|-------|-----|-------|
| Default | #XXXXXX | Primary buttons, links, active indicators |
| Hover | #XXXXXX | Darkened/lightened on hover |
| Active | #XXXXXX | While being pressed |
| Disabled | #XXXXXX | Disabled primary elements (pair with opacity 0.5) |
### Secondary Accent
| State | Hex | Usage |
|-------|-----|-------|
| Default | #XXXXXX | Secondary buttons, accent elements |
| Hover | #XXXXXX | Hover state |
| Active | #XXXXXX | Active/pressed state |
| Disabled | #XXXXXX | Disabled state |
### Neutral Scale
| Shade | Hex | Usage |
|-------|-----|-------|
| 50 | #XXXXXX | Page backgrounds, subtle fills |
| 100 | #XXXXXX | Card backgrounds, hover states on white |
| 150 | #XXXXXX | Dividers on light backgrounds |
| 200 | #XXXXXX | Input borders, secondary dividers |
| 300 | #XXXXXX | Disabled text, placeholder text |
| 400 | #XXXXXX | Icon default color, helper text |
| 500 | #XXXXXX | Secondary text, labels |
| 600 | #XXXXXX | Body text on light backgrounds |
| 700 | #XXXXXX | Strong text, emphasis |
| 800 | #XXXXXX | Headings |
| 900 | #XXXXXX | Primary text, highest contrast |
| 950 | #XXXXXX | Near-black, use sparingly |
### Semantic Colors
| Role | Text | Background | Border |
|------|------|------------|--------|
| Success | #XXXXXX | #XXXXXX | #XXXXXX |
| Warning | #XXXXXX | #XXXXXX | #XXXXXX |
| Error | #XXXXXX | #XXXXXX | #XXXXXX |
| Info | #XXXXXX | #XXXXXX | #XXXXXX |
### Surface Colors
| Surface | Hex | Usage |
|---------|-----|-------|
| Page background | #XXXXXX | `<body>` background |
| Card background | #XXXXXX | Card, panel, popover backgrounds |
| Elevated surface | #XXXXXX | Dropdowns, tooltips, floating elements |
| Overlay backdrop | rgba(X,X,X,0.X) | Behind modals and drawers |
### Dark Mode
[Either provide a full mapping for dark mode:]
| Light token | Dark equivalent |
|-------------|-----------------|
| Page background #XXXXXX | #XXXXXX |
| Card background #XXXXXX | #XXXXXX |
| Primary text #XXXXXX | #XXXXXX |
| Secondary text #XXXXXX | #XXXXXX |
| Border #XXXXXX | #XXXXXX |
| Primary #XXXXXX | #XXXXXX (adjust for dark bg contrast) |
[...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
| Role | Size (rem / px) | Weight | Line Height | Letter Spacing |
|------|-----------------|--------|-------------|----------------|
| Display | X.Xrem / XXpx | XXX | 1.1 | -0.02em |
| H1 | X.Xrem / XXpx | XXX | 1.2 | -0.01em |
| H2 | X.Xrem / XXpx | XXX | 1.25 | -0.005em |
| H3 | X.Xrem / XXpx | XXX | 1.3 | 0 |
| H4 | X.Xrem / XXpx | XXX | 1.35 | 0 |
| Body Large | X.Xrem / XXpx | XXX | 1.6 | 0 |
| Body | 1rem / 16px | 400 | 1.5 | 0 |
| Body Small | X.Xrem / XXpx | XXX | 1.5 | 0 |
| Caption | X.Xrem / XXpx | XXX | 1.4 | 0.01em |
| Overline | X.Xrem / XXpx | XXX | 1.4 | 0.05em |
### 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.
| Token | Value | Common Use |
|-------|-------|------------|
| space-0 | 0px | No spacing |
| space-1 | Xpx | Tight inline spacing, icon-to-text gap |
| space-2 | Xpx | Input padding (vertical), badge padding |
| space-3 | Xpx | Button padding (vertical), list item gap |
| space-4 | Xpx | Card padding (internal), form field gap |
| space-5 | Xpx | Group separation, field-to-field gap |
| space-6 | Xpx | Section padding, card spacing |
| space-8 | Xpx | Large section breaks |
| space-10 | Xpx | Page-level vertical rhythm |
| space-12 | Xpx | Major content separations |
| space-16 | Xpx | Hero sections, page-level spacing |
| space-20 | Xpx | Full-page section gaps |
| space-24 | Xpx | Maximum spacing (hero to content) |
### Component Padding
| Component | Padding |
|-----------|---------|
| Button (sm) | Xpx Xpx |
| Button (md) | Xpx Xpx |
| Button (lg) | Xpx Xpx |
| Input | Xpx Xpx |
| Card | Xpx |
| Modal | Xpx |
| Section spacing | Xpx (between major page sections) |
### Breakpoints
| Name | Min Width | Columns | Gutter |
|------|-----------|---------|--------|
| sm | XXXpx | X | Xpx |
| md | XXXpx | X | Xpx |
| lg | XXXpx | XX | Xpx |
| xl | XXXXpx | XX | Xpx |
### Container
| Breakpoint | Max Width |
|------------|-----------|
| sm | 100% (padding Xpx) |
| md | XXXpx |
| lg | XXXXpx |
| xl | XXXXpx |
---
## 5. Shape & Elevation
### Corner Radius Scale
| Token | Value | Usage |
|-------|-------|-------|
| radius-none | 0px | Tables, full-bleed elements |
| radius-sm | Xpx | Badges, chips, small elements |
| radius-default | Xpx | Buttons, inputs |
| radius-md | Xpx | Cards, dropdowns |
| radius-lg | Xpx | Modals, large panels |
| radius-xl | Xpx | Feature cards, hero sections |
| radius-full | 9999px | Avatars, pill buttons, indicators |
### Shadow Scale
| Token | CSS Value | Usage |
|-------|-----------|-------|
| shadow-none | none | Flat elements, bordered cards |
| shadow-xs | 0 1px 2px rgba(X,X,X,0.XX) | Subtle lift, input focus |
| shadow-sm | 0 1px 3px rgba(X,X,X,0.XX), 0 1px 2px rgba(X,X,X,0.XX) | Cards, buttons |
| shadow-md | 0 4px 6px rgba(X,X,X,0.XX), 0 2px 4px rgba(X,X,X,0.XX) | Dropdowns, popovers |
| shadow-lg | 0 10px 15px rgba(X,X,X,0.XX), 0 4px 6px rgba(X,X,X,0.XX) | Modals, drawers |
| shadow-xl | 0 20px 25px rgba(X,X,X,0.XX), 0 8px 10px rgba(X,X,X,0.XX) | Floating panels |
### 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
| Token | Value |
|-------|-------|
| border-thin | 1px solid [neutral-200 hex] |
| border-default | 1px solid [neutral-300 hex] |
| border-heavy | 2px solid [neutral-400 hex] |
---
## 6. Iconography
- **Library:** [Icon library name — e.g., Lucide, Heroicons, Phosphor]
- **Style:** [Outline / Solid / Duotone] — use ONE style consistently
### Icon Sizes
| Context | Size | Notes |
|---------|------|-------|
| Inline (with text) | 16px | Aligns with body text |
| Button icon | 18px | Pairs with button text |
| Navigation | 20px | Sidebar and nav items |
| Decorative / empty state | 24px | Standalone icons, illustrations |
### 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
```css
@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:
| Component | Key Properties to Specify |
|-----------|--------------------------|
| Button (primary, secondary, ghost, destructive) | Background, text color, border, height, padding, radius, font weight, hover/active/focus/disabled states |
| Input | Background, border, text/placeholder colors, height, padding, radius, focus ring, error state |
| Card | Background, border, shadow, radius, padding, hover state (if clickable) |
| Badge (default, success, warning, error, info) | Background, text color, padding, radius, font size/weight |
| Toast (success, error, warning, info) | Background, text color, icon, border-left, shadow, auto-dismiss duration |
| Modal | Backdrop color, background, radius, shadow, padding, max-width, animation |
| Table | Header style, row height/border/hover, cell padding, sort indicators |
| Navigation | Style (sidebar/topnav), background, dimensions, item states, mobile behavior |
**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
| Pairing | Foreground | Background | Ratio | Pass? |
|---------|------------|------------|-------|-------|
| Body text on page bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Body text on card bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Primary button text on primary bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Secondary text on page bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Placeholder on input bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Link text on page bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Error text on error bg | #XXXXXX | #XXXXXX | XX:1 | AA |
| Success text on success bg | #XXXXXX | #XXXXXX | XX:1 | AA |
### 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
| Name | Value | Target |
|------|-------|--------|
| sm | XXXpx | Large phones, landscape |
| md | XXXpx | Tablets |
| lg | XXXpx | Laptops, small desktops |
| xl | XXXXpx | Large desktops |
### Fluid Typography
Use `clamp()` for responsive type sizing:
```css
--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.
Required examples (follow the format above for each):
Primary + secondary button side by side — button variants with correct spacing
Card with heading, body text, and action button — card, typography, and button integration
Form with label, input, helper text, and error state — form field in both valid and error states
Page header with logo area, navigation, and CTA button — nav and layout integration
Data table row with status badge and action buttons — table, badge, and button together
Empty state with icon, message, and CTA — empty state pattern with correct spacing
Error state (inline field error + full-page error) — both error display variants
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
Version
Where It Goes
Notes
Full logo (text)
Header, login page
Your product name in heading font
Icon only
Favicon, mobile app icon
Single letter or simple mark
Dark background variant
Dark nav, footer
Ensure contrast
Light background variant
Light pages, emails
Default version
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
You Decide
AI Implements
"I want it to feel like Linear"
Complete color, type, and spacing system
"Warmer, more approachable"
Adjusts temperature, radius, type to humanist
"I hate that green"
Swaps green for next-best semantic color
"Can the buttons be softer?"
Increases radius, reduces weight, adjusts shadow
"I need dark mode"
Full dark mode token mapping
"This is for enterprise"
Trust-oriented palette, geometric type, high contrast
Rule: You describe the destination. AI drives.
Common Mistakes
Mistake
What Happens
Fix
Skipping brand identity, letting AI choose
Every page looks different, AI fills gaps with random defaults
Generate BRAND-IDENTITY.md first
Specifying colors but not states
Hover, active, disabled states get invented randomly
This template specifies every state
"Just make it look modern"
AI defaults to generic SaaS — indistinguishable from templates
Pick reference brands instead
Choosing colors you personally like
Your brand might clash with accessibility or audience expectations
React to proposals based on your audience, not personal taste
Skipping dark mode decision
Some AI tools generate dark mode anyway, others don't
Explicitly opt in or out
No anti-patterns list
AI adds gradients, shadows, and decorations "to make it pop"
Anti-patterns section bans the usual suspects
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
1---2name: brand-identity-generator3description: Use this skill when the user needs to create a visual brand identity for their product. Generates a comprehensive BRAND-IDENTITY.md file for the project root. Covers colors, typography, spacing, components, accessibility, and responsive design — with no gaps for AI to fill with generic defaults.4---56# Brand Identity Generator
78Generate 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.
910**Two modes:**
11- **Guided discovery** (default) — Ask one question, propose a full identity, refine from reactions. The user never needs design vocabulary.
12- **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.
1314The 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.
1516> Logo guidance, decision frameworks, and common branding mistakes are included at the end.
1718---
1920## Discovery Process
2122**Core principle: The user should never need to use design vocabulary. They react to your proposals. You do the heavy lifting.**
2324### Default Path (Guided Discovery)
2526**Step 1 — Ask ONE question:**
2728> "What are you building and who is it for?"
2930That's it. One question. Do not ask about colors, fonts, or design preferences.
3132**Step 2 — Select reference brands:**
3334Based on their answer, select the 1-2 closest reference brands from the Reference Brand Library below. Use the "Best for" field to match.
3536**Step 3 — Propose a complete identity in plain English:**
3738Write a human-readable recommendation. Talk about feeling, not specs. Example tone:
3940> "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..."
4142Then present a summary covering:
43- Overall feel in plain words
44- Which reference brands you're drawing from and why
45- Color direction (warm/cool, light/dark, accent character)
46- Typography character (not font names — "clean and precise" vs "warm and readable")
47- Density and spacing feel
48- Component personality (sharp and fast vs soft and friendly)
4950Do NOT present the full 12-section spec yet. Keep it conversational.
5152**Step 4 — User reacts:**
5354They might say things like:
55- "Love it"
56- "Warmer"
57- "I hate green"
58- "More like Notion"
59- "Can we make it feel more premium?"
60- "Less corporate"
6162Adjust and re-propose. This loop usually takes 1-3 rounds.
6364**Step 5 — Generate the full BRAND-IDENTITY.md:**
6566Once the user approves, generate the complete output using the Output Template below. Write it to the project root as `BRAND-IDENTITY.md`.
6768### Expert Path
6970Detect when the user provides specific design tokens — hex codes, font names, radius values, spacing scales. Signs of an expert:
71- They paste CSS custom properties or Tailwind config
72- They name specific fonts ("Inter for headings, Source Sans for body")
73- They provide hex codes
74- They reference specific component libraries
7576When detected:
771. Acknowledge exactly what they've specified
782. Fill every gap with smart defaults that complement their choices
793. Skip the discovery conversation
804. Generate the full BRAND-IDENTITY.md
815. Still apply ALL enforced best practices (accessibility, responsive, etc.)
8283---
8485## Reference Brand Library
868725 brands across 7 categories. Use the "Feel" to describe brands to users. Use the "Design DNA" internally to derive specific values.
8889### Minimal / Precise
9091**Stripe**
92- Feel: Precise, confident, no wasted space
93- Best for: Financial tools, APIs, B2B platforms
94- Design DNA: Cool temperature | Moderate spacing | Moderate radius | Subtle shadows | Geometric type | Medium weight | High contrast
9596**Linear**
97- Feel: Fast, quiet, stays out of your way
98- Best for: Dev tools, productivity apps, task management
99- Design DNA: Cool temperature | Moderate spacing | Moderate radius | Minimal shadows | Geometric type | Light weight | High contrast
100101**Vercel**
102- Feel: Bold, dark, futuristic
103- Best for: Technical platforms, dev tools, infrastructure
104- Design DNA: Cool temperature | Moderate spacing | Sharp radius | No shadows | Geometric type | Heavy weight | High contrast
105106**Superhuman**
107- Feel: Luxurious, dense, keyboard-driven
108- Best for: Premium productivity, power-user tools
109- Design DNA: Cool temperature | Dense spacing | Moderate radius | Subtle shadows | Geometric type | Medium weight | High contrast
110111### Warm / Approachable
112113**Notion**
114- Feel: Warm, inviting, like a blank notebook
115- Best for: Creative tools, knowledge work, wikis
116- Design DNA: Warm temperature | Spacious spacing | Moderate radius | Subtle shadows | Humanist type | Light weight | Moderate contrast
117118**Basecamp**
119- Feel: Honest, unpretentious, handmade feel
120- Best for: Small business tools, project management
121- Design DNA: Warm temperature | Spacious spacing | Rounded radius | No shadows | Humanist type | Medium weight | Moderate contrast
122123**Mailchimp**
124- Feel: Quirky, fun, doesn't take itself too seriously
125- Best for: Small business marketing, email tools
126- Design DNA: Warm temperature | Spacious spacing | Rounded radius | Subtle shadows | Humanist type | Medium weight | Moderate contrast
127128**Canva**
129- Feel: Bright, encouraging, "you can do this"
130- Best for: Creative tools for non-designers, visual editors
131- Design DNA: Warm temperature | Moderate spacing | Rounded radius | Subtle shadows | Geometric type | Medium weight | High contrast
132133### Collaborative / Social
134135**Slack**
136- Feel: Friendly, colorful, energetic
137- Best for: Team communication, workplace tools
138- Design DNA: Warm temperature | Moderate spacing | Rounded radius | Subtle shadows | Humanist type | Medium weight | High contrast
139140**Figma**
141- Feel: Playful, creative, multiplayer
142- Best for: Design collaboration, real-time editing
143- Design DNA: Neutral temperature | Moderate spacing | Rounded radius | Subtle shadows | Geometric type | Medium weight | High contrast
144145**Loom**
146- Feel: Personal, casual, lightweight
147- Best for: Async video, screen recording, communication
148- Design DNA: Warm temperature | Spacious spacing | Rounded radius | Moderate shadows | Humanist type | Light weight | Moderate contrast
149150**Discord**
151- Feel: Bold, youthful, expressive
152- Best for: Community platforms, social features, gaming
153- Design DNA: Cool temperature | Moderate spacing | Rounded radius | Moderate shadows | Geometric type | Heavy weight | High contrast
154155### Trust / Authority
156157**Plaid**
158- Feel: Trustworthy, institutional, safe
159- Best for: Fintech infrastructure, banking integrations
160- Design DNA: Cool temperature | Moderate spacing | Moderate radius | No shadows | Geometric type | Medium weight | High contrast
161162**Gusto**
163- Feel: Approachable authority, grown-up but not stuffy
164- Best for: HR, payroll, compliance tools
165- Design DNA: Warm temperature | Spacious spacing | Rounded radius | Subtle shadows | Humanist type | Medium weight | Moderate contrast
166167**Mercury**
168- Feel: Sleek, premium, quietly confident
169- Best for: Business banking, financial dashboards
170- Design DNA: Cool temperature | Spacious spacing | Moderate radius | Subtle shadows | Geometric type | Light weight | High contrast
171172**Wise**
173- Feel: Transparent, clean, no-nonsense
174- Best for: International finance, money transfer, transparent pricing
175- Design DNA: Cool temperature | Spacious spacing | Moderate radius | No shadows | Geometric type | Light weight | High contrast
176177### Calm / Wellness
178179**Calm**
180- Feel: Soft, spacious, like a deep breath
181- Best for: Meditation, wellness, self-care
182- Design DNA: Warm temperature | Spacious spacing | Rounded radius | No shadows | Humanist type | Light weight | Low contrast
183184**Headspace**
185- Feel: Warm, illustrated, gentle
186- Best for: Mental health, habit tracking, guided experiences
187- Design DNA: Warm temperature | Spacious spacing | Pill radius | No shadows | Geometric type | Medium weight | Low contrast
188189**Apple Health**
190- Feel: Clinical but friendly, data-forward
191- Best for: Health, fitness tracking, medical
192- Design DNA: Neutral temperature | Moderate spacing | Rounded radius | No shadows | Geometric type | Light weight | Moderate contrast
193194### Bold / Consumer
195196**Spotify**
197- Feel: Dark, vibrant, high-energy
198- Best for: Entertainment, media, content platforms
199- Design DNA: Cool temperature | Moderate spacing | Pill radius | No shadows | Geometric type | Heavy weight | High contrast
200201**Duolingo**
202- Feel: Playful, cartoonish, addictive
203- Best for: Education, gamified experiences, learning
204- Design DNA: Warm temperature | Spacious spacing | Rounded radius | Moderate shadows | Geometric type | Heavy weight | High contrast
205206**Robinhood**
207- Feel: Simple, green, "investing is easy"
208- Best for: Consumer fintech, simplified complex tools
209- Design DNA: Neutral temperature | Spacious spacing | Moderate radius | No shadows | Geometric type | Light weight | Moderate contrast
210211### Data / Dashboard
212213**Datadog**
214- Feel: Dense, dark, information-rich
215- Best for: Monitoring, infrastructure, observability
216- Design DNA: Cool temperature | Dense spacing | Sharp radius | No shadows | Monospace-accented type | Medium weight | Moderate contrast
217218**Mixpanel**
219- Feel: Clean data viz, chart-forward
220- Best for: Analytics, reporting, metrics dashboards
221- Design DNA: Cool temperature | Moderate spacing | Moderate radius | Subtle shadows | Geometric type | Light weight | Moderate contrast
222223**Airtable**
224- Feel: Colorful, organized, approachable complexity
225- Best for: Structured data, spreadsheet-like tools, databases
226- Design DNA: Warm temperature | Moderate spacing | Rounded radius | Subtle shadows | Geometric type | Medium weight | High contrast
227228---
229230## Output Template
231232This 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.
233234````markdown
235# Brand Identity — [Product Name]
236237> Generated by brand-identity-generator. This file is the single source of truth for all visual decisions.
238> Every AI tool building UI for this project should read this file first.
239240---
241242## 1. Brand Context
243244- **Product:** [What it is — one sentence]
245- **Audience:** [Who uses it, in what context, how often, on what devices]
246- **Feel:** [Plain-English feeling — 1-2 sentences]
247- **Reference brands:** [1-2 brands] — [what to take from each, specifically]
248249---
250251## 2. Colors
252253### Primary
254| State | Hex | Usage |
255|-------|-----|-------|
256| Default | #XXXXXX | Primary buttons, links, active indicators |
257| Hover | #XXXXXX | Darkened/lightened on hover |
258| Active | #XXXXXX | While being pressed |
259| Disabled | #XXXXXX | Disabled primary elements (pair with opacity 0.5) |
260261### Secondary Accent
262| State | Hex | Usage |
263|-------|-----|-------|
264| Default | #XXXXXX | Secondary buttons, accent elements |
265| Hover | #XXXXXX | Hover state |
266| Active | #XXXXXX | Active/pressed state |
267| Disabled | #XXXXXX | Disabled state |
268269### Neutral Scale
270| Shade | Hex | Usage |
271|-------|-----|-------|
272| 50 | #XXXXXX | Page backgrounds, subtle fills |
273| 100 | #XXXXXX | Card backgrounds, hover states on white |
274| 150 | #XXXXXX | Dividers on light backgrounds |
275| 200 | #XXXXXX | Input borders, secondary dividers |
276| 300 | #XXXXXX | Disabled text, placeholder text |
277| 400 | #XXXXXX | Icon default color, helper text |
278| 500 | #XXXXXX | Secondary text, labels |
279| 600 | #XXXXXX | Body text on light backgrounds |
280| 700 | #XXXXXX | Strong text, emphasis |
281| 800 | #XXXXXX | Headings |
282| 900 | #XXXXXX | Primary text, highest contrast |
283| 950 | #XXXXXX | Near-black, use sparingly |
284285### Semantic Colors
286| Role | Text | Background | Border |
287|------|------|------------|--------|
288| Success | #XXXXXX | #XXXXXX | #XXXXXX |
289| Warning | #XXXXXX | #XXXXXX | #XXXXXX |
290| Error | #XXXXXX | #XXXXXX | #XXXXXX |
291| Info | #XXXXXX | #XXXXXX | #XXXXXX |
292293### Surface Colors
294| Surface | Hex | Usage |
295|---------|-----|-------|
296| Page background | #XXXXXX | `<body>` background |
297| Card background | #XXXXXX | Card, panel, popover backgrounds |
298| Elevated surface | #XXXXXX | Dropdowns, tooltips, floating elements |
299| Overlay backdrop | rgba(X,X,X,0.X) | Behind modals and drawers |
300301### Dark Mode
302303[Either provide a full mapping for dark mode:]
304305| Light token | Dark equivalent |
306|-------------|-----------------|
307| Page background #XXXXXX | #XXXXXX |
308| Card background #XXXXXX | #XXXXXX |
309| Primary text #XXXXXX | #XXXXXX |
310| Secondary text #XXXXXX | #XXXXXX |
311| Border #XXXXXX | #XXXXXX |
312| Primary #XXXXXX | #XXXXXX (adjust for dark bg contrast) |
313[...complete mapping for every token above]
314315[Or explicitly opt out:]
316317> Dark mode not supported. Do not generate dark mode variants.
318319---
320321## 3. Typography
322323### Font Stack
324- **Headings:** [Font Name], [fallback stack]
325- **Body:** [Font Name], [fallback stack]
326- **Monospace:** [Font Name], [fallback stack] *(if applicable — omit if no code/data display)*
327328### Type Scale
329| Role | Size (rem / px) | Weight | Line Height | Letter Spacing |
330|------|-----------------|--------|-------------|----------------|
331| Display | X.Xrem / XXpx | XXX | 1.1 | -0.02em |
332| H1 | X.Xrem / XXpx | XXX | 1.2 | -0.01em |
333| H2 | X.Xrem / XXpx | XXX | 1.25 | -0.005em |
334| H3 | X.Xrem / XXpx | XXX | 1.3 | 0 |
335| H4 | X.Xrem / XXpx | XXX | 1.35 | 0 |
336| Body Large | X.Xrem / XXpx | XXX | 1.6 | 0 |
337| Body | 1rem / 16px | 400 | 1.5 | 0 |
338| Body Small | X.Xrem / XXpx | XXX | 1.5 | 0 |
339| Caption | X.Xrem / XXpx | XXX | 1.4 | 0.01em |
340| Overline | X.Xrem / XXpx | XXX | 1.4 | 0.05em |
341342### Typography Rules
343- **Max line width:** 65ch for body text, 45ch for narrow columns
344- **Min body size:** 16px — never go smaller for body text
345- **Font loading:** Use `font-display: swap` and `<link rel="preload">` for custom fonts
346347---
348349## 4. Spacing & Layout
350351### Base Unit
352- Base: Xpx
353354### Spacing Scale
355356All values are multiples of the base unit.
357358| Token | Value | Common Use |
359|-------|-------|------------|
360| space-0 | 0px | No spacing |
361| space-1 | Xpx | Tight inline spacing, icon-to-text gap |
362| space-2 | Xpx | Input padding (vertical), badge padding |
363| space-3 | Xpx | Button padding (vertical), list item gap |
364| space-4 | Xpx | Card padding (internal), form field gap |
365| space-5 | Xpx | Group separation, field-to-field gap |
366| space-6 | Xpx | Section padding, card spacing |
367| space-8 | Xpx | Large section breaks |
368| space-10 | Xpx | Page-level vertical rhythm |
369| space-12 | Xpx | Major content separations |
370| space-16 | Xpx | Hero sections, page-level spacing |
371| space-20 | Xpx | Full-page section gaps |
372| space-24 | Xpx | Maximum spacing (hero to content) |
373374### Component Padding
375| Component | Padding |
376|-----------|---------|
377| Button (sm) | Xpx Xpx |
378| Button (md) | Xpx Xpx |
379| Button (lg) | Xpx Xpx |
380| Input | Xpx Xpx |
381| Card | Xpx |
382| Modal | Xpx |
383| Section spacing | Xpx (between major page sections) |
384385### Breakpoints
386| Name | Min Width | Columns | Gutter |
387|------|-----------|---------|--------|
388| sm | XXXpx | X | Xpx |
389| md | XXXpx | X | Xpx |
390| lg | XXXpx | XX | Xpx |
391| xl | XXXXpx | XX | Xpx |
392393### Container
394| Breakpoint | Max Width |
395|------------|-----------|
396| sm | 100% (padding Xpx) |
397| md | XXXpx |
398| lg | XXXXpx |
399| xl | XXXXpx |
400401---
402403## 5. Shape & Elevation
404405### Corner Radius Scale
406| Token | Value | Usage |
407|-------|-------|-------|
408| radius-none | 0px | Tables, full-bleed elements |
409| radius-sm | Xpx | Badges, chips, small elements |
410| radius-default | Xpx | Buttons, inputs |
411| radius-md | Xpx | Cards, dropdowns |
412| radius-lg | Xpx | Modals, large panels |
413| radius-xl | Xpx | Feature cards, hero sections |
414| radius-full | 9999px | Avatars, pill buttons, indicators |
415416### Shadow Scale
417| Token | CSS Value | Usage |
418|-------|-----------|-------|
419| shadow-none | none | Flat elements, bordered cards |
420| shadow-xs | 0 1px 2px rgba(X,X,X,0.XX) | Subtle lift, input focus |
421| shadow-sm | 0 1px 3px rgba(X,X,X,0.XX), 0 1px 2px rgba(X,X,X,0.XX) | Cards, buttons |
422| shadow-md | 0 4px 6px rgba(X,X,X,0.XX), 0 2px 4px rgba(X,X,X,0.XX) | Dropdowns, popovers |
423| shadow-lg | 0 10px 15px rgba(X,X,X,0.XX), 0 4px 6px rgba(X,X,X,0.XX) | Modals, drawers |
424| shadow-xl | 0 20px 25px rgba(X,X,X,0.XX), 0 8px 10px rgba(X,X,X,0.XX) | Floating panels |
425426### Elevation Rules
427- Use **shadow** for floating elements (dropdowns, modals, tooltips)
428- Use **border** for inline elements (cards, inputs, dividers)
429- Use **background change** for state changes (hover, selected)
430- Never combine shadow + heavy border on the same element
431432### Borders
433| Token | Value |
434|-------|-------|
435| border-thin | 1px solid [neutral-200 hex] |
436| border-default | 1px solid [neutral-300 hex] |
437| border-heavy | 2px solid [neutral-400 hex] |
438439---
440441## 6. Iconography
442443- **Library:** [Icon library name — e.g., Lucide, Heroicons, Phosphor]
444- **Style:** [Outline / Solid / Duotone] — use ONE style consistently
445446### Icon Sizes
447| Context | Size | Notes |
448|---------|------|-------|
449| Inline (with text) | 16px | Aligns with body text |
450| Button icon | 18px | Pairs with button text |
451| Navigation | 20px | Sidebar and nav items |
452| Decorative / empty state | 24px | Standalone icons, illustrations |
453454### Icon Rules
455- Stroke weight: [X.X]px
456- Color: inherits text color by default. Use `currentColor`.
457- Never mix icon libraries. Pick one and use it everywhere.
458- Icons in buttons go left of text. Icons in nav go left of label.
459460---
461462## 7. Animation & Motion
463464### Default Transition
465- Duration: [XXX]ms
466- Easing: [easing function — e.g., cubic-bezier(0.4, 0, 0.2, 1)]
467468### What Animates
469- Button hover/active state changes
470- Dropdown open/close
471- Modal enter/exit
472- Toast slide-in and fade-out
473- Focus ring appearance
474- Color and background-color transitions
475- Accordion expand/collapse
476477### What Does NOT Animate
478- Page layouts or grid shifts
479- Font size or weight changes
480- Border-radius changes
481- Box-shadow changes (except focus ring)
482- Scroll position (use native smooth scroll)
483484### Reduced Motion
485```css
486@media (prefers-reduced-motion: reduce) {
487 *, *::before, *::after {
488 animation-duration: 0.01ms !important;
489 animation-iteration-count: 1 !important;
490 transition-duration: 0.01ms !important;
491 }
492}
493```
494495- Always support `prefers-reduced-motion`
496- No decorative animations unless explicitly specified in this document
497498---
499500## 8. Component Specs (Summary)
501502This section specifies the brand-level token values for key components. For detailed component behavior, patterns, and implementation guidance, see the **ui-patterns** skill.
503504### Key Component Tokens
505506Specify values for these components using the brand tokens from sections above:
507508| Component | Key Properties to Specify |
509|-----------|--------------------------|
510| Button (primary, secondary, ghost, destructive) | Background, text color, border, height, padding, radius, font weight, hover/active/focus/disabled states |
511| Input | Background, border, text/placeholder colors, height, padding, radius, focus ring, error state |
512| Card | Background, border, shadow, radius, padding, hover state (if clickable) |
513| Badge (default, success, warning, error, info) | Background, text color, padding, radius, font size/weight |
514| Toast (success, error, warning, info) | Background, text color, icon, border-left, shadow, auto-dismiss duration |
515| Modal | Backdrop color, background, radius, shadow, padding, max-width, animation |
516| Table | Header style, row height/border/hover, cell padding, sort indicators |
517| Navigation | Style (sidebar/topnav), background, dimensions, item states, mobile behavior |
518519**State coverage requirements:**
520- **Interactive** (Button, Input, Nav items): default, hover, active, focus, disabled, loading, error
521- **Container** (Card, Modal): default, hover (if clickable), selected, disabled, loading (skeleton)
522- **Status** (Badge, Toast): variant-based — not interactive-state-based
523- **Data** (Table): row default, hover, selected, header, empty state, loading (skeleton)
524525---
526527## 9. Anti-Patterns
528529These are explicitly banned. Any AI tool reading this file should treat these as hard rules.
5305311. **No gratuitous gradients** — Solid colors only unless explicitly specified above
5322. **No text shadows** — Never apply shadow to text elements
5333. **No stock photography** — Use icons, illustrations, or user-generated content instead
5344. **No AI-generated hero images** — They look generic and undermine trust
5355. **No decorative borders** — Borders serve structure (separation, containment), not decoration
5366. **Never mix icon libraries** — Use [specified library] exclusively
5377. **No color as sole indicator** — Always pair color with text, icon, or pattern (accessibility requirement)
5388. **No placeholder-only labels** — Every input needs a visible label above it; placeholders are supplemental
5399. **No pure black (#000000) backgrounds** — Use [neutral-950 hex] instead
54010. **No pure white (#FFFFFF) on dark backgrounds** — Use [neutral-50 hex] for softer contrast
54111. **No more than 2 font families** — Heading + body (+ mono if needed for code)
54212. **No font sizes below 12px** — Caption and overline can go to 12px but never smaller
54313. **No horizontal scrolling** — Content must fit viewport width at every breakpoint
54414. [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]
54515. [Brand-specific anti-pattern]
54616. [Brand-specific anti-pattern]
547548---
549550## 10. Accessibility (Enforced)
551552These are not suggestions. They are requirements. Every component and page must comply.
553554### Color Contrast (WCAG 2.1 AA)
555- Normal text (< 24px / < 18.66px bold): **4.5:1** minimum contrast ratio
556- Large text (>= 24px / >= 18.66px bold): **3:1** minimum contrast ratio
557- UI components and graphical objects: **3:1** minimum
558559### Contrast Ratios for This Brand
560| Pairing | Foreground | Background | Ratio | Pass? |
561|---------|------------|------------|-------|-------|
562| Body text on page bg | #XXXXXX | #XXXXXX | XX:1 | AA |
563| Body text on card bg | #XXXXXX | #XXXXXX | XX:1 | AA |
564| Primary button text on primary bg | #XXXXXX | #XXXXXX | XX:1 | AA |
565| Secondary text on page bg | #XXXXXX | #XXXXXX | XX:1 | AA |
566| Placeholder on input bg | #XXXXXX | #XXXXXX | XX:1 | AA |
567| Link text on page bg | #XXXXXX | #XXXXXX | XX:1 | AA |
568| Error text on error bg | #XXXXXX | #XXXXXX | XX:1 | AA |
569| Success text on success bg | #XXXXXX | #XXXXXX | XX:1 | AA |
570571### Interactive Elements
572- **Focus indicators** on ALL interactive elements (buttons, links, inputs, selects, checkboxes)
573- Focus ring: 2px solid [primary hex], 2px offset — visible on both light and dark backgrounds
574- **Touch targets:** minimum 44x44px on all interactive elements
575- **Color not sole indicator:** Never use color alone to communicate state. Pair with icon, text, or pattern.
576577### Forms
578- **Visible labels** above every input (not placeholder-only)
579- **Error messages** appear below the field with icon + text (not color alone)
580- **Required fields** marked with text "(required)" — not asterisk only
581- **Autocomplete** attributes on all standard fields (name, email, address, etc.)
582583### Structure
584- **Heading hierarchy:** h1 > h2 > h3 > h4 — never skip levels
585- **Skip navigation link** as first focusable element on every page
586- **Landmark roles:** main, nav, footer, aside — used correctly
587- **Alt text:** All meaningful images have descriptive alt text. Decorative images use `alt=""`
588- **Language attribute:** `<html lang="en">` (or appropriate language)
589590---
591592## 11. Responsive Design (Enforced)
593594### Approach
595- **Mobile-first:** Base styles are mobile. Layer up with min-width media queries.
596597### Breakpoints
598| Name | Value | Target |
599|------|-------|--------|
600| sm | XXXpx | Large phones, landscape |
601| md | XXXpx | Tablets |
602| lg | XXXpx | Laptops, small desktops |
603| xl | XXXXpx | Large desktops |
604605### Fluid Typography
606Use `clamp()` for responsive type sizing:
607```css
608--font-display: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
609--font-h1: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
610--font-h2: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
611--font-h3: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
612--font-body-lg: clamp(X.Xrem, Xvw + Xrem, X.Xrem);
613```
614615### Mobile Requirements
616- No horizontal scroll at any viewport width
617- Touch targets: 44px minimum on mobile
618- Input font size: 16px minimum (prevents iOS zoom)
619- Thumb-friendly zones for primary actions
620621### Navigation Transformation
622- **Desktop (>= [lg breakpoint]):** [sidebar/topnav as specified in component specs]
623- **Tablet ([md] to [lg]):** [collapsed sidebar / topnav with overflow menu]
624- **Mobile (< [md]):** [hamburger menu / bottom tab bar / drawer nav]
625626### Images
627- `max-width: 100%` on all images
628- Use `srcset` and `sizes` for responsive images
629- Provide WebP with fallback
630- Lazy load below-the-fold images: `loading="lazy"`
631632### Container
633- Max width: [xl container max-width]
634- Auto side margins for centering
635- Horizontal padding: [space-4] on mobile, [space-6] on desktop
636````
637638---
639640## 12. Application Examples
641642These examples use actual values from the sections above — not placeholders. They show how the system comes together in real components.
643644For each example, provide both CSS custom properties AND Tailwind utility classes.
645646### Example format (follow this pattern for all 8):
647648**Primary + secondary button side by side:**
649```css
650/* CSS Custom Properties */
651.btn-primary {
652 background-color: var(--color-primary); /* #XXXXXX from Section 2 */
653 color: var(--color-primary-text); /* #XXXXXX from Section 8 Button table */
654 padding: var(--space-3) var(--space-5); /* Xpx Xpx from Section 4 */
655 border-radius: var(--radius-default); /* Xpx from Section 5 */
656 font-weight: var(--font-weight-button); /* XXX from Section 8 */
657 font-size: var(--font-body); /* 1rem from Section 3 */
658 height: Xpx; /* from Section 8 */
659 transition: background-color var(--transition-duration) var(--transition-easing);
660}
661.btn-primary:hover { background-color: #XXXXXX; } /* from Section 8 Hover row */
662.btn-primary:focus-visible {
663 outline: 2px solid #XXXXXX; /* from Section 8 Focus row */
664 outline-offset: 2px;
665}
666```
667```html
668<!-- Tailwind -->
669<div class="flex gap-[Xpx]">
670 <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">
671 Primary Action
672 </button>
673 <button class="bg-[#XXXXXX] text-[#XXXXXX] border border-[#XXXXXX] px-[Xpx] py-[Xpx] rounded-[Xpx] font-[XXX] h-[Xpx] hover:bg-[#XXXXXX]">
674 Secondary Action
675 </button>
676</div>
677```
678679### Required examples (follow the format above for each):
6806811. **Primary + secondary button side by side** — button variants with correct spacing
6822. **Card with heading, body text, and action button** — card, typography, and button integration
6833. **Form with label, input, helper text, and error state** — form field in both valid and error states
6844. **Page header with logo area, navigation, and CTA button** — nav and layout integration
6855. **Data table row with status badge and action buttons** — table, badge, and button together
6866. **Empty state with icon, message, and CTA** — empty state pattern with correct spacing
6877. **Error state (inline field error + full-page error)** — both error display variants
6888. **Modal with header, body content, and action buttons** — modal with correct padding and button placement
689690Every value in these examples must come from a specific section above. No invented values.
691692---
693694## Logo Guidance
695696### MVP Logo
697- Use text-only for MVP. Your product name in your heading font at display weight is a logo.
698- Create a simple favicon: first letter of your product on your primary color background.
699- Use an SVG for crispness at all sizes.
700701### Versions Needed
702| Version | Where It Goes | Notes |
703|---------|---------------|-------|
704| Full logo (text) | Header, login page | Your product name in heading font |
705| Icon only | Favicon, mobile app icon | Single letter or simple mark |
706| Dark background variant | Dark nav, footer | Ensure contrast |
707| Light background variant | Light pages, emails | Default version |
708709### When to Invest in a Real Logo
710- After product-market fit (not before)
711- When you're embarrassed showing the text logo to potential customers
712- When you have budget for a designer ($500-2000 range)
713- Never let logo design block your launch
714715---
716717## What You Decide vs. What AI Implements
718719| You Decide | AI Implements |
720|------------|---------------|
721| "I want it to feel like Linear" | Complete color, type, and spacing system |
722| "Warmer, more approachable" | Adjusts temperature, radius, type to humanist |
723| "I hate that green" | Swaps green for next-best semantic color |
724| "Can the buttons be softer?" | Increases radius, reduces weight, adjusts shadow |
725| "I need dark mode" | Full dark mode token mapping |
726| "This is for enterprise" | Trust-oriented palette, geometric type, high contrast |
727728**Rule:** You describe the destination. AI drives.
729730---
731732## Common Mistakes
733734| Mistake | What Happens | Fix |
735|---------|-------------|-----|
736| Skipping brand identity, letting AI choose | Every page looks different, AI fills gaps with random defaults | Generate BRAND-IDENTITY.md first |
737| Specifying colors but not states | Hover, active, disabled states get invented randomly | This template specifies every state |
738| "Just make it look modern" | AI defaults to generic SaaS — indistinguishable from templates | Pick reference brands instead |
739| Choosing colors you personally like | Your brand might clash with accessibility or audience expectations | React to proposals based on your audience, not personal taste |
740| Skipping dark mode decision | Some AI tools generate dark mode anyway, others don't | Explicitly opt in or out |
741| No anti-patterns list | AI adds gradients, shadows, and decorations "to make it pop" | Anti-patterns section bans the usual suspects |
742743---
744745## Quality Gate
746747Before writing the final `BRAND-IDENTITY.md`, verify every item:
748749- [ ] All 12 sections fully populated — no "TBD," no placeholders, no empty cells
750- [ ] Every color pairing listed in Section 10 passes WCAG 2.1 AA (4.5:1 for normal text, 3:1 for large text)
751- [ ] All component states specified (default, hover, active, focus, disabled, loading, error as applicable)
752- [ ] Anti-patterns list has 16+ items including at least 3 brand-specific entries
753- [ ] Fluid typography `clamp()` values produce correct sizes at 320px and 1440px viewport widths
754- [ ] Spacing scale is internally consistent (based on base unit, no arbitrary jumps)
755- [ ] Application examples in Section 12 use actual hex values, spacing, and font specs — not placeholders
756- [ ] Font loading strategy specified (`font-display: swap`, preload)
757- [ ] 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."
758- [ ] All accessibility requirements from Section 10 are present and filled in
759- [ ] Contrast ratio table has at least 8 pairings calculated
760- [ ] Touch targets specified as 44px minimum in both Section 10 and Section 11
761- [ ] Breakpoint values are consistent between Section 4 and Section 11
762- [ ] Icon library specified and "never mix" rule included
763- [ ] Reduced motion CSS included in Section 7
764765---
766767## Related Skills
768769Once the brand identity is generated, these skills use the tokens to build the actual UI:
770771- **beautify** — How to apply these tokens beautifully (visual hierarchy, whitespace, composition)
772- **ui-patterns** — Component implementation and page layouts using these tokens
773- **motion-polish** — Animation timing and micro-interactions that match the brand personality
774- **design-review** — Quality gate to audit whether the UI correctly implements this identity
Run npx skillmds@latest add whawkinsiv/brand-identity-generator in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use this skill when the user needs to create a visual brand identity for their product. Generates a comprehensive BRAND-IDENTITY.md file for the project root. Covers colors, typography, spacing, components, accessibility, and responsive design — with no gaps for AI to fill with generic defaults. It is listed under Design & Media on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
whawkinsiv (@whawkinsiv) published this skill. Their other Agent Skills are listed on their SkillMD profile.
whawkinsiv