danpeg/visual-research/visual-research

Visual Research

Full-pipeline skill for researching a brand's visual identity, capturing imagery from every available source, and packaging it into a branded HTML report with a 13-section competitive analysis.

Setup

Before starting, check available tools and build a capabilities report.

Required:

• curl — Instagram API calls, direct image downloads. Pre-installed on macOS/Linux.

Recommended (API keys):

Check: echo $GEMINI_API_KEY

Optional (CLI tools):

Check each: which playwright, which yt-dlp, python3 -c "import scrapling" 2>/dev/null && echo ok

Setup behavior:

1. Check each prerequisite and report what's available
2. For missing items, explain what the user loses and how to install
3. If anything is missing, STOP and wait for the user to confirm before proceeding. Present a clear summary like:

``` Ready: Playwright, yt-dlp, curl Missing: GEMINI_API_KEY (vision analysis will use Claude instead) Scrapling (will use web_fetch fallback)

Install now, or proceed with what's available? ```

Do NOT continue to Phase 1 until the user explicitly says to proceed.

If everything is available, report the green status and proceed directly to Phase 1 — no confirmation needed.

1. Record the capabilities in the output document's Setup section

Source Selection

After Setup confirms tool availability, present the user with source choices before starting the pipeline. Use AskUserQuestion with multiSelect: true to let the user pick which sources to research.

Always included (not selectable): Website homepage + hero image pipeline (~20K tokens). This is the core of any brand research.

Present these 3 questions in a single AskUserQuestion call:

Question 1 — Social sources (header: "Social", multiSelect: true):

Question 2 — Design/industry sources (header: "Design", multiSelect: true):

Question 3 — Other sources (header: "Other", multiSelect: true):

After the user responds, record the selected sources as the Source Plan. Before starting Phase 1, print the Source Plan and total estimated token cost:

Source Plan:
  ✓ Website homepage (always included)  ~20K tokens
  ✓ Instagram                           ~30K tokens
  ✓ Agency case studies                 ~25K tokens
  ✓ Press / media kit                   ~12K tokens
  ✗ TikTok (skipped)
  ✗ YouTube (skipped)
  ...
  ─────────────────────────────────
  Estimated total: ~87K tokens

Token estimates are approximate — actual usage varies by brand (a Fortune 500 with extensive press coverage will use more tokens than a small startup). Estimates are based on: web searches ~2-3K tokens each, web fetches ~5-20K, image vision analysis ~2-5K per image.

Input

Accept a brand config inline or as JSON:

{
  "brand": "Brand Name",
  "website": "https://example.com",
  "social": {
    "instagram": "handle",
    "tiktok": "handle",
    "youtube": "handle",
    "x": "handle"
  },
  "known_agencies": [],
  "known_campaigns": []
}

If the user provides just a brand name, discover the rest during Phase 1.

Pipeline

DISCOVER → CAPTURE → EXTRACT → ANALYZE → PACKAGE

Phase 1 — Discover

