skeleton-svelte

name	skeleton-svelte
description	Use this skill when working with Skeleton UI components in Svelte projects. It provides guidelines for Skeleton's component composition pattern, theme-aware color system, design presets, and layout patterns. Trigger when building UI components, styling elements, creating layouts, or working with Skeleton-specific features in Svelte 5 and SvelteKit 2+ projects.

Skeleton Svelte

Overview

Skeleton is a design system built on Tailwind CSS that provides framework-specific UI components for Svelte via @skeletonlabs/skeleton-svelte. This skill provides workflows and reference documentation for building Svelte applications using Skeleton's component library, color system, and design patterns.

Core Principles

Apply these fundamental principles when working with Skeleton:

Component Composition

Use Skeleton's composed pattern with granular child components. Components accept arbitrary props and the class attribute for styling:

<Card class="preset-filled-surface-100-900">
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Content>
    <p>Content</p>
  </Card.Content>
</Card>

Theme-Aware Colors

Critical: Always use color pairings for theme-aware styling. Never hard-code colors with dark: prefixes.

✅ Correct:

<div class="bg-surface-50-950 text-surface-950-50">
  <p class="text-surface-700-300">Content</p>
</div>

❌ Incorrect:

<div class="bg-white text-black dark:bg-gray-950 dark:text-white">
  <p class="text-gray-700 dark:text-gray-300">Content</p>
</div>

Color pairing syntax: {property}-{color}-{lightShade}-{darkShade}

Examples:

• bg-surface-50-950 - Light background in light mode, dark in dark mode
• text-surface-950-50 - Dark text in light mode, light in dark mode
• border-surface-300-700 - Adaptive border colors

Reference: See references/colors.md for comprehensive color system documentation.

Design Presets

Use built-in presets for consistent styling:

• preset-filled-{color}-{shade} - Solid backgrounds with contrast text
• preset-tonal-{color} - Soft, tinted backgrounds
• preset-outlined-{color}-{shade} - Bordered with transparent background

<Button class="preset-filled-primary-500">Primary Action</Button>
<Button class="preset-tonal-secondary">Secondary</Button>
<Button class="preset-outlined-surface-300-700">Cancel</Button>

Reference: See references/presets.md for all preset variants and custom preset creation.

Workflow: Building UI Components

Step 1: Identify the Component Type

Determine which Skeleton component best fits the requirement:

• Avatar - User profile images with fallback
• Button - Interactive actions
• Card - Content containers
• Dialog - Modal overlays
• Input/Label - Form fields
• Badge - Status indicators

Reference: See references/components.md for complete component catalog with examples.

Step 2: Import and Structure

Import the component and use the composed pattern:

<script>
  import { Card, Button } from '@skeletonlabs/skeleton-svelte';
</script>

<Card class="preset-filled-surface-100-900">
  <Card.Header>
    <Card.Title>Component Title</Card.Title>
  </Card.Header>
  <Card.Content>
    <!-- Content here -->
  </Card.Content>
  <Card.Footer>
    <Button class="preset-filled-primary-500">Action</Button>
  </Card.Footer>
</Card>

Step 3: Apply Theme-Aware Styling

Add color pairings and presets using the class attribute:

<Card class="preset-outlined-surface-300-700">
  <Card.Content>
    <h3 class="font-semibold text-surface-950-50">Heading</h3>
    <p class="text-surface-700-300">Description text</p>
  </Card.Content>
</Card>

Step 4: Add State Management (if needed)

Use Svelte 5 runes for reactive state:

<script>
  import { Dialog, Button } from '@skeletonlabs/skeleton-svelte';
  let open = $state(false);
</script>

<Button onclick={() => (open = true)} class="preset-filled-primary-500">Open Dialog</Button>

<Dialog bind:open>
  <Dialog.Content>
    <!-- Dialog content -->
  </Dialog.Content>
</Dialog>

Workflow: Creating Layouts

Step 1: Choose Layout Pattern

Select an appropriate layout foundation:

