tailwindcss-themeable

!npm (tag)
!npm

- tailwindcss-themeable
- Demos
- Installation
- Usage
- Override auto-generated shade values
- Customized palette keys
- Full configurations
- About shades generating algorithm
- Credits

Adds multiple themes support for Tailwind CSS and Windi CSS.

You can just develop your app with one theme and it will work with multiple themes color palettes, all you need is just to specify your default color values for your theme pallette. We will generate all shades from 50 to 900 for you, following the built-in shade name convention of the default color values.

!dracula_vs_material

Demos

| Demo | Demo Link | Source Code |
| ------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Tailwind CSS | https://upupming.site/tailwindcss-themeable/tailwind/ | examples/tailwind |
| Windi CSS | https://upupming.site/tailwindcss-themeable/windi/ | examples/windi |
| Override shades | https://upupming.site/tailwindcss-themeable/override-shades/ | examples/override-shades |
| Customized palette keys | https://upupming.site/tailwindcss-themeable/customized-palette-keys/ | examples/customized-palette-keys |
| vue3-compact-template themed example | https://upupming.site/vue3-compact-template/storybook/?path=/story/components--themed | https://github.com/upupming/vue3-compact-template/blob/main/src/stories/ThemedExample.vue |

Installation

``bash
npm i -D tailwindcss-themeable
`

Usage

We define the color palette keys following the dracula contribute color palette.

CSS variables are generated from build time, and added to the corresponding scope for usage.

Configuration:

`ts
// windi.config.ts or tailwind.config.js
import { themeable } from 'tailwindcss-themeable'
// or: const { themeable } = require('tailwindcss-themeable')

plugins: [
themeable({
themes: [
{
name: 'example-theme',
palette: {
// color palette key: hex code
background: '#282A36',
foreground: '#F8F8F2',
selection: '#44475A',
comment: '#6272A4',
cyan: '#8BE9FD',
green: '#50FA7B',
orange: '#FFB86C',
pink: '#FF79C6',
purple: '#BD93F9',
red: '#FF5555',
yellow: '#F1FA8C'
}
},
isDark: true
]
})
]
`

Then you can wrap you HTML elements with themeable-example-theme class to use the example-theme theme! All text-themeable-, bg-themeable-, and so on... classes use the CSS variable from the generated CSS of your configuration. tailwindcss-themeable already has two built-in themes (dracula and material) you can use directly.

`html


`css
.text-themeable-foreground {
--tw-text-opacity: 1;
color: rgba(var(--themeable-foreground), var(--tw-text-opacity));
}

.bg-themeable-background {
--tw-bg-opacity: 1;
background-color: rgba(var(--themeable-background), var(--tw-bg-opacity));
}
`

Override auto-generated shade values

As the tailwindcss docs says:

> Bad news, color is complicated and despite trying dozens of different tools, we’ve yet to find one that does a good job generating these sorts of color palettes. We picked all of Tailwind’s default colors by hand, meticulously balancing them by eye and testing them in real designs to make sure we were happy with them.

Although our shade generating algorithm is okay in most cases, you may still find the auto-generated shades not satisfying. You can specify all (or just a part of) the shades of a color if you want, this will overwrite the auto-generated shade value. Below is an example configuration, you can explore more on the override-shades example:

`js
themeable({
themes: [
{
name: 'theme-example',
palette: {
background: {
// Replace the hex color value with whatever your like
'50': '#F9FAFB',
'100': '#F3F4F6',
'200': '#E5E7EB',
'300': '#D1D5DB',
'400': '#9CA3AF',
'500': '#6B7280',
'600': '#4B5563',
'700': '#374151',
'800': '#1F2937',
'900': '#111827',
DEFAULT: '#6B7280',
}
//...
}
]
})
`

Customized palette keys

You may find the dracula theme's palette key is not satisfying, and you may like some name convention such as primary, secondary, etc., just like the material ui does. No problem, you can pass any key you want, but be cautious that you must define the primary key for all your themes to avoid the problem of missing a color when switching themes. The plugin will log a warning message if you forget some keys in a theme. Below is an example configuration, you can explore more on the customized-palette-keys example:

`js
themeable({
themes: [
{
name: 'theme-1',
palette: {
primary: '#42a5f5'
//...
}
},
{
name: 'theme-2',
palette: {
// make sure all your themes have your customized keys to avoid problems when switching themes
primary: '#fcba03'
//...
}
}
]
})
`

Full configurations

This is the type definition of this plugin, you can dive into the source code to see more, all the type definitions are well documented for your convenience. If you have any questions, please fell free to open an issue. And new theme contribution is welcome!

`ts
export interface ThemeableOptions {
/**
* Support a list of theme definitions, the user should define the colors of the theme follow the contribute of Dracula theme.
* See https://draculatheme.com/contribute#color-palette
* @default []
*/
themes?: Theme[]
/**
* Prefix of the class to enable a theme, for example the container with class ${classPrefix}-dracula will enable dracula theme in its children elements
* @default themeable
*/
classPrefix?: string
/** When not specify any theme in HTML, the defaultTheme will be used
* @default dracula
*/
defaultTheme?: string
/**
* This will allow you the change the difference in saturation between each shade of color. By default we use 1.771968374684816 because these are the averages that steps change in tailwind's default colors. Thanks to https://tw-shade-gen.netlify.app/
*/
saturationFactor?: number
/**
* This will allow you the change the difference in lightness between each shade of color. By default we use 7.3903743315508015 because these are the averages that steps change in tailwind's default colors. Thanks to https://tw-shade-gen.netlify.app/
*/
lightFactor?: number
}
`

About shades generating algorithm

The shades generating algorithm will find a best shade number (50-900) for your color, and then generate darker and lighter shades with fixed saturation and lightness step (saturationFactor and lightFactor`).

Credits

1. Idea of shades generation
1. https://github.com/dracula/tailwind
2. https://github.com/nickgraffis/tailwind-color-generator
3. https://github.com/anheric/tailwindshades
2. Idea of theming
1. Theming Tailwind with CSS Variables