# Visual Research Methodology

**Owner:** Jessica (Art Direction)  
**Purpose:** Transform brand strategy into actionable visual directions with curated reference boards.

---

## The Process

### Phase 1: Extract Positioning DNA

Before any visual search, extract the brand's positioning intelligence:

```
From brand strategy, identify:
1. positioning_strategy — HOW they differentiate (e.g., accessibility-democratization, rebellion-challenger)
2. market_contrast — WHO they're positioned against (e.g., vs-pacification-paradigm)
3. positioned_against — Specific competitors by name
4. affinity_keywords — Searchable terms (e.g., capable, confident, elevated)
5. The Test Question — One question to filter every reference (e.g., "Does this treat the child as CAPABLE or FRAGILE?")
```

**The Test Question — Rules:**
- Must be a single, specific yes/no question
- Specific enough that two different people would answer it the same way about the same image
- References the brand's core tension (what they're FOR vs. what they're AGAINST)

**❌ Bad Test Questions (too vague — never use these):**
- "Does this feel modern?" (modern vs. what?)
- "Does this look premium?" (no contrast defined)
- "Does this resonate with millennials?" (not measurable)
- "Does this feel right for the brand?" (circular)

**✅ Good Test Questions:**
- "Does this treat the child as CAPABLE or FRAGILE?" (capability-first brand)
- "Does this earn trust through proof, or signal eco-virtue without it?" (purpose-proof CPG)
- "Does this feel like a bank our parents use, or a tool we'd choose?" (fintech challenger)

**Output:** Positioning brief (1 page max)

---

### Phase 2: Define Visual Search Vectors

Translate positioning into visual search vectors:

| Positioning Element | Visual Search Vector |
|---------------------|---------------------|
| Strategy: rebellion-challenger | Bold typography, hand-drawn, irreverent brands |
| Strategy: quality-elevation | Premium materials, craft, elevated aesthetics |
| Strategy: accessibility-democratization | Clean UI, approachable, not intimidating |
| Contrast: vs-legacy-incumbents | Challenger brands in same/adjacent categories |
| Contrast: vs-mass-market-generic | Premium alternatives to commodity products |

**For each vector, identify 5-10 brands to capture.**

---

### Phase 3: Capture References

Use the visual research tools:

```bash
# Screenshot brands — PREFERRED: Use Pinchtab (free, unlimited, handles JS-rendered sites)
# Start server if not running: nohup pinchtab --headless > /tmp/pinchtab.log 2>&1 &
pinchtab nav "https://example.com"
sleep 3
pinchtab ss -o output.png           # screenshot
pinchtab text > output.txt          # readable text (800 tokens vs 10K for screenshots)

# For bulk scraping / sites that block bots: Scrapling (774x faster than BeautifulSoup, Cloudflare bypass)
python3 scripts/scrape.py "https://example.com" --stealth        # text with anti-bot bypass
python3 scripts/scrape.py "https://example.com" --links          # all links
python3 scripts/scrape.py "https://example.com" --css "h1,h2,p"  # specific elements

# Alternative: ScreenshotOne API (has rate limits)
ACCESS_KEY=$(cat /home/clawd/secrets/screenshotone/access_key)
curl -sL "https://api.screenshotone.com/take?access_key=${ACCESS_KEY}&url=https://example.com&viewport_width=1200&viewport_height=900&format=jpg&block_ads=true&block_cookie_banners=true&delay=2" -o output.jpg

# Analyze with taxonomy
python3 /home/clawd/workspace/scripts/visual-research/tag_image.py \
  --url "https://curiousendeavor.com/path/to/image.jpg" \
  --name "Brand Name - Description" \
  --save
```

**Capture sources:**
- Brand homepages (ScreenshotOne)
- Behance case studies (direct image URLs)
- Agency portfolios (Collins, Pentagram, Character)
- Notion Inspiration Library (existing curated refs)

---

### Phase 4: Build Direction Boards

