npm package: @ilijazm/tailwindcss-semantic-palette
Description: TailwindCSS Semantic Palette is a highly extendable plugin for Tailwind CSS that extends the default color palette with colors with semantic meaning.
Author: Ilijaz Mehmedovic
Latest version: 0.2.4

# TailwindCSS Semantic Palette

TailwindCSS Semantic Palette is a highly extendable plugin for Tailwind CSS
that extends the default color palette with colors with semantic meaning.
This allows the user to reference colors by their intended meaning such as `primary`, `success`, or `warning`
instead of specific color values such as `indigo`, `green`, or `yellow`.

![Introduction](docs/images/readme_introduction.png)


**Table of content**

1. [Installation](#1-installation)
2. [Features](#2-features)
3. [Customization](#3-customization)
4. [Contributions](#4-contributions)
5. [Further information](#5-further-information)

## 1. Installation

To install the TailwindCSS Semantic Palette follow the following steps:

1. Install the TailwindCSS Semantic Palette dependency:

```bash
npm install @ilijazm/tailwindcss-semantic-palette
```

2. Import the plugin in your `.css`-file.

```diff
@import "tailwindcss";
+ @plugin "@ilijazm/tailwindcss-semantic-palette";
```

## 2. Features

### Default palette extension

By default, the plugin adds the following colors to the TailwindCSS palette:

* `surface`
* `container`
* `content`
* `brand`
* `primary`
* `secondary`
* `tertiary`
* `accent`
* `info`
* `success`
* `warning`
* `danger`

![Default colors](docs/images/default_colors.png)

### Automatic shade generation

Color shades can be automatically generated.
That means that one color is enough to generate the full tailwindcss shades from 50 to 950.

This example demonstrates how the user can customize the `brand`-color to a automatically generated shade
based on the color `#2fd077`:

```css
@import 'tailwindcss';

/* The color shades from 50 to 950 are automatically generated */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette--brand: "#2fd077";
}
```

This is _roughtly_ equivalent to the following configuration:

```css
@import 'tailwindcss';

/* The color shades from 50 to 950 are automatically generated */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette--brand: "#ecfbf3", "#c6f2da", "#a0eac1", "#7be1a9", "#55d990", "#2fd077", "#26aa62", "#1e844c", "#155f36", "#0d3921", "#04130b";
}
```

For more information on that read the section [Customize a color](#customize-a-color).

## 3. Customization

TailwindCSS Semantic Palette is build to support a wide range of customization options:

Skip to the desired content:

* [Select a subset of colors](#select-a-subset-of-colors)
* [Customize a color](#customize-a-color)
* [Select a subset of colors and customize colors](#select-a-subset-of-colors)
* [Use custom colors exclusively](#use-custom-colors-exclusively)
* [Add custom colors to a selected subset of colors](#add-custom-colors-to-a-selected-subset-of-colors)
* [Add custom colors to all default colors](#add-custom-colors-to-all-default-colors)

### Select a subset of colors

To select only a subset of colors to add to the palette, one can use the `semantic-palette` option.
The `semantic-palette` option allows selecting a subset of colors.

Selecting a subset of colors is useful to control and limit the set of colors that gets added to the project.
For example, a user only needs to add the colors `primary` and `brand` to the palette.

The following code demonstrates how the user is able to select a subset of colors:

```css
@import 'tailwindcss';

/* Only extend the palette with the default colors for 'primary' and 'brand'. */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette: primary, brand;
}
```

This yields the following result:

![A subset of colors](docs/images/subset_of_colors.png)

### Customize a color

To customize a color of the palette, one can use the `semantic-palette--<color_name>` options.
The `semantic-palette--<color_name>` option allows setting the color shades of a specific color.

Customizing a color is useful to apply the proper styling and branding to a project.
For example, a user wants to set the color `primary` to `rose`.

The following code demonstrates how the user is able to set the color `primary` to `rose`:

```css
@import 'tailwindcss';

/* Extends the palette with all the default colors but set a custom primary color */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette--primary: "var(--color-rose-*)";
}
```

This yields the following result:

![Customize primary](docs/images/customize_primary.png)

Alternatively, one can either define an array of colors to specify the exact colors
or specify a single color and generate the shades automatically.

This array must contain exactly 11 items since TailwindCSS has 11 shades for each color
`(50, 100, 200, ..., 800, 900, 950)`.

For example, a user wants to set the exact `brand` color.

The following code demonstrates how the user is able to set the color `brand` to its exact color:

```css
@import 'tailwindcss';

/* Extends the palette with all the default colors but set a custom brand color */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette--brand: "#ecfbf3", "#c6f2da", "#a0eac1", "#7be1a9", "#55d990", "#2fd077", "#26aa62", "#1e844c", "#155f36", "#0d3921", "#04130b";
}
```

This yields the following result:

![Customize palette](docs/images/customize_brand.png)

Alternatively, one can specify a single color and let the shades get generated automatically
like in the following example:

```css
@import 'tailwindcss';

/* Extends the palette with all the default colors but set a custom brand color */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette--brand: "#2fd077";
}
```

### Select a subset of colors and customize colors

To select a subset of colors while customizing the colors one can use the `semantic-palette` option
whiles also using the `semantic-palette--<color_name>` options.

Selecting a subset of colors whiles customizing colors is useful to control, limit, and customize the set of colors
that gets added to the project.
For example, a user only needs to add the colors `primary` and `brand` to the palette
whiles also setting a custom `brand`-color.

The following code demonstrates how the user is able to select a subset of colors
whiles also customizing the `brand`-color:

```css
@import 'tailwindcss';

/* Only extend the palette with 'primary', 'brand', and 'warning' and customize the color 'brand'. */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette: primary, brand, warning;
    semantic-palette--brand: "#2fd077";
}
```

### Use custom colors exclusively

The select custom colors exclusively one can use the `semantic-palette` option and set custom color names
that later get specified using the `semantic-palette--<color_name>` options.

Using custom colors exclusively is useful if the project requires very specific colors
while not needing the default colors provided by the plugin.
For example one could develop a kanban-board that requires shades for the colors `to-do`, `in-progress`, and `done`.

The following code demonstrated how the user is able to use custom colors exclusively:

```css
@import 'tailwindcss';

/* Only extend the palette with the custom colors 'to-do', 'in-progress', and 'done' */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette: to-do, in-progress, done;
    semantic-palette--to-do: "#2fd077";
    semantic-palette--in-progress: "var(--color-sky-*)";
    semantic-palette--done: "hsl(260, 13%, 95%)", "hsl(262, 11%, 86%)", "hsl(260, 10%, 77%)", "hsl(260, 11%, 68%)", "hsl(261, 11%, 59%)", "hsl(261, 11%, 50%)", "hsl(261, 11%, 41%)", "hsl(263, 11%, 32%)", "hsl(263, 11%, 23%)", "hsl(263, 11%, 14%)", "hsl(260, 13%, 5%)"
}
```

### Add custom colors to a selected subset of colors

```css
@import 'tailwindcss';

/* Extend the palette with colors for 'success' and 'error'
   as well as the custom colors 'to-do', 'in-progress', and 'done' */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette: success, error, to-do, in-progress, done;
    semantic-palette--to-do: "#ecfbf3", "#c6f2da", "#a0eac1", "#7be1a9", "#55d990", "#2fd077", "#26aa62", "#1e844c", "#155f36", "#0d3921", "#04130b";
    semantic-palette--in-progress: "var(--color-sky-*)";
    semantic-palette--done: "hsl(260, 13%, 95%)", "hsl(262, 11%, 86%)", "hsl(260, 10%, 77%)", "hsl(260, 11%, 68%)", "hsl(261, 11%, 59%)", "hsl(261, 11%, 50%)", "hsl(261, 11%, 41%)", "hsl(263, 11%, 32%)", "hsl(263, 11%, 23%)", "hsl(263, 11%, 14%)", "hsl(260, 13%, 5%)"
}
```

### Add custom colors to all default colors

```css
@import 'tailwindcss';

/* Extends the palette with all the default colors
   as well as the custom colors 'to-do', 'in-progress', and 'done' */
@plugin '@IlijazM/tailwindcss-semantic-palette' {
    semantic-palette: "*", to-do, in-progress, done;
    semantic-palette--to-do: "#ecfbf3", "#c6f2da", "#a0eac1", "#7be1a9", "#55d990", "#2fd077", "#26aa62", "#1e844c", "#155f36", "#0d3921", "#04130b";
    semantic-palette--in-progress: "var(--color-sky-*)";
    semantic-palette--done: "hsl(260, 13%, 95%)", "hsl(262, 11%, 86%)", "hsl(260, 10%, 77%)", "hsl(260, 11%, 68%)", "hsl(261, 11%, 59%)", "hsl(261, 11%, 50%)", "hsl(261, 11%, 41%)", "hsl(263, 11%, 32%)", "hsl(263, 11%, 23%)", "hsl(263, 11%, 14%)", "hsl(260, 13%, 5%)"
}
```

## 4. Contributions

Contributions are welcome! Please feel free to submit a Pull Request.

### Build project

1. Install dependencies with `npm install`
1. Run `npm run build`
1. Result is in the `dist/` directory

### Run example

1. Go into the directory `example/`
1. Install dependencies with npm `install`
1. Run development build with `npm run dev`
1. Check the example via `http://localhost:5173/`

## 5. Further information

### Dependencies

```
.
├── 📦 culori
└── 📦 tailwindcss
```

### License

[MIT](../LICENSE)