Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix: add cssMinify: false to all Vite configs to prevent light-dark() breakage (#623)

Cindy Zhangc99287c0ebf0
diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.md
index 25e08f9e2d..70f0480e55 100644
--- a/apps/example-nextjs/README.md
+++ b/apps/example-nextjs/README.md
@@ -127,6 +127,14 @@ export function Providers({children}) {
| No `'use client'` on theme provider | Server component error from `createContext` | Mark the provider file with `'use client'` |
| StyleX as preset instead of plugin | Build errors or missing styles | Use `plugins` array, not `presets`, for `@stylexjs/babel-plugin` |
+### ⚠️ CSS Minifiers and `light-dark()`
+
+XDS tokens use the native CSS `light-dark()` function for theming. If you use a CSS minifier that "lowers" modern CSS (such as LightningCSS), it will convert `light-dark()` into `--lightningcss-light` / `--lightningcss-dark` polyfill variables that are never initialized — silently breaking all colors.
+
+Next.js uses PostCSS for CSS processing (not LightningCSS), so this issue **does not apply** to the standard Next.js setup shown here. However, if you add a custom CSS minifier or use `next.config.mjs` experimental CSS features that invoke LightningCSS, you may encounter this. The safest approach is to avoid post-processing XDS-generated CSS through any tool that doesn't support native `light-dark()`.
+
+For Vite-based setups, see the [Vite example's README](../example-vite/) for the specific fix (`cssMinify: false`).
+
## Related
- [Issue #145 — Add example-nextjs project](https://github.com/facebookexperimental/xds/issues/145)
diff --git a/apps/example-vite/README.md b/apps/example-vite/README.md
index cc78e982b6..fbab0139e6 100644
--- a/apps/example-vite/README.md
+++ b/apps/example-vite/README.md
@@ -37,6 +37,10 @@ import stylex from '@stylexjs/unplugin';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
export default defineConfig({
+ build: {
+ // Prevent lightningcss from lowering light-dark() into broken polyfills
+ cssMinify: false,
+ },
plugins: [
stylex.vite({
dev: process.env.NODE_ENV === 'development',
@@ -109,12 +113,30 @@ npm run preview
## Gotchas
-| Issue | Symptom | Fix |
-| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
-| Missing resolve aliases | Module not found errors for `@xds/core` | Add `resolve.alias` pointing to source directory |
-| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |
-| Plugin order | Styles not extracted or HMR broken | `stylex.vite()` must come before `react()` in the plugins array |
-| Duplicate React types | JSX component type errors in monorepo | Known monorepo issue with `@types/react` hoisting; doesn't affect runtime |
+| Issue | Symptom | Fix |
+| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------- |
+| LightningCSS mangles light-dark | All colors invisible or broken theming | Add `build: { cssMinify: false }` — see below |
+| Missing resolve aliases | Module not found errors for `@xds/core` | Add `resolve.alias` pointing to source directory |
+| Missing CSS entry point | StyleX has no CSS asset to append to | Create a minimal `index.css` and import it in `main.tsx` |
+| Plugin order | Styles not extracted or HMR broken | `stylex.vite()` must come before `react()` in the plugins array |
+| Duplicate React types | JSX component type errors in monorepo | Known monorepo issue with `@types/react` hoisting; doesn't affect runtime |
+
+### ⚠️ LightningCSS and `light-dark()`
+
+XDS tokens use the native CSS `light-dark()` function for theming. Vite's default CSS minifier (LightningCSS) "lowers" `light-dark()` into `--lightningcss-light` / `--lightningcss-dark` polyfill variables. These polyfill variables are **never initialized**, so every color silently becomes empty — all theming breaks with no visible error.
+
+**The fix is simple:** disable CSS minification in your Vite build config:
+
+```ts
+export default defineConfig({
+ build: {
+ cssMinify: false,
+ },
+ // ... plugins, resolve, etc.
+});
+```
+
+This is safe because XDS dist CSS is already minified. Setting `lightningcssTargets` on the StyleX plugin is **not sufficient** — Vite's build-phase CSS minifier runs separately from the StyleX plugin and will still mangle `light-dark()` values.
## Related
diff --git a/apps/example-vite/vite.config.ts b/apps/example-vite/vite.config.ts
index b0b0a0ab73..9c24e4122e 100644
--- a/apps/example-vite/vite.config.ts
+++ b/apps/example-vite/vite.config.ts
@@ -22,6 +22,13 @@ const lightningcssTargets = {
// https://vite.dev/config/
export default defineConfig({
+ build: {
+ // Don't use lightningcss for CSS minification — it lowers light-dark()
+ // into --lightningcss-light/--lightningcss-dark polyfill variables that
+ // are never initialized, silently breaking all XDS theming colors.
+ // XDS dist CSS is already minified, so this costs nothing.
+ cssMinify: false,
+ },
plugins: [
stylex.vite({
dev: process.env.NODE_ENV === 'development',
diff --git a/apps/storybook/vite.config.ts b/apps/storybook/vite.config.ts
index 83a484904e..ffb18449b2 100644
--- a/apps/storybook/vite.config.ts
+++ b/apps/storybook/vite.config.ts
@@ -16,6 +16,13 @@ const rootDir = path.resolve(__dirname, '../..');
const coreRoot = path.resolve(__dirname, '../../packages/core/src');
export default defineConfig({
+ build: {
+ // Don't use lightningcss for CSS minification — it lowers light-dark()
+ // into --lightningcss-light/--lightningcss-dark polyfill variables that
+ // are never initialized, silently breaking all XDS theming colors.
+ // The pre-compiled dist CSS imported by preview.tsx is already minified.
+ cssMinify: false,
+ },
plugins: [
stylex.vite({
// Use production mode with CSS extraction