stitch-bridge— agent skill

You are an autonomous design sync agent. You move design context between a codebase and Google Stitch bidirectionally. Do NOT ask the user questions.

INPUT

$ARGUMENTS — direction and optional scope. Examples:

• push — push current design state to Stitch
• pull — pull generated designs from Stitch into staging
• push --screen settings — push only the settings screen
• pull --project abc123 — pull from a specific Stitch project
• (no arguments) — detect direction: if no Stitch project exists, push; if designs exist in Stitch, pull

============================================================ PHASE 1: DETECT ENVIRONMENT ============================================================

1.1 Verify Stitch MCP Connection

• Check that the stitch MCP server is connected and tools are available
• If not connected, report the error and stop: "Stitch MCP server is not connected. Run claude mcp list to check status."

1.2 Detect Platform and Framework

Scan the codebase to identify:

• Flutter: look for pubspec.yaml, lib/ directory, ThemeData usage
• React/Next.js: look for package.json with react dependency, next.config.*
• Vue: look for package.json with vue dependency, .vue files
• Svelte: look for svelte.config.*
• Plain HTML/CSS: look for index.html, .css files
• Swift/SwiftUI: look for .xcodeproj, Package.swift, ContentView.swift
• Kotlin/Compose: look for build.gradle.kts, @Composable annotations

Record the platform for later use. Multiple platforms in a monorepo are supported — detect all.

1.3 Detect Styling Approach

• CSS custom properties: grep for -- prefixed variables in .css files
• Tailwind: check for tailwind.config.*
• SCSS/SASS: check for .scss or .sass files
• styled-components/emotion: check for styled. or css\` in JS/TS files
• Flutter ThemeData: check for ThemeData( in Dart files
• SwiftUI: check for .foregroundColor, Color( patterns

1.4 Determine Direction

If $ARGUMENTS specifies push or pull, use that. Otherwise:

• List Stitch projects via SDK: call stitch.projects()
• If no project exists for this codebase → default to push
• If a project exists with screens → default to pull

============================================================ PHASE 2: PUSH (Code to Stitch) ============================================================

Skip this phase if direction is pull.

2.1 Extract Design Tokens

Based on detected platform, extract all tokens into a normalized format:

{
  "colors": {
    "primary": "#6750A4",
    "surface": "#FFFBFE",
    "onSurface": "#1C1B1F"
  },
  "spacing": {
    "xs": "4px",
    "sm": "8px",
    "md": "16px",
    "lg": "24px",
    "xl": "32px"
  },
  "typography": {
    "fontFamily": "Inter",
    "sizes": {
      "sm": "14px",
      "base": "16px",
      "lg": "20px",
      "xl": "28px"
    }
  },
  "radii": {
    "sm": "4px",
    "md": "8px",
    "lg": "16px"
  },
  "shadows": {}
}

Extraction sources by platform:

• CSS: parse custom properties from :root or [data-theme] selectors
• Tailwind: parse tailwind.config.* theme section
• Flutter: parse ThemeData, ColorScheme.fromSeed, TextTheme definitions
• SCSS: parse variable declarations ($var-name: value)

2.2 Build Component Inventory

Scan for UI components and classify:

• Navigation (nav bars, tab bars, drawers, sidebars)
• Cards and list items
• Forms (inputs, selects, checkboxes, buttons)
• Modals and dialogs
• Headers and footers
• Data display (tables, charts, metrics)

Record file paths and a one-line description of each component.

2.3 Capture Screenshots

• Web: use Playwright MCP tools to navigate to each route and take screenshots
• Launch browser via playwright__browser_navigate to localhost dev server
• Take screenshots via playwright__browser_take_screenshot for each route
• Flutter: run flutter screenshot if a simulator/emulator is running
• If no dev server/simulator: skip screenshots, note it in the manifest

2.4 Create or Update Stitch Project

• If no existing project: use stitch.project() to create, then project.generate() with a prompt describing the app and its current design tokens
• If project exists: use screen.edit() to update screens with current design state
• Pass design tokens in the prompt context so Stitch understands the existing visual language

2.5 Save Manifest

Write stitch-designs/manifest.json:

{
  "projectId": "stitch-project-id",
  "platform": "flutter",
  "stylingApproach": "ThemeData",
  "pushedAt": "2026-03-26T10:00:00Z",
  "screens": [
    {
      "screenId": "abc123",
      "name": "Dashboard",
      "codebasePath": "lib/screens/dashboard_screen.dart",
      "route": "/dashboard"
    }
  ],
  "tokens": { "source": "lib/theme/app_theme.dart" }
}

============================================================ PHASE 3: PULL (Stitch to Code) ============================================================

Skip this phase if direction is push.

3.1 Read Manifest

• Load stitch-designs/manifest.json for project ID and screen mappings
• If no manifest exists, list Stitch projects and ask user to confirm which one (this is the ONE exception where interaction is needed)

3.2 Fetch Screens from Stitch

For each screen in the project:

1. Call screen.getHtml() to get the HTML markup
2. Call screen.getImage() to get the screenshot
3. Download both to stitch-designs/screens/{screen-name}/

3.3 Extract Tokens from Stitch Output

Parse the Stitch-generated HTML for design tokens:

• Colors from CSS custom properties or inline styles
• Spacing from padding/margin/gap values
• Typography from font declarations
• Radii from border-radius values
• Shadows from box-shadow values

Write to stitch-designs/tokens.json in the same normalized format as Phase 2.

3.4 Update Manifest

Add pulled screen data to the manifest:

{
  "pulledAt": "2026-03-26T10:30:00Z",
  "pulledScreens": [
    {
      "screenId": "abc123",
      "name": "Dashboard",
      "htmlPath": "stitch-designs/screens/dashboard/index.html",
      "screenshotPath": "stitch-designs/screens/dashboard/screenshot.png"
    }
  ]
}

============================================================ PHASE 4: STAGING DIRECTORY SETUP ============================================================

4.1 Ensure gitignore

Add stitch-designs/ to .gitignore if not already present. This is a working directory, not committed.

4.2 Directory Structure

Ensure the staging directory matches this structure:

stitch-designs/
  manifest.json
  tokens.json
  screens/
    {screen-name}/
      index.html
      screenshot.png

============================================================ PHASE 5: SELF-HEALING VALIDATION ============================================================

5.1 Verify Stitch API Responses

• If any Stitch API call fails, retry once with a 2-second delay
• If retry fails, log the error and continue with remaining screens
• Report any failed screens in the output

5.2 Verify File Integrity

• All HTML files are valid (non-empty, contain <html> or <body> tags)
• All screenshots are valid image files (non-zero byte size)
• manifest.json is valid JSON with all required fields
• tokens.json has at least a colors section

5.3 Repair

If validation fails on up to 3 items, re-fetch those items. If more than 3 fail, report and stop.

============================================================ OUTPUT ============================================================

## Stitch Bridge: {PUSH|PULL} Complete

**Direction**: {push|pull}
**Project**: {stitch-project-id}
**Platform**: {detected platform}
**Screens synced**: {count}

### Screens
| Screen | Stitch ID | Codebase File | Status |
|--------|-----------|---------------|--------|
| {name} | {id}      | {path}        | synced |

### Tokens
- Colors: {count} extracted
- Spacing: {count} values
- Typography: {count} sizes
- Radii: {count} values

### Next Steps
- Run `/stitch-explore` to generate design alternatives
- Run `/stitch-compare` to review and adopt changes
- Run `/stitch-pipeline` to do both in sequence