24 KiB

Raw Blame History

Session Log: Eira Visual Design Integration Architecture

Date: 2026-01-04
Participants: Freya (WDS Designer Agent), User (Mårten)
Topic: Complete architecture for integrating Eira visual design workflow into WDS
Status: Design phase - to be prototyped in Dogweek project

Executive Summary

Designed complete integration of Eira (visual design agent) into WDS workflow. Eira enables AI-powered visual design exploration using image generation models (Nano Banana, DALL-E, Midjourney, etc.) while maintaining strategic alignment with BMad Method principles.

Key Innovation: Phase 2.5 "Visual Design Brief" - a creative exploration phase between strategy (Phase 2) and detailed scenarios (Phase 4) where wild visual concepts are generated before locking into detailed specs.

Core Principle: Strategy → Creative Exploration → Detailed Execution

Problem Statement

Current State:

WDS produces functional prototypes but often uses default/generic visual design (Tailwind defaults)
"Visual Poverty" - cluttered layouts, generic aesthetics, no strategic visual direction
No systematic way to explore visual concepts before detailed design work

Desired State:

"Visual Prosperity" - typography-first hierarchy, generous white space, premium aesthetics
Strategic visual design that triggers psychological drivers from trigger map
Systematic creative exploration before detailed execution
Tool-agnostic approach (not locked to one image generation model)

Architecture Overview

Phase Integration

Phase 1: Project Brief
├─ Business strategy
├─ VTC (Value to Customer)
└─ Question: "Will this project require visual design?" (YES/NO)

Phase 2: Trigger Mapping
├─ User psychology
├─ Demographics
├─ Psychological triggers
└─ User context (informs device priorities)

Phase 2.5: Visual Design Brief ← NEW!
├─ Strategic document (tool-agnostic)
├─ Content concept generation
├─ Visual exploration (wild & creative)
├─ Direction selection
└─ Design token extraction

Phase 3: PRD/Platform
├─ Technical foundation
└─ Device priorities (informed by Phase 2.5)

Phase 4: UX Design (Scenarios)
├─ Detailed conceptual specs
├─ High-fidelity mockups (using approved direction)
├─ HTML prototypes
└─ Design system evolution

Phase 2.5: Visual Design Brief (Detailed)

Purpose

Strategic document that defines boundaries and direction for visual exploration. Completely tool-agnostic - focuses on WHAT to explore, not HOW to generate.

Content Structure

# Visual Design Brief: [Project Name]

## Strategic Foundation
- Value to Customer (VTC)
- Target Demographics
- Key Psychological Triggers (top 3-5 to emphasize visually)
- Brand Positioning

## Visual Direction to Explore
- Mood & Feeling (3-5 adjectives)
- Visual References (brands/products to learn from)
- Visual Prosperity Standards (must achieve / must avoid)

## Content Concepts
For each key page (homepage, features, pricing, etc.):
- Purpose (which trigger does this serve?)
- Strategic content (headline, subheadline, features, CTA)
- Visual exploration focus

## Exploration Parameters
- Directions to Explore (2-3 different visual approaches)
- Pages to Visualize
- Device Priority (based on demographics)

## Constraints & Requirements
- Brand Assets (existing/to create)
- Technical Constraints
- Must Include / Must Avoid

## Success Criteria
- Evaluation questions
- Strategic alignment checks

Visual Prosperity Standards

Must Achieve:

Typography-first hierarchy
Generous, intentional white space
Premium color palettes (3-4 colors max)
Clean, purposeful imagery
Every element serves strategic purpose

Must Avoid:

Tailwind CSS default styles (blue buttons, generic grays)
Generic UI kit aesthetics (Material, Bootstrap defaults)
Cluttered layouts with poor hierarchy
Decorative elements without purpose
Stock photo aesthetics

Workflow: Freya ↔ User ↔ Eira

Step 1: Freya Creates Visual Design Brief

Input:

Project Brief (Phase 1)
Trigger Map (Phase 2)

Process:

Freya reads strategic context
Generates content concepts using content creation workshop
Defines exploration parameters
Creates Visual Design Brief document

Output:

docs/2.5-visual-design-brief/visual-design-brief.md

Step 2: Tool Selection Workshop

Freya runs workshop with user:

Q1: Which image generation model do you want to use?
    [ ] Nano Banana Pro (Google) - Best text rendering, manual workflow
    [ ] DALL-E 3 (OpenAI) - API access, good automation
    [ ] Midjourney v7 - Beautiful aesthetics, style consistency
    [ ] Flux Pro - Fast, good prompt adherence
    [ ] Ideogram 2.0 - Excellent typography
    [ ] Other: ___________

