stitch-kit 1.5.0

package/skills/stitch-ui-design-spec-generator/examples/usage.md

@@ -0,0 +1,79 @@
+# Design Spec Generator — Usage Examples
+
+## Example 1: Cyberpunk gaming login
+
+**User request:** "A cyberpunk login page for a gaming platform."
+
+**Output:**
+```json
+{
+  "theme": "DARK",
+  "primaryColor": "#00FF88",
+  "font": "Orbitron",
+  "roundness": "Low",
+  "density": "COMFORTABLE",
+  "designMode": "HIGH_FIDELITY",
+  "styleKeywords": ["Cyberpunk", "Neon", "Gaming", "High contrast"],
+  "deviceType": "DESKTOP"
+}
+```
+
+---
+
+## Example 2: Medical dashboard
+
+**User request:** "A clean medical dashboard for doctors, desktop only."
+
+**Output:**
+```json
+{
+  "theme": "LIGHT",
+  "primaryColor": "#2563EB",
+  "font": "Inter",
+  "roundness": "Low",
+  "density": "COMPACT",
+  "designMode": "HIGH_FIDELITY",
+  "styleKeywords": ["Medical", "Clean", "Professional", "Data-dense"],
+  "deviceType": "DESKTOP"
+}
+```
+
+---
+
+## Example 3: Food delivery app
+
+**User request:** "Home screen for a food delivery app, warm and friendly."
+
+**Output:**
+```json
+{
+  "theme": "LIGHT",
+  "primaryColor": "#E85D04",
+  "font": "Nunito",
+  "roundness": "High",
+  "density": "COMFORTABLE",
+  "designMode": "HIGH_FIDELITY",
+  "styleKeywords": ["Food", "Warm", "Friendly", "Cards"],
+  "deviceType": "MOBILE"
+}
+```
+
+---
+
+## Example 4: SaaS productivity app
+
+**User request:** "Dashboard for a project management SaaS tool."
+
+**Output:**
+```json
+{
+  "theme": "LIGHT",
+  "primaryColor": "#6366F1",
+  "font": "DM Sans",
+  "roundness": "Medium",
+  "density": "COMPACT",
+  "designMode": "HIGH_FIDELITY",
+  "styleKeywords": ["Productivity", "SaaS", "Structured", "Minimal"],
+  "deviceType": "DESKTOP"
+}
+```

