Google Stitch — AI UI Design Integration¶

STATUS: active (VERSION PINNED — see KNOWN ISSUES) OWNER: alexander (Design System Engineer) ALSO_USED_BY: floris, floor, dima CATEGORY: third-party-integration COST: free (Google Labs) ADDED: 2026-03-20 UPDATED: 2026-03-27 — v0.5.1 blocked, pinned to v0.4.0. Session corruption incident.

WHAT IS STITCH¶

Google Stitch is an AI-powered UI design platform from Google Labs. Generates high-fidelity UI designs from text prompts or images. Powered by Gemini 3 (Pro or Flash). Outputs HTML/CSS + screenshots. React conversion via Stitch Skills. Has MCP server for programmatic access from agents. Has DESIGN.md — agent-friendly markdown for design system import/export. Completely free.

URL: https://stitch.withgoogle.com SDK: @google/stitch-sdk MCP CLI: @_davideast/stitch-mcp Stitch Skills: https://github.com/google-labs-code/stitch-skills

WHY GE USES STITCH¶

Alexander cannot generate visual mockups — LLMs can't design. Stitch bridges the gap: Alexander writes text descriptions → Stitch generates visual UI. DESIGN.md maps directly to GE's wiki brain approach (agent-friendly markdown). MCP server allows Alexander to call Stitch programmatically during task execution. Free = aligns with intern-pricepoint mission.

Design Pipeline Role¶

Layer 1 (80%): Standard screens → shadcn/ui + DESIGN.md tokens (no Stitch needed)
Layer 2 (15%): Custom screens → Alexander describes → Stitch generates → human reviews
Layer 3 (5%):  Premium/complex → external designer with DESIGN.md constraints

Stitch is the engine for Layer 2.

AUTHENTICATION¶

Method: API Key (recommended for GE)¶

Stitch supports two auth methods: 1. API Key — simple, no OAuth dance. Recommended. 2. Application Default Credentials (ADC) — Google Cloud IAM. Overkill for GE's use.

Get API Key¶

Go to https://stitch.withgoogle.com
Sign in with Google account
Settings → Generate API Key
Copy key

Store in Vault¶

vault kv put admin-ui/api-keys/stitch api_key="STITCH_API_KEY_HERE"

Vault path: admin-ui/api-keys/stitch:api_key Follows GE pattern: nested path for non-standard providers.

NOTE: Stitch API key is SEPARATE from Gemini API key. Gemini key (at admin-ui/api-keys:google) is for LLM inference. Stitch key is for the design platform. Different service, different key.

ADMIN-UI INTEGRATION¶

1. Add to API Management page¶

File: admin-ui/app/(dashboard)/api-management/page.tsx

Add to providers array:

{
  id: 'stitch',
  name: 'Google Stitch (Design AI)',
  vaultPath: 'admin-ui/api-keys/stitch',
  vaultKey: 'api_key',
  color: 'bg-blue-100 text-blue-700',
  description: 'AI UI design generation — used by Alexander for custom screen design',
}

2. Add Vault getter (optional convenience)¶

File: admin-ui/lib/vault/client.ts

export async function getStitchApiKey(): Promise<string | null> {
  return getSecret('admin-ui/api-keys/stitch', 'api_key');
}

3. Add to billing providers¶

SQL migration:

INSERT INTO service_providers (id, name, category, markup_multiplier, cost_unit)
VALUES ('stitch', 'Google Stitch', 'design', 1.00, 'request');

NOTE: markup 1.00 because Stitch is free. Track usage for analytics only.

EXECUTOR INTEGRATION (for Alexander agent)¶

Alexander needs Stitch tools available during task execution. Two options: MCP server in executor, or SDK calls in agent_runner.py.

Option A: MCP Server (recommended)¶

The @_davideast/stitch-mcp proxy exposes Stitch as MCP tools. Add to executor's MCP config so Alexander's sessions have Stitch available.

Environment variable in executor pod:

env:
  - name: STITCH_API_KEY
    valueFrom:
      secretKeyRef:
        name: ge-secrets
        key: stitch-api-key

MCP config for Alexander's sessions:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["@_davideast/stitch-mcp", "proxy"]
    }
  }
}

Option B: SDK in Python executor¶

If executor needs to call Stitch from Python (not via MCP): Use the REST API directly — Stitch SDK is TypeScript-only.

Not recommended. Prefer MCP approach.

AVAILABLE MCP TOOLS¶

The proxy exposes three high-level virtual tools:

build_site¶

Maps project screens to routes, returns design HTML per page.

{
  "projectId": "string",
  "routes": [
    { "screenId": "string", "route": "/" },
    { "screenId": "string", "route": "/about" }
  ]
}

get_screen_code¶

Retrieves a screen's HTML code. Input: { "projectId": "string", "screenId": "string" } Output: HTML string

get_screen_image¶

