Tailwind 4 support for consuming apps - core-components ships a Tailwind-3-only plugin

[bernie-nyc]

Description

Apps that embed @evidence-dev/core-components in their own build (not the Evidence
app framework) currently can't move to Tailwind CSS 4. core-components@5.4.2
depends on @evidence-dev/tailwind@3.1.4, which is built on the Tailwind 3 JS-plugin
model (config-file plugins: [...], tw-colors, tailwindcss@3.4.18). Tailwind 4 is
CSS-first and compiles each imported CSS module in isolation, which surfaces two hard
incompatibilities in Evidence's published dist. Both are fixable without changing
any Evidence runtime behavior.

I've built a working, dependency-free compatibility bridge for our own app and would like
to contribute it (or the equivalent) upstream. Details and a reference implementation below.

Environment

• @evidence-dev/core-components@5.4.2 (latest release)
• @evidence-dev/tailwind@3.1.4 → tailwindcss@3.4.18, tw-colors@^3.3.2
• Consuming app: Vite + React SPA importing Evidence's Svelte components, on
  tailwindcss@^4.3.3 + @tailwindcss/vite

What problem would this solve?

Under Tailwind 4 the app build fails, and even if it didn't, Evidence's colors wouldn't
render. Two distinct causes:

1. Raw @apply in compiled CSS modules → hard build failure

Two stylesheets shipped in dist use bare @apply with Evidence utilities and Tailwind
built-ins:

• dist/unsorted/ui/QueryViewerSupport/prismtheme.css - @apply font-mono;,
  @apply text-base-content-muted;
• dist/organisms/layout/header/SearchButton.css - @apply bg-base-100 border-base-300 hover:bg-base-200/40 … font-sans …;, @apply text-base-content-muted;

They're imported directly by components (e.g. Prismjs.svelte does import './prismtheme.css'). Tailwind 3 processed the whole tree in one PostCSS pass, so these
resolved. Tailwind 4 compiles each imported CSS module in isolation and can't see the
utility/theme surface, so the build dies with:

Cannot apply unknown utility class `font-mono`. Are you using CSS modules or
similar and missing `@reference`?
  file: …/@evidence-dev/core-components/dist/unsorted/ui/QueryViewerSupport/prismtheme.css

Tailwind 4's fix for this pattern is an @reference directive at the top of such modules.

2. Compiled CSS references --twc-* variables that only Evidence's TW3 plugin defines

Evidence's compiled CSS reads tw-colors channel variables directly, e.g. in
Modal.svelte:

dialog::backdrop { background-color: hsl(var(--twc-base-100) / 0.8); }

and throughout dist in the Tailwind-3 opacity-fallback form:

background-color: hsl(var(--twc-base-100) / var(--twc-base-100-opacity, var(--tw-bg-opacity)));
color:            hsl(var(--twc-base-content) / var(--twc-base-content-opacity, var(--tw-text-opacity)));

These --twc-<token> variables (and the --tw-*-opacity defaults the fallbacks lean on)
are emitted at Evidence's own build time by @evidence-dev/tailwind's
createThemes (tw-colors) + createVarsForColors plugins. A consuming app on Tailwind
4 doesn't run those plugins, so the variables are undefined and every Evidence surface
that uses them renders transparent/incorrect.

How should it work?

Proposed solution

Ship a Tailwind 4 path alongside the existing Tailwind 3 one, mirroring how
@evidence-dev/tailwind is already structured (it already exports a ./vite-plugin):

1. A TW4 preset (@theme CSS) reproducing Evidence's color/theme surface:

• --color-<token> entries so bg-*/text-*/border-* utilities exist, routed through
  --twc-<token> channels so they theme-switch;
• the --twc-<token> "H S% L%" channel values per theme (the exact output of
  resolveTwcConfig/createVarsForColors), bound to :root/[data-theme=…];
• [data-theme="dark"] as an @custom-variant;
• the Inter/Spectral font stacks;
• --tw-*-opacity: 1 defaults so the compiled TW3 opacity fallbacks resolve;
• an @source inline(...) safelist over the token surface.

2. A Vite plugin that injects @reference into Evidence's raw-@apply dist CSS
   modules (the prismtheme.css / SearchButton.css class above) - the same shape as the
   existing @evidence-dev/tailwind/vite-plugin.

Because the --twc-* values are derivable from Evidence's existing theme pipeline
(buildThemes → resolveTwcConfig), the preset can be generated from a user's
evidence.config rather than hardcoded, so custom themes keep working.

Reference implementation

I built exactly this as a standalone package (evidence-tailwind4) with zero coupling to
our host app, specifically so it can lift upstream:

• preset.css - @theme routed through --twc-*, per-theme channel values generated from
  Evidence's default theme, dark @custom-variant, fonts, --tw-*-opacity defaults, safelist.
• vite-plugin.js - injects @reference "tailwindcss" + the preset into Evidence's
  @apply CSS modules (enforce: 'pre', so it runs before @tailwindcss/vite).
• Tests compile the preset with the real Tailwind 4 CLI and assert the token surface, the
  dark variant, --twc-* routing, and both-theme channels.

Verification: full production build green; real-browser computed styles show Evidence's
exact default palette in light and dark, with both app utilities and Evidence's baked
hsl(var(--twc-*) / a) references switching on [data-theme]
(e.g. bg-primary → #2563eb light / #3b82f6 dark; bg-base-100 → white / rgb(9,9,11)).

Questions for maintainers

1. Would you accept this as a ./tailwind4 / ./preset.css + ./vite-plugin export on
   @evidence-dev/tailwind (guarded so the TW3 path is untouched), or as a separate package?
2. Preference on the preset being generated from evidence.config at build time vs.
   shipped static + overridable? (I lean generated, reusing resolveTwcConfig.)
3. Any appetite for making the two dist stylesheets self-referencing (adding @reference
   at Evidence's build time) so the Vite plugin becomes unnecessary for the @apply case?

Happy to open a PR against whichever shape you prefer.