Q2: Access method?
    [ ] Manual (copy-paste prompts, download results)
    [ ] API (automated generation)
    [ ] Third-party platform

Q3: Do you have API keys/access configured?
    [ ] Yes - ready to go
    [ ] No - will use manual workflow

User decision: Determines execution approach, not strategy

Step 3: Freya Generates Tool-Specific Setup

For Nano Banana (example):

A. System Instructions (ONE-TIME SETUP - Universal for all projects)

Freya generates ONCE, user pastes into NB system instructions field:

UNIVERSAL KNOWLEDGE (applies to all projects):
- Eira persona and mission
- Visual Poverty vs Visual Prosperity definitions
- BMad/WDS workflow understanding
- Technical standards (typography specs, color palette rules, spacing principles)
- Collaboration style and output format
- Design token JSON structure and requirements
- Visual Prosperity checklist
- Export capabilities and format

EXPORT INSTRUCTIONS:
When user requests export (e.g., "Export the approved design"), provide:
1. Design token JSON (colors, typography, spacing, layout)
2. HTML structure (semantic, accessible markup)
3. CSS styles (component styles, layout patterns)
4. Layout patterns JSON (structure, grid, spacing, responsive behavior)

Use standard JSON/HTML/CSS format following the design token structure defined above.

This stays in NB permanently, applies to every project.

B. Project Context (PER-PROJECT - First message in new chat)

Freya generates for THIS PROJECT, user pastes as first message:

PROJECT-SPECIFIC CONTEXT (changes per project):
- Project name and strategic summary
- VTC (Value to Customer)
- Target demographics
- Key psychological triggers
- Visual mood direction
- Brand positioning
- Design constraints
- Existing brand assets (if any)

This context persists for entire project conversation.

C. Task Prompts (PER-TASK - Each exploration)

Freya generates for EACH SPECIFIC TASK (page/direction):

TASK-SPECIFIC ONLY (minimal, focused):
- Which page (homepage/features/pricing)
- Which direction to explore (premium/playful/bold)
- Specific content for this page (headline, features, CTA)
- Any page-specific requirements

DELIVERY LOCATION:
- Save visual output to: docs/2.5-visual-design-brief/explorations/[page]/[direction].png
- File naming: [page]-[direction]-[device].png
- Example: homepage-premium-desktop.png

Everything else (standards, principles, project context) is already in system instructions or project context.

Step 4: Visual Exploration (User ↔ Eira)

Process:

User pastes task prompt into Nano Banana (includes delivery location)
Eira (NB) generates visual concept
User downloads/screenshots result
User saves to specified location from task prompt
Repeat for each page and direction

Delivery Structure:

docs/2.5-visual-design-brief/explorations/
├── homepage/
│   ├── homepage-premium-desktop.png
│   ├── homepage-playful-desktop.png
│   └── homepage-bold-desktop.png
├── features/
│   ├── features-premium-desktop.png
│   ├── features-playful-desktop.png
│   └── features-bold-desktop.png
└── pricing/
    ├── pricing-premium-desktop.png
    ├── pricing-playful-desktop.png
    └── pricing-bold-desktop.png

File Naming Convention:

Format: [page]-[direction]-[device].png
Examples:
- homepage-premium-desktop.png
- features-playful-mobile.png
- pricing-bold-tablet.png

Step 5: Direction Selection (User + Freya)

User shares results with Freya:

"Here are the explorations Eira generated: [screenshots/descriptions]"

Freya analyzes:

Strategic alignment (triggers correct psychology?)
Visual prosperity (meets standards?)
Differentiation (stands out from competitors?)
Demographic resonance (appeals to target users?)

Freya recommends:

Winning direction (or hybrid approach)
Rationale for selection
Refinements needed

User decides:

Approves direction
Requests refinements
Tries new direction

Step 6: Design Token Extraction

From approved visual direction:

Option A: Eira (NB) Generates JSON Directly

User asks Eira in Nano Banana:
"Generate design token JSON files for the approved direction"

Eira outputs complete JSON structure:
{
  "colors": {
    "primary": "#0A0E27",
    "secondary": "#1A1F3A",
    "accent": "#00FF9D",
    "background": "#FFFFFF",
    "text": {
      "primary": "#1A1A1A",
      "secondary": "#666666",
      "tertiary": "#999999"
    }
  },
  "typography": {
    "headings": {
      "family": "Inter",
      "weights": [600, 700, 800],
      "sizes": {
        "h1": "48px",
        "h2": "36px",
        "h3": "24px"
      }
    },
    "body": {
      "family": "Inter",
      "weight": 400,
      "size": "16px",
      "lineHeight": "1.6"
    }
  },
  "spacing": {
    "unit": "8px",
    "scale": [8, 16, 24, 32, 48, 64, 96]
  },
  "layout": {
    "maxWidth": "1200px",
    "gridColumns": 12,
    "gutter": "24px"
  }
}

