Stitch::Manage Design System

Design-System

Create a "source of truth" for your project's design language to ensure consistency across all future screens.

[!NOTE]

Refer to your system prompt for instruction on handling MCP tool prefixes for

all tools mentioned in this skill (e.g., get_screen,

create_design_system_from_design_md, apply_design_system).

📥 Retrieval

To analyze a Stitch project, you must retrieve metadata and assets using the Stitch MCP tools:

1. Project lookup: Use list_projects to find the target projectId. 2. Screen lookup: Use list_screens for that projectId to find representative screens (e.g., "Home", "Main Dashboard"). 3. Metadata fetch: Call get_screen for the target screen to get screenshot.downloadUrl and htmlCode.downloadUrl. 4. Asset download: Use read_url_content to fetch the HTML code.

🧠 Synthesis from Description

If you need to extract a design system from existing screens, use the design-md skill (in the stitch-utilities plugin).

If there are no existing screens (new project), or the user provides a direct description (e.g., "dark theme, blue and purple, rounded, Inter font"):

1. Map the user's vague terms to precise values using the design mappings (see design-md skill in stitch-utilities or generate-design skill). 2. Select concrete hex codes, font families, and roundness values. 3. Generate the DESIGN.md file (refer to the design-md skill in stitch-utilities for structure). 4. Proceed to the "Create or Update Design System in Stitch" step below.

📝 Output Structure

The DESIGN.md file should follow the structure defined in the design-md skill (in the stitch-utilities plugin).

🚀 Create or Update Design System in Stitch

After generating .stitch/DESIGN.md, make sure to also create or update the design system in Stitch.

Two-step design system creation:

[!WARNING]

Checkpoint — User Confirmation Required.

Before uploading, you MUST pause and ask the user for

confirmation. Present a summary of the design system you are about to create

(display name, key colors, fonts, and roundness) and wait for explicit approval

before proceeding. Do NOT upload until the user confirms.

1. Upload `DESIGN.md`:

• Option A (Recommended - Uploader Script): Use the modified upload-to-stitch Python script which natively handles .md files. It base64-encodes the markdown file in-process and sends it to the /v1/projects/{projectId}/screens:batchCreate endpoint, bypassing output token limits.

     python3 stitch-skills/plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \
       --project-id <PROJECT_ID> \
       --file-path /path/to/DESIGN.md \
       --api-key <API_KEY> \
       --generated-by <GENERATED_BY>

Set <GENERATED_BY> to identify the skill or tool that produced the DESIGN.md. Use the calling skill name when invoked from another skill (e.g. stitch::code-to-design), or the agent/tool name for standalone use (e.g. Gemini, Claude Code). If omitted, the script defaults to UserUploadedDesignMd.

This returns the sourceScreen ID and the screenInstance ID.

• Option B (Direct MCP Tool): If the DESIGN.md is small (under ~5KB), you can call the upload_design_md MCP tool directly, passing the base64-encoded design markdown content as designMdBase64.

2. Create Design System: Call the create_design_system_from_design_md tool immediately after the upload, passing the projectId and the selectedScreenInstance (containing the id and sourceScreen returned from the upload step).

Once the upload script and create_design_system_from_design_md have both completed, Stitch holds the design tokens at the project level — you do NOT need to repeat them in generation prompts.

🎨 Apply Design System to Screens

Use apply_design_system to apply a design system to existing screens.

[!IMPORTANT]

selectedScreenInstances must contain only id and sourceScreen — do

NOT include position/dimension fields (x, y, width, height) or the

request will fail with "invalid argument". Get the screen instance IDs from

get_project.

{
  "projectId": "...",
  "assetId": "...",
  "selectedScreenInstances": [
    {
      "id": "...",
      "sourceScreen": "projects/.../screens/..."
    }
  ]
}

How to get the required IDs: 1. Call get_project to retrieve screenInstances — each has an id and sourceScreen. 2. Call list_design_systems to retrieve the design system name (format: assets/{assetId}) — use the part after assets/ as the assetId. 3. Filter out any instances with type: "DESIGN_SYSTEM_INSTANCE" — only pass real screens.

📋 Update Project Metadata

After writing .stitch/DESIGN.md, also create or update .stitch/metadata.json to track the projectId, title, all known screens, and design system summary. See examples/metadata.json for the format.

Schema Reference

See reference/tool-schema.md for the full designSystem object schema with all available options.

💡 Best Practices

