Stitch Architecture

Stitch Conceptual Model

• Project: Top-level container. One project per landing page engagement. Contains screens and a design system.
• Screen: A single generated UI design. Has associated HTML and a screenshot, both available as download URLs. Edits produce new screen versions; originals are preserved and can be revisited.
• Design System: Project-wide visual tokens (colors, fonts, shapes, spacing). Applies consistently to all screens. Described in semantic language, not CSS.
• Generation is asynchronous: Screen generation can take 1-3 minutes. Do NOT retry a generation call if it seems slow. Use get_screen or list_screens to check completion status.
• Assets are URLs: Both getHtml() and getImage() return download URLs, not inline content. Download the files using whatever tools are available.
• Namespace varies: Stitch MCP tool names may be prefixed differently depending on the server configuration. Always discover the prefix via list_tools at startup.

Font Personality Guide

Stitch supports 28 font enums. Use this guide to select fonts based on the brand personality established during the interview. Always select both a headline font and a body font.

Modern / Clean Sans-Serif

For brands described as: modern, clean, minimal, technical, sharp

Warm / Friendly Sans-Serif

For brands described as: warm, friendly, approachable, inviting

Professional / Corporate

For brands described as: professional, trustworthy, established, reliable

Traditional / Elegant Serif

For brands described as: elegant, premium, refined, classic

Display / Statement (headline only – pair with a neutral body font)

For brands that want a distinctive headline presence:

Recommended Pairings

Color Variant Decision Tree

Stitch design systems accept a colorVariant enum that controls how the palette is generated from the custom color. Use the brand adjectives from the interview to select the right variant.

Default Color Suggestions

When the user has no existing brand colors, suggest based on desired emotion:

Prompt Engineering Patterns

Generation Prompt Template

Select sections based on product type (see Section Taxonomy below).

Prompt Guidelines

Do:

• Describe layout in terms of sections and content purpose
• Mention the mood/feel even though the design system also encodes it (reinforcement helps)
• Specify CTA button text explicitly (e.g., “Start Free Trial”)
• Keep prompts to 6-8 sentences maximum
• Name specific section types (hero, testimonials, features, pricing)

Do not:

• Write CSS, HTML, or code in the prompt
• Reference pixels, padding, margins, or breakpoints
• Ask for animations or interactivity (Stitch generates static HTML)
• List more than 5-6 sections (overloading degrades quality)
• Use vague instructions (“make it nice”) – be specific about structure

Edit Prompt Patterns

Variant Prompt Patterns

Landing Page Section Taxonomy

Standard Sections (in suggested order)

Section Selection by Product Type

Design System Quick Reference

Roundness Values

Design System Creation Sequence

1. Call create_project with the project name as the title
2. Build the DesignSystem object using the translation mappings from the interview
3. Call create_design_system with the project ID
4. Immediately call update_design_system – this is required to render the system; create alone is not sufficient
5. Save the project ID and design system asset ID to .stitch/metadata.json

Applying a Design System to Existing Screens

This is the step that requires careful data handling:

1. Call get_project with the project name to retrieve screenInstances
2. Each screenInstance contains two required fields:
   • id – the instance ID (different from screen ID)
   • sourceScreen – resource name in format projects/{project}/screens/{screen}
3. Build a selectedScreenInstances array containing objects with both id and sourceScreen
4. Call apply_design_system with projectId, assetId (from the design system), and selectedScreenInstances
5. Re-fetch screens after applying to get updated HTML

Common mistake: using the screen ID as the instance ID. They are different values. The instance ID comes from the screenInstances array in the get_project response.