tw-theme-kit
v1.1.0
Published
Professional Tailwind CSS plugin for multi-theme color systems with one className
Maintainers
ericgrahamReadme
tw-theme-kit
Switch Tailwind color themes with one class. Built for Tailwind CSS v4.
Version: 1.1.0
Install
npm i -D tw-theme-kitTailwind CSS v4 is required. npm installs it automatically as a peer dependency.
Setup
1. Add the plugin — tailwind.config.js
import { createThemes } from 'tw-theme-kit';
export default {
content: ['./src/**/*.{html,js,jsx,ts,tsx,vue,svelte,astro}'],
plugins: [
createThemes({
light: {
primary: 'steelblue',
secondary: 'darkblue',
brand: '#F3F3F3',
},
dark: {
primary: 'turquoise',
secondary: 'tomato',
brand: '#4A4A4A',
},
}),
],
};CommonJS:
const { createThemes } = require('tw-theme-kit');2. Link the config — your CSS entry file
@import "tailwindcss";
@config "./tailwind.config.js";3. Apply a theme — add the theme name as a class
<html class="light">
<div class="bg-brand">
<h1 class="text-primary">Hello</h1>
<p class="text-secondary">World</p>
</div>
</html>Switch themes by changing the class: <html class="dark">
Features
| Feature | Description |
| --- | --- |
| One-class switching | Apply light, dark, or any custom theme name as a class |
| OKLCH colors | Automatic conversion for Tailwind v4 opacity support |
| Theme variants | Use dark:rounded to style elements per active theme |
| Nested themes | Scope themes to subtrees with data-theme |
| Nested palettes | { DEFAULT, 100, 200 } objects flatten to primary, primary-100, etc. |
| CSS variables | --ttk-primary, --ttk-secondary, … available in custom CSS |
| ESM + CJS | Works with import and require |
| TypeScript | Full type declarations included |
API
import {
createThemes,
resolveThemeKitConfig,
generateVariantDefinitions,
isThemeKitColorError,
isThemeKitError,
themeKitMeta,
ThemeKitColorError,
ThemeKitError,
} from 'tw-theme-kit';createThemes(config, options?) — returns a Tailwind plugin.
resolveThemeKitConfig(config, options?) — returns { variants, utilities, colors } without wrapping in a plugin. Useful for custom tooling.
generateVariantDefinitions(selector) — returns nested-theme-aware Tailwind variant selectors for a theme class.
isThemeKitError(value) / isThemeKitColorError(value) — runtime type guards for error handling.
themeKitMeta — frozen { name, version, cssVariablePrefix } for logging and tooling.
Lightweight runtime entry — import primitives only (no Tailwind plugin):
import { themeKitMeta, generateVariantDefinitions } from 'tw-theme-kit/runtime';Types: ThemeKitConfig, ThemeKitOptions
Examples
Multiple themes
createThemes({
light: { primary: 'steelblue', brand: '#F3F3F3' },
dark: { primary: 'turquoise', brand: '#4A4A4A' },
forest: { primary: '#2A9D8F', brand: '#264653' },
});Nested color scales
createThemes({
light: {
primary: {
DEFAULT: 'orange',
100: 'red',
200: 'blue',
},
},
});
// → bg-primary, bg-primary-100, bg-primary-200Color-scheme helpers
createThemes(({ light, dark }) => ({
winter: light({ primary: 'white', surface: '#F3F3F3' }),
forest: dark({ primary: 'black', surface: '#1A1A1A' }),
}));CSS variables
.card {
color: var(--ttk-primary);
background: var(--ttk-brand);
}Theme variants
<button class="dark:bg-white dark:text-black">Themed button</button>Nested themes
<html class="dark">
<div data-theme class="winter">
<!-- winter colors apply here -->
</div>
</html>Place
group-*modifiers before theme variants:group-hover:dark:bg-red-500
Options
createThemes(config, {
produceCssVariable: (name) => `--ttk-${name}`, // default
produceThemeClass: (name) => name, // default
produceThemeVariant: (name) => name, // default, same as produceThemeClass
strict: false, // throw ThemeKitColorError on bad colors
});| Option | Default | Purpose |
| --- | --- | --- |
| produceCssVariable | `--ttk-${name}` | CSS custom property name |
| produceThemeClass | theme name | Class applied to activate a theme |
| produceThemeVariant | same as class | Prefix for variant utilities |
| strict | false | Fail on invalid color values |
License
MIT