Organize references into 2-4 distinct directions. Each direction board must include:

1. **Direction Name** — Evocative, not generic (e.g., "Playful Challenger" not "Option A")
   - **❌ NEVER name directions:** Option A/B/C, Direction 1/2/3, Modern/Classic/Bold/Minimal, or any single adjective
   - **✅ Good names are evocative tensions or archetypes:** "Digital Rebel", "Quiet Earth", "Warm Authority", "Trust Earned", "Activist Object"
   - **Formula:** [Emotion/Stance] + [Object/Role] = evocative name (e.g., "Radical Transparency", "Curious Laboratory")
2. **Visual DNA** — 3-5 key traits with examples
3. **Brand References** — 3-5 REAL named brands that embody this direction
   - Name specific brands, not categories ("Monzo, Revolut, Chime" not "challenger banks")
   - Each brand should be something you could screenshot — real, findable, recognizable
4. **Why It Works** — Connection to brand positioning
5. **The Test** — How to evaluate if a design fits this direction

**Board Template:** `/home/clawd/workspace/public/visual-research/mission-playful-challenger/index.html`

---

## ⚠️ MANDATORY OUTPUT FORMAT: HTML Direction Boards

**You MUST produce an HTML file as the final deliverable.** A text summary or markdown document is NOT acceptable output for visual research. The output is a visual board that will be presented to a client or creative team.

### Create: `[project-slug]/index.html`

Each HTML board must include these sections per direction:

```html
<!-- STRUCTURE for each direction board -->
<section class="direction" id="[direction-slug]">
  <h2 class="direction-name">[Evocative Direction Name]</h2>
  <p class="positioning-link">[Why It Works — 1-2 sentences connecting to brand positioning strategy]</p>
  <div class="visual-dna">
    <!-- 3-5 visual DNA traits listed -->
  </div>
  <div class="brand-references">
    <!-- 3-5 real named brands, each with:
         - Brand name
         - What to capture (homepage, campaign, packaging)
         - Why this brand fits this direction -->
  </div>
  <div class="reference-images">
    <!-- Captured screenshots/images from Phase 3 -->
  </div>
  <p class="the-test">[Test: How to evaluate if a design fits this direction]</p>
</section>
```

### ⚠️ IMAGE SOURCE HIERARCHY — MANDATORY. Follow in order. Never skip to a lower tier.

**Tier 1 — Agency case study extraction (preferred):**
- Search: `web_search "[Brand] rebrand agency case study"`
- Run: `bash /root/.openclaw/workspace/scripts/images/extract-images.sh <case-study-url> ./assets/[brand]/ 5`
- Handles: Prismic (Porto Rocha), Sanity (Koto, Wolff Olins), Mux video (Collins), Cloudinary, imgix, standard HTML
- Result: production-quality images, zero cookie banners, extracted directly from agency CMS

**Tier 2 — Press kit / Behance:**
- Search: `web_search "[Brand] press kit images"` or `"[Brand] site:behance.net"`
- Download directly from press page or Behance project
- Result: curated, clean, professionally photographed

**Tier 3 — Live site screenshot with cookie blocking:**
- Use Playwright: `playwright screenshot --browser chromium --wait-for-timeout 5000 --block-service-workers "https://brand.com" output.jpg`
- After capture: use JS to remove overlays — `document.querySelectorAll('[id*=cookie],[class*=cookie],[id*=consent]').forEach(e=>e.remove())`
- If cookie banner still visible → crop screenshot to exclude it OR try /about, /products, /collections instead of homepage
- Check screenshot before using — reject any image with cookie banner or modal overlay

**❌ NEVER acceptable:**
- Raw Playwright against a homepage with no cookie-blocking attempt
- Text-only cards (no image)
- Colored placeholder blocks
- Screenshots with visible cookie consent dialogs, overlays, or loading spinners

---

