Theme System Documentation#

The color theme system is now centralized and easy to extend. All theme definitions are managed through a single configuration file.

Architecture#

/src/lib/config/themes.config.ts - Central theme configuration (add new themes here)
/src/lib/stores/colorTheme.ts - Theme state management
/src/lib/components/layout/ColorThemeToggle.svelte - Theme picker UI
/src/lib/styles/themes/*.css - Individual theme CSS files
/src/lib/styles/themes.css - Theme CSS imports

Adding a New Theme#

To add a new theme, follow these steps:

1. Add Theme Definition to Config#

Edit /src/lib/config/themes.config.ts and add your theme to the THEMES array:

{
  value: 'midnight',           // Unique identifier (used in CSS and localStorage)
  label: 'Midnight',           // Display name in dropdown
  description: 'Deep night',   // Short description
  color: 'oklch(20% 0.05 240)', // Preview color (shown in dropdown)
  category: 'cool'             // 'neutral' | 'warm' | 'cool' | 'vibrant'
}

2. Create Theme CSS File#

Create /src/lib/styles/themes/midnight.css with your color definitions:

/* ============================================================================
   MIDNIGHT THEME - Deep night
   Primary: Dark blue
   Secondary: Navy
   Accent: Steel
   Hue: 240° (blue)
   ============================================================================ */
[data-color-theme='midnight'] {
	/* Define your CSS custom properties here */
	--color-primary-500: oklch(20% 0.05 240);
	/* ... other color definitions ... */
}

3. Import Theme CSS#

Add the import to /src/lib/styles/themes.css:

@import './themes/midnight.css';

That's It!#

The theme will automatically:

✅ Appear in the color theme dropdown
✅ Be type-safe in TypeScript
✅ Work with the theme switcher
✅ Persist in localStorage

Configuration API#

`THEMES`#

Array of all available themes. Each theme has:

value: Unique identifier (string)
label: Display name (string)
description: Short description (string)
color: Preview color in OKLCH format (string)
category: Theme category (string)

`ColorTheme`#

TypeScript type automatically generated from theme values.

`DEFAULT_THEME`#

The default theme used when no preference is stored.

`getThemesByCategory()`#

Returns themes organized by category for UI rendering.

`getTheme(value)`#

Get a specific theme definition by its value.

Example: Adding Multiple Themes#

// In themes.config.ts
export const THEMES: readonly ThemeDefinition[] = [
	// ... existing themes ...

	// New themes
	{
		value: 'midnight',
		label: 'Midnight',
		description: 'Deep night',
		color: 'oklch(20% 0.05 240)',
		category: 'cool'
	},
	{
		value: 'sunrise',
		label: 'Sunrise',
		description: 'Morning glow',
		color: 'oklch(75% 0.15 50)',
		category: 'warm'
	}
] as const;

Then create midnight.css and sunrise.css in the themes folder, and import them in themes.css.