Tailwind setup

@static-bloom/tailwind is a CSS-first theme for Tailwind CSS 4.3: an @theme inline block, custom variants and custom utilities. There is no JavaScript config. A typed merge helper ships alongside (Class merging).

1. Install Tailwind 4 with its Vite plugin (or the CLI) and the theme.

   pnpm add -D tailwindcss @tailwindcss/vite
   pnpm add @static-bloom/tailwind

2. Register the Vite plugin.

   vite.config.ts

   import { defineConfig } from 'vite'
   import tailwindcss from '@tailwindcss/vite'
   
   export default defineConfig({ plugins: [tailwindcss()] })

3. Import the theme after Tailwind.

   src/style.css

   @import 'tailwindcss';
   @import '@static-bloom/tailwind';
   @import '@static-bloom/vue/tailwind.css'; /* only with @static-bloom/vue */

4. Set the flavor on the document (or let a flavor runtime do it) and use the utilities.

   <html data-flavor="midnight" data-theme="dark">
     <body class="bg-canvas text-fg font-sans">
       <button class="bg-primary text-on-primary rounded-md px-4 py-2 glow-sm">Connect</button>
     </body>
   </html>

What each line does

Import	Brings
@static-bloom/tailwind	The locally bundled fonts (@static-bloom/css/fonts.css) and the theme
@static-bloom/tailwind/theme.css	The theme only: tokens, colors, fonts, radius, shadows, easings, animations, utilities, variants
@static-bloom/vue/tailwind.css	An @source for the Vue package’s dist, so Tailwind generates the classes its components use

The theme imports @static-bloom/css/tokens.css, not the reset or the component classes: Tailwind’s own preflight stays in charge of the base. Use theme.css when another stylesheet already loads the fonts, such as the full @static-bloom/css bundle.

Runtime theming

Every mapping uses @theme inline, so generated CSS points at the --sb-* variables directly. Switching data-flavor or data-accent restyles every utility without a rebuild, and opacity modifiers mix the variable: bg-primary/20 compiles to color-mix(in oklab, var(--sb-primary) 20%, transparent).

Note

Raw palette colors always carry the sb- prefix (bg-sb-base, text-sb-plasma). An unprefixed base color would make Tailwind read text-base as a color instead of the 1rem font size. Semantic keys (bg-canvas, text-fg) have no prefix because none collides with a Tailwind name.

Opt out of Tailwind’s default colors

Tailwind’s own palette stays available next to Static Bloom’s. To remove it, reset the color namespace before the theme, so the Static Bloom mappings are declared after the reset:

src/style.css

@import 'tailwindcss';
@import './palette-reset.css';
@import '@static-bloom/tailwind';

src/palette-reset.css

@theme {
  --color-*: initial;
}

Starlight and other layered setups

Starlight ships its own reset, so a Starlight site imports Tailwind’s theme and utilities into explicit layers instead of tailwindcss. The full stylesheet is on Starlight setup.