extracting-stitch-mockups

name	extracting-stitch-mockups
description	Extracts generated mockup images from Google Stitch project pages. Use when user provides a Stitch project URL (stitch.withgoogle.com/projects/...), mentions extracting/downloading Stitch mockups, saving Stitch designs, or wants to archive generated design assets. Requires authenticated Chrome browser profile.
allowed-tools	Read, Write, Bash, Grep, Glob

Extract Stitch Mockups

Quick Start

1. Get project URL - User provides https://stitch.withgoogle.com/projects/{id}
2. Resolve feature directory - Determine where to save using fallback chain
3. Run extraction script - Execute scripts/extract_images.py with Playwright
4. Save to exports - Images saved to design-intent/google-stitch/{feature}/exports/

---

Feature Directory Resolution

Determine target feature directory using this fallback chain:

1. User specifies - Optional --feature argument provided
2. Auto-detect - Match Stitch project title to existing design-intent/google-stitch/{feature}/ directories
3. Prompt user - List existing directories and ask user to select or create new

Auto-Detection Logic

• Extract project title from Stitch page (e.g., "Eco-Travel Home Screen")
• Normalize to feature format: lowercase, hyphens, strip special chars
• Search for matching directory in design-intent/google-stitch/
• If multiple partial matches, prompt user to select

---

Extraction Process

Prerequisites

• Chrome browser with active Google session
• uv installed (https://github.com/astral-sh/uv)
• Playwright browsers: uv run playwright install chromium

Script Execution

# Basic usage
uv run scripts/extract_images.py "https://stitch.withgoogle.com/projects/123"

# With explicit feature directory
uv run scripts/extract_images.py "https://stitch.withgoogle.com/projects/123" --feature dashboard

# Or run directly (after chmod +x)
./scripts/extract_images.py "https://stitch.withgoogle.com/projects/123"

Image Filtering

• Source: lh3.googleusercontent.com/aida/... URLs only
• Size filter: Images with dimensions >= 400px (mockups, not UI elements)
• Excludes: avatars, icons, UI chrome

Generation Check

Script checks for "Generating..." status on page:

• If detected: Exit with message to retry after generation completes
• If complete: Proceed with extraction

---

Output Structure

Images saved to existing feature's exports/ directory:

design-intent/google-stitch/{feature}/exports/
├── mockup-1.png
├── mockup-2.png
└── mockup-N.png

File Naming

• Sequential numbering: mockup-{index}.png
• Index starts at 1
• Preserves original image format (typically PNG)

---

Report

After extraction, display summary:

Extracted {N} mockups from Stitch project

Project: {project-title}
URL: {project-url}

Saved to: design-intent/google-stitch/{feature}/exports/
  - mockup-1.png (400x800)
  - mockup-2.png (400x800)
  - ...

Feature directory:
  design-intent/google-stitch/{feature}/
  ├── prompt-v{N}.md
  ├── exports/          <- Mockups saved here
  │   ├── mockup-1.png
  │   └── mockup-2.png
  └── wireframes/

---

Common Issues

• Not authenticated - Open Chrome, sign into Google, then retry
• Still generating - Wait for Stitch to complete, then retry
• No feature directory - Run authoring-stitch-prompts first, or specify --feature

See TROUBLESHOOTING.md for detailed solutions.

Reference Files

• WORKFLOW.md - Detailed browser automation steps
• EXAMPLES.md - Sample extractions
• TROUBLESHOOTING.md - Error handling