An open source design system that's fully customizable and agent ready
TypeScript
docs(theme): add build-theme and SSR guidance to theme docs (#1210)
Cindy Zhang0969a72d1eac
diff --git a/packages/cli/docs/theme.doc.dense.mjs b/packages/cli/docs/theme.doc.dense.mjsindex 86159ee739..daf5cc8076 100644--- a/packages/cli/docs/theme.doc.dense.mjs+++ b/packages/cli/docs/theme.doc.dense.mjs@@ -7,6 +7,9 @@ export const docsDense = {{ title: 'Themes', content: [null, { type: 'prose', text: 'xds theme --list to see project themes' }] },{ 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: '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] },diff --git a/packages/cli/docs/theme.doc.mjs b/packages/cli/docs/theme.doc.mjsindex ff83526d29..42dea25240 100644--- a/packages/cli/docs/theme.doc.mjs+++ b/packages/cli/docs/theme.doc.mjs@@ -3,7 +3,7 @@export const docs = {name: 'theme',title: 'XDS Theme System',- description: 'XDSTheme provider, custom themes, light/dark mode, and component style overrides.',+ description: 'XDSTheme provider, custom themes, build-theme for production/SSR, light/dark mode, and component style overrides.',sections: [{@@ -155,6 +155,90 @@ const myTheme = defineTheme({},],},+ {+ title: 'Building Themes for Production',+ 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.).",+ },+ {+ type: 'code',+ lang: 'bash',+ label: 'Build a theme to CSS',+ code: `npx xds build-theme ./src/themes/ocean.ts -o ./dist/ocean.css`,+ },+ {+ type: 'prose',+ text: "This generates three files:",+ },+ {+ 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: 'code',+ lang: 'tsx',+ label: 'Using a built theme',+ code: `import { oceanTheme } from './themes/ocean';+import './themes/ocean.css'; // static CSS — present on first paint++<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.",+ },+ ],+ },+ {+ title: 'Runtime vs Built Themes',+ content: [+ {+ type: 'prose',+ text: "XDS themes work in two modes. Choose based on your environment:",+ },+ {+ type: 'table',+ headers: ['', 'Runtime (unbuilt)', '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)'],+ ],+ },+ {+ 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.",+ ],+ },+ {+ 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.",+ ],+ },+ ],+ },{title: 'Light/Dark Mode',content: [