design-app

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.]

---

## 4. Spacing System

### Scale
[Token-based scale (space-1 through space-16) with pixel values
and usage guidelines for proximity grouping]

### Spacing Rules
[When to use tight vs. loose spacing based on content relationships]

---

## 5. Component Designs

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)

### Components to Specify:
1. **Button** — Primary, Secondary, Ghost variants
2. **Card** — Content container with elevation
3. **Text Input** — Default, focus, error, disabled
4. **Navigation** — Tab bar or sidebar pattern
5. **List Item** — The primary repeating element
6. **Badge/Tag** — Status indicators
7. **Modal/Dialog** — Overlay pattern

### Layout Patterns
[Key screen layouts — how the navigation, content area, and
action zones are arranged. Include responsive breakpoints if web.]

---

## 6. Motion & Interaction

### Transition Tokens
[Duration and easing values for micro-interactions]

### Key Animations
[Hover effects, page transitions, loading states, state changes]

---

## 7. Implementation Notes

### File Mapping
[Which existing files need changes, which new files to create]

### Migration Path
[If existing design exists — how to incrementally adopt this concept]

### Design Tokens Export
[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

1. Theme toggle — Light/dark mode switch in the top corner
2. Representative screen — Show the app's primary screen with real-looking content (not lorem ipsum)
3. Component showcase — Display all specified components in their various states
4. Interactive states — Hover effects, focus states, and transitions must work
5. Responsive — Must look reasonable on both desktop and mobile widths
6. 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>
  <!-- Google Fonts -->
  <style>
    /* CSS Custom Properties for all design tokens */
    :root { /* light mode tokens */ }
    [data-theme="dark"] { /* dark mode tokens */ }

    /* Full component styles using only token references */
    /* Interactive states */
    /* Responsive breakpoints */
    /* Theme toggle styles */
  </style>
</head>
<body>
  <!-- Theme toggle button -->
  <!-- App header/navigation -->
  <!-- Primary screen mockup with realistic content -->
  <!-- Component showcase section -->
  <!-- Color palette visualization -->

  <script>
    // Theme toggle logic
    // Any interactive behavior
  </script>
</body>
</html>

---

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
================================================================