setting-up-charcoal-tailwind

Setting up charcoal with Tailwind

@charcoal-ui/tailwind-config turns charcoal tokens into a Tailwind preset. This is the actively developed utility route — new Design Token 2.0 features land here first.

Install

npm install --save-dev @charcoal-ui/tailwind-config @charcoal-ui/theme

Peer dependencies: tailwindcss >=1.4.6, postcss >=7.0.32, csstype >=3.0.0. Tailwind v4 support is WIP — v4 works only by pointing @config at a v3-shaped config.

Configure

// tailwind.config.js
const { light, dark } = require('@charcoal-ui/theme')
const { createTailwindConfig } = require('@charcoal-ui/tailwind-config')

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  presets: [
    createTailwindConfig({
      version: 'v3',
      theme: {
        ':root': light,
        '@media (prefers-color-scheme: dark)': dark,
      },
      unstableTokenV2: true, // Design Token 2.0 — omit and you get 1.0
      iconsV2: true,
    }),
  ],
}

createTailwindConfig() options: version ('v1' | 'v2' | 'v3', Tailwind's version — unrelated to charcoal's), theme, cssVariablesV1, unstableTokenV2, iconsV1, iconsV2. A bare default preset is also exported as config.

unstableTokenV2: true needs the theme CSS too

The preset does not define Design Token 2.0 variables. unstable_createTailwindConfigTokenV2() contains no plugin and no addBase() — it only emits class values that reference var(--charcoal-color-*). Something else has to define them.

Two disjoint namespaces are in play:

Defined by	Names	Example
The preset, when cssVariablesV1 is on (default)	--charcoal-<v1 token>	--charcoal-background1, --charcoal-text1
@charcoal-ui/theme/css/v2/*.css	--charcoal-color-<v2 token>	--charcoal-color-container-default