Tailwind Config for Design System Libraries

Tailwind for Design Systems

When building a design system library, your Tailwind config becomes the single source of truth for all design tokens.

Design Token Architecture

// tokens.js
module.exports = {
  colors: {
    primary: { 50: "#eff6ff", 500: "#3b82f6", 900: "#1e3a8a" },
    neutral: { 50: "#fafafa", 500: "#a3a3a3", 900: "#171717" },
    success: { DEFAULT: "#22c55e", light: "#dcfce7" },
    danger:  { DEFAULT: "#ef4444", light: "#fee2e2" },
  },
  spacing: {
    xs: "0.25rem", sm: "0.5rem", md: "1rem",
    lg: "1.5rem", xl: "2rem", "2xl": "3rem",
  },
  borderRadius: {
    sm: "0.25rem", md: "0.375rem", lg: "0.5rem", full: "9999px",
  },
};

Using Tokens in Config

const tokens = require("./tokens");

module.exports = {
  theme: {
    colors: tokens.colors,
    spacing: tokens.spacing,
    borderRadius: tokens.borderRadius,
    extend: {
      // App-specific extensions here
    },
  },
};

CSS Variable Bridge

For runtime theming (e.g., multiple brands):

colors: {
  primary: "hsl(var(--color-primary) / <alpha-value>)",
  surface: "hsl(var(--color-surface) / <alpha-value>)",
}

Then define variables per brand:

[data-brand="acme"]  { --color-primary: 221 83% 53%; }
[data-brand="globex"] { --color-primary: 142 71% 45%; }

Strict Mode

Override (not extend) to enforce only approved tokens:

theme: {
  colors: tokens.colors,    // Only these colors
  spacing: tokens.spacing,  // Only this spacing
  // No extend section
}

Distribution

Export your config as an npm package and use it as a Tailwind preset in consuming applications.