Getting Started

Dark Mode

SV5UI uses mode-watcher for dark mode support. All components automatically adapt to the current theme.

Setup

Two things are needed: the ModeWatcher component in your layout, and the @custom-variant CSS rule.

src/routes/+layout.svelte

<script lang="ts">
  import './layout.css';
  import { ModeWatcher } from 'mode-watcher';

  let { children } = $props();
</script>

<ModeWatcher />
{@render children()}

src/routes/layout.css

@import 'tailwindcss';
@import 'sv5ui/theme.css';

/* Required for Tailwind dark mode to work with mode-watcher */
@custom-variant dark (&:where(.dark, .dark *));

Important

The @custom-variant dark rule is required for Tailwind CSS 4 dark mode classes to work with mode-watcher's .dark class approach.

Toggle Button

SV5UI provides a ready-to-use ThemeModeButton component that toggles between light and dark mode with a smooth icon animation.

<script lang="ts">
  import { ThemeModeButton } from 'sv5ui';
</script>

<!-- Default -->
<ThemeModeButton />

<!-- Outline variant, small -->
<ThemeModeButton size="sm" variant="outline" />

<!-- Soft primary, large -->
<ThemeModeButton size="lg" variant="soft" color="primary" />

<!-- Custom icons -->
<ThemeModeButton lightIcon="lucide:sun-medium" darkIcon="lucide:moon-star" />

Programmatic Control

Use mode-watcher's utilities to control the theme programmatically.

+page.svelte

<script lang="ts">
  import { mode, setMode, toggleMode } from 'mode-watcher';
</script>

<!-- Current mode: "light" | "dark" | undefined -->
<p>Current: {$mode}</p>

<!-- Set specific mode -->
<button onclick={() => setMode('dark')}>Dark</button>
<button onclick={() => setMode('light')}>Light</button>

<!-- Toggle between modes -->
<button onclick={toggleMode}>Toggle</button>

Styling with Dark Mode

Use Tailwind's dark: variant for custom styles, or use sv5ui's semantic color classes that adapt automatically.

Example.svelte

<!-- Tailwind dark: variant works automatically -->
<div class="bg-white dark:bg-gray-900">
  <p class="text-gray-900 dark:text-white">
    This text adapts to the theme.
  </p>
</div>

<!-- sv5ui semantic colors adapt automatically -->
<div class="bg-surface text-on-surface">
  <p class="text-on-surface/60">
    Semantic colors handle dark mode for you.
  </p>
</div>

Why Semantic Colors?

SV5UI's OKLCH tokens adapt automatically — you rarely need Tailwind's dark: variant.

Approach	Code
Manual (verbose)	`bg-white dark:bg-gray-900 text-gray-900 dark:text-white`
Semantic (automatic)	`bg-surface text-on-surface`

Learn more

See the Theming page for the full list of color tokens and how to customize them.

Theming Components