# Brand Harvest

> Harvest ALL design elements from a target website at maximum fidelity for banner/ad production. Extracts logos (SVG/PNG variants), color palette (hex + CSS vars + gradients), typography (font families, weights, @font-face URLs), spacing tokens, button/CTA styles, hero imagery, multi-breakpoint screenshots. Outputs brand-kit.json (W3C Design Tokens spec) + asset directory ready for gpt-image-banner. Use when starting custom banner production for a new brand/site (Casino Rewards, SMSads creative work). Trigger signals: 'harvest [site]', 'extract brand from [url]', 'brand kit [domain]', 'get design tokens from [site]', 'scrape [site] for banner production'. ANTI-PATTERN: Not for code audit, SEO, content scraping, or competitive intel — use apify-competitor-intelligence or apify-market-research instead.

- Skill: `cryptopafi/brand-harvest` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cryptopafi/brand-harvest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cryptopafi/brand-harvest/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: cryptopafi (https://skillmd.com/u/cryptopafi)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/cryptopafi/brand-harvest

---


# /brand-harvest — Website Design System Extractor

Harvest a target website's complete design system at maximum fidelity for downstream banner/ad production. Output `brand-kit.json` (W3C Design Tokens) + asset directory consumed by `/gpt-image-banner` and `/banner-critique`.

## §1. Identity

**Purpose:** Single-shot brand kit extraction. Replaces manual logo hunt + ad-hoc ZIP downloader + LP screenshot crop. Solves LP-aspect-ratio fidelity loss (e.g. 2.58:1 → square crop drops 60% content).

**Triggers:** `harvest <url>`, `brand kit <domain>`, `extract design tokens from <site>`, `scrape <site> for banner production`.

**DO NOT use for:** code audit / SEO analysis / content scraping / competitive intel → those go to `apify-competitor-intelligence` or `apify-market-research`.

## §2. Inputs

| Input | Type | Required | Description |
|---|---|---|---|
| `url` | string | YES | Target URL (e.g., https://luxurycasino.com) |
| `breakpoints` | array | NO | Viewport widths for screenshots. Default: `[375, 768, 1440]` |
| `output_dir` | path | NO | Asset destination. Default: `~/.nexus/projects/brand-harvest/{domain}/` |
| `tools` | array | NO | Tool order override. Default: `["firecrawl", "project-wallace", "playwright"]` |
| `firecrawl_key` | string | COND | Required if `firecrawl` in tools. Source from `$FC_API_KEY` env |

## §3. Outputs

```
{output_dir}/
  brand-kit.json           ← Merged W3C Design Tokens + logo URLs + metadata
  logos/
    logo-primary.{svg,png}
    favicon.{ico,png,svg}
  screenshots/
    desktop-1440.png
    tablet-768.png
    mobile-375.png
  css-tokens.json          ← Project Wallace W3C output
  firecrawl-branding.json  ← Raw Firecrawl /branding response
  raw-html.md              ← Tavily extract fallback
```

## §4. Dependencies

| Dep | Type | Install | Required |
|---|---|---|---|
| `firecrawl-py` | Python pkg | `pip install firecrawl-py` | YES (primary) |
| `@projectwallace/design-tokens-cli` | npm | `npx @projectwallace/design-tokens-cli` | YES (supplement) |
| `playwright` | npm | `npx playwright install chromium` | YES (screenshots) |
| `apify-ultimate-scraper` skill | NexusOS skill | already installed | OPTIONAL (logo bulk) |
| Tavily MCP | MCP | already in stack | FALLBACK |
| `FC_API_KEY` env | API key | free at firecrawl.dev (1K/mo) | YES (Firecrawl) |
| `BRANDFETCH_KEY` env | API key | free at brandfetch.com | OPTIONAL |

## §5. Algorithm

### Stage 1 — Structured Brand Data (Firecrawl Branding v2)
```python
from firecrawl import Firecrawl
import os, json
f = Firecrawl(api_key=os.environ['FC_API_KEY'])
result = f.scrape(url, formats=['branding'])
branding = result.get('branding', {})
# Contains: logo.url, colors[].hex, colors[].type, typography[].family,
#           typography[].weights, spacing, components
```

### Stage 2 — CSS Token Extraction (Project Wallace)
```bash
npx @projectwallace/design-tokens-cli analyze --url "{url}" --output css-tokens.json
```
Post-process: merge `css-tokens.json` colors/fonts into `brand-kit.json`.

### Stage 3 — Multi-Breakpoint Screenshots (Playwright)
```bash
for width in 375 768 1440; do
  npx playwright screenshot --full-page \
    --viewport-size "${width},900" "{url}" "screenshots/${width}.png"
done
```

### Stage 4 — Logo Download & Dedupe
Download all logo URLs from Stage 1. Run `identify` (ImageMagick) to detect SVG vs PNG. SVG present → primary. Fallback: `botflowtech/website-logo-extractor` via Apify.

### Stage 5 — Merge & Emit `brand-kit.json`
W3C Design Token Format spec-compliant JSON + `meta.source`, `meta.url`, `meta.extracted_at`.

## §6. Error Handling

| Error | Action |
|---|---|
| `FC_API_KEY` missing | Fall back to Tavily extract + Project Wallace only; warn user |
| Firecrawl 402 (credits exhausted) | Fall back to OSS path; log warning |
| Project Wallace CLI fail (JS-rendered CSS) | Use Playwright CSS coverage directly |
| Logo URL 403/404 | Try og:image → favicon → Twitter card |
| No logos found | Run `botflowtech/website-logo-extractor` via Apify |
| Aspect ratio mismatch for banner crop | Use `playwright screenshot --clip` with explicit dims |

## §7. Tests

- **Smoke:** `harvest https://www.luxurycasino.com` → `brand-kit.json` contains ≥3 colors + ≥1 font + ≥1 logo
- **Regression:** re-run on `https://apple.com` → compare against reference kit (Apple = known stable surface)
- **Fallback:** unset `FC_API_KEY` → still produces a valid (degraded) `brand-kit.json` via Tavily + Project Wallace

## §8. Example Invocation

```
/brand-harvest https://www.luxurycasino.com
/brand-harvest https://zodiaccasino.com --breakpoints 320,768,1920
/brand-harvest https://casinokingdom.com --output-dir ~/Desktop/ck-kit
```

Expected wall: ~2 min · Expected cost: 2-5 Firecrawl credits (free tier covers ~200-500 sites/mo).

## §9. Integration

- `brand-kit.json` is direct input format for `/gpt-image-banner`
- Logo URLs feed `/banner-critique` for brand compliance checks
- Compatible with `/marketing-agency` for brief enrichment
- **Production pipeline:** `/brand-harvest` → `/gpt-image-banner` → `/banner-critique` = full banner production loop

## §10. Source

Skeleton produced by DELPHI D2 research `nx-20260527-ah27` (EPR 16/20, self_grade 89). See `~/.nexus/workspace/completed/nx-20260527-ah27/` for full research + selection table + gap analysis.