svelte5-showcase-components

What this skill does

# Svelte 5 Showcase Components

## Quick Start

The Svelte 5 Showcase is a production-ready component library with **49 components** organized into **7 categories**, built with Svelte 5 runes, TypeScript strict mode, and TailwindCSS v4.

**Showcase Location:** `/Users/dawiddutoit/projects/play/svelte`

**Component Categories:**
1. **Primitives** (24) - Core UI primitives (buttons, inputs, forms, dialogs)
2. **Navigation** (6) - Navigation patterns (tabs, breadcrumbs, pagination, menus)
3. **Data Display** (6) - Display components (tables, accordions, avatars, carousels)
4. **Overlays** (5) - Modal dialogs and overlays (popovers, sheets, drawers)
5. **Feedback** (2) - User feedback (progress bars, toast notifications)
6. **Layout** (2) - Layout primitives (aspect ratio, resizable panels)
7. **Custom** (4) - Brand-specific components (hero sections, service cards)

**Quick Component Lookup:**

```bash
# Browse all components at:
/Users/dawiddutoit/projects/play/svelte/src/lib/components/ui/

# Example showcase pages:
/Users/dawiddutoit/projects/play/svelte/src/routes/showcase/primitives/button/+page.svelte
/Users/dawiddutoit/projects/play/svelte/src/routes/showcase/primitives/form/+page.svelte
```

---

## Table of Contents

