npm package: @raminy/css-config
Description: Tailwind CSS v4 configuration with predefined themes, semantic color tokens, and SCSS utilities for theme customization and generation.
Author: Ramin yavari
Latest version: 4.4.0

# @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](https://storybook.raminy.dev/?path=/docs/colorpalettes--docs)

---

## Installation

1. Install Tailwind CSS v4:

```bash
npm install -D tailwindcss@latest
```

2. 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:

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

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

```ts
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

```html
<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:

```html
<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:

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

👉 [View the full list of semantic color tokens](https://storybook.raminy.dev/?path=/docs/colorpalettes--docs)

---

## Customize or Generate Your Own Themes

To customize themes, start by importing the SCSS utilities:

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

### 🎯 Theme Format

A theme is a map structured like this:

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

Example:

```scss
$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.

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

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

Selects multiple themes by name from the predefined theme set.

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

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

Returns a single predefined theme.

```scss
$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.

```scss
$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:

```scss
@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:

```scss
@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

```scss
@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.

```scss
@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.

```scss
@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:

```bash
pnpm generate:styles-css
```

---

### 🛠 Scripts

#### Adding or Removing a Semantic Token

After adding or removing a semantic token, rerun:

```bash
pnpm generate:styles-css
```

This will update the Tailwind config and regenerate types accordingly.