sar/.agents/skills/wds-4-ux-design/data/guides/NANO-BANANA-PROMPT-GUIDE.md

# Nano Banana Prompt Composition Guide

**Purpose:** How to translate WDS page specifications into effective AI image generation prompts.

---

## The Core Problem

Page specifications are verbose (500–1000+ lines). Nano Banana accepts:
- **prompt**: max 8192 characters
- **system_instruction**: max 512 characters
- **input images**: up to 3 reference images for visual conditioning

This guide defines what to extract, what to skip, and how to balance creativity with spec adherence.

---

## What to Extract from Specs

### Always Include

| Element | Where to find it | Example |
|---------|-----------------|---------|
| **Image descriptions** | `Content > Image:` fields | "Öland landscape — open fields, workshop in distance, blue sky" |
| **Section names + order** | `## Page Sections` headers | Header → Hero → Vehicle Icons → About → Trust → Seasons → Footer |
| **Section purposes** | `**Purpose:**` lines | "Instant emotional connection and phone number access" |
| **Primary headlines** | `Content > SE/EN:` (pick one language) | "Vi är Källa Fordonservice" |
| **CTA / action labels** | Button/link content fields | "Ring 0485-270 70", "Läs mer om oss" |
| **Color values** | Visual direction or design tokens | Blues/grays, white background, red accent |
| **Font family** | Typography direction | Inter or similar sans-serif |
| **Layout pattern** | Layout Structure section | "3 columns desktop, 1 column mobile" |
| **Brand mood words** | Visual direction | Professional, local, reliable, Nordic |

### Always Skip

| Element | Why |
|---------|-----|
| Object IDs (`hem-hero-image`) | Development metadata, irrelevant to visual output |
| HTML tags (h1, h2, p, section) | Semantic structure, not visual |
| Component file paths | Internal references |
| Behavior / interaction states | Hover/active/disabled — static image can't show these |
| Accessibility attributes (aria-label) | Screen reader metadata |
| SEO section (meta descriptions, structured data) | Search engine metadata |
| Object Registry tables | Summary tables with no visual info |
| Checklists and Open Questions | Process tracking |
| Secondary/tertiary language content | Pick one language per generation |
| Font sizes in px | Too prescriptive for AI — describe hierarchy instead ("large bold headline", "smaller body text") |

---

## Prompt Budget Allocation

**Total: 8192 characters**

| Section | Faithful | Expressive | Vision |
|---------|----------|------------|--------|
| Creative preamble | 200 | 300 | 500 |
| Page/section context | 300 | 300 | 200 |
| Layout structure | 800 | 600 | 200 |
| Image descriptions | 1000 | 1000 | 1500 |
| Design tokens (colors, fonts) | 500 | 400 | 300 |
| Key content (headlines, CTAs) | 2000 | 1500 | 500 |
| Brand atmosphere | 200 | 500 | 1000 |
| **Buffer / user additions** | **3192** | **3592** | **3992** |

The buffer is intentionally large — prompt quality comes from clarity, not length.

---

## System Instruction Templates (max 512 chars)

### Faithful Mode
```
Professional UI designer creating a clean, realistic interface mockup.
Use specified colors and typography precisely. Show actual text content,
not placeholders. Standard mobile/web UI patterns. Sharp, production-ready look.
```

### Expressive Mode
```
Creative UI designer making a polished, visually appealing interface.
Follow the general layout structure but take creative liberties with
visual treatments, lighting, depth, and atmosphere. Make it look like
a real, beautiful product that inspires confidence.
```

### Vision Mode
```
Brand visual artist creating an artistic concept. Capture the emotional
essence and personality of the brand. Focus on color story, mood, light,
and feeling. The layout is a rough guide, not a constraint. Create something
that makes people feel the brand before they read a word.
```

### Image Asset Mode
```
Professional photographer/illustrator creating a single image for use
on a website. The image should feel authentic, not stock-photo polished.
Natural lighting, real environments, documentary style. High quality,
suitable for hero banners or content cards.
```

---

