Theming

Phoundry UI uses CSS custom properties for theming. All components reference semantic tokens that can be overridden globally, per-component, or dynamically at runtime via the ThemeManager.

CSS setup

Import the style files in your app’s root layout or CSS entry point:

@import 'phoundry-ui/styles';

The bundle includes Tailwind integration, source registration for packaged components, theme variables, component tokens, utility classes, and editor styles in the intended order.

The ThemeManager is a singleton that handles runtime theme registration and application. It applies themes by setting CSS custom properties on document.documentElement, and listens for system color-scheme changes to re-apply automatically.

Basic usage

The ThemeManager ships with built-in themes across many families. Register them all at once, or pick only the ones you need.

Show code

import { getThemeManager, builtinThemes } from 'phoundry-ui';

const tm = getThemeManager();

// Register the built-in theme palettes
for (const theme of builtinThemes) {
  tm.register(theme);
}

// Apply based on user preferences (persistence is your responsibility)
tm.applyBasedOnPreference({
  colorScheme: 'system',
  lightTheme: 'phi.default-light',
  darkTheme: 'phi.default-dark',
});

Built-in themes

Click any theme to apply it live. This documentation updates to show the selected palette.

Dark Themes

Light Themes

ThemeDefinition

Prop	Type	Default	Description
id required	string	—	Unique identifier (e.g. 'phi.nord-dark').
name required	string	—	Human-readable name shown in theme pickers.
author	string	—	Theme author attribution.
mode required	'light' \| 'dark' \| 'both'	—	Which system appearance this theme targets.
variables required	ThemeVariables	—	CSS variable overrides (primary set).
lightVariables	ThemeVariables	—	Separate variable set for light mode (only when mode is 'both').
preview	{ background, foreground, accent }	—	Preview colors for theme picker UI.

ThemeManager methods

Prop	Type	Default	Description
register(theme)	ThemeDefinition	—	Register a theme. Replaces existing themes with the same ID.
unregister(id)	string → boolean	—	Remove a theme by ID. Clears active theme if it matches.
getThemesByMode(mode)	'light' \| 'dark' → ThemeDefinition[]	—	Get themes that match a mode (includes 'both').
activeThemeId	string \| null	—	Reactive getter for the currently applied theme ID.
apply(id)	string	—	Apply a theme by ID (ignores color-scheme preference).
applyBasedOnPreference(settings)	ThemeSettings	—	Apply the correct theme based on colorScheme, lightTheme, and darkTheme.
clearTheme()	void	—	Remove all CSS variables set by the active theme.