From 5e32786fb77ad74b4744f83a57bc39f447dce9e1 Mon Sep 17 00:00:00 2001 From: Gabi Date: Tue, 24 Mar 2026 13:57:56 +0100 Subject: [PATCH 1/2] feat: document full DesignTheme API surface and replace deprecated GEMINI_3_PRO MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against live Stitch MCP server (2026-03-24) via SDK research. - Replace deprecated GEMINI_3_PRO with GEMINI_3_1_PRO across all generation skills - Document 18+ DesignTheme fields in get_project (was showing 2) - Fix wrong field name: primaryColor → customColor in get_project response - Add colorVariant (9 enums), headlineFont/bodyFont/labelFont (replacing deprecated single font), namedColors (40+ semantic tokens), spacingScale, designMd, and override colors to schemas and skills - Spec generator now outputs API-native values (colorVariant, split fonts, ROUND_EIGHT enums, spacingScale) — no downstream translation needed - Design-system extraction reads designMd + namedColors from API first, falls back to HTML parsing only for motion/shadows - Orchestrator pulls DesignTheme from existing projects before generating new screens, so screen 5 matches screens 1-4 automatically - Refresh docs/mcp-schemas/*.json with all new fields --- docs/mcp-schemas/create_design_system.json | 65 +++++++- docs/mcp-schemas/edit_screens.json | 4 +- .../generate_screen_from_text.json | 70 +++++++- docs/mcp-schemas/generate_variants.json | 4 +- docs/mcp-schemas/get_project.json | 69 +++++++- skills/stitch-design-md/SKILL.md | 20 ++- skills/stitch-design-system/SKILL.md | 149 ++++++++++++++---- skills/stitch-mcp-create-project/SKILL.md | 20 ++- skills/stitch-mcp-edit-screens/SKILL.md | 7 +- .../SKILL.md | 7 +- skills/stitch-mcp-generate-variants/SKILL.md | 7 +- skills/stitch-mcp-get-project/SKILL.md | 119 +++++++++++++- skills/stitch-orchestrator/SKILL.md | 17 +- skills/stitch-ued-guide/SKILL.md | 53 ++++++- .../stitch-ui-design-spec-generator/SKILL.md | 119 +++++++++++--- skills/stitch-ui-prompt-architect/SKILL.md | 40 ++++- 16 files changed, 681 insertions(+), 89 deletions(-) diff --git a/docs/mcp-schemas/create_design_system.json b/docs/mcp-schemas/create_design_system.json index fa4c65f..8faf93d 100644 --- a/docs/mcp-schemas/create_design_system.json +++ b/docs/mcp-schemas/create_design_system.json @@ -60,7 +60,70 @@ "backgroundLight": { "description": "Light mode background (hex).", "type": "string" }, "backgroundDark": { "description": "Dark mode background (hex).", "type": "string" }, "preset": { "type": "string" }, - "description": { "type": "string" } + "description": { "type": "string" }, + "colorVariant": { + "enum": [ + "COLOR_VARIANT_UNSPECIFIED", "MONOCHROME", "NEUTRAL", "TONAL_SPOT", + "VIBRANT", "EXPRESSIVE", "FIDELITY", "CONTENT", "RAINBOW", "FRUIT_SALAD" + ], + "type": "string" + }, + "headlineFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "bodyFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "labelFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "namedColors": { + "type": "object", + "description": "Semantic color map (40+ tokens like primary, on_primary, surface, etc.)" + }, + "spacingScale": { + "format": "int32", + "type": "integer", + "description": "0=minimal, 1=compact, 2=normal, 3=spacious" + }, + "designMd": { + "type": "string", + "description": "Auto-generated markdown design system document" + }, + "overridePrimaryColor": { "type": "string", "description": "Hex override for primary color" }, + "overrideSecondaryColor": { "type": "string" }, + "overrideTertiaryColor": { "type": "string" }, + "overrideNeutralColor": { "type": "string" } }, "type": "object" } diff --git a/docs/mcp-schemas/edit_screens.json b/docs/mcp-schemas/edit_screens.json index e7c2f6d..5a160ab 100644 --- a/docs/mcp-schemas/edit_screens.json +++ b/docs/mcp-schemas/edit_screens.json @@ -23,8 +23,8 @@ "type": "string" }, "modelId": { - "description": "Optional. GEMINI_3_PRO for complex edits, GEMINI_3_FLASH for simple changes.", - "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH"], + "description": "Optional. GEMINI_3_1_PRO = latest Thinking model. GEMINI_3_PRO = deprecated (use 3_1_PRO). GEMINI_3_FLASH for simple changes.", + "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"], "type": "string" } }, diff --git a/docs/mcp-schemas/generate_screen_from_text.json b/docs/mcp-schemas/generate_screen_from_text.json index 1777a88..83fb6fd 100644 --- a/docs/mcp-schemas/generate_screen_from_text.json +++ b/docs/mcp-schemas/generate_screen_from_text.json @@ -16,11 +16,12 @@ "type": "string" }, "modelId": { - "description": "Optional. GEMINI_3_PRO = Thinking model (higher quality, slower). GEMINI_3_FLASH = default (faster).", + "description": "Optional. GEMINI_3_1_PRO = latest Thinking model. GEMINI_3_PRO = deprecated (use 3_1_PRO). GEMINI_3_FLASH = default (faster).", "enum": [ "MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", - "GEMINI_3_FLASH" + "GEMINI_3_FLASH", + "GEMINI_3_1_PRO" ], "type": "string" }, @@ -225,7 +226,70 @@ "description": "Color saturation 1–4. Higher = more vivid.", "format": "int32", "type": "integer" - } + }, + "colorVariant": { + "enum": [ + "COLOR_VARIANT_UNSPECIFIED", "MONOCHROME", "NEUTRAL", "TONAL_SPOT", + "VIBRANT", "EXPRESSIVE", "FIDELITY", "CONTENT", "RAINBOW", "FRUIT_SALAD" + ], + "type": "string" + }, + "headlineFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "bodyFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "labelFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "namedColors": { + "type": "object", + "description": "Semantic color map (40+ tokens like primary, on_primary, surface, etc.)" + }, + "spacingScale": { + "format": "int32", + "type": "integer", + "description": "0=minimal, 1=compact, 2=normal, 3=spacious" + }, + "designMd": { + "type": "string", + "description": "Auto-generated markdown design system document" + }, + "overridePrimaryColor": { "type": "string", "description": "Hex override for primary color" }, + "overrideSecondaryColor": { "type": "string" }, + "overrideTertiaryColor": { "type": "string" }, + "overrideNeutralColor": { "type": "string" } }, "type": "object" }, diff --git a/docs/mcp-schemas/generate_variants.json b/docs/mcp-schemas/generate_variants.json index cd53acc..08fa706 100644 --- a/docs/mcp-schemas/generate_variants.json +++ b/docs/mcp-schemas/generate_variants.json @@ -27,8 +27,8 @@ "type": "string" }, "modelId": { - "description": "Optional. GEMINI_3_PRO for higher quality, GEMINI_3_FLASH for speed.", - "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH"], + "description": "Optional. GEMINI_3_1_PRO = latest Thinking model. GEMINI_3_PRO = deprecated (use 3_1_PRO). GEMINI_3_FLASH for speed.", + "enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"], "type": "string" } }, diff --git a/docs/mcp-schemas/get_project.json b/docs/mcp-schemas/get_project.json index 93f473c..ac0773c 100644 --- a/docs/mcp-schemas/get_project.json +++ b/docs/mcp-schemas/get_project.json @@ -96,7 +96,70 @@ "enum": ["ROUNDNESS_UNSPECIFIED", "ROUND_TWO", "ROUND_FOUR", "ROUND_EIGHT", "ROUND_TWELVE", "ROUND_FULL"], "type": "string" }, - "saturation": { "description": "1–4", "format": "int32", "type": "integer" } + "saturation": { "description": "1–4", "format": "int32", "type": "integer" }, + "colorVariant": { + "enum": [ + "COLOR_VARIANT_UNSPECIFIED", "MONOCHROME", "NEUTRAL", "TONAL_SPOT", + "VIBRANT", "EXPRESSIVE", "FIDELITY", "CONTENT", "RAINBOW", "FRUIT_SALAD" + ], + "type": "string" + }, + "headlineFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "bodyFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "labelFont": { + "enum": [ + "FONT_UNSPECIFIED", + "BE_VIETNAM_PRO", "EPILOGUE", "INTER", "LEXEND", "MANROPE", + "NEWSREADER", "NOTO_SERIF", "PLUS_JAKARTA_SANS", "PUBLIC_SANS", + "SPACE_GROTESK", "SPLINE_SANS", "WORK_SANS", "DOMINE", + "LIBRE_CASLON_TEXT", "EB_GARAMOND", "LITERATA", "SOURCE_SERIF_FOUR", + "MONTSERRAT", "METROPOLIS", "SOURCE_SANS_THREE", "NUNITO_SANS", + "ARIMO", "HANKEN_GROTESK", "RUBIK", "GEIST", "DM_SANS", + "IBM_PLEX_SANS", "SORA" + ], + "type": "string" + }, + "namedColors": { + "type": "object", + "description": "Semantic color map (40+ tokens like primary, on_primary, surface, etc.)" + }, + "spacingScale": { + "format": "int32", + "type": "integer", + "description": "0=minimal, 1=compact, 2=normal, 3=spacious" + }, + "designMd": { + "type": "string", + "description": "Auto-generated markdown design system document" + }, + "overridePrimaryColor": { "type": "string", "description": "Hex override for primary color" }, + "overrideSecondaryColor": { "type": "string" }, + "overrideTertiaryColor": { "type": "string" }, + "overrideNeutralColor": { "type": "string" } }, "type": "object" }, @@ -124,6 +187,10 @@ "id": { "type": "string" }, "label": { "type": "string" }, "sourceScreen": { "description": "Format: projects/{project}/screens/{screen}", "type": "string" }, + "type": { + "enum": ["SCREEN_INSTANCE_TYPE_UNSPECIFIED", "SCREEN_INSTANCE", "DESIGN_SYSTEM_INSTANCE", "GROUP_INSTANCE"], + "type": "string" + }, "variantScreenInstance": { "$ref": "#/$defs/ScreenInstance" }, "width": { "format": "int32", "type": "integer" }, "x": { "format": "int32", "type": "integer" }, diff --git a/skills/stitch-design-md/SKILL.md b/skills/stitch-design-md/SKILL.md index 739cb14..c8afb09 100644 --- a/skills/stitch-design-md/SKILL.md +++ b/skills/stitch-design-md/SKILL.md @@ -47,7 +47,12 @@ If the user pastes a Stitch design URL like `https://stitch.withgoogle.com/proje 2. Call `[prefix]:list_projects` with `filter: "view=owned"` → select project by title → extract numeric ID 3. Call `[prefix]:list_screens` with `projects/[projectId]` → pick the representative screen 4. Call `[prefix]:get_screen` with numeric `projectId` and `screenId` -5. Call `[prefix]:get_project` with `projects/[projectId]` → get `designTheme` (font, roundness, customColor, colorMode) +5. Call `[prefix]:get_project` with `projects/[projectId]` → get full `designTheme` including: + - Core: `colorMode`, `customColor`, `colorVariant`, `roundness`, `spacingScale` + - Fonts: `headlineFont`, `bodyFont`, `labelFont` + - Colors: `namedColors` (40+ semantic tokens), override colors + - Documentation: `designMd` (auto-generated design system — if present, use as foundation for DESIGN.md) + - Backgrounds: `backgroundLight`, `backgroundDark` ### Download the assets @@ -70,10 +75,14 @@ Work through these layers systematically: ### 2.1 Project identity - Project title and numeric ID (from `name` field) - `deviceType` (MOBILE / DESKTOP / TABLET / AGNOSTIC) -- `designTheme.font`, `designTheme.roundness`, `designTheme.colorMode` from `get_project` +- `designTheme.headlineFont`, `designTheme.bodyFont`, `designTheme.labelFont` (font roles) +- `designTheme.roundness`, `designTheme.colorMode`, `designTheme.colorVariant` +- `designTheme.spacingScale` (0=minimal, 1=compact, 2=normal, 3=spacious) ### 2.2 Visual atmosphere -Describe the aesthetic in 2–3 sentences. Go beyond generic adjectives — what does it feel like? What editorial or product category does it evoke? +If `designTheme.description` exists, use it as the starting point. If `designTheme.designMd` exists, it contains a full design system document — extract the creative direction, do's/don'ts, and component philosophy from it. + +Then describe the aesthetic in 2–3 sentences. Go beyond generic adjectives — what does it feel like? What editorial or product category does it evoke? Examples: - "Sophisticated minimalist sanctuary — gallery-like spaciousness, photography-first, Scandinavian calm" @@ -81,6 +90,11 @@ Examples: - "Warm artisanal brand — handcrafted feel, organic textures, generous breathing room" ### 2.3 Color palette + +**If `namedColors` is available from `get_project`:** Use it as the authoritative color source. It provides 40+ semantic tokens (primary, secondary, tertiary, surface hierarchy, error states, inverse variants). Map these directly to palette documentation instead of guessing from HTML. + +**If `backgroundLight`/`backgroundDark` are available:** Use them as the canonical background colors for light/dark modes. + For each key color, write: ``` [Descriptive name] ([hex]) — [functional role] diff --git a/skills/stitch-design-system/SKILL.md b/skills/stitch-design-system/SKILL.md index ca44146..9ce5cb7 100644 --- a/skills/stitch-design-system/SKILL.md +++ b/skills/stitch-design-system/SKILL.md @@ -44,33 +44,108 @@ Three output files: If multiple screens exist, retrieve all of them. Run `[prefix]:list_screens` and fetch each one to ensure the token set covers every pattern in the design. -## Step 2: Extract raw design values +## Step 1.5: Read project DesignTheme (ground truth) + +Before parsing HTML, get the authoritative design data from the Stitch API. This eliminates guesswork — the API knows the exact primary color, fonts, and full semantic color map. + +1. **Call `get_project`** with `projects/[projectId]` +2. **Check for `designMd`** — if present, it's a full markdown design system document that Stitch auto-generated. Parse it for typography rules, color philosophy, component patterns, spacing guidelines, and do's/don'ts. This is the most valuable single field. +3. **Extract `namedColors`** — a 40+ token semantic color map. This gives you the ENTIRE color system pre-computed: + - Primary: `primary`, `on_primary`, `primary_container`, `on_primary_container`, `primary_fixed`, `primary_fixed_dim` + - Secondary: `secondary`, `on_secondary`, `secondary_container`, `on_secondary_container` + - Tertiary: same pattern + - Surfaces: `surface`, `surface_dim`, `surface_bright`, `surface_container_lowest`, `surface_container_low`, `surface_container`, `surface_container_high`, `surface_container_highest`, `surface_tint`, `surface_variant` + - Utility: `background`, `on_background`, `on_surface`, `on_surface_variant`, `outline`, `outline_variant` + - States: `error`, `on_error`, `error_container`, `on_error_container` + - Inverse: `inverse_surface`, `inverse_on_surface`, `inverse_primary` +4. **Extract structural values:** + +| DesignTheme field | → CSS token | Mapping | +|---|---|---| +| `customColor` | `--color-primary` | Hex seed — but prefer `namedColors.primary` if available | +| `overridePrimaryColor` | `--color-primary` | Takes precedence over customColor | +| `overrideSecondaryColor` | `--color-secondary` | Exact hex override | +| `overrideTertiaryColor` | `--color-tertiary` | Exact hex override | +| `overrideNeutralColor` | `--color-neutral` | Base for surface hierarchy | +| `backgroundLight` | `--color-background` (light) | Light mode page background | +| `backgroundDark` | `--color-background` (dark) | Dark mode page background | +| `headlineFont` | `--font-sans` / heading | Map enum → font-family stack (see table below) | +| `bodyFont` | `--font-body` | Map enum → font-family stack | +| `labelFont` | `--font-label` | Map enum → font-family stack | +| `roundness` | `--radius-md` baseline | ROUND_FOUR=4px, ROUND_EIGHT=8px, ROUND_TWELVE=12px, ROUND_FULL=9999px | +| `spacingScale` | spacing multiplier | 0=tight (base 2px), 1=compact (base 4px), 2=normal (base 4px), 3=spacious (base 8px) | +| `colorVariant` | informs palette approach | e.g., FIDELITY means stick to brand colors, VIBRANT means boost saturation | + +**Font enum → CSS font-family mapping:** + +| Stitch enum | CSS font-family | +|---|---| +| `INTER` | `'Inter', system-ui, sans-serif` | +| `DM_SANS` | `'DM Sans', system-ui, sans-serif` | +| `GEIST` | `'Geist', system-ui, sans-serif` | +| `SPACE_GROTESK` | `'Space Grotesk', system-ui, sans-serif` | +| `MANROPE` | `'Manrope', system-ui, sans-serif` | +| `PLUS_JAKARTA_SANS` | `'Plus Jakarta Sans', system-ui, sans-serif` | +| `WORK_SANS` | `'Work Sans', system-ui, sans-serif` | +| `IBM_PLEX_SANS` | `'IBM Plex Sans', system-ui, sans-serif` | +| `RUBIK` | `'Rubik', system-ui, sans-serif` | +| `SORA` | `'Sora', system-ui, sans-serif` | +| `EPILOGUE` | `'Epilogue', system-ui, sans-serif` | +| `NUNITO_SANS` | `'Nunito Sans', system-ui, sans-serif` | +| `LEXEND` | `'Lexend', system-ui, sans-serif` | +| `PUBLIC_SANS` | `'Public Sans', system-ui, sans-serif` | +| `SOURCE_SANS_THREE` | `'Source Sans 3', system-ui, sans-serif` | +| `MONTSERRAT` | `'Montserrat', system-ui, sans-serif` | +| `HANKEN_GROTESK` | `'Hanken Grotesk', system-ui, sans-serif` | +| `ARIMO` | `'Arimo', system-ui, sans-serif` | +| `BE_VIETNAM_PRO` | `'Be Vietnam Pro', system-ui, sans-serif` | +| `SPLINE_SANS` | `'Spline Sans', system-ui, sans-serif` | +| `METROPOLIS` | `'Metropolis', system-ui, sans-serif` | +| `EB_GARAMOND` | `'EB Garamond', Georgia, serif` | +| `LITERATA` | `'Literata', Georgia, serif` | +| `SOURCE_SERIF_FOUR` | `'Source Serif 4', Georgia, serif` | +| `LIBRE_CASLON_TEXT` | `'Libre Caslon Text', Georgia, serif` | +| `NEWSREADER` | `'Newsreader', Georgia, serif` | +| `DOMINE` | `'Domine', Georgia, serif` | +| `NOTO_SERIF` | `'Noto Serif', Georgia, serif` | + +5. **Use these as the baseline.** Then use HTML analysis (Step 2) only for values the API doesn't provide: motion/transition durations, exact spacing pixel values, shadow definitions, additional colors beyond the namedColors set. + +**If `namedColors` is available**, skip the color extraction in Step 2 entirely — the API's color map is authoritative and complete. Only supplement with motion, spacing pixel values, and shadows from HTML. + +**If `designMd` is available**, use it as the foundation for the DESIGN.md output (Step 5). Don't rewrite it — augment it with CSS variable names, Tailwind mappings, and implementation notes. + +## Step 2: Extract supplementary values from HTML + +If Step 1.5 provided `namedColors` and `designMd`, you only need HTML for: -From the Stitch HTML and screenshot, extract: +### Motion +- Transition durations used (or infer: 150ms for micro, 300ms for panels) +- Easing styles (linear, ease-out, spring-like) + +### Spacing pixel values +- Exact gap/padding values used in the design +- Shadow definitions -### Colors -Identify every distinct color. For each, determine: -- **Exact hex value** (from Tailwind config in ``, or infer from screenshot) -- **Semantic role**: What does this color DO? (primary action, surface, text, border, error, success...) -- **Usage frequency**: How dominant is it? +### Additional colors (rare) +Only if the design uses colors not in `namedColors` — check for gradients, overlays, or custom accent colors. -Aim for 8-12 semantic tokens, not 50 specific shades. +**If Step 1.5 did NOT provide namedColors** (older projects without designMd), fall back to full HTML extraction: -### Typography +### Colors (fallback) +Identify every distinct color from the Tailwind config in `` or infer from screenshot. For each, determine semantic role and usage frequency. Aim for 8-12 semantic tokens. + +### Typography (fallback) - Font families (heading, body, mono — if present) - Type scale sizes (the actual `px` or `rem` values used in the design) - Font weights used - Line heights -### Spacing & geometry +### Spacing & geometry (fallback) - Base spacing unit (usually 4px or 8px) - Border radius values - Shadow definitions -### Motion -- Transition durations used (or infer: 150ms for micro, 300ms for panels) -- Easing styles (linear, ease-out, spring-like) - ## Step 3: Generate `design-tokens.css` Create `design-tokens.css` with full light + dark mode token sets. @@ -83,32 +158,42 @@ Create `design-tokens.css` with full light + dark mode token sets. - `--shadow-*` — Elevation - `--motion-*` — Animation timing -**Template:** +**Template (when namedColors is available from API — preferred):** ```css /* ============================================================= Design Tokens — extracted from Stitch project: [Project Name] Generated by stitch-design-system skill + Source: DesignTheme API (namedColors) + HTML supplementary ============================================================= */ /* ---- Light mode (default) ---- */ :root { - /* Colors: Semantic roles, not visual names */ - --color-background: [hex]; /* Page background */ - --color-surface: [hex]; /* Card, panel backgrounds */ - --color-surface-elevated: [hex]; /* Tooltip, dropdown backgrounds */ - --color-primary: [hex]; /* Primary CTA, key actions */ - --color-primary-hover: [hex]; /* Primary at hover state */ - --color-primary-fg: [hex]; /* Text/icon on primary bg */ - --color-secondary: [hex]; /* Secondary actions, accents */ - --color-secondary-fg: [hex]; /* Text/icon on secondary bg */ - --color-text: [hex]; /* Body text */ - --color-text-muted: [hex]; /* Secondary, supporting text */ - --color-text-disabled: [hex]; /* Disabled element text */ - --color-border: [hex]; /* Dividers, input borders */ - --color-border-focus: [hex]; /* Focus ring color */ - --color-error: [hex]; /* Error states */ - --color-success: [hex]; /* Success states */ - --color-warning: [hex]; /* Warning states */ + /* Colors: Direct mapping from Stitch namedColors API response */ + --color-primary: [namedColors.primary]; + --color-on-primary: [namedColors.on_primary]; + --color-primary-container: [namedColors.primary_container]; + --color-secondary: [namedColors.secondary]; + --color-on-secondary: [namedColors.on_secondary]; + --color-tertiary: [namedColors.tertiary]; + --color-on-tertiary: [namedColors.on_tertiary]; + --color-error: [namedColors.error]; + --color-on-error: [namedColors.on_error]; + --color-background: [namedColors.background]; + --color-on-background: [namedColors.on_background]; + --color-surface: [namedColors.surface]; + --color-on-surface: [namedColors.on_surface]; + --color-surface-variant: [namedColors.surface_variant]; + --color-on-surface-variant: [namedColors.on_surface_variant]; + --color-surface-container: [namedColors.surface_container]; + --color-surface-container-low: [namedColors.surface_container_low]; + --color-surface-container-high: [namedColors.surface_container_high]; + --color-surface-container-highest: [namedColors.surface_container_highest]; + --color-outline: [namedColors.outline]; + --color-outline-variant: [namedColors.outline_variant]; + --color-inverse-surface: [namedColors.inverse_surface]; + --color-inverse-on-surface: [namedColors.inverse_on_surface]; + --color-inverse-primary: [namedColors.inverse_primary]; + --color-surface-tint: [namedColors.surface_tint]; /* Typography */ --font-sans: [font-family-stack]; /* Heading and UI font */ diff --git a/skills/stitch-mcp-create-project/SKILL.md b/skills/stitch-mcp-create-project/SKILL.md index 4177f19..68bbb47 100644 --- a/skills/stitch-mcp-create-project/SKILL.md +++ b/skills/stitch-mcp-create-project/SKILL.md @@ -52,10 +52,28 @@ The tool returns a `name` field in the format `projects/NUMERIC_ID`. You must ex ```json { "name": "projects/3780309359108792857", - "title": "Analytics Dashboard" + "title": "Analytics Dashboard", + "createTime": "2026-03-24T14:30:00Z", + "visibility": "PRIVATE", + "deviceType": "PHONE", + "projectType": "TEXT_TO_UI", + "designTheme": { + "colorMode": "LIGHT", + "customColor": "", + "colorVariant": "TONAL_SPOT", + "roundness": "ROUND_TWELVE", + "spacingScale": 1, + "headlineFont": "ROBOTO", + "bodyFont": "ROBOTO", + "labelFont": "ROBOTO", + "namedColors": {}, + "designMd": "" + } } ``` +> The `designTheme` populates with full values (including `designMd` and `namedColors`) after the first screen is generated. For a brand-new project, expect mostly empty/default theme values. + **Extract:** - **Full name:** `projects/3780309359108792857` → use for `list_screens`, `get_project` - **Numeric ID:** `3780309359108792857` → use for `generate_screen_from_text`, `get_screen` diff --git a/skills/stitch-mcp-edit-screens/SKILL.md b/skills/stitch-mcp-edit-screens/SKILL.md index bcace25..1ee2c0e 100644 --- a/skills/stitch-mcp-edit-screens/SKILL.md +++ b/skills/stitch-mcp-edit-screens/SKILL.md @@ -37,7 +37,7 @@ You must have both a `projectId` AND at least one `screenId` before calling this "selectedScreenIds": ["88805abc123def456"], "prompt": "Change the background to dark mode (#09090B). Make the primary color indigo (#818CF8). Increase the font size of the header to 32px bold.", "deviceType": "DESKTOP", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -77,8 +77,9 @@ Same enum as `generate_screen_from_text`: `MOBILE`, `DESKTOP`, `TABLET`, `AGNOST | Value | Use when | |-------|---------| -| `GEMINI_3_PRO` | Complex edits — layout changes, multi-component updates | -| `GEMINI_3_FLASH` | Simple edits — color swaps, text changes, quick iterations | +| `GEMINI_3_1_PRO` | **Recommended** — complex layouts, high fidelity | +| `GEMINI_3_FLASH` | Fast iteration, wireframes, simple changes | +| `GEMINI_3_PRO` | **Deprecated.** Still works but will be removed. Use `GEMINI_3_1_PRO` instead. | ## Handling `output_components` diff --git a/skills/stitch-mcp-generate-screen-from-text/SKILL.md b/skills/stitch-mcp-generate-screen-from-text/SKILL.md index 64a0037..d1df6e3 100644 --- a/skills/stitch-mcp-generate-screen-from-text/SKILL.md +++ b/skills/stitch-mcp-generate-screen-from-text/SKILL.md @@ -32,7 +32,7 @@ You must have a `projectId` before calling this. If you don't have one: "projectId": "3780309359108792857", "prompt": "[Full structured prompt — see below]", "deviceType": "MOBILE", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -70,8 +70,9 @@ For best results, use the `stitch-ui-prompt-architect` skill to assemble the pro ### `modelId` | Value | Use when | |-------|---------| -| `GEMINI_3_PRO` | **Recommended** — high-fidelity, complex layouts, production quality | -| `GEMINI_3_FLASH` | Wireframes, rapid iteration, when speed matters more than quality | +| `GEMINI_3_1_PRO` | **Recommended** — complex layouts, high fidelity | +| `GEMINI_3_FLASH` | Fast iteration, wireframes, simple changes | +| `GEMINI_3_PRO` | **Deprecated.** Still works but will be removed. Use `GEMINI_3_1_PRO` instead. | ## After generating diff --git a/skills/stitch-mcp-generate-variants/SKILL.md b/skills/stitch-mcp-generate-variants/SKILL.md index 16068c0..0dd91ee 100644 --- a/skills/stitch-mcp-generate-variants/SKILL.md +++ b/skills/stitch-mcp-generate-variants/SKILL.md @@ -37,7 +37,7 @@ You must have both a `projectId` AND at least one `screenId` of an existing scre "aspects": ["COLOR_SCHEME", "IMAGES"] }, "deviceType": "DESKTOP", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -100,8 +100,9 @@ Same enum: `MOBILE`, `DESKTOP`, `TABLET`, `AGNOSTIC` | Value | Use when | |-------|---------| -| `GEMINI_3_PRO` | Higher quality variants, complex designs | -| `GEMINI_3_FLASH` | Faster iteration, simpler screens | +| `GEMINI_3_1_PRO` | **Recommended** — complex layouts, high fidelity | +| `GEMINI_3_FLASH` | Fast iteration, wireframes, simple changes | +| `GEMINI_3_PRO` | **Deprecated.** Still works but will be removed. Use `GEMINI_3_1_PRO` instead. | ## Output diff --git a/skills/stitch-mcp-get-project/SKILL.md b/skills/stitch-mcp-get-project/SKILL.md index 08d4603..71057be 100644 --- a/skills/stitch-mcp-get-project/SKILL.md +++ b/skills/stitch-mcp-get-project/SKILL.md @@ -50,16 +50,131 @@ The user may provide the project reference in several formats — always extract "title": "Analytics Dashboard", "createTime": "2024-11-10T09:00:00Z", "updateTime": "2024-11-15T10:30:00Z", + "deviceType": "PHONE", + "visibility": "PRIVATE", + "projectType": "TEXT_TO_UI", + "origin": "STITCH", + "metadata": { + "isRemixed": false, + "userRole": "OWNER" + }, "designTheme": { "colorMode": "LIGHT", - "primaryColor": "#6366F1" + "customColor": "#6366F1", + "colorVariant": "TONAL_SPOT", + "roundness": "ROUND_TWELVE", + "spacingScale": 1, + "headlineFont": "ROBOTO", + "bodyFont": "ROBOTO", + "labelFont": "ROBOTO", + "font": "ROBOTO", + "namedColors": { + "primary": "#5B5FC7", + "on_primary": "#FFFFFF", + "primary_container": "#E1DFFF", + "on_primary_container": "#414594", + "secondary": "#5C5D72", + "on_secondary": "#FFFFFF", + "tertiary": "#785572", + "on_tertiary": "#FFFFFF", + "surface": "#FBF8FF", + "on_surface": "#1B1B21", + "surface_container": "#EFEDF5", + "surface_container_low": "#F5F2FA", + "surface_container_high": "#E9E7EF", + "outline": "#777680", + "error": "#BA1A1A", + "on_error": "#FFFFFF" + }, + "overridePrimaryColor": "", + "overrideSecondaryColor": "", + "overrideTertiaryColor": "", + "overrideNeutralColor": "", + "backgroundLight": "#FBF8FF", + "backgroundDark": "#131316", + "description": "Modern indigo-toned interface with clean surfaces", + "designMd": "# Design System\n\n## Color Palette\n..." }, "screenInstances": [ - { "name": "projects/3780309359108792857/screens/88805..." } + { + "name": "projects/3780309359108792857/screens/88805...", + "id": "88805...", + "sourceScreen": "screens/88805...", + "type": "SCREEN_INSTANCE", + "width": 412, + "height": 892, + "x": 0, + "y": 0, + "hidden": false + }, + { + "name": "projects/3780309359108792857/screens/99901...", + "id": "99901...", + "sourceScreen": "screens/99901...", + "type": "DESIGN_SYSTEM_INSTANCE", + "width": 412, + "height": 892, + "x": 500, + "y": 0, + "hidden": false, + "sourceAsset": "assets/design-system-123" + } ] } ``` +> `designMd` is truncated above — in practice it's a full auto-generated design system doc (often 500+ lines). `namedColors` typically contains 40+ semantic tokens; only the most common are shown here. + +## DesignTheme field reference + +| Field | Type | Values / Notes | +|-------|------|----------------| +| `colorMode` | enum | `LIGHT`, `DARK` | +| `customColor` | string | Hex seed color (e.g. `#6366F1`). This is the color seed — NOT called `primaryColor` | +| `colorVariant` | enum | `MONOCHROME`, `NEUTRAL`, `TONAL_SPOT`, `VIBRANT`, `EXPRESSIVE`, `FIDELITY`, `CONTENT`, `RAINBOW`, `FRUIT_SALAD` | +| `roundness` | enum | `ROUND_FOUR`, `ROUND_EIGHT`, `ROUND_TWELVE`, `ROUND_FULL` | +| `spacingScale` | number | `0`–`3` (density multiplier) | +| `headlineFont` | enum | 28-font set: `ROBOTO`, `OPEN_SANS`, `LATO`, `MONTSERRAT`, `POPPINS`, `INTER`, `PLAYFAIR_DISPLAY`, `MERRIWEATHER`, `RALEWAY`, `NUNITO`, `SOURCE_SANS_3`, `OSWALD`, `QUICKSAND`, `CABIN`, `BARLOW`, `WORK_SANS`, `DM_SANS`, `SPACE_GROTESK`, `SORA`, `OUTFIT`, `PLUS_JAKARTA_SANS`, `MANROPE`, `ALBERT_SANS`, `FIGTREE`, `GEIST`, `ONEST`, `INSTRUMENT_SANS`, `GENERAL_SANS` | +| `bodyFont` | enum | Same 28-font set | +| `labelFont` | enum | Same 28-font set | +| `font` | enum | **Deprecated** — legacy single-font field, same enum | +| `namedColors` | object | 40+ semantic color tokens (`primary`, `on_primary`, `surface`, `surface_container`, `outline`, `error`, etc.) | +| `overridePrimaryColor` | string | Hex override, empty string if unused | +| `overrideSecondaryColor` | string | Hex override, empty string if unused | +| `overrideTertiaryColor` | string | Hex override, empty string if unused | +| `overrideNeutralColor` | string | Hex override, empty string if unused | +| `backgroundLight` | string | Hex background for light mode | +| `backgroundDark` | string | Hex background for dark mode | +| `description` | string | Brief aesthetic description of the theme | +| `designMd` | string | Auto-generated design system markdown — the full token spec. Can be very long | + +## Project-level fields + +| Field | Type | Values / Notes | +|-------|------|----------------| +| `deviceType` | string | `PHONE`, `TABLET`, `DESKTOP`, etc. | +| `visibility` | enum | `PRIVATE`, `PUBLIC` | +| `projectType` | enum | `TEXT_TO_UI`, `PROJECT_DESIGN`, etc. | +| `origin` | enum | `STITCH`, `IMPORTED_FROM_GALILEO` | +| `metadata.isRemixed` | boolean | Whether this project was remixed from another | +| `metadata.userRole` | string | `OWNER`, `VIEWER`, etc. | + +## ScreenInstance fields + +| Field | Type | Notes | +|-------|------|-------| +| `id` | string | Numeric screen ID | +| `sourceScreen` | string | Path reference to the source screen | +| `type` | enum | `SCREEN_INSTANCE`, `DESIGN_SYSTEM_INSTANCE`, `GROUP_INSTANCE` | +| `width` / `height` | number | Pixel dimensions | +| `x` / `y` | number | Canvas position | +| `hidden` | boolean | Whether hidden in the project | +| `sourceAsset` | string | Present on `DESIGN_SYSTEM_INSTANCE` types — references the design system asset | + +## Using the theme data + +Use `designMd` and `namedColors` when generating new screens — they contain the authoritative design system for this project. Pass `namedColors` to `stitch-design-system` for instant token extraction. + ## After getting the project - Note the `designTheme` — use it to keep new screens visually consistent diff --git a/skills/stitch-orchestrator/SKILL.md b/skills/stitch-orchestrator/SKILL.md index d923867..7de9df2 100644 --- a/skills/stitch-orchestrator/SKILL.md +++ b/skills/stitch-orchestrator/SKILL.md @@ -138,6 +138,21 @@ If any of these are missing — re-invoke the prompt architect. Don't send vague If creating new: Call `stitch-mcp-create-project` → get `projectId` (both numeric and full-path forms) +#### Step 4a: Pull DesignTheme from existing project (consistency gate) + +**When reusing an existing project**, read its DesignTheme to keep new screens visually consistent: + +1. Call `stitch-mcp-get-project` with `projects/[projectId]` +2. Extract the `designTheme` from the response +3. **If `designMd` exists:** this project has a full design system. Pass key values as constraints to the spec generator (Step 2) to override its guesses: + - `headlineFont`, `bodyFont`, `labelFont` → override spec's font selection + - `colorVariant`, `customColor` → override spec's color derivation + - `roundness`, `spacingScale` → override spec's geometry +4. **If `namedColors` exists:** pass the full color map to `stitch-design-system` later (Step 7) — it eliminates HTML parsing for colors +5. Store the DesignTheme for reference throughout the workflow + +This prevents the spec generator from picking a different font or color scheme for new screens in an established project. + #### Step 4b: Check for existing design systems After selecting a project: @@ -153,7 +168,7 @@ Call `stitch-mcp-generate-screen-from-text` with: - `projectId`: numeric ID (no `projects/` prefix) - `prompt`: assembled prompt from Step 3 - `deviceType`: from Design Spec -- `modelId`: `GEMINI_3_PRO` (default) or `GEMINI_3_FLASH` (if user wants fast iteration) +- `modelId`: `GEMINI_3_1_PRO` (default — high fidelity) or `GEMINI_3_FLASH` (fast iteration, wireframes) > ⏱ **Generation timing:** Stitch typically takes 60–180 seconds to generate a screen. This is normal — do NOT retry or assume failure during this window. > diff --git a/skills/stitch-ued-guide/SKILL.md b/skills/stitch-ued-guide/SKILL.md index 32671fa..5c03307 100644 --- a/skills/stitch-ued-guide/SKILL.md +++ b/skills/stitch-ued-guide/SKILL.md @@ -36,8 +36,59 @@ The most effective Stitch prompts follow this 4-part structure: | Model | When to use | |-------|-------------| -| `GEMINI_3_PRO` | High-fidelity designs, complex layouts, when quality matters — **recommended default** | +| `GEMINI_3_1_PRO` | High-fidelity designs, complex layouts, when quality matters — **recommended default** | | `GEMINI_3_FLASH` | Fast iteration, wireframes, rapid exploration, when speed matters | +| `GEMINI_3_PRO` | **Deprecated** — still works but will be removed. Use `GEMINI_3_1_PRO` instead | + +## Color variant reference (colorVariant) + +Controls how Stitch derives the full color palette from your `primaryColor`: + +| colorVariant | Visual effect | Best for | +|---|---|---| +| `MONOCHROME` | Single-hue, editorial feel | Luxury, minimal, text-heavy, portfolios | +| `NEUTRAL` | Subdued, professional | Corporate, enterprise, medical | +| `TONAL_SPOT` | Balanced accent spots on neutral base | SaaS, productivity, dashboards | +| `VIBRANT` | Bold, energetic colors | Consumer apps, social, food | +| `EXPRESSIVE` | Multicolor, dynamic | Creative, gaming, entertainment | +| `FIDELITY` | Precise brand color matching | Brand-heavy, marketing, landing pages | +| `CONTENT` | Palette adapts to content | Media, editorial, photo-heavy | +| `RAINBOW` | Full spectrum | Kids apps, events, playful | +| `FRUIT_SALAD` | Warm multicolor | Food, lifestyle, wellness | + +## Spacing scale reference (spacingScale) + +| spacingScale | Effect | Best for | +|---|---|---| +| 0 | Minimal spacing — very tight, data-dense | Admin panels, data tables, terminal-style UIs | +| 1 | Compact — efficient use of space | Dashboards, dense mobile lists, SaaS tools | +| 2 | Normal — comfortable breathing room | Standard apps, consumer products | +| 3 | Spacious — generous whitespace | Landing pages, marketing, portfolios, luxury | + +## DesignTheme API field reference + +Quick reference for all DesignTheme fields returned by `get_project`: + +| Field | Type | Description | +|---|---|---| +| `colorMode` | LIGHT / DARK | Base theme mode | +| `customColor` | hex string | Seed color for palette generation | +| `colorVariant` | enum (9 values) | How palette is derived from seed | +| `headlineFont` | font enum (28 values) | Display/headline typeface | +| `bodyFont` | font enum | Body text typeface | +| `labelFont` | font enum | Labels, captions, metadata typeface | +| `font` | font enum | **Deprecated** — use headlineFont/bodyFont/labelFont | +| `roundness` | ROUND_FOUR/EIGHT/TWELVE/FULL | Corner radius preset | +| `spacingScale` | integer 0-3 | Layout density | +| `namedColors` | object (40+ tokens) | Full semantic color map (Material 3) | +| `designMd` | string | Auto-generated design system markdown | +| `description` | string | Brief aesthetic description | +| `overridePrimaryColor` | hex | Explicit primary override | +| `overrideSecondaryColor` | hex | Explicit secondary override | +| `overrideTertiaryColor` | hex | Explicit tertiary override | +| `overrideNeutralColor` | hex | Explicit neutral base override | +| `backgroundLight` | hex | Light mode background | +| `backgroundDark` | hex | Dark mode background | ## Layout patterns diff --git a/skills/stitch-ui-design-spec-generator/SKILL.md b/skills/stitch-ui-design-spec-generator/SKILL.md index 79f22c8..734e8ce 100644 --- a/skills/stitch-ui-design-spec-generator/SKILL.md +++ b/skills/stitch-ui-design-spec-generator/SKILL.md @@ -25,6 +25,9 @@ You can also use it directly when a user asks: "What design spec would work for **Type B — PRD document or summary:** > Provide a file path or paste PRD content. Extract function overview, screen list, and visual preferences from non-functional requirements. +**Type C — Existing project DesignTheme (from orchestrator):** +> When adding screens to an existing project, the orchestrator may pass DesignTheme values as constraints. Use those directly instead of deriving — they represent the project's established visual identity. + ## Logic rules — apply in order ### 1. Analyze tone → derive style keywords and colors @@ -55,38 +58,63 @@ You can also use it directly when a user asks: "What design spec would work for | "wireframe", "sketch", "low-fi", "draft" | WIREFRAME | | All other cases | HIGH_FIDELITY | -### 4. Determine roundness +### 4. Determine roundness (API enum values) | Style keywords contain | → roundness | |---|---| -| "sharp", "brutalist", "corporate", "enterprise" | Low | -| "modern", "clean", "professional" | Medium | -| "friendly", "playful", "card", "soft", "rounded" | High | +| "sharp", "brutalist", "corporate", "enterprise", "terminal" | `ROUND_FOUR` | +| "modern", "clean", "professional", "balanced" | `ROUND_EIGHT` | +| "friendly", "playful", "card", "soft", "rounded" | `ROUND_TWELVE` | +| "pill", "bubble", "very rounded", "capsule" | `ROUND_FULL` | -### 5. Determine density +### 5. Determine density + spacingScale -| Context | → density | -|---|---| -| Data tables, dashboards, admin panels | COMPACT | -| Mobile apps, social, consumer | COMFORTABLE | -| Marketing pages, landing pages, portfolios | SPACIOUS | +| Context | → density | → spacingScale | +|---|---|---| +| Data tables, dashboards, admin panels | COMPACT | 0 or 1 | +| Mobile apps, social, consumer | COMFORTABLE | 2 | +| Marketing pages, landing pages, portfolios | SPACIOUS | 3 | -## Output format +### 6. Determine colorVariant -Always output **exactly this JSON structure** — no extra fields, no explanations: +The `colorVariant` controls how Stitch derives the full color palette from your `primaryColor`. Pick based on the visual identity: -```json -{ - "theme": "DARK" | "LIGHT", - "primaryColor": "#HEXCODE", - "font": "Font Name", - "roundness": "High" | "Medium" | "Low", - "density": "COMPACT" | "COMFORTABLE" | "SPACIOUS", - "designMode": "WIREFRAME" | "HIGH_FIDELITY", - "styleKeywords": ["Keyword1", "Keyword2", "Keyword3"], - "deviceType": "MOBILE" | "TABLET" | "DESKTOP" | "AGNOSTIC" -} -``` +| Domain / Tone | → colorVariant | +|---|---| +| Corporate, Medical, Finance | `NEUTRAL` or `TONAL_SPOT` | +| Luxury, Fashion, Minimal, Editorial | `MONOCHROME` or `FIDELITY` | +| Productivity, SaaS, Enterprise | `TONAL_SPOT` | +| Creative, Gaming, Cyberpunk | `VIBRANT` or `EXPRESSIVE` | +| Lifestyle, Food, Social | `VIBRANT` or `CONTENT` | +| Playful, Kids, Events | `RAINBOW` or `FRUIT_SALAD` | +| Brand-heavy, Marketing, Landing pages | `FIDELITY` | + +Quick reference: +- `MONOCHROME` — single-hue, editorial feel +- `NEUTRAL` — subdued, professional +- `TONAL_SPOT` — balanced accent spots on neutral base +- `VIBRANT` — bold, energetic colors +- `EXPRESSIVE` — multicolor, dynamic +- `FIDELITY` — sticks close to the exact brand colors +- `CONTENT` — palette adapts to content +- `RAINBOW` — full spectrum +- `FRUIT_SALAD` — warm multicolor + +### 7. Determine fonts (headline / body / label) + +The API supports three separate font roles. Default behavior: all three = same font. Split them for specific design approaches: + +**Same font (default for most projects):** +> All three set to the same value (e.g., `INTER` / `INTER` / `INTER`) + +**Split fonts (use when the design benefits from typographic contrast):** + +| Design approach | headlineFont | bodyFont | labelFont | +|---|---|---|---| +| Editorial / magazine | `EB_GARAMOND` or `LITERATA` | `INTER` or `DM_SANS` | `INTER` or `DM_SANS` | +| Brutalist / hacker | `SPACE_GROTESK` | `INTER` | `IBM_PLEX_SANS` | +| Luxury / high-end | `LIBRE_CASLON_TEXT` | `MANROPE` | `MANROPE` | +| Data-heavy dashboard | `INTER` | `INTER` | `IBM_PLEX_SANS` or `SOURCE_SANS_THREE` | **Font selection guide — use Stitch enum names exactly:** @@ -106,6 +134,49 @@ Full font list: `BE_VIETNAM_PRO`, `EPILOGUE`, `INTER`, `LEXEND`, `MANROPE`, `NEW `MONTSERRAT`, `METROPOLIS`, `SOURCE_SANS_THREE`, `NUNITO_SANS`, `ARIMO`, `HANKEN_GROTESK`, `RUBIK`, `GEIST`, `DM_SANS`, `IBM_PLEX_SANS`, `SORA` +### 8. Determine background colors + +| theme | → backgroundLight | → backgroundDark | +|---|---|---| +| DARK (default) | `#FAFAFA` | Derive from domain — deep grey `#0F0F11` for tech, warm `#1A1816` for lifestyle | +| LIGHT | Derive — pure `#FFFFFF` for corporate, warm `#FFFBF5` for lifestyle | `#18181B` | + +## Output format + +Always output **exactly this JSON structure** — no extra fields, no explanations: + +```json +{ + "theme": "DARK", + "primaryColor": "#6366F1", + "headlineFont": "SPACE_GROTESK", + "bodyFont": "INTER", + "labelFont": "INTER", + "colorVariant": "FIDELITY", + "roundness": "ROUND_EIGHT", + "spacingScale": 2, + "backgroundLight": "#FAFAFA", + "backgroundDark": "#131315", + "density": "COMFORTABLE", + "designMode": "HIGH_FIDELITY", + "styleKeywords": ["Clean", "Professional", "Focused"], + "deviceType": "DESKTOP" +} +``` + +Field types: +- `theme`: `"DARK"` | `"LIGHT"` +- `primaryColor`: hex string +- `headlineFont`, `bodyFont`, `labelFont`: Stitch font enum (see list above) +- `colorVariant`: `"MONOCHROME"` | `"NEUTRAL"` | `"TONAL_SPOT"` | `"VIBRANT"` | `"EXPRESSIVE"` | `"FIDELITY"` | `"CONTENT"` | `"RAINBOW"` | `"FRUIT_SALAD"` +- `roundness`: `"ROUND_FOUR"` | `"ROUND_EIGHT"` | `"ROUND_TWELVE"` | `"ROUND_FULL"` +- `spacingScale`: integer 0-3 +- `backgroundLight`, `backgroundDark`: hex string +- `density`: `"COMPACT"` | `"COMFORTABLE"` | `"SPACIOUS"` +- `designMode`: `"WIREFRAME"` | `"HIGH_FIDELITY"` +- `styleKeywords`: array of 2-4 adjectives +- `deviceType`: `"MOBILE"` | `"TABLET"` | `"DESKTOP"` | `"AGNOSTIC"` + ## Integration After generating the spec JSON, the next step is always `stitch-ui-prompt-architect`, which merges the spec with the user's request to produce a `[Context] [Layout] [Components]` Stitch generation prompt. diff --git a/skills/stitch-ui-prompt-architect/SKILL.md b/skills/stitch-ui-prompt-architect/SKILL.md index 522dd45..5e195cb 100644 --- a/skills/stitch-ui-prompt-architect/SKILL.md +++ b/skills/stitch-ui-prompt-architect/SKILL.md @@ -81,13 +81,33 @@ Mobile High-Fidelity login screen for a fintech app. ### 1. Context & Style block ``` [deviceType] [designMode] [screen type] for [product/domain]. -[styleKeywords joined as adjectives] aesthetic. +[styleKeywords joined as adjectives] aesthetic. [colorVariant] color palette. [theme] mode. -Background: [derive from theme + domain]. +Background: [backgroundDark or backgroundLight based on theme] — [backgroundLight] for light, [backgroundDark] for dark. Primary: [primaryColor] ([color name]). -Font: [font]. +Headline font: [headlineFont]. Body font: [bodyFont]. Label font: [labelFont]. +Roundness: [roundness]. Spacing: [spacingScale description]. ``` +**colorVariant descriptors for the prompt:** +- MONOCHROME → "monochromatic, single-hue palette" +- NEUTRAL → "subdued neutral palette" +- TONAL_SPOT → "tonal spot accents on neutral base" +- VIBRANT → "vibrant, bold color palette" +- EXPRESSIVE → "expressive, multicolor palette" +- FIDELITY → "high-fidelity brand color matching" +- CONTENT → "content-adaptive palette" +- RAINBOW / FRUIT_SALAD → "colorful, playful palette" + +**spacingScale descriptors:** +- 0 → "minimal spacing, data-dense" +- 1 → "compact spacing" +- 2 → "comfortable spacing" +- 3 → "spacious, breathing layout" + +**When an existing project's DesignTheme is available** (passed from orchestrator with `designMd`): +Include relevant design rules from `designMd` in the context block — typography philosophy, color usage rules, component patterns, and do's/don'ts. This ensures new screens match the established design system. + ### 2. Layout Structure block Derive from deviceType and screen type: @@ -134,8 +154,14 @@ Input spec: { "theme": "LIGHT", "primaryColor": "#6366F1", - "font": "DM Sans", - "roundness": "Medium", + "headlineFont": "DM_SANS", + "bodyFont": "DM_SANS", + "labelFont": "IBM_PLEX_SANS", + "colorVariant": "TONAL_SPOT", + "roundness": "ROUND_EIGHT", + "spacingScale": 1, + "backgroundLight": "#FFFFFF", + "backgroundDark": "#18181B", "density": "COMPACT", "designMode": "HIGH_FIDELITY", "styleKeywords": ["Productivity", "SaaS", "Structured"], @@ -145,11 +171,11 @@ Input spec: Output prompt: ``` -Desktop High-Fidelity analytics dashboard. Productivity SaaS aesthetic. Light mode. Background: White (#ffffff). Primary: Indigo (#6366F1). Font: DM Sans. Clean, structured, data-dense. +Desktop High-Fidelity analytics dashboard. Productivity SaaS aesthetic. Tonal spot accents on neutral base. Light mode. Background: White (#FFFFFF). Primary: Indigo (#6366F1). Headline font: DM Sans. Body font: DM Sans. Label font: IBM Plex Sans. Roundness: 8px. Compact spacing, data-dense layout. Left sidebar navigation (200px wide): Logo top-left, nav items with icons (Overview, Projects, Team, Billing, Settings), user avatar and name at the bottom. Main content: Top bar with 'Good morning, Sarah' and date. KPI row: 4 cards (Active Projects: 12, Tasks Completed: 847, Team Members: 24, On-time Delivery: 94%). Main chart: 'Velocity' line chart (last 30 days). Bottom split: 'Recent Activity' feed left, 'Upcoming Deadlines' list right. -KPI cards: indigo number, grey label, subtle upward trend arrow in green. Line chart: indigo primary line, grey grid, hover tooltip. Activity feed: avatar, action text, timestamp. Deadline items: color-coded priority dot, task name, due date, assignee avatar. +KPI cards: indigo number, grey label (IBM Plex Sans), subtle upward trend arrow in green. Line chart: indigo primary line, grey grid, hover tooltip. Activity feed: avatar, action text, timestamp. Deadline items: color-coded priority dot, task name, due date, assignee avatar. ``` --- From 89733ef072ac1c2d48b4b7fc4cffb2605c7e95af Mon Sep 17 00:00:00 2001 From: Gabi Date: Tue, 24 Mar 2026 14:27:11 +0100 Subject: [PATCH 2/2] fix: update remaining GEMINI_3_PRO refs and deprecated font field in examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Caught by automated consistency checks: - stitch-ideate: GEMINI_3_PRO → GEMINI_3_1_PRO as default model - 7 example files: replace GEMINI_3_PRO with GEMINI_3_1_PRO - create/update design system skills: add headlineFont/bodyFont/labelFont alongside deprecated font field - spec-generator examples: use enum names and split font fields --- skills/stitch-ideate/SKILL.md | 2 +- skills/stitch-mcp-create-design-system/SKILL.md | 8 +++++++- .../examples/desktop.md | 6 +++--- .../examples/mobile.md | 6 +++--- skills/stitch-mcp-update-design-system/SKILL.md | 3 +++ skills/stitch-orchestrator/examples/workflow.md | 6 ++++-- .../examples/usage.md | 16 ++++++++++++---- 7 files changed, 33 insertions(+), 14 deletions(-) diff --git a/skills/stitch-ideate/SKILL.md b/skills/stitch-ideate/SKILL.md index a27755a..9c60115 100644 --- a/skills/stitch-ideate/SKILL.md +++ b/skills/stitch-ideate/SKILL.md @@ -439,7 +439,7 @@ Each direction needs its own project (to keep designs organized) and its own ful - `projectId`: numeric ID only (no `projects/` prefix) - `prompt`: the **full PRD text** — product overview, design system, all screen specs, build guide - `deviceType`: from PRD (usually `DESKTOP` or `MOBILE`) - - `modelId`: `GEMINI_3_PRO` (default for high-fidelity multi-screen generation) + - `modelId`: `GEMINI_3_1_PRO` (default for high-fidelity multi-screen generation). Note: `GEMINI_3_PRO` is deprecated — always use `GEMINI_3_1_PRO`. After generation, hand off to the **orchestrator's Step 5b** (post-generation iteration menu) for edit/variant/convert options. diff --git a/skills/stitch-mcp-create-design-system/SKILL.md b/skills/stitch-mcp-create-design-system/SKILL.md index 7840103..b9d07fb 100644 --- a/skills/stitch-mcp-create-design-system/SKILL.md +++ b/skills/stitch-mcp-create-design-system/SKILL.md @@ -31,6 +31,9 @@ Creates a new Stitch Design System — a reusable theme configuration that can b "theme": { "colorMode": "LIGHT", "font": "DM_SANS", + "headlineFont": "DM_SANS", + "bodyFont": "DM_SANS", + "labelFont": "DM_SANS", "roundness": "ROUND_EIGHT", "saturation": 3, "customColor": "#6366F1", @@ -62,7 +65,10 @@ Creates a new Stitch Design System — a reusable theme configuration that can b | Field | Type | Values | Description | |-------|------|--------|-------------| | `colorMode` | enum | `LIGHT`, `DARK` | Base appearance mode | -| `font` | enum | See font list below | Primary typeface | +| `font` | enum | See font list below | **Deprecated** — sets all three font roles. Use the specific fields below instead | +| `headlineFont` | enum | See font list below | Typeface for headings and titles | +| `bodyFont` | enum | See font list below | Typeface for body text and paragraphs | +| `labelFont` | enum | See font list below | Typeface for labels, captions, and UI chrome | | `roundness` | enum | `ROUND_FOUR`, `ROUND_EIGHT`, `ROUND_TWELVE`, `ROUND_FULL` | Border radius scale | | `saturation` | int | 1–4 | Color vibrancy (1 = muted, 4 = vivid) | | `customColor` | string | Hex color | Primary brand color | diff --git a/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md b/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md index a45cd20..54c6293 100644 --- a/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md +++ b/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md @@ -11,7 +11,7 @@ "projectId": "3780309359108792857", "prompt": "Desktop High-Fidelity analytics dashboard for a SaaS platform. Enterprise clean aesthetic. Light mode. Background: White (#ffffff). Primary: Indigo (#6366F1). Font: DM Sans.\n\nLeft sidebar navigation (200px): Logo top-left, nav items with icons (Overview, Projects, Reports, Settings), user avatar and name at bottom. Top bar: 'Analytics Overview' title, date range picker, 'Export' button.\n\nKPI row: 4 metric cards — Total Revenue ($142,800, +12% MoM), Active Users (8,420, +5%), Churn Rate (2.1%, -0.3%), Avg Session (4m 32s). Main chart: 'Monthly Recurring Revenue' line chart, last 12 months, indigo line with subtle fill. Bottom split: 'Top Performing Plans' bar chart left, 'Recent Signups' table right.", "deviceType": "DESKTOP", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -29,7 +29,7 @@ "projectId": "3780309359108792857", "prompt": "Desktop High-Fidelity admin console for server monitoring. Developer aesthetic. Dark mode. Background: Zinc-900 (#18181B). Primary: Emerald (#10B981). Font: IBM Plex Mono.\n\nDense information layout. Top bar: 'System Status' title, 'All Systems Operational' badge in green. Main grid: 6 server status cards in 3-column grid — each card shows Server name, CPU gauge (%), Memory gauge (%), Uptime, Status indicator (green/red dot). Bottom panel: Terminal-style log stream with color-coded severity (ERROR in red, WARN in yellow, INFO in emerald).", "deviceType": "DESKTOP", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -47,7 +47,7 @@ "projectId": "3780309359108792857", "prompt": "Desktop High-Fidelity landing page for 'Taskflow', a project management SaaS. Clean minimalist aesthetic. Light mode. Background: White (#ffffff). Primary: Violet (#7C3AED). Font: Inter.\n\nSticky top nav: Logo left, links center (Features, Pricing, Blog, Docs), 'Sign in' ghost button and 'Start free' primary button right. Hero: Large headline 'Ship projects faster, together', subtext 'The only PM tool your team will actually use', two CTA buttons ('Get started free' primary, 'See demo' ghost), hero mockup screenshot of dashboard. Features section: 3-column grid of feature cards with icon, title, description. Social proof: Logos row of known companies.", "deviceType": "DESKTOP", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` diff --git a/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md b/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md index c10f106..2b514f3 100644 --- a/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md +++ b/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md @@ -11,7 +11,7 @@ "projectId": "3780309359108792857", "prompt": "Mobile High-Fidelity login screen for a cyberpunk game 'NetRunner'. Neon aesthetic. Dark mode. Background: Deep black (#050505). Primary: Neon blue (#00D9FF). Font: Orbitron.\n\nCenter-aligned vertical stack. Header: Glitch-effect 'NETRUNNER' logo with horizontal scan-line overlay. Form: 'NetID' input field with neon blue glowing border, 'Passcode' input with eye-toggle icon, neon pink glow on focus. Primary CTA: Full-width 'JACK IN' button with animated neon border. Divider: 'OR CONNECT VIA' with subtle lines. OAuth row: Ghost buttons for Google and Discord. Footer: 'New agent? Register your ID' link in muted cyan.", "deviceType": "MOBILE", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -47,7 +47,7 @@ "projectId": "3780309359108792857", "prompt": "Mobile High-Fidelity product detail screen for a premium sneaker store. Streetwear aesthetic. Light mode. Background: White (#ffffff). Primary: Black (#18181B). Font: Space Grotesk.\n\nTop: Back arrow + share icon. Hero: Full-width image carousel showing 'Air Max 90 OG' sneaker from multiple angles, dot indicators. Info section: Brand tag 'Nike', product name 'Air Max 90 OG White/Infrared', price '$140', 5-star rating '(1,247 reviews)'. Size selector: Row of size chips (US 7, 8, 9, 10, 11, 12) — 9 highlighted as selected, 7 greyed out (unavailable). Color options: 3 circular swatches. Description: Short collapsible text. Sticky bottom bar: 'Add to Cart' full-width black button, heart icon (save) to its left.", "deviceType": "MOBILE", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` @@ -65,7 +65,7 @@ "projectId": "3780309359108792857", "prompt": "Mobile High-Fidelity home screen for a fitness tracking app 'FlexOS'. Dark athletic aesthetic. Dark mode. Background: Zinc-900 (#18181B). Primary: Neon green (#22C55E). Font: DM Sans.\n\nTop: Greeting 'Good morning, Alex 👋', date subtitle. Today's goal ring: Large circular progress ring (67% complete), center shows '2,847 / 4,200 cal'. Quick stats row: 3 cards — Steps 8,432, Active Minutes 52, Water 6/8 cups. Workout recommendations: Horizontal scroll of workout cards — gradient thumbnail, workout name, duration, difficulty badge. Recent activity: List of today's logged exercises with icon, name, duration, calories. Bottom nav: Home (active), Workout, Nutrition, Progress, Profile.", "deviceType": "MOBILE", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` diff --git a/skills/stitch-mcp-update-design-system/SKILL.md b/skills/stitch-mcp-update-design-system/SKILL.md index 7fc9e48..fee7629 100644 --- a/skills/stitch-mcp-update-design-system/SKILL.md +++ b/skills/stitch-mcp-update-design-system/SKILL.md @@ -35,6 +35,9 @@ You must have the design system's asset `name` before calling this. If you don't "theme": { "colorMode": "DARK", "font": "GEIST", + "headlineFont": "GEIST", + "bodyFont": "GEIST", + "labelFont": "GEIST", "roundness": "ROUND_TWELVE", "saturation": 2, "customColor": "#818CF8", diff --git a/skills/stitch-orchestrator/examples/workflow.md b/skills/stitch-orchestrator/examples/workflow.md index ae95702..a336ab9 100644 --- a/skills/stitch-orchestrator/examples/workflow.md +++ b/skills/stitch-orchestrator/examples/workflow.md @@ -31,7 +31,9 @@ Output: { "theme": "LIGHT", "primaryColor": "#6366F1", - "font": "DM Sans", + "headlineFont": "DM_SANS", + "bodyFont": "DM_SANS", + "labelFont": "DM_SANS", "roundness": "Medium", "density": "COMPACT", "designMode": "HIGH_FIDELITY", @@ -80,7 +82,7 @@ Result: `{ "name": "projects/3780309359108792857" }` "projectId": "3780309359108792857", "prompt": "[assembled prompt from Step 3]", "deviceType": "DESKTOP", - "modelId": "GEMINI_3_PRO" + "modelId": "GEMINI_3_1_PRO" } } ``` diff --git a/skills/stitch-ui-design-spec-generator/examples/usage.md b/skills/stitch-ui-design-spec-generator/examples/usage.md index 03b266b..a844cc4 100644 --- a/skills/stitch-ui-design-spec-generator/examples/usage.md +++ b/skills/stitch-ui-design-spec-generator/examples/usage.md @@ -9,7 +9,9 @@ { "theme": "DARK", "primaryColor": "#00FF88", - "font": "Orbitron", + "headlineFont": "SPACE_GROTESK", + "bodyFont": "INTER", + "labelFont": "INTER", "roundness": "Low", "density": "COMFORTABLE", "designMode": "HIGH_FIDELITY", @@ -29,7 +31,9 @@ { "theme": "LIGHT", "primaryColor": "#2563EB", - "font": "Inter", + "headlineFont": "INTER", + "bodyFont": "INTER", + "labelFont": "INTER", "roundness": "Low", "density": "COMPACT", "designMode": "HIGH_FIDELITY", @@ -49,7 +53,9 @@ { "theme": "LIGHT", "primaryColor": "#E85D04", - "font": "Nunito", + "headlineFont": "NUNITO_SANS", + "bodyFont": "NUNITO_SANS", + "labelFont": "NUNITO_SANS", "roundness": "High", "density": "COMFORTABLE", "designMode": "HIGH_FIDELITY", @@ -69,7 +75,9 @@ { "theme": "LIGHT", "primaryColor": "#6366F1", - "font": "DM Sans", + "headlineFont": "DM_SANS", + "bodyFont": "DM_SANS", + "labelFont": "DM_SANS", "roundness": "Medium", "density": "COMPACT", "designMode": "HIGH_FIDELITY",