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:

• Project lookup: Use list_projects to find the target projectId.
• Screen lookup: Use list_screens for that projectId to find

representative screens (e.g., "Home", "Main Dashboard").

• Metadata fetch: Call get_screen for the target screen to get

screenshot.downloadUrl and htmlCode.downloadUrl.

• 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"):

• Map the user's vague terms to precise values using the design mappings (see design-md skill in stitch-utilities or generate-design skill).
• Select concrete hex codes, font families, and roundness values.
• Generate the DESIGN.md file (refer to the design-md skill in stitch-utilities for structure).
• 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.

• 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.
• 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:

• Call get_project to retrieve screenInstances — each has an id and

sourceScreen.

• Call list_design_systems to retrieve the design system name (format:

assets/{assetId}) — use the part after assets/ as the assetId.

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