Skip to content

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

TypeScript

fix: add color-scheme to reset.css for lightningcss light-dark() compatibility (#624)

Cindy Zhang3c1c25263ec1
diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.md
index 70f0480e55..d325bd39ca 100644
--- a/apps/example-nextjs/README.md
+++ b/apps/example-nextjs/README.md
@@ -96,13 +96,21 @@ import './globals.css';
```js
const nextConfig = {
- transpilePackages: ['@xds/core', '@xds/theme'],
+ transpilePackages: ['@xds/core', '@xds/theme-default'],
typescript: {ignoreBuildErrors: true},
};
export default nextConfig;
```
-> **Note (monorepo only):** When consuming `@xds/core` inside the XDS monorepo, you may need a webpack alias to resolve `@xds/core/theme/tokens.stylex` to the source file. See `next.config.mjs` in this example for details. External consumers using the source tarball won't need this.
+Also add a `browserslist` to `package.json` to set proper CSS build targets. The StyleX babel plugin uses lightningcss internally, and without modern targets it will lower `light-dark()` into broken polyfill variables:
+
+```json
+{
+ "browserslist": ["last 1 Chrome version"]
+}
+```
+
+> For internal tools targeting latest Chrome, `"last 1 Chrome version"` is sufficient. For broader browser support, use targets that include Chrome 123+ (when `light-dark()` shipped).
### 6. Theme provider (client boundary)
@@ -110,7 +118,7 @@ export default nextConfig;
// src/app/providers.tsx
'use client';
import {XDSTheme} from '@xds/core/theme';
-import {defaultTheme} from '@xds/theme/default';
+import {defaultTheme} from '@xds/theme-default';
export function Providers({children}) {
return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;
@@ -127,13 +135,11 @@ 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.
+## Testing outside the monorepo
-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()`.
+This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@xds/core` from npm. Monorepo workspace resolution can silently bypass issues that external consumers hit (missing dependencies, wrong include paths, different CSS pipeline behavior).
-For Vite-based setups, see the [Vite example's README](../example-vite/) for the specific fix (`cssMinify: false`).
+**Before merging changes to this example, test it as an external consumer** — see the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
## Related
diff --git a/apps/example-nextjs/next.config.mjs b/apps/example-nextjs/next.config.mjs
index 558382711d..49dc05327b 100644
--- a/apps/example-nextjs/next.config.mjs
+++ b/apps/example-nextjs/next.config.mjs
@@ -1,29 +1,11 @@
-import path from 'path';
-import {fileURLToPath} from 'url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
/** @type {import('next').NextConfig} */
const nextConfig = {
- transpilePackages: ['@xds/core', '@xds/theme'],
+ transpilePackages: ['@xds/core', '@xds/theme-default'],
typescript: {
// XDS core has a known type issue in Popover internals;
// safe to ignore for this example.
ignoreBuildErrors: true,
},
- webpack: (config) => {
- // The @xds/core package exports ./theme/tokens.stylex but tsup
- // bundles it into chunks rather than producing a separate file.
- // Alias it to the source file so @xds/theme can resolve it.
- config.resolve.alias = {
- ...config.resolve.alias,
- '@xds/core/theme/tokens.stylex': path.resolve(
- __dirname,
- '../../packages/core/src/theme/tokens.stylex.ts',
- ),
- };
- return config;
- },
};
export default nextConfig;
diff --git a/apps/example-nextjs/package.json b/apps/example-nextjs/package.json
index 2931e32115..e93aad3415 100644
--- a/apps/example-nextjs/package.json
+++ b/apps/example-nextjs/package.json
@@ -23,5 +23,8 @@
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
"typescript": "^5.7.0"
- }
+ },
+ "browserslist": [
+ "last 1 Chrome version"
+ ]
}
diff --git a/apps/example-vite/README.md b/apps/example-vite/README.md
index fbab0139e6..1617d0256e 100644
--- a/apps/example-vite/README.md
+++ b/apps/example-vite/README.md
@@ -36,11 +36,16 @@ import stylex from '@stylexjs/unplugin';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Required: tells the StyleX plugin's internal lightningcss transform
+// not to lower light-dark() into broken polyfill variables.
+// XDS tokens use light-dark() which is baseline 2024.
+const lightningcssTargets = {
+ chrome: 123 << 16,
+ firefox: 120 << 16,
+ safari: (17 << 16) | (5 << 8),
+};
+
export default defineConfig({
- build: {
- // Prevent lightningcss from lowering light-dark() into broken polyfills
- cssMinify: false,
- },
plugins: [
stylex.vite({
dev: process.env.NODE_ENV === 'development',
@@ -50,6 +55,9 @@ export default defineConfig({
type: 'commonJS',
rootDir: __dirname,
},
+ lightningcssOptions: {
+ targets: lightningcssTargets,
+ },
}),
react(),
],
@@ -62,10 +70,16 @@ export default defineConfig({
'@xds/core': path.resolve(__dirname, 'node_modules/@xds/core/src'),
},
},
+ // Prevent Vite from pre-bundling XDS with esbuild. XDS ships as source
+ // that must be compiled by the StyleX plugin — pre-bundling strips the
+ // stylex.create/defineVars calls and causes a runtime error.
+ optimizeDeps: {
+ exclude: ['@xds/core', '@xds/theme-default'],
+ },
});
```
-> **Important:** The `resolve.alias` config points `@xds/core` to the source directory so Vite compiles XDS components from TypeScript source. The `unstable_moduleResolution` config helps StyleX resolve token definitions correctly. Plugin order matters — `stylex.vite()` must come before `react()`.
+> **Important:** The `lightningcssOptions.targets` config is required — without it, the StyleX plugin's internal lightningcss transform lowers `light-dark()` into polyfill variables that silently break all theming colors. The `resolve.alias` points `@xds/core` to source so Vite compiles from TypeScript. Plugin order matters — `stylex.vite()` must come before `react()`.
### 3. CSS entry point
@@ -113,30 +127,19 @@ npm run preview
## Gotchas
-| 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.
+| Issue | Symptom | Fix |
+| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
+| Vite pre-bundles XDS | `Unexpected stylex.defineVars at runtime` | Add `optimizeDeps: { exclude: ['@xds/core', '@xds/theme-default'] }` |
+| 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 |
-**The fix is simple:** disable CSS minification in your Vite build config:
+## Testing outside the monorepo
-```ts
-export default defineConfig({
- build: {
- cssMinify: false,
- },
- // ... plugins, resolve, etc.
-});
-```
+This example lives in the XDS monorepo for convenience, but it should be representative of a real app consuming `@xds/core` from npm. Monorepo workspace symlinks can silently bypass issues that external consumers hit (Vite dep pre-bundling, missing dependencies, wrong resolve paths).
-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.
+**Before merging changes to this example, test it as an external consumer** — see the [Testing Example Apps](https://github.com/facebookexperimental/xds/wiki/Testing-Example-Apps) wiki page for the full procedure.
## Related
diff --git a/apps/example-vite/vite.config.ts b/apps/example-vite/vite.config.ts
index 9c24e4122e..d4bbd43468 100644
--- a/apps/example-vite/vite.config.ts
+++ b/apps/example-vite/vite.config.ts
@@ -22,13 +22,6 @@ 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',
@@ -50,9 +43,15 @@ export default defineConfig({
// from TypeScript source rather than requiring a pre-built dist/.
'@xds/core/theme/tokens.stylex': path.resolve(
__dirname,
- '../../packages/core/src/theme/tokens.stylex.ts',
+ 'node_modules/@xds/core/src/theme/tokens.stylex.ts',
),
- '@xds/core': path.resolve(__dirname, '../../packages/core/src'),
+ '@xds/core': path.resolve(__dirname, 'node_modules/@xds/core/src'),
},
},
+ // Prevent Vite from pre-bundling XDS with esbuild. XDS ships as source
+ // that must be compiled by the StyleX plugin — pre-bundling strips the
+ // stylex.create/defineVars calls and causes a runtime error.
+ optimizeDeps: {
+ exclude: ['@xds/core', '@xds/theme-default'],
+ },
});
diff --git a/apps/storybook/vite.config.ts b/apps/storybook/vite.config.ts
index ffb18449b2..8e7eca736a 100644
--- a/apps/storybook/vite.config.ts
+++ b/apps/storybook/vite.config.ts
@@ -7,7 +7,7 @@
* SYNC: When modified, update this header and /apps/storybook/README.md
*/
-import { defineConfig } from 'vite';
+import {defineConfig} from 'vite';
import react from '@vitejs/plugin-react';
import stylex from '@stylexjs/unplugin';
import path from 'path';
@@ -16,13 +16,6 @@ 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
diff --git a/internal/vibe-tests/app/vite.config.preview.ts b/internal/vibe-tests/app/vite.config.preview.ts
index 6bf67d8d32..4f4c538fb1 100644
--- a/internal/vibe-tests/app/vite.config.preview.ts
+++ b/internal/vibe-tests/app/vite.config.preview.ts
@@ -31,12 +31,7 @@ const lightningcssTargets = {
*/
export default defineConfig({
root: __dirname,
- build: {
- // Don't use lightningcss for minification — it lowers light-dark()
- // into --lightningcss-light/--lightningcss-dark polyfill variables
- // which breaks theming. The StyleX plugin handles its own CSS.
- cssMinify: false,
- },
+ build: {},
plugins: [
stylex.vite({
dev: process.env.NODE_ENV === 'development',
diff --git a/internal/vibe-tests/app/vite.config.report.ts b/internal/vibe-tests/app/vite.config.report.ts
index 34d5e4da10..5035a450e9 100644
--- a/internal/vibe-tests/app/vite.config.report.ts
+++ b/internal/vibe-tests/app/vite.config.report.ts
@@ -39,10 +39,6 @@ export default defineConfig({
rollupOptions: {
input: path.resolve(__dirname, 'index.report.html'),
},
- // Don't use lightningcss for minification — it lowers light-dark()
- // into --lightningcss-light/--lightningcss-dark polyfill variables
- // which breaks theming. The pre-compiled CSS is already minified.
- cssMinify: false,
},
resolve: {
alias: [
diff --git a/internal/vibe-tests/app/vite.config.ts b/internal/vibe-tests/app/vite.config.ts
index 7e4a90d13e..c07cadcd5e 100644
--- a/internal/vibe-tests/app/vite.config.ts
+++ b/internal/vibe-tests/app/vite.config.ts
@@ -23,12 +23,7 @@ const lightningcssTargets = {
};
export default defineConfig({
- build: {
- // Don't use lightningcss for minification — it lowers light-dark()
- // into --lightningcss-light/--lightningcss-dark polyfill variables
- // which breaks theming. The StyleX plugin handles its own CSS.
- cssMinify: false,
- },
+ build: {},
plugins: [
stylex.vite({
dev: process.env.NODE_ENV === 'development',
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjs
index 74741a6506..e6864e4cb8 100644
--- a/packages/cli/src/commands/build-theme.mjs
+++ b/packages/cli/src/commands/build-theme.mjs
@@ -654,7 +654,15 @@ export function registerTheme(program) {
return;
}
- const css = `@layer xds.theme {\n${scopeBlocks.join('\n\n')}\n}\n`;
+ // If any scope block uses light-dark(), include a color-scheme declaration
+ // so that CSS tools that lower light-dark() (e.g. LightningCSS) can inject
+ // their polyfill toggle variables in the same file. Without this, the
+ // polyfill vars are used but never defined, silently breaking all colors.
+ const joined = scopeBlocks.join('\n\n');
+ const colorSchemeDecl = joined.includes('light-dark(')
+ ? ' :root { color-scheme: light dark; }\n\n'
+ : '';
+ const css = `@layer xds.theme {\n${colorSchemeDecl}${joined}\n}\n`;
// Determine output path
const outPath = options.out
diff --git a/packages/core/src/reset.css b/packages/core/src/reset.css
index 0aaf441432..61a470970f 100644
--- a/packages/core/src/reset.css
+++ b/packages/core/src/reset.css
@@ -66,11 +66,18 @@
/*
* Consistent line-height, prevent text size adjustment on orientation
* change in iOS, and set a readable tab size.
+ *
+ * color-scheme: light dark — declares that this page supports both modes,
+ * enabling CSS light-dark() to resolve correctly. Also ensures that CSS
+ * tools (e.g. LightningCSS) which polyfill light-dark() for older browsers
+ * inject their toggle-variable initialization in the same CSS bundle.
+ * XDSTheme overrides color-scheme per-wrapper as needed.
*/
:where(html) {
line-height: 1.5;
-webkit-text-size-adjust: 100%;
tab-size: 4;
+ color-scheme: light dark;
}
/*