## Worked Example: Kalla 1.1-hem Hero Image

**Source spec:** 1.1-hem.md, Object `hem-hero-image`

**Spec image description:**
> "Öland landscape — open fields, the workshop visible in the distance, blue sky. Warm, inviting, unmistakably Öland."

**User creative override:**
> "Make the sky a dramatic sunset"

**Reference images provided:**
1. Verkstad-01.jpg (workshop exterior)
2. Verkstad-02.jpg (workshop angle)
3. Kalla-Logo.jpg (brand logo — for color/style context)

**Composed system_instruction** (298 chars):
```
Professional photographer creating a hero banner image for a Swedish
car workshop website. Authentic, documentary style. Natural Öland light.
The workshop is a community hub — warm, trustworthy, approachable.
Not stock-photo polished. Real place, real feeling.
```

**Composed prompt** (682 chars):
```
Wide landscape photograph of a Swedish car workshop (Källa Fordonservice)
on northern Öland. The workshop building is visible in the middle distance,
surrounded by the flat, open Öland landscape with low stone walls and
sparse vegetation.

The sky is a dramatic sunset — deep oranges, purples and golds spreading
across a vast Nordic sky. The golden light catches the workshop building,
making it glow warmly against the landscape.

The mood is warm, inviting, and unmistakably Öland — wide horizons,
quiet strength, a place you can trust. The workshop feels like it belongs
to the landscape, not imposed on it.

Colors: warm golden sunset tones, cool blue-gray Swedish twilight,
earthy workshop browns. Professional but human.
```

**Parameters:**
- `aspect_ratio`: `16:9` (hero banner)
- `model_tier`: `pro`
- `negative_prompt`: "stock photo, generic, urban, text overlay, watermark"

---

## Worked Example: Full Page Mockup

**Scope:** Full page, Expressive mode, Mobile (9:16)

**Composed prompt** (~2800 chars):
```
Mobile UI mockup (portrait) for "Källa Fordonservice" — a car workshop
website in northern Öland, Sweden. Clean Swedish minimalism, professional
but warm and approachable.

Page layout from top to bottom:

1. HEADER: Logo "Källa Fordonservice" on left. Phone icon and "Kontakta"
   button on right. Clean, minimal top bar.

2. SERVICE MENU: Horizontal scrollable menu below header with service
   categories: Service, Reparationer, AC, Däck, Yrkesmaskiner, Tunga fordon.
   Subtle, secondary navigation.

3. HERO SECTION: Full-width landscape photo of Öland with workshop in
   distance, dramatic sunset sky. Phone number "0485-270 70" overlaid
   in a semi-transparent dark box with white text, centered in lower third.
   The hero image dominates — emotional first impression.

4. VEHICLE ICON BAR: Row of 4 small vehicle icons below hero:
   Motorcycle, Car, Motorhome, Bus. Simple line icons with labels.
   Shows breadth of service.

5. ABOUT PREVIEW: Two-column on desktop, stacked on mobile.
   Left: Photo of two mechanics (Björn & Nauriz) in workshop, candid,
   friendly. Right: Heading "Vi är Källa Fordonservice" + short intro
   paragraph. Trust badges row below (3 small partner logos, muted).
   "Läs mer om oss →" link.

6. TRUST CARDS: Three cards in a row (stacked on mobile). Each has:
   image (4:3), heading, 2-line teaser text. White cards with subtle shadow.
   Topics: "En riktig bilverkstad", "Däck till alla fordon",
   "Del av Autoexperten".

7. SEASONS SECTION: Heading "Så skiftar säsongerna i Källa" centered.
   Four cards below (2×2 grid on mobile): Spring, Summer, Autumn, Winter.
   Each with atmospheric Öland seasonal photo, season name, teaser text.
   Warm, editorial feel.

8. FOOTER: Contact info, address, phone. Simple, functional.

Design details:
- Background: white or very light gray
- Text: dark charcoal, strong readable sans-serif (Inter)
- Accent: deep blue for links, subtle red for CTAs
- Cards: white with soft shadow (2-3px), rounded corners (4-8px)
- Images: warm, authentic, documentary style
- Generous whitespace between sections
- Mobile single-column, thumb-friendly
```

