Skip to content

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.md
index 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:
```tsx
import '@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:
```js
const 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 monorepo
diff --git a/apps/example-nextjs/next.config.mjs b/apps/example-nextjs/next.config.mjs
index 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.tsx
index 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.md
index 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-dom
npm 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:
```tsx
import '@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 provider
Wrap your app with `XDSTheme` and the default theme:
```tsx
import {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 monorepo
diff --git a/apps/example-vite/package.json b/apps/example-vite/package.json
index 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"
+ ]
}