npm - stitch-kit - Versions diffs - 1.5.0 - Mend

stitch-kit 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/AGENTS.md +139 -0
package/CHANGELOG.md +86 -0
package/README.md +167 -0
package/agents/stitch-kit.md +93 -0
package/bin/stitch-kit.mjs +430 -0
package/docs/architecture.md +118 -0
package/docs/color-prompt-guide.md +119 -0
package/docs/mcp-naming-convention.md +64 -0
package/docs/mcp-schemas/README.md +130 -0
package/docs/mcp-schemas/apply_design_system.json +36 -0
package/docs/mcp-schemas/create_design_system.json +78 -0
package/docs/mcp-schemas/create_project.json +290 -0
package/docs/mcp-schemas/delete_project.json +20 -0
package/docs/mcp-schemas/edit_screens.json +46 -0
package/docs/mcp-schemas/generate_screen_from_text.json +242 -0
package/docs/mcp-schemas/generate_variants.json +77 -0
package/docs/mcp-schemas/get_project.json +137 -0
package/docs/mcp-schemas/get_screen.json +92 -0
package/docs/mcp-schemas/list_design_systems.json +32 -0
package/docs/mcp-schemas/list_projects.json +136 -0
package/docs/mcp-schemas/list_screens.json +56 -0
package/docs/mcp-schemas/update_design_system.json +32 -0
package/docs/mcp-schemas/upload_screens_from_images.json +52 -0
package/docs/prd-to-stitch-workflow.md +137 -0
package/docs/skills-index.md +108 -0
package/docs/tailwind-reference.md +207 -0
package/package.json +41 -0
package/skills/stitch-a11y/SKILL.md +428 -0
package/skills/stitch-a11y/resources/audit-checklist.md +102 -0
package/skills/stitch-animate/SKILL.md +371 -0
package/skills/stitch-animate/resources/animation-patterns.md +248 -0
package/skills/stitch-design-md/SKILL.md +215 -0
package/skills/stitch-design-md/examples/DESIGN.md +54 -0
package/skills/stitch-design-md/examples/usage.md +67 -0
package/skills/stitch-design-md/scripts/fetch-stitch.sh +35 -0
package/skills/stitch-design-system/SKILL.md +314 -0
package/skills/stitch-design-system/resources/tokens-template.css +237 -0
package/skills/stitch-html-components/SKILL.md +344 -0
package/skills/stitch-html-components/resources/architecture-checklist.md +74 -0
package/skills/stitch-html-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-loop/SKILL.md +183 -0
package/skills/stitch-loop/examples/SITE.md +39 -0
package/skills/stitch-loop/examples/next-prompt.md +24 -0
package/skills/stitch-loop/examples/usage.md +77 -0
package/skills/stitch-mcp-apply-design-system/SKILL.md +82 -0
package/skills/stitch-mcp-create-design-system/SKILL.md +117 -0
package/skills/stitch-mcp-create-project/SKILL.md +77 -0
package/skills/stitch-mcp-delete-project/SKILL.md +62 -0
package/skills/stitch-mcp-edit-screens/SKILL.md +121 -0
package/skills/stitch-mcp-generate-screen-from-text/SKILL.md +102 -0
package/skills/stitch-mcp-generate-screen-from-text/examples/desktop.md +53 -0
package/skills/stitch-mcp-generate-screen-from-text/examples/mobile.md +71 -0
package/skills/stitch-mcp-generate-variants/SKILL.md +124 -0
package/skills/stitch-mcp-get-project/SKILL.md +67 -0
package/skills/stitch-mcp-get-screen/SKILL.md +117 -0
package/skills/stitch-mcp-get-screen/scripts/fetch-stitch.sh +35 -0
package/skills/stitch-mcp-list-design-systems/SKILL.md +84 -0
package/skills/stitch-mcp-list-projects/SKILL.md +77 -0
package/skills/stitch-mcp-list-screens/SKILL.md +69 -0
package/skills/stitch-mcp-update-design-system/SKILL.md +82 -0
package/skills/stitch-mcp-upload-screens-from-images/SKILL.md +95 -0
package/skills/stitch-mcp-upload-screens-from-images/scripts/encode-image.sh +43 -0
package/skills/stitch-nextjs-components/SKILL.md +181 -0
package/skills/stitch-nextjs-components/resources/architecture-checklist.md +65 -0
package/skills/stitch-nextjs-components/resources/component-template.tsx +101 -0
package/skills/stitch-nextjs-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-orchestrator/SKILL.md +337 -0
package/skills/stitch-orchestrator/examples/workflow.md +173 -0
package/skills/stitch-react-components/SKILL.md +236 -0
package/skills/stitch-react-components/references/tailwind-to-react.md +117 -0
package/skills/stitch-react-components/resources/architecture-checklist.md +34 -0
package/skills/stitch-react-components/resources/component-template.tsx +35 -0
package/skills/stitch-react-components/scripts/fetch-stitch.sh +35 -0
package/skills/stitch-react-native-components/SKILL.md +333 -0
package/skills/stitch-react-native-components/resources/architecture-checklist.md +74 -0
package/skills/stitch-react-native-components/resources/component-template.tsx +104 -0
package/skills/stitch-react-native-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-remotion/SKILL.md +280 -0
package/skills/stitch-setup/SKILL.md +183 -0
package/skills/stitch-shadcn-ui/SKILL.md +255 -0
package/skills/stitch-skill-creator/SKILL.md +257 -0
package/skills/stitch-skill-creator/references/output-patterns.md +71 -0
package/skills/stitch-skill-creator/scripts/init_stitch_skill.py +229 -0
package/skills/stitch-svelte-components/SKILL.md +282 -0
package/skills/stitch-svelte-components/resources/architecture-checklist.md +62 -0
package/skills/stitch-svelte-components/resources/component-template.svelte +193 -0
package/skills/stitch-svelte-components/scripts/fetch-stitch.sh +36 -0
package/skills/stitch-swiftui-components/SKILL.md +424 -0
package/skills/stitch-swiftui-components/resources/architecture-checklist.md +83 -0
package/skills/stitch-swiftui-components/resources/component-template.swift +131 -0
package/skills/stitch-swiftui-components/resources/layout-mapping.md +155 -0
package/skills/stitch-swiftui-components/scripts/fetch-stitch.sh +45 -0
package/skills/stitch-ued-guide/SKILL.md +124 -0
package/skills/stitch-ui-design-spec-generator/SKILL.md +115 -0
package/skills/stitch-ui-design-spec-generator/examples/usage.md +79 -0
package/skills/stitch-ui-design-variants/SKILL.md +127 -0
package/skills/stitch-ui-prompt-architect/SKILL.md +196 -0
package/skills/stitch-ui-prompt-architect/references/KEYWORDS.md +170 -0

