An open source design system that's fully customizable and agent ready
TypeScript
docs(theme): clarify StyleX static analysis constraints for createTheme (#290)
Cindy Zhange1a7592bd038
diff --git a/internal/vibe-tests/test-sets/default.json b/internal/vibe-tests/test-sets/default.jsonindex 96337a36a4..b76d515df5 100644--- a/internal/vibe-tests/test-sets/default.json+++ b/internal/vibe-tests/test-sets/default.json@@ -617,6 +617,19 @@"Make buttons use uppercase text in this theme"]},+ {+ "id": "tc-9",+ "category": "theme-customization",+ "prompt": "Create two custom XDS themes that share the same spacing and typography tokens but have different color palettes. The first theme ('ocean') should use blue tones (#0077B6 accent) and the second ('sunset') should use warm orange tones (#E76F51 accent). Keep it DRY — don't duplicate the shared token values.",+ "expectedComponents": [+ "XDSTheme"+ ],+ "complexity": "complex",+ "followUps": [+ "Add a theme switcher that lets the user toggle between the two themes",+ "Add a third theme that shares colors with ocean but uses different spacing"+ ]+ },{"id": "fwc-4","category": "feature-with-constraint",diff --git a/packages/cli/docs/theme.md b/packages/cli/docs/theme.mdindex 0ee1f07626..07aef4c09a 100644--- a/packages/cli/docs/theme.md+++ b/packages/cli/docs/theme.md@@ -88,6 +88,68 @@ The `styles` field uses `stylex.createTheme()` for each token group. The `raw` f**Token groups** (all required in both `styles` and `raw`):colors, spacing, size, radius, elevation, transition, typography, textSize, lineHeight, fontWeight+### ⚠️ Static Analysis Constraint++StyleX's Babel plugin requires that **all values passed to `stylex.createTheme()` are inline object literals** — not variable references, spread expressions, or function return values. This is a compile-time constraint.++```tsx+// ❌ BROKEN — StyleX cannot statically analyze variable references+const sharedSpacing = {+ '--spacing-1': '4px',+ '--spacing-2': '8px',+};+const spacingTheme = stylex.createTheme(spacingVars, sharedSpacing);+// Error: "Only static values are allowed inside of a createTheme() call"++// ❌ BROKEN — spread also fails+const spacingTheme = stylex.createTheme(spacingVars, {...sharedSpacing});++// ✅ WORKS — inline object literal+const spacingTheme = stylex.createTheme(spacingVars, {+ '--spacing-1': '4px',+ '--spacing-2': '8px',+});+```++### Sharing values across multiple themes++When creating multiple themes that share token groups (e.g., same spacing, different colors), you **must duplicate the inline values** in each `createTheme()` call. This is required by StyleX's static analysis — there is no way to DRY up `createTheme` arguments.++```tsx+// ✅ Correct: each theme has its own inline createTheme calls+// (values can be identical — that's fine, they must just be inline literals)++// --- ocean theme ---+const oceanSpacingTheme = stylex.createTheme(spacingVars, {+ '--spacing-1': '4px',+ '--spacing-2': '8px',+ // ... same values, written inline+} as unknown as BaseSpacingRaw);++// --- sunset theme ---+const sunsetSpacingTheme = stylex.createTheme(spacingVars, {+ '--spacing-1': '4px',+ '--spacing-2': '8px',+ // ... same values, written inline+} as unknown as BaseSpacingRaw);+```++The `raw` field (plain objects, not passed to StyleX) _can_ use shared variables:++```tsx+// ✅ raw values can be shared — they're not processed by StyleX+const sharedSpacingRaw = {+ '--spacing-1': '4px',+ '--spacing-2': '8px',+};++export const oceanTheme: Theme = {+ name: 'ocean',+ styles: {spacing: oceanSpacingTheme /* ... */},+ raw: {spacing: sharedSpacingRaw /* ... */}, // ✅ OK — not a createTheme call+};+```+## Light/Dark Mode### Automatic (recommended)diff --git a/packages/cli/src/commands/theme.mjs b/packages/cli/src/commands/theme.mjsindex 38fd9a4cd7..e92a3b4bd6 100644--- a/packages/cli/src/commands/theme.mjs+++ b/packages/cli/src/commands/theme.mjs@@ -419,6 +419,10 @@ const fontWeightRaw = {// =============================================================================// createTheme calls// =============================================================================+// ⚠️ StyleX CONSTRAINT: Each createTheme() call MUST receive an inline object+// literal. Do NOT extract values into a shared variable and reference it here —+// StyleX's Babel plugin cannot statically analyze variable references.+// If you need multiple themes with the same tokens, duplicate the inline values.const colorTheme = stylex.createTheme(colorVars, colorRaw as unknown as BaseColorRaw);const spacingTheme = stylex.createTheme(spacingVars, spacingRaw as unknown as BaseSpacingRaw);