• Single-column - Blog posts, documentation pages
• Two-column - Sidebar + main content
• Three-column - Dashboard with dual sidebars
• Dashboard - Grid-based card layouts

Reference: See references/layouts.md for complete layout patterns and examples.

Step 2: Apply Semantic HTML

Use semantic elements for proper structure:

<div class="h-full">
  <header class="sticky top-0 z-10 bg-surface-50-950">
    <nav><!-- Navigation --></nav>
  </header>

  <main class="flex-1 overflow-y-auto">
    <div class="container mx-auto px-4 py-8">
      <!-- Content -->
    </div>
  </main>

  <footer class="bg-surface-100-900">
    <!-- Footer -->
  </footer>
</div>

Step 3: Implement Responsive Behavior

Use Tailwind's responsive prefixes for mobile-first design:

<div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
  <!-- Responsive grid -->
</div>

Step 4: Add Theme-Aware Styling

Apply color pairings throughout the layout:

<header class="border-b border-surface-300-700 bg-surface-50-950">
  <!-- Header content -->
</header>

<main class="bg-surface-100-900">
  <!-- Main content -->
</main>

Common Patterns

Form with Validation

<script>
  import { Button, Input, Label } from '@skeletonlabs/skeleton-svelte';

  let email = $state('');
  let error = $state('');

  function handleSubmit(e) {
    e.preventDefault();
    if (!email.includes('@')) {
      error = 'Invalid email';
      return;
    }
    // Process form
  }
</script>

<form onsubmit={handleSubmit}>
  <div>
    <Label for="email">Email</Label>
    <Input
      id="email"
      type="email"
      bind:value={email}
      class="border-surface-300-700"
      aria-invalid={!!error}
    />
    {#if error}
      <p class="mt-1 text-sm text-error-500">{error}</p>
    {/if}
  </div>
  <Button type="submit" class="mt-4 preset-filled-primary-500">Submit</Button>
</form>

Responsive Card Grid

<script>
  import { Card } from '@skeletonlabs/skeleton-svelte';
</script>

<div class="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
  {#each items as item}
    <Card class="preset-filled-surface-100-900">
      <Card.Header>
        <Card.Title>{item.title}</Card.Title>
      </Card.Header>
      <Card.Content>
        <p class="text-surface-700-300">{item.description}</p>
      </Card.Content>
    </Card>
  {/each}
</div>

Status Badge

<script>
  import { Badge } from '@skeletonlabs/skeleton-svelte';
</script>

<Badge class="preset-tonal-success">Active</Badge>
<Badge class="preset-tonal-warning">Pending</Badge>
<Badge class="preset-tonal-error">Inactive</Badge>

Project-Specific Configuration

This project uses:

• Skeleton with Svelte 5 and SvelteKit 2+
• Tailwind CSS 4.x
• Mona theme (configured in src/app.html)

The Mona theme provides specific color palettes and design tokens. When creating components, ensure they align with the theme's aesthetic.

Resources

Reference Documentation

• references/colors.md - Complete color system, pairings, shades, and transparency
• references/presets.md - Design presets, variants, and custom preset creation
• references/layouts.md - Layout patterns, semantic HTML, responsive design
• references/components.md - Comprehensive component catalog with examples

External Documentation

• Official Documentation: https://www.skeleton.dev
• Component Examples: https://www.skeleton.dev/components
• Theme Generator: https://www.skeleton.dev/themes

Best Practices

1. Use color pairings - Always use dual-tone syntax for theme support
2. Apply composition pattern - Leverage child components for flexibility
3. Semantic HTML - Use proper HTML elements for accessibility
4. Mobile-first responsive - Start with mobile layout, enhance for larger screens
5. Preset consistency - Use design presets for uniform styling
6. State with runes - Use Svelte 5's $state, $derived, $effect for reactivity
7. Reference documentation - Consult references/ files for detailed information

Important Notes

• Components are built on Zag.js for state management
• The design system is framework agnostic at its core
• Cannot be used alongside Flowbite or DaisyUI (conflicting Tailwind modifications)
• Component classes automatically get precedence over internal styles