---
name: design-agent
description: UI/UX design coordination, brand development, and design documentation for Symph Agency Design phase. Use when creating UI screens, brand guidelines, or preparing design specs.
---

# Design Agent

Execute the Design phase of Symph Agency pipeline.

## Workflow Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                      DESIGN PHASE WORKFLOW                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  0. BRAND CHECK (Router)                                        │
│     └─> Does product have existing brand?                       │
│         ├─> YES: Skip to Step 2 (Sample Screens)                │
│         └─> NO:  Run full brand-identity workflow               │
│                                                                  │
│  1. BRAND IDENTITY (if needed)                                  │
│     ├─> 1a. Trend Research (2026 design trends)                 │
│     ├─> 1b. AI-Brand Anti-Patterns Audit                        │
│     ├─> 1c. Moodboard (visual direction)                        │
│     ├─> 1d. Graphics Style Definition                           │
│     ├─> 1e. Logo generation                                     │
│     ├─> 1f. Typography + Colors                                 │
│     ├─> 1g. Voice guidelines                                    │
│     └─> 1h. Social media templates                              │
│         └─> 🔄 HUMAN REVIEW (Approve/Revise everything above)   │
│                                                                  │
│  2. SAMPLE SCREENS (3 key screens)                              │
│     └─> Generate with Nano Banana Pro                           │
│         └─> 🔄 HUMAN REVIEW (Approve/Revise)                    │
│                                                                  │
│  3. ALL SCREENS (from PRD user stories)                         │
│     └─> Generate remaining screens                              │
│         └─> 🔄 HUMAN REVIEW (Approve/Revise)                    │
│                                                                  │
│  4. FIGMA FILE                                                  │
│     └─> Create Figma file with all screens                      │
│         └─> Share link for designer finalization                │
│                                                                  │
│  5. FINAL SIGN-OFF                                              │
│     └─> 🔄 HUMAN: Mark Design "Done"                            │
│         └─> Advance to Build Phase                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

---

## State Machine

Workflow state tracked in: `[product]/agency/artifacts/design/workflow.json`

| State | Description | Next Action |
|-------|-------------|-------------|
| `not_started` | Design phase not begun | Run brand check |
| `brand_check` | Checking for existing brand | Route to branding or screens |
| `trend_research` | Researching 2026 design trends | Auto-complete → ai_audit |
| `ai_audit` | Generating AI-brand anti-patterns list | Auto-complete → moodboard |
| `moodboard_generating` | Creating moodboard / visual direction | Present to human |
| `graphics_style_generating` | Defining graphics style | Present to human |
| `brand_identity_running` | Running logo/type/color/voice/social | Present to human |
| `brand_identity_review` | Awaiting brand approval (all sections) | Human approves/revises |
| `brand_identity_approved` | Brand system complete | Generate sample screens |
| `branding_skipped` | Using existing brand | Generate sample screens |
| `sample_screens_generating` | Creating 3 sample screens | Present to human |
| `sample_screens_review` | Awaiting approval | Human approves/revises |
| `sample_screens_approved` | Samples locked | Generate all screens |
| `all_screens_generating` | Creating remaining screens | Present to human |
| `all_screens_review` | Awaiting approval | Human approves/revises |
| `all_screens_approved` | All screens locked | Generate Figma |
| `figma_generating` | Creating Figma file | Share link |
| `figma_ready` | Figma available | Await final sign-off |
| `final_review` | Human finalizing in Figma | Human marks done |
| `completed` | Design phase done | Advance to Build |

---

## Step-by-Step Execution

### Step 0: Brand Check (Router)

**First, determine if the product needs full branding or already has one.**

```bash
PRODUCT="product-name"
PRODUCT_DIR="/home/aria/products/$PRODUCT"

# Check for existing brand assets
BRAND_EXISTS=false

if [ -d "$PRODUCT_DIR/brand-guidelines" ] || \
   [ -f "$PRODUCT_DIR/design/brand-guidelines.md" ] || \
   [ -f "$PRODUCT_DIR/design/design.yaml" ] || \
   [ -d "$PRODUCT_DIR/design/logos" ]; then
  BRAND_EXISTS=true
fi
```

**Routing Decision:**

