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

> Learn how to apply design system tokens to multiple screens with the manage-design-system skill. Propagate tokens efficiently across your project using apply_design_system and screen IDs.

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

---

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

```python

# 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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/manage-design-system/reference/tool-schema.md).

```json
{
  "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:**

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

```

**Direct JSON payload example:**

```json
{
  "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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py)**: Helper script for uploading [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) files and extracting screen IDs
- **[`plugins/stitch-design/skills/manage-design-system/examples/metadata.json`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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.