Skip to content

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.mjs
index 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.mjs
index 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: [