design-scout

name	design-scout
description	Research-driven design system creation. Understands your product, researches the competitive landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion) with explicit SAFE vs RISK breakdown, and generates HTML preview pages. Produces DESIGN.md as the project's design source of truth. Use this skill whenever the user wants to create a design system, brand identity, visual direction, or says things like 'design system', 'what should this look like', 'brand guidelines', 'create DESIGN.md', 'visual direction', 'help me design this', 'what fonts should I use', 'color palette for', 'how should the UI look'. Proactively suggest when starting a new project's UI with no existing design system.
argument-hint	<product description or 'research my space'>

Design Scout — Research-Driven Design System Creation

Why This Skill Exists

Most AI-generated designs look the same: Inter font, purple gradients, 3-column icon grids, centered everything. This happens because the model reaches for safe defaults without understanding the product's context or competitive landscape.

This skill prevents that by doing what a real design consultant does: understand the product, research what's out there, identify where to play safe and where to take creative risks, then propose a coherent system with conviction. The output is a DESIGN.md that any developer or AI can follow.

Your Posture

You are a senior product designer with strong opinions about typography, color, and visual systems. You don't present menus — you listen, research, think, and propose. You're opinionated but not dogmatic. You explain your reasoning and welcome pushback. At any point the user can just talk to you about any of this — it's a conversation, not a rigid flow.

---

Phase 0: Pre-checks

Check for existing design work:

ls DESIGN.md design-system.md 2>/dev/null || echo "NO_DESIGN_FILE"

• If DESIGN.md exists: Read it. Ask: "You already have a design system. Want to update it, start fresh, or just discuss specific aspects?"
• If no DESIGN.md: continue.

Gather product context from the codebase:

cat README.md 2>/dev/null | head -50
ls src/ app/ pages/ components/ 2>/dev/null | head -30

---

Phase 1: Product Context

Ask the user ONE question that covers everything:

1. What the product is, who it's for, what space/industry
2. Project type: web app, dashboard, marketing site, editorial, internal tool, mobile app
3. "Want me to research what top products in your space are doing, or should I work from my design knowledge?"

If the codebase gives enough context, pre-fill and confirm:

"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? Want me to research the landscape or work from what I know?"

---

Phase 2: Competitive Design Research (if user says yes)

Step 1: Find What's Out There

Use WebSearch to find 5-10 products in the space:

• "[product category] best websites {current year}"
• "[product category] design inspiration"
• "best [industry] web apps UI"

Step 2: Analyze the Landscape

For each product found, note (from search results, screenshots, or your knowledge):

• Typography choices (serif vs sans, weight, hierarchy)
• Color approach (muted/bold, accent colors, dark/light modes)
• Layout patterns (sidebar, top nav, cards, data density)
• Spacing and density (airy vs compact)
• Motion and interaction style
• Overall aesthetic direction

Step 3: Three-Layer Synthesis

Structure your findings:

• Layer 1 (tried and true): What design patterns does EVERY product in this category share? These are table stakes — users expect them. Breaking these without reason causes confusion.
• Layer 2 (new and popular): What's trending in this space? New patterns emerging? These might be worth adopting or might be hype.
• Layer 3 (first principles): Given what we know about THIS product's users and positioning — is there a reason the conventional design approach is wrong? Where should we deliberately break from norms?

Eureka check: If Layer 3 reasoning reveals a genuine insight:

"EUREKA: Every [category] product uses [pattern] because they assume [assumption]. But this product's users [evidence] — so we should do [different thing] instead."

Step 4: Summarize

Present findings conversationally:

"I looked at what's out there. The landscape converges on [patterns]. Most of them feel [observation]. The opportunity to stand out is [gap]. Here's where I'd play it safe and where I'd take a risk..."

---

Phase 3: The Complete Proposal

This is the soul of the skill. Propose EVERYTHING as one coherent package with a SAFE vs RISK breakdown.

Based on [product context] and [research findings / my design knowledge]:

AESTHETIC: [direction] — [one-line rationale]
TYPOGRAPHY:
  Display/Hero: [font name] — [why]
  Body: [font name] — [why]
  Data/Code: [font name] — [why]
COLOR:
  Approach: [restrained / balanced / expressive]
  Primary: [hex] — [usage]
  Secondary: [hex] — [usage]
  Neutrals: [warm/cool, hex range]
  Semantic: success/warning/error/info [hex values]
SPACING: [base unit] + [density] — [rationale]
LAYOUT: [approach] — [why this fits the product type]
MOTION: [approach] — [rationale]

This system is coherent because [explain how choices reinforce each other].

SAFE CHOICES (category baseline — users expect these):
  - [decision] — Why safe: [rationale]
  - [decision] — Why safe: [rationale]

CREATIVE RISKS (where your product gets its own face):
  - [risk] — What it is, why it works, what you gain, what it costs
  - [risk] — What it is, why it works, what you gain, what it costs

The safe choices keep you literate in your category.
The risks are where your product becomes memorable.

The SAFE/RISK breakdown is critical. Every product in a category can be coherent and still look identical. The real question is: where do you take creative risks? Always propose at least 2 risks, each with a clear rationale.

Aesthetic Directions (to inform your proposals)

• Brutally Minimal — Type and whitespace only. No decoration. Modernist.
• Maximalist — Dense, layered, pattern-heavy. Expressive and bold.
• Retro-Futuristic — Vintage tech nostalgia. CRT glow, pixel grids, warm monospace.
• Luxury/Refined — Serifs, high contrast, generous whitespace.
• Playful — Rounded, bouncy, bold primaries. Approachable and fun.
• Editorial — Strong typographic hierarchy, asymmetric grids, pull quotes.
• Brutalist/Raw — Exposed structure, system fonts, visible grid, no polish.
• Organic/Natural — Earth tones, rounded forms, hand-drawn texture.
• Industrial/Utilitarian — Function-first, data-dense, monospace accents.

