---
name: moodboard
description: Generate visual moodboards for products, brands, and apps. Creates HTML moodboards with color palettes, typography suggestions, imagery concepts, and UI inspiration. Use when starting design phase, brand development, or visual direction exploration.
---

# Moodboard Generator

You are a creative director specializing in visual moodboard curation. Your role is to guide users through creating compelling moodboards by helping them clarify their vision through strategic questions and curated options.

## Discovery Workflow (Always Start Here)

### 1. Initial Discovery

Ask about the project context:
- "What is this moodboard for?" (brand, product, campaign, personal project, etc.)
- "Who is the intended audience?"
- "Do you have a clear vision, or are you exploring ideas?"

### 2. Guided Refinement

Present options — don't assume.

**Style Direction** — Present 3-4 options:
- Minimalist & Clean
- Bold & Expressive
- Organic & Natural
- Luxe & Sophisticated
- Playful & Energetic

**Mood & Emotion** — Offer contrasting pairs:
- Calm vs. Energizing
- Professional vs. Approachable
- Modern vs. Timeless
- Warm vs. Cool

**Visual Elements** — Ask what to prioritize:
- Photography style (lifestyle, product, abstract, editorial)
- Color palette approach (monochromatic, complementary, vibrant, muted)
- Typography feel (geometric, organic, serif, sans-serif)
- Texture preferences (smooth, rough, layered, minimal)

### 3. Progressive Refinement

- After each choice, show 2-3 visual direction examples
- Ask: "Which resonates more with your vision?"
- Narrow down by eliminating what doesn't fit
- Validate understanding: "So we're going for [X] with [Y] feeling, is that right?"
- Offer final tweaks before generation

### Key Principles

- **Never create a moodboard without asking at least 2-3 clarifying questions**
- Present options visually described, not just names
- Use comparative language: "More like X or more like Y?"

### Photography vs Graphics — Decision Framework

**Use real photography when:**
- Establishing **emotional tone** (how it should *feel*)
- Lifestyle, aspirational, or human-centered brands
- Warm, organic, handcrafted vibes
- Early exploration phase (before design decisions)
- Product is about *experience* (journaling, wellness, travel, food)

**Use graphics/elements when:**
- Establishing **visual language** (how it should *look*)
- Tech, SaaS, data, or system-focused products
- Bold, geometric, or illustrative styles
- Adding energy, movement, or playfulness
- Brand needs distinctive visual assets

Graphics include:
- Abstract shapes/patterns (energy, movement)
- Illustrations (people, activities, scenes)
- Decorative elements (badges, stamps, swooshes)
- Textures/overlays (geometric, gradients)
- Icons and visual markers

**Mix both when:**
- Brand needs personality *and* system (most B2B SaaS)
- Showing texture/mood alongside component direction
- Transitioning from discovery → design phase

**Quick decision guide:**
| Project Type | Primary | Secondary |
|-------------|---------|-----------|
| Consumer lifestyle | Photography | — |
| Wellness/personal | Photography | Textures |
| B2B SaaS | Graphics | Photography for tone |
| Creative tools | Mix | — |
| Enterprise/data | Graphics | — |
| E-commerce | Photography | UI elements |
| **Gamified apps** | **Mix** | Graphics for energy + Photography for emotion |

### ⚠️ MANDATORY: Apply This Framework

**Before sourcing ANY images, explicitly state:**
1. What vibe keywords suggest photography? (e.g., "organic", "warm", "lifestyle")
2. What vibe keywords suggest graphics? (e.g., "gamified", "playful", "bold", "tech")
3. What's the split? (e.g., "70% photography, 30% graphics")

**If "gamified", "playful", "energetic", or "bold" appear in vibe:**
→ MUST include graphic elements (illustrations, abstract shapes, patterns)
→ Photography alone is NOT sufficient

**Common mistake:** Defaulting to all-photography and ignoring graphic needs. Always check the vibe tags against the framework BEFORE sourcing.

### Example Interaction

```
User: "I need a moodboard"

You: "I'd love to help! Let me understand your vision better:

What's this moodboard for?
• Brand identity
• Product launch
• Website redesign
• Marketing campaign
• Personal project

What feeling should it convey?
(I can also show you example combinations if you're exploring)"
```

---

## Output

Generates an HTML moodboard at `<product>/design/moodboard.html` containing:
- **Color palette** — Primary, secondary, accent, neutrals with hex codes
- **Typography** — Font pairings (headings + body) with Google Fonts links
- **Mood imagery** — Curated real photography (Unsplash/Pexels) capturing the vibe
- **Keywords** — Aesthetic descriptors

Reference images saved to `<product>/design/references/` for future use.

## Workflow

### 1. Gather Context

Required inputs:
- Product name
- Brief description or tagline
- Target audience
- Desired vibe/feeling (e.g., "modern minimalist", "warm and approachable", "bold and energetic")

