Chore: Clarify stability of theming APIs

apps/docs/docs/api/configuration/babel-plugin.mdx

@@ -10,101 +10,147 @@ sidebar_position: 1
 
 ## Configuration options
 
+### `dev`
+
+```ts
+dev: boolean // Default: false
+```
+
+When `true`, StyleX will insert debug class names to identify the source of the styles.
+
+<hr />
+
+### `test`
+
+```ts
+test: boolean // Default: false
+```
+
+When `true`, StyleX will only output debug classNames identifying the 
+source of the styles.
+
+It will *not* generate any styles or functional classNames.
+This can be useful for snapshot testing.
+
+<hr />
+
+### `runtimeInjection`
+
+```ts
+runtimeInjection: boolean // Default: the value of `dev`
+```
+
+Should StyleX generate code to inject styles at runtime?
+This may be useful during development but should be disabled in production.
+
+<hr />
+
+### `classNamePrefix`
+
+```ts
+classNamePrefix: string // Default: 'x'
+```
+
+Prefix to applied to every generated className.
+
+<hr />
+
+### `useRemForFontSize`
+
+```ts
+useRemForFontSize: boolean // Default: true
+```
+
+Should `px` values for `fontSize` be converted to `rem`?
+It is considered a best practice to use `rem` for font sizes to allow
+users to scale the font size up or down.
+
+<hr />
+
+### `styleResolution`
+
 ```ts
-type StyleXOptions = {
-  // Should insert debug class names to identify the source of the styles
-  // Also, sets the default value of `runtimeInjection`
-  //
-  // Default: `false`
-  dev: boolean,
-
-  // Are you in testing environment
-  // When true, StyleX will generate styles or functional classNames.
-  // Instead it will only output debug classNames that reference the 
-  // filePath and variables names of the styles applied.
-  //
-  // Default: `false`
-  test: boolean,
-
-  // Should StyleX generate code to inject styles at runtime?
-  // This may be useful during development but should be disabled
-  // in production.
-  //
-  // Default: the value of `dev`
-  runtimeInjection?: boolean,
-
-  // Prefix to applied to every generated className
-  //
-  // Default: 'x'
-  classNamePrefix: string,
-
-  // Should `px` values for `fontSize` be converted to `rem`?
-  // It is a best practice to use `rem` for font sizes to allow
-  // users to scale the font size up or down.
-  //
-  // Default: `true`
-  useRemForFontSize?: boolean,
-
-  // Strategy to use for merging styles
-  //
-  // Default: 'application-order'
-  styleResolution:
-    // The last style applied wins. Consistent with how inline styles work on the web.
-    | 'application-order' 
-    // More specific styles will win over less specific styles. (margin-top wins over margin)
-    // Consistent with how React Native works.
-    | 'property-specificity'
-    // @deprecated
-    // Similar to 'application-order' but incomplete and error-prone.
-    // Will be removed in a future release.
-    | 'legacy-expand-shorthands',
-
-  // Override the name of the package where you can import stylex from.
-  //
-  // Default: ['@stylexjs/stylex']
-  importSources: Array<string>,
-
-  // Enable experimental compile-time optimization to pre-compute
-  // `stylex.props` and `stylex()` function calls with conditional styles
-  // when all possible styles used are defined in the same file and known 
-  // at compile-time.
-  //
-  // Default: `false`
-  genConditionalClasses?: boolean,
-
-  // Named imports of StyleX variables are unused after compilation.
-  // Some bundlers may remove them as dead code. Causing variables to be undefined.
-  // Enable this option to prevent that by adding an import with no specifier.
-  // (e.g. `import './my-vars.stylex.js'`)
-  //
-  // Default: `false`
-  treeshakeCompensation?: boolean,
-
-  // Strategy to use for resolving variables defined with 
-  // `stylex.defineVars()`
-  // This is required if you plan to use StyleX's theming APIs
-  // 
-  // Default: undefined
-  unstable_moduleResolution?:
-    | {
-        // The module system to be used.
-        // Use this value when using `ESModules`.
-        type: 'commonJS',
-        // The absolute path to the root directory of your project.
-        rootDir: string,
-        // Override `.stylex.js` with your own extension.
-        themeFileExtension?: string,
-      }
-    | {
-        // Use this when using the Haste module system
-        // Where all files are imported by filename rather
-        // than relative paths and all filenames must be unique.
-        type: 'haste',
-        // Override `.stylex.js` with your own extension.
-        themeFileExtension?: string,
-      }
-};
+styleResolution: // Default: 'application-order'
+  | 'application-order'
+  | 'property-specificity'
+  // @deprecated
+  | 'legacy-expand-shorthands'
+```
 
+Strategy to use for merging styles.
+- **application-order**: The last style applied wins. Consistent with how
+  inline styles work on the web.
+- **property-specificity**: More specific styles will win over less specific
+  styles. Consistent with React Native. (margin-top wins over margin)
+- *Deprecated* - **legacy-expand-shorthands**: Similar to 'application-order'
+  but incomplete and error-prone. Will be removed in a future release.
+
+<hr />
+
+### `importSources`
+
+```ts
+importSources: Array<string> // Default: ['@stylexjs/stylex']
 ```
 
-...
+Override the package name where you can import stylex from.
+Used for setting up custom module aliases.
+
+<hr />
+
+### `genConditionalClasses`
+
+```ts
+genConditionalClasses: boolean // Default: false
+```
+
+Enable experimental compile-time optimization to pre-compute
+`stylex.props` and `stylex()` function calls with conditional styles
+when all possible styles used are defined in the same file and known
+at compile-time.
+
+<hr />
+
+### `treeshakeCompensation`
+
+```ts
+treeshakeCompensation: boolean // Default: false
+```
+
+Named imports of StyleX variables are unused after compilation.
+Some bundlers may remove them as dead code. Causing variables to be undefined.
+Enable this option to prevent that by adding an import with no specifier.
+(e.g. `import './my-vars.stylex.js'`)
+
+<hr />
+
+### `unstable_moduleResolution`
+
+```ts
+unstable_moduleResolution: // Default: undefined
+  | {
+      // The module system to be used.
+      // Use this value when using `ESModules`.
+      type: 'commonJS',
+      // The absolute path to the root directory of your project.
+      rootDir: string,
+      // Override `.stylex.js` with your own extension.
+      themeFileExtension?: string,
+    }
+  | {
+      // Use this when using the Haste module system
+      // Where all files are imported by filename rather
+      // than relative paths and all filenames must be unique.
+      type: 'haste',
+      // Override `.stylex.js` with your own extension.
+      themeFileExtension?: string,
+    }
+```
+
+Strategy to use for resolving variables defined with `stylex.defineVars()`
+This is required if you plan to use StyleX's theming APIs.
+
+**NOTE**: While theming APIs are stable, the shape of this configuration option
+may change in the future.
+
+

apps/docs/docs/learn/05-theming/01-defining-variables.mdx

@@ -11,10 +11,10 @@ import TabItem from '@theme/TabItem';
 
 # Defining variables
 
-:::danger
+:::info Note
 
-Theming APIs for defining and overriding CSS variables are experimental and
-subject to change.
+The [`unstable_moduleResolution`](/docs/api/configuration/babel-plugin/#unstable_moduleresolution)
+option needs to enabled in the StyleX Babel configuration to enable theming APIs.
 
 :::
 

apps/docs/docs/learn/05-theming/02-using-variables.mdx

@@ -11,10 +11,10 @@ import TabItem from '@theme/TabItem';
 
 # Using variables
 
-:::danger
+:::info Note
 
-Theming APIs for defining and overrideing CSS variables are experimental and
-subject to change.
+The [`unstable_moduleResolution`](/docs/api/configuration/babel-plugin/#unstable_moduleresolution)
+option needs to enabled in the StyleX Babel configuration to enable theming APIs.
 
 :::
 

apps/docs/docs/learn/05-theming/03-creating-themes.mdx

@@ -8,10 +8,10 @@ sidebar_position: 3
 
 # Creating themes
 
-:::danger
+:::info Note
 
-Theming APIs for defining and overriding CSS variables are experimental and
-subject to change.
+The [`unstable_moduleResolution`](/docs/api/configuration/babel-plugin/#unstable_moduleresolution)
+option needs to enabled in the StyleX Babel configuration to enable theming APIs.
 
 :::