An open source design system that's fully customizable and agent ready
TypeScript
fix(theme): ship built theme modules to prevent double CSS injection (#1247)
Cindy Zhangf9e1f6aa041d
diff --git a/apps/example-nextjs-tailwind/src/app/providers.tsx b/apps/example-nextjs-tailwind/src/app/providers.tsxindex 41e4dfd709..329a994036 100644--- a/apps/example-nextjs-tailwind/src/app/providers.tsx+++ b/apps/example-nextjs-tailwind/src/app/providers.tsx@@ -1,7 +1,7 @@'use client';import {XDSTheme} from '@xds/core/theme';-import {defaultTheme} from '@xds/theme-default';+import {defaultTheme} from '@xds/theme-default/built';export function Providers({children}: {children: React.ReactNode}) {return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;diff --git a/apps/example-nextjs/src/app/providers.tsx b/apps/example-nextjs/src/app/providers.tsxindex 41e4dfd709..329a994036 100644--- a/apps/example-nextjs/src/app/providers.tsx+++ b/apps/example-nextjs/src/app/providers.tsx@@ -1,7 +1,7 @@'use client';import {XDSTheme} from '@xds/core/theme';-import {defaultTheme} from '@xds/theme-default';+import {defaultTheme} from '@xds/theme-default/built';export function Providers({children}: {children: React.ReactNode}) {return <XDSTheme theme={defaultTheme}>{children}</XDSTheme>;diff --git a/apps/example-vite/src/App.tsx b/apps/example-vite/src/App.tsxindex 25b4cd0c3b..6d65dadca6 100644--- a/apps/example-vite/src/App.tsx+++ b/apps/example-vite/src/App.tsx@@ -1,7 +1,7 @@import {useState} from 'react';import * as stylex from '@stylexjs/stylex';import {XDSTheme} from '@xds/core/theme';-import {defaultTheme} from '@xds/theme-default';+import {defaultTheme} from '@xds/theme-default/built';import {XDSVStack, XDSHStack} from '@xds/core/Layout';import {XDSButton} from '@xds/core/Button';import {XDSText, XDSHeading} from '@xds/core/Text';@@ -65,10 +65,10 @@ export default function App() {<XDSVStack gap={3}><XDSHeading level={2}>Badges</XDSHeading><XDSHStack gap={3} vAlign="center">- <XDSBadge variant="info" label='Info' />- <XDSBadge variant="success" label='Success' />- <XDSBadge variant="warning" label='Warning' />- <XDSBadge variant="error" label='Error' />+ <XDSBadge variant="info" label="Info" />+ <XDSBadge variant="success" label="Success" />+ <XDSBadge variant="warning" label="Warning" />+ <XDSBadge variant="error" label="Error" /></XDSHStack></XDSVStack>diff --git a/apps/sandbox/src/app/providers.tsx b/apps/sandbox/src/app/providers.tsxindex 12f9bda6cc..3a14aaec2f 100644--- a/apps/sandbox/src/app/providers.tsx+++ b/apps/sandbox/src/app/providers.tsx@@ -2,12 +2,12 @@import {useState, createContext, useContext, useEffect} from 'react';import {XDSTheme} from '@xds/core/theme';-import {defaultTheme} from '@xds/theme-default';-import {neutralTheme} from '@xds/theme-neutral';-import {brutalistTheme} from '@xds/theme-brutalist';-import {metaTheme} from '@xds/theme-meta';-import {whatsappTheme} from '@xds/theme-whatsapp';-import {dailyTheme} from '@xds/theme-daily';+import {defaultTheme} from '@xds/theme-default/built';+import {neutralTheme} from '@xds/theme-neutral/built';+import {brutalistTheme} from '@xds/theme-brutalist/built';+import {metaTheme} from '@xds/theme-meta/built';+import {whatsappTheme} from '@xds/theme-whatsapp/built';+import {dailyTheme} from '@xds/theme-daily/built';import type {XDSDefinedTheme, ThemeMode} from '@xds/core/theme';const themes: Record<string, XDSDefinedTheme> = {diff --git a/apps/storybook/.storybook/main.ts b/apps/storybook/.storybook/main.tsindex 99108548bb..23cafa180e 100644--- a/apps/storybook/.storybook/main.ts+++ b/apps/storybook/.storybook/main.ts@@ -6,15 +6,15 @@ const rootDir = path.resolve(__dirname, '../../..');const coreRoot = path.resolve(__dirname, '../../../packages/core/src');const themeDefaultRoot = path.resolve(__dirname,- '../../../packages/themes/default/src',+ '../../../packages/themes/default/src/source.ts',);const themeNeutralRoot = path.resolve(__dirname,- '../../../packages/themes/neutral/src',+ '../../../packages/themes/neutral/src/source.ts',);const themeBrutalistRoot = path.resolve(__dirname,- '../../../packages/themes/brutalist/src',+ '../../../packages/themes/brutalist/src/source.ts',);/**diff --git a/packages/cli/docs/theme.doc.dense.mjs b/packages/cli/docs/theme.doc.dense.mjsindex daf5cc8076..84744d4b3d 100644--- a/packages/cli/docs/theme.doc.dense.mjs+++ b/packages/cli/docs/theme.doc.dense.mjs@@ -3,17 +3,15 @@export const docsDense = {description: 'XDSTheme provider, custom themes, light/dark, component overrides',sections: [- { title: 'Quick Start', content: [null] },- { title: 'Themes', content: [null, { type: 'prose', text: 'xds theme --list to see project themes' }] },+ { title: 'Quick Start', content: [null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },+ { title: 'Themes', content: [null, { type: 'prose', text: '@xds/theme-{name} = source (runtime). @xds/theme-{name}/built = optimized (+ theme.css).' }] },{ title: 'Props', content: [null] },- { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual. only override token groups that differ.' }, null, null, { type: 'prose', text: 'token groups: colors/spacing/size/radius/shadow/transition/typography/textSize/lineHeight/fontWeight' }, { type: 'list', items: ['no variable refs in createTheme (static analysis)', 'no spread in createTheme'] }] },- { title: 'defineTheme', content: [{ type: 'prose', text: 'higher-level API. supports scale configs (typography, radius, motion) + explicit token overrides + component overrides.' }, null, null] },- { title: 'Build for Production', content: [{ type: 'prose', text: 'npx xds build-theme compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts. import CSS alongside JS module.' }, null, null, null, null, null] },- { title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS present on first paint. USE BUILT FOR SSR — component overrides (heading scale, text styles) flash on hydration with runtime themes.' }, null, null, null, null] },- { title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values. mode=system follows OS.' }, null, null] },+ { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },+ { title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (typography, radius, motion) + explicit token overrides + component overrides.' }, null, null] },+ { title: 'Build for Production', content: [{ type: 'prose', text: 'npx xds theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },+ { title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },+ { title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },{ title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <XDSTheme> providers' }, null] },- { title: 'Page Background', content: [{ type: 'prose', text: 'XDSTheme is display:contents. apply bg to wrapper.' }, null] },- { title: 'Component Overrides', content: [{ type: 'prose', text: 'themes override component styles via components field + module augmentation' }, null, null, { type: 'prose', text: 'xds --detail compact component <Name> for themeable slots' }] },{ title: 'useXDSTheme', content: [null, { type: 'prose', text: 'read-only. manage state at app level.' }] },],};diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex 42dea25240..6b0028e425 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -3,7 +3,8 @@export const docs = {name: 'theme',title: 'XDS Theme System',- description: 'XDSTheme provider, custom themes, build-theme for production/SSR, light/dark mode, and component style overrides.',+ description:+ 'XDSTheme provider, custom themes, theme build for production/SSR, light/dark mode, and component style overrides.',sections: [{@@ -12,9 +13,9 @@ export const docs = {{type: 'code',lang: 'tsx',- label: 'Basic theme setup',+ label: 'Basic theme setup (runtime injection)',code: `import {XDSTheme} from '@xds/core';-import {defaultTheme} from '@xds/theme/default';+import {defaultTheme} from '@xds/theme-default';function App() {return (@@ -24,6 +25,26 @@ function App() {);}`,},+ {+ type: 'code',+ lang: 'tsx',+ label: 'Optimized setup (pre-built CSS)',+ code: `import {XDSTheme} from '@xds/core';+import {defaultTheme} from '@xds/theme-default/built';+import '@xds/theme-default/theme.css';++function App() {+ return (+ <XDSTheme theme={defaultTheme}>+ <YourApp />+ </XDSTheme>+ );+}`,+ },+ {+ type: 'prose',+ text: 'The default import uses runtime style injection \u2014 works everywhere, no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.',+ },],},{@@ -33,13 +54,26 @@ function App() {type: 'table',headers: ['Theme', 'Import', 'Description'],rows: [- ['Default', "import {defaultTheme} from '@xds/theme/default'", 'Blue accent, system fonts, light/dark'],- ['Neutral', "import {neutralTheme} from '@xds/theme/neutral'", 'Grayscale, shadcn-inspired'],+ [+ 'Default',+ "import {defaultTheme} from '@xds/theme-default'",+ 'Blue accent, system fonts, light/dark',+ ],+ [+ 'Neutral',+ "import {neutralTheme} from '@xds/theme-neutral'",+ 'Grayscale, shadcn-inspired',+ ],+ [+ 'Brutalist',+ "import {brutalistTheme} from '@xds/theme-brutalist'",+ 'Zero radius, monospace, heavy borders',+ ],],},{type: 'prose',- text: "Run `npx xds theme --list` to see themes in your project.",+ text: 'All theme packages export from two subpaths:\n- `@xds/theme-{name}` \u2014 source theme (runtime injection)\n- `@xds/theme-{name}/built` \u2014 pre-built theme (pair with `theme.css`)',},],},@@ -50,9 +84,14 @@ function App() {type: 'table',headers: ['Prop', 'Type', 'Default', 'Description'],rows: [- ['theme', 'Theme', '—', 'Theme object (required)'],- ['mode', "'system' | 'light' | 'dark'", "'system'", 'Color mode. system follows OS preference.'],- ['children', 'ReactNode', '—', 'App content'],+ ['theme', 'XDSDefinedTheme', '\u2014', 'Theme object (required)'],+ [+ 'mode',+ "'system' | 'light' | 'dark'",+ "'system'",+ 'Color mode. system follows OS preference.',+ ],+ ['children', 'ReactNode', '\u2014', 'App content'],],},],@@ -62,7 +101,7 @@ function App() {content: [{type: 'prose',- text: "Use the CLI wizard (recommended) or create manually. Only override token groups that differ from defaults — omitted groups use defineVars defaults from @xds/core.",+ text: 'Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults \u2014 omitted tokens use the XDS defaults.',},{type: 'code',@@ -70,56 +109,14 @@ function App() {label: 'Scaffold with CLI',code: 'npx xds theme',},- {- type: 'code',- lang: 'tsx',- label: 'Manual creation',- code: `import * as stylex from '@stylexjs/stylex';-import type {ThemeType as Theme} from '@xds/core/theme';-import {colorVars, colorDefaults} from '@xds/core/theme/tokens.stylex';--const colorOverrides = {- '--color-accent': 'light-dark(#7B61FF, #9B85FF)',- '--color-background-surface': 'light-dark(#FFFFFF, #1A1A2E)',- // ... all ~60 color tokens (see npx xds docs tokens)-} as const;--const colorTheme = stylex.createTheme(- colorVars,- colorOverrides as unknown as typeof colorDefaults,-);--export const myTheme: Theme = {- name: 'my-theme',- styles: {- colors: colorTheme,- // spacing, radius, etc. omitted — uses defaults- },- raw: {- colors: colorOverrides,- },-};`,- },- {- type: 'prose',- text: "Token groups (all optional in styles): colors, spacing, size, radius, shadow, transition, typography, textSize, lineHeight, fontWeight. Omitted groups use defineVars defaults.",- },- {- type: 'list',- style: 'dont',- items: [- "Variable references in stylex.createTheme(). StyleX requires inline object literals for static analysis.",- "Spread expressions in createTheme(). Same static analysis constraint.",- ],- },],},{- title: 'defineTheme (recommended)',+ title: 'defineTheme',content: [{type: 'prose',- text: "defineTheme is a higher-level API that wraps the raw stylex.createTheme pattern. It supports scale configs that generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values.",+ text: 'defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values.',},{type: 'code',@@ -130,13 +127,13 @@ export const myTheme: Theme = {const myTheme = defineTheme({name: 'my-theme',typography: {- scale: { base: 14, ratio: 1.2 }, // generates heading + text tokens+ scale: { base: 14, ratio: 1.2 },body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },},- radius: { base: 4, multiplier: 1 }, // generates radius tokens+ radius: { base: 4, multiplier: 1 },motion: { fast: 175, medium: 410, ratio: 0.75 },tokens: {- '--color-accent': ['#7B61FF', '#9B85FF'], // explicit overrides win+ '--color-accent': ['#7B61FF', '#9B85FF'], // [light, dark]},components: {button: { 'variant:primary': { color: 'white' } },@@ -147,10 +144,26 @@ const myTheme = defineTheme({type: 'table',headers: ['Config', 'Generates', 'Parameters'],rows: [- ['typography.scale', '--heading-*-size/weight/leading, --text-*-size/weight/leading', 'base (px), ratio'],- ['typography.body/heading/code', '--font-family-body, --font-family-heading, --font-family-code', 'family, fallbacks?, url?, weight?'],- ['radius', '--radius-none through --radius-page, --radius-full', 'base (px), multiplier (0–2)'],- ['motion', '--duration-fast-*, --duration-medium-*, --ease-*', 'fast (ms), medium (ms), ratio, easing?'],+ [+ 'typography.scale',+ '--text-heading-*-size/weight/leading, --text-body-size/weight/leading',+ 'base (px), ratio',+ ],+ [+ 'typography.body/heading/code',+ '--font-family-body, --font-family-heading, --font-family-code',+ 'family, fallbacks?, url?, weight?',+ ],+ [+ 'radius',+ '--radius-1 through --radius-4, --radius-container, --radius-page',+ 'base (px), multiplier (0\u20132)',+ ],+ [+ 'motion',+ '--duration-fast-min/fast/fast-max, --duration-medium-min/medium/medium-max',+ 'fast (ms), medium (ms), ratio, easing?',+ ],],},],@@ -160,42 +173,55 @@ const myTheme = defineTheme({content: [{type: 'prose',- text: "`npx xds build-theme` compiles a defineTheme file into a static CSS file. This is the recommended path for production apps — especially those using server-side rendering (Next.js, Remix, etc.).",+ text: '`npx xds theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',},{type: 'code',lang: 'bash',- label: 'Build a theme to CSS',- code: `npx xds build-theme ./src/themes/ocean.ts -o ./dist/ocean.css`,+ label: 'Build a theme',+ code: 'npx xds theme build ./src/themes/ocean.ts',},{type: 'prose',- text: "This generates three files:",+ text: 'This generates the following files alongside the source:',},{- type: 'list',- style: 'unordered',- items: [- "ocean.css — all token overrides + component overrides as static CSS in @layer xds.theme",- "ocean.js — a JS module with __built: true (tells XDSTheme to skip runtime injection)",- "ocean.d.ts — TypeScript declarations",+ type: 'table',+ headers: ['File', 'Description'],+ rows: [+ [+ 'ocean.css',+ 'Pre-compiled CSS with token overrides, component overrides, and prose element styles in @scope rules',+ ],+ [+ 'ocean.js',+ 'ES module exporting the theme object with `__built: true` and pre-resolved token values. Also re-exports the icon registry if the source theme declares one.',+ ],+ [+ 'ocean.d.ts',+ 'TypeScript declarations for the theme and icon registry exports',+ ],+ [+ 'ocean.variants.d.ts',+ '(Optional) Module augmentations for custom component prop values found in the theme\u2019s component overrides',+ ],],},+ {+ type: 'prose',+ text: 'The `__built: true` flag tells XDSTheme to skip runtime `<style>` injection \u2014 the CSS file handles it.',+ },{type: 'code',lang: 'tsx',- label: 'Using a built theme',- code: `import { oceanTheme } from './themes/ocean';-import './themes/ocean.css'; // static CSS — present on first paint+ label: 'Using a custom built theme',+ code: `import {oceanTheme} from './themes/ocean';+import './themes/ocean.css';<XDSTheme theme={oceanTheme}><App /></XDSTheme>`,},- {- type: 'prose',- text: "Options: --no-prose skips HTML element mappings (h1, p, code, etc.). --tailwind generates a Tailwind CSS preset mapping XDS tokens to var() references.",- },],},{@@ -203,38 +229,59 @@ import './themes/ocean.css'; // static CSS — present on first paintcontent: [{type: 'prose',- text: "XDS themes work in two modes. Choose based on your environment:",+ text: 'XDS themes work in two modes:',},{type: 'table',- headers: ['', 'Runtime (unbuilt)', 'Built'],+ headers: ['', 'Runtime (source)', 'Built'],rows: [- ['How it works', 'defineTheme() + useInsertionEffect injects <style> at hydration', 'npx xds build-theme pre-compiles to a .css file'],- ['Token overrides', 'Inline CSS custom properties on wrapper div — present during SSR ✅', 'Same — inline styles ✅'],- ['Component overrides', 'Injected via useInsertionEffect — client-only ❌', 'In static .css file — present during SSR ✅'],- ['SSR safe', 'Tokens only — component styles flash on hydration', 'Fully SSR safe — no flash'],- ['Best for', 'Dev, prototyping, client-only SPAs', 'Production, SSR apps (Next.js, Remix)'],+ [+ 'Import (published theme)',+ "@xds/theme-{name}",+ "@xds/theme-{name}/built + theme.css",+ ],+ [+ 'Import (custom theme)',+ 'defineTheme() directly',+ "Built .js + .css from `npx xds theme build`",+ ],+ [+ 'How it works',+ 'useInsertionEffect injects <style> at hydration',+ 'Pre-compiled .css file loaded with the page',+ ],+ [+ 'Component overrides',+ 'Injected client-only',+ 'In static CSS \u2014 present during SSR',+ ],+ [+ 'SSR safe',+ 'Tokens yes, component overrides flash on hydration',+ 'Fully SSR safe \u2014 no flash',+ ],+ [+ 'Best for',+ 'Dev, prototyping, client-only SPAs',+ 'Production, SSR apps (Next.js, Remix)',+ ],],},- {- type: 'prose',- text: "The __built flag on the theme object tells XDSTheme to skip useInsertionEffect entirely — the CSS is already loaded as a static file.",- },{type: 'list',style: 'do',items: [- "Use build-theme for production SSR apps. Component overrides (heading scale, text styles) require a <style> tag that useInsertionEffect can only inject client-side.",- "Import the built .css file alongside the theme JS module. The CSS must be in the initial HTML for SSR to work.",- "Use runtime themes during development for fast iteration — no build step needed.",+ 'Use the /built subpath + theme.css for production SSR apps.',+ 'Use runtime themes during development for fast iteration.',+ 'Run `npx xds theme build` for custom themes to get the built artifacts.',],},{type: 'list',style: 'dont',items: [- "Use runtime (unbuilt) themes in production SSR apps. Component overrides will flash on hydration.",- "Forget the CSS import when using a built theme. Without it, component overrides won't apply.",+ 'Use runtime themes in production SSR apps \u2014 component overrides will flash on hydration.',+ 'Import /built without the CSS file \u2014 component overrides won\u2019t apply.',],},],@@ -244,13 +291,13 @@ import './themes/ocean.css'; // static CSS — present on first paintcontent: [{type: 'prose',- text: "Use light-dark() in token values for automatic mode switching. Use mode='system' (default) on XDSTheme to follow OS preference.",+ text: "Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on XDSTheme to follow OS preference.",},{type: 'code',lang: 'tsx',- label: 'Automatic with light-dark()',- code: "'--color-accent': 'light-dark(#0064E0, #2694FE)',\n// ^light ^dark",+ label: 'Light/dark tuple',+ code: "'--color-accent': ['#0064E0', '#2694FE'],\n// ^light ^dark",},{type: 'code',@@ -272,7 +319,7 @@ import './themes/ocean.css'; // static CSS — present on first paintcontent: [{type: 'prose',- text: "Wrap different sections in separate <XDSTheme> providers.",+ text: 'Wrap different sections in separate <XDSTheme> providers.',},{type: 'code',@@ -292,83 +339,6 @@ import './themes/ocean.css'; // static CSS — present on first paint},],},- {- title: 'Page Background',- content: [- {- type: 'prose',- text: "XDSTheme uses display: contents — it doesn't create a visual box. Apply the theme's background color to a wrapper element via StyleX.",- },- {- type: 'code',- lang: 'tsx',- label: 'Applying background color',- code: `const styles = stylex.create({- page: {- backgroundColor: 'var(--color-background-body)',- minHeight: '100vh',- },-});--<XDSTheme theme={myTheme}>- <div {...stylex.props(styles.page)}>- <XDSLayout>...</XDSLayout>- </div>-</XDSTheme>;`,- },- ],- },- {- title: 'Component Style Overrides',- content: [- {- type: 'prose',- text: "Themes can override individual component styles via the components field. Components register themeable properties via module augmentation, and your theme provides StyleX overrides.",- },- {- type: 'code',- lang: 'tsx',- label: 'Card with gradient border',- code: `const cardOverrides = stylex.create({- container: {- borderRadius: '20px',- background: 'linear-gradient(135deg, var(--color-accent), var(--color-success))',- padding: '2px',- },- content: {- backgroundColor: 'var(--color-background-card)',- borderRadius: '18px',- },-});--export const myTheme: Theme = {- name: 'my-theme',- styles: { colors: colorTheme },- components: {- card: {- container: cardOverrides.container,- content: cardOverrides.content,- },- } as Theme['components'],-};`,- },- {- type: 'table',- headers: ['Component', 'Key', 'Slots', 'What to customize'],- rows: [- ['Button', 'button', 'variants (by variant name)', 'Background, border, shadow per variant'],- ['Card', 'card', 'container, content', 'Border, radius, shadow, background'],- ['Heading', 'heading', 'styles (h1-h6), editorialStyles (h1-h6)', 'Font, size, weight, color per level'],- ['Text', 'text', 'styles (body, large, label, supporting, code)', 'Font, size, weight, color per type'],- ['Prose', 'prose', 'base, styles (p, ul, ol, li, blockquote, code, pre, hr, strong, em, a)', 'Prose element styling'],- ],- },- {- type: 'prose',- text: "Run `npx xds --detail compact component <Name>` to see a component's themeable slots.",- },- ],- },{title: 'useXDSTheme Hook',content: [@@ -380,14 +350,14 @@ export const myTheme: Theme = {function MyComponent() {const ctx = useXDSTheme();- // ctx.theme — the Theme object- // ctx.mode — 'system' | 'light' | 'dark'+ // ctx.theme \u2014 the XDSDefinedTheme object+ // ctx.mode \u2014 'system' | 'light' | 'dark'return null;}`,},{type: 'prose',- text: "This is read-only. To change the theme/mode, manage state at the app level and pass it to <XDSTheme>.",+ text: 'This is read-only. To change the theme/mode, manage state at the app level and pass it to <XDSTheme>.',},],},diff --git a/packages/cli/docs/theme.doc.zh.mjs b/packages/cli/docs/theme.doc.zh.mjsindex dd31045bbf..cba9fc569b 100644--- a/packages/cli/docs/theme.doc.zh.mjs+++ b/packages/cli/docs/theme.doc.zh.mjs@@ -3,14 +3,15 @@export const docsZh = {description: 'XDSTheme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',sections: [- { title: '快速开始', content: [null] },- { title: '可用主题', content: [null, { type: 'prose', text: '运行 `npx xds theme --list` 查看项目中的主题。' }] },+ { title: '快速开始', content: [null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS(需配合 theme.css)。' }] },+ { title: '可用主题', content: [null, { type: 'prose', text: '@xds/theme-{name} = 源码版(运行时注入)。@xds/theme-{name}/built = 优化版(配合 theme.css)。' }] },{ title: 'XDSTheme 属性', content: [null] },- { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导(推荐)或手动创建。只覆盖与默认值不同的令牌组,省略的组会自动使用 @xds/core 的 defineVars 默认值。' }, null, null, { type: 'prose', text: '令牌组(styles 中均为可选):colors、spacing、size、radius、elevation、transition、typography、textSize、lineHeight、fontWeight。省略的组使用 defineVars 默认值。' }, { type: 'list', items: ['stylex.createTheme() 中不能使用变量引用。StyleX 需要内联对象字面量进行静态分析。', 'createTheme() 中不能使用展开表达式。同样的静态分析约束。'] }] },- { title: '亮/暗模式', content: [{ type: 'prose', text: "在令牌值中使用 light-dark() 实现自动模式切换。在 XDSTheme 上使用 mode='system'(默认)跟随系统偏好。" }, null, null] },+ { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导(推荐)或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },+ { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置(typography、radius、motion)+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },+ { title: '生产构建', content: [{ type: 'prose', text: 'npx xds theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js(__built:true)+ .d.ts。' }, null, null, null, null] },+ { title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时:useInsertionEffect 在客户端注入样式。构建:静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },+ { title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。XDSTheme 上 mode='system'(默认)跟随系统偏好。" }, null, null] },{ title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <XDSTheme> 提供者中。' }, null] },- { title: '页面背景', content: [{ type: 'prose', text: 'XDSTheme 使用 display: contents,不会创建视觉容器。通过 StyleX 将主题背景色应用到包裹元素。' }, null] },- { title: '组件样式覆盖', content: [{ type: 'prose', text: '主题可以通过 components 字段覆盖单个组件样式。组件通过模块增强注册可主题化的属性,主题提供 StyleX 覆盖。' }, null, null, { type: 'prose', text: '运行 `npx xds --detail compact component <Name>` 查看组件的可主题化插槽。' }] },{ title: 'useXDSTheme 钩子', content: [null, { type: 'prose', text: '这是只读的。要更改主题/模式,在应用层管理状态并传递给 <XDSTheme>。' }] },],};diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjsindex 4795cfa050..a9559f1bdb 100644--- a/packages/cli/src/commands/build-theme.mjs+++ b/packages/cli/src/commands/build-theme.mjs@@ -614,11 +614,14 @@ function extractIconInfo(filePath) {* Includes the theme name, marker, and re-exports the icon registry.* All styling is in the CSS file.*/-function generateBuiltModule(themeDef, iconImportPath) {- const iconImport = iconImportPath- ? `import { icons } from '${iconImportPath}';\n`+function generateBuiltModule(themeDef, iconInfo) {+ const iconImport = iconInfo+ ? `import { ${iconInfo.exportName} } from '${iconInfo.importPath}';\n`+ : '';+ const iconsField = iconInfo ? ` icons: ${iconInfo.exportName},` : '';+ const iconReExport = iconInfo+ ? `\nexport { ${iconInfo.exportName} };\n`: '';- const iconsField = iconImportPath ? ' icons,' : '';// Resolve token values — tuples become light-dark() stringsconst resolvedTokens = {};@@ -646,15 +649,20 @@ export const ${toIdentifier(themeDef.name)}Theme = {tokens: ${tokensStr},${iconsField}};-`;+${iconReExport}`;}/*** Generate TypeScript declarations for a built theme module.*/-function generateBuiltTypes(themeDef) {+function generateBuiltTypes(themeDef, iconInfo) {+ const iconType = iconInfo+ ? `import type { XDSIconRegistry } from '@xds/core/Icon';+export declare const ${iconInfo.exportName}: XDSIconRegistry;+`+ : '';return `import type { XDSDefinedTheme } from '@xds/core/theme';-export declare const ${toIdentifier(themeDef.name)}Theme: XDSDefinedTheme;+${iconType}export declare const ${toIdentifier(themeDef.name)}Theme: XDSDefinedTheme;`;}@@ -930,10 +938,9 @@ export function registerTheme(program) {const dtsPath = path.join(outDir, `${baseName}.d.ts`);const iconInfo = extractIconInfo(filePath);- const iconImportPath = iconInfo ? iconInfo.importPath : null;- fs.writeFileSync(jsPath, generateBuiltModule(resolvedTheme || themeDef, iconImportPath));- fs.writeFileSync(dtsPath, generateBuiltTypes(themeDef));+ fs.writeFileSync(jsPath, generateBuiltModule(resolvedTheme || themeDef, iconInfo));+ fs.writeFileSync(dtsPath, generateBuiltTypes(themeDef, iconInfo));if (!json) {console.log(`✓ ${path.relative(process.cwd(), jsPath)}`);diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsxindex f8fb665cf7..dfa25d46d3 100644--- a/packages/core/src/theme/XDSTheme.tsx+++ b/packages/core/src/theme/XDSTheme.tsx@@ -94,6 +94,9 @@ const XDSThemeNestingContext = React.createContext(false);/** Track which themes have already been injected */const injectedThemes = new Set<string>();+/** Track which themes have already logged the perf warning */+const warnedThemes = new Set<string>();+/*** Hook to inject theme CSS into the document.* Built themes (from `xds theme build`) skip injection — their CSS@@ -109,6 +112,19 @@ function useThemeStyleInjection(theme: XDSDefinedTheme): void {const themeKey = `xds-theme-${theme.name}`;if (injectedThemes.has(themeKey)) return;+ // One-time perf hint per theme+ if (!warnedThemes.has(theme.name)) {+ warnedThemes.add(theme.name);+ console.warn(+ `[XDS] Theme "${theme.name}" is using runtime style injection. ` ++ `For better performance, use the pre-built theme:\n\n` ++ ` import {${theme.name}Theme} from '@xds/theme-${theme.name}/built';\n` ++ ` import '@xds/theme-${theme.name}/theme.css';\n\n` ++ `For custom themes, run \`npx xds theme build <file>\` to generate ` ++ `the built artifacts.`,+ );+ }+const {prose, component} = generateThemeCSS(theme);if (!prose && !component) return;diff --git a/packages/themes/brutalist/package.json b/packages/themes/brutalist/package.jsonindex 4a3c468414..7246b4dfa2 100644--- a/packages/themes/brutalist/package.json+++ b/packages/themes/brutalist/package.json@@ -2,17 +2,22 @@"name": "@xds/theme-brutalist","version": "0.0.11","private": true,- "description": "Brutalist theme for XDS \u2014 zero radius, monospace, heavy borders",+ "description": "Brutalist theme for XDS — zero radius, monospace, heavy borders","license": "MIT","sideEffects": false,- "main": "./dist/index.js",- "module": "./dist/index.mjs",- "types": "./dist/index.d.ts",+ "main": "./dist/source.js",+ "module": "./dist/source.mjs",+ "types": "./dist/source.d.ts","exports": {".": {- "types": "./dist/index.d.ts",- "import": "./dist/index.mjs",- "require": "./dist/index.js"+ "types": "./dist/source.d.ts",+ "import": "./dist/source.mjs",+ "require": "./dist/source.js"+ },+ "./built": {+ "types": "./dist/brutalist.d.ts",+ "import": "./dist/brutalist.js",+ "require": "./dist/brutalist.js"},"./theme.css": "./dist/theme.css"},@@ -21,7 +26,7 @@"src"],"scripts": {- "build": "xds theme build src/index.ts -o dist/theme.css && tsup && rm -f dist/brutalist.js dist/brutalist.d.ts"+ "build": "xds theme build src/brutalistTheme.ts -o dist/theme.css && tsup"},"peerDependencies": {"@xds/core": "*"diff --git a/packages/themes/brutalist/src/index.ts b/packages/themes/brutalist/src/brutalistTheme.tssimilarity index 100%rename from packages/themes/brutalist/src/index.tsrename to packages/themes/brutalist/src/brutalistTheme.tsdiff --git a/packages/themes/brutalist/src/source.ts b/packages/themes/brutalist/src/source.tsnew file mode 100644index 0000000000..2586cba92a--- /dev/null+++ b/packages/themes/brutalist/src/source.ts@@ -0,0 +1 @@+export {brutalistTheme} from './brutalistTheme';diff --git a/packages/themes/brutalist/tsup.config.ts b/packages/themes/brutalist/tsup.config.tsindex 176795f3bb..673e12333f 100644--- a/packages/themes/brutalist/tsup.config.ts+++ b/packages/themes/brutalist/tsup.config.ts@@ -1,9 +1,9 @@import {defineConfig} from 'tsup';export default defineConfig({- entry: ['src/index.ts'],+ entry: ['src/source.ts'],format: ['cjs', 'esm'],dts: true,- clean: false, // Don't clean — xds build-theme already put theme.css in dist/+ clean: false, // Don't clean — xds theme build already put theme files in dist/external: ['@xds/core', 'react'],});diff --git a/packages/themes/daily/package.json b/packages/themes/daily/package.jsonindex 54e438b1d0..f6400a91ac 100644--- a/packages/themes/daily/package.json+++ b/packages/themes/daily/package.json@@ -5,13 +5,18 @@"description": "Daily theme for XDS components — warm, productivity-focused (Lucide icons)","license": "MIT","sideEffects": false,- "main": "./dist/index.js",- "types": "./dist/index.d.ts",+ "main": "./dist/source.js",+ "types": "./dist/source.d.ts","exports": {".": {- "types": "./dist/index.d.ts",- "import": "./dist/index.mjs",- "require": "./dist/index.js"+ "types": "./dist/source.d.ts",+ "import": "./dist/source.mjs",+ "require": "./dist/source.js"+ },+ "./built": {+ "types": "./dist/daily.d.ts",+ "import": "./dist/daily.js",+ "require": "./dist/daily.js"},"./theme.css": "./dist/theme.css"},@@ -20,7 +25,7 @@"src"],"scripts": {- "build": "xds theme build src/dailyTheme.ts -o dist/theme.css && tsup && rm -f dist/daily.js dist/daily.d.ts"+ "build": "xds theme build src/dailyTheme.ts -o dist/theme.css && tsup"},"dependencies": {"lucide-react": "^0.575.0"@@ -32,5 +37,5 @@"devDependencies": {"@xds/cli": "*"},- "module": "./dist/index.mjs"+ "module": "./dist/source.mjs"}diff --git a/packages/themes/daily/src/index.ts b/packages/themes/daily/src/source.tssimilarity index 100%rename from packages/themes/daily/src/index.tsrename to packages/themes/daily/src/source.tsdiff --git a/packages/themes/daily/tsup.config.ts b/packages/themes/daily/tsup.config.tsindex d2efee8f89..e2b0d03bb9 100644--- a/packages/themes/daily/tsup.config.ts+++ b/packages/themes/daily/tsup.config.ts@@ -1,9 +1,9 @@import {defineConfig} from 'tsup';export default defineConfig({- entry: ['src/index.ts'],+ entry: ['src/source.ts', 'src/icons.tsx'],format: ['cjs', 'esm'],dts: true,- clean: false, // Don't clean — xds build-theme already put theme.css in dist/+ clean: false, // Don't clean — xds theme build already put theme files in dist/external: ['@xds/core', 'react', 'lucide-react'],});diff --git a/packages/themes/default/package.json b/packages/themes/default/package.jsonindex ddaf2775b8..a2c27bdecc 100644--- a/packages/themes/default/package.json+++ b/packages/themes/default/package.json@@ -5,13 +5,18 @@"description": "Default theme for XDS components (Heroicons)","license": "MIT","sideEffects": false,- "main": "./dist/index.js",- "types": "./dist/index.d.ts",+ "main": "./dist/source.js",+ "types": "./dist/source.d.ts","exports": {".": {- "types": "./dist/index.d.ts",- "import": "./dist/index.mjs",- "require": "./dist/index.js"+ "types": "./dist/source.d.ts",+ "import": "./dist/source.mjs",+ "require": "./dist/source.js"+ },+ "./built": {+ "types": "./dist/default.d.ts",+ "import": "./dist/default.js",+ "require": "./dist/default.js"},"./theme.css": "./dist/theme.css"},@@ -20,7 +25,7 @@"src"],"scripts": {- "build": "xds theme build src/defaultTheme.ts -o dist/theme.css && tsup && rm -f dist/default.js dist/default.d.ts"+ "build": "xds theme build src/defaultTheme.ts -o dist/theme.css && tsup"},"dependencies": {"@heroicons/react": "^2.2.0"@@ -32,5 +37,5 @@"devDependencies": {"@xds/cli": "*"},- "module": "./dist/index.mjs"+ "module": "./dist/source.mjs"}diff --git a/packages/themes/default/src/index.ts b/packages/themes/default/src/source.tssimilarity index 100%rename from packages/themes/default/src/index.tsrename to packages/themes/default/src/source.tsdiff --git a/packages/themes/default/tsup.config.ts b/packages/themes/default/tsup.config.tsindex ea80f41b14..e22496fe88 100644--- a/packages/themes/default/tsup.config.ts+++ b/packages/themes/default/tsup.config.ts@@ -1,9 +1,9 @@import {defineConfig} from 'tsup';export default defineConfig({- entry: ['src/index.ts'],+ entry: ['src/source.ts', 'src/icons.tsx'],format: ['cjs', 'esm'],dts: true,- clean: false, // Don't clean — xds build-theme already put theme.css in dist/+ clean: false, // Don't clean — xds theme build already put theme files in dist/external: ['@xds/core', 'react', '@heroicons/react'],});diff --git a/packages/themes/meta/package.json b/packages/themes/meta/package.jsonindex 7ce8dc48e4..9763e467c4 100644--- a/packages/themes/meta/package.json+++ b/packages/themes/meta/package.json@@ -5,13 +5,18 @@"description": "Meta theme for XDS components — Meta's brand identity with blue accent and clean aesthetics","license": "MIT","sideEffects": false,- "main": "./dist/index.js",- "types": "./dist/index.d.ts",+ "main": "./dist/source.js",+ "types": "./dist/source.d.ts","exports": {".": {- "types": "./dist/index.d.ts",- "import": "./dist/index.mjs",- "require": "./dist/index.js"+ "types": "./dist/source.d.ts",+ "import": "./dist/source.mjs",+ "require": "./dist/source.js"+ },+ "./built": {+ "types": "./dist/meta.d.ts",+ "import": "./dist/meta.js",+ "require": "./dist/meta.js"},"./theme.css": "./dist/theme.css"},@@ -20,7 +25,7 @@"src"],"scripts": {- "build": "xds theme build src/metaTheme.ts -o dist/theme.css && node scripts/gen-compat-css.mjs && tsup && rm -f dist/meta.js dist/meta.d.ts"+ "build": "xds theme build src/metaTheme.ts -o dist/theme.css && node scripts/gen-compat-css.mjs && tsup"},"dependencies": {"@heroicons/react": "^2.2.0"@@ -32,5 +37,5 @@"devDependencies": {"@xds/cli": "*"},- "module": "./dist/index.mjs"+ "module": "./dist/source.mjs"}diff --git a/packages/themes/meta/src/index.ts b/packages/themes/meta/src/source.tssimilarity index 100%rename from packages/themes/meta/src/index.tsrename to packages/themes/meta/src/source.tsdiff --git a/packages/themes/meta/tsup.config.ts b/packages/themes/meta/tsup.config.tsindex 176795f3bb..e22496fe88 100644--- a/packages/themes/meta/tsup.config.ts+++ b/packages/themes/meta/tsup.config.ts@@ -1,9 +1,9 @@import {defineConfig} from 'tsup';export default defineConfig({- entry: ['src/index.ts'],+ entry: ['src/source.ts', 'src/icons.tsx'],format: ['cjs', 'esm'],dts: true,- clean: false, // Don't clean — xds build-theme already put theme.css in dist/- external: ['@xds/core', 'react'],+ clean: false, // Don't clean — xds theme build already put theme files in dist/+ external: ['@xds/core', 'react', '@heroicons/react'],});diff --git a/packages/themes/neutral/package.json b/packages/themes/neutral/package.jsonindex bac7b3a8ee..537f71c40a 100644--- a/packages/themes/neutral/package.json+++ b/packages/themes/neutral/package.json@@ -5,13 +5,18 @@"description": "Neutral theme for XDS components (Lucide icons)","license": "MIT","sideEffects": false,- "main": "./dist/index.js",- "types": "./dist/index.d.ts",+ "main": "./dist/source.js",+ "types": "./dist/source.d.ts","exports": {".": {- "types": "./dist/index.d.ts",- "import": "./dist/index.mjs",- "require": "./dist/index.js"+ "types": "./dist/source.d.ts",+ "import": "./dist/source.mjs",+ "require": "./dist/source.js"+ },+ "./built": {+ "types": "./dist/neutral.d.ts",+ "import": "./dist/neutral.js",+ "require": "./dist/neutral.js"},"./theme.css": "./dist/theme.css"},@@ -20,7 +25,7 @@"src"],"scripts": {- "build": "xds theme build src/neutralTheme.ts -o dist/theme.css && tsup && rm -f dist/neutral.js dist/neutral.d.ts"+ "build": "xds theme build src/neutralTheme.ts -o dist/theme.css && tsup"},"dependencies": {"lucide-react": "^0.575.0"@@ -32,5 +37,5 @@"devDependencies": {"@xds/cli": "*"},- "module": "./dist/index.mjs"+ "module": "./dist/source.mjs"}diff --git a/packages/themes/neutral/src/index.ts b/packages/themes/neutral/src/source.tssimilarity index 100%rename from packages/themes/neutral/src/index.tsrename to packages/themes/neutral/src/source.tsdiff --git a/packages/themes/neutral/tsup.config.ts b/packages/themes/neutral/tsup.config.tsindex d2efee8f89..e2b0d03bb9 100644--- a/packages/themes/neutral/tsup.config.ts+++ b/packages/themes/neutral/tsup.config.ts@@ -1,9 +1,9 @@import {defineConfig} from 'tsup';export default defineConfig({- entry: ['src/index.ts'],+ entry: ['src/source.ts', 'src/icons.tsx'],format: ['cjs', 'esm'],dts: true,- clean: false, // Don't clean — xds build-theme already put theme.css in dist/+ clean: false, // Don't clean — xds theme build already put theme files in dist/external: ['@xds/core', 'react', 'lucide-react'],});diff --git a/packages/themes/syntax/package.json b/packages/themes/syntax/package.jsonindex 7c4ee12fa2..ded2af2bc5 100644--- a/packages/themes/syntax/package.json+++ b/packages/themes/syntax/package.json@@ -1,7 +1,7 @@{"name": "@xds/theme-syntax","version": "0.0.11",- "description": "Syntax highlighting theme presets for XDS \u2014 11 community themes mapped to the XDS 14-token syntax architecture",+ "description": "Syntax highlighting theme presets for XDS — 11 community themes mapped to the XDS 14-token syntax architecture","license": "MIT","sideEffects": false,"main": "./dist/index.js",diff --git a/packages/themes/whatsapp/package.json b/packages/themes/whatsapp/package.jsonindex 4aad8a4101..829ef0e013 100644--- a/packages/themes/whatsapp/package.json+++ b/packages/themes/whatsapp/package.json@@ -5,14 +5,19 @@"description": "WhatsApp theme for XDS — green accent, warm grays, Roboto, rounded surfaces","license": "MIT","sideEffects": false,- "main": "./dist/index.js",- "module": "./dist/index.mjs",- "types": "./dist/index.d.ts",+ "main": "./dist/source.js",+ "module": "./dist/source.mjs",+ "types": "./dist/source.d.ts","exports": {".": {- "types": "./dist/index.d.ts",- "import": "./dist/index.mjs",- "require": "./dist/index.js"+ "types": "./dist/source.d.ts",+ "import": "./dist/source.mjs",+ "require": "./dist/source.js"+ },+ "./built": {+ "types": "./dist/whatsapp.d.ts",+ "import": "./dist/whatsapp.js",+ "require": "./dist/whatsapp.js"},"./theme.css": "./dist/theme.css"},@@ -21,7 +26,7 @@"src"],"scripts": {- "build": "xds theme build src/whatsappTheme.ts -o dist/theme.css && tsup && rm -f dist/whatsapp.js dist/whatsapp.d.ts"+ "build": "xds theme build src/whatsappTheme.ts -o dist/theme.css && tsup"},"peerDependencies": {"@xds/core": "*",diff --git a/packages/themes/whatsapp/src/index.ts b/packages/themes/whatsapp/src/source.tssimilarity index 100%rename from packages/themes/whatsapp/src/index.tsrename to packages/themes/whatsapp/src/source.tsdiff --git a/packages/themes/whatsapp/tsup.config.ts b/packages/themes/whatsapp/tsup.config.tsindex 176795f3bb..e22496fe88 100644--- a/packages/themes/whatsapp/tsup.config.ts+++ b/packages/themes/whatsapp/tsup.config.ts@@ -1,9 +1,9 @@import {defineConfig} from 'tsup';export default defineConfig({- entry: ['src/index.ts'],+ entry: ['src/source.ts', 'src/icons.tsx'],format: ['cjs', 'esm'],dts: true,- clean: false, // Don't clean — xds build-theme already put theme.css in dist/- external: ['@xds/core', 'react'],+ clean: false, // Don't clean — xds theme build already put theme files in dist/+ external: ['@xds/core', 'react', '@heroicons/react'],});