define-design-guidelines

# 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 - premium, editorial, sophisticated (Playfair, Cormorant)" - "Bold geometric - strong, modern, impactful (Clash Display, Satoshi)" - "Rounded/friendly - approachable, soft, inviting (Nunito, Quicksand)" - "Editorial mix - display headlines with refined body (custom pairing)" - "Clean sans - neutral but NOT generic (Geist, DM Sans - not Inter/Roboto)" ``` **Question 4: Geometry & Shape** **Use the opus agent's geometry & motion analysis.** ``` header: "Geometry" question: "What geometric character defines your UI?" options: - "[Inferred] (Recommended)" - "Sharp zero-radius - all corners sharp, no exceptions (precision, clinical)" - "Minimal/subtle - small radius (4-6px) for polish without softness" - "Rounded/soft - generous radius (8-16px) for friendliness" - "Pill shapes - fully rounded buttons/badges for playfulness" - "Mixed - sharp containers, rounded interactive elements" ``` **Question 5: Information Density** **Use the opus agent's analysis of ICP technical level and patience.** ``` header: "Density" question: "How dense should information be?" options: - "[Inferred] (Recommended)" - "Dense - information-rich, minimal whitespace (power users)" - "Balanced - comfortable density with clear hierarchy" - "Spacious - generous whitespace, breathing room" - "Editorial - dramatic spacing, statement pieces" ``` **Question 6: Motion Philosophy** **Use the opus agent's motion philosophy recommendation.** ``` header: "Motion" question: "What's your animation philosophy?" options: - "[Inferred] (Recommended)" - "Instant - <100ms, no unnecessary animation (respects time)" - "Functional - fast, purposeful, feedback-focused" - "Subtle - refined micro-interactions, polished feel" - "Delightful - playful animations, personality-forward" - "Dramatic - bold transitions, statement animations" ``` **Question 7: Primary Color Direction** ``` header: "Primary Color" question: "What color family anchors your palette?" options: - "[Inferred if clear signal] (Recommended)" - "Orange/amber - energy, action, warmth" - "Blue - trust, calm, professional" - "Green - growth, success, nature" - "Purple - creativity, premium, unique" - "Red/coral - bold, urgent, passionate" - "Teal/cyan - modern, tech, fresh" - "Neutral - black/white/gray dominant, accent secondary" - "Custom - I have specific brand colors" ``` **Question 7b: Brand Colors (If "Custom" selected)** ``` header: "Brand Colors" question: "What are your brand colors?" freeText: true placeholder: "e.g., 'Primary: #F97316 (orange), Secondary: #3B82F6 (blue), Background: #0A0A0B'" ``` **Question 8: Technical Constraints** ``` header: "Tech Stack" question: "What's your frontend tech stack?" options: - "React + Tailwind (Recommended - most flexible)" - "React + CSS-in-JS (styled-components, emotion)" - "React + CSS Modules" - "Vue + Tailwind" - "Vanilla HTML/CSS/JS" - "Other framework" multiSelect: false ``` **Question 9: Signature Elements** ``` header: "Signature" question: "What should be immediately recognizable about your UI? (Select 2-3)" options: - "[Inferred from aesthetic] (Recommended)" - "Zero border-radius everywhere" - "Monospace typography for data" - "Single dominant accent color" - "Heavy use of negative space" - "Custom cursor or micro-interactions" - "Unique loading states" - "Distinctive iconography" - "Gradient treatments" - "Texture or grain overlays" - "Bold asymmetric layouts" multiSelect: true ``` **Question 10: Product Context** (Free text) ``` header: "Product Context" question: "Describe your product briefly - what does it do and what's the primary interface?" freeText: true placeholder: "e.g., 'Chess analysis tool - main screen shows a chess board with win percentage overlay. Data-heavy stats pages.'" ``` **Question 11: References** (Optional, free text) ``` header: "References" question: "Any products or websites whose design you admire? (Optional)" freeText: true placeholder: "e.g., 'Linear's clean interface, Stripe's documentation, Notion's typography'" ``` **Question 12+: Gap-Filling** After core questions, verify you have clarity on: - Aesthetic direction (specific, not vague) - Typography approach - Color palette direction - Geometry decisions - Motion philosophy - Signature elements Keep asking until confident enough to generate a distinctive design system. ### Phase 3: Generate Document Based on the design-research agent's analysis and user's confirmed preferences, generate `DESIGN_GUIDELINES.md`. The document should include: 1. **Identity** - User, problem, aesthetic direction, "We Are / We Are NOT", signature elements, core principles 2. **Design Tokens** - Colors (surfaces, text, accent, status, borders), typography (fonts, sizes, weights), spacing, geometry, shadows, animation timings, breakpoints 3. **Voice & Copy** - UI tone, bad/good examples, state copy 4. **Components** - Cards, buttons, inputs, toasts with specific specs 5. **Layout Patterns** - Primary layout philosophy, visual hierarchy 6. **Motion** - Philosophy, orchestrated reveals, loading states 7. **Anti-Patterns** - AI slop to avoid, brand violations, customer-ignoring mistakes 8. **Ship Checklist** - Pre-ship verification items **Incorporate the design-research agent's full analysis** into the document—especially the anti-patterns, signature elements, and reference products. Write `DESIGN_GUIDELINES.md` to the current working directory. ### Phase 4: Automatic Alignment Audit After generating the document, **automatically** audit it against CUSTOMER.md and BRAND_GUIDELINES.md to ensure perfect alignment. This is NOT optional—run at least one audit cycle. **Launch the Design Quality Auditor Agent:** ``` Launch Task agent (subagent_type: design-quality-auditor) with prompt: "Audit DESIGN_GUIDELINES.md for alignment with customer profile and brand guidelines. Document paths: - DESIGN_GUIDELINES.md: [path] - CUSTOMER.md: [path] - BRAND_GUIDELINES.md: [path] (if exists) Perform your full audit protocol and report results." ``` The agent will: 1. Read all three documents 2. Check customer alignment, brand alignment, internal consistency, completeness 3. Report `✅ AUDIT PASSED` or `⚠️ ISSUES FOUND` with specific fixes **After audit completes:** 1. **If AUDIT PASSED**: Proceed to finalization 2. **If ISSUES FOUND**: - Apply all suggested fixes to DESIGN_GUIDELINES.md - Run the audit again - Repeat until AUDIT PASSED (max 3 cycles to prevent infinite loops) **Example audit issue and fix:** ``` ISSUE: Customer Alignment - ICP values "zero patience" but motion philosophy specifies 300ms animations which feels slow for this audience. FIX: Change base animation duration to 100ms, reserve 300ms only for celebratory moments like score reveals. ``` ### Phase 5: Finalization Once audit passes, add version history: