Generates BRAND-IDENTITY.md file defining visual brand identity: colors, typography, spacing, components, accessibility, responsive design. For product branding setup.
npx claudepluginhub whawkinsiv/solo-founder-superpowers --plugin solo-founder-superpowersThis skill uses the workspace's default tool permissions.
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.
Provides Ktor server patterns for routing DSL, plugins (auth, CORS, serialization), Koin DI, WebSockets, services, and testApplication testing.
Conducts multi-source web research with firecrawl and exa MCPs: searches, scrapes pages, synthesizes cited reports. For deep dives, competitive analysis, tech evaluations, or due diligence.
Provides demand forecasting, safety stock optimization, replenishment planning, and promotional lift estimation for multi-location retailers managing 300-800 SKUs.
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:
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.
Core principle: The user should never need to use design vocabulary. They react to your proposals. You do the heavy lifting.
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:
Do NOT present the full 12-section spec yet. Keep it conversational.
Step 4 — User reacts:
They might say things like:
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.
Detect when the user provides specific design tokens — hex codes, font names, radius values, spacing scales. Signs of an expert:
When detected:
25 brands across 7 categories. Use the "Feel" to describe brands to users. Use the "Design DNA" internally to derive specific values.
Stripe
Linear
Vercel
Superhuman
Notion
Basecamp
Mailchimp
Canva
Slack
Figma
Loom
Discord
Plaid
Gusto
Mercury
Wise
Calm
Headspace
Apple Health
Spotify
Duolingo
Robinhood
Datadog
Mixpanel
Airtable
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
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.
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>
Every value in these examples must come from a specific section above. No invented values.
| 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 |
| 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.
| 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 |
Before writing the final BRAND-IDENTITY.md, verify every item:
clamp() values produce correct sizes at 320px and 1440px viewport widthsfont-display: swap, preload)Once the brand identity is generated, these skills use the tokens to build the actual UI: