@raminy/css-config
Version:
Tailwind CSS v4 configuration with predefined themes, semantic color tokens, and SCSS utilities for theme customization and generation.
274 lines (192 loc) • 5.93 kB
Markdown
# @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.