---

## Section Focus Mode

When generating a single section at high fidelity, spend the full prompt budget on that section. Include:

- All object details for that section
- Full content text (still one language)
- Precise visual style descriptions
- Layout relationships between objects
- Image descriptions with user overrides

This is useful for iterating on hero sections, card layouts, or navigation patterns before generating the full page.

---

## Generation Modes: Generate vs Edit

Nano Banana supports two fundamentally different modes:

### Generate Mode
Creates images from scratch. Reference images (input_image_path_1/2/3) influence **style and subject** but NOT layout.

**Use for:**
- Standalone image assets (hero photos, card images)
- Wireframes from page specifications (no visual input needed)
- When you have NO layout reference to work from

### Edit Mode
Transforms an existing image. The primary input image (slot 1) controls **layout structure** — section order, proportions, element placement are preserved. Additional images influence style.

**Use for:**
- Wireframe → Mockup transformation (recommended pipeline)
- Sketch → Digital wireframe conversion
- Iterative refinement of existing mockups

**Critical rules for edit mode:**
- **Always pin `aspect_ratio`** — if omitted, model may change aspect ratio and lose content
- **Targeted edits work, broad edits fail** — "add a nav bar to the header" succeeds; "make everything premium" drops sections
- **Adding > Removing** — model handles adding visible elements well, struggles to remove or restructure existing elements
- **Slot 1 = layout source** — put the image whose structure you want to keep in input_image_path_1

---

## Recommended Pipeline: Spec → Wireframe → Mockup

The most reliable approach for full-page mockups is a two-step pipeline:

### Step 1: Spec → Clean Wireframe (generate mode)

Use generate mode to create a clean digital wireframe from the page spec's layout structure. No photography, no colors — just gray boxes and text labels.

**Why this works:** Wireframes are NB's strength. Gray boxes + labels don't require photography or realistic text rendering. The structured layout data (column ratios, aspect ratios, element counts) translates directly into accurate placement.

**System instruction template:**
```
UX wireframe designer creating clean, precise digital wireframes. Use only
grayscale — light gray boxes for image placeholders, medium gray for backgrounds,
dark gray for text labels. No photography, no colors, no decoration. Professional
wireframe style. Clear section boundaries.
```

**Prompt structure:**
Describe each section top-to-bottom with specific layout instructions:
- Column ratios ("Left column ~50%, Right column ~50%")
- Element counts ("3 cards side by side", "11 icons in a row")
- Content labels ("heading: Vi är Källa Fordonservice")
- Image placeholder labels ("[HERO IMAGE — Öland landscape]")

**Preventing wireframe label leakage into mockups:**
ANY text in the wireframe will bleed into the mockup. This includes:
- Section annotations ("SECTION 1 — HEADER", "TRUST CARDS", "FOOTER")
- Placeholder labels ("[LOGO]", "[HERO IMAGE]", "[PHOTO — Name]")
- Descriptive text inside gray boxes

To minimize leakage:
- Use only real content text (actual headings, labels) — these are fine since they belong in the mockup
- Use empty gray boxes without text labels for image placeholders
- Avoid section titles that aren't part of the actual page design
- If labels are needed for your own reference, accept that some may leak and plan to iterate

**Parameters:**
- `mode`: `generate`
- `aspect_ratio`: `9:16` (full page portrait scroll)
- `model_tier`: `pro` (worth the quality for layout accuracy)
- `negative_prompt`: "photography, realistic images, colorful design, stock photos, polished UI, gradients, shadows"

### Step 2: Wireframe → Polished Mockup (edit mode)

Use edit mode with the generated wireframe as primary input to apply visual design while preserving layout.

**System instruction template:**
```
UI designer transforming wireframes into polished website mockups. Follow
the wireframe layout EXACTLY — section order, proportions, element placement.
Apply clean [brand style] with warm photography. Professional but human.
[viewport type] viewport.
```