| Condition | Action | Next State |
|-----------|--------|------------|
| `brand-guidelines/` folder exists | Skip branding | `branding_skipped` → Step 2 |
| `design/design.yaml` has colors + fonts | Skip branding | `branding_skipped` → Step 2 |
| `design/logos/` folder with logo files | Skip branding | `branding_skipped` → Step 2 |
| None of the above | Run full brand-identity | `brand_identity_running` → Step 1 |

**Update workflow.json:**
```json
{
  "state": "brand_check",
  "brandCheck": {
    "existingBrandFound": true/false,
    "assetsFound": ["brand-guidelines/", "design.yaml", ...],
    "decision": "skip" | "run_brand_identity"
  }
}
```

---

### Step 1a: Trend Research (MANDATORY — every new brand)

**Always run this first.** Trends inform what looks current vs. dated for the product's audience and category.

Use the `trend-research` skill:
```
Read skills/trend-research/SKILL.md and execute.

Focus areas for this product:
- Industry: [from PRD — e.g. fintech, health, B2B SaaS]
- Audience: [from PRD target personas]
- Platform: [primary surfaces — mobile app, web dashboard, landing page]
- Year: 2026
```

**Key questions to answer from research:**
- What visual styles are dominating this industry in 2026?
- What color directions are trending (palettes, moods)?
- What typography treatments are current?
- What layout patterns are resonating (bento grids, full-bleed, editorial)?
- What motion/animation styles are in use?
- What are leading competitors doing visually that works?

**Save to:** `[product]/design/trend-research.md`

**Update workflow.json state:** `trend_research` → auto-advance to `ai_audit`

---

### Step 1b: AI-Brand Anti-Patterns Audit (MANDATORY — every new brand)

**Generate a product-specific list of patterns that make a brand look AI-generated.** These become hard constraints during all subsequent design decisions.

**Research and document the following categories:**

#### Universal AI-Brand Red Flags
These apply to every product — include them verbatim:

| Pattern | Why it looks AI-generated | What to do instead |
|---------|--------------------------|-------------------|
| Gradient blue-to-purple hero | The default "AI company" palette — overused to death | Pick a distinct, opinionated color story rooted in the product's category |
| Floating 3D blob shapes | Overused in AI SaaS landing pages circa 2022–2024 | Use purposeful illustration, photography, or clean geometry |
| "Poppins + Inter" as the only type pairing | AI tools default to these; they signal no typographic intent | Make a deliberate type choice that reflects brand personality |
| Generic robot/brain/network node icons | Signals "AI did this" immediately | Use category-relevant iconography; commission or customize |
| Hyper-symmetrical, perfectly balanced layouts | Real designers introduce intentional tension | Use asymmetry, white space variation, editorial hierarchy |
| Neon glows on dark backgrounds | "Cyberpunk AI" cliché — every AI brand did this in 2023 | Use light thoughtfully; glows should have a reason |
| Stock photo people smiling at laptops | Screams template | Real photography or high-quality illustration with a distinct POV |
| "Powered by AI" badges everywhere | Over-explaining undermines trust | Show capability through UX, not labeling |
| Helvetica Neue / sans-serif monoculture | Zero personality | Introduce at least one expressive typeface for headlines |
| Cookie-cutter card grid layouts | The default AI output for dashboards | Vary card sizes, introduce hierarchy, use whitespace deliberately |

#### Product-Specific Anti-Patterns
Research and add 3–5 patterns specific to this product's category:
```
- What do bad [industry] brands look like in 2026?
- What visual clichés are saturating this specific category?
- What would a lazy AI do with this product's brand?
- What does the top competitor do that feels generic?
```

**Save to:** `[product]/design/ai-anti-patterns.md`

**This file is referenced during every generation step** — include it as a constraint in all image generation prompts.

**Update workflow.json state:** `ai_audit` → auto-advance to `moodboard_generating`

---

### Step 1c: Moodboard (MANDATORY — new section)

**Create a visual moodboard that establishes the emotional direction of THIS specific brand before any design decisions are locked.**

The moodboard answers: *"What should it feel like to experience this brand?"*

#### ⚠️ Product-Anchoring Requirement (CRITICAL)

The moodboard must be derived from this product's unique context — not pulled from generic AI defaults or recycled from other Symphony products.

**Before writing a single word of the moodboard, answer these anchoring questions:**

