define-design-guidelines

What this skill does

# Design Guidelines Skill

Create the DESIGN_GUIDELINES.md document that defines HOW to design interfaces for your customer. This document drives all UI/UX: components, layouts, animations, colors, typography—everything visual.

> **Prerequisite**: CUSTOMER.md must exist. Design without customer definition is just aesthetic preference. The interface must resonate with WHO you're building for.

## Overview

This skill supports both **creating new design guidelines** and **refining existing ones**.

This skill guides you through:
0. **Prerequisite Check** - Verify CUSTOMER.md exists; stop if not
1. **Deep Analysis** - Launch design-research agent to understand ideal design for the customer
2. **Discovery** - Confirm/refine design direction with targeted questions
3. **Generate Document** - Create DESIGN_GUIDELINES.md with full design system
4. **Automatic Alignment Audit** - Opus agent verifies alignment with CUSTOMER.md/BRAND_GUIDELINES.md, fixes issues, repeats until perfect
5. **Finalization** - Add version history once audit passes

## Core Philosophy: Anti-AI-Slop

**CRITICAL**: This skill bakes in the frontend-design skill's principles. Every design guideline must avoid generic AI aesthetics:

### What to AVOID (AI Slop)
- **Generic fonts**: Inter, Roboto, Arial, system fonts, Space Grotesk
- **Cliché colors**: Purple gradients on white, generic blue CTAs, safe gray palettes
- **Predictable layouts**: Cookie-cutter grids, template-looking compositions
- **Safe choices**: Border-radius everywhere, subtle animations, inoffensive everything
- **Generic components**: Bootstrap/MUI defaults without personality

### What to EMBRACE
- **Bold aesthetic commitment**: Pick an extreme and execute with precision
- **Distinctive typography**: Characterful fonts that match the product personality
- **Intentional color**: Dominant colors with sharp accents, not timid even distribution
- **Spatial creativity**: Asymmetry, overlap, diagonal flow, grid-breaking elements
- **Atmospheric details**: Textures, gradients, shadows, effects that create depth

**The test**: Would someone mistake this for a generic template? If yes, it's wrong.

## Workflow

### Phase 0: Prerequisite Check

**CRITICAL**: Before anything else, check for CUSTOMER.md:

1. Use Glob to search for `**/CUSTOMER.md` in the current directory
2. **If NOT found**: Stop immediately and inform the user:

```
"I can't create design guidelines without knowing WHO you're designing for.

Please create your CUSTOMER.md first using /define-customer.

Design without customer definition is just aesthetic preference—it won't resonate with anyone specific."
```

Do NOT proceed. End the workflow here.

