stitch-sdk-usage

WHEN YOUR AGENT SHOULD USE IT

A QUICK BOUNDARY

USE FOR

Generate a UI screen from a plain-text prompt and fetch its HTML and screenshot.
Create a screen directly from an uploaded mockup image instead of a text prompt.
Apply a shared design system's theme across a set of existing screens.
Call a Stitch MCP tool directly by name from an agent instead of the typed domain classes.
Catch SDK errors and branch on whether the failure is safe to retry.

Documents

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

Using the Stitch SDK

The Stitch SDK provides a TypeScript interface for Google Stitch, an AI-powered UI generation service.

Installation

npm install @google/stitch-sdk

Environment Variables

export STITCH_API_KEY="your-api-key"

Quick Start

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

const project = await stitch.createProject("My App");
const screen = await project.generate("A settings page with dark theme");
const html = await screen.getHtml(); // download URL for the HTML
const imageUrl = await screen.getImage(); // download URL for the screenshot

The stitch singleton reads STITCH_API_KEY from the environment and connects on first use — no setup code required.

Working with Projects

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

// List all projects
const projects = await stitch.projects();

// Reference a project by ID (no network call)
const project = stitch.project("4044680601076201931");

// Create a new project
const newProject = await stitch.createProject("My App");

Design Systems

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

// List design systems
const systems = await project.listDesignSystems();

// Reference by ID (no network call)
const dsRef = project.designSystem("existing-asset-id");

// Update a design system
const updated = await ds.update({ displayName: "Updated Theme" });

// Apply to screens (requires SelectedScreenInstance objects from project.data.screenInstances)
const screens = await ds.apply([
  { id: "instance-id", sourceScreen: "projects/123/screens/456" },
]);

Uploading Images

Upload an existing image file (PNG, JPG, JPEG, WEBP) to create a screen directly from a mockup or asset.

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

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

// Upload a local image file
const [screen] = await project.uploadImage("./mockup.png", {
  title: "Home Screen",
});

console.log(screen.id);
const html = await screen.getHtml();
const imageUrl = await screen.getImage();

The method reads the file from disk and posts it directly to the Stitch REST API — no output token constraints apply (unlike agent-driven MCP calls).

Supported formats: .png, .jpg, .jpeg, .webp

Options:

Option	Type	Default	Description
`title`	`string`	—	Display title for the created screen
`createScreenInstances`	`boolean`	`true`	Whether to add the screen to the canvas

Throws StitchError with codes: NOT_FOUND (file not found), UNKNOWN_ERROR (unsupported format or upload failure), AUTH_FAILED (invalid API key).

Generating and Iterating on Screens

// Generate a new screen from a prompt
const screen = await project.generate(
  "Login page with email and password fields",
);

// Edit an existing screen
const edited = await screen.edit("Make the background dark and add a subtitle");

// Generate variants of a screen
const variants = await screen.variants("Try different color schemes", {
  variantCount: 2,
  creativeRange: "EXPLORE",
  aspects: ["COLOR_SCHEME", "LAYOUT"],
});

Retrieving Screen Assets

// Get screen HTML download URL
const html = await screen.getHtml();

// Get screen screenshot download URL
const imageUrl = await screen.getImage();

Both methods use cached data from the generation response when available, falling back to an API call when needed.

Dynamic Tool Client (for agents)

For agents and orchestration scripts that forward JSON payloads to MCP tools:

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

// Find available tools
const { tools } = await stitch.listTools();
for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}
// Call a tool with a JSON payload
const result = await stitch.callTool("generate_screen_from_text", {
  projectId: "123",
  prompt: "A login page",
});
await stitch.close();

Error Handling

All SDK methods throw StitchError on failure. Use try/catch:

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

try {
  const project = stitch.project("bad-id");
  await project.screens();
} catch (e) {
  if (e instanceof StitchError) {
    console.log(e.code); // "AUTH_FAILED", "NOT_FOUND", etc.
    console.log(e.message); // Human-readable description
    console.log(e.recoverable); // Whether retrying might succeed
  }
}

Error codes: AUTH_FAILED, NOT_FOUND, PERMISSION_DENIED, RATE_LIMITED, NETWORK_ERROR, VALIDATION_ERROR, UNKNOWN_ERROR

API Reference

Stitch Class

Method	Returns	Description
`createProject(title)`	`Promise<Project>`	Create a new project
`projects()`	`Promise<Project[]>`	List all projects
`project(id)`	`Project`	Reference a project by ID (no network call)

Project Class

Method	Returns	Description
`generate(prompt, deviceType?)`	`Promise<Screen>`	Generate a screen from a text prompt
`screens()`	`Promise<Screen[]>`	List all screens in the project
`getScreen(screenId)`	`Promise<Screen>`	Retrieve a specific screen by ID
`uploadImage(filePath, opts?)`	`Promise<Screen[]>`	Upload an image file and create a screen from it
`createDesignSystem(designSystem)`	`Promise<DesignSystem>`	Create a design system for this project
`listDesignSystems()`	`Promise<DesignSystem[]>`	List all design systems
`designSystem(id)`	`DesignSystem`	Reference by ID (no API call)

deviceType: "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"

uploadImage supported formats: .png .jpg .jpeg .webp

DesignSystem Class

Method	Returns	Description
`update(designSystem)`	`Promise<DesignSystem>`	Update the design system's theme
`apply(selectedScreenInstances)`	`Promise<Screen[]>`	Apply this design system to screens

Screen Class

Method	Returns	Description
`getHtml()`	`Promise<string>`	Get the screen's HTML download URL
`getImage()`	`Promise<string>`	Get the screen's screenshot download URL
`edit(prompt, deviceType?, modelId?)`	`Promise<Screen>`	Edit the screen using a text prompt
`variants(prompt, options, deviceType?, modelId?)`	`Promise<Screen[]>`	Generate variants of the screen

modelId: "GEMINI_3_PRO" | "GEMINI_3_FLASH"

StitchToolClient (for agents)

Method	Returns	Description
`callTool(name, args)`	`Promise<T>`	Call any MCP tool by name
`listTools()`	`Promise<Tools>`	Discover available tools
`connect()`	`Promise<void>`	Establish MCP connection (auto-called by callTool)
`close()`	`Promise<void>`	Close the connection

Explicit Configuration

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

const client = new StitchToolClient({
  apiKey: "your-api-key",
  baseUrl: "https://stitch.googleapis.com/mcp",
  timeout: 300_000,
});

const sdk = new Stitch(client);
const projects = await sdk.projects();

Option	Env Variable	Description
`apiKey`	`STITCH_API_KEY`	API key for authentication
`accessToken`	`STITCH_ACCESS_TOKEN`	OAuth access token
`projectId`	`GOOGLE_CLOUD_PROJECT`	GCP project ID (required with OAuth)
`baseUrl`	—	MCP server URL (default: `https://stitch.googleapis.com/mcp`)
`timeout`	—	Request timeout in ms (default: 300000)

Installation

Install this skill from google-labs-code/stitch-sdk on GitHub, not from a copy somewhere else. The command below does this for you.

Copy & paste — that's it

npx skills add google-labs-code/stitch-sdk --skill "stitch-sdk-usage" --full-depth

Run this in your project — your agent picks the skill up automatically.

BEFORE IT WILL WORK

1 FOR YOU

01
Set a Stitch API key
Export STITCH_API_KEY, or STITCH_ACCESS_TOKEN plus GOOGLE_CLOUD_PROJECT for OAuth, since the stitch singleton reads it on first use.

License

Licensed under Apache-2.0— you can use, modify, and redistribute it under that license's terms.

View the full license file on GitHub →