Mapping complex design systems to tailwind utilities broken in v4 CSS config DSL

[non25]

What version of Tailwind CSS are you using?

v4.1.12

What build tool (or framework if it abstracts the build tool) are you using?

For example: postcss: v8.5.6, postcss-loader v8.1.1

What version of Node.js are you using?

v22.19.0

What browser are you using?

Firefox v142.0.1, Chromium v139.0.7258.154

What operating system are you using?

Arch Linux

https://gist.github.com/non25/6e1ddd3d4667aac9c4511d1be7db38ba

Describe your issue

Since the introduction of the new CSS DSL configuration syntax in Tailwind v4, I've found it extremely difficult—if not impossible—to maintain a mapping between a complex, domain/purpose-focused design system and Tailwind's utility classes in a clean, maintainable way.

My use case involves:

• A color system with semantic/grouped tokens that should map only to a specific subset of Tailwind's domains (for example, only background-color or text-color depending on their semantic intent).
• A spacing system (with its own design tokens) that needs to be mapped predictably and consistently across related Tailwind utilities (like padding, gap, size, etc.).

The new configuration approach doesn't provide a clean way to express these mappings directly. To achieve the necessary mappings, I have to generate the Tailwind config using a custom code-generation script, which is both ugly and hard to maintain. I'm forced to essentially re-implement or reverse-engineer how Tailwind generates spacing and utility classes, which feels fragile and not in the intended spirit of the framework.

Steps to Reproduce:

1. Attempt to map a complex design system (with domain-focused color and spacing tokens) to Tailwind utility domains using only the new CSS DSL config syntax.
2. Notice that there is no first-class way to control or limit how each design token maps to only certain Tailwind utility domains or property groups (e.g., ensuring a color token appears only as a background, not a border, or mapping spacing tokens only to padding/gap).
3. As a workaround, generate the config with your own code, essentially duplicating the logic that Tailwind itself uses internally.

Expected Behavior:
I'd expect to be able to use Tailwind's config and generator in a "semantic" or "domain-aware" manner, mapping complex design system tokens to only the relevant utility groups, while still taking full advantage of Tailwind's underlying generator and conventions—without having to write custom code-generation tooling. This would make working with complex/enterprise-level design systems much more maintainable and would reinforce Tailwind's place as a flexible foundation for modern web UI work.

[wongjn]

2. Notice that there is no first-class way to control or limit how each design token maps to only certain Tailwind utility domains or property groups (e.g., ensuring a color token appears only as a background, not a border, or mapping spacing tokens only to padding/gap).

There is a first-class way to control or limit how each design token maps to only certain Tailwind utility domains or property groups. Use the appropriate specific namespace in @theme:

Utility set	Namespace
bg-<color>	--background-color
border-<color>	--border-color
p-<length> et al.	--padding
gap-<length> et al.	--gap

[non25]

That's not maintainable still, I don't know why you so hastily converted this to a discussion, consider re-opening it as an issue.

I'll still need to write by hand or through js code generation:

• text, fill and stroke for each fg / content color
• border, outline and ring for each border color
• basis, w, min-w, max-w, h, min-h, max-h, size, translate for each size token
• margin, padding, inset, border-spacing, scroll-margin, scroll-padding for each padding token

Yeah, that's a little better than generating mx, my, mt, mb, ml, mr, with code generation, but not a lot.

[wongjn]

I don't know why you so hastily converted this to a discussion, consider re-opening it as an issue.

At least from your description of your problem, it doesn't sound like there is any sort of bug with how Tailwind works. Rather, that Tailwind doesn't fit your workflow as nicely as you'd like it to. We use issues to track bugs, hence why I converted your issue into a discussion.

For those other properties, you can check the code for other specific namespaces. You could also consider using the legacy JavaScript configuration API, which uses the v3 configuration shape.

[non25]

I want to clarify why this is an important issue for people who maintain larger or more complex design systems:

Shouldn’t the new configuration API be at least as expressive and flexible as the legacy JS config? If the plan is to deprecate/remove the JS config entirely (as you mention suggesting the “legacy” v3 API), teams that rely on dynamic mapping and maintainable code-driven config will be left without any viable path forward.

• Has the team considered these edge cases in the new configuration API design?
• Is there an intention to achieve feature and expressiveness parity with the legacy JS config, or is this a deliberate move away from configurable/programmable mapping?
• How should users who need programmable mapping and restricted domain usage for tokens expect to manage this going forward?

Tailwind has become the de-facto CSS framework, even being the default output of tools like Figma MCP. It’s important that power users and teams with mature design systems can continue to use Tailwind effectively and maintainably—without fragile or hacky workarounds.

Could the team share their thinking here? Is there openness to making the new config syntax as flexible as the legacy JS approach for these types of advanced use cases?

[non25]

Here's my attempt for 3 spacing/sizing variables and for one color.
Is this this the best way for this problem to be solved with CSS config DSL or I'm missing something?

[adamwathan]

Can you share what you were doing in v3? Generally what you shared here is about what I would expect if you need to completely override all of the defaults and want the ability to assign different values to different utilities using the same name.

Could the team share their thinking here?

The thinking is always just making the framework I personally enjoy using and if others like it as well then cool, if not then free to fork and customize for their own needs, or pretend it never existed and write everything themselves like they otherwise would have.