Themes
@xngui/theme@xngui/themeRuntime appearance and palette presets — XThemeService, XPaletteService, and 38 built-in themes.
Overview
Three layers
Foundation styles load once; appearance and palette are optional layers you can mix.
- @xngui/styles foundation
Primitives, semantic light/dark roles, scale, states — always imported in your global stylesheet.
- XThemeService appearance
Toggles .dark on <html> and sets data-theme — persists under x-theme in localStorage.
- XPaletteService palette
Swaps primary, accent, and other primitive ramps — optional if you use a CSS theme @import instead.
Choose your path
Same presets — three ways to apply primitive color ramps.
CSS @import
Build-time primitive overrides
When the brand palette is fixed before deploy.
- No JavaScript required
- Import only the preset file you need
- Works in any stack — not Angular-specific
XPaletteService
Runtime palette switching
When users pick presets in-app (picker, settings, demo).
- This page previews live — tap any preset card below
- Pairs with light / dark mode from XThemeService
- Remembers choice in localStorage across reloads
Theme builder
Prototype and export
When tuning ramps before committing CSS or provideXPalettes().
- Live preview against semantic light / dark CSS
- Copy CSS overrides or register custom palettes
- Start from any of the 38 built-in presets
styles.css@import '@xngui/styles';@import '@xngui/styles/themes/chromatic/blue';palette.tsimport { XPaletteService } from '@xngui/theme';inject(XPaletteService).setPalette('ocean');Related docs
Light / dark appearance and color palettes are separate — pick how you apply the 38 built-in presets.
Styles tokens for the CSS token pipeline, primitives, semantic roles, and palette @import path.
Theme
Theme Services
Three runtime services — appearance mode, color ramps, and computed token reads.
XThemeServiceControl light, dark, and system appearance.
- light · dark · system preference.
- Adds or removes .dark on <html> automatically.
- Remembers choice in localStorage.
XThemeService.tsimport { XThemeService } from '@xngui/theme';const theme = inject(XThemeService);theme.mode(); // 'light' | 'dark' | 'system'theme.resolvedMode(); // 'light' | 'dark' after system resolvetheme.isDark(); // booleantheme.setMode('dark'); // persists to localStoragetheme.toggle(); // flips resolved light ↔ darktheme.cycle(); // light → dark → system → …XPaletteServiceSwap primitive color ramps without touching semantic CSS.
- 38 built-in palettes plus any you register at runtime.
- setPalette() injects a :root style block at runtime.
- registerPalette() for one-off brand ramps.
XPaletteService.tsimport { XPaletteService } from '@xngui/theme';const palettes = inject(XPaletteService);palettes.palette(); // active palette idpalettes.catalog(); // built-in + registered metapalettes.setPalette('blue'); // injects <style id="x-palette">palettes.registerPalette({ id: 'brand', label: 'Brand', description: 'Custom ramp.', icon: '🎨', tokens: { '--x-primary-500': 'oklch(0.55 0.14 250)' },});XTokenResolverResolve live token values from the DOM.
- Read computed values for any --x-* token.
- Clear cache after theme or palette changes.
- Used by theme builder and debugging tools.
XTokenResolver.tsimport { XTokenResolver } from '@xngui/theme';const tokens = inject(XTokenResolver);tokens.resolve('--x-primary'); // computedCSSValuetokens.invalidate(); // clear cache after theme/palette changeAppearance
Switch light, dark, or system — the theme service toggles .dark on the document root.
- Preference
system- Resolved
light- Active palette
default
theme.tsimport { XPaletteService, XThemeService } from '@xngui/theme';// Appearance — toggles .dark on <html>inject(XThemeService).setMode('dark');inject(XThemeService).toggle();// Primitive ramps — :root block in <style id="x-palette">inject(XPaletteService).setPalette('blue');Predefined Themes
Chromatic Palettes
Seventeen Tailwind chromatic hues — tap a card to preview live and copy its @import line.
Warm spectrum
Tailwind red → yellow chromatic ramps
- Red
- Orange
- Amber
- Yellow
Fresh spectrum
Tailwind lime → teal chromatic ramps
- Lime
- Green
- Emerald
- Teal
Cool spectrum
Tailwind cyan → indigo chromatic ramps
- Cyan
- Sky
- Blue
- Indigo
Vivid spectrum
Tailwind violet → rose chromatic ramps
- Violet
- Purple
- Fuchsia
- Pink
- Rose
Nature Themes
Twelve season and nature presets — four seasons plus land, sea, and sky moods with curated role anchors.
Seasons
Spring, summer, autumn, and winter mood presets
- Spring
- Summer
- Autumn
- Winter
Nature & sky
Land, sea, and sky scene presets
- Sunset
- Ocean
- Forest
- Desert
- Aurora
- Starry night
- Mountain
- Rain
Inspired Themes
Palettes inspired by published design systems — not official products. See themes/THIRD_PARTY_NOTICES.md.
Inspired themes
Palettes inspired by published design systems — not official products
- GitHub
- Dracula
- Material
- Nord
- Catppuccin
- Tokyo Night
- Gruvbox
Utility Themes
Minimal monochrome and high-contrast presets for layout clarity and accessibility demos.
Utility
Minimal and accessibility-focused presets
- Monochrome
- High contrast
Brand Spectrum
Each hue ships full 50–950 ramps for all eight roles — primary is exact Tailwind, semantics pick up subtle brand gravity.
primarysecondaryaccentneutralsuccesswarningdangerinfoprimarysecondaryaccentneutralsuccesswarningdangerinfoprimarysecondaryaccentneutralsuccesswarningdangerinfoprimarysecondaryaccentneutralsuccesswarningdangerinfoCustom Palettes
Register brand ramps at bootstrap or runtime with palette providers and registerPalette(). Prototype ramps in the theme builder before exporting CSS overrides.
palettes.tsimport { provideXPalettes } from '@xngui/theme';export const appConfig = { providers: [ provideXPalettes([ { id: 'brand', label: 'Brand', description: 'Company primary ramp.', icon: '🎨', tokens: { 'x-primary-500': 'oklch(0.55 0.14 250)', 'x-primary-600': 'oklch(0.48 0.16 250)', }, }, ]), ],};register.tsimport { XPaletteService } from '@xngui/theme';const palettes = inject(XPaletteService);palettes.registerPalette({ id: 'brand', label: 'Brand', description: 'Runtime palette.', icon: '🎨', tokens: { '--x-primary-500': 'oklch(0.55 0.14 250)' },});palettes.setPalette('brand');