[v4] `__unstable__loadDesignSystem` `candidatesToCss` can not get correct result

[hyoban]

What version of Tailwind CSS are you using?

4.0.0-alpha.5

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

vite 5.1.5, @tailwindcss/vite 4.0.0-alpha.5

What version of Node.js are you using?

v20.11.1

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://github.com/hyoban-repro/tailwindcss-compile-candidates

Describe your issue

I want to use candidatesToCss to get the corresponding output for className.

import { __unstable__loadDesignSystem } from 'tailwindcss';

const css = `
@import "tailwindcss";

@theme {
  --font-family-display: "Satoshi", "sans-serif";

  --breakpoint-3xl: 1920px;

  --color-neon-pink: oklch(71.7% 0.25 360);
  --color-neon-lime: oklch(91.5% 0.258 129);
  --color-neon-cyan: oklch(91.3% 0.139 195.8);
}
`
const designSystem = __unstable__loadDesignSystem(css)

console.log(designSystem.candidatesToCss([
  'max-w-lg',
  '3xl:max-w-xl',
  'font-display',
  'text-4xl',
  'text-neon-cyan'
]))

All of this should be valid className, but the output is:

[
  null,
  null,
  '.font-display {\n  font-family: "Satoshi", "sans-serif";\n}\n',
  null,
  '.text-neon-cyan {\n  color: oklch(91.3% 0.139 195.8);\n}\n'
]

[thecrypticace]

I'm going first warn you that this is 100,000% subject to change — hence the __unstable__ prefix.

The results you are getting are correct because:

1. __unstable__loadDesignSystem does NOT handle imports by design. The aim is to do zero I/O in the core tailwindcss package.
2. There is no 4xl breakpoint so you'd need to also add that to your theme.

The solution here is to use either:

• Use postcss-import to process the CSS beforehand. This is what we do in intellisense and in our Prettier plugin (as we already have to use PostCSS for some other things so it makes sense to go ahead and use it).
• Read the default theme directly fs.readFileSync(require.resolve('tailwindcss/theme.css')) and prepend it to the CSS you're passing in. Multiple @theme calls are supported and will be merged.

Again, I want to stress that this is an experimental API and everything under __unstable__loadDesignSystem is subject to change or removal.

[hyoban]

Thanks a lot for your reply.