3. **If found**: Read the CUSTOMER.md and extract key context:
   - ICP definition (who they are)
   - What they value (speed? precision? fun? simplicity?)
   - Behavioral traits (patient? impatient? technical? casual?)
   - Anti-personas (who they're NOT)
   - Any visual/experience hints

**IMPORTANT - Pre-fill Recommendations**: Use CUSTOMER.md to infer recommended options for all questions:

| If CUSTOMER.md says... | Recommend... |
|------------------------|--------------|
| ICP values "speed", "efficiency", "no patience" | Terminal/utilitarian aesthetic, fast animations, dense UI |
| ICP is technical (developers, engineers) | Monospace typography, dark theme, information-dense |
| ICP values "data", "statistics", "precision" | Data terminal aesthetic, clinical colors, sharp geometry |
| ICP is "fun-seekers", "casual players", "beginners" | Playful/soft aesthetic, rounded corners, inviting colors |
| ICP is "professionals", "executives" | Refined/luxury aesthetic, premium typography, restrained palette |
| ICP values "creativity", "expression" | Bold/maximalist aesthetic, unexpected layouts, strong personality |
| Anti-persona is "corporate" or "enterprise" | Avoid generic SaaS look, embrace distinctive character |

The goal: **User should be able to accept all recommended defaults** and get a design system that resonates with their ICP.

Then check for existing DESIGN_GUIDELINES.md:

```
header: "Existing Design Guidelines Found"
question: "I found existing DESIGN_GUIDELINES.md. What would you like to do?"
options:
  - "Refine it - update based on new insights"
  - "Start fresh - create new design guidelines"
  - "Review it - just read through what's there"
```

### Phase 1: Deep Analysis

**BEFORE asking any questions**, launch the `design-research` agent to deeply analyze the customer profile and determine the ideal design direction.

**Launch the Design Research Agent:**

```
Launch Task agent (subagent_type: design-research) with prompt:

"Analyze the customer profile to determine ideal UI/UX design direction.

CUSTOMER.md path: [path found in Phase 0]

Provide your full design analysis covering:
1. Customer Design Psychology
2. Recommended Aesthetic Direction
3. Typography Recommendation
4. Color Direction
5. Geometry & Motion
6. Signature Elements
7. Anti-Patterns for This ICP
8. Design Reference Products

Be specific and decisive. This analysis will inform the entire design system."
```

The agent will:
1. Read CUSTOMER.md and BRAND_GUIDELINES.md (if exists)
2. Research industry design patterns and competitors
3. Provide comprehensive design analysis with specific recommendations

**After agent completes**, extract the analysis and use it to:
1. Pre-fill ALL question recommendations with high confidence
2. Present a summary to the user before discovery questions

**Present Analysis Summary:**

```
header: "Design Analysis"
question: "Based on your customer profile, here's my recommended design direction. Does this feel right?"
[Display: Aesthetic direction, typography, theme, key signature elements]
options:
  - "Yes - this direction feels right, let's refine details (Recommended)"
  - "Mostly - good direction but some things feel off"
  - "No - I have a different vision"
```

If "Yes" or "Mostly", proceed to Phase 2 with agent recommendations as defaults.
If "No", ask what's different and adjust recommendations.

### Phase 2: Discovery

Use AskUserQuestion for all questions. **Put the recommended option FIRST** with "(Recommended)" suffix. **Use the opus agent's analysis to inform ALL recommendations.**

**Question 1: Aesthetic Direction**

This is the most important question. The entire design system flows from this choice.

**Use the opus agent's recommendation as the default.** The agent has already analyzed CUSTOMER.md deeply.

```
header: "Aesthetic Direction"
question: "What aesthetic direction fits your product and customer?"
options:
  - "[Inferred from CUSTOMER.md] (Recommended)"
  - "Data terminal - clinical, sharp, information-dense (Bloomberg, trading apps)"
  - "Brutally minimal - stark, essential, no decoration"
  - "Industrial utilitarian - functional, raw, tool-like"
  - "Luxury/refined - premium, elegant, restrained"
  - "Editorial/magazine - typographic, editorial, sophisticated"
  - "Brutalist/raw - bold, unapologetic, confrontational"
  - "Retro-futuristic - nostalgic tech, synthwave, neon"
  - "Playful/toy-like - fun, colorful, delightful"
  - "Soft/pastel - gentle, approachable, calming"
  - "Art deco/geometric - structured, ornamental, patterns"
  - "Organic/natural - flowing, earthy, warm"
```

**Question 2: Theme Preference**

**Use the opus agent's color direction analysis.**

```
header: "Theme"
question: "What's your primary theme?"
options:
  - "[Inferred] (Recommended)"
  - "Dark theme - dark backgrounds, light text (more distinctive)"
  - "Light theme - light backgrounds, dark text (more accessible)"
  - "Both - design for both with theme switching"
```

**Question 3: Typography Character**

**Use the opus agent's typography recommendation.**

```
header: "Typography"
question: "What typographic character fits your brand?"
options:
  - "[Inferred] (Recommended)"
  - "Monospace-forward - technical, precise, data-focused (JetBrains Mono, Fira Code)"
  - "Elegant serif -