@raminy/css-config

For Consumers

This package is designed for use with Tailwind CSS v4 and includes:

A preconfigured CSS setup for Tailwind v4.
Optional TS config (usually unnecessary since Tailwind v4 is zero-config and can rely on the CSS setup alone).
Prebuilt postcss.config.cjs and postcss.config.mjs.
A set of predefined themes.
SCSS utilities for customizing or generating new themes.

👉 See the list of predefined themes and semantic color tokens

Installation

Install Tailwind CSS v4:

npm install -D tailwindcss@latest

Import the base Tailwind config from this package in your main CSS entry file. This should appear immediately after the core Tailwind directives to ensure correct layering:

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

Add the following import to your main ts or js entrypoint:

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

⚠️ Note: If you plan to customize the theme(s), do not import the files above. Instead, follow the customization instructions below.

Applying a Theme

A default theme is always applied automatically. If you're using a single theme, no additional steps are needed.

If you're using multiple themes, you can explicitly set a theme and/or mode (light or dark) using data- attributes on any HTML element. These values will cascade to all descendants unless overridden.

🎨 Set a Theme

<body data-theme="cg-blue">
  ...
</body>

🌗 Set a Mode

By default, the mode respects the user’s system preferences. However, you can force it per element:

<body data-theme-mode="light">
  ...
</body>

Using the Theme with Tailwind

Themes provide semantic color tokens. These map to Tailwind utilities, so changing the theme or mode automatically updates the color scheme.

Example:

<div class="bg-primary text-on-primary border-divider">...</div>

👉 View the full list of semantic color tokens

Customize or Generate Your Own Themes

To customize themes, start by importing the SCSS utilities:

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

🎯 Theme Format

A theme is a map structured like this:

(
  [semantic-color]: (
    light: [color-value],
    dark: [color-value],
  ),
  ...
)

Example:

$theme-cg-blue: (
  primary: (
    light: #0052cc,
    dark: #4c9aff,
  ),
  on-primary: (
    light: #ffffff,
    dark: #092957,
  ),
  muted: (
    light: #d6e4f0,
    dark: #1c2b3a,
  ),
);

🛠 Available Utilities

`theme-generator($primary-color)`

Generates a full theme from a single primary color.

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

`pick-themes((...))`

Selects multiple themes by name from the predefined theme set.

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

`pick-theme-by-name($name)`

Returns a single predefined theme.

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

`extend-theme-variant($base-theme, $overrides)`

Extends an existing theme with overrides or new semantic tokens.

$custom-theme: utils.extend-theme-variant(
  utils.pick-theme-by-name(cg-blue),
  (
    primary: (
      light: #0052cc,
      dark: #4c9aff,
    ),
    header: (
      light: #627799,
      dark: #bb23fc,
    ),
  )
);

If you add a new semantic color, you must also register it with Tailwind. This should be done where the Tailwind config CSS is imported or defined—typically inside your main style entry.

To register a semantic color, use the @theme block and map your semantic token to the corresponding theme variable:

@theme {
  --color-[SEMANTIC_COLOR_NAME]: --theme-[SEMANTIC_COLOR_NAME];
}

Example

If you've added semantic color tokens like header and footer, define them as follows:

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

This makes your new semantic colors available to Tailwind's utility classes, allowing them to respond to theme and mode changes automatically.

`@mixin set-themes($themes, $default-theme)`

Applies a list of themes. Takes:

$themes: A map of theme name → theme
$default-theme: The name of the default theme

@include utils.set-themes(
  (
    cg-blue: utils.pick-theme-by-name(cg-blue),
    purple: utils.theme-generator(#6200ee),
    electric-blue: utils.extend-theme-variant(
        utils.pick-theme-by-name(electric-blue),
        (
          primary: (
            light: #0052cc,
            dark: #4c9aff,
          ),
        )
      ),
  ),
  electric-blue
);

`@mixin light-mode()`

Applies styles only when light mode is active — respecting both the user's system preferences and any data-theme-mode="light" overrides.

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

`@mixin dark-mode()`

Applies styles only when dark mode is active, based on system settings or a data-theme-mode="dark" override.

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

For Maintainers

🎨 Theme CSS Variables

All CSS variables are defined in SCSS and compiled to:

tailwind.config.css — contains Tailwind color mappings
themes/themes.types.ts — contains generated TypeScript types

To regenerate these files after changes to tokens or themes:

pnpm generate:styles-css

🛠 Scripts

Adding or Removing a Semantic Token

After adding or removing a semantic token, rerun:

pnpm generate:styles-css

This will update the Tailwind config and regenerate types accordingly.