1. [When to Use This Skill](#1-when-to-use-this-skill)
2. [Component Inventory](#2-component-inventory)
3. [Quick Integration](#3-quick-integration)
4. [Common Usage Patterns](#4-common-usage-patterns)
5. [Form Handling](#5-form-handling)
6. [Supporting Files](#6-supporting-files)
7. [Expected Outcomes](#7-expected-outcomes)
8. [Requirements](#8-requirements)
9. [Red Flags to Avoid](#9-red-flags-to-avoid)

---

## When to Use This Skill

### Explicit Triggers

Invoke this skill when the user explicitly asks for:
- "What components are available in the showcase?"
- "How do I use the [component name] component?"
- "Show me examples of [component type]"
- "How to integrate showcase components into my project?"
- "Copy [component] from showcase to my project"
- "What's the difference between Dialog and Drawer?"
- "Showcase component documentation"

### Implicit Triggers

Invoke when the user's task involves:
- Building UI with Svelte 5 and needs component references
- Looking for form validation examples with sveltekit-superforms
- Needing accessible component patterns
- Asking about Svelte 5 runes usage in components
- Requesting Tailwind CSS component styling patterns
- Exploring shadcn-svelte implementation examples

### Debugging Triggers

Invoke when troubleshooting:
- Import errors with showcase components
- Svelte 5 runes syntax issues in components
- Form validation not working with superforms
- Tailwind classes not applying to components
- TypeScript errors in component props
- Component styling inconsistencies

---

## Component Inventory

### Complete Component List (49 Total)

#### Primitives (24 components)

**Form Controls:**
- `Button` - Clickable button with variants (default, destructive, outline, ghost, link)
- `Input` - Text input field with type variants
- `Textarea` - Multi-line text input
- `Checkbox` - Boolean checkbox with label
- `Switch` - Toggle switch component
- `Radio Group` - Radio button group
- `Select` - Dropdown selection menu
- `Slider` - Range slider input
- `Label` - Accessible form label
- `Input OTP` - One-time password input

**Form Components:**
- `Form Field` - Form field wrapper with context
- `Form Label` - Accessible form label
- `Form Description` - Helper text for fields
- `Form Field Errors` - Validation error display
- `Form Fieldset` - Group related fields
- `Form Button` - Form submit button

**Feedback & Display:**
- `Alert` - Alert messages with variants
- `Alert Dialog` - Modal confirmation dialog
- `Badge` - Status badge with variants
- `Card` - Container card with header/footer
- `Dialog` - Modal dialog overlay
- `Skeleton` - Loading skeleton placeholder
- `Tooltip` - Hover tooltip
- `Toggle` - Toggle button
- `Toggle Group` - Toggle button group

**Date Inputs:**
- `Calendar` - Date picker calendar
- `Range Calendar` - Date range picker

#### Navigation (6 components)

- `Breadcrumb` - Breadcrumb navigation trail
- `Command` - Command palette / search
- `Menubar` - Menu bar navigation
- `Navigation Menu` - Dropdown navigation menu
- `Pagination` - Page navigation
- `Tabs` - Tabbed interface

#### Data Display (6 components)

- `Accordion` - Collapsible content sections
- `Avatar` - User avatar with fallback
- `Carousel` - Image/content carousel (Embla)
- `Collapsible` - Single collapsible section
- `Scroll Area` - Custom scrollbar area
- `Table` - Data table with header/footer

#### Overlays (5 components)

- `Context Menu` - Right-click context menu
- `Drawer` - Bottom drawer overlay (Vaul)
- `Hover Card` - Hover card overlay
- `Popover` - Popover overlay
- `Sheet` - Side sheet overlay

#### Feedback (2 components)

- `Progress` - Progress bar indicator
- `Sonner` - Toast notification system

#### Layout (2 components)

- `Aspect Ratio` - Aspect ratio container
- `Resizable` - Resizable panel layout (Paneforge)

#### Custom Components (4 components)

- `Feature Card` - Branded feature card
- `Hero Section` - Landing page hero
- `Loading Spinner` - Custom loading animation
- `Service Card` - Expandable service card with credentials

**Location:** `/Users/dawiddutoit/projects/play/svelte/src/lib/components/ui/`

---

## Quick Integration

### Method 1: Using shadcn-svelte CLI (Recommended)

```bash
# Install CLI and add components
npx shadcn-svelte@latest add button
npx shadcn-svelte@latest add card
npx shadcn-svelte@latest add form
```

**What this does:**
1. Installs required dependencies
2. Copies component files to `src/lib/components/ui/`
3. Updates barrel exports in `index.ts`

### Method 2: Manual Copy from Showcase

**Step 1: Copy component directory**

```bash
# Copy button component
cp -r /Users/dawiddutoit/projects/play/svelte/src/lib/components/ui/button \
  ./src/lib/components/ui/

# Copy multiple components
cp -r /Users/dawiddutoit/projects/play/svelte/src/lib/components/ui/{button,card,input} \
  ./src/lib/components/ui/
```

**Step 2: Update barrel exports**

```typescript
// src/lib/components/index.ts
export { Button, buttonVariants } from './ui/button';
export { Card, CardHeader, CardTitle, CardContent, CardFooter } from './ui/card';
export { Input } from './ui/input';
```

**Step 3: Install dependencies**

```bash
npm install bits-ui clsx tailwind-merge tailwind-variants lucide-svelte
```

**Step 4: Copy utilities**

```typescript
// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

export type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & { ref?: U | null };
```

### Method 3: Read from Showcase

```svelte
<script lang="ts">
  // Read showcase implementation for reference
  // Location: /Users/dawiddutoit/projects/play/svelte/src/lib/components/ui/[component]/
</script>
```

**View showcase examples:**
```
/Users/dawiddutoit/projects/play/svelte/src/routes/showcase/primitives/[component]/+page.svelte
```

---

## Common Usage Patterns

### Svelte 5 Runes (Required Syntax)

All components use Svelte 5 runes:

```svelte
<script lang="ts">
  // ✅ Svelte 5 (REQUIRED)
  let count = $state(0);
  let doubled = $derived(count * 2);

  $effect(() => {
    console.log('count changed:', count);
  });

  // ❌ Svelte 4 (DO NOT USE)
  // let count = 0;
  // $: doubled = count * 2;
  // $: console.log(count);
</script>
```

### Props Pattern

```svelte
<script lang="ts">
  interface Props {
    title: string;
    count?: number;
    variant?: 'default' | 'destructive';
    onUpdate?: (value: number) => void;
  }

  let { title, count = 0, variant = 'default', onUpdate }: Props = $props();
</script>
```

### Bindable Props

```svelte
<script lang="ts">
  // Component with bindable value
  interface Props {
    value: stri