User copies JSON output, brings back to Cursor.

Option B: Freya Extracts from Visual

If Eira doesn't generate JSON, Freya can extract from the approved visual:
- Analyzes colors, typography, spacing from image
- Creates JSON structure
- May need user confirmation on exact values

User brings back to Cursor:

Design token JSON (from Eira or Freya)
Visual assets (approved direction images)

Freya saves to:

design-system/tokens/colors.json
design-system/tokens/typography.json
design-system/tokens/spacing.json
design-system/tokens/layout.json

Step 7: Return to Cursor/WDS (Integration)

User brings back to Freya in Cursor:

Assets:

Visual explorations (PNG/JPG files)
Approved direction images

Code:

Design token JSON files
Any HTML/CSS snippets generated

Documentation:

Visual Design Brief
Direction selection rationale
Design token documentation

Freya integrates:

Saves assets to appropriate folders
Loads design tokens into design system
Updates project outline with approved direction
Prepares for Phase 4 (detailed scenarios)

Phase 4: Detailed Scenario Design (Changed Approach)

Now Working with Approved Direction

Difference from Phase 2.5:

Phase 2.5 = EXPLORE (loose, creative, multiple directions)
Phase 4 = EXECUTE (structured, consistent, approved direction)

Workflow Per Scenario

Step 1: Freya Creates Conceptual Spec

Detailed content and hierarchy
Strategic purpose
User psychology triggers

Step 2: Freya Generates Structured Prompts

Uses approved visual direction
Precise specifications (not exploratory)
Maintains design token consistency
STRUCTURED & PRECISE (not wild)

Step 3: Designer Sketches Wireframe (Optional)

Designer creates wireframe/concept for this scenario
Hand-drawn, Figma, or any tool
Defines UX structure and layout

Step 4: Freya Generates Per-Page Visual Design Brief

Extracts from conceptual spec for THIS page only
Strategic purpose, content, visual direction
Design constraints, delivery location
References approved direction from Phase 2.5

Step 5: User → Eira → High-Fidelity Mockup (Primary Device)

Upload designer sketch (if exists) + visual design brief
Generate PRIMARY device first (desktop or mobile based on demographics)
Maintain approved visual direction
Review and approve before moving to other devices

Step 6: User → Eira → Responsive Variations (Sequential)

Generate SECONDARY devices one at a time
Each references approved primary device
Prompt: "Adapt approved [primary] design for [secondary device]"
Order: Primary → Secondary → Tertiary
Example: Desktop → Mobile → Tablet

Step 7: Eira Exports Design Assets

User asks Eira: "Export the approved design"
Eira provides: Design tokens JSON, HTML structure, CSS styles, Layout patterns
User brings exports back to Cursor

Step 8: Extract Layout Patterns

Freya identifies reusable layout patterns from Eira's output
Saves to design-system/layouts/
Documents layout structure, grid, spacing patterns
Template Reuse: Similar pages can reference this layout pattern

Step 9: Freya Builds HTML Prototype

Uses design tokens from design system
Uses layout patterns from design system
Implements approved visual direction
Creates functional prototype

Note on Template Reuse:

Once first page template is complete, similar pages are faster
Example: After homepage hero → other hero sections reference the pattern
Eira can generate variations: "Use hero-section-centered layout with new content"

Folder Structure

