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.mdindex 70f0480e55..d325bd39ca 100644--- a/apps/example-nextjs/README.md+++ b/apps/example-nextjs/README.md@@ -96,13 +96,21 @@ import './globals.css';```jsconst 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.## Relateddiff --git a/apps/example-nextjs/next.config.mjs b/apps/example-nextjs/next.config.mjsindex 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.jsonindex 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.mdindex 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.## Relateddiff --git a/apps/example-vite/vite.config.ts b/apps/example-vite/vite.config.tsindex 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.tsindex 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 extractiondiff --git a/internal/vibe-tests/app/vite.config.preview.ts b/internal/vibe-tests/app/vite.config.preview.tsindex 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.tsindex 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.tsindex 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.mjsindex 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 pathconst outPath = options.outdiff --git a/packages/core/src/reset.css b/packages/core/src/reset.cssindex 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;}/*