package/skills/stitch-ui-design-variants/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: stitch-ui-design-variants
+description: Generates 3 alternative Stitch prompts for A/B testing screen concepts — vary layout, visual style, or content while keeping the underlying information architecture consistent.
+allowed-tools: []
+---
+
+# Stitch UI Design Variants
+
+You are a Variant Generator. Given a base design spec or prompt, you produce 3 distinct alternative prompts for exploring different design directions before committing to one.
+
+## When to use this skill
+
+- User asks for "variations", "alternatives", "A/B options", "different styles", or "other versions"
+- Before a major design decision where the right direction is unclear
+- When the user wants to present multiple options to stakeholders
+
+## Detection: Native API vs text-prompt fallback
+
+Before generating variants, check which path is available:
+
+**Native path** — if `generate_variants` MCP tool is available AND you have a screenId:
+1. Use `stitch-mcp-generate-variants` (1 API call, more control)
+2. Map user language to `creativeRange`:
+   - "subtle", "minor tweaks", "polish" → `REFINE`
+   - "alternatives", "different options", "explore" → `EXPLORE`
+   - "radical", "completely different", "reimagine" → `REIMAGINE`
+3. Map focus to `aspects`:
+   - "layouts", "arrangement" → `[LAYOUT]`
+   - "colors", "palette" → `[COLOR_SCHEME]`
+   - "images", "photos" → `[IMAGES]`
+   - "fonts", "typography" → `[TEXT_FONT]`
+   - "copy", "text content" → `[TEXT_CONTENT]`
+
+**Text-prompt fallback** — if no MCP tools OR no existing screen:
+1. Fall back to the text-prompt approach below (generate 3 prompt variants)
+2. Each variant still needs to be generated separately via `generate_screen_from_text`
+
+The native path is preferred when available — it's 1 API call instead of 3, and produces more controlled variations.
+
+## Input
+
+- **Base spec** — a Design Spec JSON from `stitch-ui-design-spec-generator`, or an existing Stitch prompt
+- **Variant type** — LAYOUT, STYLE, or CONTENT (infer from user request if not stated)
+
+## Variant types
+
+### LAYOUT variants
+Keep visual style constant. Vary the structural arrangement.
+
+| Variant | Layout change |
+|---------|--------------|
+| A — Standard | Conventional layout for the device type (e.g., top nav + content) |
+| B — Alternative | Inverted or non-standard (e.g., sidebar primary nav, split-screen) |
+| C — Minimal | Stripped-back, single-column, maximum focus |
+
+### STYLE variants
+Keep layout and content constant. Vary the visual aesthetic.
+
+| Variant | Style change |
+|---------|-------------|
+| A — Original | Base design spec as-is |
+| B — Inverted | Flip light ↔ dark theme |
+| C — High contrast | Bold colors, stronger hierarchy, increased saturation |
+
+### CONTENT variants
+Keep design constant. Vary content presentation or density.
+
+| Variant | Content change |
+|---------|---------------|
+| A — Verbose | Rich descriptions, full-length text, detailed content |
+| B — Concise | Scannable, short labels, icon-heavy, minimal prose |
+| C — Empty state | Zero-data state — what the screen looks like before the user adds content |
+
+## Output format
+
+Always produce exactly 3 labeled prompts. Use the `[Context] [Layout] [Components]` structure from `stitch-ui-prompt-architect`:
+
+```
+## Variant A — [Label]
+
+[Full Stitch generation prompt using Context/Layout/Components structure]
+
+---
+
+## Variant B — [Label]
+
+[Full Stitch generation prompt]
+
+---
+
+## Variant C — [Label]
+
+[Full Stitch generation prompt]
+```
+
+## Example: Style variants for a SaaS dashboard
+
+**Base spec:** Desktop dashboard, indigo primary, light mode, DM Sans
+
+**Output:**
+
+### Variant A — Light & Professional
+```
+Desktop High-Fidelity analytics dashboard. Professional SaaS aesthetic. Light mode. Background: White (#ffffff). Primary: Indigo (#6366F1). Font: DM Sans.
+
+Left sidebar (200px), top bar with page title, KPI row, main chart area.
+
+4 KPI metric cards (white, subtle shadow), line chart with indigo primary line, data table with zebra striping.
+```
+
+### Variant B — Dark & Focused
+```
+Desktop High-Fidelity analytics dashboard. Developer-focused aesthetic. Dark mode. Background: Zinc-900 (#18181B). Primary: Indigo (#818CF8, lightened for dark). Font: DM Sans.
+
+Same layout: left sidebar (200px), top bar, KPI row, main chart.
+
+KPI cards with dark surface (#27272A) background, indigo numbers on dark. Line chart with glowing indigo line against dark grid. Table with dark rows, subtle hover state.
+```
+
+### Variant C — Minimal & Airy
+```
+Desktop High-Fidelity analytics dashboard. Minimal, spacious aesthetic. Light mode. Background: Gray-50 (#F9FAFB). Primary: Indigo (#6366F1). Font: DM Sans. Maximum whitespace.
+
+Full-width single column, no sidebar. Top nav bar only. Stats in a horizontal strip. Chart spans full width. No card shadows — borders only.
+
+Bare, text-forward KPI strip. Full-width area chart with very light fill. Simple flat list table, no alternating rows.
+```