docs/
├── 1-project-brief/
│   └── product-brief.md
│
├── 2-strategy/
│   ├── trigger-map.md
│   └── vtc.md
│
├── 2.5-visual-design-brief/  ← NEW PHASE!
│   ├── visual-design-brief.md (strategic document)
│   │
│   ├── content-concepts/
│   │   ├── homepage-concept.md
│   │   ├── features-concept.md
│   │   └── pricing-concept.md
│   │
│   ├── explorations/
│   │   ├── homepage/
│   │   │   ├── direction-1-premium.png
│   │   │   ├── direction-2-playful.png
│   │   │   └── direction-3-bold.png
│   │   ├── features/
│   │   └── pricing/
│   │
│   ├── approved-direction/
│   │   ├── selection-rationale.md
│   │   ├── mood-board.png
│   │   └── design-tokens-foundation.json
│   │
│   └── tool-setup/ (if using Nano Banana)
│       ├── system-instructions.md
│       ├── project-context.md
│       └── exploration-prompts.md
│
├── 3-prd-platform/
│   └── ... (technical foundation)
│
├── 4-scenarios/
│   ├── 1.1-homepage/
│   │   ├── 1.1-homepage.md (conceptual spec)
│   │   ├── 1.1-homepage.html (prototype)
│   │   └── high-fidelity/
│   │       ├── desktop.png
│   │       ├── tablet.png
│   │       └── mobile.png
│   │
│   └── ... (other scenarios)
│
└── design-system/
    ├── brand-assets/ (if existing brand)
    │   ├── logo.svg
    │   └── brand-guidelines.pdf
    │
    ├── tokens/
    │   ├── colors.json
    │   ├── typography.json
    │   ├── spacing.json
    │   └── layout.json
    │
    ├── components/
    │   ├── buttons.json
    │   ├── cards.json
    │   └── forms.json
    │
    ├── layouts/
    │   ├── hero-sections.json
    │   ├── feature-grids.json
    │   ├── pricing-tables.json
    │   └── navigation-patterns.json
    │
    └── visual-identity/
        ├── approved-mood-board.png
        └── component-showcase.png

Prompt Style Comparison

Phase 2.5: Exploration Prompts (LOOSE & CREATIVE)

Characteristics:

Broad strokes, not pixel-perfect
Focus on MOOD and FEELING
Multiple variations encouraged
"What if...?" explorations
Minimal restrictions
"Get wild and crazy"

Example:

Homepage concept for [Project]

STRATEGIC CONTEXT:
- Target: [demographics]
- Trigger: [psychological driver]
- Value: [VTC]

CONTENT:
- Headline: [strategic headline]
- Features: [3-4 highlights]

VISUAL EXPLORATION:
Explore 3 different moods:

Direction 1: PREMIUM & TRUSTWORTHY
- Think: Stripe, Apple Card
- Colors: Deep, sophisticated
- Typography: Bold, confident
- Mood: Professional, premium

Direction 2: PLAYFUL & ACCESSIBLE
- Think: Duolingo, Notion
- Colors: Vibrant, warm
- Typography: Rounded, friendly
- Mood: Fun, welcoming

Direction 3: BOLD & INNOVATIVE
- Think: Vercel, Linear
- Colors: High contrast, electric
- Typography: Sharp, modern
- Mood: Forward-thinking, disruptive

FREEDOM:
- Don't restrict creativity
- Show me what's possible
- Surprise me

Phase 4: Execution Prompts (STRUCTURED & PRECISE)

Characteristics:

Exact specifications
Approved direction only
Design token consistency
Pixel-perfect requirements
Clear constraints
Buildable by developers

Example:

Homepage hero section for [Project]

LAYOUT STRUCTURE:
- Navigation: Logo left, menu right
- Hero: Centered headline + CTA
- Background: Gradient [exact colors]

TYPOGRAPHY:
- Headline: Inter Bold, 48px, #1A1A1A
- Subheadline: Inter Regular, 18px, #666666
- CTA: Inter Semibold, 16px, #FFFFFF

COLOR PALETTE:
- Primary: #0A0E27 (from approved direction)
- Accent: #00FF9D (from approved direction)
- Background: Linear gradient #1A1F3A to #0A0E27

SPACING:
- Padding: 64px top/bottom
- Max-width: 1200px centered
- Button spacing: 24px from subheadline

STYLE:
- Follow approved mood board
- Maintain design token consistency
- Flat with subtle gradients

AVOID:
- Deviating from approved direction
- Tailwind defaults

Tool-Agnostic Design

Visual Design Brief = Strategic Document

Always the same, regardless of tool:

Strategic foundation
Content concepts
Exploration parameters
Success criteria

Tool choice = Implementation detail:

User chooses based on preference/access
Freya adapts prompts to chosen tool
Same strategy → different execution tools

Supported Tools (Examples)

Nano Banana Pro:

Best text rendering
Good UI layouts
Manual workflow
Freya generates: System instructions + Project context + Structured prompts

DALL-E 3:

API access
Good automation
Freya generates: API-friendly prompts + Batch scripts

Midjourney v7:

Beautiful aesthetics
Style consistency (--sref)
Freya generates: Discord-formatted prompts + Style references

Flux Pro:

Fast generation
Good prompt adherence
Freya generates: Technical prompts + API integration

Integration Points with Existing WDS

Phase 1: Project Brief

Add question:

