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

> Learn how to use generate_variants with creativeRange options REFINE EXPLORE or REIMAGINE for precise control over screen variations in Stitch Skills. Optimize your content generation today.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`.

```json
{
  "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.

```python
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`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/metadata.json) to register new screens with plugins like `react-components`.

```python

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

```bash

# 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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-utilities/skills/design-md/SKILL.md)** — Documents how [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/designs/variant_1.html)) alongside their screenshot PNGs. Update [`.stitch/metadata.json`](https://github.com/google-labs-code/stitch-skills/blob/main/.stitch/metadata.json) to register these new assets with downstream build plugins like `react-components`.