stitch-mcp-generate-variants

Stitch MCP — Generate Variants

Generates alternative versions of existing screens using Stitch's native variant generation API. This is more efficient than the text-prompt approach (1 API call vs. 3) and offers fine-grained control over what aspects to vary.

Critical prerequisite

Only use this skill when the user explicitly mentions "Stitch".

You must have both a projectId AND at least one screenId of an existing screen. Variants are always based on an existing design — you can't generate variants from scratch.

When to use

• User wants to explore alternative versions of an existing screen
• After generation, user says "show me some variations" or "try different styles"
• The orchestrator's Step 5b offers "Generate variants"
• A/B testing — creating multiple options for stakeholder review

Call the MCP tool

{
  "name": "generate_variants",
  "arguments": {
    "projectId": "3780309359108792857",
    "selectedScreenIds": ["88805abc123def456"],
    "prompt": "Explore different color schemes while keeping the layout structure",
    "variantOptions": {
      "variantCount": 3,
      "creativeRange": "EXPLORE",
      "aspects": ["COLOR_SCHEME", "IMAGES"]
    },
    "deviceType": "DESKTOP",
    "modelId": "GEMINI_3_1_PRO"
  }
}

Parameter reference

projectId — numeric ID only, no prefix

✅ "3780309359108792857"
❌ "projects/3780309359108792857"

selectedScreenIds — array of numeric screen IDs

✅ ["88805abc123def456"]
❌ ["projects/123/screens/88805abc123def456"]

The source screen(s) to generate variants from.

prompt — optional guidance for variant direction

Provide context about what kind of variations the user wants. The variantOptions do the heavy lifting, but the prompt adds nuance.

variantOptions — controls what and how much to vary

| Field | Type | Values | Description | |-------|------|--------|-------------| | variantCount | int | 1–5 | Number of variants to generate | | creativeRange | enum | REFINE, EXPLORE, REIMAGINE | How much to deviate from the original | | aspects | array | See below | Which design aspects to vary |

creativeRange mapping from user language

| User says | → creativeRange | What it does | |-----------|----------------|-------------| | "subtle changes", "minor tweaks", "polish" | REFINE | Small refinements, stays close to original | | "alternatives", "different options", "explore" | EXPLORE | Meaningful differences while keeping the concept | | "radical", "completely different", "reimagine" | REIMAGINE | Major departures from the original design |

aspects — what to vary

| Value | Varies | Keeps stable | |-------|--------|-------------| | LAYOUT | Structure, spacing, component arrangement | Colors, fonts, content | | COLOR_SCHEME | Colors, gradients, contrast | Layout, fonts, content | | IMAGES | Photography, illustrations, icons | Layout, colors, text | | TEXT_FONT | Typography, font choices, sizes | Layout, colors, content | | TEXT_CONTENT | Copy, labels, placeholder text | Layout, colors, fonts |

You can combine aspects: ["LAYOUT", "COLOR_SCHEME"] varies both simultaneously.

deviceType — optional

Same enum: MOBILE, DESKTOP, TABLET, AGNOSTIC

modelId — optional

| Value | Use when | |-------|---------| | GEMINI_3_1_PRO | Recommended — complex layouts, high fidelity | | GEMINI_3_FLASH | Fast iteration, wireframes, simple changes | | GEMINI_3_PRO | Deprecated. Still works but will be removed. Use GEMINI_3_1_PRO instead. |

Output

Returns new screens added to the project. Each variant appears as a separate screen in list_screens.

After generating variants

1. Call stitch-mcp-list-screens to find all new variant screens
2. Call stitch-mcp-get-screen for each to get screenshots
3. Present side by side: "Here are your 3 variants: [screenshots]. Which one do you prefer?"
4. Once the user picks a winner, offer:
5. "Edit the chosen variant further?" → stitch-mcp-edit-screens
6. "Convert to code?" → framework conversion workflow
7. "Generate more variants from the winner?" → another generate_variants call

Anti-patterns

• Never generate variants without an existing screen — you need a source design
• Never use projects/ID format for projectId or screenId — both must be numeric
• Never set variantCount above 5 — the API caps at 5