**Prompt structure:**
Describe what to fill each placeholder with:
- Hero: specific scene description
- Photos: subject descriptions
- Cards: imagery for each card
- Colors: specific palette to apply
- Typography: font style

**Parameters:**
- `mode`: `edit`
- `input_image_path_1`: path to wireframe from step 1
- `input_image_path_2`: reference photo (optional, for style conditioning)
- `aspect_ratio`: MUST match step 1 (e.g., `9:16`)
- `model_tier`: `pro`
- `negative_prompt`: "wireframe style, gray boxes, placeholder text, section labels, annotations, sketch lines"

### Why This Pipeline Outperforms Direct Generation

| Approach | Layout accuracy | Visual quality | Reliability |
|----------|----------------|----------------|-------------|
| Direct generate (no reference) | Low — model invents layout | Medium | Unpredictable |
| Sketch → Mockup (edit) | Good — follows sketch structure | Medium-High | Good |
| **Spec → Wireframe → Mockup** | **High — spec-accurate** | **High** | **Best** |
| Iterative editing | Degrades with each pass | Varies | Poor for removal/restructure |

---

## Multi-Pass Strategy

Alternative workflow for thorough visual exploration (when not using the wireframe pipeline):

1. **Image assets first** — Generate key images (hero photo, card photos) as standalone assets
2. **Section focus** — Design critical sections (hero, trust cards) at high fidelity
3. **Full page mockup** — Combine everything into a page overview
4. **Iterate** — Refine based on user feedback

Each pass builds on the previous — reference images from pass 1 can condition pass 2.

---

## Batch Generation: Similar Page Sequences

Many projects have groups of pages that share the same layout but differ in content: vehicle type pages, service pages, article pages, product pages.

### The Template-and-Swap Pattern

1. **Design once** — Generate and iterate on ONE page until the user approves the visual direction
2. **Extract the template** — The approved prompt becomes a reusable template with swap points
3. **Generate the rest** — For each remaining page, swap in the unique content and generate

### Example: 11 Vehicle Type Pages

**Template prompt** (from approved 3.4-personbil):
```
Mobile UI mockup for a vehicle type page on "Källa Fordonservice" website.
Swedish minimalism, professional but warm.

Layout:
1. HEADER + SERVICE MENU (shared)
2. HERO: Full-width photo of {VEHICLE_IMAGE_DESCRIPTION}
   Heading: "{VEHICLE_NAME}" in bold
3. VEHICLE ICON BAR: {VEHICLE_TYPE} icon highlighted
4. SERVICES LIST: What we do for {VEHICLE_NAME_LOWERCASE}:
   {SERVICE_BULLETS}
5. CTA: "Ring oss: 0485-270 70"
6. RELATED ARTICLES: 2-3 article cards relevant to {VEHICLE_TYPE}
7. FOOTER (shared)

Design: white background, dark charcoal text, deep blue accent,
white cards with subtle shadow, warm authentic imagery.
```

**Swap table:**

| Page | VEHICLE_NAME | VEHICLE_IMAGE_DESCRIPTION | SERVICE_BULLETS |
|------|-------------|--------------------------|-----------------|
| 3.1 | Gräsklippare | Lawn mower on green garden, Öland summer | Service, reparation, vintervård |
| 3.2 | Moped/Skoter | Moped on coastal road | Service, reparation, besiktning |
| 3.9 | Traktor | Tractor in agricultural field, earth tones | Service, hydraulik, däck |
| ... | ... | ... | ... |

### Key Principles for Batch Generation

- **Shared parameters stay fixed:** system_instruction, creative mode, aspect ratio, design tokens, reference images
- **Only content swaps:** image descriptions, headlines, service lists, section-specific text
- **Sequential generation:** Generate one at a time, quick-review each, flag outliers for iteration
- **Use `flash` model tier** for batch runs (faster, cheaper) — save `pro` for the template page
- **Track everything** in the agent experience file for reproducibility

---

## Known Limitations

Documented from extensive testing on Kalla Fordonservice 1.1-hem (13+ generations, Feb 2026).

