sveltekit-webapp

Scaffold and configure a production-ready SvelteKit PWA with opinionated defaults. Use when: creating a new web application, setting up a SvelteKit project, building a PWA, or when a user asks to "build me an app/site/webapp". Handles full setup including TypeScript, Tailwind, Skeleton + Bits UI components, testing, linting, and Vercel deployment. Generates a PRD with user stories for review, then upon user approval, builds through development, staging, and production with user approval at each stage.

# SvelteKit Webapp Skill

Scaffold production-ready SvelteKit PWAs with opinionated defaults and guided execution.

## Quick Start

1. **Describe your app** — Tell me what you want to build
2. **Review the PRD** — I'll generate a plan with user stories
3. **Approve** — I build, test, and deploy with your oversight
4. **Done** — Get a live URL + admin documentation

> "Build me a task tracker with due dates and priority labels"

That's all I need to start. I'll ask follow-up questions if needed.

## Prerequisites

These CLIs must be available (the skill will verify during preflight):

| CLI | Purpose | Install |
|-----|---------|---------|
| `sv` | SvelteKit scaffolding | `npm i -g sv` (or use via `pnpx`) |
| `pnpm` | Package manager | `npm i -g pnpm` |
| `gh` | GitHub repo creation | [cli.github.com](https://cli.github.com) |
| `vercel` | Deployment | `npm i -g vercel` |

Optional (if features require):
- `turso` — Turso database CLI

## Opinionated Defaults

This skill ships with sensible defaults that work well together. **All defaults can be overridden** via `SKILL-CONFIG.json`:

- **Component library:** Skeleton (Svelte 5 native) + Bits UI fallback
- **Package manager:** pnpm
- **Deployment:** Vercel
- **Add-ons:** ESLint, Prettier, Vitest, Playwright, mdsvex, MCP
- **State:** Svelte 5 runes ($state, $derived, $effect)

See [User Configuration](#user-configuration) for override details.

---

## User Configuration

Check `~/.openclaw/workspace/SKILL-CONFIG.json` for user-specific defaults before using skill defaults. User config overrides skill defaults for:
- Deployment provider (e.g., vercel, cloudflare, netlify)
- Package manager (pnpm, npm, yarn)
- Add-ons to always include
- MCP IDE configuration
- Component library preferences

## Workflow Overview

1. **Gather**: Freeform description + design references + targeted follow-ups
2. **Plan**: Generate complete PRD (scaffold, configure, features, tests as stories)
3. **Iterate**: Refine PRD with user until confirmed
4. **Preflight**: Verify all required auths and credentials
5. **Execute**: Guided build-deploy-verify cycle with user checkpoints (development → staging → production)

---

## Phase 1: Gather Project Description

A conversational, iterative approach to understanding what the user wants.

### 1a. Freeform Opening

Start with an open question:
- "What do you want to build?"
- "Describe the webapp you have in mind"

Let the user lead with what matters to them.

### 1b. Design References

Ask for inspiration:
```
Share 1-3 sites you'd like this to feel like 
(design, functionality, or both).

Examples:
- "Like Notion but simpler"
- "Fieldwire's mobile-first approach"
- "Linear's clean aesthetic"
```

"Show me what you like" communicates more than paragraphs of description.

### 1c. Visual Identity (Optional)

If design references suggest custom branding, ask:
```
Any specific colors, fonts, or logos you want to use?
(I can pre-configure the Tailwind theme)
```

### 1d. Targeted Follow-ups

Based on gaps in the description, ask specifically:

| Gap | Question |
|-----|----------|
| Users unclear | "Who's the primary user? (role, context)" |
| Core action unclear | "What's the ONE thing they must be able to do?" |
| Content unknown | "Any existing content/assets to incorporate?" |
| Scale unknown | "How many users do you expect? (ballpark)" |
| Timeline | "Any deadline driving this?" |

Only ask what's missing—don't interrogate.

### 1e. Structured Summary

Before proceeding, confirm understanding:

```
📝 PROJECT SUMMARY: [Name]

Purpose: [one sentence]
Primary user: [who]
Core action: [what they do]
Design inspiration: [references]
Visual identity: [colors/fonts if specified]
Key features:
  • [feature 1]
  • [feature 2]
  • [feature 3]

Technical signals detected:
  • Database: [yes/no] — [reason]
  • Authentication: [yes/no] — [reason]
  • Internationalization: [yes/no] — [reason]

Does this capture it? [Yes / Adjust]
```

Iterate until the user confirms.

---

## Phase 2: Plan (Generate PRD)

Generate a complete PRD with technical stack, user stories, and mock data strategy.

### Technical Stack

**Always Included:**
```
CLI:              pnpx sv (fallback: npx sv)
Template:         minimal
TypeScript:       yes
Package manager:  pnpm (fallback: npm)

Core add-ons (via sv add):
  ✓ eslint
  ✓ prettier
  ✓ mcp (claude-code)
  ✓ mdsvex
  ✓ tailwindcss (+ typography, forms plugins)
  ✓ vitest
  ✓ playwright

Post-scaffold:
  ✓ Skeleton (primary component library — Svelte 5 native, accessible)
  ✓ Bits UI (headless primitives — fallback for gaps/complex custom UI)
  ✓ vite-plugin-pwa (PWA support)
  ✓ Svelte 5 runes mode
  ✓ adapter-auto (auto-detects deployment target)
```

**Why Skeleton + Bits UI?**
- Skeleton: Full-featured component library built for Svelte 5, accessible by default
- Bits UI: Headless primitives when you need more control or custom styling
- Both play well together — Skeleton for speed, Bits for flexibility

**Inferred from Description:**
```
drizzle     → if needs database (ask: postgres/sqlite/turso)
lucia       → if needs auth
paraglide   → if needs i18n (ask: which languages)
```

### State Management

Follow Svelte 5 best practices (see https://svelte.dev/docs/kit/state-management):

- Use `$state()` runes for reactive state
- Use `$derived()` for computed values
- Use Svelte's context API (`setContext`/`getContext`) for cross-component state
- Server state flows through `load` functions → `data` prop
- **Never** store user-specific state in module-level variables (shared across requests)

### Code Style Preferences

Check `SKILL-CONFIG.json` for user preferences. Common patterns:

- **Prefer `bind:` over callbacks** — For child→parent data flow, use `bind:value` instead of `onchange` callback props. More declarative, less boilerplate.
- **Avoid `onMount`** — Use `$effect()` for side effects. It's reactive and works with SSR.
- **Runes everywhere** — `$state()`, `$derived()`, `$effect()` over legacy stores and lifecycle hooks.
- **Small components** — Default soft limit of ~200 lines per component (configurable in SKILL-CONFIG.json). If growing larger, extract sub-components. Small is beautiful. 🤩

### Directory Structure

`sv create` generates:
```
src/
├── routes/          # SvelteKit routes
├── app.html         # HTML template
├── app.d.ts         # Type declarations
└── app.css          # Global styles
static/              # Static assets
```

We add:
```
src/
├── lib/
│   ├── components/  # Reusable components (Skeleton + Bits UI)
│   ├── server/      # Server-only code (db client, auth)
│   ├── stores/      # Svelte stores (.svelte.ts for runes)
│   ├── utils/       # Helper functions
│   └── types/       # TypeScript types
static/
└── icons/           # PWA icons
```

### User Stories (prd.json)

**Story structure:**
```json
{
  "project": "ProjectName",
  "branchName": "dev",
  "description": "Brief description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Scaffold project",
      "description": "Set up the base SvelteKit project.",
      "acceptanceCriteria": [...],
      "priority": 1,
      "passes": false,
      "blocked": false,
      "notes": ""
    }
  ]
}
```

**Story sizing rule:** Each story must fit in one context window. If it feels big, split it.

**Standard story sequence:**

1. **Scaffold** — `pnpx sv create`, add core add-ons
2. **Configure** — Skeleton + Bits UI, PWA, directory structure, VSCode workspace, Tailwind theme
3. **Mock Data** — Set up mock database/fixtures for development
4. **Foundation** — Root layout, design tokens, home page (INDEX PAGE CHECKPOINT)
5. **Features** — Core features from gathered requirements
6. **Infrastructure** — Database schema, migrations, auth (if needed)
7. **Polish** — PWA manifest, icons
8. **Tests** — E2E tests for critical flows

**Index Page Checkpoint:** After the index/home page is built (but before other pages), PAUSE execution and request user review. The index page es