sveltekit-webapp

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
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 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:

{
  "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 establishes the visual direction—getting early feedback here avoids wasted work on subsequent pages.

See references/scaffold-stories.md for story templates.

Mock Data Strategy

Development uses mock data; production uses real database.

Mock data approach:
- Generate mock data per-story as needed
- Store in src/lib/server/mocks/ or use MSW for API mocking
- E2E tests run against mock data locally
- Stage 2+ switches to real database

When drizzle is selected, include stories for:

• Initial schema creation
• Drizzle Kit configuration
• First migration

External Dependencies

Identify required credentials:

Feature	Dependency	Required
Any project	GitHub CLI	Yes
Deployment	Vercel CLI or adapter-auto	Yes
Database (postgres)	DATABASE_URL	For staging
Database (turso)	Turso CLI	For staging
OAuth providers	Client ID/Secret	For staging
Payments	Stripe API keys	For staging

Dev uses mocks; staging/production need real credentials.

---

Phase 3: Iterate Until Confirmed

Present the PRD and refine until the user approves.

Present the PRD

📋 PRD: [Project Name]

TECHNICAL STACK:
✅ Always: TypeScript, Tailwind, Skeleton + Bits UI, ESLint, 
   Prettier, Vitest, Playwright, PWA
🔍 Inferred:
   [✓/✗] Database (drizzle) - [reason]
   [✓/✗] Authentication (lucia) - [reason]  
   [✓/✗] Internationalization (paraglide) - [reason]

USER STORIES: [N] stories
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
US-001: Scaffold project (Setup)
US-002: Configure Skeleton + Bits UI (Setup)
US-003: Set up mock data (Setup)
US-004: Create root layout (Foundation)
[... feature stories ...]
US-XXX: Configure PWA manifest (Polish)
US-XXX: Add E2E tests (Tests)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔐 External dependencies:
   • GitHub CLI (required now)
   • Vercel CLI (required now)
   • DATABASE_URL (required for staging)
   • [others for st

---

*Content truncated.*