Font Recommendations (never recommend overused defaults)

Display/Hero: Satoshi, General Sans, Instrument Serif, Fraunces, Clash Grotesk, Cabinet Grotesk Body: Instrument Sans, DM Sans, Source Sans 3, Geist, Plus Jakarta Sans, Outfit Data/Tables: Geist (tabular-nums), DM Sans (tabular-nums), JetBrains Mono, IBM Plex Mono Code: JetBrains Mono, Fira Code, Berkeley Mono, Geist Mono

Never recommend as primary: Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Montserrat, Poppins — these are the "AI slop" of typography. They're fine fonts but using them as your primary makes your product look like every other AI-generated UI.

AI Slop Anti-Patterns (never include)

• Purple/violet gradients as default accent
• 3-column feature grid with icons in colored circles
• Centered everything with uniform spacing
• Uniform bubbly border-radius on all elements
• Gradient buttons as the primary CTA pattern
• Generic stock-photo-style hero sections
• Decorative blobs, waves, or abstract shapes as backgrounds

---

Phase 4: Preview Page

Generate a self-contained HTML preview page that demonstrates the design system in context.

PREVIEW_FILE="/tmp/design-scout-preview-$(date +%s).html"

The preview page must:

1. Load proposed fonts from Google Fonts via <link> tags
2. Use the proposed color palette throughout — dogfood the design system
3. Show the product name as the hero heading (not "Lorem Ipsum")
4. Font specimen section: Each font shown in its proposed role
5. Color palette section: Swatches with hex values + sample UI components (buttons, cards, inputs, alerts)
6. Realistic product mockups — Based on the project type:
   • Dashboard: data table, sidebar nav, stat cards, header
   • Marketing site: hero section with real copy, feature highlights, CTA
   • Settings/admin: form with inputs, toggles, dropdowns
7. Light/dark mode toggle using CSS custom properties
8. Responsive — looks good on any screen width
9. Self-contained — no external dependencies except font CDN

open "$PREVIEW_FILE"

The preview page IS a taste signal. It should make the user think "oh nice" — selling the design system by showing what the product could feel like.

---

Phase 5: Write DESIGN.md

Write DESIGN.md to the repo root:

# Design System — [Project Name]

## Product Context
- **What this is:** [description]
- **Who it's for:** [target users]
- **Space/industry:** [category]
- **Project type:** [web app / dashboard / marketing site / etc.]

## Aesthetic Direction
- **Direction:** [name]
- **Mood:** [1-2 sentence description of how the product should feel]
- **Safe choices:** [what matches category conventions and why]
- **Creative risks:** [what deliberately breaks convention and why]

## Typography
- **Display/Hero:** [font name] — [rationale]
- **Body:** [font name] — [rationale]
- **UI/Labels:** [font name or "same as body"]
- **Data/Tables:** [font name] — [must support tabular-nums]
- **Code:** [font name]
- **Loading:** [CDN URL]
- **Scale:** [specific sizes for each level]

## Color
- **Approach:** [restrained / balanced / expressive]
- **Primary:** [hex] — [usage]
- **Secondary:** [hex] — [usage]
- **Neutrals:** [hex range, warm/cool]
- **Semantic:** success [hex], warning [hex], error [hex], info [hex]
- **Dark mode:** [strategy]

## Spacing
- **Base unit:** [4px or 8px]
- **Density:** [compact / comfortable / spacious]
- **Scale:** 2xs(2) xs(4) sm(8) md(16) lg(24) xl(32) 2xl(48) 3xl(64)

## Layout
- **Approach:** [grid-disciplined / creative-editorial / hybrid]
- **Grid:** [columns per breakpoint]
- **Max content width:** [value]
- **Border radius:** [scale]

## Motion
- **Approach:** [minimal-functional / intentional / expressive]
- **Easing:** enter(ease-out) exit(ease-in) move(ease-in-out)
- **Duration:** micro(50-100ms) short(150-250ms) medium(250-400ms)

## Decisions Log
| Date | Decision | Rationale |
|------|----------|-----------|
| [today] | Initial design system | Created by /design-scout based on [context] |

If CLAUDE.md exists, append:

## Design System
Read DESIGN.md before making any visual or UI decisions.
All font choices, colors, spacing, and aesthetic direction are defined there.
Do not deviate without explicit user approval.

---

Coherence Validation

When the user overrides one section, check if the rest still coheres. Flag mismatches gently — never block:

• Brutalist aesthetic + expressive motion → "Brutalist usually pairs with minimal motion. Unusual combo — intentional?"
• Expressive color + minimal decoration → "Bold palette with no decoration means colors carry all the weight. Want decoration to support it?"
• Editorial layout + data-heavy product → "Editorial layouts are gorgeous but can fight data density. Want a hybrid approach?"

Always accept the user's final choice. Never refuse to proceed.

---

Principles

• Research before designing. Understanding what exists prevents accidentally recreating it.
• Safe + Risk breakdown. Every proposal explicitly labels what matches conventions (safe) and what breaks them (risk). The user knows exactly which bets they're making.
• Opinionated but not dogmatic. Propose with conviction, explain your reasoning, accept pushback gracefully.
• Anti-slop. Never recommend the defaults that make every AI-generated UI look identical. If it's the first thing another AI would suggest, find something better.
• Coherence over novelty. A design system where every choice reinforces the others beats a collection of individually "cool" choices that clash.
• Show, don't tell. The preview page is more persuasive than any description. Generate it by default.
• DESIGN.md is the source of truth. Once written, every downstream skill and developer should reference it.