# Stitch Documentation

Source collection: https://stitch.withgoogle.com/docs
Extracted: 2026-05-22T08:52:08.247Z

This file contains Markdown converted from the accessible rendered documentation pages discovered at stitch.withgoogle.com/docs. Each page section includes its source URL.

## Pages

- [Start with a prompt. Iterate into a design.](#start-with-a-prompt-iterate-into-a-design-) - https://stitch.withgoogle.com/docs/
- [Everything you need to know to design with Stitch](#everything-you-need-to-know-to-design-with-stitch) - https://stitch.withgoogle.com/docs/learn/overview/
- [Effective Prompting](#effective-prompting) - https://stitch.withgoogle.com/docs/learn/prompting/
- [Device Types](#device-types) - https://stitch.withgoogle.com/docs/learn/device-types/
- [Design Modes](#design-modes) - https://stitch.withgoogle.com/docs/learn/design-modes/
- [Using Variations](#using-variations) - https://stitch.withgoogle.com/docs/learn/variants/
- [Controls & Hotkeys](#controls-hotkeys) - https://stitch.withgoogle.com/docs/learn/controls/
- [Open Source Licenses](#open-source-licenses) - https://stitch.withgoogle.com/docs/learn/licenses/
- [Stitch via MCP](#stitch-via-mcp) - https://stitch.withgoogle.com/docs/mcp/setup/
- [Getting Started](#getting-started) - https://stitch.withgoogle.com/docs/mcp/guide/
- [Reference](#reference) - https://stitch.withgoogle.com/docs/mcp/reference/
- [Build your first design](#build-your-first-design) - https://stitch.withgoogle.com/docs/sdk/tutorial/
- [Use with AI SDK](#use-with-ai-sdk) - https://stitch.withgoogle.com/docs/sdk/ai-sdk/
- [Agent-driven workflows](#agent-driven-workflows) - https://stitch.withgoogle.com/docs/sdk/agent-workflows/
- [How to edit a screen](#how-to-edit-a-screen) - https://stitch.withgoogle.com/docs/sdk/edit-screen/
- [How to generate variants](#how-to-generate-variants) - https://stitch.withgoogle.com/docs/sdk/generate-variants/
- [How to download artifacts](#how-to-download-artifacts) - https://stitch.withgoogle.com/docs/sdk/download-artifacts/
- [How to extract themes](#how-to-extract-themes) - https://stitch.withgoogle.com/docs/sdk/extract-themes/
- [How to manage design systems](#how-to-manage-design-systems) - https://stitch.withgoogle.com/docs/sdk/design-systems/
- [How to upload files](#how-to-upload-files) - https://stitch.withgoogle.com/docs/sdk/upload-image/
- [Reference](#reference) - https://stitch.withgoogle.com/docs/sdk/reference/
- [Architecture](#architecture) - https://stitch.withgoogle.com/docs/sdk/architecture/
- [What is DESIGN.md?](#what-is-design-md-) - https://stitch.withgoogle.com/docs/design-md/overview/
- [Import from your codebase](#import-from-your-codebase) - https://stitch.withgoogle.com/docs/design-md/get-instructions/
- [The DESIGN.md specification](#the-design-md-specification) - https://stitch.withgoogle.com/docs/design-md/specification/
- [View, edit, and export](#view-edit-and-export) - https://stitch.withgoogle.com/docs/design-md/usage/
- [Validate with the CLI](#validate-with-the-cli) - https://stitch.withgoogle.com/docs/design-md/cli/
- [Linting rules](#linting-rules) - https://stitch.withgoogle.com/docs/design-md/linting-rules/
- [Get started with Agent Skills](#get-started-with-agent-skills) - https://stitch.withgoogle.com/docs/skills/get-started/
- [Code to Design roundtrip](#code-to-design-roundtrip) - https://stitch.withgoogle.com/docs/skills/roundtrip/
- [Build in a loop](#build-in-a-loop) - https://stitch.withgoogle.com/docs/skills/build-in-a-loop/
- [Generate walkthrough videos](#generate-walkthrough-videos) - https://stitch.withgoogle.com/docs/skills/walkthrough-videos/
- [Taste](#taste) - https://stitch.withgoogle.com/docs/skills/taste/
- [Skill reference](#skill-reference) - https://stitch.withgoogle.com/docs/skills/reference/

## Start with a prompt. Iterate into a design.

Source: https://stitch.withgoogle.com/docs/

Stitch transforms your ideas into designs through AI-powered iteration. Whether you’re building web apps, mobile experiences, or prototypes, start here.

### Try it yourself

PROMPT IDEA A landing page for a running podcast named “The Pacing Project”. THEME Modern, edgy, high contrast. Use black and white with hard angles. CONTENT Hero section with “Stories and lessons about racing and proper pacing” and links to podcast platforms.

### What you’ll find here

#### Learn Stitch

Master effective prompting, design modes, device types, and iteration techniques. Everything you need to create with Stitch.

Prompting Device Types Design Modes Controls

#### MCP Integration

Connect Stitch to AI agents via Model Context Protocol. Automate design workflows and integrate with your development pipeline.

Setup Authentication API Reference
## Everything you need to know to design with Stitch

Source: https://stitch.withgoogle.com/docs/learn/overview/

A subtly opinionated walkthrough

Stitch

Welcome to Stitch. Today you’re learning to start with design and lean into ideation. The key is not to overthink it.

### The key to better prompts and better designs

Section titled “The key to better prompts and better designs”

**Ideate.** The hardest part is getting past the blank page. The best way to create better designs is through iteration, not perfect initial prompts. Let’s follow a simple formula.

### Starting prompt examples

Section titled “Starting prompt examples”

A good recipe for an initial prompt follows this formula:

PROMPT IDEA What it is. THEME The idea for the core theme. CONTENT The content. IMAGE Optional reference image.

Your first prompt doesn’t need to be perfect. Describe the specific content you want on the page and the general vibe. Don’t worry about specific font selections or hex codes yet. Stitch will help you with this ideation process. We need to get past the blank prompt and into creativity.

Here’s an example.

PROMPT IDEA A landing page for a running podcast named “The Pacing Project”. THEME Modern, edgy, and high contrast. Use black and white with hard angles. CONTENT A hero section with the headline “Stories and lessons about racing and proper pacing” and links to podcast platforms.

#### Selecting the device type

Section titled “Selecting the device type”

App or Web? Just pick one. Don’t worry too much about the device type at first. Take a quick gut check on which format you think is most suitable at first. Stitch has plenty of ways to convert one mode to another as you iterate.

Now hit generate.

### Navigating and controlling the canvas

Section titled “Navigating and controlling the canvas”

Let’s get comfortable with the canvas.

#### Hotkeys

Section titled “Hotkeys”

Think of your two main interactions with the canvas in two modes: Selection and Navigation. The `V` key toggles the `Select` tool, while the `H` key toggles the `Pan` tool for quick drag-based navigation. Because the canvas is vast, it can be easy to lose track of where you are. If that ever happens, hit `⌘←` / `Ctrl+←` to navigate to the nearest screen. You can cycle through screens using `⌘→` / `Ctrl+→` and `⌘←` / `Ctrl+←`.

For a whole list of shortcuts hit `?` to see all the hotkeys available.

### Starting the ideation process

Section titled “Starting the ideation process”

The real ideation process begins once the design appears. Odds are you’ll find several aspects of the initial generation that you like and others you dislike. Stitch has tools to tweak the dislikes and lean further into what the generation got right.

### Make one major change at a time

Section titled “Make one major change at a time”

Pick one thing you want to change, just one. Select the Screen you want to change, click Edit, Add to Chat, and write a prompt. **Be specific about what to change and how to change it.** For example, if the pricing table needs to emphasize the best value tier:

Target specific component Specific visual instruction UI/UX Keyword

Update the pricing table to emphasize the middle card. Increase its container height and add a drop shadow. Reduce the scale of the sibling cards to create a clear visual hierarchy.

You can keep this formula going: find one change, write a clear and targeted prompt using UI/UX keywords, and generate.

#### Edit Theme

Section titled “Edit Theme”

If your change is within the core theme of the design, Stitch has a specific feature to work faster and target those specific changes.

Select the Screen, click Generate and then Edit Theme. Here you can change core aspects of the theme such as the Light or Dark mode appearance, accent color, the corner radius of components, and font.

#### Design to Prototype

Section titled “Design to Prototype”

Once you have your design in a more preferred state, let’s take it for a bit of a test drive. Click the screen, click Generate, and then Prototype. This creates a scrollable and interactive prototype that helps you get a feel for what the design is like in action.

Here you can check interactive states that aren’t visible in a static design. Check out the hover styles for components like buttons, links, and cards. Write a message in a textbox and see if it’s too small or big for the typical amount of text expected. Think about how this prototype is going to be used in the wild. From there, continue to ideate based on these new interactive factors.

#### Download code and images

Section titled “Download code and images”

When you’re ready to take your design and bring it to life, it’s time to download the code and images. Stitch creates designs for both image and HTML code outputs.

Click a screen or drag and select all the screens you want to export. Click download. This will download a zip file to your device and from here you can integrate it into many different tools to make it real.

#### HTML converts to many formats

Section titled “HTML converts to many formats”

It’s important to understand that the HTML code serves as a base for translation. LLMs excel at taking HTML combined with a reference image and converting it to other component formats such as React, Angular, and Vue, or non-web platforms such as Jetpack Compose, Flutter, and SwiftUI.

To learn about generating specific component formats, check out the Build Strategies section.

### Keep ideating. Keep creating.

Section titled “Keep ideating. Keep creating.”

The key to better results is effective prompting and ideation. Keep ideating until you find the design that feels right.
## Effective Prompting

Source: https://stitch.withgoogle.com/docs/learn/prompting/

Effective practices to iterate towards effective results

Stitch

This guide provides instructions for crafting effective prompts to design and refine your app with Stitch.

### Starting Your Project

Section titled “Starting Your Project”

Choose to start with a broad concept or specific details. For complex apps, start high-level and then drill down on details screen by screen.

#### High-Level vs. Detailed Prompts

Section titled “High-Level vs. Detailed Prompts”

Start with a general idea.

PROMPT HIGH-LEVEL An app for marathon runners.

Describe core functionalities for a better starting point.

PROMPT DETAILED An app for marathon runners to engage with a community, find partners, get training advice, and find races near them.

#### Set the Vibe with Adjectives

Section titled “Set the Vibe with Adjectives”

Use adjectives to define the app’s feel (influences colors, fonts, imagery).

PROMPT ADJECTIVES A vibrant and encouraging fitness tracking app.

PROMPT ADJECTIVES A minimalist and focused app for meditation.

### Refining Your App by Iterating Screen by Screen

Section titled “Refining Your App by Iterating Screen by Screen”

#### Refine with Specific, Incremental Changes

Section titled “Refine with Specific, Incremental Changes”

Stitch performs best with clear, specific instructions. Focus on one screen/component and make one or two adjustments per prompt.

- **Be Specific:** Tell Stitch _what_ to change and _how_.

Target specific element Target specific screen Specific visual change Reference brand theme

Change the primary call-to-action button on the login screen to be larger and use the brand’s primary blue color.

- **Focus on Specific Screens/Features:**

#### Describe Desired Imagery

Section titled “Describe Desired Imagery”

Guide the style or content of images.

- **Specific Image Style:** “Music player page for ‘Suburban Legends.’ Album art is a macro, zoomed-in photo of ocean water. Page background/imagery should reflect this.”

### Controlling App Theme

Section titled “Controlling App Theme”

#### Colors

Section titled “Colors”

Request specific colors or describe a mood for the color palette.

- **Specific Color Prompt:** `"Change primary color to forest green."`
- **Mood-Based Color Prompt:** `"Update theme to a warm, inviting color palette."`

#### Fonts & Borders

Section titled “Fonts & Borders”

Modify typography and element styling (buttons, containers).

- **Font Style Prompt:** `"Use a playful sans-serif font."` OR `"Change headings to a serif font."`
- **Border/Button Style Prompt:** `"Make all buttons have fully rounded corners."` OR `"Give input fields a 2px solid black border."`

PROMPT COMBINED THEME Book discovery app: serif font for text, light green brand color for accents.

### How to Modify Images in Your Design

Section titled “How to Modify Images in Your Design”

#### Be Specific When Changing Images

Section titled “Be Specific When Changing Images”

Clearly identify the image to modify. Use descriptive terms from the app’s content.

- **Targeting General Images:** `"Change background of [all] [product] images on [landing page] to light taupe."`
- **Targeting a Specific Image:**

Define location Describe content to target Instruction

On ‘Team’ page, image of ‘Dr. Carter (Lead Dentist)’: update her lab coat to black.

#### Coordinate Images with Theme Changes

Section titled “Coordinate Images with Theme Changes”

If updating theme colors, specify if images should also reflect these changes.

- **Prompt:** `"Update theme to light orange. Ensure all images and illustrative icons match this new color scheme."`

### Changing the Language of Your App’s Text

Section titled “Changing the Language of Your App’s Text”

Use the following prompt:

- **Prompt:** `"Switch all product copy and button text to Spanish."`

### Pro Tips for Stitch

Section titled “Pro Tips for Stitch”

- **Be Clear & Concise:** Avoid ambiguity.
- **Iterate & Experiment:** Refine designs with further prompts.
- **One Major Change at a Time:** Easier to see impact and adjust.
- **Use UI/UX Keywords:** (e.g., “navigation bar,” “call-to-action button,” “card layout”).
- **Reference Elements Specifically:** (e.g., “primary button on sign-up form,” “image in hero section”).
- **Review & Refine:** If a change isn’t right, rephrase or be more targeted.
## Device Types

Source: https://stitch.withgoogle.com/docs/learn/device-types/

How to choose your canvas and translate designs between App and Web.

Stitch

When you start a project, Stitch asks you to make a choice: **App** or **Web**.

This isn’t just about screen size; it is about defining your **Primary Design Surface**. The device type dictates how Stitch interprets layout, navigation, and hierarchy.

### Layouts rely on context

Section titled “Layouts rely on context”

- **App Mode:** Optimizes for vertical scrolling, bottom-aligned navigation (thumb zones), and stacked content.
- **Web Mode:** Optimizes for horizontal sprawl, top-aligned navigation, and multi-column grids.

A sceen designed in **App Mode** will look like a large app when viewed on a desktop. Conversely, a **Web Mode** design squeezed onto phone screen often loses critical details and UI components expected on native mobile apps.

### Designing between modes

Section titled “Designing between modes”

The best way to move from one platform to another is not to resize, but to **translate**.

Stitch

If you have a mobile app design and want a web version, draft a prompt that describes what needs to change to optimize the design for that device type. First, use an existing design as a **Reference Image** for a new project or an update for a new screen. A new screen can be tricky in the way Stitch currently works but we’ll detail some ways to help smooth that over below.

#### Phase 1: The App Design

Section titled “Phase 1: The App Design”

Let’s look at an example for this _Raffinato_ app. _Raffinato means refined in Italian._ This project started in **App Mode** because the mobile ordering flow was most important.

PROMPT IDEA An ordering app for a local quality obsessed espresso focused coffee shop named Raffinato. THEME A light, high contrast theme with a modern and minimalistic feel. CONTENT Prefer a variable sized grid layout: 1 column on one row, followed by 2 columns on the next. Break up the grid into sections with labels categorizing the types of drinks in each section. Provide a mobile ordering layout for common espresso drinks with placeholder values for prices. Focus on the typographic balance for menu items placing the visual emphasis on the item name and less emphasis on details such as size in ounces, and price. NAVIGATION Provide navigation to easily switch screens between main grid, details, and the cart.

This generates a tight, vertical interface perfect for a phone.

#### Phase 2: Translating to Web

Section titled “Phase 2: Translating to Web”

To move to Web, either create a **New Project** set to **Web Mode** or provide an update prompt in the existing project, and use a screen’s downloaded image as a reference.

Your goal now is to tell Stitch how to utilize the larger screen real estate. Focus on core UI/UX aspects that need to change, such as the **Navigation**, the **Hero Section**, and the **Grid Density**.

Here is how the prompt handles the device type translation:

PROMPT NAVIGATION Consolidate the bottom tab bar and top menu into a single, horizontal navigation bar at the top of the screen with links for Home, Menu, Rewards, and Account. HERO Transform ‘The Daily Focus’ card into a split-layout hero section. Place the Cortado text and button on the left, and expand the image to cover the right side. GRID LAYOUT Update the product lists from a 2-column mobile layout to a 4-column desktop grid. Maintain the light cream card background and minimalist vibe.

By explicitly telling Stitch to move the navigation to the top and split the hero content, the prompt focuses on retaining the _feel_ of the brand and optimizing the design for the utility of the device type.

### Switching Device Types in the same project

Section titled “Switching Device Types in the same project”

When you create a Stitch project with a specific device type it will continue to generate screens of that device type’s size. You can give Stitch a prompt to convert to another device type within the same project, but it requires manual finessing.

If you generate a Web prompt inside an App project, Stitch will generate the web content inside an app frame.

1. **Generate** the design.
2. Use **Preview > Device Type** to switch the view to the intended target (e.g., Desktop).
3. **Resize** the frame manually if elements feel cut off.

#### Pro Tip: The Hidden Content

Section titled “Pro Tip: The Hidden Content”

When switching from App to Web within a project, try increasing the vertical height of the design frame significantly. Stitch often generates the “rest” of the website logic, but hides it because the original App frame was too short. Dragging the frame handle down can reveal the rest of your layout.
## Design Modes

Source: https://stitch.withgoogle.com/docs/learn/design-modes/

Select the right engine for your creative workflow.

Stitch

Stitch isn’t just one AI model; it is a suite of design engines.

In the generation settings, you will find the **Design Mode** selector. Think of these not just as different “versions,” but as different specialized tools. Some are built for speed, some for raw creativity, and others for deep logic and reasoning.

### Thinking with 3 Pro

Section titled “Thinking with 3 Pro”

**Best for:** Complex logic, deep reasoning, and your “Production” candidate.

This is the heavy lifter. Powered by Gemini 3 Pro, this mode prioritizes **reasoning over speed**. It takes a little longer to generate because it is “thinking” through the implications of your prompt—how the navigation should flow, what the hierarchy implies, and how the colors interact.

If you are building a complex dashboard or a nuance-heavy landing page, this is where you should be. The wait is worth the pixel-perfect logic it returns.

### Redesign (Nano Banana Pro)

Section titled “Redesign (Nano Banana Pro)”

**Best for:** Modernizing old apps, stylistic experiments, and “vibes” based workflows.

The Redesign agent is your best friend when it comes to Vibe Design. It is incredible for taking a dated interface and applying a specific design aesthetic.

#### The Style Word Bank

Section titled “The Style Word Bank”

The Redesign agent thrives on specific art-direction keywords. Instead of saying “make it look cool,” try combining terms from these categories to define a distinct visual language.

**Layout & Structure**

- **Bento Grid:** Modular, boxy, card-based layouts. Distinct compartments that organize content into a cohesive, grid-like hierarchy.
- **Editorial:** High-fashion magazine feel. Large serif headings, generous whitespace, asymmetrical image placement.
- **Swiss Style:** Objectively clear. Heavy reliance on grid systems, sans-serif typography (Helvetica-ish), and flush-left text.
- **Split-Screen:** Distinct vertical division, often pairing a solid color block with full-bleed imagery.

**Texture & Depth**

- **Glassmorphism:** Translucency, background blur (backdrop-filter), and subtle white borders. “Frosted glass.”
- **Claymorphism:** Soft, inflated 3D shapes with inner shadows. Friendly, approachable, and tactile.
- **Skeuomorphic:** Realistic textures (leather, paper, metal) and controls that look like physical switches.
- **Grainy/Noise:** Adding film grain or texture overlays to gradients to reduce the “digital” shine and add warmth.

**Atmosphere & Era**

- **Brutalist:** Raw, unpolished, default system fonts, high contrast, hard edges. “Ugly-cool.”
- **Cyberpunk:** Dark mode, neon accents (cyan/magenta), glitch effects, tech-heavy interfaces.
- **Y2K:** Late 90s/Early 2000s optimism. Chrome textures, bubble letters, bright blues and pinks, pill-shaped buttons.
- **Retro-Futurism:** 80s Synthwave. Sunsets, wireframe grids, VHS aesthetics, glowing lines.

**Color & Contrast**

- **Duotone:** The entire UI is composed of two contrasting colors (and their shades).
- **Monochromatic:** Using a single base hue (e.g., “Shades of Electric Blue”) for a cohesive, branded look.
- **Pastel Goth:** Soft, milky pastel colors paired with stark black typography and borders.
- **Dark Mode OLED:** True black backgrounds (#000000) rather than dark grey, optimized for high contrast and pop.

PROMPT ACTION Redesign this dashboard. STYLE Use a modern Bento Grid layout. DETAILS Dark mode background. Use the Inter font for the headers.

### 2.5 Pro

Section titled “2.5 Pro”

**Best for:** High-fidelity HTML and A/B comparisons.

Gemini 2.5 Pro produces exceptionally high-quality code and design fidelity. It is often useful to generate a prompt in **Thinking with 3 Pro** and then run the exact same prompt in **2.5 Pro** to see two different high-level interpretations of your idea.

### Fast

Section titled “Fast”

**Best for:** Rapid wireframing and Figma exports.

The Rapid mode is optimized for compatibility if your primary goal is to export your initial sketches directly to **Figma** for manual refinement.
## Using Variations

Source: https://stitch.withgoogle.com/docs/learn/variants/

Variations are one of the most powerful and fun to use features in Stitch. They allow you to generate multiple design options at once, breaking you out of a linear workflow and showing you possibilities you might not have imagined.

You are really good at exploring multiple versions of a design and comparing them, so it seems a waste to only generate one option at a time!

Currently, you can generate anywhere from one to five different options at a time. This feature is your sandbox for “What if?” moments.

### When to use variations

Section titled “When to use variations”

While the standard Chat is great for specific, granular updates (like changing a button color), Variations are best used for:

- **Getting Unstuck:** If you don’t know what to change, but you know the current design isn’t working.
- **Exploration:** When you want to see three different layout concepts for the same content.
- **Pivoting:** When you want to change the entire vibe (e.g., from “Corporate Blue” to “Neon Cyberpunk”) in one go.

### Controlling the Creative Range

Section titled “Controlling the Creative Range”

Each time you generate variations, you specify the **Creative Range** to give Stitch. This tells the AI how far to stray from your current design:

- **Refined (Low Range):** Keeps the structure intact but plays with fonts, subtle spacing, and colors. Use this for polish.
- **Creative (High Range):** Absolute “let’s see what’s possible” freedom. This allows Stitch to completely restructure the layout, swap imagery, and overhaul the theme.

### Writing prompts for Variations

Section titled “Writing prompts for Variations”

Unlike the standard editing process where we recommend making “one major change at a time,” Variations are the place to make **big swings**. You can combine theme changes and layout changes into a single prompt because you are generating multiple options to choose from.

Sets the vibe Specific color request Target specific screen Clear, specific instruction

Update the app theme to a luxury aesthetic using a strict black and white palette. On the Episode List screen, change the layout to a minimalist grid.

**Pro Tip:** Even when asking for broad changes, be specific about the _direction_. Instead of saying “Make it different,” say “Make it minimalist” or “Make it bold.”

### Iterating on a winner

Section titled “Iterating on a winner”

The power of variations doesn’t stop after the first click. Once Stitch presents you with five options, you might find that Option 3 has the perfect layout, but Option 5 has the better color scheme.

1. **Pick the best base:** Select the variation that is closest to your vision.
2. **Vary the variation:** You can run variations _on top_ of a variation. Select your winner, lower the **Creative Range** to “Refined,” and ask Stitch to bring in the color scheme you liked from the other option.
## Controls & Hotkeys

Source: https://stitch.withgoogle.com/docs/learn/controls/

Master the canvas with keyboard shortcuts and powerful navigation tools.

### Controls & Hotkeys

Section titled “Controls & Hotkeys”

Stitch is designed for speed. The more comfortable you get with keyboard shortcuts and canvas tools, the faster you’ll move from concept to polished design.

### Quick Access to Shortcuts

Section titled “Quick Access to Shortcuts”

Press **?** at any time to bring up the complete list of keyboard shortcuts. This modal shows every available shortcut organized by category, with platform-specific modifiers displayed correctly (⌘ on Mac, Ctrl on Windows/Linux).

**Pro Tip:** The shortcuts modal is your reference guide. If you forget a hotkey mid-workflow, tap **?** to quickly look it up without breaking your flow.

### Core Keyboard Shortcuts

Section titled “Core Keyboard Shortcuts”

These are the shortcuts you’ll use most often. They’re designed to keep your hands on the keyboard and your focus on the canvas.

#### Edit Actions

Section titled “Edit Actions”

- **Undo**: `⌘Z` / `Ctrl+Z`
- **Redo**: `⌘⇧Z` / `Ctrl+Shift+Z`
- **Copy**: `⌘C` / `Ctrl+C`
- **Paste**: `⌘V` / `Ctrl+V`
- **Duplicate**: `⌘D` / `Ctrl+D` — Quickly clone selected screens
- **Delete**: `Backspace` or `Delete`
- **Select All**: `⌘A` / `Ctrl+A`

#### Canvas Tools

Section titled “Canvas Tools”

These shortcuts let you switch between different canvas interaction modes:

- **Select Tool**: `V` — The default tool for selecting and moving screens
- **Pan Tool**: `H` — Drag to navigate around the canvas
- **Zoom Tool (hold)**: `Z` — Click to zoom in, Alt+click to zoom out, or drag to zoom to a specific area

#### View Controls

Section titled “View Controls”

- **Zoom In**: `+` or `=` or `⌘=` / `Ctrl+=`
- **Zoom Out**: `-` or `⌘-` / `Ctrl+-`
- **Fit to View**: `0` or `⌘1` / `Ctrl+1` — Zoom to fit all content

#### Project Actions

Section titled “Project Actions”

- **Save**: `⌘S` / `Ctrl+S`
- **Download Selected Screen(s)**: `⇧D` / `Shift+D`

### Command Palette (⌘K)

Section titled “Command Palette (⌘K)”

Press **⌘K** (Mac) or **Ctrl+K** (Windows/Linux) to open the Command Palette. This is your universal search for all available actions in Stitch.

The Command Palette shows every command that’s currently available, filtered by context:

- **Active commands** appear first based on your current selection
- Type to filter the list instantly
- Use arrow keys to navigate, Enter to execute
- Commands show their keyboard shortcuts on the right

**Why use the Command Palette?**

- Discover features you might not know exist
- Execute actions without reaching for the mouse
- See what’s possible in your current context

**Pro Tip:** If you know roughly what you want to do but can’t remember the exact menu location, **⌘K** is the fastest way to find it. Type a few letters and the command you need will surface.

### Navigating the Canvas

Section titled “Navigating the Canvas”

Stitch projects can grow large quickly, with dozens of screens spread across the canvas. These shortcuts help you move efficiently.

#### Screen Navigation

Section titled “Screen Navigation”

- **Next Screen**: `⌘→` / `Ctrl+→` — Jump to the next screen in reading order
- **Previous Screen**: `⌘←` / `Ctrl+←` — Jump to the previous screen

When you navigate between screens using these shortcuts, Stitch automatically:

1. Selects the target screen
2. Zooms to fit that screen in view
3. Centers it for optimal visibility

**Reading Order:** Screens are ordered left-to-right, top-to-bottom—the same way you’d read a page. This makes navigation predictable even in complex projects.

#### Lost on the Canvas?

Section titled “Lost on the Canvas?”

If you ever lose your bearings, press `⌘←` / `Ctrl+←` to snap to the nearest screen. Press `0` or `⌘1` / `Ctrl+1` to zoom out and see your entire project.

### Bottom Toolbar: Select, Pan, Zoom

Section titled “Bottom Toolbar: Select, Pan, Zoom”

The bottom toolbar shows three canvas tools. Each tool changes how you interact with the canvas.

#### Tool Modes

Section titled “Tool Modes”

**Select Mode (`V`)**

- Click to select screens
- Drag to move screens
- Click and drag on empty canvas to create a selection rectangle
- This is the default mode—you’ll spend most of your time here

**Pan Mode (`H`)**

- Click and drag anywhere to move around the canvas
- Useful for navigating large projects
- No risk of accidentally selecting or moving screens

**Zoom Mode (`Z`)**

- **Click** to zoom in (centered on click position)
- **Alt+Click** to zoom out
- **Click and drag** to draw a rectangle—Stitch zooms to fit that area exactly
- Press **Escape** to cancel an in-progress zoom selection

#### Quick Access: Hold to Activate

Section titled “Quick Access: Hold to Activate”

You don’t need to permanently switch tools for quick actions. Stitch supports **temporary mode switching** for faster workflows:

**Hold Space for Quick Pan**

- In any mode, hold **Space** to temporarily switch to pan
- Drag to reposition the canvas
- Release **Space** to return to your previous tool

**Hold Z for Quick Zoom**

- Hold **Z** to temporarily switch to zoom mode
- Perform your zoom action (click, Alt+click, or drag)
- Release **Z** to return to your previous tool

**Tap vs Hold**

- **Tap** a key (`V`, `H`, or `Z`) to switch to that tool permanently
- **Hold** a key (`Space` or `Z`) to activate temporarily—release to go back

**Why this matters:** You can stay in Select mode for your main workflow, hold Space to quickly reposition the canvas, then release to keep selecting and editing. No extra clicks, no mode confusion.

#### Visual Feedback

Section titled “Visual Feedback”

The active tool is always highlighted in the bottom toolbar, even during temporary mode switches. Your cursor also changes to match the current mode:

- **Arrow** for Select
- **Hand** for Pan (open hand when idle, closed fist when dragging)
- **Magnifying glass** for Zoom (+ for zoom in, - for zoom out with Alt held)

### Putting It All Together

Section titled “Putting It All Together”

Here’s a typical workflow that combines these controls:

1. Press **⌘K** to open the Command Palette and generate a new screen
2. Press **⌘→** to navigate to the new screen (auto-zoom and select)
3. Use **V** to enter Select mode and click the screen
4. Hold **Space** to pan and position the screen perfectly
5. Tap **Z** and drag a rectangle around a specific component to zoom in
6. Press **⌘D** to duplicate the screen
7. Press **?** if you forget any shortcut along the way

The goal is to keep you moving fast, staying in flow, and getting to great designs faster.

### Advanced Tip: Combine Shortcuts

Section titled “Advanced Tip: Combine Shortcuts”

Many shortcuts work together:

- Select multiple screens, then press **⇧D** to download them all at once
- Hold **Space** while in Zoom mode to temporarily pan without switching tools
- Use **⌘A** to select all screens, then **⌘D** to duplicate your entire project layout

Speed comes from muscle memory. The more you use these shortcuts, the less you’ll think about them—and the more you’ll think about your design.
## Open Source Licenses

Source: https://stitch.withgoogle.com/docs/learn/licenses/

Open source licenses attribution for Stitch.

Stitch is built with open source software. You can view the full list of open source licenses here:

View Full Open Source Licenses File
## Stitch via MCP

Source: https://stitch.withgoogle.com/docs/mcp/setup/

Connect IDEs and CLIs to Stitch using the Model Context Protocol.

The Stitch Model Context Protocol (MCP) server allows your favorite AI tools like Cursor, Antigravity, or the Gemini CLI to directly interact with your Stitch projects.

### Understanding Remote MCP

Section titled “Understanding Remote MCP”

Most MCP servers you use are **Local**. They read files on your hard drive or run scripts on your machine. Stitch is a **Remote** MCP server. It lives in the cloud.

Because it is remote, it requires a secure “handshake” to ensure that the AI agent acting on your behalf actually has permission to modify your designs.

### API Keys vs OAuth

Section titled “API Keys vs OAuth”

The Stitch MCP server supports two authentication methods:

1. **API Keys:** Persistent keys generated in the [Stitch Settings page](https://app-companion-430619.appspot.com/settings).
2. **OAuth:** A browser-based authentication flow required by specific AI clients that do not support manual key entry, or for environments where storing persistent secrets on disk is restricted.

#### When to use which

Section titled “When to use which”

In most cases, API Keys are the easiest approach. They are the fastest way to get your tool connected. However, OAuth is worth the extra minute of setup in specific situations.

| Scenario | Use API Keys if… | Use OAuth if… |
| --- | --- | --- |
| Client Support | Your tool (e.g., Cursor, Antigravity, or the Gemini CLI) accepts an API key in a config file or environment variable. | Your tool (e.g., web-based tools) requires a “Sign In” flow and doesn’t provide a way to manually input a key. |
| Storage Policy | You are on a private machine where saving a secret key in a local .json or .env file is standard practice. | You are in a “Zero-Trust” or ephemeral environment where saving persistent secrets to the hard drive is blocked or risky. |
| Revocation | You are comfortable manually deleting a key from the Stitch Settings page and then finding/removing it from your local files. | You want the ability to “Log Out” and instantly invalidate the tool’s access via the Stitch Settings page without hunting for local files. |
| Session Logic | You want a connection that stays active indefinitely until you manually change it. | You prefer a session-based connection that can be set to expire or require a re-approval after a period of inactivity. |

### API Key Setup

Section titled “API Key Setup”

1. Go to your [Stitch Settings page](https://app-companion-430619.appspot.com/settings).
2. Scroll to the API Keys section
3. Click on “Create API Key” to generate a new API key.
4. Copy the API key and save it in a secure location.

[Stitch](https://app-companion-430619.appspot.com/settings)

### Storing API Keys

Section titled “Storing API Keys”

Never store your API key in a place where it can be exposed to the public. Never commit your API key to a public repository. Don’t include your API key in client-side code that can be viewed by others.

### MCP Client Setup

Section titled “MCP Client Setup”

#### Gemini CLI

Section titled “Gemini CLI”

Install the [Stitch extension](https://github.com/gemini-cli-extensions/stitch) for the Gemini CLI.

```
gemini extensions install https://github.com/gemini-cli-extensions/stitch
```

#### Cursor

Section titled “Cursor”

Create a `.cursor/mcp.json` file with the following entry:

```
{
  "mcpServers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}
```

#### Antigravity

Section titled “Antigravity”

In the Agent Panel, click the three dots in the top right and select **MCP Servers**. Click, **Manage MCP Servers**. Select “View raw config” and add the following entry:

```
{
  "mcpServers": {
    "stitch": {
      "serverUrl": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}
```

#### VSCode

Section titled “VSCode”

Open the Command Palette (Cmd+Shift+P) and type “MCP: Add Server”. Select “Add MCP Server”. Select **HTTP** to add a remote MCP server. Enter the Stitch MCP URL, `https://stitch.googleapis.com/mcp`. Set the name to “stitch” and confirm.

Then modify the `mcp.json` file to add the API key:

```
{
  "servers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "type": "http",
      "headers": {
        "Accept": "application/json",
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}
```

#### Claude Code

Section titled “Claude Code”

Use the `claude mcp` command to authenticate and add the following entry:

```
claude mcp add stitch --transport http https://stitch.googleapis.com/mcp --header "X-Goog-Api-Key: api-key" -s user
```

### OAuth Setup

Section titled “OAuth Setup”

We need to generate two secrets to allow your MCP Client to talk to Stitch:

1. **Project ID:** The container for your work.
2. **Access Token:** The short lived key for to verify authentication for the project.

#### 1. Install the Google Cloud SDK

Section titled “1. Install the Google Cloud SDK”

Stitch relies on the `gcloud` CLI for secure authentication. If you don’t have it, you can install it globally through this quickstart, or you can install it as a standalone like the instructions below.

##### Standalone

Section titled “Standalone”

```
# Download and install (simplified for standard environments)
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# Set local configuration to avoid prompts
export CLOUDSDK_CORE_DISABLE_PROMPTS=1
```

##### Homebrew

Section titled “Homebrew”

```
brew install --cask google-cloud-sdk
```

#### 2. Double-Layer Authentication

Section titled “2. Double-Layer Authentication”

You need to log in twice. Once as **You** (the user), and once as the **Application** (your local code/MCP client).

```
# 1. User Login (Opens Browser)
gcloud auth login

# 2. Application Default Credentials (ADC) Login
# This allows the MCP server to "impersonate" you securely.
gcloud auth application-default login
```

#### 3. Configure the Project & Permissions

Section titled “3. Configure the Project & Permissions”

Select your working project and enable the Stitch API. You must also grant your user permission to consume services.

```
# Replace [YOUR_PROJECT_ID] with your actual Google Cloud Project ID
PROJECT_ID="[YOUR_PROJECT_ID]"

gcloud config set project "$PROJECT_ID"

# Enable the Stitch API
gcloud beta services mcp enable stitch.googleapis.com --project="$PROJECT_ID"

# Grant Service Usage Consumer role
USER_EMAIL=$(gcloud config get-value account)
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="user:$USER_EMAIL" \
    --role="roles/serviceusage.serviceUsageConsumer" \
    --condition=None
```

#### 4. Generate the Secrets (.env)

Section titled “4. Generate the Secrets (.env)”

Finally, we generate the Access Token and save it to a `.env` file.

> This overwrites any existing `.env` file

```
# Print the token
TOKEN=$(gcloud auth application-default print-access-token)

# Note: This overwrites any existing .env file
echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" > .env
echo "STITCH_ACCESS_TOKEN=$TOKEN" >> .env

echo "Secrets generated in .env"
```

#### 5. Keeping it Fresh

Section titled “5. Keeping it Fresh”

**Note:** Access Tokens are temporary (usually lasting 1 hour). When your MCP client stops responding or says “Unauthenticated,” you need to:

1. Re-run the commands in **Step 4** to update your `.env` file
2. Copy the new `STITCH_ACCESS_TOKEN` value from `.env` into your MCP client config file

Most MCP clients don’t automatically read from `.env` files, so you’ll need to manually update the token in your config file each time it expires.

### Setting up your MCP Client

Section titled “Setting up your MCP Client”

Copy the values from your `.env` file into your MCP client configuration. Replace the placeholders below with the actual values from your `.env` file:

- `<YOUR_PROJECT_ID>` → Value of `GOOGLE_CLOUD_PROJECT` from `.env`
- `<YOUR_ACCESS_TOKEN>` → Value of `STITCH_ACCESS_TOKEN` from `.env`

> [!IMPORTANT] You will need to manually update the `Authorization` header in your config file every hour when the access token expires. See **Step 5** above for the refresh workflow.

#### Cursor

Section titled “Cursor”

Create a `.cursor/mcp.json` file with the following entry:

```
{
  "mcpServers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ACCESS_TOKEN>",
        "X-Goog-User-Project": "<YOUR_PROJECT_ID>"
      }
    }
  }
}
```

#### Antigravity

Section titled “Antigravity”

In the Agent Panel, click the three dots in the top right and select **MCP Servers**. Click **Manage MCP Servers**. Select “View raw config” and add the following entry:

```
{
  "mcpServers": {
    "stitch": {
      "serverUrl": "https://stitch.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ACCESS_TOKEN>",
        "X-Goog-User-Project": "<YOUR_PROJECT_ID>"
      }
    }
  }
}
```

#### VSCode

Section titled “VSCode”

Open the Command Palette (Cmd+Shift+P) and type “MCP: Add Server”. Select “Add MCP Server”. Select **HTTP** to add a remote MCP server. Enter the Stitch MCP URL, `https://stitch.googleapis.com/mcp`. Set the name to “stitch” and confirm.

Then modify the `mcp.json` file to add the headers:

```
{
  "servers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "type": "http",
      "headers": {
        "Accept": "application/json",
        "Authorization": "Bearer <YOUR_ACCESS_TOKEN>",
        "X-Goog-User-Project": "<YOUR_PROJECT_ID>"
      }
    }
  }
}
```

#### Claude Code

Section titled “Claude Code”

Use the `claude mcp` command to add the server:

```
claude mcp add stitch \
  --transport http https://stitch.googleapis.com/mcp \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  --header "X-Goog-User-Project: <YOUR_PROJECT_ID>" \
  -s user

# -s user: saves to $HOME/.claude.json
# -s project: saves to ./.mcp.json
```

#### Gemini CLI

Section titled “Gemini CLI”

Install the [Stitch extension](https://github.com/gemini-cli-extensions/stitch) for the Gemini CLI:

```
gemini extensions install https://github.com/gemini-cli-extensions/stitch
```

### Available Tools

Section titled “Available Tools”

Once authenticated, your AI assistant will have access to the following tools to manage your Stitch workflow. See the [Reference](https://stitch.withgoogle.com/docs/mcp/reference) for full schemas and details.

#### Project Management

Section titled “Project Management”

- `create_project`: Creates a new container for your UI work.
- `get_project`: Retrieves specific details for a single project.
- `list_projects`: Retrieves a list of all your active designs.

#### Screen Management

Section titled “Screen Management”

- `list_screens`: Fetches all screens within a specific project.
- `get_screen`: Retrieves specific details for a single screen.

#### AI Generation

Section titled “AI Generation”

- `generate_screen_from_text`: Creates a new design from a text prompt.
- `edit_screens`: Edits existing screens using a text prompt.
- `generate_variants`: Generates design variants of existing screens.

#### Design Systems

Section titled “Design Systems”

- `create_design_system`: Creates a new design system with foundational design tokens.
- `update_design_system`: Updates an existing design system.
- `list_design_systems`: Lists all design systems for a project.
- `apply_design_system`: Applies a design system to one or more screens.

### Terms of Service

Section titled “Terms of Service”

By using this product you agree to the terms and conditions of the following license: [Google APIs Terms of Service](https://console.cloud.google.com/tos?id=universal).
## Getting Started

Source: https://stitch.withgoogle.com/docs/mcp/guide/

Get up and running and learn a few tips and tricks along the way.

The Stitch MCP takes the power of generating designs from within the Stitch editor and right into your IDE, CLI, or whatever AI tool of choice. You can convert your designs right into your codebase and generate new screens. This gives you programmable and automatable control with Stitch.

### Before we begin

Section titled “Before we begin”

#### Authentication

Section titled “Authentication”

Before anything else, you’ll need to authenticate with the Stitch MCP. This guide assumes you’ve already authenticated with the Stitch MCP. Check out our [Setup and Authentication Guide](https://stitch.withgoogle.com/docs/mcp/setup) to get started.

#### What coding agent to use?

Section titled “What coding agent to use?”

You can use any coding agent of your choice. The Stitch MCP server integrates into coding agents with support for remote HTTP MCP servers.

#### What we’re building

Section titled “What we’re building”

A Stitch to [React](http://react.dev/) component system. Write a prompt and get a well structured set of React components from your Stitch design.

### Prompting Stitch

Section titled “Prompting Stitch”

Write a prompt asking to see your Stitch Projects and each screen within that project.

PROMPT ACTION Show me my Stitch projects. FORMAT List out each screen under each project and its screen id.

You’ll see a response that looks something like below, although it will vary across tools and model choice.

```
1. Raffinato Coffee Store App
Created: Jan 14, 2026 • Desktop • Light Mode • Private

Screens (3):

- Home Menu
- Full Menu
- Checkout
```

Each Stitch Project can contain a series of screens. These screens are what contain the code and the images of your design.

#### Prompting for fun

Section titled “Prompting for fun”

The magic of MCP tools is the integration of contextual data retrieval with AI model intelligence. You can ask for understanding of your Stitch projects or instruct the agent to generate new designs and code based upon context on your local machine. Or, you can just ask it a fun question.

PROMPT FOR FUN Tell me what my Stitch Projects say about me as a developer.

This one is a lot of fun. If you run it and want to share, give us a shout on [Twitter / X](https://x.com/stitchbygoogle). Alright, back to real work.

#### Prompting for code

Section titled “Prompting for code”

Once the agent knows what project or screen you want to work with, you can access the code or the generated image.

PROMPT PROJECT + SCREEN Download the HTML code for the Full Menu screen in the Raffinato project. TOOL GUIDANCE Use a utility such as curl -L ACTION Create a file named ./tmp/${screen-name}.html with the HTML code.

The HTML file is a complete `<html>` document with a Tailwind CSS configuration specific to that design.

#### HTML to other UI frameworks

Section titled “HTML to other UI frameworks”

LLMs excel at converting HTML to many different UI systems. This HTML file serves as a foundation. By prompting an agent not only can you convert HTML to React, Vue, or Handlebars but even UI frameworks outside of the web platform, such as Flutter and Jetpack Compose.

#### Prompting for images

Section titled “Prompting for images”

Just like above, you can ask an agent for the image of your Stitch screen.

PROMPT PROJECT + SCREEN Download the image for the Full Menu screen in the Raffinato project. TOOL GUIDANCE Use a utility such as curl -L ACTION Create a file named ./tmp/${screen-name}.png containing the image.

Now you’ll have a local copy of your image. However, not much has happened yet. So let’s move this quickly along and convert an entire screen to React components.

### Using Agent Skills with Stitch MCP

Section titled “Using Agent Skills with Stitch MCP”

Many coding agents support the [Agent Skill Open Standard](https://agentskills.io/home). A skill encapsulates an instruction based prompt with a set of resources such as specific tool calls from a MCP server. This skill paradigm is a great fit for generating a React component system from the Stitch MCP.

#### Creating the React component system

Section titled “Creating the React component system”

The `add-skill` library lets you install agent skills to the most commonly used coding agents right from a GitHub URL.

```
npx add-skill google-labs-code/stitch-skills --skill react:components --global
```

This skill provides the details to an agent to understand what Stitch tools to use, steps to run, and best practices for separating React components. If you want to check out exactly what it does, see our [Stitch Agent Skills GitHub repo](https://github.com/google-labs-code/stitch-skills).

After it’s installed, you can write a prompt to trigger this skill and let it do the work.

PROMPT SKILL TRIGGER Convert the Landing Page screen in the Podcast Project.

The agent will get to work and leave you with a React app running on a [Vite](https://vite.dev/) local server.
## Reference

Source: https://stitch.withgoogle.com/docs/mcp/reference/

| # | Tool | Category | Read-Only |
| --- | --- | --- | --- |
| 1 | create_project | Project Management | false |
| 2 | get_project | Project Management | true |
| 3 | list_projects | Project Management | true |
| 4 | list_screens | Screen Management | true |
| 5 | get_screen | Screen Management | true |
| 6 | generate_screen_from_text | AI Generation | false |
| 7 | edit_screens | AI Generation | false |
| 8 | generate_variants | AI Generation | false |
| 9 | create_design_system | Design Systems | false |
| 10 | update_design_system | Design Systems | false |
| 11 | list_design_systems | Design Systems | true |
| 12 | apply_design_system | Design Systems | false |

### Tools

Section titled “Tools”

#### create_project

Section titled “create_project”

Creates a new Stitch project. A project is a container for UI designs and frontend code.

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Optional. The title of the project."
    }
  },
  "required": []
}
```

##### Output

Section titled “Output”

Returns the created `Project` resource with generated `name`, `title`, and metadata.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Create a new Stitch project called ‘Marketing Site’ Start a new design project Set up a new project for my app

#### get_project

Section titled “get_project”

Retrieves the details of a specific Stitch project using its project name.

ANNOTATIONS readOnly

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Required. Resource name. Format: `projects/{project}`. Example: `projects/4044680601076201931`"
    }
  },
  "required": ["name"]
}
```

##### Output

Section titled “Output”

Returns a `Project` resource object.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Get the details of project 4044680601076201931 Show me the project info What’s in my project?

#### list_projects

Section titled “list_projects”

Lists all Stitch projects accessible to the user. By default, it lists projects owned by the user.

ANNOTATIONS readOnly

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "description": "Optional. AIP-160 filter on `view` field. Supported: `view=owned` (default), `view=shared`."
    }
  },
  "required": []
}
```

##### Output

Section titled “Output”

Array of `Project` resource objects.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

List all my Stitch projects Show me my projects List shared projects

#### list_screens

Section titled “list_screens”

Lists all screens within a given Stitch project.

ANNOTATIONS readOnly

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID (e.g., '4044680601076201931'), without `projects/` prefix."
    }
  },
  "required": ["projectId"]
}
```

##### Output

Section titled “Output”

Array of [`Screen`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#screen) objects.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

List all screens in project 12345 Show me the designs in this project What screens are in my project?

#### get_screen

Section titled “get_screen”

Retrieves the details of a specific screen within a project.

ANNOTATIONS readOnly

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Required. Resource name. Format: `projects/{project}/screens/{screen}`"
    },
    "projectId": {
      "type": "string",
      "description": "Required (deprecated). Project ID without prefix."
    },
    "screenId": {
      "type": "string",
      "description": "Required (deprecated). Screen ID without prefix."
    }
  },
  "required": ["name", "projectId", "screenId"]
}
```

> `projectId` and `screenId` are deprecated in favor of `name` (resource name format), but all three are currently required.

##### Output

Section titled “Output”

Returns a [`Screen`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#screen) object with `htmlCode`, `screenshot`, `figmaExport` file references and download URLs.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Get the details of screen abc123 in project 12345 Show me the screen info Check the status of this screen

#### generate_screen_from_text

Section titled “generate_screen_from_text”

Generates a new screen from a text prompt. This process normally takes **a few minutes**. Avoid retrying even when you encounter connection errors. Connection errors don’t necessarily mean failure, try using `get_screen` after a few minutes. If `output_components` contains suggestions, present them to the user. If accepted, call again with the suggestion as the new `prompt`.

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "prompt": {
      "type": "string",
      "description": "Required. Text prompt describing the screen to generate."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
    },
    "modelId": {
      "type": "string",
      "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
    }
  },
  "required": ["projectId", "prompt"]
}
```

> `GEMINI_3_PRO` is deprecated. Use `GEMINI_3_1_PRO` or `GEMINI_3_FLASH` instead.

##### Output

Section titled “Output”

Returns generated [`Screen`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#screen) objects and [`SessionOutputComponent`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#sessionoutputcomponent) entries (text, suggestions, or design references).

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Generate a mobile login screen for project 12345 Design a dashboard page with charts and statistics Create a landing page with a hero section, features grid, and footer Build a settings page for a dark-themed app

#### edit_screens

Section titled “edit_screens”

Edits existing screens using a text prompt. Similar to `generate_screen_from_text`, this process normally takes **a few minutes**. Avoid retrying even when you encounter connection errors. Connection errors don’t necessarily mean failure, try using `get_screen` after a few minutes.

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenIds": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Required. Screen IDs to edit, without `screens/` prefix."
    },
    "prompt": {
      "type": "string",
      "description": "Required. Edit instruction."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
    },
    "modelId": {
      "type": "string",
      "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
    }
  },
  "required": ["projectId", "selectedScreenIds", "prompt"]
}
```

> `GEMINI_3_PRO` is deprecated. Use `GEMINI_3_1_PRO` or `GEMINI_3_FLASH` instead.

##### Output

Section titled “Output”

Returns the updated [`Screen`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#screen) objects.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Change the button color to blue on screen abc123 Make the hero text larger and add a subtitle Add a navigation bar to these screens Switch the layout to a two-column grid

#### generate_variants

Section titled “generate_variants”

Generates design variants of existing screens.

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenIds": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Required. Screen IDs to generate variants for."
    },
    "prompt": {
      "type": "string",
      "description": "Required. Text guiding variant generation."
    },
    "variantOptions": {
      "$ref": "#/$defs/VariantOptions",
      "description": "Required. Variant configuration."
    },
    "deviceType": {
      "type": "string",
      "enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
    },
    "modelId": {
      "type": "string",
      "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
    }
  },
  "required": ["projectId", "selectedScreenIds", "prompt", "variantOptions"]
}
```

> `GEMINI_3_PRO` is deprecated. Use `GEMINI_3_1_PRO` or `GEMINI_3_FLASH` instead.

###### VariantOptions

Section titled “VariantOptions”

```
{
  "type": "object",
  "properties": {
    "variantCount": {
      "type": "integer",
      "description": "Number of variants (1–5). Default: 3."
    },
    "creativeRange": {
      "type": "string",
      "enum": ["CREATIVE_RANGE_UNSPECIFIED", "REFINE", "EXPLORE", "REIMAGINE"]
    },
    "aspects": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["VARIANT_ASPECT_UNSPECIFIED", "LAYOUT", "COLOR_SCHEME", "IMAGES", "TEXT_FONT", "TEXT_CONTENT"]
      }
    }
  }
}
```

##### Output

Section titled “Output”

Returns generated variant [`Screen`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#screen) objects.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Generate 3 variants of screen abc123 focusing on layout and color Reimagine my landing page with radical variations Create subtle refinements of these screens Show me 5 different color schemes for this design

#### create_design_system

Section titled “create_design_system”

Creates a new design system for a project. Establishes foundational design tokens (colors, typography, shapes, appearance) that apply across all screens.

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "designSystem": {
      "$ref": "#/$defs/DesignSystem",
      "description": "Required. The design system to create."
    },
    "projectId": {
      "type": "string",
      "description": "Optional. Project ID. If empty, creates a global (unassociated) asset."
    }
  },
  "required": ["designSystem"]
}
```

###### DesignSystem

Section titled “DesignSystem”

```
{
  "type": "object",
  "properties": {
    "displayName": {
      "type": "string",
      "description": "Required. Display name."
    },
    "theme": {
      "$ref": "#/$defs/DesignTheme",
      "description": "Required. Theme configuration."
    }
  },
  "required": ["displayName", "theme"]
}
```

###### DesignTheme

Section titled “DesignTheme”

```
{
  "type": "object",
  "properties": {
    "colorMode": { "type": "string", "enum": ["COLOR_MODE_UNSPECIFIED", "LIGHT", "DARK"] },
    "headlineFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
    "bodyFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
    "labelFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
    "roundness": { "type": "string", "enum": ["ROUNDNESS_UNSPECIFIED", "ROUND_FOUR", "ROUND_EIGHT", "ROUND_TWELVE", "ROUND_FULL"] },
    "customColor": { "type": "string", "description": "Required. Hex color seed for the dynamic color system." },
    "colorVariant": { "type": "string", "enum": ["COLOR_VARIANT_UNSPECIFIED", "MONOCHROME", "NEUTRAL", "TONAL_SPOT", "VIBRANT", "EXPRESSIVE", "FIDELITY", "CONTENT", "RAINBOW", "FRUIT_SALAD"] },
    "overridePrimaryColor": { "type": "string", "description": "Optional. Override primary color (hex)." },
    "overrideSecondaryColor": { "type": "string", "description": "Optional. Override secondary color (hex)." },
    "overrideTertiaryColor": { "type": "string", "description": "Optional. Override tertiary color (hex)." },
    "overrideNeutralColor": { "type": "string", "description": "Optional. Override neutral color (hex)." },
    "designMd": { "type": "string", "description": "Optional. Markdown design instructions." }
  },
  "required": ["colorMode", "headlineFont", "bodyFont", "roundness", "customColor"]
}
```

##### Output

Section titled “Output”

Returns the created design system `Asset`.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Create a dark mode design system with Inter font and round corners Set up a design system with blue as the primary color Create a brand identity with Geist font and minimal roundness

#### update_design_system

Section titled “update_design_system”

Updates an existing design system. Identifies the asset by its `name` field.

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Required. Resource name. Format: `assets/{asset}`. Example: `assets/15996705518239280238`"
    },
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "designSystem": {
      "$ref": "#/$defs/DesignSystem",
      "description": "Required. The updated design system content."
    }
  },
  "required": ["name", "projectId", "designSystem"]
}
```

> Uses the same [`DesignSystem`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#designsystem) and [`DesignTheme`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#designtheme) schemas as `create_design_system`.

##### Output

Section titled “Output”

Returns the updated design system `Asset`.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Update the design system to use dark mode Change the font to Geist in our design system Update the roundness to fully rounded

#### list_design_systems

Section titled “list_design_systems”

Lists all design systems for a project (or global design systems if no `projectId`).

ANNOTATIONS readOnly

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Optional. Project ID. If empty, lists global design systems."
    }
  },
  "required": []
}
```

##### Output

Section titled “Output”

Array of `Asset` objects containing design systems.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

List all design systems in project 12345 Show me the available design systems What design systems do I have?

#### apply_design_system

Section titled “apply_design_system”

Applies a design system to one or more screens, modifying their appearance to match the system’s tokens (colors, fonts, shapes).

ANNOTATIONS destructive

##### Input

Section titled “Input”

```
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Required. Project ID without prefix."
    },
    "selectedScreenInstances": {
      "type": "array",
      "items": { "$ref": "#/$defs/SelectedScreenInstance" },
      "description": "Required. Screen instances to update (from `get_project`)."
    },
    "assetId": {
      "type": "string",
      "description": "Required. Design system asset ID (from `list_design_systems`), without `assets/` prefix."
    }
  },
  "required": ["projectId", "selectedScreenInstances", "assetId"]
}
```

###### SelectedScreenInstance

Section titled “SelectedScreenInstance”

```
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Required. The screen instance ID (NOT the source screen ID). Available from `get_project`."
    },
    "sourceScreen": {
      "type": "string",
      "description": "Required. Resource name. Format: `projects/{project}/screens/{screen}`"
    }
  },
  "required": ["id", "sourceScreen"]
}
```

##### Output

Section titled “Output”

Returns the updated [`Screen`](https://stitch.withgoogle.com/docs/mcp/reference/index.html#screen) objects.

##### Example Prompts

Section titled “Example Prompts”

PROMPT

Apply the blue design system to all screens in project 12345 Restyle these screens with the brand identity Use design system abc to update my screens

### Shared Types

Section titled “Shared Types”

#### Screen

Section titled “Screen”

A generated screen design within a Stitch project.

| Field | Type | Description |
| --- | --- | --- |
| name | string | Resource name. Format: projects/{project}/screens/{screen} |
| id | string | (Deprecated) The screen id. |
| title | string | Title of the screen. |
| prompt | string | Prompt used to generate the screen. |
| screenshot | File | Screenshot image of the screen. |
| htmlCode | File | HTML code of the screen. |
| figmaExport | File | Figma export of the screen. |
| theme | DesignTheme | Theme used for generation. |
| deviceType | DeviceType | Device type. |
| screenType | ScreenType | Screen type. |
| screenMetadata | ScreenMetadata | Metadata (agent, status, display mode). |
| width | string | Width of the screen. |
| height | string | Height of the screen. |
| groupId | string | Group id for related screens (e.g., variants). |
| groupName | string | Display name of the group. |
| generatedBy | string | Generator identifier. |
| isCreatedByClient | boolean | true if created via API upload, false if by agents. |

#### File

Section titled “File”

| Field | Type | Description |
| --- | --- | --- |
| name | string | Resource name. Format: projects/{project}/files/{file} |
| downloadUrl | string | URL for download. FIFE base URL for images. |
| mimeType | string | E.g., "image/png", "text/html". |
| fileContentBase64 | string | (Write-only) Base64-encoded content for uploads. |
| uploadBlobId | string | BlobId from upload service. |
| userFeedback | UserFeedback | (Read-only) Latest feedback. |

#### DesignSystem

Section titled “DesignSystem”

Represents visual/functional design guidelines used to generate consistent, branded designs.

| Field | Type | Description |
| --- | --- | --- |
| displayName | string | Display name of the design system. |
| theme | DesignTheme | Theme configuration. |

#### Asset

Section titled “Asset”

Wrapper for design system resources (used by `update_design_system`).

| Field | Type | Description |
| --- | --- | --- |
| name | string | Resource name. Format: assets/{asset} |
| designSystem | DesignSystem | The design system content. |
| version | string | (Read-only) Version counter. 0 = unversioned. |

#### DesignTheme

Section titled “DesignTheme”

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| colorMode | ColorMode | true | Light or dark mode. |
| headlineFont | Font | true | Headline typography. |
| bodyFont | Font | true | Body typography. |
| labelFont | Font | false | Label typography. |
| roundness | Roundness | true | Corner roundness. |
| customColor | string | true | Seed color for dynamic color system (hex, e.g., "#ff0000"). |
| colorVariant | ColorVariant | false | Dynamic color system variant. |
| overridePrimaryColor | string | false | Override primary color (hex). |
| overrideSecondaryColor | string | false | Override secondary color (hex). |
| overrideTertiaryColor | string | false | Override tertiary color (hex). |
| overrideNeutralColor | string | false | Override neutral color (hex). |
| designMd | string | false | Markdown design instructions. |

#### ScreenMetadata

Section titled “ScreenMetadata”

| Field | Type | Description |
| --- | --- | --- |
| agentType | AgentTypeEnum | TURBO_AGENT, PRO_AGENT, IMAGE_AGENT, GENIE_AGENT, IMAGE_PRO_AGENT, HATTER_AGENT, GEMINI_3_AGENT |
| status | ScreenStatusEnum | IN_PROGRESS, COMPLETE, FAILED |
| statusMessage | string | Human-readable status from agent. |
| displayMode | DisplayModeEnum | SCREENSHOT, HTML, CODE, MARKDOWN, STICKY_NOTE |
| isRemixed | boolean | Whether screen was created from a remix. |
| componentRegions | ComponentRegion[] | Component region annotations. |

#### SessionOutputComponent

Section titled “SessionOutputComponent”

Returned from generation tools in `output_components`.

| Field | Type | Description |
| --- | --- | --- |
| text | string | Agent text response. |
| suggestion | string | Suggested follow-up for the user. |
| design | Design | Generated design reference. |

#### UserFeedback

Section titled “UserFeedback”

| Field | Type | Description |
| --- | --- | --- |
| rating | string | POSITIVE or NEGATIVE. |
| comment | string | Additional comment. |
| designFeedbackReason | string | DESIGN_DOESNT_MATCH_PROMPT, EDIT_DOESNT_MATCH_PROMPT, COMPONENT_ISSUE, INCORRECT_THEME, etc. |

#### VariantOptions

Section titled “VariantOptions”

| Field | Type | Description |
| --- | --- | --- |
| variantCount | integer | Variants to generate (1–5). Default: 3. |
| creativeRange | CreativeRange | Creative freedom level. |
| aspects | VariantAspect[] | Aspects to focus on. |

#### SelectedScreenInstance

Section titled “SelectedScreenInstance”

Used by `apply_design_system`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| id | string | true | Screen instance ID (from get_project), not the source screen ID. |
| sourceScreen | string | true | Resource name. Format: projects/{project}/screens/{screen} |

### Enums

Section titled “Enums”

#### DeviceType Enum

Section titled “DeviceType Enum”

| Value | Description |
| --- | --- |
| DEVICE_TYPE_UNSPECIFIED | Unspecified. |
| MOBILE | Mobile device. |
| DESKTOP | Desktop device. |
| TABLET | Tablet device. |
| AGNOSTIC | Not tied to a device. |

#### ModelId Enum

Section titled “ModelId Enum”

| Value | Description |
| --- | --- |
| MODEL_ID_UNSPECIFIED | Unspecified. |
| GEMINI_3_PRO | (Deprecated) Gemini 3 Pro. Use GEMINI_3_1_PRO or GEMINI_3_FLASH instead. |
| GEMINI_3_FLASH | Gemini 3 Flash. |
| GEMINI_3_1_PRO | Gemini 3.1 Pro. |

#### ScreenType Enum

Section titled “ScreenType Enum”

| Value | Description |
| --- | --- |
| SCREEN_TYPE_UNSPECIFIED | Defaults to DESIGN. |
| DESIGN | A design screen. |
| IMAGE | A pure image. |
| PROTOTYPE | A design prototype. |
| DOCUMENT | A document (e.g., PRD). |
| PROTOTYPE_V2 | A design prototype v2. |

#### ColorMode Enum

Section titled “ColorMode Enum”

| Value | Description |
| --- | --- |
| COLOR_MODE_UNSPECIFIED | Unspecified. |
| LIGHT | Light mode. |
| DARK | Dark mode. |

#### ColorVariant Enum

Section titled “ColorVariant Enum”

| Value | Description |
| --- | --- |
| COLOR_VARIANT_UNSPECIFIED | Unspecified. |
| MONOCHROME | Monochrome variant. |
| NEUTRAL | Neutral variant. |
| TONAL_SPOT | Tonal spot variant. |
| VIBRANT | Vibrant variant. |
| EXPRESSIVE | Expressive variant. |
| FIDELITY | Fidelity variant. |
| CONTENT | Content variant. |
| RAINBOW | Rainbow variant. |
| FRUIT_SALAD | Fruit salad variant. |

#### Font Enum

Section titled “Font Enum”

29 supported font families:

`INTER` · `DM_SANS` · `GEIST` · `SORA` · `MANROPE` · `LEXEND` · `EPILOGUE` · `BE_VIETNAM_PRO` · `PLUS_JAKARTA_SANS` · `PUBLIC_SANS` · `SPACE_GROTESK` · `SPLINE_SANS` · `WORK_SANS` · `MONTSERRAT` · `METROPOLIS` · `SOURCE_SANS_THREE` · `NUNITO_SANS` · `ARIMO` · `HANKEN_GROTESK` · `RUBIK` · `IBM_PLEX_SANS` · `NEWSREADER` · `NOTO_SERIF` · `DOMINE` · `LIBRE_CASLON_TEXT` · `EB_GARAMOND` · `LITERATA` · `SOURCE_SERIF_FOUR`

#### Roundness Enum

Section titled “Roundness Enum”

| Value | Description |
| --- | --- |
| ROUNDNESS_UNSPECIFIED | Unspecified. |
| ROUND_TWO | (Deprecated) Round 2. |
| ROUND_FOUR | Round 4. |
| ROUND_EIGHT | Round 8. |
| ROUND_TWELVE | Round 12. |
| ROUND_FULL | Fully rounded. |

#### CreativeRange Enum

Section titled “CreativeRange Enum”

| Value | Description |
| --- | --- |
| CREATIVE_RANGE_UNSPECIFIED | Unspecified. |
| REFINE | Subtle refinements, close to original. |
| EXPLORE | Balanced exploration. (Default) |
| REIMAGINE | Radical explorations. |

#### VariantAspect Enum

Section titled “VariantAspect Enum”

| Value | Description |
| --- | --- |
| VARIANT_ASPECT_UNSPECIFIED | Unspecified. |
| LAYOUT | Element arrangement. |
| COLOR_SCHEME | Color palette. |
| IMAGES | Image usage. |
| TEXT_FONT | Font choices. |
| TEXT_CONTENT | Text content. |

### MCP Annotations

Section titled “MCP Annotations”

MCP Annotations are metadata hints that an MCP server attaches to each tool definition to tell the client (the AI agent or host application) about the tool’s behavioral characteristics. They’re part of the [MCP spec](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#data-types) and help clients make smarter decisions about tool usage without needing to understand the tool’s implementation.

Each tool includes behavior annotations:

| Annotation | Meaning |
| --- | --- |
| readOnlyHint | true = read-only, no mutations. |
| destructiveHint | true = may create/modify/delete resources. |
| idempotentHint | true = repeated calls produce same result. |
| openWorldHint | true = interacts with external systems. |

#### How they work with tools in practice

Section titled “How they work with tools in practice”

Each tool in the Stitch MCP server declares these as part of its tool registration. For example:

- `list_projects` has `readOnlyHint: true` — it just fetches data, so an agent can call it without worrying about side effects.
- `create_project` has `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false` — it mutates state, so the client should confirm with the user first.
- `generate_screen_from_text` has `destructiveHint: true` and `idempotentHint: false` — each call creates a new screen, so retrying on a timeout could produce duplicates.

#### Why they matter

Section titled “Why they matter”

These are hints, not enforced rules. They allow MCP clients to:

- Auto-approve read-only tools without prompting the user
- Show confirmation dialogs for destructive operations
- Safely retry idempotent tools on network failures
- Audit external interactions when `openWorldHint` is true

In the Stitch server’s case, all tools have `openWorldHint: false` because they interact only with the Stitch backend — not arbitrary third-party services.
## Build your first design

Source: https://stitch.withgoogle.com/docs/sdk/tutorial/

Install the Stitch SDK and generate your first UI screen in under five minutes.

The Stitch SDK (`@google/stitch-sdk`) lets you generate, edit, and manage UI designs directly from TypeScript. No MCP config files, no CLI setup-just `npm install` and go.

By the end of this tutorial, you’ll have a working script that creates a project, generates a screen, and retrieves the HTML and image URLs.

google-labs-code / stitch-sdk Star

TypeScript SDK for the Stitch design generation API

TypeScript @google/stitch-sdk

### What you’ll need

Section titled “What you’ll need”

- **Node.js** 20 or later (or [Bun](https://bun.sh/))
- A **Stitch API Key** from your [Stitch Settings page](https://stitch.withgoogle.com/docs/mcp/setup)

### Install the SDK

Section titled “Install the SDK”

#### npm

Section titled “npm”

```
npm install @google/stitch-sdk
```

#### Bun

Section titled “Bun”

```
bun add @google/stitch-sdk
```

### Set your API key

Section titled “Set your API key”

Export your key as an environment variable. The SDK picks it up automatically.

```
export STITCH_API_KEY="your-api-key"
```

### Write the script

Section titled “Write the script”

Create a file called `my-first-design.ts`:

```
import { stitch } from "@google/stitch-sdk";

// 1. Create a project
const project = await stitch.createProject("My First App");
console.log(`Project created: ${project.id}`);

// 2. Generate a screen
const screen = await project.generate("A simple login page with email and password fields");
console.log(`Screen generated: ${screen.id}`);

// 3. Get your outputs
const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();

console.log(`HTML:  ${htmlUrl}`);
console.log(`Image: ${imageUrl}`);
```

### Run it

Section titled “Run it”

#### tsx

Section titled “tsx”

```
npx tsx my-first-design.ts
```

#### Bun

Section titled “Bun”

```
bun my-first-design.ts
```

You’ll see output that looks like this:

```
Project created: 4044680601076201931
Screen generated: 98b50e2ddc9943efb387052637738f61
HTML:  https://...
Image: https://...
```

Open the HTML URL in your browser. You’ll see a fully styled login page with Tailwind CSS baked in.

### What just happened?

Section titled “What just happened?”

You used three core SDK concepts:

1. **`stitch`** - The default singleton. It connects to the Stitch MCP server using your API key.
2. **`project.generate(prompt)`** - Sends a prompt to Stitch and returns a `Screen` object.
3. **`screen.getHtml()` / `screen.getImage()`** - Retrieves download URLs for the generated design.

The SDK gives you a fluent, object-oriented API: `stitch` → `Project` → `Screen`. Each object knows how to navigate to the next.

### Next steps

Section titled “Next steps”

Now that you have a working design, try these:

- [Edit a screen](https://stitch.withgoogle.com/docs/sdk/edit-screen) to refine the design with a follow-up prompt
- [Generate variants](https://stitch.withgoogle.com/docs/sdk/generate-variants) to explore alternative layouts and color schemes
- [Manage design systems](https://stitch.withgoogle.com/docs/sdk/design-systems) to create and apply visual themes across screens
- [Upload files](https://stitch.withgoogle.com/docs/sdk/upload-image) to import mockups, screenshots, and HTML prototypes from disk
- [Use the SDK with the Vercel AI SDK](https://stitch.withgoogle.com/docs/sdk/ai-sdk) to let an LLM orchestrate your design workflow
- [Build agent-driven workflows](https://stitch.withgoogle.com/docs/sdk/agent-workflows) using `callTool` and `listTools` for full programmatic control
- Check out the full [SDK Reference](https://stitch.withgoogle.com/docs/sdk/reference) for every method available
## Use with AI SDK

Source: https://stitch.withgoogle.com/docs/sdk/ai-sdk/

Wire Stitch tools into the Vercel AI SDK and let an LLM generate designs autonomously.

The Stitch SDK ships a dedicated adapter for the [Vercel AI SDK](https://sdk.vercel.ai/). Import `stitchTools()` from the `/ai` subpath and drop it directly into `generateText()` or `streamText()`. The LLM handles tool orchestration-you just write the prompt.

### Install

Section titled “Install”

You need three packages:

```
npm install @google/stitch-sdk ai @ai-sdk/google
```

### Set your keys

Section titled “Set your keys”

```
export STITCH_API_KEY="your-stitch-api-key"
export GOOGLE_GENERATIVE_AI_API_KEY="your-gemini-api-key"
```

### Basic usage

Section titled “Basic usage”

```
import { generateText } from "ai";
import { google } from "@ai-sdk/google";
import { stitchTools } from "@google/stitch-sdk/ai";

const { text } = await generateText({
  model: google("gemini-3.1-flash-lite-preview"),
  tools: stitchTools(),
  maxSteps: 5,
  prompt: "Create a new Stitch project called 'Landing Page' and generate a hero section with a CTA button.",
});

console.log(text);
```

The LLM will call `create_project`, then `generate_screen_from_text`, then return a natural language summary of what it built. You don’t need to write any orchestration logic.

### Filter tools

Section titled “Filter tools”

If you want to restrict which tools the model can access, pass an `include` array:

```
const tools = stitchTools({
  include: ["create_project", "generate_screen_from_text", "list_projects"],
});
```

This is useful for tightening the model’s scope-for example, preventing it from deleting projects.

### Override the API key

Section titled “Override the API key”

If you don’t want to rely on the `STITCH_API_KEY` env var, pass it directly:

```
const tools = stitchTools({ apiKey: "your-key-here" });
```

### How it works

Section titled “How it works”

`stitchTools()` returns a `Record<string, Tool>` that is directly compatible with the AI SDK’s tool format. Each tool is pre-wired with an `execute` function that calls the underlying Stitch MCP server. The adapter has **zero runtime dependency** on the `ai` package-it only imports the `Tool` type.

For a deeper look at the architecture, see [Architecture](https://stitch.withgoogle.com/docs/sdk/architecture).
## Agent-driven workflows

Source: https://stitch.withgoogle.com/docs/sdk/agent-workflows/

Use callTool and listTools for full programmatic control over Stitch from AI agents and automation scripts.

The domain API (`stitch.projects()`, `project.generate()`) is the preferred interface for humans writing scripts. But if you’re building an **AI agent**, an **automation pipeline**, or need access to tools the domain layer doesn’t wrap yet, use the lower-level `callTool` and `listTools` APIs.

### List available tools

Section titled “List available tools”

Discover what the Stitch MCP server can do:

```
import { stitch } from "@google/stitch-sdk";

const { tools } = await stitch.listTools();
for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}
```

### Call any tool by name

Section titled “Call any tool by name”

`callTool` gives you raw access to every MCP tool, including ones not yet surfaced in the domain API:

```
// Create a project
const result = await stitch.callTool("create_project", { title: "Agent Project" });
console.log(result);

// Generate a screen
const screen = await stitch.callTool("generate_screen_from_text", {
  projectId: result.name.replace("projects/", ""),
  prompt: "A dashboard with charts and KPIs",
});
console.log(screen);
```

### How agents discover tool schemas

Section titled “How agents discover tool schemas”

An agent calling `callTool` needs to know two things: what parameters a tool expects, and what the response looks like. The SDK provides two ways to get this information.

#### Runtime discovery with listTools()

Section titled “Runtime discovery with listTools()”

Call `listTools()` to get the full catalog of tools with their JSON Schemas. An agent reads these schemas to understand what arguments to construct:

```
const { tools } = await stitch.listTools();
const createTool = tools.find(t => t.name === "create_project");
console.log(JSON.stringify(createTool.inputSchema, null, 2));
// → { type: "object", properties: { title: { type: "string", ... } } }
```

The agent can then construct a valid `callTool` invocation from the schema - no hardcoded knowledge of parameter names required.

#### Static schemas with toolDefinitions

Section titled “Static schemas with toolDefinitions”

The SDK also ships a **generated** `toolDefinitions` array (from `tools-manifest.json`) with the same schemas baked in at build time. This is what `stitchTools()` uses to wire tools into the Vercel AI SDK without a runtime `listTools()` call:

```
import { toolDefinitions } from "@google/stitch-sdk/tool-definitions"; // internal

for (const tool of toolDefinitions) {
  console.log(tool.name, Object.keys(tool.inputSchema.properties));
}
```

#### Responses are unstructured

Section titled “Responses are unstructured”

`callTool` returns raw JSON from the MCP server - the shape depends on the tool. Agents should inspect the response dynamically rather than assuming a fixed structure. The domain API (`project.generate()`, `screen.edit()`) parses these responses into typed objects, but at the `callTool` level, it’s the agent’s job to interpret the result.

### Mix domain and tool APIs

Section titled “Mix domain and tool APIs”

The `stitch` singleton exposes both layers through the same object. You can use `callTool` for creation, then switch to the domain API for everything else:

```
// Create via callTool (agent-style)
const raw = await stitch.callTool("create_project", { title: "Hybrid Flow" });

// Switch to domain API (human-style)
const project = stitch.project(raw.name);
const screen = await project.generate("A settings page");
const html = await screen.getHtml();
```

This is the **identity map pattern** - `stitch.project(id)` creates a `Project` handle from any project ID or resource name without an API call. Use it to bridge between raw tool results and the fluent domain API.

### Build a custom client

Section titled “Build a custom client”

If you need OAuth credentials or want to connect to a different Stitch environment, instantiate `StitchToolClient` directly:

```
import { StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({
  accessToken: process.env.STITCH_ACCESS_TOKEN,
  projectId: process.env.GOOGLE_CLOUD_PROJECT,
});

await client.connect();
const tools = await client.listTools();
console.log(`${tools.tools.length} tools available`);

await client.close();
```

### When to use which

Section titled “When to use which”

| Pattern | Best for |
| --- | --- |
| Domain API (stitch.projects() → project.generate() → screen.getHtml()) | Human scripts, tutorials, straightforward workflows |
| callTool | AI agents, automation, tools not in the domain layer, dynamic tool selection |
| stitchTools() | Vercel AI SDK integration - see Use with AI SDK |
| Custom StitchToolClient | OAuth, multi-tenant, or non-default server environments |
## How to edit a screen

Source: https://stitch.withgoogle.com/docs/sdk/edit-screen/

Refine an existing design with a follow-up prompt using the SDK.

Already have a screen? Use `screen.edit()` to iterate on it with natural language. The SDK handles the tool call, returns a new `Screen` object, and keeps the original untouched.

### Find a screen to edit

Section titled “Find a screen to edit”

First, grab a screen from one of your existing projects:

```
import { stitch } from "@google/stitch-sdk";

const projects = await stitch.projects();
const project = projects.at(0);
const screens = await project.screens();
const screen = screens.at(0);

console.log(`Editing screen ${screen.id} in project ${project.id}`);
```

### Edit it

Section titled “Edit it”

Pass a natural language instruction to `screen.edit()`:

```
const edited = await screen.edit("Change the color scheme to dark mode");
```

This returns a **new** `Screen` object. The original `screen` is unchanged.

> Generation can take up to a minute. Don’t retry on timeout-the server is still working.

### Compare the results

Section titled “Compare the results”

```
const originalHtml = await screen.getHtml();
const editedHtml = await edited.getHtml();

console.log(`Original: ${originalHtml}`);
console.log(`Edited:   ${editedHtml}`);
```

### Specify a device type or model

Section titled “Specify a device type or model”

If you need a specific device target or model, pass them as optional parameters:

```
const edited = await screen.edit(
  "Add a bottom navigation bar",
  "MOBILE",          // deviceType
  "GEMINI_3_PRO"     // modelId
);
```

See the [Reference](https://stitch.withgoogle.com/docs/sdk/reference) for all available `deviceType` and `modelId` values.
## How to generate variants

Source: https://stitch.withgoogle.com/docs/sdk/generate-variants/

Explore alternative designs by generating variants of an existing screen.

Variants let you explore different takes on an existing design. Give the SDK a screen, a prompt, and some options-it returns an array of new `Screen` objects, each a unique riff on the original.

### Find a screen

Section titled “Find a screen”

```
import { stitch } from "@google/stitch-sdk";

const projects = await stitch.projects();
const project = projects.at(0);
const screens = await project.screens();
const screen = screens.at(0);
```

### Generate variants

Section titled “Generate variants”

```
const variants = await screen.variants(
  "Change the button style to outline",
  { numVariants: 3 }
);

console.log(`Generated ${variants.length} variants`);
```

### Browse the results

Section titled “Browse the results”

Each variant is a full `Screen` object with its own HTML and image:

```
for (const variant of variants) {
  const html = await variant.getHtml();
  console.log(`Variant ${variant.id}: ${html}`);
}
```

### Variant options

Section titled “Variant options”

The second argument controls the generation behavior:

```
const variants = await screen.variants(
  "Explore different color palettes",
  {
    numVariants: 5,
    creativeRange: "REIMAGINE",
    aspects: ["COLOR_SCHEME", "LAYOUT"],
  }
);
```

| Option | Values | Description |
| --- | --- | --- |
| numVariants | 1–5 | Number of variants to generate. Default: 3. |
| creativeRange | REFINE, EXPLORE, REIMAGINE | How far from the original. REFINE = subtle tweaks, REIMAGINE = radical changes. |
| aspects | LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, TEXT_CONTENT | Which design aspects to vary. |

See the [Reference](https://stitch.withgoogle.com/docs/sdk/reference) for the complete type definitions.
## How to download artifacts

Source: https://stitch.withgoogle.com/docs/sdk/download-artifacts/

Save generated HTML and images to disk from the SDK.

Every Stitch screen produces two downloadable artifacts: an **HTML file** (a complete document with inline Tailwind CSS) and a **screenshot image**. The SDK gives you download URLs-you just fetch and save.

### Get the download URLs

Section titled “Get the download URLs”

```
import { stitch } from "@google/stitch-sdk";

const projects = await stitch.projects();
const screens = await projects.at(0).screens();
const screen = screens.at(0);

const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();
```

### Save HTML to disk

Section titled “Save HTML to disk”

```
import fs from "fs/promises";

const response = await fetch(htmlUrl);
const html = await response.text();
await fs.writeFile(`${screen.id}.html`, html);
```

Open the file in a browser. You’ll see the fully rendered design with Tailwind classes.

### Save the screenshot image

Section titled “Save the screenshot image”

Images come back as binary data. Use `arrayBuffer()` instead of `text()`:

```
const imgResponse = await fetch(imageUrl);
const buffer = await imgResponse.arrayBuffer();
await fs.writeFile(`${screen.id}.jpeg`, Buffer.from(buffer));
```

### Batch download all screens in a project

Section titled “Batch download all screens in a project”

```
import fs from "fs/promises";
import path from "path";

const outDir = "./designs";
await fs.mkdir(outDir, { recursive: true });

const project = (await stitch.projects()).at(0);
const screens = await project.screens();

for (const screen of screens) {
  const htmlUrl = await screen.getHtml();
  if (htmlUrl) {
    const res = await fetch(htmlUrl);
    await fs.writeFile(path.join(outDir, `${screen.id}.html`), await res.text());
  }

  const imgUrl = await screen.getImage();
  if (imgUrl) {
    const res = await fetch(imgUrl);
    await fs.writeFile(path.join(outDir, `${screen.id}.jpeg`), Buffer.from(await res.arrayBuffer()));
  }
}

console.log(`Downloaded ${screens.length} screens to ${outDir}`);
```
## How to extract themes

Source: https://stitch.withgoogle.com/docs/sdk/extract-themes/

Parse Tailwind config, Google Fonts, and Material Symbols from generated HTML.

Every Stitch screen generates a complete HTML document with an embedded Tailwind CSS configuration, Google Fonts links, and Material Symbols references. You can extract these to reuse the design system in your own project.

### Fetch the raw HTML

Section titled “Fetch the raw HTML”

Start by getting the HTML content from a screen:

```
import { stitch } from "@google/stitch-sdk";

const project = (await stitch.projects()).at(0);
const screen = (await project.screens()).at(0);

const htmlUrl = await screen.getHtml();
const response = await fetch(htmlUrl);
const html = await response.text();
```

### Extract the Tailwind config

Section titled “Extract the Tailwind config”

Stitch embeds the Tailwind configuration in a `<script>` tag with `id="tailwind-config"`:

```
const configMatch = html.match(/<script id="tailwind-config">([\s\S]*?)<\/script>/);

if (configMatch) {
  console.log("Tailwind config:");
  console.log(configMatch[1].trim());
}
```

This gives you the full `tailwind.config` object-colors, fonts, spacing, and border radius tokens specific to that design.

### Extract Google Fonts

Section titled “Extract Google Fonts”

Pull out the Google Fonts `<link>` tags to know which fonts the design uses:

```
const fontLinks = html.match(/<link[^>]*fonts\.googleapis\.com[^>]*>/g) || [];

for (const link of fontLinks) {
  console.log(link);
}
```

### Extract Material Symbols

Section titled “Extract Material Symbols”

If the design uses Material Design icons, parse them out:

```
const matches = Array.from(
  html.matchAll(/<span[^>]*class="[^"]*material-symbols-[^"]*"[^>]*>([^<]+)<\/span>/g)
);

const icons = new Set(matches.map(m => m.at(1).trim()));
console.log(`Icons used: ${[...icons].join(", ")}`);
```

### Putting it all together

Section titled “Putting it all together”

Combine these techniques into a design-token extraction pipeline. Generate a screen with a specific aesthetic, then extract the tokens:

```
const screen = await project.generate("A modern SaaS pricing page with a blue theme");
const url = await screen.getHtml();
const html = await (await fetch(url)).text();

// Now extract tailwind config, fonts, and icons from `html`
```

This is a powerful pattern for building a consistent design system from AI-generated foundations.
## How to manage design systems

Source: https://stitch.withgoogle.com/docs/sdk/design-systems/

Create, update, and apply design systems to screens programmatically with the SDK.

A design system defines the visual rules for your project — colors, typography, spacing. When you apply one to screens, every screen follows the same visual language. The SDK lets you create, update, and apply design systems without touching the Stitch UI.

### Create a design system

Section titled “Create a design system”

```
import { stitch } from "@google/stitch-sdk";

const project = stitch.project("your-project-id");
const ds = await project.createDesignSystem({ displayName: "My Theme" });
console.log(`Created: ${ds.id}`);
```

The `displayName` is what appears in the Stitch UI. Pick something descriptive — “Brand Dark Mode” beats “DS 1”.

### List existing design systems

Section titled “List existing design systems”

```
const systems = await project.listDesignSystems();
for (const ds of systems) {
  console.log(`${ds.id}: ${ds.data?.displayName}`);
}
```

### Reference a design system by ID

Section titled “Reference a design system by ID”

If you already know the asset ID, skip the network call:

```
const ds = project.designSystem("existing-asset-id");
```

This creates a handle without fetching anything from the server. Use it when you know the ID from a previous step or from the Stitch UI.

### Update a design system

Section titled “Update a design system”

```
const updated = await ds.update({ displayName: "Updated Theme" });
```

### Apply to screens

Section titled “Apply to screens”

Applying a design system re-renders screens with the new visual tokens. You need `SelectedScreenInstance` objects — get these from the project’s screen instances:

```
const projectData = await stitch.callTool("get_project", {
  name: `projects/${project.id}`,
});

// Extract screen instances
const instances = projectData.screenInstances.map((si: any) => ({
  id: si.id,
  sourceScreen: si.sourceScreen,
}));

// Apply the design system to all screens
const screens = await ds.apply(instances);
console.log(`Applied to ${screens.length} screens`);
```

> Only include `id` and `sourceScreen` in the instance objects. Extra fields like position or dimensions cause an “invalid argument” error.

### Full workflow: create and apply

Section titled “Full workflow: create and apply”

Here’s the end-to-end pattern — create a project, generate screens, create a design system, and apply it:

```
import { stitch } from "@google/stitch-sdk";

const project = await stitch.createProject("Themed App");

// Generate a few screens
const home = await project.generate("A landing page for a productivity app");
const settings = await project.generate("A settings page with dark theme toggle");

// Create and apply a design system
const ds = await project.createDesignSystem({ displayName: "Productivity Theme" });

// Get screen instances for applying
const projectData = await stitch.callTool("get_project", {
  name: `projects/${project.id}`,
});

const instances = projectData.screenInstances.map((si: any) => ({
  id: si.id,
  sourceScreen: si.sourceScreen,
}));

await ds.apply(instances);
console.log("Design system applied to all screens");
```
## How to upload files

Source: https://stitch.withgoogle.com/docs/sdk/upload-image/

Upload images, HTML, and other design assets directly to a Stitch project from code.

Got a mockup, a screenshot, or an HTML prototype on disk? Upload it directly to Stitch and turn it into a screen — no manual import, no browser, no base64 encoding headaches.

### Upload a file

Section titled “Upload a file”

```
import { stitch } from "@google/stitch-sdk";

const project = stitch.project("your-project-id");

const result = await project.upload("./mockup.png", {
  title: "Home Screen",
});

if (result.success) {
  const [screen] = result.screens;
  console.log(`Screen created: ${screen.id}`);
  const html = await screen.getHtml();
  const imageUrl = await screen.getImage();
}
```

The SDK reads the file from disk and posts it directly to the Stitch REST API. No output token limits apply — unlike agent-driven MCP calls that choke on base64-encoded payloads.

### Supported formats

Section titled “Supported formats”

| Extension | Type | Screen type |
| --- | --- | --- |
| .png | Image | IMAGE |
| .jpg / .jpeg | Image | IMAGE |
| .webp | Image | IMAGE |
| .html / .htm | Document | DOCUMENT |

HTML files are uploaded as document screens — useful for importing static snapshots of existing web pages or prototypes.

### Options

Section titled “Options”

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| title | string | — | Display title for the screen in Stitch |
| createScreenInstances | boolean | true | Whether to add the screen to the canvas |

### Upload HTML prototypes

Section titled “Upload HTML prototypes”

Upload a self-contained HTML file to import an existing design:

```
const result = await project.upload("./prototype.html", {
  title: "Landing Page Prototype",
});
```

The SDK detects `.html` and `.htm` extensions automatically and sets the screen type to `DOCUMENT`.

### Handle results

Section titled “Handle results”

`upload()` never throws. It returns a discriminated result object:

```
const result = await project.upload("./mockup.png");

if (result.success) {
  console.log(`Created ${result.screens.length} screens`);
} else {
  console.error(`${result.error.code}: ${result.error.message}`);
}
```

#### Error codes

Section titled “Error codes”

| Code | Meaning |
| --- | --- |
| FILE_NOT_FOUND | File doesn’t exist at the given path |
| UNSUPPORTED_FORMAT | Extension isn’t .png, .jpg, .jpeg, .webp, .html, or .htm |
| AUTH_FAILED | Invalid or missing API key |
| UPLOAD_FAILED | Server rejected the upload |
| UNKNOWN_ERROR | Unexpected failure |

### Bulk upload

Section titled “Bulk upload”

Upload multiple files in a loop:

```
import fs from "fs/promises";
import path from "path";

const project = stitch.project("your-project-id");
const files = await fs.readdir("./designs");

for (const file of files) {
  if (/\.(png|jpe?g|webp|html?)$/i.test(file)) {
    const result = await project.upload(
      path.join("./designs", file),
      { title: path.parse(file).name },
    );
    if (result.success) {
      console.log(`Uploaded ${file} → ${result.screens[0].id}`);
    }
  }
}
```
## Reference

Source: https://stitch.withgoogle.com/docs/sdk/reference/

Complete API reference for the Stitch TypeScript SDK.

### Installation

Section titled “Installation”

```
npm install @google/stitch-sdk
```

### Exports

Section titled “Exports”

All exports are available from `@google/stitch-sdk`:

```
import {
  stitch,           // Default singleton instance
  Stitch,           // Domain class: project management
  Project,          // Domain class: screen management within a project
  Screen,           // Domain class: screen operations
  StitchToolClient, // Low-level MCP client
  StitchProxy,      // Local proxy server
  StitchError,      // Error class
  StitchErrorCode,  // Error code enum
} from "@google/stitch-sdk";
```

AI SDK adapter (separate subpath):

```
import { stitchTools } from "@google/stitch-sdk/ai";
```

### stitch (Singleton)

Section titled “stitch (Singleton)”

The default entry point. A lazily-initialized `Proxy` that combines `Stitch` domain methods and `StitchToolClient` infrastructure methods.

Reads `STITCH_API_KEY` and `STITCH_HOST` from environment variables on first access.

```
import { stitch } from "@google/stitch-sdk";
```

#### Domain methods

Section titled “Domain methods”

| Method | Returns | Description |
| --- | --- | --- |
| createProject(title) | Promise<Project> | Creates a new project. |
| projects() | Promise<Project[]> | Lists all projects accessible to the authenticated user. |
| project(id) | Project | Creates a Project handle from an existing project ID or resource name. No API call. |

#### Infrastructure methods

Section titled “Infrastructure methods”

| Method | Returns | Description |
| --- | --- | --- |
| listTools() | Promise<{ tools: ToolDefinition[] }> | Lists all available MCP tools. |
| callTool<T>(name, params) | Promise<T> | Calls a raw MCP tool by name. |
| close() | Promise<void> | Closes the underlying MCP client connection. |

### Stitch

Section titled “Stitch”

Main entry point class. Manages projects.

```
import { Stitch, StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({ apiKey: "..." });
const s = new Stitch(client);
```

#### Constructor

Section titled “Constructor”

| Parameter | Type | Description |
| --- | --- | --- |
| client | StitchToolClient | An initialized tool client instance. |

#### Methods

Section titled “Methods”

| Method | Returns | Description |
| --- | --- | --- |
| createProject(title) | Promise<Project> | Creates a new project. Maps to MCP tool create_project. |
| projects() | Promise<Project[]> | Lists all projects. Maps to MCP tool list_projects. |
| project(id) | Project | Creates a Project handle without an API call. Accepts a project ID or full resource name (projects/{id}). |

### Project

Section titled “Project”

A Stitch project containing screens.

#### Properties

Section titled “Properties”

| Property | Type | Description |
| --- | --- | --- |
| projectId | string | The project ID (without projects/ prefix). |
| id | string | Alias for projectId. |
| data | any | Raw API response data, if constructed from server response. undefined if constructed from an ID string. |

#### Methods

Section titled “Methods”

| Method | Parameters | Returns | Description |
| --- | --- | --- | --- |
| generate(prompt, deviceType?, modelId?) | prompt: string, deviceType?: DeviceType, modelId?: ModelId | Promise<Screen> | Generates a new screen from a text prompt. Maps to generate_screen_from_text. |
| screens() | - | Promise<Screen[]> | Lists all screens in the project. Maps to list_screens. |
| getScreen(screenId) | screenId: string | Promise<Screen> | Retrieves a specific screen by ID. Maps to get_screen. |
| upload(filePath, opts?) | filePath: string, opts?: { title?: string, createScreenInstances?: boolean } | Promise<UploadResult> | Uploads a file (.png, .jpg, .jpeg, .webp, .html, .htm) and creates a screen. Posts directly to REST API. Never throws — returns a discriminated result. |
| createDesignSystem(ds) | ds: { displayName: string } | Promise<DesignSystem> | Creates a design system for this project. |
| listDesignSystems() | - | Promise<DesignSystem[]> | Lists all design systems in the project. |
| designSystem(id) | id: string | DesignSystem | Creates a DesignSystem handle from an asset ID. No API call. |

### DesignSystem

Section titled “DesignSystem”

A design system asset that defines visual tokens for a project.

#### Properties

Section titled “Properties”

| Property | Type | Description |
| --- | --- | --- |
| id | string | The asset ID. |
| data | any | Raw API response data. undefined if constructed from an ID string. |

#### Methods

Section titled “Methods”

| Method | Parameters | Returns | Description |
| --- | --- | --- | --- |
| update(ds) | ds: { displayName?: string } | Promise<DesignSystem> | Updates the design system’s metadata. |
| apply(selectedScreenInstances) | { id: string, sourceScreen: string }[] | Promise<Screen[]> | Applies this design system to the given screens. Only pass id and sourceScreen — extra fields cause errors. |

### Screen

Section titled “Screen”

A generated UI screen. Provides access to HTML code and screenshot images.

#### Properties

Section titled “Properties”

| Property | Type | Description |
| --- | --- | --- |
| projectId | string | Parent project ID. |
| screenId | string | The screen ID. |
| id | string | Alias for screenId. |
| data | any | Raw API response data. |

#### Methods

Section titled “Methods”

| Method | Parameters | Returns | Description |
| --- | --- | --- | --- |
| edit(prompt, deviceType?, modelId?) | prompt: string, deviceType?: DeviceType, modelId?: ModelId | Promise<Screen> | Edits this screen with a text prompt. Returns a new Screen; original is unchanged. Maps to edit_screens. |
| variants(prompt, variantOptions, deviceType?, modelId?) | prompt: string, variantOptions: VariantOptions, deviceType?: DeviceType, modelId?: ModelId | Promise<Screen[]> | Generates design variants. Maps to generate_variants. |
| getHtml() | - | Promise<string> | Returns the HTML download URL for this screen. Uses cached URL if available. |
| getImage() | - | Promise<string> | Returns the screenshot download URL. Uses cached URL if available. |

### StitchToolClient

Section titled “StitchToolClient”

Low-level MCP client that connects to the Stitch server over HTTP.

```
import { StitchToolClient } from "@google/stitch-sdk";
```

#### Constructor

Section titled “Constructor”

| Parameter | Type | Description |
| --- | --- | --- |
| config | StitchConfigInput | Connection configuration. |

#### StitchConfigInput

Section titled “StitchConfigInput”

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| apiKey | string | One of apiKey or accessToken | API key for authentication. |
| accessToken | string | One of apiKey or accessToken | OAuth access token. |
| projectId | string | Required with accessToken | Google Cloud project ID (for OAuth). |
| baseUrl | string | No | Override the server URL. Defaults to https://stitch.googleapis.com/mcp. |

#### Methods

Section titled “Methods”

| Method | Returns | Description |
| --- | --- | --- |
| connect() | Promise<void> | Explicitly connects to the MCP server. Called automatically on first tool call. |
| callTool<T>(name, params) | Promise<T> | Calls a named MCP tool with the given parameters. |
| listTools() | Promise<{ tools: ToolDefinition[] }> | Lists all available tools from the server. |
| close() | Promise<void> | Closes the connection. |

### stitchTools(options?)

Section titled “stitchTools(options?)”

AI SDK adapter. Returns Stitch tools in Vercel AI SDK format.

Import from the `/ai` subpath:

```
import { stitchTools } from "@google/stitch-sdk/ai";
```

#### Parameters

Section titled “Parameters”

| Field | Type | Description |
| --- | --- | --- |
| options.apiKey | string | Override STITCH_API_KEY env var. |
| options.include | string[] | Only include specific tool names. |

#### Returns

Section titled “Returns”

`Record<string, Tool>` - Drop directly into `generateText({ tools: stitchTools() })`.

### StitchError

Section titled “StitchError”

Error class thrown by all SDK methods.

| Property | Type | Description |
| --- | --- | --- |
| message | string | Human-readable error message. |
| code | StitchErrorCode | Structured error code. |

#### Static methods

Section titled “Static methods”

| Method | Description |
| --- | --- |
| StitchError.fromUnknown(error) | Wraps any thrown value into a StitchError. |

### Enums

Section titled “Enums”

#### DeviceType

Section titled “DeviceType”

`"DEVICE_TYPE_UNSPECIFIED"` | `"MOBILE"` | `"DESKTOP"` | `"TABLET"` | `"AGNOSTIC"`

#### ModelId

Section titled “ModelId”

`"MODEL_ID_UNSPECIFIED"` | `"GEMINI_3_PRO"` | `"GEMINI_3_FLASH"`

#### CreativeRange

Section titled “CreativeRange”

`"CREATIVE_RANGE_UNSPECIFIED"` | `"REFINE"` | `"EXPLORE"` | `"REIMAGINE"`

#### VariantAspect

Section titled “VariantAspect”

`"VARIANT_ASPECT_UNSPECIFIED"` | `"LAYOUT"` | `"COLOR_SCHEME"` | `"IMAGES"` | `"TEXT_FONT"` | `"TEXT_CONTENT"`

### Environment Variables

Section titled “Environment Variables”

| Variable | Description |
| --- | --- |
| STITCH_API_KEY | API key for authentication. Used by the stitch singleton and stitchTools(). |
| STITCH_HOST | Override the MCP server URL. Defaults to https://stitch.googleapis.com/mcp. |
| STITCH_ACCESS_TOKEN | OAuth access token (alternative to API key). |
| GOOGLE_CLOUD_PROJECT | Google Cloud project ID (required with OAuth). |
## Architecture

Source: https://stitch.withgoogle.com/docs/sdk/architecture/

How the Stitch SDK is built and why it works the way it does.

The Stitch SDK isn’t a hand-written REST client. It’s a generated domain layer built on top of the Model Context Protocol (MCP), designed to give you a fluent TypeScript API while keeping a single source of truth for every tool Stitch offers.

### Why MCP, not REST?

Section titled “Why MCP, not REST?”

Stitch already runs an MCP server that AI agents connect to directly. Instead of maintaining a separate REST API surface, the SDK connects to the same MCP server over HTTP. This means:

- **One API surface.** The tools available to the SDK are the exact same tools your AI agent uses. No drift.
- **Instant updates.** When new tools ship on the MCP server, the SDK generator picks them up automatically.
- **Agent compatibility.** The same `callTool` semantics work whether you’re in an SDK script or an AI agent.

### The three layers

Section titled “The three layers”

The SDK has a clear three-layer architecture:

```
┌─────────────────────────────────┐
│     stitch (singleton proxy)     │  ← What you import
├─────────────────────────────────┤
│  Stitch / Project / Screen       │  ← Generated domain classes
├─────────────────────────────────┤
│       StitchToolClient           │  ← MCP-over-HTTP transport
└─────────────────────────────────┘
```

#### Layer 1: StitchToolClient (transport)

Section titled “Layer 1: StitchToolClient (transport)”

The foundation. Connects to the Stitch MCP server over HTTP, handles authentication (API key or OAuth), and exposes raw `callTool(name, params)` for any MCP tool. You can use this layer directly if you need full control.

#### Layer 2: Generated domain classes (domain)

Section titled “Layer 2: Generated domain classes (domain)”

`Stitch`, `Project`, and `Screen` are **auto-generated** from two source files:

1. **`tools-manifest.json`** - A snapshot of every MCP tool’s name, description, and input schema.
2. **`domain-map.json`** - A hand-authored mapping that assigns tools to domain classes and methods.

A generation script reads both files and produces TypeScript classes in `generated/src/`. Each method is a thin wrapper around `callTool` that handles parameter mapping and response parsing.

The generation is **content-hash locked** - regenerating only produces changes when the manifest or domain map actually changes. This prevents churn.

#### Layer 3: stitch singleton (convenience)

Section titled “Layer 3: stitch singleton (convenience)”

A `Proxy` object that lazily initializes a `StitchToolClient` from environment variables and delegates method calls to either the `Stitch` domain class or the `StitchToolClient`, depending on the method name.

When you write `stitch.projects()`, the proxy routes to `Stitch.projects()`. When you write `stitch.callTool(...)`, it routes to `StitchToolClient.callTool()`.

### Identity map pattern

Section titled “Identity map pattern”

`stitch.project(id)` and `new Project(client, id)` create a **handle** without making an API call. They parse the ID (stripping any `projects/` prefix) and return a `Project` object that you can immediately call `.generate()`, `.screens()`, or `.getScreen()` on.

This is useful when you already know a project ID from a previous operation - you don’t need to re-fetch it.

### The AI SDK adapter

Section titled “The AI SDK adapter”

`stitchTools()` (from `@google/stitch-sdk/ai`) bridges the SDK into the Vercel AI SDK ecosystem. It reads the same `tools-manifest.json` and produces a `Record<string, Tool>` compatible with `generateText()` and `streamText()`.

The adapter has **zero runtime dependency** on the `ai` package. It reconstructs the tool schema format using `Symbol.for("vercel.ai.schema")` - matching the AI SDK’s internal protocol without importing any of its code. This keeps the SDK lightweight for consumers who use only the domain API.

### Error handling

Section titled “Error handling”

All domain methods catch errors internally and re-throw them as `StitchError` instances with structured error codes. This gives you a single error type to catch:

```
import { StitchError } from "@google/stitch-sdk";

try {
  await screen.edit("...");
} catch (e) {
  if (e instanceof StitchError) {
    console.error(e.code, e.message);
  }
}
```
## What is DESIGN.md?

Source: https://stitch.withgoogle.com/docs/design-md/overview/

A design system document that AI agents read to generate consistent UI across your project.

Stitch

Every project has a visual identity: colors, fonts, spacing, component styles. Traditionally, this lives in a Figma file, a brand PDF, or a designer’s head. None of these are readable by an AI agent.

**`DESIGN.md` changes that.** It’s a plain-text design system document that both humans and agents can read, edit, and enforce. Think of it as the design counterpart to `AGENTS.md`:

| File | Who reads it | What it defines |
| --- | --- | --- |
| README.md | Humans | What the project is |
| AGENTS.md | Coding agents | How to build the project |
| DESIGN.md | Design agents | How the project should look and feel |

### What it gives you

Section titled “What it gives you”

When a design agent like Stitch reads your `DESIGN.md`, every screen it generates follows the same visual rules: your color palette, your typography, your component patterns. Without it, each screen stands alone. With it, they look like they belong together.

`DESIGN.md` is a **living artifact**, not a static config file. It evolves as your design evolves. The agent generates it, you refine it, and it’s re-applied to screens as you iterate.

Under the hood, every `DESIGN.md` has two layers: **YAML front matter** containing machine-readable design tokens (exact hex values, font properties, spacing scales) and a **markdown body** providing human-readable design rationale. Tokens give agents precise values. Prose tells them _why_ those values exist. See [the specification](https://stitch.withgoogle.com/docs/design-md/specification/) for the full format.

### The philosophy

Section titled “The philosophy”

The DESIGN.md spec is a **foundation, not a prescription**. It provides a common ground that agents, tools, and teams can rely on — a shared vocabulary for colors, typography, layout, and components — while preserving the freedom to extend the format for domain-specific needs. Unknown sections and custom tokens are accepted, not rejected.

### How they’re created

Section titled “How they’re created”

There are three paths to a `DESIGN.md`, from effortless to precise.

Stitch

#### Let the agent generate it

Section titled “Let the agent generate it”

Describe the vibe. The agent translates your aesthetic intent into tokens and guidelines.

PROMPT

A playful coffee shop ordering app with warm colors, rounded corners, and a friendly feel

Stitch generates a complete design system (colors, typography, spacing, component styles) and summarizes it as a `DESIGN.md`.

#### Derive from branding

Section titled “Derive from branding”

If you already have a brand, provide a URL or image. The agent extracts your palette, typography, and style patterns to build the `DESIGN.md` from what already exists.

Stitch

#### Write it by hand

Section titled “Write it by hand”

Advanced users can author a `DESIGN.md` directly, encoding exact design preferences. Every section is just markdown with optional YAML front matter for design tokens. No special syntax beyond standard markdown and YAML.

### Example

Section titled “Example”

Below is a minimal `DESIGN.md` for a dark-themed productivity app. The YAML front matter defines the exact token values; the markdown body explains the design intent.

```
---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text
```

This is what the agent reads when generating your next screen. For the complete format specification, see [The specification](https://stitch.withgoogle.com/docs/design-md/specification/). To validate your DESIGN.md against the spec, see [Validate with the CLI](https://stitch.withgoogle.com/docs/design-md/cli/).
## Import from your codebase

Source: https://stitch.withgoogle.com/docs/design-md/get-instructions/

Extract a DESIGN.md from an existing project — with a prompt, a skill, or both.

Your codebase already has a design language — colors scattered across stylesheets, spacing patterns buried in component files, typography choices locked in Tailwind configs. A `DESIGN.md` captures all of it in one place so Stitch can generate screens that look like they belong to your product instead of a blank-slate default.

There are two ways to get there: a quick prompt you can paste into any coding agent, or a dedicated skill that automates the entire pipeline.

### The quick prompt

Section titled “The quick prompt”

Copy this prompt into any coding agent (Gemini, Claude Code, Cursor, Antigravity) from a project directory. No skills or plugins required — the agent reads your source files and writes a `DESIGN.md` from what it finds.

PROMPT CONTEXT — OPTIONAL Add specifics about your codebase’s purpose, critical files, and goals. INSTRUCTIONS Read the codebase and/or website before designing. The repo and/or website are the source of truth. Start with real content. Pull product names, taglines, and copy from the README. Pull labels, values, and terminology from config files, CLI help text, schemas, and error messages. Nothing invented, nothing placeholder — if the repo doesn’t contain it, the design doesn’t show it. Look at existing code for visual identity: color values, type scales, spacing tokens, component patterns. If a design system exists, inherit it. If values are scattered across files, collect them — they reveal visual intent even when undocumented. Read the core logic and data structures, not just the docs. They tell you the product’s native shape — a timeline, a graph, a catalog, a pipeline. Let that shape organize the page instead of a section template. Find what the README leads with. That feature dominates the page. Establish its weight before placing anything else — what matters before what measures.

#### What the prompt does

Section titled “What the prompt does”

The prompt tells the agent to work backwards from your code, not forwards from a template. It extracts three layers:

1. **Content** — Product names, labels, and copy pulled directly from the source. No filler text, no lorem ipsum.
2. **Visual identity** — Colors, fonts, spacing, and component patterns gathered from stylesheets, theme files, and Tailwind configs.
3. **Information architecture** — The natural shape of your product’s data, which determines how the page is organized.

The output is a `DESIGN.md` you can drop into `.stitch/DESIGN.md` and immediately use for screen generation.

#### Tips for better results

Section titled “Tips for better results”

- **Point the agent at specific directories.** Add lines like “Focus on `src/styles/`, `tailwind.config.ts`, and `src/components/`” to the context block.
- **Name your stack.** Telling the agent “This is a React + Tailwind + shadcn/ui project” helps it look in the right places.
- **Iterate.** The first extraction captures the big picture. Refine it: “The accent color should be the teal from the navbar, not the blue from the footer.”

### Automated extraction with Stitch Design Skills

Section titled “Automated extraction with Stitch Design Skills”

The prompt above works anywhere, but it relies on the agent’s general reasoning. **Stitch Design Skills** are purpose-built agent instructions that know exactly where to look for design tokens in every major framework — React, Vue, Svelte, Angular, plain CSS, and Tailwind.

#### What are Stitch Design Skills?

Section titled “What are Stitch Design Skills?”

[Stitch Design Skills](https://github.com/google-labs-code/stitch-skills) is an open-source collection of 13 agent skills organized into three plugins:

| Plugin | What it does |
| --- | --- |
| stitch-design | Create and capture designs — extract tokens from code, snapshot running apps, upload to Stitch |
| stitch-build | Turn designs into code — React components, walkthrough videos, shadcn/ui integration |
| stitch-utilities | Enhance quality — prompt optimization, premium design systems, autonomous multi-page generation |

Skills follow the [Agent Skills](https://agentskills.io/) open standard and work with any compatible coding agent.

#### Install the plugin suite

Section titled “Install the plugin suite”

```
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code
```

Replace `claude-code` with `cursor`, `gemini-cli`, or `antigravity` depending on your agent.

#### Extract a DESIGN.md from source code

Section titled “Extract a DESIGN.md from source code”

The `extract-design-md` skill scans your source tree without needing to build or run the application:

PROMPT

Extract the design system from ./src and write it to .stitch/DESIGN.md

The skill automatically detects your stack (Tailwind config, CSS custom properties, theme files, styled-components) and works through each design dimension:

- **Visual atmosphere** — Overall mood, whitespace philosophy, color temperature
- **Color palette** — Every unique color, deduplicated and assigned functional roles
- **Typography** — Font families, type scale hierarchy, weight and spacing patterns
- **Component styles** — Buttons, cards, navigation, inputs, and domain-specific elements
- **Layout principles** — Grid system, responsive breakpoints, spacing strategy

The output includes both YAML frontmatter (machine-readable tokens) and Markdown prose (human-readable design rationale). This bimodal format is what makes `DESIGN.md` work for both tools and AI agents.

#### Upload to Stitch

Section titled “Upload to Stitch”

Once you have a `DESIGN.md`, push it into a Stitch project so every generated screen follows your design system:

PROMPT

Upload .stitch/DESIGN.md to Stitch and create a design system from it.

The `manage-design-system` skill handles the upload and registers the design system at the project level. All future screens inherit your tokens automatically.

#### The full code-to-design pipeline

Section titled “The full code-to-design pipeline”

For a complete import — design system extraction, static HTML capture, and Stitch upload in one pass — use the orchestrator skill:

PROMPT

Upload the frontend at ./my-app into a Stitch project called “My App Migration”.

The `code-to-design` skill chains three steps: extract static HTML from the running app, reverse-engineer the design system from source, and upload everything to Stitch.

### Which method should I use?

Section titled “Which method should I use?”

| Situation | Recommended approach |
| --- | --- |
| Quick extraction, no setup | Copy the prompt above into any agent |
| Thorough, framework-aware extraction | Install skills, use extract-design-md |
| Full migration into Stitch | Install skills, use code-to-design |
| Writing a DESIGN.md from scratch | See What is DESIGN.md? for the format |
## The DESIGN.md specification

Source: https://stitch.withgoogle.com/docs/design-md/specification/

The formal specification for the DESIGN.md format — token schema, section structure, and type system.

A DESIGN.md file has two layers. The **YAML front matter** contains machine-readable design tokens — the precise values agents use to enforce consistency. The **markdown body** provides human-readable design rationale organized into `##` sections. Prose may use descriptive color names (e.g., “Midnight Forest Green”) that correspond to systematic token names (e.g., `primary`). The tokens are the normative values; the prose provides context for how to apply them.

The spec is a **foundation, not a prescription**. It provides common ground that agents, tools, and teams can rely on, while preserving the freedom to extend the format for domain-specific needs.

### Design tokens

Section titled “Design tokens”

DESIGN.md embeds design tokens as YAML front matter at the beginning of the file. The front matter block must begin with a line containing exactly `---` and end with a line containing exactly `---`. The YAML content between these delimiters follows the schema defined below.

The token system is inspired by the [W3C Design Token Format](https://www.designtokens.org/). Tokens are easily converted to and from `tokens.json`, Figma variables, and Tailwind theme configs.

```
---
version: alpha
name: Daylight Prestige
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
---
```

#### Schema

Section titled “Schema”

```
version: <string>          # optional, current version: "alpha"
name: <string>
description: <string>      # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>
```

The `<scale-level>` placeholder represents a named level in a sizing or spacing scale. Common level names include `xs`, `sm`, `md`, `lg`, `xl`, and `full`. Any descriptive string key is valid.

### Token types

Section titled “Token types”

| Type | Format | Example |
| --- | --- | --- |
| Color | # + hex code (sRGB) | "#1A1C1E" |
| Dimension | number + unit (px, em, rem) | 48px, -0.02em |
| Token Reference | {path.to.token} | {colors.primary} |
| Typography | composite object | See properties below |

#### Typography properties

Section titled “Typography properties”

| Property | Type | Description |
| --- | --- | --- |
| fontFamily | string | The font family name |
| fontSize | Dimension | The font size |
| fontWeight | number | Numeric weight (e.g., 400, 700). In YAML, bare numbers and quoted strings are equivalent |
| lineHeight | Dimension \| number | A dimension (e.g., 24px) or a unitless multiplier (e.g., 1.6). Unitless is recommended |
| letterSpacing | Dimension | Letter spacing adjustment |
| fontFeature | string | Configures font-feature-settings |
| fontVariation | string | Configures font-variation-settings |

#### Token references

Section titled “Token references”

A token reference is wrapped in curly braces and contains an object path to another value in the YAML tree. For most token groups, the reference must point to a primitive value (e.g., `{colors.primary-60}`), not a group. Within the `components` section, references to composite values (e.g., `{typography.label-md}`) are permitted.

```
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
```

### Sections

Section titled “Sections”

Every DESIGN.md follows the same structure. Sections can be omitted if they are not relevant to the project, but those present should appear in the sequence listed below. All sections use `##` headings. An optional `#` heading may appear for document titling purposes but is not parsed as a section.

The section structure is intentionally open-ended. The canonical sections provide a shared vocabulary; design systems are free to add domain-specific sections beyond these.

#### Section order

Section titled “Section order”

| # | Section | Aliases |
| --- | --- | --- |
| 1 | Overview | Brand & Style |
| 2 | Colors |  |
| 3 | Typography |  |
| 4 | Layout | Layout & Spacing |
| 5 | Elevation & Depth | Elevation |
| 6 | Shapes |  |
| 7 | Components |  |
| 8 | Do’s and Don’ts |  |

#### Overview

Section titled “Overview”

Also known as “Brand & Style.” A holistic description of the product’s look and feel. This section defines the brand personality, target audience, and the emotional response the UI should evoke. It serves as foundational context when a specific rule or token is not defined.

```
## Overview
A calm, professional interface for a healthcare scheduling platform.
Accessibility-first design with high contrast and generous touch targets.
```

#### Colors

Section titled “Colors”

Defines the color palettes for the design system. At least the `primary` palette should be defined. Additional palettes may be named freely; a common convention is `primary`, `secondary`, `tertiary`, and `neutral`.

```
## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** The sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.
```

**Design tokens:** A `map<string, Color>` mapping the token name to its hex value.

```
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
```

#### Typography

Section titled “Typography”

Defines typography levels. Most design systems have 9–15 levels, each with a semantic role (headline, body, label) and size variant (small, medium, large).

```
## Typography

- **Headlines:** Public Sans Semi-Bold for an institutional voice.
- **Body:** Public Sans Regular at 16px for long-form readability.
- **Labels:** Space Grotesk for technical data and metadata.
```

**Design tokens:** A `map<string, Typography>` mapping the token name to its typography properties.

```
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1
    letterSpacing: 0.1em
```

#### Layout

Section titled “Layout”

Also known as “Layout & Spacing.” Describes the layout and spacing strategy — grid models, spacing scales, and containment principles.

```
## Layout

The layout follows a Fluid Grid model for mobile and a Fixed-Max-Width
Grid for desktop (max 1200px). A strict 8px spacing scale is used.
```

**Design tokens:** A `map<string, Dimension | number>` mapping the spacing scale identifier to a dimension or unitless number (e.g., column counts or ratios).

```
spacing:
  base: 16px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px
```

#### Elevation & Depth

Section titled “Elevation & Depth”

Also known as “Elevation.” Describes how visual hierarchy is conveyed. For designs that use shadows, it defines the shadow properties. For flat designs, it explains the alternative methods (borders, tonal layers, color contrast).

```
## Elevation & Depth

Depth is achieved through tonal layers rather than heavy shadows.
Background uses a soft off-white; primary content sits on pure white cards.
```

#### Shapes

Section titled “Shapes”

Describes how visual elements are shaped — corner radii, edge treatments, and the overall shape language.

```
## Shapes

All interactive elements use a minimal 4px corner radius.
Modern enough to feel current, rigid enough to feel engineered.
```

**Design tokens:** A `map<string, Dimension>` mapping the scale level to the corner radius.

```
rounded:
  sm: 4px
  md: 8px
  lg: 12px
  full: 9999px
```

#### Components

Section titled “Components”

Style guidance for component atoms. The spec defines common component types — Buttons, Chips, Lists, Inputs, Checkboxes, Radio buttons, Tooltips — but design systems are encouraged to define additional components relevant to their domain.

```
## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill, secondary uses outline
- **Inputs**: 1px border, surface-variant background, 12px padding
- **Cards**: No elevation, 1px outline border, 12px corner radius
```

**Design tokens:** A `map<string, map<string, string>>` mapping a component identifier to a group of sub-token properties. Token values may be literal values or references to previously defined tokens.

**Variants.** A component may have variants for different UI states (hover, active, pressed). Variants are defined as separate component entries with a related key name.

```
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"
```

##### Component property tokens

Section titled “Component property tokens”

| Property | Type |
| --- | --- |
| backgroundColor | Color |
| textColor | Color |
| typography | Typography |
| rounded | Dimension |
| padding | Dimension |
| size | Dimension |
| height | Dimension |
| width | Dimension |

#### Do’s and Don’ts

Section titled “Do’s and Don’ts”

Practical guidelines and common pitfalls. These act as guardrails during generation.

```
## Do's and Don'ts

- Do use the primary color only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen
```

### Consumer behavior for unknown content

Section titled “Consumer behavior for unknown content”

The spec is designed to be extended. When a consumer encounters content not defined by this specification:

| Scenario | Behavior | Example |
| --- | --- | --- |
| Unknown section heading | Preserve; do not error | ## Iconography |
| Unknown color token name | Accept if value is valid | surface-container-high: '#ede7dd' |
| Unknown typography token name | Accept as valid typography | telemetry-data |
| Unknown spacing value | Accept; store as string if not a valid dimension | grid-columns: '5' |
| Unknown component property | Accept with warning | borderColor |
| Duplicate section heading | Error; reject the file | Two ## Colors headings |

### Recommended token names

Section titled “Recommended token names”

The following names are commonly used across design systems. They are not required but are provided as guidance for consistency.

**Colors:** `primary`, `secondary`, `tertiary`, `neutral`, `surface`, `on-surface`, `error`

**Typography:** `headline-display`, `headline-lg`, `headline-md`, `body-lg`, `body-md`, `body-sm`, `label-lg`, `label-md`, `label-sm`

**Rounded:** `none`, `sm`, `md`, `lg`, `xl`, `full`
## View, edit, and export

Source: https://stitch.withgoogle.com/docs/design-md/usage/

Work with your design system in the Stitch UI. View tokens, tweak values, and export with your project.

### View the design system

Section titled “View the design system”

Open the **Design System** panel to see the active design system for any screen. The panel shows the resolved tokens: colors, fonts, roundedness, spacing, and component patterns.

If the project has multiple design systems, the panel displays the one applied to the currently selected screen.

### Set a default design system

Section titled “Set a default design system”

To apply a design system to all future screens in a project, select it as the project default. New screens generated after this point will automatically inherit its tokens.

Existing screens are not retroactively updated. To bring them into alignment, apply the design system to them individually.

### Edit via the Design System panel

Section titled “Edit via the Design System panel”

The Design System panel supports direct edits to the active design system. Changes you make here update both the structured tokens and the `DESIGN.md` summary.

Editable properties include:

- **Color palette**: primary, secondary, tertiary, and neutral base colors
- **Typography**: headline, body, and label font families
- **Roundedness**: corner radius scale

For more granular changes (component guidelines, do’s and don’ts, or the overview narrative), edit the `DESIGN.md` markdown directly.

### Export with your project

Section titled “Export with your project”

When you export a project, the `DESIGN.md` file is included in the zip alongside the generated screens. This gives downstream consumers (developers, other design tools, or other agents) a portable record of the design system.

The exported `DESIGN.md` is a standalone document. It doesn’t depend on Stitch to be useful.

### Working outside Stitch?

Section titled “Working outside Stitch?”

The [`@google/design.md` CLI](https://stitch.withgoogle.com/docs/design-md/cli/) validates any DESIGN.md file against the formal spec, checks WCAG contrast ratios, and exports tokens to Tailwind or W3C Design Token formats. It works with any DESIGN.md, whether it was generated by Stitch or written by hand.
## Validate with the CLI

Source: https://stitch.withgoogle.com/docs/design-md/cli/

Lint, diff, and export DESIGN.md files using the @google/design.md command-line tool.

The `@google/design.md` CLI validates your design system against the spec, catches broken token references, checks WCAG contrast ratios, and exports tokens to other formats — all as structured JSON that agents can act on.

### Install

Section titled “Install”

```
npm install @google/design.md
```

Or run directly without installing:

```
npx @google/design.md lint DESIGN.md
```

All commands accept a file path or `-` for stdin. Output defaults to JSON.

### Lint a DESIGN.md

Section titled “Lint a DESIGN.md”

Validate a DESIGN.md file for structural correctness. The linter parses the YAML front matter, resolves all token references, runs [8 lint rules](https://stitch.withgoogle.com/docs/design-md/linting-rules/), and reports findings.

```
npx @google/design.md lint DESIGN.md
```

Example output:

```
{
  "findings": [
    {
      "severity": "warning",
      "path": "colors",
      "message": "No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette."
    },
    {
      "severity": "info",
      "message": "Design system defines 4 colors, 3 typography scales, 2 rounding levels."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "infos": 1 }
}
```

Pipe from stdin if you’re generating DESIGN.md files programmatically:

```
cat DESIGN.md | npx @google/design.md lint -
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| file | positional | required | Path to DESIGN.md (or - for stdin) |
| --format | json \| text | json | Output format |

Exit code `1` if errors are found, `0` otherwise.

### Compare two versions

Section titled “Compare two versions”

Detect token-level changes between two DESIGN.md files. The `diff` command reports which tokens were added, removed, or modified, and flags regressions (more errors or warnings in the “after” file).

```
npx @google/design.md diff DESIGN.md DESIGN-v2.md
```

Example output:

```
{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1 },
    "after": { "errors": 0, "warnings": 2 },
    "delta": { "errors": 0, "warnings": 1 }
  },
  "regression": true
}
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| before | positional | required | Path to the “before” DESIGN.md |
| after | positional | required | Path to the “after” DESIGN.md |
| --format | json \| text | json | Output format |

Exit code `1` if regressions are detected.

### Export tokens

Section titled “Export tokens”

Convert DESIGN.md tokens to other formats for use in your codebase.

#### Tailwind CSS

Section titled “Tailwind CSS”

Generate a `theme.extend` configuration object:

```
npx @google/design.md export --format tailwind DESIGN.md
```

The output is a JSON object with `colors`, `fontFamily`, `fontSize`, `borderRadius`, and `spacing` mapped from your design tokens. Drop it into your `tailwind.config.js`.

#### DTCG (W3C Design Tokens)

Section titled “DTCG (W3C Design Tokens)”

Generate a [W3C Design Tokens Format Module](https://tr.designtokens.org/format/) compliant `tokens.json`:

```
npx @google/design.md export --format dtcg DESIGN.md
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| file | positional | required | Path to DESIGN.md |
| --format | tailwind \| dtcg | required | Export target format |

### View the spec

Section titled “View the spec”

Output the DESIGN.md format specification. This is useful for injecting spec context into agent prompts so the agent knows exactly what structure to produce.

```
npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| --rules | boolean | false | Append the active linting rules table |
| --rules-only | boolean | false | Output only the linting rules table |
| --format | markdown \| json | markdown | Output format |

### Programmatic API

Section titled “Programmatic API”

The linter is also available as a TypeScript library:

```
import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);      // Finding[]
console.log(report.summary);       // { errors, warnings, infos }
console.log(report.designSystem);  // Resolved DesignSystemState
console.log(report.tailwindConfig); // Generated Tailwind theme
```
## Linting rules

Source: https://stitch.withgoogle.com/docs/design-md/linting-rules/

The 8 rules the DESIGN.md linter enforces, what triggers each one, and how to resolve findings.

The `@google/design.md` linter runs rules against a parsed DESIGN.md file. Each rule produces findings at a fixed severity level: **error** (exit code 1), **warning**, or **info**.

### broken-ref

Section titled “broken-ref”

**Severity:** error

Detects token references (`{path.to.token}`) that do not resolve to any defined token in the YAML front matter. Also flags unknown component sub-token property names.

**Triggers when:**

- A component references a token path that does not exist (e.g., `{colors.accent}` when no `accent` color is defined)
- A component uses a property name not in the recognized set (`backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`)

**Example finding:**

```
error  components.button-primary  Reference {colors.accent} does not resolve to any defined token.
```

**Resolution:** Define the missing token in the YAML front matter, or correct the reference path. For unknown properties, use one of the recognized component sub-token names.

### missing-primary

Section titled “missing-primary”

**Severity:** warning

Warns when colors are defined in the front matter but no token named `primary` exists. Without a primary color, agents will auto-generate one, reducing your control over the palette.

**Triggers when:** The `colors` section has one or more entries, but none is named `primary`.

**Example finding:**

```
warning  colors  No 'primary' color defined. The agent will auto-generate key colors, reducing your control over the palette.
```

**Resolution:** Add a `primary` entry to the `colors` section.

### contrast-ratio

Section titled “contrast-ratio”

**Severity:** warning

Checks WCAG contrast ratios for component `backgroundColor` and `textColor` pairs. Warns when the ratio falls below the AA minimum of 4.5:1.

**Triggers when:** A component defines both `backgroundColor` and `textColor`, and the resolved color values produce a contrast ratio below 4.5:1.

**Example finding:**

```
warning  components.card-dark  textColor (#999999) on backgroundColor (#333333) has contrast ratio 3.48:1, below WCAG AA minimum of 4.5:1.
```

**Resolution:** Adjust either the background or text color to meet the 4.5:1 minimum ratio.

### orphaned-tokens

Section titled “orphaned-tokens”

**Severity:** warning

Identifies color tokens that are defined but never referenced by any component. Orphaned tokens add noise and may indicate an incomplete design system.

**Triggers when:** A color token exists in the `colors` section but is not referenced by any component’s properties. Only fires when at least one component is defined.

**Example finding:**

```
warning  colors.tertiary  'tertiary' is defined but never referenced by any component.
```

**Resolution:** Reference the token in a component, or remove it if it is no longer needed.

### missing-typography

Section titled “missing-typography”

**Severity:** warning

Warns when colors are defined but no typography tokens exist. Without typography tokens, agents will fall back to their own font choices.

**Triggers when:** The `colors` section has entries but the `typography` section is empty.

**Example finding:**

```
warning  typography  No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity.
```

**Resolution:** Add at least one typography token (e.g., `body-md`) to the front matter.

### section-order

Section titled “section-order”

**Severity:** warning

Warns when markdown sections appear out of the [canonical order](https://stitch.withgoogle.com/docs/design-md/specification/#section-order) defined by the spec. The expected sequence is: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts.

**Triggers when:** A recognized section heading appears before another recognized section that should precede it. Section aliases (e.g., “Elevation” for “Elevation & Depth”) are resolved before checking.

**Example finding:**

```
warning  Section 'Components' appears before 'Typography', which is out of order. Expected order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts
```

**Resolution:** Reorder the sections in the markdown body to match the canonical sequence.

### missing-sections

Section titled “missing-sections”

**Severity:** info

Notes when optional token sections (`spacing`, `rounded`) are absent from a file that already defines other tokens. These sections are not required, but their absence means agents will fall back to defaults.

**Triggers when:** The `colors` section has entries but `spacing` or `rounded` has no entries.

**Example finding:**

```
info  spacing  No 'spacing' section defined. Layout spacing will fall back to agent defaults.
```

**Resolution:** Add a `spacing` or `rounded` section to the front matter if you want explicit control over those values.

### token-summary

Section titled “token-summary”

**Severity:** info

Emits a summary diagnostic reporting how many tokens are defined in each section. This is purely informational.

**Example finding:**

```
info  Design system defines 4 colors, 3 typography scales, 2 rounding levels, 6 spacing tokens, 3 components.
```

### Summary

Section titled “Summary”

| Rule | Severity | What it checks |
| --- | --- | --- |
| broken-ref | error | Token references that don’t resolve; unknown component sub-tokens |
| missing-primary | warning | Colors defined but no primary exists |
| contrast-ratio | warning | Component backgroundColor/textColor below WCAG AA 4.5:1 |
| orphaned-tokens | warning | Color tokens defined but never referenced by a component |
| missing-typography | warning | Colors defined but no typography tokens exist |
| section-order | warning | Sections out of canonical order |
| missing-sections | info | Optional sections (spacing, rounded) absent |
| token-summary | info | Count of tokens defined per section |
## Get started with Agent Skills

Source: https://stitch.withgoogle.com/docs/skills/get-started/

Install the Stitch Design Skills, connect to the MCP server, and generate your first screen — all from your coding agent.

Stitch Design Skills are agent instructions that extend your coding agent with design superpowers — generating screens, extracting design systems, building multi-page sites, and converting designs to React components. They work with any agent that supports the [Agent Skills](https://agentskills.io/) standard: Gemini CLI, Claude Code, Cursor, or Antigravity.

### Install the plugin suite

Section titled “Install the plugin suite”

Run this from your project directory:

```
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code
```

This installs all three plugins (`stitch-design`, `stitch-build`, `stitch-utilities`) with 13 skills total.

#### Pick your agent target

Section titled “Pick your agent target”

```
# Claude Code
npx plugins add google-labs-code/stitch-skills --scope project --target claude-code

# Cursor
npx plugins add google-labs-code/stitch-skills --scope project --target cursor

# Gemini CLI
npx plugins add google-labs-code/stitch-skills --scope project --target gemini-cli

# Antigravity
npx plugins add google-labs-code/stitch-skills --scope project --target antigravity
```

#### Install selectively (optional)

Section titled “Install selectively (optional)”

If you only need specific skills:

```
npx skills add google-labs-code/stitch-skills --skills stitch::generate-design
```

> Many skills depend on each other. The `code-to-design` skill, for example, requires `extract-static-html`, `extract-design-md`, and `upload-to-stitch`. The full plugin install is the safer choice.

### Connect the Stitch MCP server

Section titled “Connect the Stitch MCP server”

The skills talk to Stitch through the [Model Context Protocol](https://modelcontextprotocol.io/). Follow the [Stitch MCP Setup Instructions](https://stitch.withgoogle.com/docs/mcp/setup/) to register the server and configure your API credentials.

Once connected, your agent gains access to tools like `list_projects`, `generate_screen_from_text`, and `get_screen`.

#### Verify the connection

Section titled “Verify the connection”

PROMPT

List my Stitch projects.

You should see your existing projects — or an empty list if this is your first time using Stitch. If you see an error, double-check that the MCP server is running and your API key is valid.

### Generate your first screen

Section titled “Generate your first screen”

Start with a rough idea. The `enhance-prompt` skill transforms vague concepts into structured, generation-ready prompts.

PROMPT

Enhance this prompt for Stitch: “Create a landing page for an artisanal coffee shop”

Notice the output — the skill adds a platform specification, structures the page into numbered sections, replaces vague terms with specific UI/UX keywords, and generates a design system block with color roles. This enhanced prompt produces dramatically better results than the original.

Now generate:

PROMPT

Generate a screen in my Stitch project using the enhanced prompt from the previous step.

This takes 15–30 seconds. When complete, you’ll see a confirmation with the screen ID and file paths. Open the generated screenshot to see your design — a complete landing page with hero section, feature cards, navigation, and footer, all from a single text prompt.

### What’s next

Section titled “What’s next”

You’ve installed skills, connected to Stitch, and generated your first screen. Here’s where to go from here:

- **[Import from your codebase](https://stitch.withgoogle.com/docs/design-md/get-instructions/)** — Extract a DESIGN.md from existing source code
- **[Code to Design roundtrip](https://stitch.withgoogle.com/docs/skills/roundtrip/)** — Import a React app into Stitch, edit the design, export back to components
- **[Build in a loop](https://stitch.withgoogle.com/docs/skills/build-in-a-loop/)** — Generate an entire website from a single concept
- **[Skill reference](https://stitch.withgoogle.com/docs/skills/reference/)** — Full catalog of all 13 skills

### Troubleshooting

Section titled “Troubleshooting”

| Problem | Fix |
| --- | --- |
| npx plugins not found | Install Node.js 18+: node --version |
| MCP server not responding | Verify setup: MCP Setup guide |
| Skills not visible in agent | Restart the agent session after installation |
| Permission errors | Use --scope project instead of --scope global |
| API key errors | Confirm the key in your agent’s MCP config hasn’t expired |
## Code to Design roundtrip

Source: https://stitch.withgoogle.com/docs/skills/roundtrip/

Import a React app into Stitch, edit the design visually, and export updated components — the full roundtrip.

The roundtrip workflow connects your codebase and Stitch in both directions. Start from a React app, extract its design system and screens into Stitch, make visual edits in the cloud, and export the updated designs back to clean React components.

### What you’ll build

Section titled “What you’ll build”

Starting from an existing React + Vite application, you’ll extract design tokens, capture screens as static HTML, upload everything to Stitch, edit the design, and convert it back to React components.

#### Prerequisites

Section titled “Prerequisites”

- Completed [Get started with skills](https://stitch.withgoogle.com/docs/agent-skills/get-started/) (skills installed, MCP connected)
- An existing React application with a working dev server
- Node.js 18+ and `puppeteer` installed

### Step 1: Extract design tokens from source

Section titled “Step 1: Extract design tokens from source”

Scan your source files to reverse-engineer a design system document — no build step required.

PROMPT

Extract the design system from ./my-app/src and write it to .stitch/DESIGN.md

The `extract-design-md` skill reads your components, stylesheets, Tailwind config, and theme files. It identifies colors, typography, spacing, and component patterns.

Open the resulting `.stitch/DESIGN.md` and you’ll see:

- **YAML frontmatter** with machine-readable color tokens
- **Markdown sections** describing visual atmosphere, palette, typography, and layout
- **Descriptive names** like “Deep Ocean Blue (#1a365d)” instead of raw hex codes

### Step 2: Capture static HTML snapshots

Section titled “Step 2: Capture static HTML snapshots”

Start your dev server, then capture the running app as self-contained HTML:

PROMPT

Extract static HTML from [http://localhost:5173](http://localhost:5173/) and save to .stitch/designs/home.html

The skill launches headless Chrome, captures the fully rendered DOM, inlines all CSS, and converts images to base64 data URIs. Each output file is completely self-contained — no external dependencies.

For multiple pages, repeat for each route:

PROMPT

Also extract [http://localhost:5173/about](http://localhost:5173/about) to .stitch/designs/about.html

### Step 3: Upload to Stitch

Section titled “Step 3: Upload to Stitch”

Push everything to a new Stitch project in one command:

PROMPT

Upload .stitch/DESIGN.md and all HTML files in .stitch/designs/ to a new Stitch project called “My App Migration”

The skill creates a project, uploads the DESIGN.md as a design system, and imports each HTML file as a screen. Open [Stitch](https://stitch.withgoogle.com/) to see your project with all the uploaded screens, styled according to your design system.

### Step 4: Edit the design

Section titled “Step 4: Edit the design”

Make targeted visual changes without touching code:

PROMPT

Edit the home screen: add a testimonial section between the features and the footer with three customer quotes in a horizontal card layout.

The skill calls `edit_screens` with your instruction while preserving the existing design system. One change at a time produces the best results — iterate with additional edits rather than bundling everything into one prompt.

### Step 5: Export back to React

Section titled “Step 5: Export back to React”

Convert the updated Stitch screens back to component code:

PROMPT

Convert the screens in my Stitch project to React components.

The `react-components` skill downloads the latest screen HTML, extracts Tailwind theme values, breaks the design into modular components, creates type-safe interfaces, moves static data into `src/data/mockData.ts`, and validates everything via AST.

Start your dev server — the React components now reflect the design changes you made in Stitch, including the new testimonial section.

### The full roundtrip

Section titled “The full roundtrip”

Here’s what you just completed:

| Step | Direction | What happened |
| --- | --- | --- |
| Extract tokens | Code → DESIGN.md | Reverse-engineered the design system from source |
| Capture HTML | Code → Static files | Snapshot the running app as self-contained HTML |
| Upload | Files → Stitch | Imported assets and design system to the cloud |
| Edit | Stitch → Updated design | Made targeted visual changes |
| Export | Stitch → React | Generated updated components from the design |

### What’s next

Section titled “What’s next”

- **[Import from your codebase](https://stitch.withgoogle.com/docs/design-md/get-instructions/)** — More options for extracting design systems, including a quick prompt that needs no skills
- **[Create a premium design system](https://stitch.withgoogle.com/docs/agent-skills/premium-design-system/)** — Generate a curated design system with anti-generic standards
- **[Why semantic tokens?](https://stitch.withgoogle.com/docs/agent-skills/semantic-tokens/)** — Understand why descriptive design language works better for AI than raw CSS
## Build in a loop

Source: https://stitch.withgoogle.com/docs/skills/build-in-a-loop/

The stitch-loop autonomous build cycle generates entire websites page by page. Define the vision and design system once — the skill handles the rest.

The `stitch-loop` skill generates entire websites page by page, automatically. You define the vision and design system upfront. The skill handles the rest — generating each page, wiring navigation, and queuing the next task.

### How the baton loop works

Section titled “How the baton loop works”

A relay baton file at `.stitch/next-prompt.md` defines the current page to generate. After each page, the skill updates the baton with the next task. This creates a self-sustaining build cycle.

**State files the skill manages:**

| File | Purpose |
| --- | --- |
| .stitch/next-prompt.md | Current task (the baton) |
| .stitch/SITE.md | Site vision, sitemap, and roadmap |
| .stitch/DESIGN.md | Design system for visual consistency |
| .stitch/metadata.json | Stitch project and screen IDs |

### Step 1: Define the site vision

Section titled “Step 1: Define the site vision”

Create `.stitch/SITE.md` describing your site:

```
# Site: Artisan Coffee Co.

## Vision
A 5-page portfolio website for a specialty coffee roaster.

## Sitemap
- [ ] index — Landing page with hero and featured blends
- [ ] about — Origin story and roasting philosophy
- [ ] menu — Coffee menu with categories and pricing
- [ ] locations — Store locations with map
- [ ] contact — Contact form and hours
```

### Step 2: Establish a design system

Section titled “Step 2: Establish a design system”

Set visual consistency before generating any pages. The preferred approach — generate a premium design system:

PROMPT

Generate a DESIGN.md for an artisanal coffee brand using the taste-design skill. Warm tones, editorial typography, generous whitespace.

Or extract from an existing codebase:

PROMPT

Extract the design system from ./existing-site/src into .stitch/DESIGN.md

### Step 3: Write the first baton

Section titled “Step 3: Write the first baton”

Create `.stitch/next-prompt.md` for the first page:

```
---
page: index
---
A warm, editorial landing page for Artisan Coffee Co.

**DESIGN SYSTEM (REQUIRED):**
[Paste from .stitch/DESIGN.md]

**Page Structure:**
1. Header with logo and navigation links to about, menu, locations, contact
2. Hero section with full-width image, headline, and primary CTA
3. Featured blends section with three product cards
4. Testimonial section with customer quote
5. Footer with address, social links, and copyright
```

### Step 4: Run the loop

Section titled “Step 4: Run the loop”

PROMPT

Read .stitch/next-prompt.md and execute the stitch-loop build cycle.

The skill generates the screen via Stitch, downloads HTML and screenshots, moves the HTML to `site/public/`, updates the sitemap, and writes the next baton. Repeat the same prompt for each subsequent page — the baton drives the cycle forward.

### Navigation and consistency

Section titled “Navigation and consistency”

The skill automatically wires internal links across pages, adds new pages to the global navigation, and maintains consistent headers and footers.

If navigation drifts after several pages:

PROMPT

Update all page headers to include links to: index, about, menu, locations, contact.

### Tips for better results

Section titled “Tips for better results”

- **Edit rather than regenerate.** If a page is close but not right, targeted edits preserve more context than starting over.
- **Check the design system.** Visual drift usually means the DESIGN.md wasn’t included in the prompt.
- **Compare screenshots.** After generating multiple pages, ask the agent to compare them for visual consistency.

### Orchestration options

Section titled “Orchestration options”

| Method | How it works |
| --- | --- |
| Manual | Run the agent repeatedly with the same prompt |
| Human-in-loop | Review each page before continuing |
| CI/CD | Trigger on .stitch/next-prompt.md changes |
| Agent chains | One agent dispatches to another via the baton file |
## Generate walkthrough videos

Source: https://stitch.withgoogle.com/docs/skills/walkthrough-videos/

Create professional walkthrough videos from Stitch project screens using Remotion with animated transitions.

The `remotion` skill turns your Stitch project screens into polished walkthrough videos — complete with cross-fade transitions, spring-animated zoom effects, and text overlays. Useful for demos, stakeholder reviews, or documentation.

### Prerequisites

Section titled “Prerequisites”

- A Stitch project with at least 2 designed screens
- Node.js and npm installed
- Access to the Stitch MCP server

### Retrieve screens

Section titled “Retrieve screens”

PROMPT

List all screens in Stitch project projects/123456 and download their screenshots.

The skill fetches screen metadata via MCP, downloads full-resolution screenshots to `assets/screens/`, and creates a `screens.json` manifest with titles, dimensions, and per-screen durations.

### Set up and generate

Section titled “Set up and generate”

If no Remotion project exists, the skill creates one. Then configure your transitions:

#### Fade (default)

Section titled “Fade (default)”

Smooth cross-fades between screens. Best for calm, professional presentations.

PROMPT

Use fade transitions between all screens with 15 frames overlap.

#### Slide

Section titled “Slide”

Directional slides for sequential user flows:

PROMPT

Use slide transitions from left to right to show the user journey.

#### Zoom

Section titled “Zoom”

Spring-animated zoom effects for emphasizing specific features:

PROMPT

Add a zoom-in effect on the hero section of the home screen before transitioning to the features page.

Mix and match — use fades for most screens and a zoom to highlight a key moment.

### Add text overlays

Section titled “Add text overlays”

#### Screen titles

Section titled “Screen titles”

PROMPT

Add the screen title as a bottom overlay on each slide, fading in after 0.5 seconds.

#### Feature callouts

Section titled “Feature callouts”

PROMPT

Add a pulsing circle highlighting the search bar on the navigation screen.

#### Progress indicator

Section titled “Progress indicator”

PROMPT

Add a thin progress bar at the top showing the current position in the walkthrough.

### Render the video

Section titled “Render the video”

Preview first in the browser-based Remotion Studio:

PROMPT

Start the Remotion Studio to preview the walkthrough video.

Then render to file:

PROMPT

Render the walkthrough video as walkthrough.mp4 with H.264 codec.

#### Quality options

Section titled “Quality options”

| Flag | Effect |
| --- | --- |
| --quality 100 | Maximum quality (larger file) |
| --codec h264 | Best compatibility |
| --codec h265 | Better compression, less compatibility |
| --concurrency 4 | Parallel rendering for speed |

### Adjusting pacing

Section titled “Adjusting pacing”

- **Too fast?** Increase per-screen duration in `screens.json` (default is 3–5 seconds)
- **Too slow?** Reduce duration or add more dynamic transitions
- **Uneven?** Set longer durations for complex screens, shorter for simple ones

PROMPT

Set the dashboard screen duration to 6 seconds and the login screen to 3 seconds.

### Troubleshooting

Section titled “Troubleshooting”

| Issue | Fix |
| --- | --- |
| Blurry screenshots | Append =w{width} to download URLs for full resolution |
| Choppy animations | Increase frame rate to 60fps |
| Misaligned text overlays | Match composition dimensions to screen dimensions |
| Remotion build fails | Check Node version compatibility; run npm install |
## Taste

Source: https://stitch.withgoogle.com/docs/skills/taste/

Generate a DESIGN.md that actively prevents generic AI aesthetics — calibrated color, distinctive typography, and explicit anti-patterns.

This excellent Agent Skill was contributed by a community member, Leon Lin.

Leonxlnx / taste-skill Star

Portable Agent Skills that upgrade AI-built interfaces: stronger layout, typography, motion, and spacing

Markdown Leonxlnx/taste-skill

Most AI-generated interfaces converge on the same look: oversaturated purple gradients, centered three-column cards, `Inter` font, fabricated statistics. The `taste-design` skill generates design systems that explicitly ban these patterns and enforce premium standards.

### When to use taste-design

Section titled “When to use taste-design”

| Skill | What it does | Philosophy |
| --- | --- | --- |
| extract-design-md | Reverse-engineers tokens from source code | Descriptive — documents what exists |
| design-md | Extracts tokens from existing Stitch screens | Descriptive — documents what exists |
| taste-design | Generates a design system from a concept | Prescriptive — enforces premium standards |

Use `taste-design` when starting fresh and you want a design system that stands above the AI-generated average.

### Generate a premium DESIGN.md

Section titled “Generate a premium DESIGN.md”

PROMPT

Generate a premium DESIGN.md for a high-density financial analytics dashboard using the taste-design skill.

The output includes visual atmosphere calibrated on the taste spectrum, strict anti-pattern rules, calibrated color science, opinionated typography, and spring-physics motion specifications.

### Color calibration

Section titled “Color calibration”

Colors use HSL with intentionally restrained saturation. This reflects a principle from print design: sophisticated palettes use low-saturation colors for large surfaces and reserve high saturation for small, intentional accents.

**Rules the skill enforces:**

- Accent saturation stays below 80% — no oversaturated neon
- Pure black (`#000000`) is banned — use off-blacks like Zinc-950 (`#18181B`)
- Maximum one accent color — forces visual discipline

#### Adjusting the palette

Section titled “Adjusting the palette”

PROMPT

Adjust the DESIGN.md accent color to a deep teal (#0D9488) and warm the neutrals toward sand tones.

### Typography

Section titled “Typography”

The skill uses musical interval ratios for the type scale — the same harmonic relationships that make musical intervals sound natural:

| Scale | Ratio | Character |
| --- | --- | --- |
| Minor Third | 1.200 | Compact, information-dense |
| Major Third | 1.250 | Balanced, versatile |
| Perfect Fourth | 1.333 | Generous, editorial |
| Golden Ratio | 1.618 | Dramatic, high-impact |

**Font pairing rules:**

- `Inter` is banned in premium contexts — too ubiquitous
- Recommended sans-serif: `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`
- Recommended modern serif: `Fraunces`, `Gambarino`, `Editorial New`
- Dashboard constraint: sans-serif + monospace only (`Geist` + `Geist Mono`)

PROMPT

Use Outfit for display headlines and Geist for body text with Geist Mono for data.

### Spatial rhythm

Section titled “Spatial rhythm”

Every margin, padding, and gap is a multiple of the base unit (typically 4px or 8px). This creates spatial relationships the eye perceives as orderly even when asymmetric.

#### Adjusting density

Section titled “Adjusting density”

The taste spectrum ranges from 1 (airy) to 10 (cockpit-dense):

PROMPT

Generate a DESIGN.md at density 8 — this is a monitoring dashboard that needs to display many metrics simultaneously.

Higher density triggers monospace numbers for alignment, border-top dividers instead of cards, tighter spacing ratios, and flat surfaces distinguished by typography rather than shadow.

### The taste scoring rubric

Section titled “The taste scoring rubric”

Evaluate your DESIGN.md across four dimensions. A premium design scores 7+ across all four:

| Dimension | What it measures |
| --- | --- |
| Color Sophistication | Palette restraint, saturation discipline, contrast intentionality |
| Typographic Craft | Font distinctiveness, scale harmony, weight hierarchy |
| Spatial Coherence | Base unit consistency, rhythm, responsive scaling |
| Visual Hierarchy | Clear primary/secondary/tertiary levels, information architecture |

If any dimension feels weak:

PROMPT

The typographic hierarchy feels flat. Increase the weight contrast between headlines and body, and add letter-spacing differentiation.

### Anti-pattern checklist

Section titled “Anti-pattern checklist”

Before finalizing, verify these are absent:

- ❌ No emojis in the design
- ❌ No `Inter` font
- ❌ No pure black (`#000000`)
- ❌ No neon outer glow shadows
- ❌ No 3-column equal card layouts
- ❌ No fabricated metrics (“99.98% UPTIME”, “124ms AVG. RESPONSE”)
- ❌ No AI copywriting clichés (“Elevate”, “Seamless”, “Unleash”)
- ❌ No filler UI text (“Scroll to explore”, bouncing chevrons)
- ❌ No `LABEL // YEAR` formatting patterns
## Skill reference

Source: https://stitch.withgoogle.com/docs/skills/reference/

All Stitch Skills — what they do, which tools they use, and how to invoke them.

The Stitch Design Skills are organized into three plugins. Each skill follows the [Agent Skills](https://agentskills.io/) open standard and works with any compatible coding agent.

### stitch-design

Section titled “stitch-design”

Core design workflows for creating, capturing, and managing designs.

#### code-to-design

Section titled “code-to-design”

Orchestrates the full import pipeline: detect framework → extract static HTML → extract design tokens → upload to Stitch.

PROMPT

Upload the frontend at ./dashboard into Stitch project “Dashboard Migration”.

**Dependencies:** `extract-static-html`, `extract-design-md`, `upload-to-stitch`

#### generate-design

Section titled “generate-design”

Generates new screens from text or images, edits existing screens, and creates design variants.

PROMPT

Make a browse tab for a mobile dating app with card-based profiles.

**MCP tools:** `generate_screen_from_text`, `edit_screens`, `generate_variants`, `list_projects`, `create_project`, `list_design_systems`

#### manage-design-system

Section titled “manage-design-system”

Uploads DESIGN.md specifications, creates project-level design systems, and applies them to screens.

PROMPT

Upload .stitch/DESIGN.md and create a design system for project 123456.

**MCP tools:** `create_design_system_from_design_md`, `apply_design_system`, `list_design_systems`, `upload_design_md`

#### extract-design-md

Section titled “extract-design-md”

Reverse-engineers a `DESIGN.md` from frontend source code — React, Vue, Svelte, Angular, plain CSS, or Tailwind. No build step required.

PROMPT

Extract the design system from ./my-app/src and write it to .stitch/DESIGN.md

**Pipeline:** Scan source tree → Detect framework → Extract tokens → Normalize → Deduplicate → Generate DESIGN.md

#### extract-static-html

Section titled “extract-static-html”

Captures self-contained HTML snapshots from running web applications, inlining CSS and converting images to base64.

PROMPT

Extract a static snapshot of [http://localhost:5173](http://localhost:5173/) and save to .stitch/home.html

#### upload-to-stitch

Section titled “upload-to-stitch”

Uploads local assets (images, HTML) to the Stitch REST API via a standalone script that bypasses LLM output token limits.

PROMPT

Upload landing_page.html to Stitch project projects/987654321.

### stitch-build

Section titled “stitch-build”

Code generation and media compilation from Stitch designs.

#### react-components

Section titled “react-components”

Converts Stitch screens to modular React component hierarchies with Tailwind theme extraction and AST-based validation.

PROMPT

Convert all screens in project projects/123 to React components.

#### remotion

Section titled “remotion”

Generates walkthrough videos from Stitch projects using Remotion with spring-animated zoom effects and configurable transitions. See [Generate walkthrough videos](https://stitch.withgoogle.com/docs/agent-skills/walkthrough-videos/).

PROMPT

Create a walkthrough video of the Calculator App Stitch project.

#### shadcn-ui

Section titled “shadcn-ui”

Expert guidance for integrating shadcn/ui components — discovery, installation, and customization with Radix UI and Tailwind CSS.

PROMPT

Set up shadcn/ui and build a data table with sorting and pagination.

### stitch-utilities

Section titled “stitch-utilities”

Quality enhancement at both ends of the pipeline.

#### design-md

Section titled “design-md”

Analyzes existing Stitch project screens and synthesizes a `DESIGN.md` from the rendered output. This is the _design → tokens_ direction (as opposed to `extract-design-md` which is _code → tokens_).

PROMPT

Analyze Stitch project 123456 and generate a DESIGN.md capturing its visual identity.

**MCP tools:** `list_screens`, `get_screen`, `upload_design_md`, `list_projects`, `get_project`

#### enhance-prompt

Section titled “enhance-prompt”

Transforms vague ideas into structured, generation-ready prompts with UI/UX keywords, design system context, and page structure.

PROMPT

Enhance this prompt: “make a settings page”

#### stitch-loop

Section titled “stitch-loop”

Orchestrates autonomous multi-page site generation using a relay baton pattern. See [Build a multi-page site](https://stitch.withgoogle.com/docs/agent-skills/multi-page-site/).

PROMPT

Read .stitch/next-prompt.md and execute the stitch-loop build cycle.

#### taste-design

Section titled “taste-design”

Generates premium `DESIGN.md` files with anti-generic standards — calibrated color science, musical-interval type scales, spring physics motion, and an explicit anti-pattern catalog. See [Create a premium design system](https://stitch.withgoogle.com/docs/agent-skills/premium-design-system/).

PROMPT

Generate a premium DESIGN.md for a high-density financial analytics cockpit.

### Installing individual skills

Section titled “Installing individual skills”

The full plugin suite is the recommended install. If you need specific skills only:

```
# Design only (generate and edit screens)
npx skills add google-labs-code/stitch-skills \
  --skills stitch::generate-design,stitch::manage-design-system,enhance-prompt

# Import existing code (full migration pipeline)
npx skills add google-labs-code/stitch-skills \
  --skills stitch::code-to-design,stitch::extract-design-md,stitch::extract-static-html,stitch::upload-to-stitch

# Code generation (Stitch to React)
npx skills add google-labs-code/stitch-skills \
  --skills react:components,shadcn-ui
```

> Many skills have inter-dependencies. Check the dependency listings above before installing selectively.