Introducing @raminy/css-config: Prebuilt Theming for Tailwind CSS v4

With Tailwind CSS v4 introducing CSS-based configuration, managing consistent themes across design systems just got simpler. But what about supporting multiple color themes, semantic tokens, and dark mode — without rewriting everything from scratch?

That’s where @raminy/css-config comes in.

This package is a drop-in, theme-driven utility designed for modern Tailwind workflows. It provides prebuilt configurations, semantic tokens, SCSS utilities, and a library of themes — all designed to work seamlessly with Tailwind v4's zero-config ethos.

🧱 What's in the Box

Here’s what @raminy/css-config includes:

A preconfigured CSS setup for Tailwind v4.
Optional TypeScript config (usually unnecessary).
Ready-to-use postcss.config files (cjs and mjs).
A library of predefined themes with semantic color tokens.
SCSS utilities to generate or customize themes with full light/dark support.

Whether you want to apply a single palette or support runtime theming with cascading data attributes, the package provides the structure to scale.

🚀 Installation & Setup

Install Tailwind v4 and the package:

npm install -D tailwindcss@latest @raminy/css-config

Then, import the Tailwind base and theme setup in your main CSS entrypoint:

@import "tailwindcss";
@import "@raminy/css-config/tailwind.config.css";

In your JavaScript or TypeScript entrypoint, import the theme file:

import "@raminy/css-config/theme.css";
// or
import "@raminy/css-config/theme.scss";

⚠️ If you plan to customize themes, skip this import and follow the SCSS setup below.

🎨 Applying Themes

A default theme is applied automatically. But if your app supports multiple themes or dark mode, you can opt-in using HTML data- attributes:

<body data-theme="cg-blue" data-theme-mode="dark">
  <!-- Everything inside will use the 'cg-blue' theme in dark mode -->
</body>

Themes and modes cascade by default — allowing nested overrides and partial theme switching (e.g., modals, embedded components).

👉 Example of applying themes and modes to specific page sections

🧩 Using Themes with Tailwind

Themes are powered by semantic tokens like primary, on-primary, divider, and more. These tokens map directly to Tailwind utilities:

<div class="bg-primary text-on-primary border-divider">
  <!-- This block auto-updates with the active theme/mode -->
</div>

As you switch themes or modes, your utility classes adapt without needing to rewrite them.

👉 Browse all semantic tokens here

🛠 Customizing or Building New Themes

You can extend the default themes or define your own from scratch using the SCSS utilities provided.

Step 1: Import SCSS Tools

@use "@raminy/css-config/theme-utils.scss" as utils;

Step 2: Understand Theme Format

Themes are defined as semantic maps:

$theme-mybrand: (
  primary: (
    light: #0052cc,
    dark: #4c9aff,
  ),
  on-primary: (
    light: #ffffff,
    dark: #092957,
  ),
);

Step 3: Use SCSS Utilities

Generate a theme from a single color:

$theme = utils.theme-generator(#6200ee);

Pick a predefined theme:

$cg = utils.pick-theme-by-name(cg-blue);

Pick a list of predefined themes:

$themes = utils.pick-themes((cg-blue, crane-purple));

Extend an existing or a generated theme:

$custom = utils.extend-theme-variant($cg, (
  header: (
    light: #627799,
    dark: #bb23fc,
  ),
  footer: (
    light: #627689,
    dark: #cb13fc,
  ),
));

@theme {
  --color-header: --theme-header;
  --color-footer: --theme-footer;
}

Apply all your themes with:

@include utils.set-themes(
  (
    cg-blue: $cg,
    custom-purple: $theme,
  ),
  cg-blue // default
);

🧰 Other Available Utilities

@mixin light-mode()

This mixin applies styles exclusively in light mode, whether it's determined by the user's system preference or explicitly set via data-theme-mode="light". It's useful when you want to fine-tune appearance based on active mode.

@include utils.light-mode() {
  background-color: #343434;
  color: #f00;
}

@mixin dark-mode()

This mixin applies styles only when dark mode is active, triggered either by system-level settings or a data-theme-mode="dark" override on any ancestor element.

@include utils.dark-mode() {
  background-color: #ededed;
  color: #f00;
}

🧠 Why This Exists

Tailwind v4 simplified configuration, but left a gap in theme orchestration and semantic token layering. @raminy/css-config bridges that by offering:

A consistent, reusable foundation.
Extendable SCSS-based workflows.
First-class support for multiple themes, dark mode, and semantic color systems.

Whether you're building design systems, multi-tenant apps, or themable components — this setup lets you focus on intent, not low-level wiring.

📚 Explore Further

If you're already using Tailwind v4 and want a powerful, customizable theme layer — give @raminy/css-config a spin.

Have questions, feedback, or want to showcase your themes? Reach out on LinkedIn.

raminy.dev...