How to use semantic color names with specific namespaces

[idenyigabriel]

I am currently working with the new tailwind v4, and trying to implement some custom colours specific to a theme variable namespace and can't seem to find my way around this using the v4 configuration.

Essentially, I'd like to replicate something like this in tailwind v4. Please note that the code below is not an actual working code but just meant to convey my intended use.

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class', // or 'media' if you prefer OS-level dark mode
  theme: {
    extend: {
      colors: {
        // Default (Light) Mode Colors
        text: {
          default: '#374151', // Gray-700
          muted: '#6b7280',   // Gray-500
          subtle: '#9ca3af',  // Gray-400
          strong: '#111827',  // Gray-900
        },
        background: {
          default: '#f9fafb', // Gray-50
          secondary: '#f3f4f6', // Gray-100
        },
        border: {
          default: '#d1d5db', // Gray-300
          muted: '#e5e7eb',   // Gray-200
          strong: '#9ca3af',  // Gray-400
        },
        primary: {
          default: '#3b82f6', // Blue-500
          muted: '#60a5fa',   // Blue-400
          strong: '#2563eb',  // Blue-600
          subtle: '#eff6ff',  // Blue-50
        },
        secondary: {
          default: '#8b5cf6', // Purple-500
          muted: '#a78bfa',  // Purple-400
          strong: '#6d28d9', // Purple-600
          subtle: '#f3e8ff', // Purple-50
        },

        // Dark Mode Colors (using the dark: prefix)
        dark: {
          text: {
            default: '#f3f4f6', // Gray-100
            muted: '#d1d5db',   // Gray-300
            subtle: '#9ca3af',  // Gray-400
            strong: '#ffffff',  // White
          },
          background: {
            default: '#1f2937', // Gray-800
            secondary: '#374151', // Gray-700
          },
          border: {
            default: '#4b5563', // Gray-600
            muted: '#374151',   // Gray-700
            strong: '#d1d5db',  // Gray-300
          },
          primary: {
            default: '#60a5fa', // Blue-400
            muted: '#3b82f6',   // Blue-500
            strong: '#a5f3fc',  // Cyan-200
            subtle: '#1e3a8a',  // Blue-900
          },
          secondary: {
            default: '#a78bfa', // Purple-400
            muted: '#8b5cf6',  // Purple-500
            strong: '#e0f2fe', // Sky-100
            subtle: '#4c1d95', // Purple-900
          },
        },

        // Red Mode Colors (using a custom 'red' class prefix)
        red: {
          text: {
            default: '#ef4444', // Red-500
            muted: '#fca5a5',   // Red-400
            subtle: '#fecaca',  // Red-300
            strong: '#b91c1c',  // Red-700
          },
          background: {
            default: '#fee2e2', // Red-100
            secondary: '#fecaca', // Red-300
          },
          border: {
            default: '#f56565', // Red-400
            muted: '#fca5a5',   // Red-400
            strong: '#ef4444',  // Red-500
          },
          primary: { // You might redefine primary for the red mode
            default: '#dc2626', // Red-600
            muted: '#e11d48',   // Rose-600
            strong: '#991b1b',  // Red-800
            subtle: '#fee2e2',  // Red-100
          },
          secondary: { // And potentially secondary
            default: '#e11d48', // Rose-600
            muted: '#f43f5e',   // Rose-500
            strong: '#be123c',  // Rose-700
            subtle: '#ffe4e6',  // Rose-50
          },
        },
      },
    },
  },
  plugins: [],
}

The intended result is to be able to use utility classes like text-muted, bg-primary, border-subtle configured specifically for each namespace, as well being able to use modifiers on them, across the different modes eg: light, dark, etc.

[wongjn]

Use the utility-specific namespaces like to have semantic colors:

@theme {
  --text-color-default: …;
  --background-color-default: …;
  --border-color-default: …;
}

Use standard CSS rules per each "theme":

@theme {
  …
}

@layer theme {
  @media (prefers-color-scheme: dark) {
    :root {
      --text-color-default: …;
      --background-color-default: …;
      --border-color-default: …;
    }
  }

  .red {
    --text-color-default: …;
    --background-color-default: …;
    --border-color-default: …;
  }
}

[idenyigabriel]

This was really helpful, thank you!