How to Manage and Apply Design Systems in Stitch: A Complete Workflow Guide

Stitch's design-system workflow uses the stitch::manage-design-system skill to orchestrate four stages: retrieving project assets, synthesizing design tokens, uploading a DESIGN.md file, and applying the system to screens via MCP tools.

Stitch from Google Labs provides a structured workflow for managing and applying design systems in Stitch through the stitch::manage-design-system skill defined in plugins/stitch-design/skills/manage-design-system/SKILL.md. This system separates data acquisition, design definition, and application into discrete stages using Model Context Protocol (MCP) tools and utility scripts.

Retrieving Project Assets

Before generating a design system, you must fetch metadata for the target project and representative screens. According to the source code in plugins/stitch-design/skills/manage-design-system/SKILL.md, the retrieval process follows a specific sequence:

• list_projects – Enumerates available projects
• list_screens – Lists screens within the target project
• get_screen – Retrieves specific screen metadata
• read_url_content – Downloads the HTML content of a screen for analysis

This four-step retrieval process (steps 1-4 in the skill file) ensures the system has sufficient context to generate accurate design tokens.

Synthesizing Design Specifications

Once assets are retrieved, the workflow synthesizes design tokens. If a design system already exists, the skill extracts it via the design-md utility found in the stitch-utilities plugin.

When creating a new system from a text description (e.g., "dark theme, blue accents, rounded corners"), the skill maps these vague terms to concrete tokens using design-md mappings. The output is a DESIGN.md file that follows the schema defined in plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md.

Creating and Uploading the Design System

Because MCP tool arguments are constrained by token budgets, the upload process bypasses direct tool invocation and uses the upload_to_stitch.py script instead.

The Upload Script

Located at plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py, this script:

1. Reads the DESIGN.md file
2. Base64-encodes the content
3. Calls the BatchCreateScreens REST endpoint directly

# Example: Upload a DESIGN.md file

# Run from command line:

python3 upload_to_stitch.py \
  --project-id 1234567890123456789 \
  --file-path path/to/DESIGN.md \
  --api-key $STITCH_API_KEY \
  --generated-by stitch::manage-design-system

Creating the System

After upload, the skill calls create_design_system_from_design_md, passing the projectId and the screenInstance returned by the upload step. This automatically populates the design-system tokens; an additional update_design_system call is not required in this path.

{
  "projectId": "1234567890123456789",
  "selectedScreenInstance": {
    "id": "<SCREEN_INSTANCE_ID>",
    "sourceScreen": "projects/1234567890123456789/screens/<SCREEN_ID>"
  },
  "deviceType": "DESKTOP"
}

Applying Design Systems to Screens

The final stage applies the newly-created design system to existing screens using the apply_design_system tool. The request payload must contain only the id and sourceScreen fields for each target screen, as defined in the tool-schema.md specification.

{
  "projectId": "1234567890123456789",
  "assetId": "<DESIGN_SYSTEM_ASSET_ID>",
  "selectedScreenInstances": [
    {"id": "a1b2c3", "sourceScreen": "projects/123.../screens/a1b2c3"},
    {"id": "d4e5f6", "sourceScreen": "projects/123.../screens/d4e5f6"}
  ]
}

The required IDs are obtained via get_project (for screenInstances) and list_design_systems (for the assetId).

Summary

• Retrieval: Use list_projects → list_screens → get_screen to fetch project metadata before synthesis
• Synthesis: Generate DESIGN.md via the design-md utility, mapping natural language to concrete tokens
• Upload: Use upload_to_stitch.py to base64-encode and upload files directly to the BatchCreateScreens endpoint
• Creation: Call create_design_system_from_design_md with the project ID and screen instance to populate tokens automatically
• Application: Invoke apply_design_system with target screen IDs and design system asset ID to update existing screens

Frequently Asked Questions

How does Stitch handle large DESIGN.md files that exceed token limits?

Stitch handles large files through the upload_to_stitch.py script located at plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py. This script reads the markdown file, base64-encodes it, and calls the BatchCreateScreens REST endpoint directly, bypassing the MCP tool argument constraints entirely.

What is the difference between create_design_system_from_design_md and update_design_system?

When using the create_design_system_from_design_md tool after uploading a DESIGN.md file, the system automatically populates all design tokens based on the uploaded specification. An additional update_design_system call is not required in this creation path. The update_design_system tool is used for modifying existing design systems rather than initial creation.

How do I obtain the assetId needed for apply_design_system?

The assetId required for the apply_design_system tool is obtained by calling list_design_systems on your project. This returns the design system identifier that you then pass to the apply_design_system call along with your target screen instances.

Can I create a design system from a text description without existing screens?

Yes. The stitch::manage-design-system skill can generate a design system from natural language descriptions (e.g., "dark theme with blue accents") using the design-md utility in the stitch-utilities plugin. This utility maps vague descriptive terms to concrete design tokens and produces a valid DESIGN.md file following the schema defined in tool-schema.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}