matteotitta Research substrate (Exa)
Default: Exa, per .claude/rules/exa-protocol.md (auto-loaded for research, audit, competitor, ICP, AEO, content sourcing, sales prospecting work).
Primary tools: web_search_exa, web_fetch_exa. Use case: fallback visual-identity reference harvest when screenshots unavailable.
Citation: every Exa-derived claim uses [VERIFIED: exa_search, {url}, accessed {YYYY-MM-DD}] per .claude/rules/ontology.md. Quality gate: ≥3 sources per major claim, ≥50% [VERIFIED] confidence.
Brand Kit
Extract visual identity from screenshots and compile into a DESIGN.md-format brand system file: YAML token frontmatter (machine-authoritative) + 8 ordered prose sections (human rationale). Screenshot-first approach for pixel-perfect fidelity — URL scraping available as supplementary input.
Scope: Visual identity only. Voice, copy, and messaging live in TOV guidelines and client CLAUDE.md — not in the brand kit. Use /brand-context for voice sync.
Authority: This skill produces the canonical input for every downstream visual-production skill. The integration contract (how DESIGN.md flows to shadcn primitives, Figma variables, and non-web tools) is defined in .claude/rules/design-production.md — that file auto-loads when working on visual production. Read it before invoking this skill.
Claude Code triggers
Invoke when:
- "extract brand from [company]"
- "brand kit for [client]"
- "brand guidelines for [URL]"
- "brand identity for [company]"
- "design system extraction"
- "get colors and fonts from [screenshots/URL]"
- "create brand file for [client]"
- "build brand system for [client]"
- "design tokens from [company]"
- "visual identity extraction"
- After completing initial client onboarding when brand assets are available
Do NOT invoke when:
- User wants TOV/voice guidelines → use
/tov-guidelines - User wants messaging/positioning → use
/product-messaging - User wants competitor analysis → use
/competitor-research - User wants the Genesys Growth brand → load
/genesys-branddirectly
Modes
Quick mode (default)
Use when you have screenshots and/or a website URL. Analyze screenshots → extract visual identity → compile into template → mark gaps as [NEEDS VERIFICATION].
Time: ~10 minutes. Quality: Good for drafts, internal use, early engagement.
Full mode
Use when you have brand guidelines PDF, Figma access, or prior work alongside screenshots. Gather all sources → cross-reference for accuracy → populate all 8 sections with verified data → self-review.
Time: ~20 minutes. Quality: Production-ready, client-facing.
Trigger: Use full mode when user says "full brand kit" or provides multiple source types.
Proactive input prompting
When invoked, immediately ask for these inputs before starting:
Before I create the brand kit, I need:
- Client name — which client is this for?
- Screenshots — paste or provide paths to 3-5 screenshots (homepage, about, pricing, feature page)
- Website URL (optional) — I'll use this for supplementary CSS extraction
- Mode — Quick (screenshots only) or Full (with brand PDF/Figma/prior work)?
- Any brand assets? — Figma files, brand PDF, style guide, logo files?
If you give me just a URL, I'll take screenshots via Playwright and run in Quick mode.
Skip prompting if all inputs are already clear from context.
Input requirements
Required
| Input | Description | Source |
|---|---|---|
| Screenshots (primary) | 3-5: homepage, about, pricing, feature page | User pastes images, file paths, or URL for auto-capture |
| Client name | Company name | User specification |
Optional (improve quality significantly)
| Input | How it helps |
|---|---|
| Website URL | Supplementary CSS extraction — exact hex values, font imports, variable names |
| Figma URL | Exact tokens via Figma MCP (get_screenshot + get_variable_defs) |
| Brand PDF / style guide | Official brand assets — verified colors, fonts, usage rules |
| Logo files | Logo variants + colourways for the Logo section (Section 2). File names populate the logo: tokens; the skill never invents variants |
Validation
Before proceeding: at least one source available (screenshots, URL, or brand PDF); client project folder exists at projects/consulting/{slug}/ (or will be created); template file exists at the premium reference.
Process
The brand kit runs in 4 phases. Read the premium reference for the full step-by-step.
Phase summary:
- 8-dim brief parse (preprocessing). Before any of the phases below, run the closed-vocab parser at the premium reference on the client's brief. Resolves 8 dimensions (palette / accent / typography / display / layout / mood / density / constraints) + Genesys 9th dimension (evidence_weight) into closed-vocab values. Default-resolves missing dimensions transparently. Forces decision on ambiguous brief language ("professional" / "minimal" / "premium") BEFORE the open-ended interview runs.
- Capture & analyze — collect screenshots, visual analysis (colors / typography / spacing / components / effects / layout), optional CSS extraction with platform detection, cross-reference and score confidence (0-5).
- Visual description — mood, metaphor, color story, typography personality, spatial rhythm, signature elements, texture, motion, component character, prompt for reproduction.
- Compile DESIGN.md — YAML tokens FIRST (Step 3.0), then 8 prose sections in canonical order. Tokens are machine-authoritative; prose explains.
- Write, lint & verify — write file, run 8 lint rules (3 mandatory: broken-ref, primary-defined, section-order; 5 strong recommendations: contrast-ratio, typography-defined, orphaned-tokens, one-primary-per-screen, two-font-weights-max), self-review, update client CLAUDE.md, suggest downstream actions.
Anti-hallucination guardrails
- Never invent hex values. If you can't extract a color with confidence, mark it as
[NEEDS VERIFICATION]with your best approximation and confidence score. - Never invent font names. If you can't identify the font, describe the letterform shape and suggest likely candidates marked
[NEEDS VERIFICATION]. - Never invent logo variants. Only document logo files that actually exist in the project folder.
- Mark confidence levels. Every token gets a 0-5 confidence score.
- Source every section. Note whether each value came from screenshot analysis, CSS extraction, or brand PDF.
- Screenshots are visual truth. When CSS and screenshots disagree, trust what you see in the screenshot — the CSS may be overridden or compiled differently.
Quality
Pre-delivery checklist + confidence scoring + worked example (Linear.app) + anti-examples + iteration prompts library: the premium reference.
Integration with other skills
The DESIGN.md output is the canonical input for every visual-production skill. The contract — how tokens flow to shadcn primitives (web), Figma variables, and non-web tools — is defined in .claude/rules/design-production.md.
| Skill | Relationship | What it reads from DESIGN.md |
|---|---|---|
| company-context | Upstream | (Provides company description / ICP — input, not output) |
| brand-context | Sibling sync | Reads voice signals → updates client CLAUDE.md |
| landing-page-wireframe | Downstream (web) | All tokens → wireframe spec |
| landing-page-copy | Downstream (web) | colors, typography, Do's/Don'ts |
| landing-page-playground | Downstream (web) | All tokens → multiple variants |
| landing-page-audit | Downstream (web) | All tokens (used as the rubric) |
| vibe-coding | Downstream (web) | All tokens → CSS vars + Tailwind config + shadcn components |
| website-build | Downstream (orchestrator) | All tokens (orchestrates brand → wireframe → copy → deploy) |
| website-copy | Downstream (web) | colors (semantic), typography, Do's/Don'ts |
| figma-to-prototype | Downstream (Figma) | All tokens → Figma variables |
| dashboard | Downstream (web) | colors, typography, spacing → React + shadcn + recharts |
| linkedin-carousels | Downstream (brief) | colors, typography, Do's/Don'ts |
| linkedin-infographics | Downstream (brief) | colors, typography, components |
| sales-deck | Downstream (brief) | colors, typography, components |
| one-pager | Downstream (brief) | colors, typography, spacing, components |
| ad-creative-brief | Downstream (brief) | colors, typography, components |
MCP data integration
Level: 0 — Context (heavy pulls)
Pulls fresh
| Source | What to pull | Tool | When |
|---|---|---|---|
| Playwright | Screenshots of website pages | browser_take_screenshot |
When user provides URL instead of screenshots |
| Figma | Design tokens and screenshots | get_screenshot, get_variable_defs |
When user provides Figma URL |
| Firecrawl | Website CSS for supplementary extraction | firecrawl_scrape |
Optional — URL provided |
| Exa | Brand mentions, visual identity references | web_search_exa |
Optional enrichment |
Fallback (no MCP)
- User-provided screenshots (always works — no MCP needed)
- WebFetch for website pages
- WebSearch for brand references
HTML preview sync (4-layer defense against staling)
The .html preview is, by default, regenerated from the .md tokens — not edited directly. A client can opt into a richer hand-authored preview instead (see layer 4). Drift is prevented by:
- Atomic emission in this skill. The Phase 3 compile step always writes both
.mdand.htmlin the same run. Both files carry a sharedsync_versioninteger (frontmatter field on the.md; meta tag in the.html) that increments on every run. - Pre-commit hook.
.claude/hooks/pre-commit.sh(step 6) fires on any commit touching**/brand/MMYY-brand-kit.md. It pipes the changed paths toscripts/regenerate-preview.py --changed, which reads the YAML token frontmatter, regenerates the sibling.htmlfrom the premium reference, and re-stages both files. Mirrors theskill-catalogauto-sync pattern. - Stale banner inside the HTML. The HTML's inline script fetches its sibling
.mdon load. If the.mdsync_versionexceeds the HTML's embeddedsync_version, the page renders a red banner: "⚠ This preview is stale. Source DESIGN.md has been updated. Re-run /brand-kit to refresh." - No-clobber guard for hand-authored previews. The regenerator never overwrites a preview a human authored. The template stamps a
brand-kit:autogenmarker into every generated file; a preview lacking that marker (or carrying an explicitbrand-kit:no-regencomment) is treated as hand-authored and left untouched. On a source change the regenerator still bumpssync_versionso layer 3 fires — the hand-authored preview shows the stale banner, prompting a manual refresh — but it is never clobbered. Escape hatches: delete the.htmlto get a fresh autogen preview on the next commit, or runscripts/regenerate-preview.py <md> --force.
Combined: drift is structurally prevented (layer 1), automatically corrected for autogen previews (layer 2), visibly flagged if both fail (layer 3), and hand-authored previews are protected from silent overwrite while still being told when they've gone stale (layer 4).
Design decision (2026-06-30): custom previews are supported (option a), not "enrich the template until autogen always suffices" (option b). A per-client brand kit can carry a four-tier palette, multiple typefaces, and bespoke graphic devices (e.g. ClientCo' journey-line) that a fixed 7-swatch template structurally can't represent. Rather than grow the template into an open-ended generator chasing every client's bespoke layout, the regenerator yields to a hand-authored preview when one exists. The bare template stays the zero-effort default for clients who don't need more.
What's in the preview
The the premium reference renders:
- Logo grid — the brand's logo variants (horizontal / stacked / icon) in full-colour and reversed, each on its approved background, plus clear-space + min-size rules. Rendered from the
logo:tokens; the regenerator drops the whole section automatically when the kit has nologo:group - Color swatches — one tile per palette color with hex label, named role (primary / secondary / tertiary / neutral / surface / on-surface / error)
- Typography ramp — display-lg / headline-lg / body-md / label-sm with sample text in the brand's font family
- Button states — primary / secondary / ghost in resting + hover styling, using the components.button-* tokens
- Spacing scale — visual bars showing xs / sm / md / lg / xl
- Do's and Don'ts call-outs — text excerpts from the prose body, surfaced visually
Stakeholder workflow: client opens HTML in browser → sees the actual palette in context → approves visually or sends back specific token-level feedback.