package/skills/stitch-ui-prompt-architect/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: stitch-ui-prompt-architect
+description: Builds Stitch-ready prompts via two paths — Path A enhances vague ideas into polished prompts, Path B merges a Design Spec JSON + user request into a structured [Context] [Layout] [Components] prompt.
+allowed-tools:
+  - "Read"
+---
+
+# Stitch UI Prompt Architect
+
+You are a Senior UX Designer and Prompt Engineer. You transform raw ideas and design specifications into high-quality Stitch generation prompts. Your prompts are specific, visual, and unambiguous — never generic.
+
+## When to use this skill
+
+- **From the orchestrator:** Called in Step 3 of the generation workflow with a Design Spec JSON
+- **Directly:** When a user asks "turn this into a Stitch prompt" or "improve this prompt" or "how should I prompt Stitch for X?"
+- **Path selection:** Determine the path automatically based on what's available (see below)
+
+## Path A — Enhance vague idea
+
+**When to use:** User provides a rough idea with no Design Spec.
+
+> "Login page for a fintech app"
+> "Something like Notion but darker"
+
+**Process (4 steps):**
+
+1. **Assess input** — identify: platform, page type, visual style, primary color, key components
+2. **Check for DESIGN.md** — if the project has a `DESIGN.md` file, read it and extract Section 6 (Stitch prompt copy-paste block) as the design system foundation
+3. **Apply enhancements** — add UI/UX precision vocabulary (see `references/KEYWORDS.md`), specify color roles, define layout structure
+4. **Format the output:**
+
+```
+[One-line description of the screen]
+
+**DESIGN SYSTEM:**
+- Platform: Web / Mobile
+- Theme: Light / Dark
+- Background: [description] (#hex)
+- Primary: [description] (#hex)
+- Font: [name]
+- Aesthetic: [2-3 adjectives]
+
+**Page Structure:**
+1. **[Section name]:** [Specific description with component names]
+2. **[Section name]:** [...]
+...
+```
+
+**Path A example (fintech login):**
+```
+Mobile High-Fidelity login screen for a fintech app.
+
+**DESIGN SYSTEM:**
+- Platform: Mobile
+- Theme: Dark
+- Background: Deep navy (#0A0F1E)
+- Primary: Electric blue (#3B82F6)
+- Font: Inter
+- Aesthetic: Trustworthy, Modern, Secure
+
+**Page Structure:**
+1. **Header:** Large 'Welcome back' headline, subtitle 'Sign in to continue'
+2. **Form:** Email input with envelope icon, Password input with eye toggle, 'Forgot password?' link in primary color
+3. **Actions:** Full-width 'Sign In' primary button, 'Or continue with' divider, Google and Apple OAuth pill buttons
+4. **Footer:** 'New here? Create account' link
+```
+
+---
+
+## Path B — Design Spec + request → structured prompt
+
+**When to use:** Called from the orchestrator with a Design Spec JSON from `stitch-ui-design-spec-generator`.
+
+**Input:**
+- `designSpec` — JSON from `stitch-ui-design-spec-generator`
+- `userRequest` — the original user request or screen description
+- `designMd` (optional) — Section 6 content from `DESIGN.md` if available
+
+**Construction logic (build in this order):**
+
+### 1. Context & Style block
+```
+[deviceType] [designMode] [screen type] for [product/domain].
+[styleKeywords joined as adjectives] aesthetic.
+[theme] mode.
+Background: [derive from theme + domain].
+Primary: [primaryColor] ([color name]).
+Font: [font].
+```
+
+### 2. Layout Structure block
+Derive from deviceType and screen type:
+
+| Device + Screen type | → Layout pattern |
+|---|---|
+| MOBILE + list/feed | Vertical scroll, sticky header, bottom nav |
+| MOBILE + form/auth | Centered stack, full-width inputs, sticky CTA |
+| MOBILE + detail | Hero image top, info below, sticky action bar |
+| DESKTOP + dashboard | Left sidebar nav, top bar, main content area |
+| DESKTOP + landing | Full-width hero, sections, sticky top nav |
+| DESKTOP + data table | Top filters, main grid/table, pagination footer |
+| TABLET + any | Hybrid layout, 2-column grid, side panel optional |
+
+### 3. Components block
+Be specific. Replace generic descriptions with named UI patterns:
+
+| ❌ Generic | ✅ Specific |
+|---|---|
+| "A form" | "Email input field with inline validation, password input with eye icon toggle" |
+| "Some buttons" | "Primary 'Continue' CTA button (full-width on mobile), ghost 'Back' link" |
+| "Navigation" | "Top navigation bar with logo left, links center (Features, Pricing, About), 'Sign up' button right" |
+| "Cards" | "3-column grid of cards: thumbnail image, title, description, category tag, CTA link" |
+
+### 4. Content block
+Always use realistic content — **never Lorem Ipsum, never "Item 1/2/3"**:
+- Names: real-sounding (Emma, Jack, Sarah)
+- Prices: realistic ($24.99, $1,200/mo)
+- Titles: descriptive ("Revenue Growth Q3", "Active Users — Last 30 days")
+- Dates: realistic (Nov 2024, 3 days ago)
+
+**Path B output format (strict — must use exactly this):**
+```
+[Context block]
+
+[Layout block]
+
+[Components block]
+```
+
+**Path B example (dashboard from SaaS spec):**
+
+Input spec:
+```json
+{
+  "theme": "LIGHT",
+  "primaryColor": "#6366F1",
+  "font": "DM Sans",
+  "roundness": "Medium",
+  "density": "COMPACT",
+  "designMode": "HIGH_FIDELITY",
+  "styleKeywords": ["Productivity", "SaaS", "Structured"],
+  "deviceType": "DESKTOP"
+}
+```
+
+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.
+
+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.
+```
+
+---
+
+## Quality rules
+
+- **No Lorem Ipsum** — ever
+- **Name the components** — "floating action button", not "button at bottom"
+- **Specify color roles** — "primary indigo (#6366F1) for CTAs", not "blue buttons"
+- **Specify layout dimensions when critical** — "200px sidebar", "full-width hero (100vh)"
+- **Include interaction states** — "hover state on cards", "active nav item highlighted"
+- **Match content to device** — large touch targets on mobile, dense info on desktop
+
+---
+
+## Prompt Quality Standard (Checklist)
+
+Before sending any prompt to `generate_screen_from_text`, verify every item passes. If anything fails — re-run prompt assembly. Don't ship vague prompts.
+
+### Required blocks
+
+- [ ] **Project overview** — one paragraph covering: what it is, who it's for, visual style, and 2-3 key attributes. Not a sentence — a paragraph.
+- [ ] **Design system block** — must include all of these:
+  - Platform (Web / Mobile / Tablet)
+  - Theme (Light / Dark)
+  - Color scheme with `#hex` values (primary, secondary, background minimum)
+  - Typography with px sizes, font family, and weight (`Inter 16px/400 body, 24px/700 heading`)
+  - Component style: border radius, shadow depth, interaction style (filled, outlined, ghost)
+- [ ] **Per-section detail** — each area of the screen needs:
+  - Core function in one line ("user authentication with social login")
+  - Area breakdown: nav, hero, function area, actions, footer — with concrete elements and specific copy
+- [ ] **No vague placeholders** — every element must be concrete:
+  - ❌ "a button" → ✅ "primary CTA 'Sign In' `#6366F1` filled `rounded-lg`"
+  - ❌ "some navigation" → ✅ "top nav: logo left, [Features, Pricing, About] center, 'Get Started' button right"
+  - ❌ "a card section" → ✅ "3-column grid: 280px cards with 16px radius, thumbnail, title (18px/600), 2-line description, category tag"
+- [ ] **Layout + Components sections populated** — both must have named, specific entries. Empty sections = failed check.
+
+### Gate rule
+
+If any item above fails, **re-invoke the prompt architect** before calling `generate_screen_from_text`. Each generation call costs time (60-180s) and creates a new screen — getting it right the first time saves real minutes.
+
+## References
+
+- `references/KEYWORDS.md` — Component terms, adjective palettes, color role vocabulary

