Getting Started

Theming

SV5UI uses an OKLCH color system with CSS custom properties. Every color automatically adapts to light and dark mode.

Import Theme

The theme is set up during installation. Import sv5ui/theme.css in your layout CSS to load all color tokens.

src/routes/layout.css
@import 'tailwindcss';
@import 'sv5ui/theme.css';

@custom-variant dark (&:where(.dark, .dark *));

OKLCH Color Space

SV5UI uses OKLCH — a perceptually uniform color space. Colors look consistent across lightness levels, making it ideal for accessible theming.

OKLCH Format
/* oklch(lightness chroma hue) */

/* Lightness: 0 (black) → 1 (white) */
/* Chroma: 0 (gray) → 0.4 (vivid) */
/* Hue: 0-360 (color wheel angle) */

--color-primary: oklch(0.546 0.245 262.88);
/*                     ↑     ↑     ↑        */
/*                  bright  vivid  blue      */

Color Tokens

Each color has 4 tokens following Material Design 3 conventions.

primary bg-primary
primary-container bg-primary-container
primary
on-primary
primary-container
on-primary-container
secondary bg-secondary
secondary-container bg-secondary-container
secondary
on-secondary
secondary-container
on-secondary-container
tertiary bg-tertiary
tertiary-container bg-tertiary-container
tertiary
on-tertiary
tertiary-container
on-tertiary-container
success bg-success
success-container bg-success-container
success
on-success
success-container
on-success-container
warning bg-warning
warning-container bg-warning-container
warning
on-warning
warning-container
on-warning-container
error bg-error
error-container bg-error-container
error
on-error
error-container
on-error-container
info bg-info
info-container bg-info-container
info
on-info
info-container
on-info-container
surface bg-surface
surface-container bg-surface-container
surface
on-surface
surface-container
on-surface-container

Surface System

Surface tokens provide depth-based backgrounds following Material Design 3. Use them for page backgrounds, cards, and elevated containers.

lowest
low
default
high
highest
TokenPreviewUsage
bg-surface
Base page background
bg-surface-dim
Dimmed surface for recessed areas
bg-surface-bright
Bright surface for prominent areas
bg-surface-container-lowest
Lowest elevation container
bg-surface-container-low
Low elevation container
bg-surface-container
Default elevation — cards, panels
bg-surface-container-high
High elevation — dialogs, drawers
bg-surface-container-highest
Highest elevation — tooltips, popovers
text-on-surfaceAaPrimary text on surface backgrounds
text-on-surface-variantAaSecondary/muted text
border-outline
Strong borders and dividers
border-outline-variant
Subtle borders and separators

Using in Tailwind

All color tokens are available as Tailwind CSS classes. Use them for backgrounds, text, borders, and more.

Example.svelte
<!-- Background colors -->
<div class="bg-primary">Primary background</div>
<div class="bg-surface-container">Elevated surface</div>

<!-- Text colors -->
<p class="text-on-surface">Primary text</p>
<p class="text-on-surface/60">Muted text (60% opacity)</p>

<!-- Border colors -->
<div class="border-outline-variant">Subtle border</div>

<!-- Combined -->
<div class="bg-primary-container text-on-primary-container">
  Tinted container
</div>

Customizing Colors

Override CSS custom properties to customize any color. Define both light and dark mode values.

src/routes/layout.css
@import 'tailwindcss';
@import 'sv5ui/theme.css';

@custom-variant dark (&:where(.dark, .dark *));

/* Override primary color */
:root {
  --color-primary: oklch(0.60 0.20 280);
  --color-on-primary: oklch(1 0 0);
  --color-primary-container: oklch(0.90 0.05 280);
  --color-on-primary-container: oklch(0.25 0.10 280);
}

.dark {
  --color-primary: oklch(0.75 0.15 280);
  --color-on-primary: oklch(0.20 0.05 280);
  --color-primary-container: oklch(0.30 0.08 280);
  --color-on-primary-container: oklch(0.90 0.05 280);
}

Border Radius

Customize the global border radius scale by overriding radius tokens.

layout.css
/* Override border radius tokens */
:root {
  --radius-xs:   0.125rem;
  --radius-sm:   0.25rem;
  --radius-md:   0.375rem;
  --radius-lg:   0.5rem;
  --radius-xl:   0.75rem;
  --radius-2xl:  1rem;
  --radius-3xl:  1.5rem;
  --radius-full: 9999px;
}

Global Configuration

Use defineConfig to set library-wide defaults for variants, slots, and icons.

src/lib/config.ts
import { defineConfig } from 'sv5ui';

defineConfig({
  button: {
    defaultVariants: { variant: 'outline', size: 'md' },
    slots: { base: 'rounded-full' }
  },
  avatar: {
    defaultVariants: { size: 'lg' },
    slots: { root: 'ring-2 ring-primary' }
  },
  icons: {
    loading: 'svg-spinners:ring-resize',
    close: 'lucide:x',
    chevronDown: 'lucide:chevron-down',
    chevronRight: 'lucide:chevron-right',
    check: 'lucide:check',
    light: 'lucide:sun',
    dark: 'lucide:moon'
  }
});

Per-Component Overrides

Every component accepts a ui prop to override specific slot classes on individual instances.

Example.svelte
<!-- Override specific component slots -->
<Button
  ui={{ base: 'rounded-full shadow-lg', label: 'uppercase' }}
  label="Custom Button"
/>

<Card ui={{ root: 'shadow-xl', header: 'bg-primary/5' }}>
  {#snippet header()}
    <h3>Styled Card</h3>
  {/snippet}
  Content here
</Card>
Installation Dark Mode