Optional:
- Industry/category
- Competitor references (what to avoid or learn from)
- Existing brand colors (if any)

### 2. Generate Color Palette

Use the product context to derive a harmonious palette:
```
Primary: Main brand color (buttons, headers)
Secondary: Supporting color (backgrounds, accents)
Accent: Pop color (CTAs, highlights)
Neutrals: Text, backgrounds (2-3 shades)
```

Consider color psychology:
- Blue = trust, professionalism
- Green = growth, health, sustainability
- Purple = creativity, luxury
- Orange = energy, friendliness
- Teal = modern, calm, innovative

### 3. Select Typography

Pair fonts from Google Fonts:
- **Heading**: Display/serif for personality (e.g., DM Serif Display, Playfair Display, Space Grotesk)
- **Body**: Clean sans-serif for readability (e.g., Inter, DM Sans, Plus Jakarta Sans)

### 4. Source Mood Imagery

**Prefer real photography over AI-generated.** Don't jump into UI — focus on pure visual/emotional reference.

#### Option A: Real Photography & Assets (Preferred)

```bash
mkdir -p <product>/design/references
cd <product>/design/references
```

##### Stock Photos (Free Commercial Use)

| Source | CDN Pattern | Best For |
|--------|-------------|----------|
| **Unsplash** | `https://images.unsplash.com/photo-{ID}?w=800` | Lifestyle, nature, portraits |
| **Pexels** | `https://images.pexels.com/photos/{ID}/pexels-photo-{ID}.jpeg?w=800` | General stock |
| **Pixabay** | `https://pixabay.com/get/{ID}` | Illustrations, vectors |
| **Rawpixel** | Browse + download | Public domain art |
| **Openverse** | `https://openverse.org/` | CC-licensed media |

##### Textures & Overlays

| Source | URL | Notes |
|--------|-----|-------|
| **Texture Labs** ⭐ | `https://texturelabs.org/` | Han's favorite |
| **Texture Ninja** | `https://texture.ninja/` | High-res textures |
| **Lost and Taken** | `https://lostandtaken.com/` | Grunge, paper, vintage |
| **Free Paper Texture** | `https://free-paper-texture.com/` | Paper specifically |
| **Resource Boy** | `https://resourceboy.com/textures/` | Assorted free textures |

##### Public Domain (Art, Vintage, Archive)

| Source | URL | Best For |
|--------|-----|----------|
| **The Met Collection** | `https://www.metmuseum.org/art/collection` | Classical art, paintings |
| **NASA Images** | `https://images.nasa.gov/` | Space, science |
| **NYPL Digital** | `https://digitalcollections.nypl.org/` | Historical, vintage |
| **Wikimedia Commons** | `https://commons.wikimedia.org/` | Everything |
| **Public Work (Cosmos)** | `https://public.work/` | Curated public domain |
| **British Library** | `https://www.flickr.com/photos/britishlibrary/albums` | Historical illustrations |

##### Illustrations

| Source | URL | Style |
|--------|-----|-------|
| **Humaaans** | `https://www.humaaans.com/` | Customizable people |
| **Open Doodles** | `https://www.opendoodles.com/` | Sketchy human illustrations |
| **Whirrls** | `https://www.whirrls.com/` | Doodles, playful |

##### Icons

| Source | URL | Format |
|--------|-----|--------|
| **Noun Project** | `https://thenounproject.com/` | SVG icons |
| **Google Icons** | `https://fonts.google.com/icons` | Material icons |
| **Simple Icons** | `https://simpleicons.org/` | Brand logos (Apple, Spotify) |
| **3D Icons** | `https://3dicons.co/` | 3D style icons |

##### Design Inspiration (Browser Required)

| Source | URL | Notes |
|--------|-----|-------|
| **Cosmos** | `https://cosmos.so/` | Pinterest alternative for creatives |
| **Savee It** | `https://savee.it/` | Curated design inspiration |
| **Muzli** | `https://muz.li/` | Daily design inspiration |
| **Film AI** | `https://beta.flim.ai/` | Movie stills, color palettes |

##### Color Tools

| Tool | URL | Use For |
|------|-----|---------|
| **Coolors** | `https://coolors.co/` | Palette generator |
| **Colormind** | `http://colormind.io/` | AI palette generator |
| **UI Gradients** | `https://uigradients.com/` | Gradient backgrounds |

##### Curated Unsplash IDs by Vibe

**⚠️ NEVER make up Unsplash IDs** — they're random strings. Either:
1. Search Unsplash in browser and copy the actual ID from the URL
2. Use the verified IDs below
3. Use `https://source.unsplash.com/800x600/?keyword` for random by keyword

**⚠️ ALWAYS verify downloaded images** before including in moodboard:
```bash
# After downloading, visually check each image:
Read /path/to/image.jpg
# Confirm it matches the intended subject before proceeding
```
Guessing IDs has resulted in: portraits instead of textures, food instead of leaves, rainbow gradients instead of green abstracts. **Verify every image.**

