pi-config/skills/design-explore/SKILL.md

name, description

name	description
design-explore	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:

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:

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:

# 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:

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