How to Batch Apply a Design System Across All Project Screens in Stitch

To batch apply a design system across all project screens in Stitch, upload a DESIGN.md file using the provided script, create the design system via the create_design_system_from_design_md MCP tool, retrieve all screen instance IDs while filtering out DESIGN_SYSTEM_INSTANCE types, extract the assetId from list_design_systems, and call apply_design_system with the project ID, assetId, and an array of screen instances containing only id and sourceScreen fields.

Stitch by Google Labs stores visual styling information in a centralized Design System object that can be attached to any screen instance. If you need to enforce brand consistency across multiple screens, you can batch apply a design system across all project screens in Stitch using a specific MCP workflow. This process involves parsing a DESIGN.md file, extracting screen metadata, and invoking the batch application tool with strictly formatted parameters.

Prerequisites: Uploading the DESIGN.md File

Before batch-applying styles, you must create and upload your design specification. Stitch uses a DESIGN.md file to define theme tokens including fonts, colors, and roundness values.

According to the source code in plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md, you upload this file using the helper script located at plugins/stitch-design/skills/manage-design-system/scripts/upload_to_stitch.py:

python3 plugins/stitch-design/skills/manage-design-system/scripts/upload_to_stitch.py \
  --project-id <PROJECT_ID> \
  --file-path .stitch/DESIGN.md \
  --api-key <API_KEY>

If you don't have a DESIGN.md file yet, you can generate one from existing screens using the utility documented in plugins/stitch-utilities/skills/design-md/SKILL.md.

Step-by-Step Batch Application

Once uploaded, follow this four-step MCP workflow to apply the design system to every screen in your project.

Step 1: Create the Design System from DESIGN.md

Call the create_design_system_from_design_md tool to parse the uploaded markdown and populate theme tokens. The payload requires the projectId, a selectedScreenInstance object containing the source screen's id and sourceScreen fields, and a deviceType:

create_design_system_from_design_md = {
    "projectId": "<PROJECT_ID>",
    "selectedScreenInstance": {
        "id": "<SOURCE_SCREEN_INSTANCE_ID>",
        "sourceScreen": "projects/<PROJECT_ID>/screens/<SOURCE_SCREEN_INSTANCE_ID>"
    },
    "deviceType": "DESKTOP"
}

This creates the design system asset in your project.

Step 2: Retrieve Project Screen Instances

To target all screens, call the get_project MCP endpoint and extract the screenInstances array. You must filter out any instances where type equals DESIGN_SYSTEM_INSTANCE, as these represent the design system definitions themselves, not UI screens that should receive styling.

project = get_project("<PROJECT_ID>")  # MCP call

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

This ensures you only collect valid target screens.

Step 3: Extract the Design-System Asset ID

Call list_design_systems to retrieve available design systems. The system returns a name field formatted as assets/<assetId>. Extract the ID segment for the next step:

design_systems = list_design_systems("<PROJECT_ID>")  # MCP call

# Example returned name: "assets/9f2c1d7e8a5b4c6d"

asset_id = design_systems[0]["name"].split("/")[-1]

Step 4: Apply the Design System to All Screens

Finally, invoke the apply_design_system tool with the projectId, the extracted assetId, and the selectedScreenInstances array. Critical: The payload must contain only the id and sourceScreen fields for each screen. Including geometry fields like x, y, width, or height will trigger an "invalid argument" error.

apply_design_system_payload = {
    "projectId": "<PROJECT_ID>",
    "assetId": asset_id,
    "selectedScreenInstances": screen_instances
}

# Send this JSON to the MCP `apply_design_system` method.

The schema for this call is documented in plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md under the apply_design_system section.

Critical Implementation Details

When preparing the batch request, strictly adhere to these constraints defined in the Stitch source code:

• Field Restriction: The selectedScreenInstances array must contain objects with only two keys: id and sourceScreen. Any additional properties from the get_project response—such as x, y, width, or height—must be stripped before calling apply_design_system.
• Type Filtering: Always exclude screens where type is DESIGN_SYSTEM_INSTANCE. Attempting to apply a design system to these internal screens will cause errors.
• Asset ID Format: The assetId passed to apply_design_system must be the raw UUID extracted from the assets/ prefix in the list_design_systems response.

Summary

• Upload your DESIGN.md using plugins/stitch-design/skills/manage-design-system/scripts/upload_to_stitch.py before creating the design system.
• Use create_design_system_from_design_md to parse the design tokens and create the system asset.
• Retrieve screen instances via get_project and filter out DESIGN_SYSTEM_INSTANCE types to avoid targeting internal screens.
• Extract the raw assetId from the list_design_systems response by parsing the assets/<assetId> string.
• Call apply_design_system with strictly formatted screen instances containing only id and sourceScreen fields to batch apply the design system across all project screens.

Frequently Asked Questions

What fields are required in the selectedScreenInstances array for batch application?

The selectedScreenInstances array must contain objects with exactly two fields: id and sourceScreen. According to the schema in plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md, including additional fields like x, y, width, or height will result in an "invalid argument" error when calling apply_design_system.

How do I exclude design system screens from the batch update?

When retrieving screens via the get_project MCP endpoint, filter the screenInstances array to exclude any objects where the type property equals DESIGN_SYSTEM_INSTANCE. These represent the design system definitions themselves rather than UI screens that should receive styling.

What causes an "invalid argument" error when calling apply_design_system?

This error occurs when the selectedScreenInstances payload contains extraneous geometry fields. The apply_design_system tool strictly validates inputs and only accepts id and sourceScreen. Ensure your code strips all other properties from the screen instances retrieved via get_project before making the batch application call.

Can I apply a design system to mobile and desktop screens simultaneously?

Yes, provided the screens are valid instances in your project. The apply_design_system tool processes the selectedScreenInstances array regardless of device type, as long as each entry contains the correct id and sourceScreen values. However, when creating the design system initially via create_design_system_from_design_md, you must specify a single deviceType (e.g., "DESKTOP" or "MOBILE").

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