1. **What is the product's core emotional promise to its user?** (Not what it does — how it should *feel*)
   - e.g. "It should feel like having a calm, knowledgeable friend who handles the confusing government stuff for you" (not "modern and clean")

2. **What is the user's emotional state when they first open this product?** (Frustrated? Excited? Anxious? Confused?)
   - The brand should meet them where they are, then move them somewhere better.

3. **What does this product's world look like?** (Physical environments, objects, textures associated with its users)
   - e.g. A badminton queue app → court halls, shuttlecocks, the feeling of a Saturday morning with your group

4. **What is one word this product should NEVER feel like?** (And why)

These answers become the creative brief constraints. Every moodboard decision must trace back to one of these answers.

#### ⚠️ Cross-Brand Uniqueness Check (MANDATORY)

Run the brand registry script before finalizing any color or type direction:

```bash
bash /home/aria/.openclaw/workspace/skills/design-agent/scripts/build-brand-registry.sh
cat /tmp/symphony-brand-registry.md
```

**Extract the "taken" visual territory:**
- What primary colors are already in use across Symphony products?
- What font combinations are overused?
- What themes (dark vs. light, earthy vs. techy) are saturated?
- Which emotional territories are already claimed?

**Uniqueness rule:** The new brand's color + type + emotional direction combination must not closely resemble any existing Symphony product. If a direction feels similar, shift it — different hue family, different typographic personality, different emotional tone.

**Document the collision check in the moodboard:**
```markdown
## Uniqueness Check
Existing Symphony palette territory (from registry):
- Purple/violet: Overture (#7c5cff)
- Teal + Orange: SmashSlot (#0EA5A0 / #F97316), Badminton Queue
- Blue: Adulting PH (#2563EB), Condominium (#0066CC)
- Earthy green + terracotta: Tiangge (#465940 / #C07B5A)

This brand's chosen direction: [X] — NOT used by any existing product.
Closest existing: [Y] — differentiated by [Z].
```

---

**Use the `moodboard` skill:**
```
Read skills/moodboard/SKILL.md and execute.

Brief for the moodboard:
- Product: [name + one-line description]
- Industry: [category]
- Target audience: [from PRD personas]
- Core emotional promise: [from anchoring question 1]
- User's emotional state on first open: [from anchoring question 2]
- Product's physical world: [from anchoring question 3]
- Word it must never feel like: [from anchoring question 4]
- Trend inputs: [reference key findings from trend-research.md]
- Anti-patterns to avoid: [reference top 3 from ai-anti-patterns.md]
- Taken visual territory (avoid): [list from uniqueness check]
```

**Moodboard must include:**

1. **Emotional Direction** — 3–5 adjectives that describe the brand feeling. Specific and owned, derived from the anchoring questions. NOT generic ("modern", "clean", "professional").
   - ❌ Wrong: "modern, clean, trustworthy"
   - ✅ Right: "quietly resourceful, warmly no-nonsense, like your smartest tito who also has a law degree"

2. **Color Mood** — 2–3 color directions to explore (moods and references, not hex codes yet). Each direction must be named after the feeling it creates, not the color:
   - ✅ "Worn leather + burnt orange — reliable craftsperson energy"
   - ✅ "Midnight ink + warm gold — intelligent gravitas without the coldness"
   - Each direction must be checked against the registry to confirm it's unclaimed.

3. **Typographic Mood** — 2 directions. Grounded in the product's emotional promise:
   - ✅ "Old-style serif headline + humanist mono body — feels like a trusted reference book, not a SaaS dashboard"
   - ✅ "Geometric display + neutral sans — precision without sterility"

4. **Imagery Style** — What kind of visuals belong in this world? Specific to the product's physical and emotional context, not generic SaaS imagery.

5. **Reference Grid** — 6–9 real-world visual references (actual brands, campaigns, products — NOT generic "AI company" brands). Sources: Dribbble, Behance, Brand New, Awwwards, real-world packaging, editorial design. Search the web for actual references. For each: name, URL, what specific element to reference.

6. **Anti-Pattern Callouts** — Explicitly mark 2–3 references as "what to avoid" with a specific reason tied to this product.

