An open source design system that's fully customizable and agent ready
TypeScript
fix(examples): remove stale typography.css refs, fix prop errors, add browserslist docs (#717)
Cindy Zhang417e15597807
diff --git a/apps/example-nextjs/README.md b/apps/example-nextjs/README.mdindex e8b0a9b510..90c652f4cd 100644--- a/apps/example-nextjs/README.md+++ b/apps/example-nextjs/README.md@@ -14,7 +14,19 @@ npm install --save-dev @stylexjs/babel-plugin @stylexjs/postcss-plugin \@babel/preset-react @babel/preset-typescript typescript @types/react @types/react-dom```-### 2. Babel config+### 2. Browserslist++Add a `browserslist` to `package.json` so that Next.js (and its internal lightningcss) targets modern browsers. Without this, lightningcss may lower `light-dark()` into polyfill variables that break XDS theming:++```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+ / Firefox 120+ / Safari 17.5+ (when `light-dark()` shipped).++### 3. Babel config`babel.config.js` — configure StyleX as a **plugin** (not a preset) with `next/babel`:@@ -47,7 +59,7 @@ module.exports = {> **Important:** The `aliases` config is required for `stylex.createTheme` to resolve token definitions correctly. Without it, theme overrides silently fail.-### 3. PostCSS config+### 4. PostCSS config`postcss.config.js` — this is how Next.js extracts StyleX CSS:@@ -76,7 +88,7 @@ module.exports = {};```-### 4. CSS entry point with `@stylex;` directive+### 5. CSS entry point with `@stylex;` directive`src/app/globals.css`:@@ -84,44 +96,32 @@ module.exports = {@stylex;```-Import it in your root layout, along with the base CSS and theme CSS:+Import it in your root layout, along with the base reset and theme CSS:```tsximport '@xds/core/reset.css';-import '@xds/core/typography.css';import '@xds/theme-default/theme.css';import './globals.css';```The CSS import order matters:+1. `reset.css` — baseline resets (`@layer reset`)-2. `typography.css` — prose styles (`@layer typography`)-3. `theme.css` — theme component overrides (`@layer xds.theme`)-4. `globals.css` — StyleX extraction (`@stylex;` directive)+2. `theme.css` — theme token overrides (`@layer xds.theme`)+3. `globals.css` — StyleX extraction (`@stylex;` directive)-### 5. Next.js config+### 6. Next.js config`next.config.mjs` — add `transpilePackages` so Next.js compiles XDS source:```jsconst nextConfig = {transpilePackages: ['@xds/core', '@xds/theme-default'],- typescript: {ignoreBuildErrors: true},};export default nextConfig;```-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)+### 7. Theme provider (client boundary)```tsx// src/app/providers.tsx@@ -136,13 +136,14 @@ export function Providers({children}) {## Gotchas-| Issue | Symptom | Fix |-| ----------------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |-| Missing `@stylex;` directive | PostCSS produces empty CSS with no error | Add `@stylex;` to your CSS entry file |-| PostCSS `include` doesn't cover XDS | XDS component styles are missing | Add `node_modules/@xds/core/**/*.{ts,tsx}` to `include` |-| Missing `aliases` in babel config | `createTheme` token overrides silently fail | Add `aliases` mapping for `@xds/core` and `@xds/core/*` |-| 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` |+| Issue | Symptom | Fix |+| ----------------------------------- | ------------------------------------------- | ----------------------------------------------------------------- |+| Missing `browserslist` | Colors broken — `light-dark()` gets lowered | Add `"browserslist": ["last 1 Chrome version"]` to `package.json` |+| Missing `@stylex;` directive | PostCSS produces empty CSS with no error | Add `@stylex;` to your CSS entry file |+| PostCSS `include` doesn't cover XDS | XDS component styles are missing | Add `node_modules/@xds/core/**/*.{ts,tsx}` to `include` |+| Missing `aliases` in babel config | `createTheme` token overrides silently fail | Add `aliases` mapping for `@xds/core` and `@xds/core/*` |+| 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` |## Testing outside the monorepodiff --git a/apps/example-nextjs/next.config.mjs b/apps/example-nextjs/next.config.mjsindex 49dc05327b..c616176c79 100644--- a/apps/example-nextjs/next.config.mjs+++ b/apps/example-nextjs/next.config.mjs@@ -1,11 +1,6 @@/** @type {import('next').NextConfig} */const nextConfig = {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,- },};export default nextConfig;diff --git a/apps/example-nextjs/src/app/page.tsx b/apps/example-nextjs/src/app/page.tsxindex 7b2aea4796..3c0c92129b 100644--- a/apps/example-nextjs/src/app/page.tsx+++ b/apps/example-nextjs/src/app/page.tsx@@ -1,5 +1,6 @@'use client';+import {useState} from 'react';import * as stylex from '@stylexjs/stylex';import {XDSVStack, XDSHStack} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';@@ -23,17 +24,21 @@ const styles = stylex.create({});export default function Home() {+ const [email, setEmail] = useState('');+return (<main {...stylex.props(styles.main)}><div {...stylex.props(styles.container)}><XDSVStack gap={6}><XDSVStack gap={2}><XDSHeading level={1}>XDS Example — Next.js</XDSHeading>- <XDSText color="secondary">+ <XDSText type="body" color="secondary">This is a reference example for consuming{' '}- <XDSText weight="bold">@xds/core</XDSText> as a source- distribution in a Next.js application. Components are compiled- from raw TypeScript source using StyleX at build time.+ <XDSText type="body" weight="bold">+ @xds/core+ </XDSText>{' '}+ as a source distribution in a Next.js application. Components are+ compiled from raw TypeScript source using StyleX at build time.</XDSText></XDSVStack>@@ -42,10 +47,10 @@ export default function Home() {{/* Buttons */}<XDSVStack gap={3}><XDSHeading level={2}>Buttons</XDSHeading>- <XDSHStack gap={3} align="center">- <XDSButton variant="primary">Primary</XDSButton>- <XDSButton variant="secondary">Secondary</XDSButton>- <XDSButton variant="ghost">Ghost</XDSButton>+ <XDSHStack gap={3} vAlign="center">+ <XDSButton label="Primary" variant="primary" />+ <XDSButton label="Secondary" variant="secondary" />+ <XDSButton label="Ghost" variant="ghost" /></XDSHStack></XDSVStack>@@ -54,7 +59,7 @@ export default function Home() {{/* Badges */}<XDSVStack gap={3}><XDSHeading level={2}>Badges</XDSHeading>- <XDSHStack gap={3} align="center">+ <XDSHStack gap={3} vAlign="center"><XDSBadge variant="info">Info</XDSBadge><XDSBadge variant="success">Success</XDSBadge><XDSBadge variant="warning">Warning</XDSBadge>@@ -67,7 +72,12 @@ export default function Home() {{/* Text Input */}<XDSVStack gap={3}><XDSHeading level={2}>Text Input</XDSHeading>- <XDSTextInput label="Email address" placeholder="[email protected]" />+ <XDSTextInput+ label="Email address"+ placeholder="[email protected]"+ value={email}+ onChange={setEmail}+ /></XDSVStack><XDSDivider />@@ -78,9 +88,9 @@ export default function Home() {<XDSText type="large" weight="bold">Large bold text</XDSText>- <XDSText>Default body text</XDSText>- <XDSText type="detail" color="secondary">- Detail text in secondary color+ <XDSText type="body">Default body text</XDSText>+ <XDSText type="supporting" color="secondary">+ Supporting text in secondary color</XDSText></XDSVStack></XDSVStack>diff --git a/apps/example-vite/README.md b/apps/example-vite/README.mdindex 5c008df078..a278b8561c 100644--- a/apps/example-vite/README.md+++ b/apps/example-vite/README.md@@ -18,12 +18,24 @@ XDS ships as raw TypeScript + StyleX source. Consumers compile it at the applica### 1. Install dependencies```bash-npm install @stylexjs/stylex @xds/core @xds/theme react react-dom+npm install @stylexjs/stylex @xds/core @xds/theme-default react react-domnpm install --save-dev @stylexjs/unplugin @vitejs/plugin-react typescript \@types/react @types/react-dom vite```-### 2. Vite config+### 2. Browserslist++Add a `browserslist` to `package.json` so that both Vite's CSS pipeline and the StyleX unplugin target modern browsers. XDS tokens use native `light-dark()` (baseline 2024) — without modern targets, lightningcss lowers it into polyfill variables that break theming:++```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+ / Firefox 120+ / Safari 17.5+ (when `light-dark()` shipped).++### 3. Vite config`vite.config.ts` — configure the StyleX unplugin, React plugin, and resolve aliases:@@ -70,6 +82,9 @@ export default defineConfig({type: 'commonJS',rootDir: __dirname,},+ // The StyleX unplugin runs its own internal lightningcss with+ // default targets of browserslist('>= 1%'). Override explicitly+ // so light-dark() is preserved as native CSS.lightningcssOptions: {targets: lightningcssTargets,},@@ -94,9 +109,9 @@ export default defineConfig({});```-> **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()`.+> **Important:** The `lightningcssOptions.targets` config is required — the StyleX unplugin's internal lightningcss defaults to `browserslist('>= 1%')` which includes Chrome 112, a browser that doesn't support `light-dark()`. Without explicit targets, all theming colors silently break. 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+### 4. CSS entry point`src/index.css` — a minimal CSS file so Vite emits a CSS asset for StyleX to append to:@@ -106,28 +121,27 @@ export default defineConfig({}```-Import it in `src/main.tsx`, along with the base CSS and theme CSS:+Import it in `src/main.tsx`, along with the base reset and theme CSS:```tsximport '@xds/core/reset.css';-import '@xds/core/typography.css';import '@xds/theme-default/theme.css';import './index.css';```The CSS import order matters:+1. `reset.css` — baseline resets (`@layer reset`)-2. `typography.css` — prose styles (`@layer typography`)-3. `theme.css` — theme component overrides (`@layer xds.theme`)-4. `index.css` — StyleX extraction placeholder+2. `theme.css` — theme token overrides (`@layer xds.theme`)+3. `index.css` — StyleX extraction placeholder-### 4. Theme provider+### 5. Theme providerWrap your app with `XDSTheme` and the default theme:```tsximport {XDSTheme} from '@xds/core/theme';-import {defaultTheme} from '@xds/theme/default';+import {defaultTheme} from '@xds/theme-default';export default function App() {return <XDSTheme theme={defaultTheme}>{/* your app */}</XDSTheme>;@@ -151,13 +165,14 @@ npm run preview## Gotchas-| 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 |+| Issue | Symptom | Fix |+| ----------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |+| Missing `lightningcssOptions` | Colors broken — `light-dark()` gets lowered | Add `lightningcssOptions: { targets: lightningcssTargets }` to StyleX plugin |+| 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 |## Testing outside the monorepodiff --git a/apps/example-vite/package.json b/apps/example-vite/package.jsonindex 4218e68ffd..f4452f4421 100644--- a/apps/example-vite/package.json+++ b/apps/example-vite/package.json@@ -22,5 +22,8 @@"@vitejs/plugin-react": "^4.3.0","typescript": "^5.7.0","vite": "^5.4.0"- }+ },+ "browserslist": [+ "last 1 Chrome version"+ ]}