Retrieves a screen's screenshot as base64. Input: { "projectId": "string", "screenId": "string" } Output: base64 PNG

SDK TOOLS (via @google/stitch-sdk)¶

Lower-level tools available when using the SDK directly:

Tool	Purpose
`create_project`	Create a new Stitch project
`generate_screen_from_text`	Generate a screen from a text prompt
`edit_screen`	Edit an existing screen with new prompt
`get_screen`	Retrieve screen data
`generate_variants`	Generate multiple design variants

Key Parameters¶

Device types: MOBILE, DESKTOP, TABLET, AGNOSTIC Models: GEMINI_3_PRO (higher quality), GEMINI_3_FLASH (faster) Variant creative range: REFINE, EXPLORE, REIMAGINE Variant aspects: LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, TEXT_CONTENT

DESIGN.MD — THE BRIDGE¶

DESIGN.md is Stitch's agent-friendly design system format. It documents design tokens, rules, and constraints in markdown. Can be exported from any URL or created manually. Can be imported into Stitch to constrain generation.

GE Workflow¶

Dima captures brand brief from client
Alexander creates DESIGN.md with:
Color palette (primary, secondary, accent, neutrals)
Typography (heading font, body font, scale)
Spacing scale
Border radii
Component style rules
DESIGN.md saved to wiki/docs/clients/{client}/{project}/design/DESIGN.md
DESIGN.md imported into Stitch project → all generated screens follow the system
DESIGN.md also consumed by Floris/Floor for manual component work

Example DESIGN.md¶

# Design System — {Client} {Project}

## Colors
- Primary: #2563EB (blue-600)
- Secondary: #7C3AED (violet-600)
- Accent: #F59E0B (amber-500)
- Background: #FFFFFF
- Surface: #F9FAFB (gray-50)
- Text: #111827 (gray-900)
- Muted: #6B7280 (gray-500)

## Typography
- Headings: Inter, 700 weight
- Body: Inter, 400 weight
- Mono: JetBrains Mono
- Scale: 14/16/18/20/24/30/36/48

## Spacing
- Base: 4px
- Scale: 4/8/12/16/24/32/48/64

## Borders
- Radius: 6px (sm), 8px (md), 12px (lg)
- Default border: 1px solid gray-200

## Components
- Buttons: rounded-md, medium padding, primary uses bg-primary text-white
- Cards: rounded-lg, border, shadow-sm, padding-6
- Inputs: rounded-md, border, padding-3, focus ring primary
- Tables: simple borders, striped rows, sticky header

STITCH SKILLS (React conversion)¶

Stitch Skills are add-on capabilities:

react:components¶

Converts Stitch HTML screens to React component systems. Handles: design token extraction, component splitting, prop interfaces. Source: https://github.com/google-labs-code/stitch-skills

design-system-synthesis¶

Analyzes a Stitch project and generates comprehensive DESIGN.md. Useful for reverse-engineering a design system from existing screens.

INSTALLATION CHECKLIST¶

[x] Generate Stitch API key at https://stitch.withgoogle.com/settings (2026-03-27)
[x] Store in Vault: secret/data/admin-ui/api-keys/stitch (2026-03-27)
[x] Add to k8s secret ge-secrets: key stitch-api-key (2026-03-27)
[ ] Add to admin-ui API Management page (providers array)
[ ] Add Vault getter in vault/client.ts
[ ] Add billing provider row (free, track usage only)
[x] Install @_davideast/stitch-mcp in executor Dockerfile (2026-03-27)
[x] Add MCP config for Alexander: /ge-ops/master/mcp-configs/alexander.json (2026-03-27)
[ ] Install @google/stitch-sdk if direct SDK access needed
[x] Test: npx @_davideast/stitch-mcp doctor — PASSED (2026-03-27)
[ ] Test: create project + generate screen via MCP proxy
[ ] Verify Stitch output renders correctly in browser
[ ] Rebuild executor image with Stitch MCP (bash build-executor.sh)
[ ] Apply updated executor-deployment.yaml (STITCH_API_KEY env var)
[ ] Verify from executor pod: MCP tools available in Alexander sessions

TROUBLESHOOTING¶

Auth errors: Verify API key is set. Run npx @_davideast/stitch-mcp doctor. Permission errors: Ensure Google account has Stitch access (free signup). Network from k3s: Stitch API is external (stitch.googleapis.com). Ensure egress allowed. Rate limits: Stitch is free but may have undocumented rate limits. Monitor 429 responses. HTML/CSS only: Stitch does NOT output React directly. Use Stitch Skills react:components or v0 API for conversion. Large projects: Keep Stitch projects focused (1 project per client project, screens grouped by flow).

READ_ALSO: development/integrations/ (other third-party integrations) READ_ALSO: development/contracts/config-authority.md (where config lives) READ_ALSO: clients/{client}/{project}/design/DESIGN.md (per-project design systems)