Document how to create custom utility classes and override them for different themes without confusion due to namespaces (Tailwind 4)

[gmoniava]

Imagine I want to have several custom utility classes - such as button-default-background or button-default-border - and also override them during dark mode (because I suppose this is one approach to create apps which support themes).

Now I could do it in following way based on tailwind 4 docs:

@custom-variant dark (&:where(.dark, .dark *));

@theme {
  --color-button-default-background: #eb6bd8;
}

@layer base {
 * {
   @variant dark {
     --color-button-default-background: #8e0d7a;
   }
 }
}

But it would generate utilities like bg-button-default-background and text-button-default-background right? However having value named: text-button-default-background seems a bit strange (usage of text and background in the same word) isn't it?

Current docs don't mention how to solve this problem.

In this discussion there was suggestion how to solve this, so can we put this information in the docs, if that's the best way to implement this using tailwind 4?