stitch-kit 1.5.0

package/skills/stitch-skill-creator/scripts/init_stitch_skill.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""
+Stitch Skill Initializer — bootstraps a new stitch-kit skill from the standard template.
+
+Usage:
+    python3 init_stitch_skill.py <skill-name> --path <path>
+
+Examples:
+    python3 init_stitch_skill.py ecommerce-architect --path skills/
+    # Creates: skills/stitch-ui-ecommerce-architect
+
+    python3 init_stitch_skill.py stitch-ui-blog-architect --path skills/
+    # Creates: skills/stitch-ui-blog-architect
+
+    python3 init_stitch_skill.py flutter-components --path skills/
+    # Creates: skills/stitch-flutter-components
+
+Rules:
+    - Domain prompt architects: stitch-ui-[domain]-architect
+    - Framework conversion skills: stitch-[framework]-components
+    - Quality/analysis tools: stitch-[capability]
+    - MCP wrappers: stitch-mcp-[tool-name]
+"""
+
+import sys
+import re
+from pathlib import Path
+
+# ─── Templates ────────────────────────────────────────────────────────────────
+
+SKILL_MD_TEMPLATE = """\
+---
+name: {skill_name}
+description: [One clear sentence — when to use this skill and what it does.]
+allowed-tools:
+  - "Read"
+  - "Write"
+---
+
+# {scenario_title}
+
+**Constraint:** Only use this skill when the user explicitly mentions "Stitch" [and any additional trigger condition].
+
+[One sentence describing what this skill does.]
+
+## When to use this skill vs. similar skills
+
+| Skill | Use when |
+|-------|---------|
+| `{skill_name}` | [This skill's use case] |
+| `[similar-skill]` | [The other skill's use case] |
+
+## Prerequisites
+
+- [What the user/environment needs before this skill can run]
+
+## Step 1: [First step]
+
+[Instructions]
+
+## Step 2: [Core workflow]
+
+[Instructions]
+
+## Output
+
+[What this skill produces]
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+
+## References
+
+- `examples/usage.md` — Worked examples
+"""
+
+USAGE_MD_TEMPLATE = """\
+# {scenario_title} — 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]
+
+**Output:**
+[Description or snippet of what gets generated]
+
+---
+
+## Example 2: [Different scenario]
+
+**User:** "[Another specific request]"
+
+**Skill activates because:** [Reason]
+
+**What the skill does:**
+1. [Step 1]
+2. [Step 2]
+
+**Output:**
+[Description or snippet]
+"""
+
+ARCH_CHECKLIST_TEMPLATE = """\
+# {scenario_title} — Architecture Checklist
+
+Run through this before marking the task complete.
+
+## Structure
+- [ ] Components are in separate files
+- [ ] No single monolithic output file
+
+## Types
+- [ ] No `any` types
+- [ ] All props have typed interfaces
+
+## 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
+"""
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+def normalize_skill_name(input_name: str) -> str:
+    """
+    Ensures the skill follows stitch-kit naming conventions.
+    Adds stitch- prefix if missing.
+    Does NOT auto-add suffixes — the caller decides the full name.
+    """
+    name = input_name.lower().strip()
+    if not name.startswith("stitch-"):
+        name = "stitch-" + name
+    return name
+
+def to_title(skill_name: str) -> str:
+    """
+    Converts 'stitch-ui-ecommerce-architect' → 'UI Ecommerce Architect'
+    """
+    core = re.sub(r"^stitch-", "", skill_name)
+    return " ".join(word.capitalize() for word in core.split("-"))
+
+def is_valid_name(name: str) -> bool:
+    """Validates kebab-case, starts with stitch-, lowercase."""
+    return bool(re.fullmatch(r"stitch-[a-z0-9]+(?:-[a-z0-9]+)*", name))
+
+# ─── Core logic ───────────────────────────────────────────────────────────────
+
+def init_skill(input_name: str, path: str) -> Path | None:
+    skill_name = normalize_skill_name(input_name)
+    scenario_title = to_title(skill_name)
+    skill_dir = Path(path).resolve() / skill_name
+
+    # Validation
+    if not is_valid_name(skill_name):
+        print(f"❌ Invalid skill name: {skill_name}")
+        print("   Expected kebab-case starting with 'stitch-'")
+        print(f"   Examples: stitch-ui-ecommerce-architect, stitch-flutter-components")
+        return None
+
+    if skill_dir.exists():
+        print(f"❌ Skill directory already exists: {skill_dir}")
+        return None
+
+    # Create directories
+    try:
+        (skill_dir / "examples").mkdir(parents=True)
+        print(f"✅ Created: {skill_dir}/")
+    except Exception as e:
+        print(f"❌ Failed to create directory: {e}")
+        return None
+
+    # Write SKILL.md
+    skill_content = SKILL_MD_TEMPLATE.format(
+        skill_name=skill_name,
+        scenario_title=scenario_title,
+    )
+    (skill_dir / "SKILL.md").write_text(skill_content)
+    print("✅ Created SKILL.md")
+
+    # Write examples/usage.md
+    usage_content = USAGE_MD_TEMPLATE.format(scenario_title=scenario_title)
+    (skill_dir / "examples" / "usage.md").write_text(usage_content)
+    print("✅ Created examples/usage.md")
+
+    # Print next steps
+    print(f"\n✅ Skill '{skill_name}' initialized.")
+    print("\nNext steps:")
+    print(f"  1. Edit {skill_dir}/SKILL.md — fill in description, steps, routing table")
+    print(f"  2. Edit {skill_dir}/examples/usage.md — replace placeholders with real examples")
+    print(f"  3. Add to .claude-plugin/marketplace.json in the right plugin group")
+    print(f"  4. Add row to docs/skills-index.md")
+    print(f"  5. Add row to README.md in the right layer table")
+
+    return skill_dir
+
+# ─── CLI ──────────────────────────────────────────────────────────────────────
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+
+    input_name = sys.argv[1]
+    path = "."
+
+    # Parse --path flag
+    for i, arg in enumerate(sys.argv[2:], start=2):
+        if arg == "--path" and i + 1 < len(sys.argv):
+            path = sys.argv[i + 1]
+            break
+
+    result = init_skill(input_name, path)
+    sys.exit(0 if result else 1)
+
+if __name__ == "__main__":
+    main()

package/skills/stitch-svelte-components/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: stitch-svelte-components
+description: Converts Stitch designs into Svelte 5 / SvelteKit components using the runes API — scoped CSS with custom properties, built-in transitions, TypeScript, dark mode, and accessible markup.
+allowed-tools:
+  - "stitch*:*"
+  - "Bash"
+  - "Read"
+  - "Write"
+---
+
+# Stitch → Svelte 5 / SvelteKit Components
+
+You are a Svelte 5 engineer. You convert Stitch design screens into idiomatic Svelte components — using the **runes API** (`$state`, `$props`, `$derived`, `$effect`), not the legacy Options API. Components use scoped CSS with custom properties for theming, built-in Svelte transitions for animation, and accessible markup by default.
+
+> **Note:** This is the only Stitch skill that targets Svelte. The official `react-components` skill targets Vite/React. Use this skill when the project uses SvelteKit.
+
+## When to use this skill
+
+Use this skill when:
+- The target project uses **SvelteKit** or **Svelte 5** standalone
+- You see `.svelte` files, `svelte.config.js`, or `+page.svelte` conventions
+- The user mentions `svelte`, `sveltekit`, `$state`, `$props`, or `runes`
+
+## Prerequisites
+
+- Access to the Stitch MCP server
+- A Stitch project with at least one generated screen
+- Target project uses Svelte 5 (runes enabled) — check `package.json` for `"svelte": "^5"`
+
+## Step 1: Retrieve the Stitch design
+
+1. **Namespace discovery** — Run `list_tools` to find the Stitch MCP prefix. Use it for all subsequent calls.
+2. **Fetch screen metadata** — Call `[prefix]:get_screen` to retrieve design JSON.
+3. **Download HTML** — Use the reliable downloader:
+   ```bash
+   bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"
+   ```
+4. **Visual reference** — Check `screenshot.downloadUrl` before writing code.
+
+## Step 2: SvelteKit file conventions
+
+SvelteKit uses file-based routing. Map Stitch screens to this structure:
+
+```
+src/
+├── routes/
+│   ├── +layout.svelte        ← Persistent shell (nav, footer)
+│   ├── +layout.ts            ← Layout load function (optional)
+│   ├── +page.svelte          ← Route page component
+│   ├── [route]/
+│   │   ├── +page.svelte      ← Sub-route page
+│   │   └── +page.ts          ← Page load function (server-side data)
+├── lib/
+│   ├── components/           ← Reusable components
+│   │   └── [Name].svelte
+│   ├── data/
+│   │   └── mockData.ts       ← Decoupled static content
+│   └── types/
+│       └── index.ts          ← Shared types
+static/                       ← Static assets
+```
+
+**Key rules:**
+- Pages live in `src/routes/` as `+page.svelte`
+- Reusable components live in `src/lib/components/`
+- Import `$lib/` is an alias for `src/lib/` — always use it
+
+## Step 3: Svelte 5 runes API
+
+**Use runes exclusively.** Never use the old `export let`, `let x = 0` reactive syntax, or `$:` labels.
+
+### Props
+```svelte
+<script lang="ts">
+  interface Props {
+    title: string
+    description?: string
+    onAction?: () => void
+  }
+
+  // $props() replaces export let
+  const { title, description = 'Default text', onAction }: Props = $props()
+</script>
+```
+
+### Reactive state
+```svelte
+<script lang="ts">
+  // $state() replaces let count = 0
+  let count = $state(0)
+  let isOpen = $state(false)
+
+  // $derived() replaces $: doubled = count * 2
+  const doubled = $derived(count * 2)
+
+  // $effect() replaces onMount / afterUpdate for side effects
+  $effect(() => {
+    console.log('count changed:', count)
+  })
+</script>
+```
+
+### Event handling
+```svelte
+<!-- Direct event attributes, no createEventDispatcher -->
+<button onclick={() => count++}>Increment</button>
+<button onclick={onAction}>Custom action</button>
+```
+
+## Step 4: Scoped CSS with design tokens
+
+Svelte scopes CSS to the component by default — use this aggressively. Map Stitch colors to custom properties in the `:root` (via `+layout.svelte` or `app.css`) and reference them in each component.
+
+**In `src/app.css` (global):**
+```css
+:root {
+  --color-background: #ffffff;
+  --color-surface: #f4f4f5;
+  --color-primary: /* dominant color from Stitch design */;
+  --color-primary-foreground: #ffffff;
+  --color-text: #09090b;
+  --color-text-muted: #71717a;
+  --color-border: #e4e4e7;
+}
+
+[data-theme='dark'] {
+  --color-background: #09090b;
+  --color-surface: #18181b;
+  --color-primary: /* same hue, adjusted for dark bg */;
+  --color-primary-foreground: #09090b;
+  --color-text: #fafafa;
+  --color-text-muted: #a1a1aa;
+  --color-border: #27272a;
+}
+```
+
+**In each component (scoped):**
+```svelte
+<style>
+  .card {
+    background-color: var(--color-surface);
+    border: 1px solid var(--color-border);
+    color: var(--color-text);
+    border-radius: 0.5rem;
+    padding: 1.5rem;
+  }
+
+  .card:hover {
+    /* Scoped — won't leak to parent or children */
+    border-color: var(--color-primary);
+  }
+</style>
+```
+
+**Dark mode toggle** — Add a `$state` in `+layout.svelte`:
+```svelte
+<script lang="ts">
+  let theme = $state<'light' | 'dark'>('light')
+
+  function toggleTheme() {
+    theme = theme === 'light' ? 'dark' : 'light'
+    document.documentElement.setAttribute('data-theme', theme)
+  }
+</script>
+
+<svelte:element this="div" data-theme={theme}>
+  {@render children()}
+</svelte:element>
+```
+
+## Step 5: Built-in transitions and animations
+
+Svelte has first-class transition support. Apply these from the Stitch design intent:
+
+```svelte
+<script lang="ts">
+  import { fade, fly, slide, scale } from 'svelte/transition'
+  import { cubicOut } from 'svelte/easing'
+
+  let show = $state(false)
+</script>
+
+<!-- Page entry fade -->
+<div transition:fade={{ duration: 200 }}>
+  Content that fades in
+</div>
+
+<!-- Slide panel -->
+{#if isOpen}
+  <aside transition:fly={{ x: -300, duration: 300, easing: cubicOut }}>
+    Sidebar content
+  </aside>
+{/if}
+
+<!-- Collapsible section -->
+{#if expanded}
+  <div transition:slide={{ duration: 200 }}>
+    Expandable content
+  </div>
+{/if}
+```
+
+**Always respect reduced motion:**
+```svelte
+<script lang="ts">
+  // Check user preference once
+  const prefersReducedMotion = $state(
+    typeof window !== 'undefined'
+      ? window.matchMedia('(prefers-reduced-motion: reduce)').matches
+      : false
+  )
+
+  // Conditionally disable transitions
+  const transitionOptions = $derived(
+    prefersReducedMotion ? {} : { duration: 200 }
+  )
+</script>
+
+<div transition:fade={transitionOptions}>...</div>
+```
+
+## Step 6: Accessibility in Svelte
+
+Svelte's compiler warns about missing accessibility attributes — treat all compiler warnings as errors.
+
+- **`role` and ARIA**: Add `role` when using non-semantic elements. Always pair with `aria-label` or `aria-labelledby`.
+- **`bind:this`**: Use for programmatic focus management (e.g., focus trap in modals).
+- **Keyboard handlers**: Any `onclick` handler on a non-interactive element needs `onkeydown`/`onkeyup` too, or use a `<button>`.
+- **Screen reader text**: Use `class="sr-only"` (define in app.css) for visually hidden labels.
+
+```svelte
+<!-- Good: button with accessible label -->
+<button
+  onclick={closeModal}
+  aria-label="Close dialog"
+  class="icon-btn"
+>
+  <CloseIcon />
+</button>
+
+<!-- Good: Svelte dialog with focus trap -->
+<dialog
+  bind:this={dialogEl}
+  aria-labelledby="dialog-title"
+  aria-modal="true"
+>
+  <h2 id="dialog-title">{title}</h2>
+</dialog>
+```
+
+## Step 7: Execution steps
+
+1. **Environment check** — If `node_modules` missing, run `npm install`.
+2. **Data layer** — Create `src/lib/data/mockData.ts` from design content.
+3. **Component drafting** — Use `resources/component-template.svelte` as base. Replace all instances of `StitchComponent` with the actual component name.
+4. **CSS tokens** — Add color tokens to `src/app.css`. If using `stitch-design-system`, import its generated `design-tokens.css` instead.
+5. **Wiring** — Update `src/routes/+page.svelte` to import and use the new components. Import from `$lib/components/`.
+6. **Quality check** — Run through `resources/architecture-checklist.md`.
+7. **Dev verification** — Run `npm run dev`. Toggle dark mode. Test keyboard navigation.
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| Runes syntax error | Confirm `svelte: ^5` in `package.json`. Old syntax is invalid in Svelte 5. |
+| `$props()` type error | Add `lang="ts"` to `<script>` tag |
+| CSS not scoped | Ensure styles are inside `<style>` block, not in a `.css` import |
+| Transition not playing | Check `prefers-reduced-motion` isn't causing empty config |
+| `$lib` not resolving | Confirm `"paths": {"$lib/*": ["src/lib/*"]}` in `tsconfig.json` |
+| Dark mode flicker on load | Read theme from `localStorage` in a synchronous `<svelte:head>` script |
+
+## Integration with other skills
+
+- **stitch-design-system** — Run first to generate `design-tokens.css` for the CSS variable foundation.
+- **stitch-animate** — Run after for Svelte-specific transition patterns beyond the basics above.
+- **stitch-a11y** — Run after for a full accessibility audit when the design has complex UI patterns.
+
+## References
+
+- `resources/component-template.svelte` — Production-ready Svelte 5 component boilerplate
+- `resources/architecture-checklist.md` — Pre-ship quality checklist
+- `scripts/fetch-stitch.sh` — Reliable GCS HTML downloader

package/skills/stitch-svelte-components/resources/architecture-checklist.md

@@ -0,0 +1,62 @@
+# Svelte Components — Architecture Checklist
+
+Run through this before marking the task complete.
+
+## Structure
+
+- [ ] Components are in `src/lib/components/` — imported via `$lib/components/`
+- [ ] Static/mock data is in `src/lib/data/mockData.ts`, not hardcoded in `.svelte` files
+- [ ] Shared types are in `src/lib/types/index.ts`
+- [ ] Pages are in `src/routes/` using `+page.svelte` convention
+
+## Svelte 5 runes
+
+- [ ] Props use `$props()`, NOT `export let`
+- [ ] Reactive state uses `$state()`, NOT `let x = 0` with `$:` elsewhere
+- [ ] Computed values use `$derived()`, NOT `$: computed = ...`
+- [ ] Side effects use `$effect()`, NOT `onMount` / `afterUpdate` (unless lifecycle-specific)
+- [ ] Event callbacks passed via props — no `createEventDispatcher`
+- [ ] Snippets use `{@render children()}` syntax, NOT `<slot>`
+
+## TypeScript
+
+- [ ] `<script lang="ts">` on every component
+- [ ] `Props` interface defined in the script block
+- [ ] No `any` types
+- [ ] `$lib` imports work (check `tsconfig.json` paths if not)
+
+## Styling — scoped CSS + CSS variables
+
+- [ ] All styles are in the component's `<style>` block (scoped by default)
+- [ ] No hardcoded hex colors — all use `var(--color-*)` tokens
+- [ ] Dark mode works — test with `[data-theme="dark"]` on `<html>`
+- [ ] `design-tokens.css` imported in `src/app.css`
+- [ ] `@media (prefers-reduced-motion: reduce)` overrides exist for any transitions
+
+## Responsive
+
+- [ ] Layout works at 320px (small mobile) — no horizontal overflow
+- [ ] Layout works at 768px (tablet)
+- [ ] Layout works at 1280px (desktop)
+- [ ] `@media` breakpoints are inside the `<style>` block, not inline styles
+
+## Accessibility baseline
+
+- [ ] Semantic HTML: `<nav>`, `<main>`, `<section>`, `<article>` where appropriate
+- [ ] All interactive elements are `<button>` or `<a>`, not `<div>` with `onclick`
+- [ ] `<button>` elements have accessible labels (text or `aria-label`)
+- [ ] Images have descriptive `alt` text (or `alt=""` + `aria-hidden="true"` for decorative)
+- [ ] Svelte compiler a11y warnings treated as errors (not ignored)
+- [ ] No `outline: none` without a `:focus-visible` replacement
+
+## Transitions
+
+- [ ] Svelte transitions are imported from `svelte/transition`
+- [ ] `prefers-reduced-motion` is checked before applying IntersectionObserver animations
+- [ ] Transitions don't cause layout shifts (use `opacity` + `transform`, not `height`/`width`)
+
+## SvelteKit specifics
+
+- [ ] `+page.svelte` imports from `$lib/`, not relative `../../`
+- [ ] Data loading uses `+page.ts` load function, not `onMount` for initial data
+- [ ] No hardcoded `window.*` calls at module level (SSR will break) — wrap in `$effect` or check `typeof window !== 'undefined'`