| name | design-app |
| description | Generate multiple design concepts for an app, compare them side-by-side, and implement the chosen direction. Creates detailed design documents with color palettes, typography, spacing, component specs, and interactive HTML mockups. |
| argument-hint | [count] - Optional: number of concepts to generate (default: 3, max: 7) |
Design App
Generate multiple competing design concepts for an app, present them for comparison, and implement the chosen direction into the codebase.
Instructions
IMPORTANT: Execute immediately. If context about the app is available from CLAUDE.md or the current project, use it. Otherwise, gather requirements first.
Step 1: Gather Design Context
1A: Understand the App
Read CLAUDE.md, README.md, package.json, and any existing design files to understand:
- What the app does — core purpose and key screens
- Target users — who uses this and in what context
- Tech stack — framework, styling approach (Tailwind, CSS Modules, styled-components, NativeWind, etc.)
- Existing design — any colors, fonts, or components already in place
If the app context is unclear, use AskUserQuestion to ask:
What is this app? Who is it for? Describe the core screens and the feeling you want it to evoke. Any design directions you're drawn to or want to avoid?
1B: Set Concept Count
Use the $ARGS count if provided, otherwise default to 3 concepts. Cap at 7.
1C: Select Design Directions
Choose contrasting design directions that suit the app. Pull from this palette of approaches — select directions that are meaningfully different from each other so the comparison is valuable:
| Direction | Personality | Best For |
|---|
| Modern Minimal | Clean, focused, typographic | Developer tools, productivity, SaaS |
| Warm Craft | Tactile, analog, personal | Journals, note-taking, personal apps |
| Dev Dark | IDE-inspired, dense, precise | Developer-facing tools, dashboards |
| Bold Vibrant | Energetic, confident, colorful | Consumer apps, creative tools, social |
| Glassmorphism | Layered, translucent, depth | Premium SaaS, dashboards, iOS-style |
| Swiss Precision | Grid-governed, typographic, systematic | Data apps, corporate, editorial |
| Organic Flow | Natural, biophilic, calming | Wellness, community, eco-focused |
| Dark Premium | Rich, glowing, sophisticated | Fintech, dev tools, premium SaaS |
| Retro Synthwave | Nostalgic, neon, playful | Games, entertainment, creative |
| Brutalist | Raw, bold, unconventional | Portfolios, agencies, counter-culture |
Don't just pick the first N — select directions that create interesting tension. For example, {Modern Minimal, Warm Craft, Dev Dark} gives three very different takes on a productivity app.
Step 2: Create Design Concepts Directory
Create the output directory structure:
docs/design-concepts/
├── concept-1-[direction-slug].md
├── concept-2-[direction-slug].md
├── concept-3-[direction-slug].md
├── mockups/
│ ├── concept-1-[direction-slug].html
│ ├── concept-2-[direction-slug].html
│ └── concept-3-[direction-slug].html
└── COMPARISON.md
If docs/design-concepts/ already exists, check for existing concepts and ask whether to replace or add to them.
Step 3: Generate Design Concept Documents
For each concept, generate a complete design document following this structure. Every concept must be fully specified — detailed enough that someone could implement it without asking questions.
Concept Document Structure
# Design Concept N: [Direction Name]
**Direction:** [1-2 sentence summary of the visual approach]
**Personality:** [3-4 adjectives]
**Emotion:** [What the user should feel using this app]
**Audience:** [Who this design speaks to]
---
## 1. Design Philosophy & Inspiration
### Core Principles
[4-5 numbered principles that govern every design decision]
### Inspiration Sources
[5-6 real products/designers/movements — be specific, not generic]
### What Makes This NOT AI-Generated
[6-8 specific anti-patterns: why this won't look like default Tailwind/Bootstrap.
Call out exact decisions — specific hex values instead of generic blue,
asymmetric spacing instead of uniform p-4, distinctive font pairings
instead of just Inter, etc.]
---
## 2. Complete Color Palette
### Design Rationale
[Why these specific colors — what metaphor or material they reference]
### Light Mode
[Full token list with hex values, organized by category:
- Background & Surfaces (4-6 tokens)
- Text hierarchy (4 tokens)
- Accent colors (3-4 tokens + muted variants)
- Borders & Dividers (3 tokens)
- Task/State colors (map to app states)
- Semantic colors (success, warning, error, info)]
### Dark Mode
[Complete alternate palette — not just "invert the colors" but a
thoughtfully designed dark variant]
### Contrast Verification
[Table showing key text/background combinations with WCAG AA/AAA results]
### Tailwind/CSS Configuration
[Ready-to-paste config for the project's styling approach]
---
## 3. Typography System
### Font Choices & Rationale
[2-3 fonts with reasoning for each choice.
Include Google Fonts import URL or system font stack.]
### Type Scale
[Table with 8-10 styles: display, title, heading, body, body-medium,
secondary, caption, overline, mono — each with size, weight,
line-height, letter-spacing, and usage]
### Font Loading Strategy
[How to load fonts for the project's framework — @font-face,
Google Fonts link, next/font, expo-font, etc.]
---
[Token-based scale (space-1 through space-16) with pixel values
and usage guidelines for proximity grouping]
[When to use tight vs. loose spacing based on content relationships]
---
Detail the visual treatment for core components. For each, specify:
Default state appearance
Hover/focus/active/disabled states
Dimensions and padding
Border radius, shadows, transitions
Color token references (not raw hex in components)
— Primary, Secondary, Ghost variants
— Content container with elevation
— Default, focus, error, disabled
— Tab bar or sidebar pattern
— The primary repeating element
— Status indicators
— Overlay pattern
[Key screen layouts — how the navigation, content area, and
action zones are arranged. Include responsive breakpoints if web.]
---
[Duration and easing values for micro-interactions]
[Hover effects, page transitions, loading states, state changes]
---
[Which existing files need changes, which new files to create]
[If existing design exists — how to incrementally adopt this concept]
[Complete token set in the format the project uses — CSS variables,
Tailwind config, or JS/TS theme object]
Quality Standards for Each Concept
- Every hex value must be intentional — no generic blue (#3B82F6), green (#22C55E), or gray (#6B7280) from Tailwind defaults unless deliberately chosen
- Color palettes must include WCAG contrast verification for text/background combinations
- Typography must specify actual font names with fallback stacks, not just "sans-serif"
- Component specs must include all interactive states — not just the default appearance
- Dark mode must be a thoughtful redesign, not auto-inverted colors
- Spacing must use a consistent scale, not arbitrary pixel values
Step 4: Generate HTML Mockups
For each concept, generate a single-file HTML mockup that demonstrates the design in action. The mockup must be self-contained (inline CSS, no external dependencies except Google Fonts).
Mockup Requirements
- Theme toggle — Light/dark mode switch in the top corner
- Representative screen — Show the app's primary screen with real-looking content (not lorem ipsum)
- Component showcase — Display all specified components in their various states
- Interactive states — Hover effects, focus states, and transitions must work
- Responsive — Must look reasonable on both desktop and mobile widths
- Color palette strip — Visual swatch bar showing all key colors
Mobile App Device Frame
If the target app is a mobile app (React Native, Flutter, Expo, etc.), wrap the mockup content inside a phone simulator frame:
- Device bezel — Rounded rectangle with realistic proportions (e.g., 390×844 for iPhone, 360×800 for Android)
- Status bar — Time, battery, signal indicators at the top
- Home indicator — Bottom bar for gesture-nav devices
- Centered on page — The phone frame sits centered on a neutral background, with the design rendered inside at native resolution
- Device picker — Optional toggle between iPhone and Android frame proportions
- The component showcase section can render outside the phone frame (below it) at full width
This gives a realistic preview of how the design will feel on a real device, rather than stretching to fill the browser window.
For web and desktop apps, render the mockup at full browser width as normal — no device frame needed.
HTML Mockup Structure
<!DOCTYPE html>
<html lang="en" data-theme="light">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>[App Name] — Concept N: [Direction]</title>
<style>
:root { }
[data-theme="dark"] { }
</style>
</head>
<body>
<script>
Step 5: Generate Comparison Document
Create docs/design-concepts/COMPARISON.md that summarizes all concepts side-by-side:
# Design Concepts Comparison
## Overview
| Aspect | Concept 1: [Name] | Concept 2: [Name] | Concept 3: [Name] |
|--------|-------------------|-------------------|-------------------|
| **Direction** | [1-line] | [1-line] | [1-line] |
| **Personality** | [adjectives] | [adjectives] | [adjectives] |
| **Primary Color** | [name + hex swatch] | [name + hex swatch] | [name + hex swatch] |
| **Font Pairing** | [heading + body] | [heading + body] | [heading + body] |
| **Dark Mode** | [approach] | [approach] | [approach] |
| **Strengths** | [2-3 bullets] | [2-3 bullets] | [2-3 bullets] |
| **Trade-offs** | [2-3 bullets] | [2-3 bullets] | [2-3 bullets] |
| **Best If** | [when to pick] | [when to pick] | [when to pick] |
## Mockup Links
- [Concept 1: [Name]](mockups/concept-1-[slug].html)
- [Concept 2: [Name]](mockups/concept-2-[slug].html)
- [Concept 3: [Name]](mockups/concept-3-[slug].html)
## Design Philosophy Comparison
[2-3 paragraphs comparing the underlying design approaches and
what kind of user experience each creates]
## Recommendation
[Suggest which concept fits the app's stated goals best, with reasoning.
Make it clear this is a recommendation — the user chooses.]
Step 6: Present Concepts for Review
After generating all documents and mockups, present a summary:
================================================================
Design Concepts Generated
================================================================
[N] concepts created in docs/design-concepts/
Concept 1: [Direction Name]
[1-line personality summary]
Doc: docs/design-concepts/concept-1-[slug].md
Mockup: docs/design-concepts/mockups/concept-1-[slug].html
Concept 2: [Direction Name]
[1-line personality summary]
Doc: docs/design-concepts/concept-2-[slug].md
Mockup: docs/design-concepts/mockups/concept-2-[slug].html
Concept 3: [Direction Name]
[1-line personality summary]
Doc: docs/design-concepts/concept-3-[slug].md
Mockup: docs/design-concepts/mockups/concept-3-[slug].html
Comparison: docs/design-concepts/COMPARISON.md
Next Steps:
1. Open the HTML mockups in a browser to see each in action
2. Review the comparison document
3. Tell me which concept to implement (or mix elements from multiple)
================================================================
Use AskUserQuestion to ask:
Which concept would you like to implement? You can pick one directly (e.g., "concept 2"), mix elements ("concept 1 colors with concept 3 typography"), or ask me to refine any concept before deciding.
Step 7: Implement Chosen Design
Once the user selects a concept (or a mix), implement it into the actual codebase.
7A: Create Design Tokens File
Based on the project's styling approach, create the token file:
- Tailwind → Extend
tailwind.config.js / tailwind.config.ts with the color, spacing, and typography tokens
- CSS Modules / vanilla CSS → Create
styles/design-tokens.css with CSS custom properties
- styled-components / Emotion → Create
styles/theme.ts with a typed theme object
- NativeWind / React Native → Extend Tailwind config + create
theme/tokens.ts for runtime access
7B: Set Up Typography
- Add font imports (Google Fonts link,
next/font, expo-font, or @font-face declarations)
- Create typography utility classes or style objects matching the type scale
7C: Apply Base Styles
- Set background colors, default text colors, and font families on the root/body
- Implement dark mode toggle if the project supports it
- Apply the spacing scale to layout containers
7D: Update Existing Components
If components already exist, update them to use the new design tokens:
- Buttons → new colors, border-radius, shadows, hover states
- Cards → new elevation, background, borders
- Inputs → new focus rings, border colors, placeholder styles
- Navigation → new active states, backgrounds
7E: Create Design Reference
Create docs/DESIGN-SYSTEM.md documenting the implemented design:
# Design System
**Based on:** Concept [N] — [Direction Name]
**Generated by:** /design-app on [date]
## Tokens Reference
[Link to token file]
## Color Palette
[Visual reference with hex values]
## Typography
[Type scale with examples]
## Component Patterns
[How to use the design system in new components]
7F: Verify Implementation
- Check that all colors reference tokens, not hardcoded hex values
- Verify WCAG contrast ratios pass on actual rendered components
- Confirm dark mode works if implemented
- Test responsive behavior at key breakpoints
Step 8: Completion Summary
================================================================
Design Implemented
================================================================
Concept: [Direction Name]
Files Created/Modified:
[list of files with annotations: new/modified]
Design System:
Tokens: [path to token file]
Reference: docs/DESIGN-SYSTEM.md
Source: docs/design-concepts/concept-[N]-[slug].md
Features:
✓ Color palette (light + dark)
✓ Typography system ([font names])
✓ Spacing scale
✓ Component styles updated
[✓ Dark mode toggle — if applicable]
Next Steps:
- Run the app to verify the design in-browser
- Use /enhance-design for conversion + accessibility polish
- Use /style to try themed variations on this base
================================================================
