tailwind-theming
v0.0.12
Published
Tailwind theming plugin
Downloads
27
Readme
Tailwind theming
This plugin is an opinionated way to theme your Tailwind CSS project. It uses CSS variables to define a set of semantic color tokens that can be used throughout your project. It provides a default light and dark theme, but you can easily use your own themes.
Installation
npm i -D tailwind-theming
Usage
Add the plugin to your tailwind.config.js
file:
import type { Config } from "tailwindcss";
import themePlugin from "tailwind-theming";
import { defaultThemes } from "tailwind-theming/themes";
const config = {
// Your Tailwind config
plugins: [themePlugin(defaultThemes)],
} satisfies Config;
export default config;
If you don't have a theme in mind, you can use my own default theme as shown above. If you want to use your own themes, you can pass them as an object.
import type { Config } from "tailwindcss";
import themePlugin from "tailwind-theming";
const config = {
// Your Tailwind config
plugins: [themePlugin({
light: {
base: {
DEFAULT: {
DEFAULT: "255 255 255",
hover: "240 240 240",
},
fg: {
DEFAULT: "0 0 0",
hover: "17 17 17",
},
},
},
dark: {
base: {
DEFAULT: {
DEFAULT: "0 0 0",
hover: "17 17 17",
},
fg: {
DEFAULT: "255 255 255",
hover: "240 240 240",
},
},
},
})],
} satisfies Config;
These can be either RGB, HSL, or hex values (255 255 255
, 0 0% 100%
, or #fff
). The plugin will transform any hex values to RGB (#fff
-> 255 255 255
) which allows tailwind to apply its opacity classes to them. For consistency, it is recommended to use one of these for all your colors, but you can mix them if you want. The only thing you need to make sure of is that a semantic token is always defined in the same format in all the themes. For example:
import type { Config } from "tailwindcss";
import themePlugin from "tailwind-theming";
const config = {
// Your Tailwind config
plugins: [themePlugin({
light: {
base: {
DEFAULT: {
// This is HSL
DEFAULT: "0 0 100%",
hover: "240 240 240",
},
fg: {
DEFAULT: "0 0 0",
hover: "17 17 17",
},
},
},
dark: {
base: {
DEFAULT: {
// Same token in different theme also in HSL
DEFAULT: "0 0 0%",
hover: "17 17 17",
},
fg: {
DEFAULT: "255 255 255",
hover: "240 240 240",
},
},
},
})],
} satisfies Config;
This will create this set of CSS variables...
:root {
--base: 255 255 255;
--base-hover: 240 240 240;
--base-fg: 0 0 0;
--base-fg-hover: 17 17 17;
}
@media (prefers-color-scheme: dark) {
:root {
--base: 0 0 0;
--base-hover: 17 17 17;
--base-fg: 255 255 255;
--base-fg-hover: 240 240 240;
}
}
.light {
--base: 255 255 255;
--base-hover: 240 240 240;
--base-fg: 0 0 0;
--base-fg-hover: 17 17 17;
}
.dark {
--base: 0 0 0;
--base-hover: 17 17 17;
--base-fg: 255 255 255;
--base-fg-hover: 240 240 240;
}
... and this set of utility classes for tailwind usable with any of the color classes: base
, base-hover
, base-fg
, base-fg-hover
You can also use opacity classes with these colors: bg-base/80
or bg-base bg-opacity-80
.
These can be used like this:
<button class="bg-base text-base-fg hover:bg-base-hover hover:text-base-fg-hover">Click me!</button>
Setting the theme
By default the plugin will use the prefers-color-scheme
media query to set the theme. If you want to set the theme manually, you can use the key of your theme as a class (light
and dark
in the case above), usually done on the <html>
element, but can be done everywhere.
<!-- This will use whatever is set above in the HTML, or the prefered color scheme of the clients system -->
<button class="bg-base text-base-fg hover:bg-base-hover hover:text-base-fg-hover">Click me!</button>
<!-- This will use the light theme -->
<div class="light">
<button class="bg-base text-base-fg hover:bg-base-hover hover:text-base-fg-hover">Click me!</button>
</div>
<!-- This will use the dark theme -->
<div class="dark">
<button class="bg-base text-base-fg hover:bg-base-hover hover:text-base-fg-hover">Click me!</button>
</div>