@bitcurve/reactor-tw-palette

A tailwindcss plugin that helps define the palette of a tailwind preset or theme with light/dark mode support and coordination with the @tailwindcss/typography (prose) plugin.

The plugin accepts a PluginThemePaletteDefinition object and uses it to:

• create CSS custom properties (CSS variables) for each color
• create color utility classes under tailwind preset/config theme.extend.colors
• automatically map colors that follow a naming convention to apply the @tailwindcss/typography (prose) plugin

This package includes a helper to extend tailwind-merge to recognize custom color utility classes added via this plugin so they can be intelligently merged with other color utilities.

This package is published as both ESM + CJS with types and source maps targeting ES2022.

Features

CSS custom properies and color utility classes generated by this plugin are prefixed with a capital P (for palette) so they are easily distinguished from other color utilities and easily searchable in code: e.g. --P-primary -> text-P-primary.

The theme palette definition supports nesting with a tailwind-config-like convention for DEFAULT keys. Nested keys are flattened for easy reference e.g. --P-primary-hover -> text-P-primary-hover.

The value of CSS custom properties set by this plugin are color channel values as required to support tailwind's opacity modifier syntax e.g. bg-P-primary/50.

Color values in a palette definition object can be RGB (#000, #fffff), HSL (hsl(...), hsla(...)), or OKLCH (oklch(...)).

This makes it is easy to paste colors from design tools and to reference colors from tailwind's default palette or any tailwind-compatible palette such as the @evilmartians/harmony OKLCH palette.

The entries in a palette definition object are entirely free-form and the only convention is for automatic mapping to the @tailwindcss/typography (prose) plugin.

Installation

All documentation and examples assume ESM; revise the syntax accordingly if you are using CommonJS.

Install this Package

Install this package as a dev dependency:

pnpm add -D @bitcurve/reactor-tw-palette

Import into your tailwind preset or theme and provide your color definition in the plugin configuration.

The theme palette definition should satisfy the type PluginThemePaletteDefinition.

const tailwindConfig = {
  // ...
  plugins: [
    palettePlugin({
      palette: themePaletteDefinition,
      typography: {
        applyAlpha: true,
        colorSpaceFn: 'oklch', // 'rgb', 'hsl', 'oklch' supported
      }
    }),
  ]
  // ...
}

Specifying typography config is optional: the defaults are applyAlpha: true and colorSpaceFn: 'rgb'.

Theme Palette Definition

import { neutral, slate, cyan } from 'tailwindcss/colors'

const neutral = {
  ...colors.neutral,
} satisfies PaletteDictionary

const palette = {
  // tuple values define respective light and dark colors in one line
  border: ['hsl(31 120 50)', 'hsl(31 120 10)'],

  // single values as strings or 1-item arrays apply the same color to both light and dark
  box: 'hsl(31 120 50)',

  // arbitrary levels of nesting are supported with `DEFAULT` special case (this produces `--P-link` and `--P-link-hover`)
  link: {
    DEFAULT: '#0000ff',
    hover: '#0000fa',
  },

  // refer to type PaletteTypographyDictionary for enforced types that map to typography plugin
  // a current limitation (pending TODO) is all values must use the same color space (rgb/hsl/oklch) and it must be set in config
  content: {
    // ...
  }
}

Merge css class names with cn()

import { cn } from '@bitcurve/reactor-style'