**Output:**
- `[product]/design/moodboard.md` — Written moodboard with references and rationale
- `[product]/design/moodboard.html` — Visual HTML version (use the moodboard skill's output)

**This section is presented to the human for approval together with Graphics Style (Step 1d) before proceeding.**

---

### Step 1d: Graphics Style Definition (MANDATORY — new section)

**Define the graphic language of the brand** — the specific visual rules that govern how the product looks across every surface. This is more specific than the moodboard (direction) and more foundational than brand guidelines (execution details).

The graphics style answers: *"If someone picked up a piece of this brand with no logo, would they still know it's us?"*

#### ⚠️ Product-Anchoring Requirement (CRITICAL)

Every graphics style decision must be justified by one of these questions:
- **Does this reflect how the user experiences this product's world?** (textures, environments, objects)
- **Does this match the emotional tone set in the moodboard?**
- **Does this feel specific to this product's category and audience — or could it apply to any product?**

If a decision can't be justified by one of the above, it's a generic default. Replace it with something specific.

#### ⚠️ Cross-Brand Differentiation Check (MANDATORY)

Before finalizing the graphics style, review the brand registry and explicitly call out how this product's graphic language differs from the closest Symphony neighbors:

```markdown
## Differentiation from Existing Symphony Products
- [closest product A] uses [X style] — this product uses [Y] instead because [reason]
- [closest product B] uses [X approach] — this product uses [Y] instead because [reason]
```

No two Symphony products should share the same combination of: illustration style + photography tone + surface treatment + layout personality.

---

**Document the following sections:**

#### Illustration & Iconography Style
- **Illustration approach** — Be specific. Not "flat design" — *why* flat, at what weight, with what level of detail, in what palette subset.
  - e.g. "No illustration — real photography only, because this product is about real people's real financial situations, not an abstracted concept"
  - e.g. "Loose editorial line art, 2px stroke, single ink color on cream — conveys handcrafted intelligence, not tech polish"
- **Icon set:** Which library (Lucide preferred), sizes, stroke weight — and any custom overrides
- **What's banned for illustration:** List specific styles that don't belong here

#### Photography & Imagery Tone
- **Subject matter:** What's in the photos — specific to this product's world
- **Lighting:** (natural / studio / dramatic / flat) — with rationale
- **Color grading:** (warm / cool / desaturated / high contrast / muted) — tied to emotional direction
- **Treatment:** (full-bleed / contained / duotone / B&W) — with usage context
- **What's explicitly banned:** Be specific to this product. Not just "no stock smiles" — *which* imagery would look wrong here.

#### Texture & Surface Style
- **Background treatment:** Specific choice with rationale — why does this texture/material fit this brand's world?
- **Card/container style:** (hard shadow / soft shadow / no shadow / border / glass / layered) — matched to the brand's depth personality
- **Depth approach:** (flat / subtle layering / strong z-depth) — matched to the product's information density needs

#### Motion & Animation Style *(for digital products)*
- **Personality:** (snappy / flowing / mechanical / playful / understated) — derived from the moodboard emotional direction
- **Transition style:** (fade / slide / spring physics / instant) — with reasoning
- **Micro-interaction approach:** (minimal / expressive / functional-only)
- **What motion must NOT feel like:** Explicitly state animation styles that break the brand feel

#### Layout Personality
- **Density:** (airy / information-dense / balanced) — matched to user's context of use
- **Grid approach:** (strict 12-col / editorial free-flow / bento / asymmetric) — with rationale
- **Hierarchy method:** (size contrast / color contrast / weight contrast / spatial contrast) — which is primary?
- **White space philosophy:** How does this brand use empty space? (breathing room / tight efficiency / editorial drama)

#### Distinctiveness Test (MANDATORY — must pass before proceeding)

Write a paragraph that answers all three:

*"This brand is visually distinctive because [specific quality that no other Symphony product has]. You'd recognize it without the logo because [specific graphic signature]. It cannot be mistaken for a generic AI brand because [what makes it feel human and specific]. It is different from [closest Symphony neighbor] because [concrete visual difference]."*

**If you cannot write this paragraph with specific, concrete answers — the graphics style is not differentiated enough. Go back and make bolder choices.**

**Save to:** `[product]/design/graphics-style.md`

---

### Step 1e: Brand Identity (if needed)

**Only run if brand check determined no existing brand. Runs after trend research, AI audit, moodboard, and graphics style are complete.**

**Use the moodboard and graphics style as inputs.** The brand-identity skill should reference these — not generate direction independently.

**Call the `brand-identity` skill:**
```
Read skills/brand-identity/SKILL.md and execute the full workflow.

Inputs:
- Product name: [from product.yaml]
- Industry: [from PRD]
- Target audience: [from PRD]
- Brand personality: [from moodboard.md — emotional direction adjectives]
- Approved color direction: [from moodboard.md — chosen color mood]
- Approved type direction: [from moodboard.md — chosen typographic mood]
- Graphics style constraints: [from graphics-style.md — key rules]
- Anti-patterns to avoid: [from ai-anti-patterns.md]
- 2026 trend context: [key findings from trend-research.md]
```

**The brand-identity skill generates:**
1. **Logo** — Icon + wordmark (calls `nano-banana-pro`). Must avoid all AI-brand anti-patterns.
2. **Typography system** — Fonts, sizes, hierarchy. Must match approved type direction.
3. **Color palette** — Primary, secondary, accent, neutrals. Must match approved color direction.
4. **Voice guidelines** — Tone, writing patterns
5. **Social media templates** — IG, LinkedIn, Twitter templates (calls `social-media-templates` skill)

**Output structure:**
```
[product]/brand-guidelines/
├── BRAND-GUIDELINES.md      # Master document
├── colors.md
├── typography.md
├── voice.md
├── logos/
│   ├── logo-primary.png
│   └── logo-icon.png
└── social-templates/
    ├── instagram-post-*.png
    ├── linkedin-post-*.png
    └── twitter-post-*.png
```

**Also reference from earlier steps:**
```
[product]/design/
├── trend-research.md        # ← Step 1a output
├── ai-anti-patterns.md      # ← Step 1b output
├── moodboard.md             # ← Step 1c output
├── moodboard.html           # ← Step 1c output
└── graphics-style.md        # ← Step 1d output
```

---

### 🔄 Human Review: Full Brand Package

**All of the following are presented together for a single approval pass:**

1. **Trend Research Summary** — Key 2026 directions relevant to this product
2. **AI Anti-Patterns List** — What we're explicitly avoiding and why
3. **Moodboard** — Emotional direction, color moods, type moods, visual references
4. **Graphics Style** — Illustration, photography, texture, motion, layout rules
5. **Logo** — Primary + icon variants
6. **Color Palette** — Swatches with hex codes and usage rules
7. **Typography** — Specimen showing font pairings + scale
8. **Voice Guidelines** — Tone descriptors + writing examples

**Present as a single structured brief.** Human approves or requests changes per section.

**Update workflow.json:**
```json
{
  "state": "brand_identity_review",
  "brandIdentity": {
    "status": "pending_review",
    "sections": {
      "trendResearch": "[product]/design/trend-research.md",
      "aiAntiPatterns": "[product]/design/ai-anti-patterns.md",
      "moodboard": "[product]/design/moodboard.md",
      "moodboardHtml": "[product]/design/moodboard.html",
      "graphicsStyle": "[product]/design/graphics-style.md",
      "brandGuidelines": "[product]/brand-guidelines/BRAND-GUIDELINES.md"
    }
  }
}
```

**After approval → `brand_identity_approved` → Step 2.**

---

### Step 2: Initialize Screen Design

```bash
# Load workflow state
PRODUCT="product-name"
PROJECT_DIR="/home/aria/products/$PRODUCT"
WORKFLOW="$PROJECT_DIR/agency/artifacts/design/workflow.json"

# Check current state
cat $WORKFLOW | jq '.state'
```

**Load required context:**
```
[product]/brand-guidelines/               # Brand system (if just created)
[product]/design/design.yaml              # Or existing design tokens
[product]/agency/prd.md                   # User stories → screens
[product]/agency/artifacts/discovery/competitors.md  # Visual references
[product]/discovery/                      # Check for UI screenshots/mockups
agency/Learnings/designer-learnings.md    # Past learnings
People/[reviewer].md                      # Design preferences
```

⚠️ **IMPORTANT: Check PRD and discovery folder for client-provided UI screenshots or mockups.** If present, these MUST be used as primary design references — they take priority over AI-generated designs. Extract layout patterns, color cues, component choices, and overall style from any provided screenshots.

---

### Step 3: Extract Screens from PRD

Parse PRD user stories to identify required screens:

```markdown
## Screens Inventory (from PRD)

| Screen ID | Name | User Story | Priority |
|-----------|------|------------|----------|
| S001 | Landing Page | As a visitor, I want to see what the product does | P0 |
| S002 | Sign Up | As a visitor, I want to create an account | P0 |
| S003 | Dashboard | As a user, I want to see my main workspace | P0 |
| S004 | [Feature 1] | As a user, I want to... | P0 |
| S005 | [Feature 2] | As a user, I want to... | P1 |
| S006 | Settings | As a user, I want to manage my preferences | P1 |
```

**Save to:** `[product]/agency/artifacts/design/screens.md`

---

### Step 4: Generate Sample Screens (3)

After branding approved, generate 3 key screens using Nano Banana Pro.

**Select 3 most important screens:**
1. Landing/Home (first impression)
2. Main Feature (core value)
3. Dashboard/Settings (daily use)

**Before generating any screen, load these files:**
```bash
cat [product]/design/ai-anti-patterns.md     # Hard constraints — NEVER violate
cat [product]/design/graphics-style.md       # Visual rules to follow
cat [product]/design/moodboard.md            # Emotional tone reference
cat [product]/brand-guidelines/BRAND-GUIDELINES.md  # Colors, fonts
```

**Generate each screen:**

```bash
# Base directory for Nano Banana Pro
NANO_DIR="/home/aria/.nvm/versions/node/v24.13.0/lib/node_modules/openclaw/skills/nano-banana-pro"

uv run $NANO_DIR/scripts/generate_image.py \
  --prompt "[Full prompt — use the template below]" \
  --filename "[product]-[screen-name].png" \
  --resolution 2K
```

**Prompt template for consistent screens:**

⚠️ Every prompt MUST include the Brand Constraints block. This is what prevents screens from looking generic or AI-generated.

```
UI design mockup for [Product Name] — [one-line product description].

Screen: [Screen Name]
Purpose: [What this screen does and what the user achieves]

Layout:
- [Header: specific description]
- [Main content: specific description]
- [Sidebar if any: specific description]
- [Footer/actions: specific description]

Key UI elements:
- [Element 1 — be specific about style, not just type]
- [Element 2]
- [Element 3]

Brand Design System:
- Primary color: [hex from approved palette]
- Secondary color: [hex]
- Accent color: [hex]
- Background: [hex — light or dark theme]
- Heading font: [approved font name]
- Body font: [approved font name]
- Corner radius: [Xpx — from brand guidelines]
- Shadow style: [from graphics-style.md]
- Icon style: [from graphics-style.md — e.g. "Lucide, 1.5px stroke, 20px"]

Graphics Style Rules (from approved graphics-style.md):
- Illustration: [specific rule — e.g. "no illustration, photography only"]
- Layout personality: [specific rule — e.g. "airy, asymmetric, large whitespace between sections"]
- Texture/surface: [specific rule — e.g. "no glassmorphism, solid cards with soft shadow"]
- Motion feel: [specific rule — e.g. "understated, no bounce animations"]

HARD CONSTRAINTS — DO NOT include any of the following (AI anti-patterns):
- [Top 3-5 items from ai-anti-patterns.md — e.g. "No gradient blue-to-purple backgrounds"]
- [e.g. "No floating 3D blob shapes"]
- [e.g. "No neon glows on dark backgrounds"]
- [e.g. "No stock photo people smiling at laptops"]
- [Product-specific anti-patterns from ai-anti-patterns.md]

Emotional tone: [From moodboard — e.g. "warmly no-nonsense, like a trusted accountant who's also your friend"]

Make it look like a real production-quality UI by a senior designer at a world-class product studio.
NOT a generic SaaS template. NOT a Figma community freebie. Specific, owned, and unmistakably [Product Name].
```

**Save generated images:**
```
[product]/agency/artifacts/design/screens/
├── sample-01-landing.png
├── sample-02-dashboard.png
└── sample-03-feature.png
```

**Update workflow.json and present for review.**

---

### Step 5: Generate All Remaining Screens

After sample screens approved:

```bash
# Loop through all screens from inventory
for screen in screens_list:
    generate_screen(screen)
    save_to_artifacts()
    update_workflow()
```

**Maintain consistency by:**
1. Using the same prompt template with the Brand Design System + Graphics Style Rules + HARD CONSTRAINTS blocks
2. Referencing the same approved files: `ai-anti-patterns.md`, `graphics-style.md`, `moodboard.md`
3. Including "Style consistent with approved [product name] design system — same fonts, colors, layout personality, and surface treatment as sample screens"
4. Noting the specific sample screen it's most similar to and ensuring visual continuity

**Save all to:**
```
[product]/agency/artifacts/design/screens/
├── S001-landing.png
├── S002-signup.png
├── S003-dashboard.png
├── S004-feature-1.png
├── S005-feature-2.png
└── S006-settings.png
```

---

### Step 6: Create Figma File

**Requirements for Figma API:**

1. **Figma Access Token** — Personal or OAuth token
2. **Team/Project ID** — Where to create the file

**API Endpoint:**
```
POST https://api.figma.com/v1/files
```

**What we can do:**
- Create new file in a project
- Add pages (one per screen)
- Import images as frames
- Set frame names and descriptions

**Alternative: Figma Plugin**
- Build a Figma plugin that imports from JSON
- Plugin reads our screens.md + images
- Creates organized Figma file

**For now (manual upload):**
1. Export all screen PNGs
2. Create Figma file manually
3. Import images as frames
4. Add link to workflow.json

**Future automation (needs setup):**
```bash
# Requires: FIGMA_ACCESS_TOKEN, FIGMA_PROJECT_ID
node scripts/create-figma-file.js \
  --project "$PRODUCT" \
  --screens-dir "$PROJECT_DIR/agency/artifacts/design/screens/" \
  --output-url workflow.json
```

---

### Step 7: Generate Design System Prompt

⭐ **CRITICAL STEP — Do this BEFORE final sign-off or when design is approved.**

Auto-generate `design/design-system-prompt.md` by distilling all discovery + design artifacts into a single coding-agent-ready document. Follow the template at `agency/templates/design-system-prompt.md`.

**Read these source files:**
1. `discovery/brief.md` → Extract audience, tone, positioning
2. `discovery/competitors.md` → Extract anti-patterns (what competitors do poorly)
3. `discovery/target-market.md` → Extract user demographics, devices, behavior
4. `design/brand-guidelines.md` → Extract visual identity, style rationale
5. `design/design.yaml` → Extract exact color hex codes, font names
6. `design/screens.md` → Extract layout patterns per screen
7. `design/screens/*.png` → List paths as reference screenshots

**The output file must include:**
- Brand Personality (audience, tone, positioning, key emotion)
- Visual Identity (exact hex colors with rationale, typography with specs)
- Component Rules (icons=Lucide only, button variants, card styles, form patterns, animations)
- Layout Patterns (max-width, spacing, responsive breakpoints, per-screen notes)
- Anti-Patterns (from competitors + universal rules like no emoji icons, no mock data)
- Reference Screens table (path + layout notes for each approved screen)

**Save to:** `[product]/design/design-system-prompt.md`

This is the **single source of truth** the coding agent uses for all design decisions during Build phase. It replaces the need to read 6+ files and piece together design intent.

---

### Step 8: Final Sign-Off

**Human marks design as complete:**

```json
{
  "state": "completed",
  "milestones": [
    { "id": "design_complete", "status": "done", "approved_by": "Jarrhey", "approved_at": "2026-02-02T15:00:00Z" }
  ]
}
```

**Update product brain.md:**
```markdown
phase: Build
design_completed_at: 2026-02-02
design_approved_by: Jarrhey
figma_url: https://figma.com/file/xxx
```

---

## Output Files Summary

| File | Purpose | Location |
|------|---------|----------|
| workflow.json | State tracking | artifacts/design/workflow.json |
| trend-research.md | 2026 design trends for this product/category | design/trend-research.md |
| ai-anti-patterns.md | What makes a brand look AI-generated — hard constraints | design/ai-anti-patterns.md |
| moodboard.md | Emotional direction, color/type moods, visual references | design/moodboard.md |
| moodboard.html | Visual HTML moodboard | design/moodboard.html |
| graphics-style.md | Illustration, photography, texture, motion, layout rules | design/graphics-style.md |
| brand-guidelines.md | Colors, typography, style | artifacts/design/brand-guidelines.md |
| design-system-prompt.md | ⭐ Distilled design system for coding agent | design/design-system-prompt.md |
| screen-coverage.md | PRD validation (maps stories to screens) | design/screen-coverage.md |
| screens.md | Screen inventory + status | artifacts/design/screens.md |
| marketing-pegs.md | Visual inspiration | artifacts/design/marketing-pegs.md |
| screenshots.md | Screenshot planning | artifacts/design/screenshots.md |
| screens/*.png | Generated UI images | artifacts/design/screens/*.png |

---

## Build Phase Handoff

When Design is complete, Build phase receives:

1. **Design System Prompt** — ⭐ `design/design-system-prompt.md` (PRIMARY — single source of truth)
2. **Graphics Style** — `design/graphics-style.md` (illustration, photography, motion, layout rules)
3. **AI Anti-Patterns** — `design/ai-anti-patterns.md` (hard constraints for coding agent)
4. **Screen Coverage Report** — `design/screen-coverage.md` (validates all P0 stories have screens)
5. **Figma Link** — `workflow.json → figma.file_url`
6. **PRD + User Stories** — `prd.md`
7. **Screen Screenshots** — `artifacts/design/screens/*.png`
8. **Brand Guidelines** — `artifacts/design/brand-guidelines.md` (raw reference)

**Pre-flight check for Build:** If `design-system-prompt.md`, `graphics-style.md`, or `screen-coverage.md` don't exist, Design is incomplete.

**Note:** The design-system-prompt.md should incorporate key points from graphics-style.md and ai-anti-patterns.md so the coding agent has everything in one file.

---

## Commands Reference

### Check current state
```bash
cat $PROJECT_DIR/agency/artifacts/design/workflow.json | jq '.state'
```

### Generate single screen
```bash
uv run $NANO_DIR/scripts/generate_image.py \
  --prompt "[prompt]" \
  --filename "$PROJECT_DIR/agency/artifacts/design/screens/[name].png" \
  --resolution 2K
```

### Update workflow state
```bash
# Use jq to update state
jq '.state = "new_state"' workflow.json > tmp.json && mv tmp.json workflow.json
```

---

## Figma API Setup (Future)

To enable automatic Figma file creation:

1. **Get Figma Access Token:**
   - Figma → Settings → Personal Access Tokens
   - Create token with file write permissions

2. **Configure in OpenClaw:**
   ```json
   {
     "skills": {
       "design-agent": {
         "figmaToken": "figd_xxx",
         "figmaProjectId": "xxx"
       }
     }
   }
   ```

3. **Install Figma API client:**
   ```bash
   npm install figma-api
   ```

4. **Use script to create file:**
   ```javascript
   // scripts/create-figma-file.js
   const Figma = require('figma-api');
   // ... implementation
   ```

---

## Human Checkpoints

| Checkpoint | What's Reviewed | Outcomes |
|------------|-----------------|----------|
| Full Brand Package | Trend research summary · AI anti-patterns · Moodboard · Graphics style · Logo · Colors · Typography · Voice | Approve / Request Changes per section |
| Sample Screens | 3 key screens | Approve / Request Changes |
| All Screens | Complete screen set | Approve / Request Changes |
| Final Sign-Off | Figma file ready | Mark Done → Build Phase |

**Never auto-advance. Always await human approval.**

### What the Brand Package review looks like

Present the full package as a structured brief in chat. Example format:

```
## [Product Name] Brand Package — Ready for Review

### 📊 2026 Trend Inputs
[3–5 bullet summary of relevant trends]

### 🚫 AI-Brand Anti-Patterns We're Avoiding
[Top 5 callouts with brief reason each]

### 🎨 Moodboard
**Emotional direction:** [adjectives]
**Color mood:** [chosen direction + why]
**Type mood:** [chosen direction + why]
**Visual references:** [list with links]
[Link to moodboard.html for full visual version]

### ✏️ Graphics Style
**Illustration:** [rule]
**Photography:** [rule]
**Texture/surface:** [rule]
**Motion:** [rule]
**Layout personality:** [rule]
**Distinctiveness statement:** [the paragraph]

### 🔵 Logo
[Attach logo-primary.png and logo-icon.png]

### 🎨 Color Palette
[Swatches — primary, secondary, accent, neutrals with hex codes]

### 📝 Typography
[Specimen — headline font, body font, scale]

### 🗣️ Voice
[Tone adjectives + 2–3 writing examples]

---
Reply with feedback per section or ✅ to approve all.
```
