cryptopafi /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)
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)
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)
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.jsoncontains ≥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.jsonvia 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.jsonis direct input format for/gpt-image-banner- Logo URLs feed
/banner-critiquefor brand compliance checks - Compatible with
/marketing-agencyfor 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.