"Will this project require visual design deliverables?" (YES/NO)
If YES: "Do you have existing brand assets?" (YES/NO/PARTIAL)

Phase 2: Trigger Mapping

No changes to workflow

Observe user context for device clues
Demographics inform visual direction

Phase 2.5: Visual Design Brief

New workflow - insert here

Triggered if visual design = YES
Freya creates Visual Design Brief
Runs tool selection workshop
Generates tool-specific setup
Facilitates exploration
Extracts design tokens

Phase 3: PRD/Platform

Informed by Phase 2.5:

Device priorities (from explorations)
Technical constraints (from approved direction)

Phase 4: UX Design

Uses approved direction:

Design tokens from Phase 2.5
Visual consistency maintained
Structured prompts (not exploratory)

Output Format (Return to Cursor)

What User Brings Back

1. Visual Assets

2.5-visual-design-brief/explorations/
├── [page]/[direction].png
└── approved-direction/mood-board.png

2. Design Tokens (JSON)

{
  "colors": {...},
  "typography": {...},
  "spacing": {...},
  "layout": {...}
}

3. Code Snippets (if generated)

/* Example CSS from approved direction */
:root {
  --color-primary: #0A0E27;
  --color-accent: #00FF9D;
  --font-heading: 'Inter', sans-serif;
  --spacing-unit: 8px;
}

4. Documentation

- visual-design-brief.md
- selection-rationale.md
- design-token-documentation.md

How Freya Integrates

Step 1: Save Assets

Move images to appropriate folders
Organize by phase and purpose

Step 2: Load Design Tokens

Parse JSON files
Validate against Visual Prosperity standards
Save to design-system/tokens/

Step 3: Update Project State

Mark Phase 2.5 complete
Document approved direction
Update project outline

Step 4: Prepare for Phase 4

Load design tokens for scenario work
Reference approved visual direction
Ready to generate structured prompts

Success Criteria

Visual Prosperity Achieved

✅ Typography-first hierarchy
✅ Generous white space
✅ Premium color palette (3-4 colors)
✅ Strategic purpose for every element
✅ No Tailwind defaults
✅ No generic UI kit aesthetics

Strategic Alignment

✅ Triggers identified psychological drivers
✅ Resonates with target demographics
✅ Differentiates from competitors
✅ Supports brand positioning

Process Quality

✅ Strategy informed visual exploration
✅ Multiple directions explored before commitment
✅ Clear rationale for chosen direction
✅ Design tokens extracted and documented
✅ Smooth integration back into WDS workflow

Next Steps (Dogweek Project Prototype)

Phase 1: Test Setup

Complete Dogweek Project Brief
Complete Dogweek Trigger Mapping
Trigger Phase 2.5 Visual Design Brief

Phase 2: Tool Selection

Run tool selection workshop
Choose image generation model (likely Nano Banana)
Set up access/credentials

Phase 3: Exploration

Freya generates Visual Design Brief
Freya generates tool-specific setup (system instructions, project context)
Freya generates exploration prompts
User executes in chosen tool
Collect visual explorations

Phase 4: Integration

Select winning direction
Extract design tokens
Bring assets + tokens back to Cursor
Freya integrates into design system
Proceed to Phase 4 scenarios

Phase 5: Refinement

Document what worked / what didn't
Refine prompts and workflow
Update architecture based on learnings
Integrate into WDS core

Open Questions (To Resolve in Prototype)

Design token extraction accuracy: How well can Freya extract tokens from generated images?
Prompt effectiveness: Do loose exploration prompts generate useful variety?
Tool comparison: Should we test multiple tools in parallel?
Iteration cycles: How many exploration rounds are typically needed?
Integration friction: What's the smoothest way to bring results back to Cursor?
Design system evolution: How do tokens from Phase 2.5 evolve through Phase 4?

Key Principles

Strategy First: Visual exploration happens AFTER strategy is clear
Explore Before Committing: Wild concepts before detailed specs
Tool Agnostic: Strategy document survives tool changes
Visual Prosperity: Eliminate defaults, cultivate premium aesthetics
Human in Loop: Designer makes final creative decisions
Strategic Alignment: Every visual choice serves psychological triggers
Design System Thinking: Extract reusable patterns, not one-offs

eira-visual-designer.md - Eira agent definition and system instructions
Visual Design Brief template (to be created)
Tool-specific prompt templates (to be created)
Design token extraction guide (to be created)

Status: Architecture complete - ready for prototype testing in Dogweek project

Next Session: Implement and test in real project, refine based on learnings

Session log created by Freya (WDS Designer Agent) - 2026-01-04

24 KiB Raw Blame History