Add support for prefixes

[thecrypticace]

This PR adds support for requiring a custom prefix on utility classes.

Prefixes work a bit differently in v4 than they did in v3:

• They look like a custom variant: tw:bg-white
• It is always first in a utility — even before other variants: tw:hover:bg-white
• It is required on all utility classes — even arbitrary properties: tw:[color:red]
• Prefixes also apply to generated CSS variables which will be separated by a dash: --tw-color-white: #fff;
• Only alpha (a-z) characters are allowed in a prefix — so no #tw# or __ or similar prefixes are allowed

To configure a prefix you can use add prefix(tw) to your theme or when importing Tailwind CSS like so:

/* when importing `tailwindcss` */
@import 'tailwindcss' prefix(tw);

/* when importing the theme separately */
@import 'tailwindcss/theme' prefix(tw);

/* or when using an entirely custom theme */
@theme prefix(tw) {
  --color-white: #fff;
  --breakpoint-sm: 640px;
  /* … */
}

This will configure Tailwind CSS to require a prefix on all utility classes when used in HTML:

<div class="tw:bg-white tw:p-4">
  This will have a white background and 4 units of padding.
</div>

<div class="bg-white p-4">
  This will not because the prefix is missing.
</div>

and when used in CSS via @apply:

.my-class {
  @apply tw:bg-white tw:p-4;
}

Additionally, the prefix will be added to the generated CSS variables. You do not need to prefix the variables in the @theme block yourself — Tailwind CSS handles this automatically.

:root {
  --tw-color-white: #fff;
  --tw-breakpoint-sm: 640px;
}

A prefix is not necessary when using the theme(…) function in your CSS or JS given that plugins will not know what the current prefix is and must work with or without a prefix:

.my-class {
  color: theme(--color-white);
}

However, because the variables themselves are prefixed when outputting the CSS, you do need to prefix the variables when using var(…) in your CSS:

.my-class {
  color: var(--tw-color-white);
}

If you want to customize the prefix itself change tw to something else:

/* my:underline, my:hover:bg-red-500, etc… */
@import 'tailwindcss' prefix(my);

[thecrypticace]

@RobinMalfait Should we switch to the new prefix syntax (where it is actually a prefix lol) in this PR and do the codemod later — or land the old prefix version and then switch to the new one when we land the codemod?

[RobinMalfait]

@thecrypticace since we didn't have prefix support before this in v4, I would say use the new syntax only and introduce a codemod later (@philipp-spiess is already making good progress on the infra for that).

Don't think it's worth / necessary to ship support for the old prefix. Because, if we have a codemod, then we would remove support for the old prefix again which makes it a breaking change (it's still alpha so it's fine, but still.)

[thecrypticace]

• Add one test to candidate.test for prefixes
• Make sure var(--…) is properly prefixed in generated utilities
• If config.prefix ends in dash we remove it and warn
• Make sure prefixes are validated — lowercase alpha characters only (a-z)

[philipp-spiess]

Looks good to me overall! One question that could need some clarification is what should the theme() function do when it does get a prefix fed into it, see the inline comment on the new test.

[RobinMalfait]

A bit annoying to configure, but I do like the new syntax for it. Can't wait for writing a codemod for this 😅