初始化项目版本
This commit is contained in:
Axhub Make
132
.agents/skills/stitch-manage-design-system/SKILL.md
Normal file
132
.agents/skills/stitch-manage-design-system/SKILL.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
name: stitch::manage-design-system
|
||||
description: >-
|
||||
Manage design systems in Stitch using MCP tools. Includes retrieval of assets,
|
||||
creating/updating design systems in Stitch, and applying them to screens.
|
||||
allowed-tools:
|
||||
- "stitch*:*"
|
||||
- "Bash"
|
||||
- "Read"
|
||||
- "Write"
|
||||
- "web_fetch"
|
||||
---
|
||||
|
||||
# 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.
|
||||
```bash
|
||||
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`.
|
||||
|
||||
```json
|
||||
{
|
||||
"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](examples/metadata.json) for the format.
|
||||
|
||||
## Schema Reference
|
||||
|
||||
See [reference/tool-schema.md](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.
|
||||
@@ -0,0 +1,162 @@
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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`.
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
| Field | Type | Description |
|
||||
|:------|:-----|:------------|
|
||||
| `colorMode` | enum | `LIGHT` or `DARK` |
|
||||
| `headlineFont` | enum | Font for headlines and display text. See font options below. |
|
||||
| `bodyFont` | enum | Font for body text. See font options below. |
|
||||
| `roundness` | enum | `ROUND_FOUR`, `ROUND_EIGHT`, `ROUND_TWELVE`, `ROUND_FULL` |
|
||||
| `customColor` | hex | Primary brand / seed color for the dynamic color system (e.g., `#E8732A`) |
|
||||
|
||||
#### Optional Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
|:------|:-----|:------------|
|
||||
| `displayName` | string | Human-readable name for the design system |
|
||||
| `labelFont` | enum | Font for labels and captions. Defaults to `bodyFont` if omitted. |
|
||||
| `colorVariant` | enum | `FIDELITY`, `TONAL`, `VIBRANT`, `EXPRESSIVE`, `CONTENT`, `MONOCHROME`, `FRUIT_SALAD`, `RAINBOW` |
|
||||
| `overridePrimaryColor` | hex | Override primary color (e.g., `#E8732A`) |
|
||||
| `overrideSecondaryColor` | hex | Override secondary color (e.g., `#1B6B93`) |
|
||||
| `overrideTertiaryColor` | hex | Override tertiary color (e.g., `#F2A541`) |
|
||||
| `overrideNeutralColor` | hex | Override neutral color (e.g., `#FAF7F2`) |
|
||||
| `spacingScale` | integer | Spacing scale factor (observed value: `3`) |
|
||||
| `designMd` | string | Markdown string with detailed design system specifications |
|
||||
|
||||
#### Font Options
|
||||
|
||||
The following font enum values are confirmed to work (server-validated):
|
||||
|
||||
| Value | Font Name |
|
||||
|:------|:----------|
|
||||
| `INTER` | Inter |
|
||||
| `ROBOTO` | Roboto |
|
||||
| `OPEN_SANS` | Open Sans |
|
||||
| `LATO` | Lato |
|
||||
| `MONTSERRAT` | Montserrat |
|
||||
| `NOTO_SANS` | Noto Sans |
|
||||
| `NOTO_SERIF` | Noto Serif |
|
||||
| `PLUS_JAKARTA_SANS` | Plus Jakarta Sans |
|
||||
| `BE_VIETNAM_PRO` | Be Vietnam Pro |
|
||||
|
||||
> [!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`.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user