stitch-kit 1.5.0

package/skills/stitch-animate/resources/animation-patterns.md

@@ -0,0 +1,248 @@
+# Animation Patterns — Copy-Paste Reference
+
+Ready-to-use patterns for the most common UI animation scenarios.
+All patterns respect `prefers-reduced-motion`.
+
+---
+
+## 1. Button hover lift (CSS — universal)
+
+```css
+.btn {
+  transition:
+    transform var(--motion-duration-fast) var(--motion-ease-out),
+    box-shadow var(--motion-duration-fast) var(--motion-ease-out),
+    background-color var(--motion-duration-fast) var(--motion-ease-default);
+}
+.btn:hover { transform: translateY(-2px); box-shadow: var(--shadow-md); }
+.btn:active { transform: translateY(0); box-shadow: var(--shadow-sm); }
+```
+
+---
+
+## 2. Card hover elevation (CSS — universal)
+
+```css
+.card {
+  transition:
+    transform var(--motion-duration-base) var(--motion-ease-out),
+    box-shadow var(--motion-duration-base) var(--motion-ease-out);
+}
+.card:hover { transform: translateY(-4px); box-shadow: var(--shadow-lg); }
+```
+
+---
+
+## 3. Fade + rise on page load (CSS keyframes)
+
+```css
+@keyframes fade-up {
+  from { opacity: 0; transform: translateY(20px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+.animate-fade-up {
+  animation: fade-up var(--motion-duration-base) var(--motion-ease-out) both;
+}
+/* Stagger children: add style="--delay: Xms" and use animation-delay: var(--delay) */
+```
+
+---
+
+## 4. Fade in (CSS keyframes)
+
+```css
+@keyframes fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+.animate-fade-in {
+  animation: fade-in var(--motion-duration-fast) var(--motion-ease-out) both;
+}
+```
+
+---
+
+## 5. Scroll reveal — Framer Motion (React/Next.js)
+
+```tsx
+'use client'
+import { motion, useReducedMotion } from 'framer-motion'
+
+export function RevealOnScroll({ children, delay = 0 }: {
+  children: React.ReactNode
+  delay?: number
+}) {
+  const shouldReduce = useReducedMotion()
+  return (
+    <motion.div
+      initial={shouldReduce ? false : { opacity: 0, y: 20 }}
+      whileInView={{ opacity: 1, y: 0 }}
+      viewport={{ once: true, margin: '-60px' }}
+      transition={{ duration: 0.4, ease: [0, 0, 0.2, 1], delay }}
+    >
+      {children}
+    </motion.div>
+  )
+}
+```
+
+---
+
+## 6. Staggered grid — Framer Motion (React/Next.js)
+
+```tsx
+'use client'
+import { motion, useReducedMotion } from 'framer-motion'
+
+const container = {
+  hidden: { opacity: 0 },
+  show: { opacity: 1, transition: { staggerChildren: 0.07 } }
+}
+const item = {
+  hidden: { opacity: 0, y: 16 },
+  show:   { opacity: 1, y: 0, transition: { ease: [0, 0, 0.2, 1], duration: 0.35 } }
+}
+
+export function StaggerGrid({ items }: { items: Item[] }) {
+  const reduce = useReducedMotion()
+  if (reduce) return <div className="grid">{items.map(i => <Card key={i.id} {...i} />)}</div>
+  return (
+    <motion.div className="grid" variants={container} initial="hidden" whileInView="show" viewport={{ once: true }}>
+      {items.map(i => <motion.div key={i.id} variants={item}><Card {...i} /></motion.div>)}
+    </motion.div>
+  )
+}
+```
+
+---
+
+## 7. Modal enter/exit — Framer Motion (React/Next.js)
+
+```tsx
+'use client'
+import { AnimatePresence, motion, useReducedMotion } from 'framer-motion'
+
+export function Modal({ isOpen, onClose, children }: ModalProps) {
+  const reduce = useReducedMotion()
+  const anim = reduce ? {} : { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0 } }
+  const panelAnim = reduce ? {} : {
+    initial: { opacity: 0, y: -20, scale: 0.97 },
+    animate: { opacity: 1, y: 0, scale: 1 },
+    exit:    { opacity: 0, y: 20, scale: 0.97 },
+    transition: { duration: 0.2 }
+  }
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <>
+          <motion.div className="backdrop" {...anim} onClick={onClose} />
+          <motion.div className="modal-panel" role="dialog" aria-modal="true" {...panelAnim}>
+            {children}
+          </motion.div>
+        </>
+      )}
+    </AnimatePresence>
+  )
+}
+```
+
+---
+
+## 8. Fade in — Svelte transition
+
+```svelte
+<script lang="ts">
+  import { fade } from 'svelte/transition'
+  let { show } = $props()
+</script>
+
+{#if show}
+  <div in:fade={{ duration: 200 }} out:fade={{ duration: 150 }}>
+    Content
+  </div>
+{/if}
+```
+
+---
+
+## 9. Slide-in panel — Svelte transition
+
+```svelte
+<script lang="ts">
+  import { fly } from 'svelte/transition'
+  import { cubicOut } from 'svelte/easing'
+  let { isOpen } = $props()
+</script>
+
+{#if isOpen}
+  <aside
+    transition:fly={{ x: -280, duration: 300, easing: cubicOut }}
+    role="dialog"
+    aria-modal="true"
+  >
+    Sidebar content
+  </aside>
+{/if}
+```
+
+---
+
+## 10. Scroll reveal — Svelte action
+
+```svelte
+<script lang="ts">
+  function revealOnScroll(node: HTMLElement, delay = 0) {
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return {}
+    node.style.opacity = '0'
+    node.style.transform = 'translateY(16px)'
+    const observer = new IntersectionObserver(([entry]) => {
+      if (entry.isIntersecting) {
+        node.style.transition = `opacity 400ms cubic-bezier(0,0,0.2,1) ${delay}ms, transform 400ms cubic-bezier(0,0,0.2,1) ${delay}ms`
+        node.style.opacity = '1'
+        node.style.transform = 'translateY(0)'
+        observer.unobserve(node)
+      }
+    }, { threshold: 0.1 })
+    observer.observe(node)
+    return { destroy() { observer.disconnect() } }
+  }
+</script>
+
+<section use:revealOnScroll>Fades in on scroll</section>
+<section use:revealOnScroll={100}>Fades in 100ms later</section>
+```
+
+---
+
+## 11. Number counter (Svelte tweened store)
+
+```svelte
+<script lang="ts">
+  import { tweened } from 'svelte/motion'
+  import { cubicOut } from 'svelte/easing'
+
+  let { target = 1000 } = $props()
+  const count = tweened(0, { duration: 800, easing: cubicOut })
+
+  $effect(() => {
+    count.set(target)
+  })
+</script>
+
+<span>{Math.round($count).toLocaleString()}</span>
+```
+
+---
+
+## Reduced motion reminder
+
+Always add this to your global CSS:
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```

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

@@ -0,0 +1,215 @@
+---
+name: stitch-design-md
+description: Analyzes a Stitch project's screens and synthesizes a natural-language DESIGN.md — visual atmosphere, color palette with hex values, typography rules, and Stitch-ready prompt snippets. Use this before stitch-loop or any multi-page build to establish design consistency.
+allowed-tools:
+  - "stitch*:*"
+  - "Read"
+  - "Write"
+---
+
+# Stitch → DESIGN.md
+
+**Constraint:** Only use this skill when the user explicitly mentions "Stitch" or when preparing design system documentation for Stitch generation.
+
+You are an expert **Design Systems Lead**. Your job is to analyze Stitch project assets and synthesize a **Semantic Design System** into a file named `DESIGN.md` — written in natural language, not CSS.
+
+## When to use this vs. stitch-design-system
+
+| Skill | What it produces | Use it for |
+|-------|-----------------|-----------|
+| `stitch-design-md` | Natural-language `DESIGN.md` | Feeding back into Stitch prompts; multi-page visual consistency; design docs |
+| `stitch-design-system` | `design-tokens.css`, `tailwind-theme.css`, `DESIGN.md` | Code-level theming for Next.js, Svelte, React, HTML output |
+
+Use `stitch-design-md` first if you're building more Stitch screens. Use `stitch-design-system` when you're converting to code.
+
+## Prerequisites
+
+- Stitch MCP Server configured
+- A Stitch project with at least one designed screen
+
+---
+
+## Step 1: Retrieve the design
+
+### If the user provides a Stitch URL
+
+If the user pastes a Stitch design URL like `https://stitch.withgoogle.com/projects/3492931393329678076?node-id=375b1aadc9cb45209bee8ad4f69af450`:
+
+1. Parse the URL:
+   - `projectId` = segment after `/projects/` and before `?` (e.g. `3492931393329678076`)
+   - `screenId` = query param `node-id` (e.g. `375b1aadc9cb45209bee8ad4f69af450`)
+2. Call `[prefix]:get_screen` with those IDs
+3. Skip ahead to Step 2
+
+### If project/screen IDs are unknown
+
+1. Run `list_tools` → find the Stitch MCP prefix
+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)
+
+### Download the assets
+
+```bash
+# Download the HTML for color and Tailwind class analysis
+bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
+```
+
+Parse the HTML for:
+- Tailwind utility classes (colors, typography, spacing, shadows)
+- Inline `tailwind.config` block (custom tokens)
+- CSS variables
+
+---
+
+## Step 2: Analyze the design
+
+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`
+
+### 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?
+
+Examples:
+- "Sophisticated minimalist sanctuary — gallery-like spaciousness, photography-first, Scandinavian calm"
+- "High-density productivity tool — information-first, sharp edges, focused contrast"
+- "Warm artisanal brand — handcrafted feel, organic textures, generous breathing room"
+
+### 2.3 Color palette
+For each key color, write:
+```
+[Descriptive name] ([hex]) — [functional role]
+```
+
+Example:
+```
+Deep Muted Teal-Navy (#294056) — Primary actions, links, active states
+Warm Barely-There Cream (#FCFAFA) — Page background
+Charcoal Near-Black (#2C2C2C) — Headlines and product names
+Soft Warm Gray (#6B6B6B) — Body copy and metadata
+```
+
+Aim for 4–6 colors. Include light AND dark mode backgrounds if both present.
+
+### 2.4 Typography
+- Font family name (from `designTheme.font` or Tailwind class)
+- Weight scale (what's used for display, section headers, body, labels)
+- Any notable letter-spacing, line-height, or size conventions
+
+### 2.5 Shape and geometry
+Translate Tailwind classes to descriptive language:
+- `rounded-full` → "Pill-shaped"
+- `rounded-lg` (12px) → "Gently rounded corners"
+- `rounded-md` (8px) → "Subtly rounded corners"
+- `rounded-none` → "Sharp, squared-off edges"
+
+### 2.6 Depth and elevation
+Describe shadow presence and style:
+- `shadow-none` → "Flat, no shadow"
+- `shadow-sm` → "Whisper-soft diffused shadow"
+- `shadow-lg` → "Prominent floating elevation"
+
+### 2.7 Layout principles
+- Max content width, grid columns, breakpoint behavior
+- Base spacing unit (4px / 8px system)
+- Section margins and padding patterns
+- Touch target sizes (if mobile)
+
+---
+
+## Step 3: Write DESIGN.md
+
+Use this exact structure:
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [numeric ID]
+**Device:** [MOBILE / DESKTOP / TABLET / AGNOSTIC]
+
+## 1. Visual Theme & Atmosphere
+[2–3 sentences describing the overall aesthetic and mood]
+
+## 2. Color Palette & Roles
+- **[Descriptive Name]** ([#hex]) — [Functional role]
+- **[Descriptive Name]** ([#hex]) — [Functional role]
+[...4–6 colors total]
+
+## 3. Typography Rules
+**Primary Font:** [Name] — [One-line character description]
+
+- **Display (H1):** [weight], [size range]
+- **Section (H2):** [weight], [size range]
+- **Body:** [weight], line-height [value], [size]
+- **Labels/Captions:** [weight], [size]
+
+## 4. Component Stylings
+- **Buttons:** [shape (Xpx radius)], [color], [padding]; hover [behavior]
+- **Cards/Containers:** [roundness (Xpx)], [background], [shadow]; hover [behavior]
+- **Inputs/Forms:** [border style], [background], [roundness], [focus behavior]
+
+## 5. Layout Principles
+- Max content width: [value]; [grid description]; [column behavior at breakpoints]
+- Base spacing unit: [4px/8px]; section margins [range]; touch targets [size]
+
+## 6. Design System Notes for Stitch Generation
+[This section is copy-paste ready for new Stitch prompts]
+
+When creating new screens:
+- **Atmosphere:** "[Quote the atmosphere description from Section 1]"
+- **Colors:** Always use descriptive name + hex (e.g. "[Name] ([#hex])")
+- **Shape:** "[Describe buttons and cards using the language from Section 4]"
+- **Spacing:** "[Describe the whitespace/density philosophy]"
+- **Font:** [Font name] — [one-line descriptor]
+```
+
+---
+
+## Step 4: Integration
+
+Tell the user what to do with it:
+
+```
+## DESIGN.md created
+
+Saved to: ./DESIGN.md
+
+**How to use it:**
+
+1. **More Stitch screens:** Copy Section 6 into the DESIGN SYSTEM block of your next Stitch prompt.
+   This keeps every new screen visually consistent with your existing design.
+
+2. **Multi-page build with stitch-loop:** Include Section 6 in every `next-prompt.md` baton file.
+
+3. **Code conversion:** Hand off to `stitch-design-system` when you're ready to generate
+   `design-tokens.css` and `tailwind-theme.css` for your framework.
+```
+
+---
+
+## Best practices
+
+- **Descriptive over technical:** "Ocean-deep Cerulean (#0077B6)" not just "blue"
+- **Functional roles matter:** Don't just name the color — say what it does
+- **Section 6 is the payoff:** This is the copy-paste block that makes every future screen consistent
+- **Be precise:** Exact hex codes always. Vague approximations ("kind of warm beige") are useless
+
+## Common pitfalls
+
+- Leaving `rounded-xl` in the doc instead of translating to "generously rounded corners (12px)"
+- Listing colors without functional roles
+- Skipping the font weight scale (just saying "Manrope" doesn't tell you when to use 400 vs 600)
+- Writing Section 6 without the actual hex codes — useless for Stitch
+
+---
+
+## References
+
+- `examples/usage.md` — Worked examples
+- `examples/DESIGN.md` — Complete sample output for a furniture e-commerce site
+- `docs/color-prompt-guide.md` — 8 ready-to-use color palettes for inspiration
+- `scripts/fetch-stitch.sh` — Reliable HTML downloader for GCS URLs

package/skills/stitch-design-md/examples/DESIGN.md

@@ -0,0 +1,54 @@
+# Design System: Oakwood Furniture Co.
+**Project ID:** 13534454087919359824
+**Device:** DESKTOP
+
+## 1. Visual Theme & Atmosphere
+
+The Oakwood Furniture site embodies a **sophisticated, minimalist sanctuary** that marries Scandinavian simplicity with luxury editorial presentation. The interface feels spacious and tranquil — photography-first, with minimal UI chrome that never competes with the products. Expansive whitespace and a whisper-soft visual hierarchy guide without shouting.
+
+## 2. Color Palette & Roles
+
+- **Warm Barely-There Cream** (#FCFAFA) — Primary page background
+- **Crisp Very Light Gray** (#F5F5F5) — Secondary surface for cards and sidebars
+- **Deep Muted Teal-Navy** (#294056) — Primary actions, buttons, links, active nav states
+- **Charcoal Near-Black** (#2C2C2C) — Headlines, product names, primary text
+- **Soft Warm Gray** (#6B6B6B) — Body copy, metadata, secondary labels
+
+## 3. Typography Rules
+
+**Primary Font:** Manrope — Modern geometric sans-serif with gentle humanist warmth
+
+- **Display (H1):** Semi-bold (600), 2.75–3.5rem
+- **Section (H2):** Semi-bold (600), 2–2.5rem
+- **Body:** Regular (400), line-height 1.7, 1rem
+- **Labels/CTAs:** Medium (500), 1rem
+
+## 4. Component Stylings
+
+- **Buttons:** Subtly rounded corners (8px), Deep Muted Teal-Navy (#294056) fill, comfortable padding (12px 24px); hover darkens by 10%
+- **Cards:** Gently rounded corners (12px), Warm Cream or Very Light Gray background, whisper-soft shadow on hover
+- **Inputs:** 1px border Soft Warm Gray (#6B6B6B), Warm Cream (#FCFAFA) background, 8px roundness, teal-navy glow on focus
+
+## 5. Layout Principles
+
+- Max content width 1440px; responsive 12-column grid; 4/3/2/1 columns across breakpoints
+- Base spacing unit 8px; section margins 5–8rem; touch targets ≥44px
+- Photography given full bleed treatment in hero zones; text content max-width 720px for readability
+
+## 6. Design System Notes for Stitch Generation
+
+Copy this section into new Stitch prompts to maintain visual consistency:
+
+---
+
+**DESIGN SYSTEM:**
+- **Atmosphere:** "Sophisticated minimalist sanctuary with gallery-like spaciousness — photography-first, warm and refined"
+- **Background:** Warm Barely-There Cream (#FCFAFA)
+- **Surface:** Crisp Very Light Gray (#F5F5F5) for cards
+- **Primary Accent:** Deep Muted Teal-Navy (#294056) for buttons and links
+- **Text Primary:** Charcoal Near-Black (#2C2C2C) for headlines
+- **Text Secondary:** Soft Warm Gray (#6B6B6B) for body copy
+- **Font:** Manrope — modern, geometric, approachable
+- **Buttons:** Subtly rounded corners (8px), comfortable padding
+- **Cards:** Gently rounded corners (12px), whisper-soft shadows on hover
+- **Spacing:** Generous breathing room, expansive whitespace, centered max-width container

package/skills/stitch-design-md/examples/usage.md

@@ -0,0 +1,67 @@
+# stitch-design-md — Usage Examples
+
+## Example 1: Extract design system from an existing Stitch screen
+
+**User:** "I've designed the homepage in Stitch. Generate a DESIGN.md so I can keep new screens consistent."
+
+**Skill activates because:** User explicitly mentions "Stitch" and wants design documentation.
+
+**What the skill does:**
+1. Calls `list_projects` → finds the project
+2. Calls `list_screens` → identifies the homepage screen
+3. Calls `get_screen` → gets HTML and screenshot download URLs
+4. Downloads HTML via `scripts/fetch-stitch.sh`
+5. Calls `get_project` → gets `designTheme` (font, roundness, colorMode)
+6. Analyzes HTML for color values, Tailwind classes, typography scale
+7. Writes `DESIGN.md` with atmosphere, palette, typography, components, layout, and Section 6 prompt snippets
+
+**Output:** `DESIGN.md` with complete design system + copy-paste Section 6
+
+---
+
+## Example 2: Multi-page site setup
+
+**User:** "Use Stitch to build a 5-page SaaS site. Generate the homepage first, then set up DESIGN.md for the rest."
+
+**What the skill does:**
+1. After homepage generation, user calls `stitch-design-md`
+2. Extracts design system from the homepage
+3. Creates `DESIGN.md` with Section 6 ready to paste
+4. User then runs `stitch-loop`, including Section 6 in every `next-prompt.md`
+5. Result: all 5 pages share the same colors, fonts, shapes, and spacing
+
+---
+
+## Example 3: From a Stitch URL
+
+**User:** "Here's my Stitch design: https://stitch.withgoogle.com/projects/3492931393329678076?node-id=375b1aadc9cb45209bee8ad4f69af450 — write a DESIGN.md for it."
+
+**What the skill does:**
+1. Parses URL → extracts `projectId: 3492931393329678076`, `screenId: 375b1aadc9cb45209bee8ad4f69af450`
+2. Calls `get_screen` directly (no need for list operations)
+3. Downloads HTML, analyzes, writes DESIGN.md
+
+---
+
+## How DESIGN.md Section 6 gets used downstream
+
+```
+# In next-prompt.md (for stitch-loop):
+
+---
+page: pricing
+---
+A clear pricing page for a SaaS project management tool.
+
+**DESIGN SYSTEM:**
+[Paste Section 6 from DESIGN.md here verbatim]
+
+**Page Structure:**
+1. Pricing hero with tagline
+2. Three pricing tiers (Free, Pro, Enterprise)
+3. Feature comparison table
+4. FAQ accordion
+5. CTA footer
+```
+
+The Section 6 block locks in the visual identity — Stitch uses it to stay consistent with your existing screens.

package/skills/stitch-design-md/scripts/fetch-stitch.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# fetch-stitch.sh
+# Reliably downloads Stitch HTML from Google Cloud Storage URLs.
+# GCS URLs require redirect handling and security handshakes that AI fetch tools fail on.
+#
+# Usage:
+#   bash scripts/fetch-stitch.sh "<url>" "<output-path>"
+#
+# Example:
+#   bash scripts/fetch-stitch.sh "$htmlCode_downloadUrl" "temp/source.html"
+
+set -euo pipefail
+
+URL="${1:?Usage: fetch-stitch.sh <url> <output-path>}"
+OUTPUT="${2:?Usage: fetch-stitch.sh <url> <output-path>}"
+
+mkdir -p "$(dirname "$OUTPUT")"
+
+curl -L \
+  -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" \
+  --compressed \
+  --retry 3 \
+  --retry-delay 1 \
+  --max-time 30 \
+  --silent \
+  --show-error \
+  --output "$OUTPUT" \
+  "$URL"
+
+if [ ! -s "$OUTPUT" ]; then
+  echo "Error: Downloaded file is empty. URL may be expired or invalid." >&2
+  exit 1
+fi
+
+echo "Downloaded to: $OUTPUT ($(wc -c < "$OUTPUT") bytes)"