Tailwind color tokens that actually scale past one project

1. The problem with raw palette classes

Using bg-blue-600 directly in components works fine until the client wants to change the brand color to teal. Then you're doing a find-and-replace across 80 files.

• Raw palette classes couple your components to a specific hue.
• Changing brand color becomes a multi-hour refactor instead of a config edit.
• Dark mode requires duplicating every color decision.

2. Setting up semantic tokens in tailwind.config.js

The fix is a thin semantic layer in your Tailwind config that maps role names to actual palette values.

• Add colors like accent, surface, muted, border to the theme.extend.colors object.
• Point each token to a CSS variable so you can swap themes at runtime.
• Use the Export Code button on any palette to get a ready-to-paste config.

3. The dark mode payoff

Once your components use semantic tokens, dark mode is just a CSS variable swap — no Tailwind dark: prefix needed on every class.

• Define light and dark values for each token in your CSS.
• Toggle a class on the root element to switch themes.
• Components stay clean — no dark:bg-slate-900 scattered everywhere.

Common mistakes

• Using bg-blue-600 directly in shared components.
• Creating semantic tokens but still using raw values in half the codebase.
• Forgetting to add focus-ring and border tokens to the semantic layer.

Before you ship

• Add accent, surface, muted, border, and text tokens to tailwind.config.js.
• Replace all raw palette classes in shared components.
• Test the token swap by changing one hex value and checking the whole UI.
• Document the token names in the project README.