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.

Table of content

1. Installation
2. Features
3. Customization
4. Contributions
5. Further information

1. Installation

To install the TailwindCSS Semantic Palette follow the following steps:

1. Install the TailwindCSS Semantic Palette dependency:

npm install @ilijazm/tailwindcss-semantic-palette

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

@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

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:

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

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

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
• Customize a color
• Select a subset of colors and customize colors
• Use custom colors exclusively
• Add custom colors to a selected subset of 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:

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

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:

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

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:

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

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

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

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

@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

@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

@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
2. Run npm run build
3. Result is in the dist/ directory

Run example

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

5. Further information

Dependencies

.
├── 📦 culori
└── 📦 tailwindcss

License

MIT