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

> Learn how to batch apply a design system to all Stitch project screens with a DESIGN.md file and script. Streamline your workflow efficiently. Get started now!

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-12

---

**To batch apply a design system across all project screens in Stitch, upload a [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/manage-design-system/scripts/upload_to_stitch.py):

```bash
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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file yet, you can generate one from existing screens using the utility documented in [`plugins/stitch-utilities/skills/design-md/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/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`:

```python
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.

```python
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:

```python
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.

```python
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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) using [`plugins/stitch-design/skills/manage-design-system/scripts/upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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").