🧬 tailwind-semantic-setup

Smart multi-theme tool for better semantic Design Systems

🚀 Features

✅ Multiple themes support
🔥 Auto-generate darker and contrast colors (better readability)
📦 All official tailwind plugins included by default
🚀 Custom addons to make your life easier:
- theme name variants to set classes only for a specific theme
- wh utility to set width and height at the same time
- circle to set same width and height with border-radius
- hocus to set hover and focus at the same time
- ...

📦 Installation

# NPM
npm install -D tailwind-semantic-setup

# PNPM
pnpm add -D tailwind-semantic-setup

💻 Usage example

🟣 1. Wrap your tailwind config and set your themes

In your tailwind config file, wrap your tailwind config with the withSemanticSetup function.
With the semanticSetup property you can setup your themes to be handled automatically.

// tailwind.config.js
const { withSemanticSetup } = require('tailwind-semantic-setup')

module.exports = withSemanticSetup({
  /* ... your tailwind config */
  semanticSetup: {
    themes: [
      {
        name: 'my-brand',
        colors: {
          primary: '#e0a82e',
          secondary: '#f9d72f',
          accent: '#00ffff',
          neutral: '#181830',
          root: '#ffffff',
        },
      },
      // ... other themes
    ],
  },
})

🟣 2. Add the `data-theme` attribute to your html code

You can put it where you want, but it's recommended to put it in the html tag to make it global accessible for the entire application.

<html data-theme="my-brand">
  <!-- ... -->
</html>

🟣 3. Use the theme classes

<div class="bg-primary text-primary-content">
  <!-- ... -->
</div>

📖 Documentation

🎨 Themes

You can define multiple themes in the semanticSetup property of your tailwind config.
Each theme must have a name and a colors object.

// tailwind.config.js
const { withSemanticSetup } = require('tailwind-semantic-setup')

module.exports = withSemanticSetup({
  // ... your tailwind config
  semanticSetup: {
    themes: [
      {
        name: 'my-brand',
        preferredColorScheme: ['dark', 'light'],
        colors: {
          primary: '#e0a82e',
          secondary: '#f9d72f',
          accent: '#00ffff',
          neutral: '#181830',
          root: '#ffffff',
        },
      },
      // ... other themes
    ],
  },
})

🟠 `name` (required)

The name of the theme. It will be used to generate the classes and the data-theme attribute value.

🟠 `preferredColorScheme` (optional)

You can set your preferences for the color scheme to be used in the user's browser. It will set color-scheme css property

🟠 `colors` (required)

Semantic Setup provides you a semantic default setup but you can add your custom colors.

Here you can see the default colors and the ones that are auto-generated for you:

(Required - added by default)

▪️ primary: The main color of your brand
▪️ secondary: The secondary color of your brand
▪️ accent: Color to have high color contrasts and highlight.
▪️ neutral: The neutral color of your brand
▪️ root: The base color of your brand (background color)

▪️ info: The info color of your brand
▪️ warning: The warning color of your brand
▪️ error: The error color of your brand

(Optional - auto-generated for Required colors)

(colorName)-dark: The darker version of the (colorName) color (i.e. primary-dark)
(colorName)-content: The readable color to use for text and icons on top of the (colorName) color (i.e. primary-content)
root-darkest (just for base color): The darkest version of the root color

This approach allows you to have a consistent color palette for your brand with different themes in a very simple way.

The default colors approach is mainly based on daisyui colors palette but adding some other nice features to make it more customizable/extendable for your brand.

🔌 Default Plugins activate / deactivate

By default, all official tailwind plugins are activated.
You can deactivate them individually using the plugins property of the semanticSetup object in your tailwind config file.

Here you can see the default plugins configuration:

// tailwind.config.js
const { withSemanticSetup } = require('tailwind-semantic-setup')

module.exports = withSemanticSetup({
  // ... your tailwind config
  semanticSetup: {
    plugins: {
      // @tailwindcss/typography
      'typography': true,
      // @tailwindcss/forms
      'forms': true,
      // @tailwindcss/line-clamp
      // Deactivated by default because it's part of tailwindcss v3.3.0
      'line-clamp': false,
      // @tailwindcss/aspect-ratio
      'aspect-ratio': true,
    },
  },
})

🚀 Custom Addons

🟠 `theme name variants`

You can set classes only for a specific theme using the theme name variants.
The variant has the following format: theme-(your-theme-name):class

<div class="p-4 theme-my-brand:p-8">
  <!-- ... -->
</div>

🟠 `wh`

You can set width and height at the same time.

<div class="wh-10">
  <!-- ... -->
</div>

🟠 `circle`

You can set a circle shape setting same width and height.

<div class="circle-8">
  <!-- ... -->
</div>

🟠 `hocus`

You can set a hover and focus state using the hocus utility.

<div class="bg-primary hocus:bg-primary-dark">
  <!-- ... -->
</div>

Created with JavaScript! ⚡ and latin music 🎺🎵