@xngui/theme

v0.0.5

Published

9 days ago

Runtime theme service for @xngui — light, dark, and system modes

0High
0Medium
0Low

`@xngui/theme`

Runtime theme for @xngui/styles — toggles .dark on document.documentElement and applies optional primitive palettes.

Install

pnpm add @xngui/theme @xngui/styles

Usage

import { XPaletteService, XThemeService, provideXPalettes } from '@xngui/theme';

inject(XThemeService).toggle();
inject(XThemeService).setMode('dark');
inject(XPaletteService).setPalette('blue');

Custom palette (bootstrap)

import { provideXPalettes } from '@xngui/theme';

export const appConfig: ApplicationConfig = {
  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)',
          // … full role ramps recommended — copy shape from X_BUILTIN_THEME_PALETTES
        },
      },
    ]),
  ],
};

Custom palette (runtime)

inject(XPaletteService).registerPalette({
  id: 'brand',
  label: 'Brand',
  description: 'Runtime palette.',
  icon: '🎨',
  tokens: { '--x-primary-500': 'oklch(0.55 0.14 250)' },
});
inject(XPaletteService).setPalette('brand');

Persistence uses X_STORAGE_KEYS.themePalette (@xngui/core).

API

| Service | Members | Role | | ----------------- | -------------------------------------------------------------- | -------------------------------------------------------- | | XThemeService | mode, resolvedMode, isDark, setMode, toggle, cycle | Light / dark / system + .dark on <html> | | XPaletteService | palette, catalog, setPalette, registerPalette | :root primitive overrides via <style id="x-palette"> | | XTokenResolver | resolve, invalidate | Read resolved --x-* from :root |

Built-in catalog: 29 palettes (17 chromatic hues + 12 semantic themes), grouped by X_THEME_PALETTE_CATEGORIES. Regenerate tokens from libs/styles via pnpm nx run styles:generate-themes.

| Helper | Role | | -------------------------- | ------------------------------------------- | | provideXPalettes | Register custom palettes at bootstrap | | toPaletteDefinition | Normalize input → XThemePaletteDefinition | | buildPaletteRootCss | Build :root { … } CSS from tokens | | normalizePaletteTokens | Ensure --x-* keys | | X_BUILTIN_THEME_PALETTES | Shipped definitions (id, meta, tokens) |

Z-index overrides and shouldAnimate() live on XConfigService (@xngui/core/config).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme