stitch-kit 1.5.0

package/skills/stitch-shadcn-ui/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: stitch-shadcn-ui
+description: Integrates shadcn/ui into React apps generated from Stitch designs. Component discovery and installation, token alignment with Stitch design system, customization patterns, and blocks (auth, dashboard, sidebar). Use with stitch-react-components or stitch-nextjs-components.
+allowed-tools:
+  - "shadcn*:*"
+  - "mcp_shadcn*"
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# shadcn/ui Integration
+
+**Constraint:** Use when the user asks about shadcn/ui, or wants to add shadcn components to a Stitch-generated React app.
+
+You are a frontend engineer specializing in shadcn/ui — reusable, accessible, customizable components built on Radix UI (or Base UI) and Tailwind CSS. You help discover, install, customize, and extend components within Stitch-generated React projects.
+
+## What shadcn/ui is (and isn't)
+
+shadcn/ui is **not a library** — components are **copied into your project**:
+
+- Code lives in `src/components/ui/` — you own it fully
+- No version lock-in — update components on your schedule
+- Full customization — modify styles, behavior, and structure
+- No extra bundle size — only the components you add are included
+
+Components are built on **Radix UI** primitives: accessible by default, keyboard navigable, ARIA compliant.
+
+## Prerequisites
+
+- React app (Vite or Next.js) with Tailwind CSS
+- Ideally: `stitch-react-components` or `stitch-nextjs-components` has already converted the Stitch design
+
+## Step 1: Initialize shadcn/ui
+
+### New project
+
+```bash
+npx shadcn@latest init
+```
+
+Follow the prompts:
+- **Style:** `default` (rounded, clean) or `new-york` (sharp, minimal)
+- **Base color:** `slate` (cool), `zinc` (neutral), `stone` (warm)
+- **CSS variables:** Yes (required for Stitch token alignment)
+
+### Existing project
+
+```bash
+npx shadcn@latest init
+```
+
+This creates `components.json` with your project configuration.
+
+---
+
+## Step 2: Align tokens with Stitch design system
+
+After running `stitch-design-system`, you'll have `design-tokens.css` with the Stitch color palette. Map these to shadcn's CSS variable format in `globals.css`:
+
+```css
+/* globals.css — map Stitch tokens to shadcn's variable names */
+:root {
+  --background: [from --color-background];
+  --foreground: [from --color-text];
+  --card: [from --color-surface];
+  --card-foreground: [from --color-text];
+  --primary: [from --color-primary];
+  --primary-foreground: [from --color-primaryFg];
+  --secondary: [from --color-surface];
+  --secondary-foreground: [from --color-text];
+  --muted: [from --color-surface];
+  --muted-foreground: [from --color-textMuted];
+  --border: [from --color-border];
+  --ring: [from --color-primary];
+  --radius: 0.5rem; /* match Stitch's border-radius scale */
+}
+
+.dark {
+  /* Same mapping from dark token values */
+  --background: [dark --color-background];
+  /* ... */
+}
+```
+
+---
+
+## Step 3: Discover and install components
+
+### Browse components
+
+Use shadcn MCP `list_components` if available, or browse https://ui.shadcn.com/docs/components
+
+### Install individual components
+
+```bash
+npx shadcn@latest add button
+npx shadcn@latest add card
+npx shadcn@latest add input
+npx shadcn@latest add dialog
+npx shadcn@latest add dropdown-menu
+npx shadcn@latest add table
+npx shadcn@latest add select
+npx shadcn@latest add badge
+npx shadcn@latest add avatar
+npx shadcn@latest add tooltip
+```
+
+### Install a full block (auth, dashboard, etc.)
+
+shadcn provides pre-built blocks:
+
+```bash
+# List available blocks (if MCP available)
+# OR browse: https://ui.shadcn.com/blocks
+
+npx shadcn@latest add [block-name]
+```
+
+Common blocks: `login-01`, `dashboard-01`, `sidebar-01`, `products-01`, `calendar-01`
+
+---
+
+## Step 4: Replace Stitch HTML elements with shadcn components
+
+| Stitch HTML element | Replace with shadcn |
+|---------------------|---------------------|
+| `<button>` primary | `<Button>` with default variant |
+| `<button>` secondary | `<Button variant="outline">` |
+| `<button>` ghost | `<Button variant="ghost">` |
+| `<button>` destructive | `<Button variant="destructive">` |
+| Card/panel container | `<Card><CardHeader><CardContent>` |
+| `<input type="text">` | `<Input>` |
+| `<input type="password">` | `<Input type="password">` |
+| `<select>` | `<Select><SelectTrigger><SelectContent>` |
+| Overlay/popup | `<Dialog><DialogContent>` |
+| Context menu | `<DropdownMenu>` |
+| Notification badge | `<Badge>` |
+| User avatar | `<Avatar><AvatarImage><AvatarFallback>` |
+| Data table | `<Table><TableHeader><TableBody>` |
+| Navigation tabs | `<Tabs><TabsList><TabsContent>` |
+| Alert/banner | `<Alert><AlertDescription>` |
+
+---
+
+## Step 5: Using the `cn()` utility
+
+All shadcn components use `cn()` (clsx + tailwind-merge) for class merging. Keep it in `lib/utils.ts`:
+
+```ts
+// src/lib/utils.ts
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+```
+
+Use it when combining Stitch design token classes with shadcn component classes:
+
+```tsx
+<Button
+  className={cn(
+    "w-full",                    // Stitch layout
+    isLoading && "opacity-50"    // Conditional state
+  )}
+  style={{ backgroundColor: theme.primary }}  // Stitch token
+>
+  Sign In
+</Button>
+```
+
+---
+
+## Customization patterns
+
+### Extend a component variant
+
+```tsx
+// src/components/ui/button.tsx (after npx shadcn add button)
+// Add a new variant in the cva() definition:
+const buttonVariants = cva("...", {
+  variants: {
+    variant: {
+      default: "...",
+      outline: "...",
+      brand: "bg-[--color-primary] text-[--color-primaryFg] hover:opacity-90",  // ← add this
+    },
+  },
+})
+```
+
+### Wrap a component with project-specific props
+
+```tsx
+// src/components/PrimaryButton.tsx
+// Wrap (don't modify) the shadcn Button for project-specific defaults
+import { Button, type ButtonProps } from '@/components/ui/button'
+
+export function PrimaryButton({ children, ...props }: ButtonProps) {
+  return (
+    <Button variant="default" className="w-full" {...props}>
+      {children}
+    </Button>
+  )
+}
+```
+
+---
+
+## Accessibility
+
+Radix UI primitives handle most accessibility automatically:
+- Keyboard navigation (Tab, Enter, Escape, Arrow keys)
+- ARIA attributes (`role`, `aria-expanded`, `aria-haspopup`)
+- Focus management (trapping focus in dialogs, restoring focus on close)
+
+When customizing, **do not remove** ARIA attributes or keyboard handlers from the base components. Add to them, don't replace them.
+
+---
+
+## Integration with Stitch workflow
+
+The typical flow:
+
+```
+stitch-mcp-get-screen → download HTML
+stitch-design-system  → extract tokens → design-tokens.css
+stitch-react-components or stitch-nextjs-components → base components
+stitch-shadcn-ui      → replace raw HTML elements with shadcn components
+                      → align globals.css with design-tokens.css
+stitch-animate        → add transitions to shadcn interactive elements
+stitch-a11y           → verify accessibility (shadcn handles most of it)
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Import path errors (`@/components/ui/...`) | Check `tsconfig.json` and `vite.config.ts` have `@/*` → `./src/*` alias |
+| Colors not matching Stitch design | Map Stitch tokens to shadcn's CSS variables in `globals.css` |
+| Dark mode not working | Ensure `ThemeProvider` (from `next-themes`) wraps the app, or toggle `.dark` class on `<html>` |
+| Missing peer deps | Run `npx shadcn@latest add [component]` again — it auto-installs deps |
+| `cn()` not found | Run `npx shadcn@latest init` to create `lib/utils.ts` |
+
+## References
+
+- shadcn/ui docs: https://ui.shadcn.com/docs
+- Radix UI: https://www.radix-ui.com/
+- `stitch-react-components` — convert Stitch design to base React components first
+- `stitch-nextjs-components` — if using Next.js App Router
+- `stitch-design-system` — extract Stitch tokens before aligning with shadcn

package/skills/stitch-skill-creator/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: stitch-skill-creator
+description: Meta-skill for creating new stitch-kit skills. Enforces naming conventions, SKILL.md structure, examples format, and the Design-First SOP. Use when adding new framework support, a new domain-specific prompt architect, or any new capability to the stitch-kit plugin.
+allowed-tools:
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# Stitch Skill Creator
+
+A factory for creating new **stitch-kit skills**. Enforces standard structure, naming conventions, and the plugin's architectural patterns.
+
+## When to use this skill
+
+- Adding support for a new framework (e.g. "Astro", "Qwik", "Flutter")
+- Creating a domain-specific prompt architect (e.g. `stitch-ui-ecommerce-architect`)
+- Adding a new quality tool (e.g. `stitch-performance`, `stitch-seo`)
+- Any time you need a new SKILL.md that integrates with the stitch-kit ecosystem
+
+---
+
+## Naming conventions
+
+| Skill type | Name pattern | Example |
+|------------|-------------|---------|
+| Framework conversion | `stitch-[framework]-components` | `stitch-astro-components` |
+| Domain prompt architect | `stitch-ui-[domain]-architect` | `stitch-ui-ecommerce-architect` |
+| MCP wrapper | `stitch-mcp-[tool-name]` | `stitch-mcp-edit-screen` |
+| Quality / analysis tool | `stitch-[capability]` | `stitch-performance` |
+| Meta / utility | `stitch-[name]` | `stitch-setup` |
+
+**Rules:**
+- Always kebab-case
+- Always starts with `stitch-`
+- Framework conversion skills end with `-components`
+- MCP wrappers follow `stitch-mcp-{snake_case_tool → kebab}` from `docs/mcp-naming-convention.md`
+
+---
+
+## Required directory structure
+
+```
+skills/[skill-name]/
+├── SKILL.md              ← Required: frontmatter + workflow (keep under 500 lines)
+├── examples/
+│   └── usage.md          ← Required: 2+ worked examples
+├── resources/            ← Optional: templates, checklists, reference tables
+│   ├── component-template.[ext]
+│   └── architecture-checklist.md
+├── scripts/              ← Optional: bash scripts
+│   └── fetch-stitch.sh   ← Copy from stitch-mcp-get-screen/scripts/ if needed
+└── references/           ← Optional: style guides, contracts, long reference docs
+```
+
+---
+
+## SKILL.md template
+
+```markdown
+---
+name: stitch-[skill-name]
+description: [One clear sentence — when to use this skill and what it does. This is used for routing by the orchestrator and for marketplace display.]
+allowed-tools:
+  - "stitch*:*"   # Include if skill calls Stitch MCP tools
+  - "Bash"        # Include if skill runs shell commands
+  - "Read"        # Usually yes
+  - "Write"       # Usually yes
+---
+
+# Stitch → [Target] [Type]
+
+**Constraint:** Only use this skill when the user explicitly mentions "Stitch" [and any additional trigger condition].
+
+[One sentence explaining what this skill does and who the agent "is" while using it.]
+
+## When to use this skill vs. similar skills
+
+[Table comparing this skill to its nearest alternatives — help the orchestrator route correctly]
+
+## Prerequisites
+
+[What the user/environment needs before this skill can run]
+
+## 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"`
+
+## Step 2: [Core conversion / workflow]
+
+[The main logic of this skill]
+
+## Step N: Output
+
+[What the skill produces — files, code, commands]
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+
+## References
+
+- `resources/component-template.[ext]` — [description]
+- `resources/architecture-checklist.md` — Pre-ship checklist
+- `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader
+```
+
+---
+
+## Examples template (examples/usage.md)
+
+```markdown
+# [Skill Name] — Usage Examples
+
+## Example 1: [Scenario title]
+
+**User:** "[Specific user request]"
+
+**Skill activates because:** [Why this triggers the skill]
+
+**What the skill does:**
+1. [Step 1]
+2. [Step 2]
+3. ...
+
+**Output:**
+[Description or code snippet of what gets generated]
+
+---
+
+## Example 2: [Different scenario]
+
+[Same format]
+```
+
+---
+
+## Architecture checklist template (resources/architecture-checklist.md)
+
+Adapt this to the target platform/framework:
+
+```markdown
+# [Framework] Components — Architecture Checklist
+
+Run through this checklist before marking the task complete.
+
+## Structure
+- [ ] [Project structure check]
+- [ ] Components are in separate files
+
+## [Framework-specific category]
+- [ ] [Framework-specific check]
+
+## TypeScript / Types
+- [ ] No `any` types
+- [ ] All props have Readonly<> wrapper
+
+## Dark mode
+- [ ] Theme tokens used everywhere — no hardcoded colors
+
+## Accessibility
+- [ ] All interactive elements are keyboard accessible
+- [ ] Images have descriptive alt text
+
+## Performance
+- [ ] No console.log in production code
+```
+
+---
+
+## Creating a framework conversion skill
+
+For a new framework (e.g. Astro):
+
+### 1. Create the directory
+
+```bash
+mkdir -p skills/stitch-astro-components/resources
+mkdir -p skills/stitch-astro-components/examples
+mkdir -p skills/stitch-astro-components/scripts
+```
+
+### 2. Copy the fetch script
+
+```bash
+cp skills/stitch-mcp-get-screen/scripts/fetch-stitch.sh \
+   skills/stitch-astro-components/scripts/fetch-stitch.sh
+```
+
+### 3. Write SKILL.md
+
+Use the template above. Key sections for framework skills:
+- **When to use vs. similar skills** — distinguish from Next.js, Svelte, etc.
+- **Project structure** — show the file layout
+- **HTML → Framework mapping** — table of HTML/CSS patterns → framework equivalents
+- **Design tokens** — how to handle Stitch's CSS variables in this framework
+- **Dark mode** — how this framework handles it
+- **Accessibility** — framework-specific ARIA patterns
+
+### 4. Create component template
+
+Write `resources/component-template.[ext]` — a working boilerplate component that demonstrates:
+- Props interface
+- Theme token usage
+- Dark mode
+- Accessibility attributes
+- Conditional rendering patterns
+
+### 5. Create architecture checklist
+
+Write `resources/architecture-checklist.md` with framework-specific checks.
+
+### 6. Write examples
+
+At least 2 examples in `examples/usage.md`.
+
+### 7. Register in marketplace.json
+
+Add to the appropriate plugin group in `.claude-plugin/marketplace.json`:
+- Web frameworks → `stitch-frameworks`
+- Mobile → `stitch-mobile`
+- New category → create a new group
+
+### 8. Update docs/skills-index.md
+
+Add the new skill to the table.
+
+### 9. Update README.md
+
+Add to the appropriate layer table.
+
+---
+
+## Creating a domain-specific prompt architect
+
+For a new domain (e.g. e-commerce):
+
+The skill name: `stitch-ui-ecommerce-architect`
+
+This skill **does not generate or execute** — it produces a structured Stitch prompt. Pattern:
+
+1. Identify domain-specific components (product card, cart, checkout flow, review stars, etc.)
+2. Define the `[Context] [Layout] [Components]` prompt template for this domain
+3. Reference `stitch-ued-guide` for visual vocabulary
+4. Output is: a ready-to-use prompt for `stitch-mcp-generate-screen-from-text`
+
+---
+
+## References
+
+- `docs/skills-index.md` — existing skills (check before creating duplicates)
+- `docs/mcp-naming-convention.md` — MCP tool naming rules
+- `stitch-nextjs-components/SKILL.md` — reference for a well-structured framework conversion skill
+- `stitch-swiftui-components/SKILL.md` — reference for a mobile platform skill

package/skills/stitch-skill-creator/references/output-patterns.md

@@ -0,0 +1,71 @@
+# Output Patterns
+
+Consistency templates for newly created Stitch skills.
+
+---
+
+## Domain prompt architect output (STRICT)
+
+A `stitch-ui-[domain]-architect` skill must return exactly one code block and no extra prose.
+
+Required structure:
+
+```text
+[Context]
+...
+
+[Layout]
+...
+
+[Components]
+...
+```
+
+Hard requirements:
+- Do not call any MCP tool — prompt assembly only, no execution
+- Do not output multiple alternatives unless the user explicitly asks for variants
+- Preserve the section labels exactly: `[Context]`, `[Layout]`, `[Components]`
+
+---
+
+## Skill creator output (recommended)
+
+When `stitch-skill-creator` scaffolds a new skill, report artifacts concisely:
+
+```markdown
+# Stitch Skill Created
+
+## Path
+- skills/stitch-[name]
+
+## Files
+- SKILL.md
+- examples/usage.md
+- resources/architecture-checklist.md  (if framework conversion)
+- scripts/fetch-stitch.sh              (if needs HTML download)
+
+## Next steps
+1. Fill domain-specific details in SKILL.md (step-by-step workflow, routing table, troubleshooting).
+2. Replace placeholder examples in `examples/usage.md` with real input/output pairs.
+3. Add to `.claude-plugin/marketplace.json` in the appropriate plugin group.
+4. Add row to `docs/skills-index.md`.
+5. Add row to `README.md` in the appropriate layer table.
+```
+
+---
+
+## MCP wrapper skill output
+
+`stitch-mcp-*` skills report the tool call result directly. No reformatting needed — just surface the relevant IDs and URLs clearly so downstream skills can use them.
+
+Minimum output:
+
+```markdown
+## [Tool Name] complete
+
+- **Project ID:** [numeric]  ← use this for generate_screen_from_text and get_screen
+- **Project path:** projects/[numeric]  ← use this for get_project and list_screens
+- **Screen ID:** [hex]  ← use this for get_screen
+- **HTML:** [downloadUrl]
+- **Screenshot:** [downloadUrl]
+```