package/skills/stitch-react-components/SKILL.md ADDED Viewed

@@ -0,0 +1,236 @@
+---
+name: stitch-react-components
+description: Converts Stitch designs into modular Vite + React components — TypeScript, theme-mapped Tailwind, dark mode via CSS variables, and clean component architecture. Use this for Vite/React apps without App Router. For Next.js 15 App Router, use stitch-nextjs-components instead.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+# Stitch → Vite / React Components
+**Constraint:** Only use this skill when the user explicitly mentions "Stitch" and React (Vite, CRA, or just "React app" without Next.js).
+You are a frontend engineer converting Stitch mobile/desktop designs into clean, modular React components using Vite + TypeScript. This skill targets plain React apps — **not** Next.js App Router. For Next.js, use `stitch-nextjs-components` instead.
+## When to use this skill vs. Next.js
+| Scenario | Use |
+|----------|-----|
+| User says "React app", "Vite", "CRA" | `stitch-react-components` |
+| User says "Next.js", "App Router", "SSR" | `stitch-nextjs-components` |
+| User wants shadcn/ui components added after | `stitch-react-components` → then `stitch-shadcn-ui` |
+| User wants server-side rendering or file-based routing | `stitch-nextjs-components` |
+## Prerequisites
+- Stitch MCP Server configured (or use downloaded HTML directly)
+- Node.js + npm/pnpm
+- Vite + React project initialized: `npm create vite@latest my-app -- --template react-ts`
+## Step 1: Retrieve the design
+1. Run `list_tools` → find Stitch MCP prefix
+2. Call `[prefix]:get_screen` with numeric `projectId` and `screenId`
+3. Download HTML: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"`
+4. Check `screenshot.downloadUrl` — verify layout matches expectations
+## Step 2: Project structure
+```
+src/
+├── components/           ← One file per component
+│   └── [Name].tsx
+├── data/
+│   └── mockData.ts       ← Static content (never in components)
+├── theme/
+│   ├── tokens.ts         ← Design token constants
+│   └── useTheme.ts       ← Dark mode hook
+├── types/
+│   └── index.ts          ← Shared TypeScript types
+├── App.tsx               ← Root component
+└── main.tsx              ← Entry point
+```
+## Step 3: Extract design tokens
+From the Stitch HTML `<head>`, find the `tailwind.config` or CSS variable definitions.
+```ts
+// src/theme/tokens.ts — extract hex values from Stitch HTML
+export const lightTokens = {
+  background: '#FFFFFF',
+  surface:    '#F4F4F5',
+  primary:    '#6366F1',
+  primaryFg:  '#FFFFFF',
+  text:       '#09090B',
+  textMuted:  '#71717A',
+  border:     '#E4E4E7',
+} as const
+export const darkTokens = {
+  background: '#09090B',
+  surface:    '#18181B',
+  primary:    '#818CF8',
+  primaryFg:  '#09090B',
+  text:       '#FAFAFA',
+  textMuted:  '#A1A1AA',
+  border:     '#27272A',
+} as const
+export type ThemeTokens = typeof lightTokens
+```
+```ts
+// src/theme/useTheme.ts
+import { useEffect, useState } from 'react'
+import { lightTokens, darkTokens, type ThemeTokens } from './tokens'
+/**
+ * Returns current theme tokens based on system color scheme.
+ * Listens for system-level dark/light mode changes.
+ */
+export function useTheme(): ThemeTokens {
+  const [isDark, setIsDark] = useState(
+    () => window.matchMedia('(prefers-color-scheme: dark)').matches
+  )
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    const handler = (e: MediaQueryListEvent) => setIsDark(e.matches)
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [])
+  return isDark ? darkTokens : lightTokens
+}
+```
+## Step 4: Component conversion rules
+### Layout mapping
+| HTML/CSS | → React / Tailwind |
+|---|---|
+| `display:flex; flex-direction:column` | `<div className="flex flex-col gap-4">` |
+| `display:flex; flex-direction:row` | `<div className="flex items-center gap-2">` |
+| `justify-content:space-between` | `<div className="flex justify-between">` |
+| `display:grid; grid-template-columns:1fr 1fr` | `<div className="grid grid-cols-2 gap-4">` |
+| `overflow-y:scroll` | `<div className="overflow-y-auto">` |
+| Long list | `items.map(item => <Card key={item.id} {...item} />)` |
+| `<img>` | `<img src="..." alt="..." className="object-cover">` |
+### Tailwind class mapping
+Use the Stitch HTML classes directly in JSX where they don't reference Stitch-specific tokens. Map Stitch tokens to CSS variables:
+```tsx
+// Stitch HTML: bg-primary → CSS variable → Tailwind arbitrary value
+// OR: use inline style with token value
+// Option A — Tailwind arbitrary value (if custom tokens in tailwind.config)
+<div className="bg-[--color-primary] text-[--color-primaryFg]">
+// Option B — inline style with useTheme()
+const theme = useTheme()
+<div style={{ backgroundColor: theme.primary, color: theme.primaryFg }}>
+```
+### Component template
+```tsx
+// src/components/StitchComponent.tsx
+/**
+ * Props for StitchComponent — all data via props, never fetched inside.
+ */
+interface StitchComponentProps {
+  /** Primary heading text */
+  title: string
+  /** Supporting description — optional */
+  description?: string
+  /** Primary action callback */
+  onAction?: () => void
+}
+/**
+ * StitchComponent — [describe purpose in one sentence]
+ */
+export function StitchComponent({
+  title,
+  description,
+  onAction,
+}: Readonly<StitchComponentProps>) {
+  const theme = useTheme()
+  return (
+    <div
+      className="rounded-xl border p-4 gap-2 flex flex-col"
+      style={{
+        backgroundColor: theme.surface,
+        borderColor: theme.border,
+      }}
+    >
+      <h3 className="text-base font-semibold" style={{ color: theme.text }}>
+        {title}
+      </h3>
+      {description ? (
+        <p className="text-sm" style={{ color: theme.textMuted }}>
+          {description}
+        </p>
+      ) : null}
+      {onAction ? (
+        <button
+          onClick={onAction}
+          className="rounded-lg px-4 py-2 text-sm font-medium transition-opacity hover:opacity-90"
+          style={{ backgroundColor: theme.primary, color: theme.primaryFg }}
+          type="button"
+        >
+          Action
+        </button>
+      ) : null}
+    </div>
+  )
+}
+```
+## Step 5: Architectural rules
+- **One component per file** — no single-file spaghetti
+- **Static data in `src/data/mockData.ts`** — never hardcoded in JSX
+- **Shared types in `src/types/index.ts`**
+- **Every component has `Readonly<ComponentNameProps>` interface**
+- **No hardcoded hex colors** — use `useTheme()` or CSS variables
+- **No `any` types**
+## Step 6: Integration with shadcn/ui
+After converting the Stitch design to base React components, you can layer in shadcn/ui:
+```bash
+npx shadcn@latest init    # Set up shadcn in your Vite project
+npx shadcn@latest add button card input dialog
+```
+Then use `stitch-shadcn-ui` skill to replace raw HTML elements with shadcn components while preserving the Stitch design tokens.
+## Troubleshooting
+| Issue | Fix |
+|-------|-----|
+| Tailwind classes not applying | Check `tailwind.config.js` includes `./src/**/*.{ts,tsx}` in content |
+| Dark mode not toggling | Verify `useTheme()` is called at component level, not hoisted |
+| Images not showing | Add explicit `width` and `height` or use `className="w-full h-auto"` |
+| Type error on props | Ensure `Readonly<>` wrapper and all required props are provided |
+## References
+- `resources/component-template.tsx` — Boilerplate component
+- `resources/architecture-checklist.md` — Pre-ship checklist
+- `references/tailwind-to-react.md` — Token + class mapping guide (Stitch HTML → React/Tailwind)
+- `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader
+- `stitch-shadcn-ui` — Add shadcn/ui components after base conversion
+- `docs/tailwind-reference.md` — Tailwind utility class lookup

package/skills/stitch-react-components/references/tailwind-to-react.md ADDED Viewed

@@ -0,0 +1,117 @@
+# Tailwind → React (Vite + Tailwind) Mapping
+When converting **Stitch HTML** to React, **keep Tailwind utility classes** but **map Stitch design tokens to the project theme** (`tailwind.config`, CSS variables). Never copy raw hex when a theme key exists.
+> Rule: Extract Stitch's inline `tailwind.config` (from the HTML `<script>` block or `DESIGN.md`) and sync with your project's `tailwind.config.*` before generating components.
+---
+## 1. Layout
+| Tailwind pattern | React output |
+|------------------|--------------|
+| `flex`, `flex-col`, `flex items-center` | Keep as-is |
+| `grid`, `grid-cols-2`, `grid-cols-3` | Keep as-is |
+| `sticky top-0` | Keep as-is |
+| `container`, `mx-auto` | Keep as-is |
+---
+## 2. Spacing
+| Tailwind | React |
+|----------|-------|
+| `p-*`, `px-*`, `py-*` | Keep (`p-4`, `px-6`) |
+| `mb-*`, `gap-*`, `space-y-*` | Keep |
+No conversion needed — Tailwind spacing IS the output.
+---
+## 3. Sizing
+| Tailwind | React |
+|----------|-------|
+| `w-full`, `w-10`, `h-*`, `min-h-screen` | Keep all |
+---
+## 4. Typography
+| Tailwind | React |
+|----------|-------|
+| `text-xs` → `text-2xl` | Keep |
+| `font-normal`, `font-medium`, `font-bold` | Keep |
+| `text-gray-500` | Keep OR map to `text-muted-foreground` if project uses shadcn-style tokens |
+| `text-primary` | Map to theme: ensure `primary` is in `theme.extend.colors` |
+Prefer **semantic token names** (`text-foreground`, `text-muted-foreground`) over raw `text-gray-*` when the project has them.
+---
+## 5. Colors — Stitch → project theme
+| Stitch / Tailwind | React |
+|-------------------|-------|
+| `bg-primary`, `text-primary` | Map to `tailwind.config` `theme.extend.colors.primary` |
+| `background-light`, `background-dark` | Map to theme `background` or use `bg-[#hex]` only if no theme key |
+| `card-light`, `card-dark` | Map to `card`, `card-foreground` (shadcn-style) |
+| `border-light`, `border-dark` | Map to theme border color |
+| `shadow-soft`, `shadow-floating` (Stitch) | Define in `theme.extend.boxShadow`; then use `shadow-soft` in JSX |
+---
+## 6. Borders & Radius
+| Tailwind | React |
+|----------|-------|
+| `border`, `border-b`, `border-2 border-dashed` | Keep |
+| `rounded`, `rounded-lg`, `rounded-xl`, `rounded-full` | Keep; add to `theme.extend.borderRadius` if Stitch overrides defaults |
+| `border-gray-200`, `dark:border-gray-700` | Keep or map to `border`, `border-muted` |
+---
+## 7. Effects
+| Tailwind | React |
+|----------|-------|
+| `shadow-sm`, `shadow-md` | Keep |
+| `shadow-soft` (Stitch custom) | Add to `theme.extend.boxShadow` in config |
+---
+## 8. Interactivity
+| Tailwind | React |
+|----------|-------|
+| `hover:bg-gray-100` | Keep or theme `hover:bg-accent` |
+| `focus:ring-1 focus:ring-primary` | Keep; ensure `primary` in theme |
+| `dark:*` variants | Keep; ensure dark mode is configured (`class` or `media`) |
+| `peer`, `peer-checked:` | Keep OR replace with React `useState` + conditional class |
+---
+## 9. Icons — Material Symbols → React
+Stitch HTML uses Material Symbols font icons. Replace in React:
+| Stitch | React (Lucide) |
+|--------|----------------|
+| `chevron_left` | `<ChevronLeft />` |
+| `expand_more` | `<ChevronDown />` |
+| `add` | `<Plus />` |
+| `remove` | `<Minus />` |
+| `add_photo_alternate` | `<ImagePlus />` |
+| `search` | `<Search />` |
+| `close` | `<X />` |
+Do not include Material Symbols font in React unless the project explicitly uses it.
+---
+## 10. Don't do these
+- Don't use raw hex in `className` when a theme key exists (`bg-primary` not `bg-[#1677FF]`)
+- Don't leave Stitch token names (`background-light`) in JSX unless they're in your `tailwind.config`
+- Don't use raw `<button>` or `<input>` when the project has shared components — use those with `className` passed through
+- Don't forget to add Stitch's custom `borderRadius` and `boxShadow` to the project config — otherwise `rounded-xl` and `shadow-soft` won't compile correctly

package/skills/stitch-react-components/resources/architecture-checklist.md ADDED Viewed

@@ -0,0 +1,34 @@
+# React (Vite) Components — Architecture Checklist
+Run through this before marking the conversion complete.
+## Structure
+- [ ] Each component is in its own file under `src/components/`
+- [ ] Custom hooks extracted to `src/hooks/`
+- [ ] Static content (labels, mock data, lists) in `src/data/mockData.ts`
+- [ ] No single monolithic file — if it's over 200 lines, split it
+## Type safety
+- [ ] Props interfaces use `Readonly<ComponentNameProps>`
+- [ ] No `any` types — use `unknown` and narrow
+- [ ] Template placeholder `StitchComponent` replaced with real component name
+## Styling
+- [ ] Stitch design tokens extracted and synced to `tailwind.config` (`theme.extend.colors`, `borderRadius`, `boxShadow`)
+- [ ] Theme-mapped class names used (`bg-primary`, `text-foreground`) — no raw hex in className
+- [ ] Dark mode (`dark:` variants) applied where applicable
+- [ ] No leftover Stitch-only tokens (e.g. `background-light`) unless defined in project config
+## Functionality
+- [ ] `useTheme()` hook implemented and wired to `dark:` classes or CSS variable root
+- [ ] All interactive elements have `onClick` / `onChange` handlers (or clear TODO comments)
+- [ ] No `console.log` in production code
+## Accessibility
+- [ ] All interactive elements are keyboard accessible
+- [ ] `<img>` elements have descriptive `alt` text
+- [ ] ARIA attributes added where semantic HTML isn't enough
+## References
+- `references/tailwind-to-react.md` — token + class mapping guide
+- `resources/component-template.tsx` — base component structure

package/skills/stitch-react-components/resources/component-template.tsx ADDED Viewed

@@ -0,0 +1,35 @@
+import React from 'react';
+/**
+ * Template for Stitch-converted React components.
+ * Replace `StitchComponent` with the actual component name.
+ * Replace `StitchComponentProps` with domain-specific props.
+ *
+ * @see resources/architecture-checklist.md before shipping
+ * @see references/tailwind-to-react.md for class mapping patterns
+ */
+interface StitchComponentProps {
+  /** Content to render inside the component */
+  readonly children?: React.ReactNode;
+  /** Additional Tailwind classes to merge in */
+  readonly className?: string;
+}
+/**
+ * Base Stitch component wrapper.
+ * Demonstrates: typed props, className passthrough, dark mode readiness.
+ */
+export const StitchComponent: React.FC<StitchComponentProps> = ({
+  children,
+  className = '',
+}) => {
+  return (
+    // Use theme-mapped tokens (bg-background, text-foreground) — never hardcoded hex
+    <div className={`relative bg-background text-foreground ${className}`}>
+      {children}
+    </div>
+  );
+};
+export default StitchComponent;

package/skills/stitch-react-components/scripts/fetch-stitch.sh ADDED Viewed

@@ -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)"