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

> Learn to manage and apply design systems in Stitch with this workflow guide. Master asset retrieval, token synthesis, DESIGN.md uploads, and screen application.

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

---

**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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file that follows 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).

## 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`](https://github.com/google-labs-code/stitch-skills/blob/main/upload_to_stitch.py)** script instead.

### The Upload Script

Located at [`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), this script:

1. Reads the [`DESIGN.md`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file
2. Base64-encodes the content
3. Calls the `BatchCreateScreens` REST endpoint directly

```python

# 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.

```json
{
  "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`](https://github.com/google-labs-code/stitch-skills/blob/main/tool-schema.md) specification.

```json
{
  "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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) via the design-md utility, mapping natural language to concrete tokens
- **Upload**: Use [`upload_to_stitch.py`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/upload_to_stitch.py) script located at [`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). 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`](https://github.com/google-labs-code/stitch-skills/blob/main/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`](https://github.com/google-labs-code/stitch-skills/blob/main/DESIGN.md) file following the schema defined in [`tool-schema.md`](https://github.com/google-labs-code/stitch-skills/blob/main/tool-schema.md).