### What NB is Good At

| Use case | Quality | Notes |
|----------|---------|-------|
| **Wireframe generation from spec** | Excellent | Best use case. Structured layout data → accurate gray-box wireframes |
| **Single image assets** (hero photos, card images) | Good | Generate mode with descriptive prompts works well |
| **Style transfer via reference images** | Good | Slot 2-3 photos influence color/mood/subject effectively |
| **Adding elements** (edit mode) | Fair | Can add nav bars, icons, logos to existing images |
| **Wireframe → Mockup transformation** | Fair | Layout preserved, but wireframe text/labels leak through |

### What NB Struggles With

| Limitation | Severity | Workaround |
|------------|----------|------------|
| **Text rendering** | Critical | ALL generated text is garbled. Spec is source of truth — never trust AI text. Use mockups for layout/mood only |
| **Logo reproduction** | High | Cannot faithfully reproduce a provided logo. Generates an "inspired by" version. Use real logo in implementation |
| **Wireframe label leakage** | High | Placeholder text like "[LOGO]", "TRUST CARDS", section annotations bleed from wireframe into mockup. Minimize text in wireframes |
| **Removing elements** (edit mode) | High | Edit mode cannot reliably remove things (icons, labels, sections). Regenerate from wireframe instead |
| **Restructuring layout** (edit mode) | High | Cannot move elements to different positions (e.g., nav links from separate row into header). Regenerate |
| **Broad edit instructions** | High | "Make everything premium" causes section loss. Must use targeted, specific edits |
| **Aspect ratio drift** (edit mode) | Medium | If `aspect_ratio` not pinned, model changes it and drops below-fold content |
| **Grid layouts** | Medium | 2×2 grids often flatten to 1×4 rows. Specify "2 rows, 2 columns" explicitly |
| **Iterative degradation** | Medium | Each edit pass introduces drift. After 2-3 edits, regenerate from wireframe |

### Critical Rules

1. **All text is wrong** — mockups are for layout and visual direction only, never for content accuracy
2. **Always pin `aspect_ratio` in edit mode** — omitting it is the #1 cause of content loss
3. **One targeted change per edit** — never combine multiple changes in one edit call
4. **Regenerate > Edit for structural changes** — if you need to move, remove, or restructure elements, go back to wireframe step
5. **Pro model for anything structural** — Flash is only for quick image asset iterations
6. **No section labels in wireframes** — any text in the wireframe will appear in the mockup

### Where NB Fits in the Design Workflow

NB is best as an **image asset production tool**, not a layout or mockup tool. AI-generated wireframes and mockups are dead images — the user cannot drag a section, resize a column, or annotate feedback directly. Use editable tools (Excalidraw, Figma) for layout iteration.

**Use NB for:**
- Hero photography (landscapes, buildings, environments)
- People photos (team portraits, candid shots)
- Card and article imagery (seasonal photos, product shots)
- Mood and atmosphere exploration
- Placeholder images during design reviews

**Do NOT use NB for:**
- Wireframes (use Excalidraw — user can edit directly)
- Production mockups (use Google Stitch for HTML/CSS or Figma)
- Anything where text accuracy matters (all NB text is garbled)
- Anything the user needs to iterate on by hand

### Model Tiers

| Tier | Model | Input images | Strengths | Cost |
|------|-------|-------------|-----------|------|
| **Flash** | Gemini 2.5 Flash Image | 3 max | Fast, cheap. Good for single image assets | Low |
| **Pro** | Gemini 3 Pro Image | 14 objects + 5 characters | Better structural accuracy, higher thinking. Worth it for wireframes and first-pass mockups | Higher |

### Technical Limits

- Prompt: 8192 characters max
- System instruction: 512 characters max
- Negative prompt: 1024 characters max
- Input images don't consume Claude context — sent directly to Gemini via filesystem
- Output thumbnails returned by default (full image via `return_full_image: true`)
- `file_id` parameter causes validation errors when combined with `input_image_path` (known NB bug — use paths only)