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:
   • "Edit the chosen variant further?" → stitch-mcp-edit-screens
   • "Convert to code?" → framework conversion workflow
   • "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