How to Use `generate_variants` with Creative Range Options in Stitch Skills

The generate_variants tool accepts a variantOptions object that uses the creativeRange parameter—set to REFINE, EXPLORE, or REIMAGINE—to control variation intensity, alongside variantCount (1-5) and aspects arrays, enabling precise control over generated screen alternatives.

The generate_variants function powers the Explore Variations workflow within the google-labs-code/stitch-skills repository, allowing developers to programmatically create alternative versions of existing screens using Stitch's generative engine. By configuring the creativeRange option in your request payload, you control whether the engine produces subtle refinements or radical redesigns while preserving your core design language.

Understanding the creativeRange Options

The creativeRange flag inside variantOptions determines how aggressively the generative engine modifies the source screen. According to plugins/stitch-design/skills/generate-design/SKILL.md, three distinct modes control this behavior:

REFINE — Subtle Adjustments

Use REFINE when you need conservative tweaks that stay close to the original design. This mode produces minor spacing adjustments, slight color temperature shifts, or subtle typography refinements without altering the overall layout structure or visual motifs.

EXPLORE — Balanced Novelty

Use EXPLORE for balanced alternatives that introduce fresh ideas while maintaining recognizability. This mode modifies layout grids, experiments with complementary color schemes, and adjusts imagery or font pairings, making it ideal for A/B testing or presenting clients with moderate evolution options.

REIMAGINE — Radical Restructuring

Use REIMAGINE when you want bold, transformative changes. This mode generates radical alternatives that may swap major layout structures, replace entire color palettes, or introduce new visual motifs—effectively creating distinct design directions from a single source screen.

Constructing the variantOptions Payload

The complete request payload requires projectId, selectedScreenIds, a guiding prompt, and the variantOptions object. The variantOptions block accepts variantCount (integer 1-5, defaults to 3), creativeRange (string), and an optional aspects array targeting specific UI elements: LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, or TEXT_CONTENT.

{
  "projectId": "projects/123456789",
  "selectedScreenIds": ["screen-abcde"],
  "prompt": "Create lighter, modern alternatives that emphasize whitespace and a pastel palette.",
  "variantOptions": {
    "variantCount": 3,
    "creativeRange": "EXPLORE",
    "aspects": ["LAYOUT", "COLOR_SCHEME"]
  }
}

Retrieving Screen IDs and Invoking the Tool

Before calling generate_variants, identify the source screen using list_screens or get_screen to obtain the projectId and screenId values. The tool processes these identifiers along with your creative parameters to generate alternatives.

import json, os, requests

payload = {
    "projectId": "projects/123456789",
    "selectedScreenIds": ["screen-abcde"],
    "prompt": "Create lighter, modern alternatives that emphasize whitespace and a pastel palette.",
    "variantOptions": {
        "variantCount": 3,
        "creativeRange": "EXPLORE",
        "aspects": ["LAYOUT", "COLOR_SCHEME"]
    }
}

# Call the generate_variants endpoint (provided by the Stitch MCP)

resp = requests.post("https://stitch-mcp.example.com/generate_variants", json=payload)
variants = resp.json()["outputComponents"]

Processing Responses and Persisting Assets

The response contains outputComponents, an array where each element includes html content and a screenshotUrl. Extract these assets and store them under .stitch/designs/ for downstream build steps, optionally updating .stitch/metadata.json to register new screens with plugins like react-components.

# Save HTML + screenshots

os.makedirs(".stitch/designs", exist_ok=True)
for i, comp in enumerate(variants):
    html_path = f".stitch/designs/variant_{i+1}.html"
    with open(html_path, "w") as f:
        f.write(comp["html"])
    # Download screenshot

    img = requests.get(comp["screenshotUrl"]).content
    with open(f".stitch/designs/variant_{i+1}.png", "wb") as f:
        f.write(img)

print("✅ Variants saved under .stitch/designs")

Command-Line Implementation

For shell-based workflows, pipe the JSON response through jq to extract components and save them directly:

# Assume $PAYLOAD contains the JSON payload

curl -X POST https://stitch-mcp.example.com/generate_variants \
     -H "Content-Type: application/json" \
     -d "$PAYLOAD" | jq -c '.outputComponents[]' | while read -r comp; do
  html=$(echo "$comp" | jq -r '.html')
  screenshot=$(echo "$comp" | jq -r '.screenshotUrl')
  idx=$(echo "$comp" | jq -r '.index')
  echo "$html" > ".stitch/designs/variant_${idx}.html"
  curl -s "$screenshot" -o ".stitch/designs/variant_${idx}.png"
done

Key Source Files

Reference these files in the google-labs-code/stitch-skills repository for detailed schema definitions and prompt engineering guidance:

• plugins/stitch-design/skills/generate-design/SKILL.md — Contains the complete Generate Variants Flow specification and the variantOptions JSON schema.
• plugins/stitch-design/skills/generate-design/README.md — Provides user-facing invocation examples and workflow integration patterns.
• plugins/stitch-design/skills/generate-design/resources/references/design-mappings.md — Lists UI/UX keywords that improve prompt effectiveness when paired with creativeRange settings.
• plugins/stitch-utilities/skills/design-md/SKILL.md — Documents how DESIGN.md files drive the visual language constraints that the variant engine respects across all creative ranges.

Summary

• generate_variants creates alternative screen designs through the Stitch MCP using controlled variation parameters.
• creativeRange offers three intensity levels: REFINE for subtlety, EXPLORE for balanced innovation, and REIMAGINE for radical redesigns.
• variantOptions combines creativeRange with variantCount (1-5) and aspects to target specific design elements like layout or color scheme.
• Output handling requires extracting html and screenshotUrl from outputComponents and persisting them to .stitch/designs/.

Frequently Asked Questions

What values does creativeRange accept?

The creativeRange parameter accepts three string values: REFINE, EXPLORE, and REIMAGINE. These control the generative engine's aggression level, ranging from minor adjustments to complete layout overhauls.

How many variants can I generate in one request?

You can request between 1 and 5 variants per call using the variantCount field. If omitted, the system defaults to generating 3 alternatives.

Which aspects can I target alongside creativeRange?

The optional aspects array accepts: LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, and TEXT_CONTENT. Combine these with creativeRange to constrain variations to specific design dimensions while letting others remain constant.

Where are the generated HTML files stored?

Persist variant HTML files under .stitch/designs/ (e.g., .stitch/designs/variant_1.html) alongside their screenshot PNGs. Update .stitch/metadata.json to register these new assets with downstream build plugins like react-components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}