Theme API
The theme package keeps the public surface intentionally small: presets, composition helpers, token resolvers, and adapters that project the same theme definition into runtime CSS or Tailwind config.
| Type | Purpose |
|---|---|
ThemeDefinition | Resolved theme object containing metadata plus primitive and semantic token scales. |
ThemeMeta | Minimal metadata contract for a theme, including its name and active mode. |
ThemeTokens | Top-level token container with primitive collections and semantic collections. |
ThemeOverride | Partial override object used when composing a product-specific theme from a preset. |
ThemePrimitives / ThemeSemanticTokens | Typed token groups for color, spacing, radius, typography, motion, and semantic surfaces. |
Runtime helpers
These exports are the common entry points for creating a theme, resolving tokens, and projecting the result into CSS or Angular runtime setup.
| Helper | Purpose |
|---|---|
createTheme(base, override?) | Returns the base preset unchanged or merges the override into a new theme definition. |
mergeTheme(base, override) | Performs the underlying token-scale merge when you need explicit control over composition. |
resolveToken(theme, tokenPath) | Resolves a token reference path such as {accent.brand} or {semantic.background.surface}. |
resolveTokenValue(theme, value) | Resolves nested token references inside a value before it is rendered or exported. |
toCssVars(theme, options?) | Converts theme tokens into CSS custom properties, with switches for primitives, semantics, and raw references. |
applyTailngTheme(theme, options?) | Writes CSS variables to a target element and can also update the local color-scheme. |
provideTailngTheme(options?) | Angular environment provider that applies a preset during app bootstrap. |
toTailwindPreset(theme) | Projects a theme into Tailwind `extend` values so utilities can consume the same tokens. |
Preset exports
Each built-in preset ships as explicit light and dark exports so teams can pick a starting point without hand-authoring every token scale.
| Preset | Light export | Dark export | Intent |
|---|---|---|---|
| Default | defaultThemePreset | defaultDarkThemePreset | Balanced spacing and expressive accents for general product interfaces. |
| Minimal | minimalThemePreset | minimalDarkThemePreset | Compact and low-contrast when content density matters more than decoration. |
| Slate | slateThemePreset | slateDarkThemePreset | Quiet neutrals for polished dashboards and dense application shells. |
| Nexus | nexusThemePreset | nexusDarkThemePreset | Modern accent balance suited to product surfaces with a little more energy. |
| Prism | prismThemePreset | prismDarkThemePreset | Sharper contrast and brighter accents for expressive product moments. |
| Atlas | atlasThemePreset | atlasDarkThemePreset | Confident teal-led tones that feel grounded across operational tools. |
| Sterling | sterlingThemePreset | sterlingDarkThemePreset | Premium contrast and refined accents for more editorial or branded experiences. |
| Daybook Classic | daybookClassicThemePreset | daybookClassicDarkThemePreset | Ledger-toned paper, navy, and signal colors for dense finance workflows. |
Composition flow
A typical workflow is: start from a preset, override semantic scales for the product, resolve any token references you need, then apply the result through CSS variables or the Angular provider.
Compose and inspect a theme
ts
import { createTheme, defaultThemePreset, resolveToken, toCssVars } from '@tailng-ui/theme';
const productTheme = createTheme(defaultThemePreset, {
meta: { name: 'acme-default-dark', mode: 'dark' },
tokens: {
semantic: {
accent: {
brand: '#2563eb',
brandHover: '#1d4ed8',
},
focus: {
ring: '#2563eb',
},
},
},
});
const brand = resolveToken(productTheme, '{accent.brand}');
const cssVars = toCssVars(productTheme);
Apply a theme at runtime
ts
import { applyTailngTheme, defaultDarkThemePreset } from '@tailng-ui/theme';
applyTailngTheme(defaultDarkThemePreset, {
target: document.documentElement,
applyColorScheme: true,
});