Skip to content

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.json
index 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.md
index 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.mjs
index 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);