Source gating: Only run searches for sources included in the Source Plan. Skip discovery for deselected sources (e.g., don't search for agency case studies if "Agency case studies" was not selected).

Find agency relationships, campaigns, and source URLs.

Read references/source-discovery-guide.md for detailed search strategies.

Core searches:

web_search "[Brand] rebrand agency case study"
web_search "[Brand] brand identity agency"
web_search "[Brand] campaign [Year] case study"
web_search "[Brand] [Agency] behance"
web_search "site:underconsideration.com/brandnew [Brand]"
web_search "site:awwwards.com [Brand]"

Check the brand's press room (/press, /newsroom, /media). Verify social handles exist and are public.

Output: List of source URLs for capture, confirmed social handles, agency identification.

Phase 2 — Capture

Source gating: Only capture sources included in the Source Plan. Always capture the website homepage. Skip social platform screenshots for deselected platforms.

Screenshot key brand touchpoints. Output to captures/ directory.

If Playwright is available:

playwright screenshot --full-page "https://[brand-website]" captures/website-homepage.png
playwright screenshot "https://www.instagram.com/[handle]/" captures/instagram-grid.png
playwright screenshot "https://www.tiktok.com/@[handle]" captures/tiktok-grid.png
playwright screenshot "https://www.youtube.com/@[handle]" captures/youtube-channel.png

Also capture: app store pages, campaign pages, and agency case study pages found in Phase 1.

Cookie consent / overlay dismissal: Third-party pages (agency portfolios, press sites, campaign microsites) almost always show cookie consent banners that will contaminate screenshots. Before capturing any third-party page, dismiss overlays:

// In Playwright script, after page.goto() and before screenshot:
// 1. Try clicking common consent buttons
for (const selector of [
  'button:has-text("Accept")', 'button:has-text("Reject All")',
  'button:has-text("Accept All")', 'button:has-text("Got it")',
  'button:has-text("OK")', 'button:has-text("I agree")',
  '[id*="cookie"] button', '[class*="consent"] button',
  '[id*="onetrust"] button#onetrust-accept-btn-handler'
]) {
  const btn = page.locator(selector).first();
  if (await btn.isVisible({ timeout: 1000 }).catch(() => false)) {
    await btn.click();
    await page.waitForTimeout(500);
    break;
  }
}
// 2. Nuclear fallback — remove overlay elements via JS
await page.evaluate(() => {
  document.querySelectorAll('[id*="cookie"],[id*="consent"],[class*="cookie"],[class*="consent"],[id*="onetrust"],[class*="gdpr"]')
    .forEach(el => el.remove());
});

When using playwright screenshot CLI (not scripted), add a wait and use --timeout to allow the page to settle, but note the CLI cannot dismiss banners. For pages known to have consent modals, prefer scripted Playwright over the CLI command.

Without Playwright: Use web_fetch to grab page content as text. Note visual capture was skipped.

Phase 3 — Extract

Source gating: Only extract images from sources included in the Source Plan. Always extract the hero image and logo. Skip deselected sources (e.g., skip Instagram API if Instagram was not selected, skip App Store if not selected).

Pull actual images from APIs and CDNs.

Read references/image-extraction-techniques.md for detailed recipes.

Core extractions:

Hero Image Sourcing (Priority — Slot 0)

The hero image is the most important visual in the report. It must be:

• High resolution (minimum 1200px wide, ideally 1600px+)
• Brand-representative — shows the brand's actual visual identity, not just something with the logo on it
• Professionally produced — press photos, campaign key art, homepage heroes. Not phone photos, not user-generated content
• Compositionally suitable — works at 16:9 aspect ratio with a gradient overlay on the left 40% (text will sit there)

Search in this priority order, collecting candidates into `hero-candidates/`:

1. Homepage hero image

• Use Playwright to screenshot the above-the-fold hero section
• Also extract the actual image URL from the page source (look for hero/banner container <img> tags, CSS background-image, <video poster>)
• Apply resolution maximizer (see below) to get the full-size asset
• Check if the CMS (DatoCMS, Contentful, Prismic, Sanity) exposes the raw asset URL without resize params

1. Press/media kit hero imagery

• Check /press, /newsroom, /media, /brand pages for downloadable high-res imagery
• Look for "brand assets" or "media kit" download links
• Press photos from product launches or conferences are often the highest quality

1. Agency case study hero

• Behance/Dribbble case studies typically lead with a hero image that the agency art-directed
• These are purpose-built to showcase the brand's visual identity at its best
• Apply resolution maximizer to Prismic/Sanity/CMS URLs

1. Brand New (Under Consideration) hero

• Rebrand articles often lead with a high-quality hero image showing the new identity (800–2000px)
• Best for brands that have undergone a major visual refresh
• Before/after comparison images are also strong hero candidates

1. Campaign key art

• Search: web_search "[Brand] campaign key art [Year]"
• Search: web_search "[Brand] brand campaign hero image"
• Trade press (It's Nice That, Creative Review, The Drum) often publishes agency-supplied high-res campaign imagery
• Conference/event photography from the brand's own events

1. Awwwards project screenshots

• Website showcases include 1600×1200 project screenshots
• Good when the brand's digital presence is its strongest visual expression
• Newer projects (2022+) are best quality

1. Product marketing screenshots

• Product pages often have polished, art-directed hero shots
• App Store screenshots via iTunes Search API (1242×2208 iPhone) — no auth needed
• Marketing landing pages for specific features/products

1. Social media — last resort only

• Only if nothing above yields a usable image
• Prefer official brand posts over user photos
• Instagram carousel first slides are usually highest production value
• Avoid: phone photos, UGC, nighttime shots, grainy/compressed images

Selection criteria — choose the best candidate: