---
name: design-explore
description: Generate UI design mockups as images for exploration and ideation. Use when the user wants to visualize a design concept before building. Supports optional DESIGN.md from awesome-design-md for design-token-accurate mockups.
---

# /design-explore

Generate visual design mockups. You ask the user what they want to design, optionally pull design tokens from a DESIGN.md file, and call the image-maker sub-agent to produce polished images.

## Flow

### Step 1: Gather requirements

Ask the user two questions:

1. **"What are we designing?"** — Free text description of the interface, page, or component.

2. **"What style? Pick from awesome-design-md or describe it."** — The user can either:
   - Provide a full URL: `https://getdesign.md/apple/design-md` or from `https://github.com/VoltAgent/awesome-design-md`
   - Describe the style in words: "dark glass morphism, purple accent, rounded corners"
   - If they provide a URL, download it and extract the design tokens

### Step 2: If DESIGN.md URL provided, extract tokens

Download the DESIGN.md file:

```bash
curl -sL <DESIGN_MD_URL> -o /tmp/design-tokens.md
```

Read the file and extract these tokens from the YAML/Markdown:

- **Palette/Colors** — background, primary, accent, text, surface
- **Typography** — font family, heading font, sizes, weights
- **Spacing** — base unit, section padding
- **Border Radius** — button, card, input values
- **Shadows** — elevation levels
- **Identity/Language** — any prose describing the visual language

If the file is YAML, parse it with `python3 -c "import yaml; ..."`. If it's Markdown, read the relevant sections.

### Step 3: Build the image prompt

Combine the user's design description with the extracted tokens into a detailed prompt:

```
Design prompt for {what}: {user's description}

Design system tokens to follow exactly:
- Color palette: {extracted palette}
- Typography: {extracted fonts}
- Border radius: {extracted radius values}
- Spacing: {extracted spacing}
- Visual identity: {extracted identity description}

Style requirements:
- Professional, high-fidelity UI mockup
- Show the interface in context (browser frame or device mockup)
- Clean, modern presentation
- Use the exact colors and fonts specified
```

If NO DESIGN.md, use only the user's description with general style guidance.

### Step 4: Call image-maker

Launch the image-maker sub-agent with the prompt:

```bash
Agent(
  subagent_type: "image-maker",
  description: "Generate design mockups",
  prompt: <the full image prompt from step 3>,
  max_turns: 3
)
```

The image-maker will generate images via OpenRouter's image models.

### Step 5: Show images inline (REQUIRED)

After images are generated, you MUST display them inline. Do NOT just save files and report paths.

1. Save each image to `/tmp/design-explore-<N>.png`
2. **Call `read` on each saved image file** — pi displays images as inline attachments
3. Present to user: "Here are the design concepts. Which direction?"

Example:
```bash
# After image-maker generates images, save them
# Then READ them so they appear inline:
read("/tmp/design-explore-1.png")
read("/tmp/design-explore-2.png")
read("/tmp/design-explore-3.png")
```

The user should see the images in the conversation, not have to open files manually.

### Step 6: Iterate

The user can:
- Pick a direction: "Go with #2 but change the accent to teal"
- Refine: generate updated images with the feedback
- Move on: "I like this. Let's build it with design-build"

---

## DESIGN.md File Format

DESIGN.md files typically look like:

```yaml
---
palette:
  background: "#FFFFFF"
  primary: "#007AFF"
  accent: "#FF9500"
  text: "#1D1D1F"
typography:
  heading: "SF Pro Display"
  body: "SF Pro Text"
  sizes:
    h1: "48px"
    h2: "32px"
    body: "17px"
spacing:
  unit: "8px"
  section: "80px"
radius:
  button: "12px"
  card: "16px"
  input: "8px"
shadows:
  card: "0 2px 8px rgba(0,0,0,0.08)"
  elevated: "0 8px 24px rgba(0,0,0,0.12)"
identity: Clean, minimal, generous white space, Apple-like clarity
---
```

But the exact format varies — always read the file contents to know the structure.

---

## Resources

- **awesome-design-md**: https://github.com/VoltAgent/awesome-design-md (55+ design systems)
- **getdesign.md**: https://getdesign.md/ (hosted DESIGN.md files)
- **image-maker agent**: Uses OpenRouter's gpt-5-image-mini (~4¢/image)