| name | screen-designer |
| description | Generate UI screen designs via Stitch SDK (HTML output, design variants) and Nano Banana 2 (Gemini Flash Image for visual mockups). For mobile, web, dashboards, landing pages. Triggers on: "design a screen", "mockup", "redesign", "generate UI", "nano banana", "stitch".
|
| user-invocable | true |
| argument-hint | <description of the screen to design> |
| compatibility | Requires Bun. Nano Banana needs GEMINI_API_KEY. Stitch needs STITCH_API_KEY. |
| tags | design, ui, mockup, nano-banana, gemini, stitch, mobile, web, desktop, tablet, screen, app, redesign, landing-page, dashboard, html, variants, design-system |
Screen Designer (Dual Engine)
Generate UI screen designs for any platform using two complementary engines:
- Stitch SDK โ HTML/CSS output, iterative editing, variants, DESIGN.md consistency
- Nano Banana 2 โ Raster image generation, screenshot redesign, visual concepts
Context
- Working directory: !
pwd
- Gemini API key: !
test -n "$GEMINI_API_KEY$GOOGLE_AI_API_KEY" && echo "YES" || echo "NO โ set GEMINI_API_KEY"
- Stitch API key: !
test -n "$STITCH_API_KEY" && echo "YES" || echo "NO โ set STITCH_API_KEY"
- Nano Banana SDK: !
test -f "${CLAUDE_SKILL_DIR}/scripts/node_modules/@google/genai/package.json" && echo "YES" || echo "NO โ run: cd ${CLAUDE_SKILL_DIR}/scripts && bun install"
- Stitch SDK: !
test -f "${CLAUDE_SKILL_DIR}/scripts/node_modules/@google/stitch-sdk/package.json" && echo "YES" || echo "NO โ run: cd ${CLAUDE_SKILL_DIR}/scripts && bun install"
Setup (first time only)
cd "${CLAUDE_SKILL_DIR}/scripts" && bun install
Step 0: Select Engine
The core rule is simple:
Design system completo / intera app / multi-screen โ Stitch (DESIGN.md, iterazione, consistenza)
Singola schermata o componente โ Nano Banana 2 (veloce, visuale, diretto)
| Scenario | Engine | Reason |
|---|
| Full app design / redesign (multiple screens) | Stitch | Creates DESIGN.md, iterative editing, multi-screen consistency |
| Design system creation (colors, fonts, tokens) | Stitch | Generates extractable design tokens from Tailwind config |
| Desktop/web design with usable HTML | Stitch | HTML+Tailwind output is directly usable |
| Iterative editing ("change X on this screen") | Stitch | Built-in edit API, preserves context |
| Design variants (explore alternatives) | Stitch | REFINE/EXPLORE/REIMAGINE with aspect control |
| Single screen mockup (any platform) | Nano Banana | Faster, direct visual output |
| Single component visualization | Nano Banana | Quick visual concept |
| Redesign from screenshot | Nano Banana | Stitch SDK doesn't accept image input |
| Visual concept / art / illustration | Nano Banana | Image generation strength |
| User explicitly requests an engine | Respect choice | Always honor user preference |
Mobile projects (Expo/React Native): Stitch HTML is a visual reference only โ it cannot be used directly in RN. Use Stitch when designing the full app to get: (1) consistent design system across all screens, (2) extractable design tokens (palette, fonts, spacing), (3) iterative editing. Use Nano Banana for quick single-screen mockups.
Track A: Stitch Engine
Step A1: Understand the request
Determine the mode, device type, and whether to use DESIGN.md:
Mode:
- Generate: New screen from text prompt (no project-id needed, one will be created)
- Edit: Modify an existing Stitch screen (requires both --project-id AND --screen-id from previous generation)
- Variants: Explore alternative designs. If --screen-id is given, --project-id is also required. Without --screen-id, a new base screen is generated first.
Device type mapping:
| Platform | DeviceType | Notes |
|---|
| iPhone, Android phone | MOBILE | HTML is reference only for RN/Expo |
| Desktop web, SaaS app | DESKTOP | HTML is directly usable |
| Dashboard, admin panel | DESKTOP | HTML is directly usable |
| Landing page, marketing | DESKTOP | HTML is directly usable |
| iPad, Android tablet | TABLET | HTML reference for native, usable for web |
| Flexible / unknown | AGNOSTIC | Let Stitch decide |
Model selection:
GEMINI_3_PRO โ Higher quality, slower (default)GEMINI_3_FLASH โ Faster iteration, slightly lower quality
Step A2: Build the prompt
Write a clear, specific prompt. Use Stitch prompting best practices:
- Be specific: "A SaaS pricing page with 3 tiers, annual/monthly toggle, and comparison table" not "a pricing page"
- Set the vibe: Use adjectives โ "minimalist, warm, professional"
- One change at a time: For edits, focus on a single modification
- Include color preferences: "dark mode with purple accents" or exact hex values
- Reference platform patterns: "bottom navigation bar", "sidebar with icons", "hero section"
For multi-screen flows, create or reference a DESIGN.md (see DESIGN.md section below).
Step A3: Generate
New screen:
bun "${CLAUDE_SKILL_DIR}/scripts/stitch-generate.ts" \
--prompt "<description>" \
--device-type "<MOBILE|DESKTOP|TABLET|AGNOSTIC>" \
--model "<GEMINI_3_PRO|GEMINI_3_FLASH>" \
--output "/tmp/screen-designer"
With DESIGN.md for consistency:
bun "${CLAUDE_SKILL_DIR}/scripts/stitch-generate.ts" \
--prompt "<description>" \
--device-type "MOBILE" \
--design-md "./DESIGN.md" \
--output "/tmp/screen-designer"
Edit existing screen:
bun "${CLAUDE_SKILL_DIR}/scripts/stitch-generate.ts" \
--prompt "Change the header to a gradient from blue to purple" \
--mode edit \
--project-id "<from previous JSON output>" \
--screen-id "<from previous JSON output>" \
--output "/tmp/screen-designer"
Generate variants:
bun "${CLAUDE_SKILL_DIR}/scripts/stitch-generate.ts" \
--prompt "Explore different layouts and color schemes" \
--mode variants \
--variant-count 3 \
--creative-range "EXPLORE" \
--aspects "LAYOUT,COLOR_SCHEME" \
--project-id "<from previous JSON output>" \
--screen-id "<from previous JSON output>" \
--output "/tmp/screen-designer"
Variant options:
| Option | Values | Description |
|---|
--variant-count | 1-5 | Number of variants (default: 3) |
--creative-range | REFINE, EXPLORE, REIMAGINE | How far from original. REFINE = subtle tweaks, REIMAGINE = radical |
--aspects | LAYOUT, COLOR_SCHEME, IMAGES, TEXT_FONT, TEXT_CONTENT | Which design aspects to vary (comma-separated) |
Step A4: Show results
- Read the generated image (PNG) to display the visual design โ note: some screens may not return an image URL, in which case the imagePath field will be absent from JSON
- Note the HTML path โ mention it so the user can open it in a browser
- Capture projectId and screenId from the JSON output โ these are required for follow-up edits/variants
- Present design choices and ask for feedback
- For mobile projects: remind user the HTML is a visual reference, not production code
Important: Always pass --project-id and --screen-id from the previous JSON output when using --mode edit or --mode variants with an existing screen. The script validates these upfront and will error if missing.
Stitch examples
Mobile โ Fitness app (reference for React Native):
bun stitch-generate.ts -p "A fitness tracking app main screen: daily step counter ring, heart rate card, weekly activity bar chart, bottom tab navigation with Home/Workouts/Nutrition/Profile. Dark theme with purple (#6C5CE7) and teal (#00CEC9) accents on dark background (#1A1A2E)" -d MOBILE
Desktop โ SaaS dashboard (usable HTML):
bun stitch-generate.ts -p "Analytics dashboard: left sidebar nav with icons, top KPI cards row (Revenue, Users, Conversion, MRR), full-width revenue line chart, two-column bottom section with user growth bar chart and geographic heatmap. Dark mode, Shadcn style, Inter font" -d DESKTOP -m GEMINI_3_PRO
Landing page (usable HTML):
bun stitch-generate.ts -p "AI writing assistant landing page: sticky nav, hero with large headline and email signup CTA, trusted-by logos bar, 3-column features grid, testimonial cards, 3-tier pricing table, footer. Dark theme with vibrant purple-to-cyan gradients, glassmorphism cards" -d DESKTOP
Track B: Nano Banana Engine
Step B1: Understand the request
Determine the mode and platform:
Mode:
- New design: User describes a screen from scratch
- Redesign: User provides a screenshot and wants it redesigned/improved
- Multi-screen flow: User wants multiple related screens
Platform (infer from context or ask):
| Platform | Device Frame | Aspect Ratio | Design System |
|---|
| iPhone | iPhone 16 Pro | 9:16 | iOS 18 native, SF Pro, SF Symbols |
| Android phone | Pixel 9 Pro | 9:16 | Material Design 3, Roboto, Material Icons |
| iPad | iPad Pro 13" | 3:4 | iPadOS, sidebar + content, SF Pro |
| Android tablet | Galaxy Tab S10 | 5:8 | Material 3 adaptive layout |
| Desktop web | Browser 1440px | 16:9 | Custom/Tailwind/Shadcn |
| Desktop app | macOS window | 16:10 | macOS native / Electron |
| Laptop web | Browser 1280px | 16:9 | Responsive web |
| Landing page | Full page scroll | 9:16 or 1:2 | Marketing/hero-driven |
| Dashboard | Wide monitor | 21:9 or 16:9 | Data-dense, sidebar + grid |
| Watch | Apple Watch | 5:6 | watchOS, compact |
Step B2: Build the JSON prompt
Build a structured JSON prompt tailored to the platform:
{
"image_type": "<platform_screen_type>",
"device": {
"frame": "<device name or browser chrome>",
"display": "<display type>",
"orientation": "<portrait|landscape>"
},
"app_concept": "<what the app/site does>",
"screen": "<which screen>",
"design_system": {
"style": "<iOS 18 / Material 3 / Tailwind / Shadcn / custom>",
"corners": "<border radius>",
"shadows": "<shadow style>",
"spacing": "<grid system>"
},
"color_palette": {
"primary": "<hex>",
"secondary": "<hex>",
"background": "<hex>",
"surface": "<hex>",
"text": "<hex>"
},
"layout": {
"navigation": "<top nav / sidebar / bottom tabs / hamburger>",
"hero": "<main content area>",
"sections": ["<section descriptions>"],
"footer": "<footer or bottom nav>"
},
"visual_details": {
"illustrations": "<icon/illustration style>",
"typography": "<font choices>",
"mood": "<visual mood>"
}
}
Platform-specific layout patterns:
- Mobile:
bottom_nav with 4-5 tabs, single-column, cards, swipeable carousels
- Tablet: Sidebar + content split, master-detail, multi-column grid
- Desktop web: Top navbar + hero + content sections + footer, sidebar optional
- Dashboard: Fixed sidebar nav + header + content grid with cards/charts/tables
- Landing page: Hero with CTA + features grid + testimonials + pricing + footer
- Desktop app: Title bar + toolbar + sidebar + main content + status bar
For redesign with screenshot, prepend this to the JSON prompt:
Redesign this screen. Keep the same functionality and information architecture,
but modernize the visual design with: <user's style preferences>.
Here is the current screen design to reimagine:
Step B3: Generate the image
bun "${CLAUDE_SKILL_DIR}/scripts/generate.ts" \
--prompt "<brief description for logging>" \
--json-prompt '<full JSON prompt>' \
--aspect-ratio "<ratio from device table>" \
--output "/tmp/screen-designer" \
--count <N>
For redesign with screenshot:
bun "${CLAUDE_SKILL_DIR}/scripts/generate.ts" \
--prompt "<brief description>" \
--json-prompt '<full JSON prompt>' \
--screenshot "<path to screenshot>" \
--aspect-ratio "<ratio>" \
--output "/tmp/screen-designer"
Step B4: Show results
- Read the generated image(s) using the Read tool to display them
- Present each screen with a brief description of design choices
- Ask if they want variations, adjustments, or another screen
DESIGN.md for Multi-Screen Consistency
When generating multiple related screens (especially with Stitch), create a DESIGN.md in the working directory to ensure visual consistency.
Creating a DESIGN.md
Either:
- Generate with Stitch first โ after the first screen, extract the design tokens and create the DESIGN.md
- Write manually โ create from the user's requirements
Template:
# Design System โ [App Name]
## Overview
[1-2 sentences: personality, density, aesthetic philosophy]
## Colors
- **Primary** (#hex): [role โ CTAs, active states]
- **Secondary** (#hex): [role โ supporting UI]
- **Background** (#hex): [role โ page backgrounds]
- **Surface** (#hex): [role โ cards, containers]
- **Text** (#hex): [role โ primary text]
- **Error** (#hex): [role โ validation, destructive]
## Typography
- **Headlines**: [font], [weight], [size range]
- **Body**: [font], [weight], [size]
- **Labels**: [font], [weight], [size]
## Components
- **Buttons**: [shape, variants, states]
- **Cards**: [elevation, radius, padding]
- **Navigation**: [pattern, active states]
- **Inputs**: [border, background, focus]
## Do's and Don'ts
- Do [guideline]
- Don't [anti-pattern]
Usage with Stitch:
bun stitch-generate.ts -p "Settings page" --design-md ./DESIGN.md --project-id <id>
Usage with Nano Banana:
Include the design system details directly in the JSON prompt's color_palette, design_system, and visual_details fields. Reuse the same values across all screens.
Prompt Engineering Guidelines
General (both engines):
- Always specify the device frame and platform context
- Include explicit color palette โ never leave colors to chance
- Describe each layout section in natural language
- Add mood/atmosphere keywords (clean, bold, minimalist, glassmorphism, brutalist, etc.)
- For text-heavy screens, specify actual placeholder content
Stitch-specific:
- Use adjectives to set the vibe โ "sophisticated", "playful", "minimalist"
- Be specific about elements โ "card with rounded corners and subtle shadow"
- One change per edit prompt โ Stitch handles single focused changes best
- For variants: specify which aspects to vary (LAYOUT, COLOR_SCHEME, etc.)
Nano Banana-specific:
- Use structured JSON for maximum quality
- For redesigns: always include screenshot via
--screenshot
- Name the target style explicitly (iOS 18, Material 3, etc.)
For multi-screen flows (both engines):
- Generate one screen at a time for consistency
- Use DESIGN.md (Stitch) or reuse same JSON palette (Nano Banana)
- Reference previous screens in the prompt
Platform tips:
- Mobile: Focus on thumb-friendly zones, large touch targets, single-column
- Web: Include browser chrome for realism, consider responsive breakpoints
- Dashboard: Prioritize data density, use charts/graphs, dark mode works well
- Landing page: Hero image/gradient is critical, clear CTA hierarchy
Troubleshooting
Nano Banana:
- "No image generated": Prompt may have triggered safety filters. Simplify the description.
- Rate limited: Script auto-retries after 10s. For batch, add pauses.
- Low quality: Use more detailed JSON prompts with explicit color palettes.
- Wrong platform feel: Be explicit about design system (iOS 18 vs Material 3 vs web).
Stitch:
- Timeout: Generation can take up to 60s. Don't retry prematurely.
- Rate limited [RATE_LIMITED]: 350 standard / 50 experimental generations per month. Use GEMINI_3_FLASH for faster iteration.
- Auth error [AUTH_FAILED]: Check STITCH_API_KEY is set and valid.
- Edit fails: Both --project-id and --screen-id are required for edit mode. Get them from the JSON output of a previous generation.
- Variants with existing screen: --project-id is required when using --screen-id in variants mode.
- "Unknown option" error: The script validates all CLI flags. Run with
--help to see valid options.
- Invalid device-type/model/creative-range/aspects: The script validates all enum values at startup. Valid values are shown in the error message.
- Mobile HTML not matching RN: Expected โ Stitch HTML is a reference. Extract design tokens (colors, spacing, fonts) for your RN implementation.
SDK not found:
cd "${CLAUDE_SKILL_DIR}/scripts" && bun install