- **Every brand reference card requires a captured image as the primary visual**
- Card structure: image (full-width, 220px, object-fit cover) → brand name → ONE line max rationale
- If all tiers fail, show a placeholder `<img>` with the brand URL in the alt — **never fall back to a colored block**

```html
<!-- CORRECT brand reference card structure -->
<div class="ref-card">
  <img src="assets/brand.jpg" alt="Brand Name — brand.com" style="width:100%;height:220px;object-fit:cover;object-position:top;display:block;">
  <div class="ref-card-body" style="padding:12px 14px;">
    <p style="font-size:14px;font-weight:700;color:#000;margin:0 0 4px;">Brand Name</p>
    <p style="font-size:12px;color:#888;margin:0;">One line of rationale, maximum 12 words.</p>
  </div>
</div>
```

## CE STYLE — NON-NEGOTIABLE

All visual research boards ARE CE deliverables. Follow ce-ui-quality/SKILL.md exactly.

Start every board with this CSS block:

```css
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500&display=swap');

* { margin: 0; padding: 0; box-sizing: border-box; }

:root {
  --red: #cc0000;
  --black: #1a1a1a;
  --grey: #666;
  --light: #999;
  --border: #eee;
  --bg: #fff;
  --size-display: 48px;
  --size-h1: 28px;
  --size-h2: 20px;
  --size-body: 14px;
  --size-small: 12px;
  --size-label: 10px;
  --size-data: 40px;
}

html { font-size: 16px; }
body {
  font-family: 'Inter', -apple-system, sans-serif;
  background: var(--bg);
  color: var(--black);
  line-height: 1.6;
  -webkit-font-smoothing: antialiased;
}

.container { max-width: 1100px; margin: 0 auto; padding: 0 40px; }
```

And this in `<head>`:
```html
<link rel="stylesheet" href="https://use.typekit.net/ffj8sbd.css">
```

Rules:
- Fonts: Larken (Typekit ffj8sbd) for headings, Inter for body — NOTHING ELSE
- Colors: only the 6 CE tokens. Do NOT use custom direction colors (navy, terracotta, gold, etc.)
- Direction sections are differentiated by red label + number, NOT by background colors
- Font weight: 400 and 500 ONLY — no bold
- No box-shadow, no gradients, no border-radius > 4px
- Container max-width: 1100px

---

### HTML Output Rules
1. **One HTML file per project** — all directions in a single `index.html`
2. **Images must be captured first** — run Playwright/Pinchtab screenshots before writing card HTML
3. **Board header includes positioning brief** — show Test Question prominently at the top
4. **No plain-text dumps** — if you haven't captured images yet, use placeholder `<img>` tags with brand+URL as alt text

### Example output path
`/root/.openclaw/workspace/public/visual-research/[brand-slug]/index.html`

---

### Phase 5: Illustration-Specific (If Applicable)

If brand requires illustration, add these layers:

| Element | Questions to Answer |
|---------|---------------------|
| **Character Style** | Eyes (dot? detailed?), Posture (active? passive?), Proportion |
| **Line Quality** | Bold? Loose? Geometric? Hand-drawn? |
| **Color Approach** | Palette size, Temperature, Unexpected combos? |
| **Scene Building** | How are environments illustrated? Detail level? |
| **Energy** | Playful? Serious? Confident? Approachable? |

**For each, show 2-4 reference images with annotations.**

---

## Taxonomy Reference

Use `/home/clawd/workspace/scripts/visual-research/taxonomy.json` for:

**Visual Layer:**
- element_type, style, mood, color_family, subject, content, context, action, craft

**Context Layer:**
- industry, audience_type, market_position, brief_fit, cultural_context

**Positioning Layer:**
- positioning_strategy, market_contrast, positioned_against, positioning_narrative, affinity_keywords

---

## Fishing Queries

To find references in library by positioning:

```bash
# Search by positioning strategy
curl -s -X POST "https://api.notion.com/v1/databases/2ff330c2-8646-81f0-bbd9-ec474393d7a5/query" \
  -H "Authorization: Bearer $NOTION_KEY" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "filter": {
      "or": [
        {"property": "Tags", "multi_select": {"contains": "quality-elevation"}},
        {"property": "Tags", "multi_select": {"contains": "rebellion-challenger"}}
      ]
    }
  }'
```

---

### Phase 6: Critique Before Delivery

Before presenting any visual research board, the agent MUST run three critique passes:

**Pass 1 — CE Quality Gate (automated):**
Run the grep validation script from ce-ui-quality/SKILL.md against the HTML file.
Zero tolerance: any banned pattern = fix before delivery. No exceptions.

Commands:
```bash
grep -i "gradient" index.html
grep "box-shadow" index.html
grep "font-weight.*[6-9]00" index.html
grep "#e5e5e5" index.html
grep -i "playfair\|roboto\|helvetica\|georgia\|system-ui" index.html
```

All must return 0 results. Fix any violations.

**Pass 2 — Positioning Critique (judgment):**
For each direction, answer these questions. If any answer is NO, revise the direction before delivery:

1. Does the direction name express a genuine tension or archetype? (Not a single adjective)
2. Are the brand references REAL, findable brands — not categories?
3. Does "Why It Works" cite the specific positioning strategy extracted in Phase 1?
4. Does the Test statement for this direction differ from the global Test Question?
5. Would two different people look at the brand reference images and agree they belong together?

**Pass 3 — Image Quality (visual check):**
For each brand reference image:
1. Is the brand's actual visual identity visible? (Not a cookie banner, loading spinner, or 404)
2. Is the image landscape-oriented or does it crop well at 220px height?
3. If any image fails → re-capture using the Image Source Hierarchy before delivery

DO NOT deliver the board until all 3 passes are clean.

---

## Quality Checklist

Before presenting visual research:

- [ ] Positioning DNA extracted from brand strategy?
- [ ] Test Question defined?
- [ ] 2-4 distinct directions (not variations of same thing)?
- [ ] Each direction has 3-5 brand references?
- [ ] References analyzed with full taxonomy (visual + context + positioning)?
- [ ] Board is visual (images dominate, not text)?
- [ ] "Why it works" connects to brand positioning?
- [ ] If illustrated: character/line/color/scene questions answered?
- [ ] All brand reference images sourced from Tier 1 or Tier 2? (No raw Playwright screenshots with cookie banners)
- [ ] CE quality gate grep ran — 0 violations?
- [ ] Phase 6 critique passes 1, 2, and 3 all clean?
- [ ] No font outside Larken/Inter/JetBrains Mono?
- [ ] No custom direction colors (navy, terracotta, gold, etc.)?

---

## File Locations

- **Taxonomy:** `/home/clawd/workspace/scripts/visual-research/taxonomy.json`
- **Analysis Script:** `/home/clawd/workspace/scripts/visual-research/tag_image.py`
- **Board Template:** `/home/clawd/workspace/public/visual-research/mission-playful-challenger/index.html`
- **Illustration Template:** `/home/clawd/workspace/public/visual-research/mission-illustration-styles/index.html`
- **Inspiration Library:** Notion DB `2ff330c2-8646-81f0-bbd9-ec474393d7a5`
- **ScreenshotOne Key:** `/home/clawd/secrets/screenshotone/access_key`

---

## Example: Mission

**Positioning DNA:**
- Strategy: accessibility-democratization, rebellion-challenger
- Contrast: vs-pacification-paradigm
- Against: Activity cards, screen pacifiers, "keep kids busy" products
- Keywords: agency, capable, confident, participation
- Test: "Does this treat the child as CAPABLE or FRAGILE?"

**Directions Built:**
1. Playful Challenger (Oatly, Liquid Death, Tony's)
2. Illustration Styles (character, scene, brand systems)

**Boards:** 
- https://curiousendeavor.com/visual-research/mission-playful-challenger/
- https://curiousendeavor.com/visual-research/mission-illustration-styles/