How to Apply Design System Tokens to Multiple Screens Using manage-design-system

The manage-design-system skill lets you propagate design tokens across screens by calling apply_design_system with a project ID, design system asset ID, and an array of selected screen instances containing only id and sourceScreen fields.

The manage-design-system skill in the google-labs-code/stitch-skills repository provides a programmatic way to apply design system tokens to multiple screens simultaneously. This workflow ensures consistent theming—colors, typography, roundness, and custom tokens—across your entire Stitch project without manually updating each screen. The process involves retrieving the correct identifiers, preparing the design system asset, and executing a targeted application call.

Prerequisites: Retrieve Project and Screen IDs

Before applying tokens, you must obtain the project ID, screen instance IDs, and design system asset ID. These identifiers are retrieved through separate API calls that inspect your Stitch project structure.

First, call get_project to fetch all screen instances within your project. Then, filter out any design system instances (which have a type of DESIGN_SYSTEM_INSTANCE) to target only the screens you want to theme. Finally, retrieve the design system asset ID using list_design_systems.

# Retrieve project details and screen instances

project = get_project(project_id="<PROJECT_ID>")
screen_instances = project["screenInstances"]

# Build target list excluding design system instances

targets = [
    {"id": si["id"], "sourceScreen": si["sourceScreen"]}
    for si in screen_instances
    if si.get("type") != "DESIGN_SYSTEM_INSTANCE"
]

# Get the design system asset ID

design_systems = list_design_systems(projectId="<PROJECT_ID>")
asset_id = design_systems[0]["name"].split("/")[-1]  # Extract from 'assets/abcd' format

Creating or Updating the Design System

If you haven't already created a design system, upload a DESIGN.md file and invoke create_design_system_from_design_md. This stores your token definitions at the project level. For existing design systems, use update_design_system to modify token values.

The design system asset holds all token definitions—including colorMode, headlineFont, roundness, and customColor—that will be inherited by target screens.

Applying the Design System to Multiple Screens

The core operation uses the apply_design_system MCP tool. This tool accepts a specific JSON payload structure that maps the design system to multiple screen instances in a single operation.

Required Payload Structure

The apply_design_system tool requires three parameters:

• projectId: Your Stitch project identifier
• assetId: The design system asset identifier (obtained from list_design_systems)
• selectedScreenInstances: An array of objects containing only id and sourceScreen fields

Critical constraint: Including geometry fields or positional data in selectedScreenInstances causes an "invalid argument" error. Only the id and sourceScreen fields are accepted according to the schema defined in plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md.

{
  "projectId": "<PROJECT_ID>",
  "assetId": "<DESIGN_SYSTEM_ASSET_ID>",
  "selectedScreenInstances": [
    {
      "id": "<SCREEN_INSTANCE_ID_1>",
      "sourceScreen": "projects/<PROJECT_ID>/screens/<SCREEN_ID_1>"
    },
    {
      "id": "<SCREEN_INSTANCE_ID_2>",
      "sourceScreen": "projects/<PROJECT_ID>/screens/<SCREEN_ID_2>"
    }
  ]
}

Example Implementation

You can execute this via command line using the MCP tool or embed it within a Stitch skill workflow.

Command line execution:

apply_design_system \
  --project-id "<PROJECT_ID>" \
  --asset-id "$asset_id" \
  --selected-screen-instances "$(jq -c '.' <<<"$targets")"

Direct JSON payload example:

{
  "projectId": "4044680601076201931",
  "assetId": "c277fcdfc1e04baf91b92d975ff4c54a",
  "selectedScreenInstances": [
    {
      "id": "98b50e2ddc9943efb387052637738f61",
      "sourceScreen": "projects/4044680601076201931/screens/98b50e2ddc9943efb387052637738f61"
    },
    {
      "id": "ab12cd34ef56789012345678abcdef01",
      "sourceScreen": "projects/4044680601076201931/screens/ab12cd34ef56789012345678abcdef01"
    }
  ]
}

When successful, each listed screen immediately inherits the design system tokens defined in your DESIGN.md file.

Key Source Files and References

The workflow is defined across several files in the google-labs-code/stitch-skills repository:

• plugins/stitch-design/skills/manage-design-system/SKILL.md: Complete documentation for retrieval, creation, and application steps
• plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md: JSON schemas and example payloads for apply_design_system, create_design_system_from_design_md, and update_design_system
• plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py: Helper script for uploading DESIGN.md files and extracting screen IDs
• plugins/stitch-design/skills/manage-design-system/examples/metadata.json: Example project-level metadata structure including design system summaries

Summary

• Use get_project to retrieve screen instance IDs and list_design_systems to obtain the design system asset ID
• Include only id and sourceScreen in the selectedScreenInstances array; omit geometry fields to avoid validation errors
• Call apply_design_system with the project ID, asset ID, and target screen array to propagate tokens to multiple screens simultaneously
• Reference tool-schema.md for exact payload specifications and validation rules

Frequently Asked Questions

What fields are required in the selectedScreenInstances array?

Each object in the selectedScreenInstances array must contain exactly two fields: id (the screen instance identifier) and sourceScreen (the full resource path like projects/<PROJECT_ID>/screens/<SCREEN_ID>). Including additional fields such as position coordinates or size data will trigger an "invalid argument" error when calling apply_design_system.

How do I find the design system asset ID?

Call the list_design_systems tool with your projectId parameter. The response includes a name field formatted as assets/<ASSET_ID>. Extract the ID portion after the slash to use as your assetId parameter in apply_design_system.

Can I apply a design system to every screen in my project at once?

Yes. When building your selectedScreenInstances array, iterate through all screen instances returned by get_project while filtering out any entries where type equals DESIGN_SYSTEM_INSTANCE. This ensures you target only content screens, not the design system definition itself.

What happens to existing screen styles when I apply a design system?

The screen inherits all token definitions defined in the design system asset—including colorMode, headlineFont, roundness, and custom color tokens. These values override any previous design system associations, applying the new token set consistently across all specified screens.

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