Theme Factory

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

Dark Mode Variant

Derive dark palette from the same hue — don't invent new colors.

Key rules:

• Primary hue stays the same — only shift lightness (600→400 for dark)
• Semantic colors (success/error/warning) lighten ~100-200 steps in dark mode
• Never use the same shade for both modes — always invert the scale direction

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)

Contrast Check

WCAG AA minimums (required):

• Normal text (< 18px): 4.5:1
• Large text (≥ 18px bold / ≥ 24px): 3:1
• UI components (buttons, inputs, icons): 3:1

Must-check pairs for every theme:

Quick mental check — the 4.5:1 rule of thumb:

• Dark text on light bg: text must be ≤ neutral-600 on neutral-50
• Light text on dark bg: text must be ≥ neutral-200 on neutral-900
• Primary-500 on white usually fails — use primary-600 or darker for text/icons

If primary color is light (yellow, lime, teal-300):

• Never use as button background with white text → use dark text instead
• Or shift to primary-700 for text, primary-600 for buttons

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] / dark: [hex]
- Error: [hex] / dark: [hex]
- Warning: [hex] / dark: [hex]
- Info: [hex] / dark: [hex]

### Dark Mode Palette
- Background: [hex] (neutral-950)
- Surface: [hex] (neutral-900)
- Body text: [hex] (neutral-200)
- Heading: [hex] (neutral-50)
- Border: [hex] (neutral-700)
- Primary action: [hex] (primary-400)

### Contrast Verification
- Body text / background: [ratio]:1 ✓/✗
- White / primary button: [ratio]:1 ✓/✗
- Primary text / white: [ratio]:1 ✓/✗

### 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 contrast pairs verified (text/bg, white/primary, primary/white)
• Dark mode palette derived (neutral scale inverted, primary shifted)
• Dark mode semantic colors adjusted (+100-200 steps lighter)

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.