/generate-design

name: stitch::generate-design
description: >-
  Generate new screens from text prompts or images, edit existing screens
  with prompts and design system tokens, and generate design variants using
  Stitch MCP. Includes prompt enhancement pipeline, design mappings, professional
  UI/UX terminology, design tokens and theme system capabilities.
allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"
  - "Write"
  - "web_fetch"

Generate Design

Create new design screens from text descriptions, images, or mockups, edit existing screens with prompts and design system tokens, and generate design variants using Stitch MCP.

> [!NOTE] > Refer to your system prompt for instruction on handling MCP tool prefixes for > all tools mentioned in this skill (e.g., `list_projects`, > `generate_screen_from_text`, `edit_screens`).

🎨 Prompt Enhancement Pipeline

Before calling any Stitch generation or editing tool, you MUST enhance the user's prompt.

1. Analyze Context

• **Project**: Use `list_projects` to find the correct `projectId`. If no

suitable project exists, create one using `create_project`.

• **Design System**: Check if a design system exists for the project via

`list_design_systems`. If one exists, design tokens (colors, fonts, roundness) are already applied at the project level — do NOT include any color, font, or theme instructions in the generation prompt. If none exists, delegate to the **manage-design-system** skill first before generating screens.

2. Refine UI/UX Terminology

Consult [Design Mappings](references/design-mappings.md) to replace vague terms.

• Vague: "Make a nice header"
• Professional: "Sticky navigation bar with glassmorphism effect and centered

logo"

Use [Prompting Keywords](references/prompt-keywords.md) for component names, adjective palettes, color roles, and shape descriptions.

3. Structure the Final Prompt

Format the enhanced prompt for Stitch. Focus exclusively on **layout, content, and structure** — never include colors, fonts, or theme instructions (these are handled by the manage-design-system skill at the project level).

For **new screens**, use this template:

[Overall purpose and user intent of the page]

**PLATFORM:** [Web/Mobile], [Desktop/Mobile]-first

**PAGE STRUCTURE:**
1. **Header:** [Description of navigation and branding]
2. **Hero Section:** [Headline, subtext, and primary CTA]
3. **Primary Content Area:** [Detailed component breakdown]
4. **Footer:** [Links and copyright information]

For **edits**, be specific about what to change:

• **Location**: "Change the [primary button] in the [hero section]..."
• **Visuals**: "...to a darker blue (#004080) and add a subtle shadow."
• **Structure**: "Add a secondary button next to the primary one with the text

'Learn More'."

> [!CAUTION] > Do NOT include hex codes, font names, color palettes, roundness values, or > any design system tokens in a **generation** prompt. These are applied at the > project level by the manage-design-system skill and will conflict if > duplicated. (For **edit** prompts, hex codes are acceptable for precise > color adjustments.)

4. Present AI Insights

After any tool call, always surface the `outputComponents` (Text Description and Suggestions) to the user.

See [examples/enhanced-prompt.md](examples/enhanced-prompt.md) for a full before/after prompt enhancement example.

--------------------------------------------------------------------------------

Steps

Determine the Mode

Decide which flow to use based on the user's request:

• User wants to create from a text description → **Generate from Text** flow
• User provides an image, screenshot, or mockup → **Generate from Image** flow
• User wants to modify an existing screen → **Edit** flow
• User wants layout/color/content variations → **Generate Variants** flow

---

Generate from Text Flow (New Screen)

1. Enhance the User Prompt

Apply the Prompt Enhancement Pipeline above.

2. Identify the Project

Use `list_projects` to find the correct `projectId` if it is not already known.

3. Generate the Screen

Call the `generate_screen_from_text` tool with the enhanced prompt and the `designSystem` ID (if found in Step 1).

{
  "projectId": "...",
  "prompt": "[Your Enhanced Prompt]",
  "designSystem": "assets/...", // Optional: Pass if found in Step 1
  "deviceType": "DESKTOP"  // Options: MOBILE, DESKTOP, TABLET
}

4. Present AI Feedback

Always show the text description and suggestions from `outputComponents` to the user.

5. Download Design Assets

After generation, download the HTML and screenshot urls from `outputComponents` to the `.stitch/designs` directory.

• **Naming**: Use the screen ID or a descriptive slug for the filename.
• **Tools**: Use `curl -o` via `run_command` or similar.
• **Directory**: Ensure `.stitch/designs` exists.

6. Review and Refine

• If the result is not exactly as expected, continue with the **Edit** flow

to make targeted adjustments.

• Do NOT re-generate from scratch unless the fundamental layout is wrong.

---

Generate from Image Flow (Image/Mockup → Design)

Use this flow when the user provides an image, screenshot, or design mockup to recreate in Stitch.

1. Identify the Project

Use `list_projects` to find the correct `projectId`. If no suitable project exists, create one using `create_project`.

2. Upload the Image

Delegate to the **upload-to-stitch** skill to upload the image to the project. This creates a new screen with the image as its content.

3. Refine with Edit

Once uploaded, use `list_screens` to find the newly created `screenId`, then call `edit_screens` with a descriptive prompt to refine the design:

{
  "projectId": "...",
  "selectedScreenIds": ["<uploaded-screen-id>"],
  "prompt": "[Describe what to adjust, enhance, or recreate from this mockup]"
}

> [!TIP] > For best results, describe the intent behind the image rather than j