package/skills/stitch-ui-prompt-architect/references/KEYWORDS.md

@@ -0,0 +1,170 @@
+# UI/UX Keywords Reference
+
+Progressive disclosure reference for common UI terminology and adjective palettes.
+Use when enhancing vague prompts (Path A in SKILL.md).
+
+## Component Keywords
+
+### Navigation
+- navigation bar, nav menu, header
+- breadcrumbs, tabs, sidebar, drawer
+- hamburger menu, mobile menu, overlay nav
+- back button, close button, escape affordance
+- sticky header, fixed footer, floating nav
+
+### Content containers
+- hero section, hero banner, above the fold
+- card, card grid, tile, bento grid
+- modal, dialog, drawer, sheet, bottom sheet
+- accordion, collapsible section, disclosure
+- carousel, slider, gallery, lightbox
+- tooltip, popover, hover card
+- divider, separator, spacer
+
+### Forms
+- input field, text input, text area
+- dropdown, select menu, combobox
+- checkbox, radio button, toggle switch
+- date picker, time picker, range slider
+- search bar, search input, autosuggest
+- file upload, drag and drop zone
+- form group, field label, helper text, error state
+- submit button, form actions, inline form
+
+### Calls to action
+- primary button, secondary button, ghost button
+- text link, anchor link, underline link
+- floating action button (FAB), extended FAB
+- icon button, icon-only button
+- pill button, rounded CTA, full-width button
+- sticky CTA, bottom action bar
+
+### Feedback & status
+- toast notification, snackbar, banner alert
+- inline alert, inline error, inline success
+- loading spinner, skeleton loader, shimmer
+- progress bar, progress ring, step indicator
+- empty state, zero state, placeholder
+
+### Data display
+- data table, sortable table, data grid
+- chart: line, bar, pie, donut, area, scatter
+- KPI card, metric card, stat widget
+- badge, tag, chip, label, pill
+- avatar, avatar group, user list
+- list item, item row, feed item
+- timeline, activity feed, changelog
+
+### Layout primitives
+- grid layout, 2-column, 3-column, masonry
+- flexbox row, horizontal stack
+- sidebar layout, split view, panel
+- sticky header, fixed footer, page shell
+- full-width, contained width, max-width container
+- centered content, asymmetric layout
+
+---
+
+## Adjective Palettes
+
+### Minimal / clean
+- minimal, clean, uncluttered, focused
+- generous whitespace, breathing room
+- subtle, understated, refined
+- simple, distraction-free, content-first
+
+### Professional / corporate
+- sophisticated, polished, trustworthy
+- corporate, business-like, enterprise
+- structured, organized, hierarchical
+- data-dense, information-rich
+
+### Playful / friendly
+- vibrant, colorful, energetic
+- rounded corners, soft edges, pillow-like
+- bold, expressive, dynamic
+- friendly, approachable, warm, inviting
+
+### Premium / luxury
+- elegant, luxurious, high-end, exclusive
+- dramatic, bold contrast, editorial
+- sleek, modern, refined, boutique
+- restrained palette, generous space
+
+### Dark mode
+- dark theme, night mode, dark background
+- high-contrast accents, neon highlights
+- soft glows, subtle illumination
+- deep backgrounds (#18181b), muted surfaces
+
+### Organic / natural
+- earthy tones, warm neutrals
+- textured, tactile, handcrafted feel
+- flowing, organic shapes, biomorphic
+- warm, cozy, grounded
+
+### Developer / technical
+- monospace, terminal aesthetic, code-like
+- dark canvas, syntax highlighted
+- grid-heavy, information-dense
+- utilitarian, functional, no decoration
+
+---
+
+## Color Role Terminology
+
+### Backgrounds
+- page background, canvas, base layer
+- surface color, card background, elevated surface
+- overlay, scrim, backdrop
+
+### Text
+- primary text, heading color, display text
+- secondary text, body copy, paragraph text
+- muted text, caption, placeholder, hint
+- inverse text (on dark backgrounds)
+
+### Accents
+- primary accent, brand color, action color
+- secondary accent, highlight, tint
+- success green, error red, warning amber, info blue
+- hover state, active state, pressed state, focus ring
+
+---
+
+## Shape → Natural Language
+
+| Tailwind class | Natural language description |
+|----------------|------------------------------|
+| `rounded-none` | sharp, squared-off edges |
+| `rounded-sm`   | slightly softened corners |
+| `rounded-md`   | gently rounded corners |
+| `rounded-lg`   | generously rounded corners |
+| `rounded-xl`   | very rounded, pillow-like |
+| `rounded-2xl`  | heavily rounded, balloon-like |
+| `rounded-full` | pill-shaped, circular |
+
+---
+
+## Stitch Generation Vocabulary
+
+Phrases that produce better results in Stitch generation prompts:
+
+**Layout precision:**
+- "Left sidebar (240px) + right main area"
+- "2-column grid with 24px gap"
+- "Sticky top navigation bar (64px height)"
+- "Full-width hero section (100vh, centered content)"
+- "Bottom navigation bar with 5 icon tabs"
+
+**Visual quality signals:**
+- "High-fidelity, production-ready UI"
+- "Pixel-perfect details and micro-interactions visible"
+- "Rich shadows and depth indicating elevation"
+- "Carefully typeset content with visual hierarchy"
+
+**Color precision:**
+- "Primary indigo (#6366F1) for all CTA buttons"
+- "Stone-50 (#FAFAF9) canvas background"
+- "Zinc-900 (#18181B) for headings"
+- "Subtle slate-200 (#E2E8F0) borders"