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
- Call
stitch-mcp-list-screens to find all new variant screens
- Call
stitch-mcp-get-screen for each to get screenshots
- Present side by side: "Here are your 3 variants: [screenshots]. Which one do you prefer?"
- 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
1---2name: stitch-mcp-generate-variants3description: Generates design variants of existing Stitch screens using the native variant API. Explore alternative layouts, color schemes, fonts, or content with configurable creativity levels.4---5
6# Stitch MCP — Generate Variants
7
8Generates 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.
9
10## Critical prerequisite
11
12**Only use this skill when the user explicitly mentions "Stitch".**
13
14You 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.
15
16## When to use
17
18- User wants to explore alternative versions of an existing screen
19- After generation, user says "show me some variations" or "try different styles"
20- The orchestrator's Step 5b offers "Generate variants"
21- A/B testing — creating multiple options for stakeholder review
22
23## Call the MCP tool
24
25```json
26{
27 "name": "generate_variants",
28 "arguments": {
29 "projectId": "3780309359108792857",
30 "selectedScreenIds": ["88805abc123def456"],
31 "prompt": "Explore different color schemes while keeping the layout structure",
32 "variantOptions": {
33 "variantCount": 3,
34 "creativeRange": "EXPLORE",
35 "aspects": ["COLOR_SCHEME", "IMAGES"]
36 },
37 "deviceType": "DESKTOP",
38 "modelId": "GEMINI_3_1_PRO"
39 }
40}
41```
42
43## Parameter reference
44
45### `projectId` — numeric ID only, no prefix
46
47```
48✅ "3780309359108792857"
49❌ "projects/3780309359108792857"
50```
51
52### `selectedScreenIds` — array of numeric screen IDs
53
54```
55✅ ["88805abc123def456"]
56❌ ["projects/123/screens/88805abc123def456"]
57```
58
59The source screen(s) to generate variants from.
60
61### `prompt` — optional guidance for variant direction
62
63Provide context about what kind of variations the user wants. The `variantOptions` do the heavy lifting, but the prompt adds nuance.
64
65### `variantOptions` — controls what and how much to vary
66
67| Field | Type | Values | Description |
68|-------|------|--------|-------------|
69| `variantCount` | int | 1–5 | Number of variants to generate |
70| `creativeRange` | enum | `REFINE`, `EXPLORE`, `REIMAGINE` | How much to deviate from the original |
71| `aspects` | array | See below | Which design aspects to vary |
72
73#### `creativeRange` mapping from user language
74
75| User says | → creativeRange | What it does |
76|-----------|----------------|-------------|
77| "subtle changes", "minor tweaks", "polish" | `REFINE` | Small refinements, stays close to original |
78| "alternatives", "different options", "explore" | `EXPLORE` | Meaningful differences while keeping the concept |
79| "radical", "completely different", "reimagine" | `REIMAGINE` | Major departures from the original design |
80
81#### `aspects` — what to vary
82
83| Value | Varies | Keeps stable |
84|-------|--------|-------------|
85| `LAYOUT` | Structure, spacing, component arrangement | Colors, fonts, content |
86| `COLOR_SCHEME` | Colors, gradients, contrast | Layout, fonts, content |
87| `IMAGES` | Photography, illustrations, icons | Layout, colors, text |
88| `TEXT_FONT` | Typography, font choices, sizes | Layout, colors, content |
89| `TEXT_CONTENT` | Copy, labels, placeholder text | Layout, colors, fonts |
90
91You can combine aspects: `["LAYOUT", "COLOR_SCHEME"]` varies both simultaneously.
92
93### `deviceType` — optional
94
95Same enum: `MOBILE`, `DESKTOP`, `TABLET`, `AGNOSTIC`
96
97### `modelId` — optional
98
99| Value | Use when |
100|-------|---------|
101| `GEMINI_3_1_PRO` | **Recommended** — complex layouts, high fidelity |
102| `GEMINI_3_FLASH` | Fast iteration, wireframes, simple changes |
103| `GEMINI_3_PRO` | **Deprecated.** Still works but will be removed. Use `GEMINI_3_1_PRO` instead. |
104
105## Output
106
107Returns new screens added to the project. Each variant appears as a separate screen in `list_screens`.
108
109## After generating variants
110
1111. Call `stitch-mcp-list-screens` to find all new variant screens
1122. Call `stitch-mcp-get-screen` for each to get screenshots
1133. Present side by side: "Here are your 3 variants: [screenshots]. Which one do you prefer?"
1144. Once the user picks a winner, offer:
115 - "Edit the chosen variant further?" → `stitch-mcp-edit-screens`
116 - "Convert to code?" → framework conversion workflow
117 - "Generate more variants from the winner?" → another `generate_variants` call
118
119## Anti-patterns
120
121- **Never generate variants without an existing screen** — you need a source design
122- **Never use `projects/ID` format** for projectId or screenId — both must be numeric
123- **Never set `variantCount` above 5** — the API caps at 5
majiayu000