@tailng-ui/theme

Framework-agnostic TailNG theme engine with token contracts, presets, CSS variable generation, and Tailwind preset adapters.

@tailng-ui/theme provides the contract and runtime tooling to define, merge, resolve, and export TailNG-compatible themes.

Installation

pnpm

pnpm add @tailng-ui/theme

yarn

yarn add @tailng-ui/theme

npm

npm install @tailng-ui/theme

Scope

• Theme contracts and token model
• Built-in presets (defaultThemePreset, minimalThemePreset)
• Theme composition (createTheme, mergeTheme)
• Token resolution (resolveToken, resolveTokenValue)
• CSS variables adapter (toCssVars, injectThemeVars)
• Tailwind adapter (toTailwindPreset)
• Component-level style contracts and CSS exports

Quick usage

import { createTheme, defaultThemePreset, toCssVars } from '@tailng-ui/theme';

const theme = createTheme(defaultThemePreset);
const cssVars = toCssVars(theme);

Token references

Semantic tokens can reference primitive tokens, for example {color.primary500}.

• toCssVars() resolves references by default.
• toCssVars({ resolveReferences: false }) keeps raw token references.
• toTailwindPreset() resolves references before generating Tailwind values.

Component contracts CSS

Package exports include component contract styles:

• @tailng-ui/theme/component-contracts/index.css
• @tailng-ui/theme/component-contracts/*

Shared form-control tokens

Form components resolve their defaults through the shared control contract before falling back to semantic tokens. Override these variables on :root, a theme scope, or a component subtree to tune the whole form family together:

• --tng-control-bg, --tng-control-fg, --tng-control-placeholder
• --tng-control-border, --tng-control-border-hover, --tng-control-border-invalid
• --tng-control-radius, --tng-control-height-sm|md|lg
• --tng-control-padding-block, --tng-control-padding-inline, --tng-control-gap
• --tng-control-font-size, --tng-control-font-weight, --tng-control-line-height
• --tng-control-shadow, --tng-control-focus-shadow
• --tng-overlay-bg, --tng-overlay-border, --tng-overlay-radius, --tng-overlay-shadow
• --tng-item-* and --tng-group-* for option rows and grouped controls

Resting controls are flat by default (--tng-control-shadow: none). Floating panels such as select menus, autocomplete results, and calendars use --tng-overlay-shadow, keeping field and overlay elevation visually distinct.

Build

pnpm nx build theme

Test

Run tests for theme:

pnpm nx run theme:vite:test

Run in watch mode:

pnpm nx run theme:vite:test --watch

Run with coverage:

pnpm nx run theme:vite:test --coverage

Run directly with Vitest (without Nx):

pnpm exec vitest run --config libs/tailng-ui/theme/vitest.config.ts

Documentation

• Package docs: https://tailng.dev
• Repository: https://github.com/tailng/tailng-ui

License

See the repository license at the root of the monorepo.