/manage-design-system

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.