Theme Factory

Purpose

Generate cohesive, beautiful UI themes when no design specifications provided, preventing generic monotone interfaces.

---

Core Principle

Brand personality drives design decisions.

Every UI communicates personality through color, typography, and style. Rather than defaulting to arbitrary colors, ask about brand personality first, then generate cohesive themes that match.

Good theme = Intentional, cohesive, personality-aligned Bad theme = Random colors, inconsistent, no personality

---

When to Use Theme Factory

Use when user EXPLICITLY asks for theme help:

• "What theme should I use?"
• "Help me pick colors"
• "What colors work well together?"
• User uncertain about aesthetic choices

Don't use if:

• User has clear aesthetic in mind → design-fundamentals handles it
• Figma file/URL provided → use figma-design-extraction
• User already chose colors/fonts → just apply them

---

Theme Selection Process

Step 1: Understand Brand Personality

Ask user (concise, 1-2 questions max):

Question 1: "What personality should this UI have?"

• Professional - Corporate, trustworthy, business-focused
• Creative - Bold, artistic, unique, expressive
• Minimal - Clean, sophisticated, simple, timeless
• Bold/Tech - Modern, eye-catching, innovative
• Warm/Organic - Natural, welcoming, friendly
• Playful - Fun, colorful, approachable, energetic

Question 2: "Any color preferences or inspirations?"

• Specific colors they like
• Competitor/inspiration URLs
• Or: "Auto-generate based on personality"

Step 2: Present Theme Options

Show 2-3 pre-defined themes from .claude/themes/ matching personality

Example:

1. Professional Blue - Corporate, trustworthy, clean
2. Minimal Monochrome - Sophisticated, timeless
3. Generate custom theme based on your preferences

If user wants custom: Generate based on personality + color preferences

---

Theme Anatomy

1. Colors

Primary Palette (shades 50-900):

• Used for: Main actions, links, buttons, key UI elements
• Scale: 50 (lightest) → 900 (darkest)

Neutral Palette (50-900):

• Used for: Text, backgrounds, borders, subtle UI
• Principle: True grays or slightly tinted toward primary

Semantic Colors:

• Success: Green (growth, positive, confirmation)
• Warning: Yellow/orange (caution, attention)
• Error: Red (danger, mistakes, destructive)
• Info: Blue (information, neutral)

Why this structure:

• Full palette enables light/dark modes
• Semantic colors ensure accessibility
• Neutrals provide visual breathing room

2. Typography

See design-fundamentals for typography pairing principles.

Theme should define:

• Font families (heading + body)
• Type scale values
• Font weights available
• Line heights

3. Spacing System

See design-fundamentals for spacing scale principles.

Theme should define:

• Base unit (4px or 8px)
• Scale values

4. Visual Properties

Border Radius:

• Minimal: Small or none (sharp, clean)
• Friendly: Medium roundness (approachable, soft)
• Playful: Large roundness or full pill shapes (fun, organic)

Shadows:

• Subtle shadows for depth (professional, minimal)
• Stronger shadows for cards/modals (modern, bold)
• No shadows for flat design (minimalist)
• Define elevation system (subtle/medium/strong)

---

Color Theory Foundations

Color Harmony Methods

Complementary - Opposites on color wheel:

• High contrast, energetic, bold
• Example: Blue + Orange, Red + Green
• Use for: Bold, tech, creative personalities

Analogous - Adjacent on color wheel:

• Harmonious, calm, cohesive
• Example: Blue + Purple + Teal
• Use for: Professional, minimal, warm personalities

Triadic - Three evenly spaced:

• Balanced, vibrant, dynamic
• Example: Red + Yellow + Blue
• Use for: Playful, creative personalities

Monochromatic - Single hue, varying lightness:

• Clean, sophisticated, minimal
• Use for: Minimal, professional personalities

Color Psychology

Quick reference:

• Blue = Trust, professional
• Green = Growth, health
• Purple = Creativity, luxury
• Red = Energy, urgency
• Orange = Friendly, energetic
• Yellow = Optimism, playfulness
• Neutral = Sophisticated, minimal

When choosing colors:

• Consider brand personality
• Use color harmony methods for cohesive palettes
• Verify contrast ratios meet WCAG AA

---

Theme Documentation Format

In planning doc:

## Theme Specification

### Selected Theme
- Name: [Theme Name]
- Source: .claude/themes/[filename].theme.json OR "Custom generated"
- Personality: [personality traits]

### Color Palette
**Primary ([Color Name]):**
- Base: [hex] (buttons, links, actions)
- Hover: [hex]
- Active: [hex]
- Full scale: 50-900 shades

**Neutral:**
- Lightest: [hex] (backgrounds)
- Medium: [hex] (body text)
- Darkest: [hex] (headings)
- Full scale: 50-900 shades

**Semantic:**
- Success: [hex]
- Error: [hex]
- Warning: [hex]
- Info: [hex]

### Typography
- Heading: [Font family], [weight], [line-height]
- Body: [Font family], [weight], [line-height]
- Scale: [values]

### Spacing
- Scale: [values - base-4 or base-8]

### Visual Style
- Border radius: [small/medium/large]
- Shadows: [subtle/medium/strong]

---

Theme Application Guidelines

Consistency Rules:

Do:

• Use only colors from theme palette
• Apply spacing scale consistently
• Follow typography scale
• Use semantic colors for their intended purpose

Don't:

• Mix colors from multiple themes
• Use arbitrary values
• Override theme for one-off styles
• Ignore semantic color meanings

Component Theming:

Buttons:

• Primary: Primary color background
• Secondary: Secondary/neutral background
• Outline: Transparent background, primary border
• Ghost: Transparent, primary text only

States:

• Hover: Slightly darker/more saturated
• Active: Noticeably darker than hover
• Disabled: Muted neutral shades
• Focus: Primary color ring

---

Common Mistakes

1. No personality - Generic theme → Fix: Choose personality first
2. Arbitrary tweaks - Modifying theme colors slightly → Fix: Use theme palette exactly as defined
3. Semantic color abuse - Green button for delete → Fix: Red (error) for destructive, green (success) for positive
4. Ignoring color harmony - Random combinations → Fix: Use color harmony methods
5. Theme mixing - Using colors from multiple themes → Fix: Commit to one theme
6. Copying examples literally - Using exact values from docs → Fix: Generate unique values matching personality

---

Validation Checklist

• Brand personality identified
• Color harmony method used
• Primary palette complete (50-900 shades)
• Neutral palette defined (50-900 shades)
• Semantic colors defined
• Typography pairing chosen
• Type scale defined
• Spacing scale defined
• Border radius values chosen
• Shadow system defined
• Theme documented in planning doc
• All colors pass WCAG AA contrast

---

Key Takeaway

Color harmony + brand personality = cohesive themes.

When users need help choosing colors/fonts:

1. Ask brand personality
2. Apply color harmony methods
3. Generate complete theme specification
4. Apply using design-fundamentals principles

Theme-factory provides interactive selection and color theory methods. Design-fundamentals provides application principles and technical foundation.

Together: Distinctive, cohesive, accessible UI themes.