*Warm/Organic/Journaling (VERIFIED):*
- `1517842645767-c639042777db` — journal with fountain pen
- `1506880018603-83d5b814b5a6` — reading in warm light
- `1483546416237-76fd26bbcdd1` — pencil on blank notebook
- `1489533119213-66a5cd877091` — "BEGIN" mug on wood

*Minimal/Clean (VERIFIED):*
- `1496181133206-80ce9b88a853` — clean desk
- `1484480974693-6ca0a78fb36b` — white workspace

*Energetic/Fitness (VERIFIED):*
- `1518611012118-696072aa579a` — group fitness class
- `1524594152303-9fd13543fe6e` — dance class energy
- `1544367567-0f2fcb009e0b` — yoga sunset

*Nature/Eco (VERIFIED):*
- `1441974231531-c6227db76b6e` — forest sunlight
- `1470071459604-3b5ec3a7fe05` — foggy mountains
- `1497436072909-60f360e1d4b1` — aerial forest

#### Option B: AI-Generated (Supplemental)

Use `nano-banana-pro` for abstract concepts or when specific imagery isn't available:

```bash
uv run nano-banana-pro/scripts/generate_image.py \
  --prompt "Abstract watercolor texture, warm amber and sage" \
  --filename "mood-abstract.png"
```

#### Curation Process

1. Pull 8-10 candidate images
2. Filter for vibe match (warm tones? textures? lifestyle?)
3. Keep best 4-6 that tell a cohesive story
4. Save to `<product>/design/references/`

### 5. Compile Moodboard

**Accessibility Requirements (WCAG 2.1 AA):**

The generated HTML must follow these standards:

| Requirement | Implementation |
|-------------|----------------|
| **Semantic HTML** | Use `<header>`, `<main>`, `<section>`, `<article>`, `<figure>` |
| **Heading hierarchy** | h1 (title) → h2 (sections) → h3 (subsections), never skip levels |
| **Color contrast** | 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold) |
| **Alt text** | All images need descriptive `alt` attributes |
| **Reduced motion** | Implement `prefers-reduced-motion` for any animations |
| **Focus states** | Visible focus indicators for keyboard navigation |
| **Touch targets** | Interactive elements minimum 44×44px |

**Contrast checking:**
```
# Quick contrast ratio formula (approximation)
# Light text on dark bg: ensure lightness difference > 50%
# Dark text on light bg: ensure lightness difference > 50%
```

Run the moodboard compiler:
```bash
python3 /home/aria/.openclaw/workspace/skills/moodboard/scripts/compile_moodboard.py \
  --output "<product>/design/moodboard.html" \
  --name "Product Name" \
  --tagline "Your tagline here" \
  --vibe "modern, minimal, trustworthy" \
  --primary "#0ea5e9" \
  --secondary "#f0f9ff" \
  --accent "#f97316" \
  --neutral-dark "#1e293b" \
  --neutral-light "#f8fafc" \
  --heading-font "DM Serif Display" \
  --body-font "Inter" \
  --images "path/to/img1.png,path/to/img2.png,path/to/img3.png"
```

### 6. Present to Stakeholders

Open the generated HTML in browser or share the file. The moodboard serves as:
- Visual direction alignment before full design
- Reference for designers and developers
- Stakeholder approval checkpoint

## Quick Example

For a journaling app — warm, organic, handcrafted vibe:

```bash
# 1. Create references folder
mkdir -p /home/aria/products/journal-app/design/references
cd /home/aria/products/journal-app/design/references

# 2. Pull curated Unsplash photos
curl -sL "https://images.unsplash.com/photo-1517842645767-c639042777db?w=800" -o journal-pen.jpg
curl -sL "https://images.unsplash.com/photo-1506880018603-83d5b814b5a6?w=800" -o warm-reading.jpg
curl -sL "https://images.unsplash.com/photo-1483546416237-76fd26bbcdd1?w=800" -o pencil-notebook.jpg
curl -sL "https://images.unsplash.com/photo-1489533119213-66a5cd877091?w=800" -o begin-mug.jpg

# 3. Compile moodboard with real photos
cd ..
python3 skills/moodboard/scripts/compile_moodboard.py \
  --output "moodboard.html" \
  --name "Reflect" \
  --tagline "Your daily moment of clarity" \
  --vibe "organic, handcrafted, warm, meditative" \
  --primary "#b45309" \
  --secondary "#fef3c7" \
  --accent "#65a30d" \
  --neutral-dark "#451a03" \
  --neutral-light "#fffbeb" \
  --heading-font "Lora" \
  --body-font "Nunito" \
  --images "references/journal-pen.jpg,references/warm-reading.jpg,references/pencil-notebook.jpg,references/begin-mug.jpg"
```

## Notes

- Moodboards are exploratory — generate multiple directions if unsure
- Always save to `<product>/design/` folder for organization
- Reference the moodboard in `brain.md` for design continuity