Refer to the design-md skill (in the stitch-utilities plugin) for best practices on describing design elements.

Design System Tool Schemas

Use these examples to format your Stitch MCP design system tool calls correctly.

---

Upload DESIGN.md (via upload_to_stitch.py script)

Uploads a DESIGN.md file to a project via the BatchCreateScreens endpoint. This is the first step in creating a design system from a markdown file.

[!NOTE]

Use the upload-to-stitch skill's script instead of the upload_design_md

MCP tool. The script handles base64 encoding in-process, avoiding the model's

output token limit.

python3 <SKILL_DIR>/scripts/upload_to_stitch.py \
  --project-id <PROJECT_ID> \
  --file-path /path/to/DESIGN.md \
  --api-key <API_KEY>

---

create_design_system_from_design_md

Creates a design system for a project using the uploaded DESIGN.md file.

{
  "projectId": "4044680601076201931",
  "selectedScreenInstance": {
    "id": "98b50e2ddc9943efb387052637738f61",
    "sourceScreen": "projects/4044680601076201931/screens/98b50e2ddc9943efb387052637738f61"
  },
  "deviceType": "DESKTOP"
}

[!NOTE]

You must upload DESIGN.md via the script first to get the source screen ID, and then fetch the project details with get_project to find the corresponding screen instance ID to pass as id in selectedScreenInstance.

---

update_design_system

Updates an existing design system for a project. This is required immediately after calling create_design_system to set the theme and display the design system in the UI.

[!NOTE]

While update_design_system is mandatory after the basic create_design_system call, you do not need to call it after create_design_system_from_design_md. The latter automatically populates and updates all theme tokens directly from the parsed YAML frontmatter of the uploaded DESIGN.md.

{
  "name": "assets/15996705518239280238",
  "projectId": "4044680601076201931",
  "designSystem": {
    "displayName": "My Design System",              // OPTIONAL. Display name of the design system
    "theme": {                                      // REQUIRED. The design theme object
      "colorMode": "LIGHT",                         // REQUIRED. Options: LIGHT, DARK
      "headlineFont": "INTER",                      // REQUIRED. Options: INTER, ROBOTO, OPEN_SANS, LATO, MONTSERRAT, NOTO_SANS, NOTO_SERIF, etc.
      "bodyFont": "INTER",                          // REQUIRED. Same font options as headlineFont
      "labelFont": "INTER",                         // OPTIONAL. Same font options as headlineFont
      "roundness": "ROUND_EIGHT",                   // REQUIRED. Options: ROUND_FOUR, ROUND_EIGHT, ROUND_TWELVE, ROUND_FULL
      "customColor": "#0EA5E9",                   // REQUIRED. Primary brand color / seed color for dynamic color system (hex)
      "colorVariant": "FIDELITY",                   // OPTIONAL. Options: FIDELITY, TONAL, VIBRANT, EXPRESSIVE, CONTENT, MONOCHROME, FRUIT_SALAD, RAINBOW
      "overridePrimaryColor": "#996e47",          // OPTIONAL. Override primary color (hex)
      "overrideSecondaryColor": "#0EA5E9",        // OPTIONAL. Override secondary color (hex)
      "overrideTertiaryColor": "#c4956a",         // OPTIONAL. Override tertiary color (hex)
      "overrideNeutralColor": "#0D0D0D",          // OPTIONAL. Override neutral color (hex)
      "designMd": "# Design System..."              // OPTIONAL. Markdown string with detailed design system spec
    }
  }
}

Field Reference

Required Fields

Optional Fields

Font Options

The following font enum values are confirmed to work (server-validated):

[!WARNING]

Omit the legacy font field when updating the design system to avoid "invalid argument" errors.

[!NOTE]

The namedColors object above is abbreviated. The full response contains 50+

Material 3 color tokens including all container, fixed, and inverse variants.

---

apply_design_system

Applies a design system to one or more screens in a project.

[!IMPORTANT]

selectedScreenInstances must contain only id and sourceScreen — do NOT

include position/dimension fields (x, y, width, height) or the request

will fail with "invalid argument". Get the screen instance IDs from

get_project.

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

How to get the required IDs: 1. Call get_project to retrieve screenInstances — each has an id and sourceScreen. 2. Call list_design_systems to retrieve the design system name (format: assets/{assetId}) — use the part after assets/ as the assetId. 3. Filter out any instances with type: "DESIGN_SYSTEM_INSTANCE" — only pass real screens.