v4: prefix BlazorBlueprint's Tailwind utilities to stop cross-build class collisions

[mathewtaylor]

Plan: docs/plans/2026-08-28-v4-tailwind-prefix.md in the internal devkit repo (not this one).

Fixes #496. Breaking — targets a v4 major.

The fault

BB ships a prebuilt Tailwind stylesheet. A consumer running their own Tailwind build ends up with two stylesheets writing into the same utilities cascade layer. Tailwind gives md:grid-cols-4 priority over sm:grid-cols-2 by sort order within a single build, not by specificity — both are one class. Across two builds that ordering is gone, and priority at the join is decided by which <link> came second.

Both directions break, which is why no ordering fixes it:

• BB second — a consumer's sm:grid-cols-2 md:grid-cols-4 collapses, because BB re-emits sm:grid-cols-2 later in the document.
• BB first — BB's own hidden sm:flex pagination collapses, because the consumer emits hidden later.

This reproduces in our own demo today: demos/BlazorBlueprint.Demo.Server/App.razor:9-11 loads app.css then blazorblueprint.css.

The fix

Prefix BB's utilities so the two builds cannot produce the same class name, and give them their own cascade layer. Verified against tailwindcss v4.3.0:

@layer bb-theme, bb-base, bb-components, bb-utilities, utilities, bb;
@import 'tailwindcss/theme.css'     layer(bb-theme)     prefix(bb);
@import 'tailwindcss/preflight.css' layer(bb-base);
@import 'tailwindcss/utilities.css' layer(bb-utilities) prefix(bb);

Emits .bb\:hidden, .bb\:sm\:flex. Consumer Class="..." values stay unprefixed and are unaffected.

Scope

• 966 class="…" strings in Components .razor, 17 in Primitives, 119 .cs files building class strings.
• The rewrite is mechanical: the current build emits 933 distinct utility tokens, and that set is the exact allowlist. Verification is a diff of the built CSS — every utility selector gains bb\: and nothing else changes.
• ClassNames.cn() needs a decision: consumer overrides currently win by string merge, and TailwindMerge keeps both when only one side is prefixed. See step 4 of the plan.
• The demo's @source on library sources must go; the demo should be a real consumer.

Ordering

#490 must land first. It touches 299 files and would conflict badly with a mechanical class rewrite.

Also worth batching into the same major: #428.

[mathewtaylor]

Branch note. Breaking work is now collected on the v4 branch, cut from develop at ff4c65d1. develop stays non-breaking and releasable as a minor.

On v4 so far:

• BbDrawerTrigger and BbDrawerClose are a bare div with @onclick — no button, no tabindex, no AsChild branch #507 — BbDrawerTrigger / BbDrawerClose render a real <button>. Merged in fix(a11y)!: BbDrawerTrigger and BbDrawerClose render a real button (BREAKING) #513, then reverted from develop in revert: move the breaking Drawer trigger change (#507) off develop to v4 #514; the change lives on v4.

Still to do there:

• Next major: flip BbTooltipTrigger AsChild default to false #428 — flip BbTooltipTrigger.AsChild to false.
• v4: prefix BlazorBlueprint's Tailwind utilities to stop cross-build class collisions #501 — prefix every Tailwind utility with bb:. Do this last — it rewrites around 1,100 class strings and will conflict with anything else in flight.

[mathewtaylor]

Done on the v4 branch in #532.

Every utility in blazorblueprint.css is now bb:-prefixed and lives in its own bb-utilities cascade layer, so a consumer's Tailwind build can never emit the same class name. ClassNames.cn strips the prefix for the merge, so Class="p-6" still replaces the library's bb:p-4 and load order no longer matters. New convention tests guard both the built stylesheet and the sources.

Consumer notes are in V4-MIGRATION-GUIDE.md: drop any @source pointing at the library; shimmer / scroll-fade-x are now bb:shimmer / bb:scroll-fade-x. #496 stays open until v4 ships.