From d940ede72f37f6e5c883e9f07bc8dff0880caeb4 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sat, 23 Nov 2024 20:13:14 +0800
Subject: [PATCH 01/18] feat(react): add `createTheme` for theme customization

---
 packages/react-docs/pages/_app.page.js        | 41 +++++------
 .../getting-started/usage/index.page.mdx      | 73 +++++++++----------
 .../pages/theme/breakpoints/index.page.mdx    |  7 +-
 .../react-docs/sandbox/create-react-app.js    | 45 +++++-------
 packages/react/__tests__/index.test.js        |  1 +
 packages/react/src/provider/TonicProvider.js  |  7 +-
 packages/react/src/theme/ThemeProvider.js     | 69 +-----------------
 packages/react/src/theme/createTheme.js       | 57 +++++++++++++++
 packages/react/src/theme/index.js             |  4 +-
 packages/react/src/theme/theme.js             | 13 +---
 .../src/theme/utils/createCSSVariableMap.js   | 40 ++++++++++
 packages/theme/src/index.js                   |  2 +-
 12 files changed, 185 insertions(+), 174 deletions(-)
 create mode 100644 packages/react/src/theme/createTheme.js
 create mode 100644 packages/react/src/theme/utils/createCSSVariableMap.js

diff --git a/packages/react-docs/pages/_app.page.js b/packages/react-docs/pages/_app.page.js
index 20a615e877..212207afae 100644
--- a/packages/react-docs/pages/_app.page.js
+++ b/packages/react-docs/pages/_app.page.js
@@ -7,6 +7,7 @@ import {
   ToastManager,
   TonicProvider,
   colorStyle as defaultColorStyle,
+  createTheme,
   theme,
   useTheme,
 } from '@tonic-ui/react';
@@ -50,28 +51,24 @@ const EmotionCacheProvider = ({
 };
 
 const App = (props) => {
-  const customTheme = useConst(() => {
-    return {
-      ...theme,
-      components: {
-        // Set default props for components here.
-        //
-        // Example:
-        // ```
-        // 'AccordionToggle': {
-        //   defaultProps: {
-        //     disabled: true,
-        //   },
-        // }
-        // ```
-      },
-      config: {
-        ...theme?.config,
-        // Enable CSS variables replacement
-        useCSSVariables: true,
-      },
-    };
-  });
+  const customTheme = useConst(() => createTheme(theme, {
+    components: {
+      // Set default props for specific components
+      //
+      // Example:
+      // ```
+      // 'ToastCloseButton': {
+      //   defaultProps: {
+      //     'aria-label': 'Close toast',
+      //   },
+      // },
+      // ```
+    },
+    config: {
+      // Enable CSS variables replacement
+      useCSSVariables: true,
+    },
+  }));
   const [initialColorMode, setColorMode] = useState(null);
   const router = useRouter();
 
diff --git a/packages/react-docs/pages/getting-started/usage/index.page.mdx b/packages/react-docs/pages/getting-started/usage/index.page.mdx
index 118dce13b8..93406bc491 100644
--- a/packages/react-docs/pages/getting-started/usage/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/usage/index.page.mdx
@@ -14,32 +14,30 @@ import {
   Box,
   TonicProvider,
   colorStyle, // [optional] Required only for customizing color styles
+  createTheme,
   theme, // [optional] Required only for customizing the theme
 } from '@tonic-ui/react';
+import { useConst } from '@tonic-ui/react-hooks';
 
 function App(props) {
-  const customTheme = {
-      ...theme,
+  const customTheme = useConst(() => createTheme(theme, {
+    components: {
       // Set default props for specific components
       //
       // Example:
-      // ```js
-      // components: {
-      //   'ToastCloseButton': {
-      //     defaultProps: {
-      //       'aria-label': 'Close toast',
-      //     },
+      // ```
+      // 'ToastCloseButton': {
+      //   defaultProps: {
+      //     'aria-label': 'Close toast',
       //   },
-      // }
+      // },
       // ```
-      components: {},
-      // Enable CSS variables
-      config: {
-        ...theme?.config,
-        useCSSVariables: true,
-      },
-    };
-  };
+    },
+    config: {
+      // Enable CSS variables replacement
+      useCSSVariables: true,
+    },
+  }));
 
   return (
     <TonicProvider
@@ -69,34 +67,32 @@ import {
   ToastManager, // allows you to create and manage toasts in the application
   TonicProvider,
   colorStyle,
+  createTheme,
   theme,
   useColorMode,
   useTheme,
 } from '@tonic-ui/react';
+import { useConst } from '@tonic-ui/react-hooks';
 
 function App(props) {
-  const customTheme = {
-      ...theme,
+  const customTheme = useConst(() => createTheme(theme, {
+    components: {
       // Set default props for specific components
       //
       // Example:
-      // ```js
-      // components: {
-      //   'ToastCloseButton': {
-      //     defaultProps: {
-      //       'aria-label': 'Close toast',
-      //     },
+      // ```
+      // 'ToastCloseButton': {
+      //   defaultProps: {
+      //     'aria-label': 'Close toast',
       //   },
-      // }
+      // },
       // ```
-      components: {},
-      // Enable CSS variables
-      config: {
-        ...theme?.config,
-        useCSSVariables: true,
-      },
-    };
-  };
+    },
+    config: {
+      // Enable CSS variables replacement
+      useCSSVariables: true,
+    },
+  }));
 
   return (
     <TonicProvider
@@ -336,24 +332,21 @@ Optionally, you can extend the theme object to override the defaults with custom
 Override the theme object and pass it to the `<ThemeProvider>` component.
 
 ```js
-import { theme } from '@tonic-ui/react';
+import { createTheme, theme } from '@tonic-ui/react';
 
 // Let's say you want to add more colors
-const customTheme = {
-  ...theme,
+const customTheme = createTheme(theme, {
   config: {
-    ...theme?.config,
     useCSSVariables: true,
   },
   colors: {
-    ...theme?.colors,
     brand: {
       90: "#1a365d",
       80: "#153e75",
       70: "#2a69ac",
     },
   },
-};
+});
 ```
 
 #### 2. Setting up the provider
diff --git a/packages/react-docs/pages/theme/breakpoints/index.page.mdx b/packages/react-docs/pages/theme/breakpoints/index.page.mdx
index 1feb2a62da..1e37bbb031 100644
--- a/packages/react-docs/pages/theme/breakpoints/index.page.mdx
+++ b/packages/react-docs/pages/theme/breakpoints/index.page.mdx
@@ -42,7 +42,7 @@ To do this, add a `breakpoints` array with additional aliases (e.g. `sm`, `md`,
 
 ```jsx disabled
 // 1. Import the theme
-import { ThemeProvider, theme } from '@tonic-ui/react';
+import { ThemeProvider, createTheme, theme } from '@tonic-ui/react';
 
 // 2. Update the breakpoints
 const breakpoints = [
@@ -59,10 +59,9 @@ breakpoints.xl = breakpoints[3];
 breakpoints['2xl'] = breakpoints[4];
 
 // 3. Extend the theme
-const customTheme = {
-  ...theme,
+const customTheme = createTheme(theme, {
   breakpoints,
-};
+});
 
 // 4. Pass the custom theme to the theme provider
 function App() {
diff --git a/packages/react-docs/sandbox/create-react-app.js b/packages/react-docs/sandbox/create-react-app.js
index d139ac7a84..c55790be80 100644
--- a/packages/react-docs/sandbox/create-react-app.js
+++ b/packages/react-docs/sandbox/create-react-app.js
@@ -28,20 +28,20 @@ import {
   ToastManager,
   TonicProvider,
   colorStyle,
+  createTheme,
   theme,
   useColorMode,
   useColorStyle,
   useTheme,
 } from '@tonic-ui/react';
+import { useConst } from '@tonic-ui/react-hooks';
+import { merge } from '@tonic-ui/utils';
 import * as React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './app';
 
-const customColorStyle = {
-  ...colorStyle,
+const customColorStyle = merge(colorStyle, {
   dark: {
-    ...colorStyle.dark,
-
     // Add custom colors here
     risk: {
       high: 'red:50',
@@ -58,8 +58,6 @@ const customColorStyle = {
     },
   },
   light: {
-    ...colorStyle.light,
-
     // Add custom colors here
     risk: {
       high: 'red:60',
@@ -75,30 +73,27 @@ const customColorStyle = {
       info: 'gray:50',
     },
   },
-};
+});
 
 const Root = (props) => {
-  const customTheme = {
-    ...theme,
-    // Set default props for specific components
-    //
-    // Example:
-    // \`\`\`js
-    // components: {
-    //   'ToastCloseButton': {
-    //     defaultProps: {
-    //       'aria-label': 'Close toast',
-    //     },
-    //   },
-    // }
-    // \`\`\`
-    components: {},
-    // Enable CSS variables
+  const customTheme = useConst(() => createTheme(theme, {
+    components: {
+      // Set default props for specific components
+      //
+      // Example:
+      // \`\`\`
+      // 'ToastCloseButton': {
+      //   defaultProps: {
+      //     'aria-label': 'Close toast',
+      //   },
+      // },
+      // \`\`\`
+    },
     config: {
-      ...theme?.config,
+      // Enable CSS variables replacement
       useCSSVariables: true,
     },
-  };
+  }));
 
   return (
     <TonicProvider
diff --git a/packages/react/__tests__/index.test.js b/packages/react/__tests__/index.test.js
index f83db6a4b4..d9a7f936c9 100644
--- a/packages/react/__tests__/index.test.js
+++ b/packages/react/__tests__/index.test.js
@@ -230,6 +230,7 @@ test('should match expected exports', () => {
 
     // theme
     'ThemeProvider',
+    'createTheme',
     'theme',
     'useTheme',
 
diff --git a/packages/react/src/provider/TonicProvider.js b/packages/react/src/provider/TonicProvider.js
index ca81bcff32..3d682e3e85 100644
--- a/packages/react/src/provider/TonicProvider.js
+++ b/packages/react/src/provider/TonicProvider.js
@@ -6,14 +6,11 @@ import { CSSBaseline } from '../css-baseline';
 
 const TonicProvider = ({
   children,
-  colorMode: colorModeProps,
-  colorStyle: colorStyleProps,
+  colorMode: colorModeProps = {},
+  colorStyle: colorStyleProps = {},
   theme,
   useCSSBaseline = false,
 }) => {
-  colorModeProps = colorModeProps ?? {};
-  colorStyleProps = colorStyleProps ?? {};
-
   if (typeof colorModeProps !== 'object') {
     console.error(
       'TonicProvider: "colorMode" prop must be an object if provided.\n' +
diff --git a/packages/react/src/theme/ThemeProvider.js b/packages/react/src/theme/ThemeProvider.js
index 8bfbbefa80..4394c2dc69 100644
--- a/packages/react/src/theme/ThemeProvider.js
+++ b/packages/react/src/theme/ThemeProvider.js
@@ -1,83 +1,20 @@
 import {
   ThemeProvider as StyledEngineThemeProvider,
 } from '@emotion/react';
-import originalTheme from '@tonic-ui/theme';
-import { ensurePlainObject, ensureString } from 'ensure-type';
-import React, { useMemo } from 'react';
+import React from 'react';
 import { DefaultPropsProvider } from '../default-props';
 import CSSVariables from './CSSVariables';
 import defaultTheme from './theme';
-import flatten from './utils/flatten';
-import toCSSVariable from './utils/toCSSVariable';
-
-const originalThemeScales = Object.keys(originalTheme);
-
-/**
- * Generate CSS variable map for a given theme object.
- *
- * @param {object} theme - The object containing the theme values.
- * @param {object} [options] - The options object.
- * @param {string} [options.prefix] - A prefix to prepend to each generated CSS variable.
- *
- * @example
- * ```js
- * const theme = {
- *   colors: {
- *     'blue:50': '#578aef',
- *   },
- * };
- * createCSSVariableMap(theme, { prefix: 'tonic' });
- * // => {
- * //   '--tonic-colors-blue-50': '#578aef'
- * // }
- * ```
- */
-const createCSSVariableMap = (theme, options) => {
-  const prefix = ensureString(options?.prefix);
-  const tokens = flatten(theme);
-  const cssVariableMap = {};
-
-  for (const [name, value] of Object.entries(tokens)) {
-    // name='colors.blue:50', prefix='tonic'
-    // => '--tonic-colors-blue-50'
-    const variable = toCSSVariable(name, { prefix });
-    cssVariableMap[variable] = value;
-  }
-
-  return cssVariableMap;
-};
 
 const ThemeProvider = ({
   children,
   theme: themeProp,
 }) => {
   const theme = themeProp ?? defaultTheme;
-  const computedTheme = useMemo(() => {
-    const themeConfig = {
-      ...defaultTheme.config,
-      ...theme?.config,
-    };
-
-    // Filter only the theme scales that are supported by the original theme
-    const normalizedTheme = Object.fromEntries(
-      Object.entries(ensurePlainObject(theme)).filter(
-        ([key]) => originalThemeScales.includes(key)
-      )
-    );
-
-    // Create CSS variable map for the theme
-    const cssVariableMap = createCSSVariableMap(normalizedTheme, { prefix: themeConfig.prefix });
-
-    return {
-      ...theme,
-      config: themeConfig,
-      __cssVariableMap: cssVariableMap,
-    };
-  }, [theme]);
 
   return (
-    <StyledEngineThemeProvider theme={computedTheme}>
-      <DefaultPropsProvider value={computedTheme.components}>
+    <StyledEngineThemeProvider theme={theme}>
+      <DefaultPropsProvider value={theme?.components}>
         <CSSVariables />
         {children}
       </DefaultPropsProvider>
diff --git a/packages/react/src/theme/createTheme.js b/packages/react/src/theme/createTheme.js
new file mode 100644
index 0000000000..5e033c0e1d
--- /dev/null
+++ b/packages/react/src/theme/createTheme.js
@@ -0,0 +1,57 @@
+import { merge } from '@tonic-ui/utils';
+import { ensurePlainObject } from 'ensure-type';
+import createCSSVariableMap from './utils/createCSSVariableMap';
+
+const defaultCSSVariablePrefix = 'tonic';
+
+const cssVariableScales = [
+  'borders',
+  'breakpoints',
+  'colors',
+  'fonts',
+  'fontSizes',
+  'fontWeights',
+  'letterSpacings',
+  'lineHeights',
+  'outlines',
+  'radii',
+  'shadows',
+  'sizes',
+  'space',
+  'zIndices',
+];
+
+const createTheme = (options, ...args) => {
+  // Merge provided options with default configurations
+  let theme = merge(options, {
+    config: {
+      prefix: defaultCSSVariablePrefix,
+      useCSSVariables: false,
+    },
+  });
+
+  // Ensure the components field is initialized
+  theme.components = theme.components ?? {};
+
+  // Merge additional arguments into the theme
+  theme = args.reduce((acc, arg) => merge(acc, arg), theme);
+
+  // Generate a theme object filtered to include only scales supported by CSS variables
+  const cssVariableTheme = Object.fromEntries(
+    Object.entries(ensurePlainObject(theme)).filter(
+      ([key]) => cssVariableScales.includes(key)
+    )
+  );
+
+  // Create a map of CSS variables with the appropriate prefix
+  const cssVariableMap = createCSSVariableMap(cssVariableTheme, { prefix: theme?.config?.prefix });
+
+  // Merge the CSS variable map into the theme
+  theme = merge(theme, {
+    __cssVariableMap: cssVariableMap,
+  });
+
+  return theme;
+};
+
+export default createTheme;
diff --git a/packages/react/src/theme/index.js b/packages/react/src/theme/index.js
index 2e19cb1818..bc7f208afc 100644
--- a/packages/react/src/theme/index.js
+++ b/packages/react/src/theme/index.js
@@ -1,9 +1,11 @@
 import ThemeProvider from './ThemeProvider';
-import theme from './theme';
+import createTheme from './createTheme';
 import useTheme from './useTheme';
+import theme from './theme';
 
 export {
   ThemeProvider,
+  createTheme,
   theme,
   useTheme,
 };
diff --git a/packages/react/src/theme/theme.js b/packages/react/src/theme/theme.js
index 21dd1e5e8a..7c89066a20 100644
--- a/packages/react/src/theme/theme.js
+++ b/packages/react/src/theme/theme.js
@@ -1,13 +1,6 @@
-import originalTheme from '@tonic-ui/theme';
+import tonicTheme from '@tonic-ui/theme';
+import createTheme from './createTheme';
 
-const theme = {
-  ...originalTheme,
-  config: {
-    prefix: 'tonic',
-    useCSSVariables: false,
-  },
-  components: {},
-  icons: [],
-};
+const theme = createTheme(tonicTheme);
 
 export default theme;
diff --git a/packages/react/src/theme/utils/createCSSVariableMap.js b/packages/react/src/theme/utils/createCSSVariableMap.js
new file mode 100644
index 0000000000..8fcf409fe4
--- /dev/null
+++ b/packages/react/src/theme/utils/createCSSVariableMap.js
@@ -0,0 +1,40 @@
+import { ensureString } from 'ensure-type';
+import flatten from './flatten';
+import toCSSVariable from './toCSSVariable';
+
+/**
+ * Generate CSS variable map for a given theme object.
+ *
+ * @param {object} theme - The object containing the theme values.
+ * @param {object} [options] - The options object.
+ * @param {string} [options.prefix] - A prefix to prepend to each generated CSS variable.
+ *
+ * @example
+ * ```js
+ * const theme = {
+ *   colors: {
+ *     'blue:50': '#578aef',
+ *   },
+ * };
+ * createCSSVariableMap(theme, { prefix: 'tonic' });
+ * // => {
+ * //   '--tonic-colors-blue-50': '#578aef'
+ * // }
+ * ```
+ */
+const createCSSVariableMap = (theme, options) => {
+  const prefix = ensureString(options?.prefix);
+  const tokens = flatten(theme);
+  const cssVariableMap = {};
+
+  for (const [name, value] of Object.entries(tokens)) {
+    // name='colors.blue:50', prefix='tonic'
+    // => '--tonic-colors-blue-50'
+    const variable = toCSSVariable(name, { prefix });
+    cssVariableMap[variable] = value;
+  }
+
+  return cssVariableMap;
+};
+
+export default createCSSVariableMap;
diff --git a/packages/theme/src/index.js b/packages/theme/src/index.js
index f02767257e..d7c1833c03 100644
--- a/packages/theme/src/index.js
+++ b/packages/theme/src/index.js
@@ -1,4 +1,4 @@
-import createTheme from './createTheme';
+import createTheme from './createTheme'; // deprecated
 
 const theme = createTheme('rem');
 

From 44da0316bf192ae7760c4995372d74ba7fb2454c Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sat, 23 Nov 2024 20:54:00 +0800
Subject: [PATCH 02/18] feat: add default value for the `options` parameter

---
 packages/react/src/theme/createTheme.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/theme/createTheme.js b/packages/react/src/theme/createTheme.js
index 5e033c0e1d..bbee4058ed 100644
--- a/packages/react/src/theme/createTheme.js
+++ b/packages/react/src/theme/createTheme.js
@@ -21,7 +21,7 @@ const cssVariableScales = [
   'zIndices',
 ];
 
-const createTheme = (options, ...args) => {
+const createTheme = (options = {}, ...args) => {
   // Merge provided options with default configurations
   let theme = merge(options, {
     config: {

From bf1ac8004d8c5ea378e22fc893e88d49e69c263a Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sat, 23 Nov 2024 21:58:23 +0800
Subject: [PATCH 03/18] docs: update examples

---
 .../components/color-style/index.page.mdx     |   8 +-
 .../getting-started/usage/index.page.mdx      | 111 +++++++++---------
 .../migrating-from-v1-to-v2.page.mdx          |  18 +--
 .../react-docs/sandbox/create-react-app.js    |  39 +++---
 4 files changed, 82 insertions(+), 94 deletions(-)

diff --git a/packages/react-docs/pages/components/color-style/index.page.mdx b/packages/react-docs/pages/components/color-style/index.page.mdx
index 3a2e628ef0..85829122ea 100644
--- a/packages/react-docs/pages/components/color-style/index.page.mdx
+++ b/packages/react-docs/pages/components/color-style/index.page.mdx
@@ -83,12 +83,11 @@ To override default color style, you can create a color style object in accordan
 
 ```jsx disabled
 import { Box, TonicProvider, colorStyle } from '@tonic-ui/react';
+import { merge } from '@tonic-ui/utils';
 import React from 'react';
 
-const customColorStyle = {
-  ...colorStyle,
+const customColorStyle = merge(colorStyle, {
   dark: {
-    ...colorStyle.dark,
     risk: {
       high: 'red:50',
       medium: 'yellow:50',
@@ -104,7 +103,6 @@ const customColorStyle = {
     },
   },
   light: {
-    ...colorStyle.light,
     risk: {
       high: 'red:60',
       medium: 'yellow:50',
@@ -119,7 +117,7 @@ const customColorStyle = {
       info: 'gray:50',
     },
   },
-};
+});
 
 const App = () => (
   <TonicProvider
diff --git a/packages/react-docs/pages/getting-started/usage/index.page.mdx b/packages/react-docs/pages/getting-started/usage/index.page.mdx
index 93406bc491..8c7e564996 100644
--- a/packages/react-docs/pages/getting-started/usage/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/usage/index.page.mdx
@@ -13,41 +13,40 @@ import React from 'react';
 import {
   Box,
   TonicProvider,
-  colorStyle, // [optional] Required only for customizing color styles
-  createTheme,
-  theme, // [optional] Required only for customizing the theme
+  colorStyle, // The default color style object
+  createTheme, // The function for theme customization
+  theme, // The default theme configuration
 } from '@tonic-ui/react';
-import { useConst } from '@tonic-ui/react-hooks';
 
-function App(props) {
-  const customTheme = useConst(() => createTheme(theme, {
-    components: {
-      // Set default props for specific components
-      //
-      // Example:
-      // ```
-      // 'ToastCloseButton': {
-      //   defaultProps: {
-      //     'aria-label': 'Close toast',
-      //   },
-      // },
-      // ```
-    },
-    config: {
-      // Enable CSS variables replacement
-      useCSSVariables: true,
-    },
-  }));
+const customTheme = createTheme(theme, {
+  config: {
+    // Enable CSS variables replacement
+    useCSSVariables: true,
+  },
+  components: {
+    // Set default props for specific components
+    //
+    // Example:
+    // ```
+    // 'ToastCloseButton': {
+    //   defaultProps: {
+    //     'aria-label': 'Close toast',
+    //   },
+    // },
+    // ```
+  },
+});
 
+function App(props) {
   return (
     <TonicProvider
       colorMode={{
         defaultValue: 'dark', // One of: 'dark', 'light'
       }}
       colorStyle={{
-        defaultValue: colorStyle, // Custom color style
+        defaultValue: colorStyle, // optional
       }}
-      theme={customTheme}
+      theme={customTheme} // optional
       useCSSBaseline={true} // If `true`, apply CSS reset and base styles
     >
       <Box {...props} />
@@ -72,37 +71,36 @@ import {
   useColorMode,
   useTheme,
 } from '@tonic-ui/react';
-import { useConst } from '@tonic-ui/react-hooks';
 
-function App(props) {
-  const customTheme = useConst(() => createTheme(theme, {
-    components: {
-      // Set default props for specific components
-      //
-      // Example:
-      // ```
-      // 'ToastCloseButton': {
-      //   defaultProps: {
-      //     'aria-label': 'Close toast',
-      //   },
-      // },
-      // ```
-    },
-    config: {
-      // Enable CSS variables replacement
-      useCSSVariables: true,
-    },
-  }));
+const customTheme = createTheme(theme, {
+  config: {
+    // Enable CSS variables replacement
+    useCSSVariables: true,
+  },
+  components: {
+    // Set default props for specific components
+    //
+    // Example:
+    // ```
+    // 'ToastCloseButton': {
+    //   defaultProps: {
+    //     'aria-label': 'Close toast',
+    //   },
+    // },
+    // ```
+  },
+});
 
+function App(props) {
   return (
     <TonicProvider
       colorMode={{
         defaultValue: 'dark', // One of: 'dark', 'light'
       }}
       colorStyle={{
-        defaultValue: colorStyle, // Custom color style
+        defaultValue: colorStyle, // optional
       }}
-      theme={customTheme}
+      theme={customTheme} // optional
       useCSSBaseline={true} // If `true`, apply CSS reset and base styles
     >
       <ToastManager
@@ -217,13 +215,11 @@ Tonic UI supports converting theme tokens defined in the theme to CSS variables.
 
 ```jsx
 <TonicProvider
-  theme={{
-    ...theme,
+  theme={merge(theme, {
     config: {
-      ...theme?.config,
       useCSSVariables: true,
     },
-  }}
+  })}
 />
 ```
 
@@ -259,12 +255,11 @@ To override default color style, you can create a color style object according t
 
 ```js
 import { colorStyle } from '@tonic-ui/react';
+import { merge } from '@tonic-ui/utils';
 
 // Let's say you want to define color style for your components
-const customColorStyle = {
-  ...colorStyle,
+const customColorStyle = merge(colorStyle, {
   dark: {
-    ...colorStyle.dark,
     risk: {
       high: 'red:50',
       medium: 'yellow:50',
@@ -280,7 +275,6 @@ const customColorStyle = {
     },
   },
   light: {
-    ...colorStyle.light,
     risk: {
       high: 'red:60',
       medium: 'yellow:50',
@@ -295,7 +289,7 @@ const customColorStyle = {
       info: 'gray:50',
     },
   },
-};
+});
 ```
 
 #### 2. Setting up the provider
@@ -332,7 +326,10 @@ Optionally, you can extend the theme object to override the defaults with custom
 Override the theme object and pass it to the `<ThemeProvider>` component.
 
 ```js
-import { createTheme, theme } from '@tonic-ui/react';
+import {
+  createTheme,
+  theme,
+} from '@tonic-ui/react';
 
 // Let's say you want to add more colors
 const customTheme = createTheme(theme, {
diff --git a/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx b/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx
index a934fb3e29..9f6994495b 100644
--- a/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx
+++ b/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx
@@ -40,12 +40,10 @@ To use previously defined `severity` and `chart` colors, you need to pass a cust
 ```jsx disabled
 import React from 'react';
 import { Box, TonicProvider, colorStyle } from '@tonic-ui/react';
+import { merge } from '@tonic-ui/utils';
 
-const customColorStyle = {
-  ...colorStyle,
+const customColorStyle = merge(colorStyle, {
    dark: {
-    ...colorStyle.dark,
-
     // deprecated
     severity: {
       critical: 'magenta:60',
@@ -77,8 +75,6 @@ const customColorStyle = {
     },
   },
   light: {
-    ...colorStyle.light,
-
     // deprecated
     severity: {
       critical: 'magenta:60',
@@ -109,7 +105,7 @@ const customColorStyle = {
       },
     },
   },
-};
+});
 
 const App = (props) => (
   <TonicProvider
@@ -128,12 +124,11 @@ Here is the recommended configuration for utilizing the `risk` and `severity` co
 
 ```js
 import { colorStyle } from '@tonic-ui/react';
+import { merge } from '@tonic-ui/utils';
 
 // Let's say you want to define color style for your components
-const customColorStyle = {
-  ...colorStyle,
+const customColorStyle = merge(colorStyle, {
   dark: {
-    ...colorStyle.dark,
     risk: {
       high: 'red:50',
       medium: 'yellow:50',
@@ -149,7 +144,6 @@ const customColorStyle = {
     },
   },
   light: {
-    ...colorStyle.light,
     risk: {
       high: 'red:60',
       medium: 'yellow:50',
@@ -164,7 +158,7 @@ const customColorStyle = {
       info: 'gray:50',
     },
   },
-};
+});
 ```
 
 ### Date Pickers
diff --git a/packages/react-docs/sandbox/create-react-app.js b/packages/react-docs/sandbox/create-react-app.js
index c55790be80..db90238ef8 100644
--- a/packages/react-docs/sandbox/create-react-app.js
+++ b/packages/react-docs/sandbox/create-react-app.js
@@ -34,7 +34,6 @@ import {
   useColorStyle,
   useTheme,
 } from '@tonic-ui/react';
-import { useConst } from '@tonic-ui/react-hooks';
 import { merge } from '@tonic-ui/utils';
 import * as React from 'react';
 import ReactDOM from 'react-dom/client';
@@ -75,26 +74,26 @@ const customColorStyle = merge(colorStyle, {
   },
 });
 
-const Root = (props) => {
-  const customTheme = useConst(() => createTheme(theme, {
-    components: {
-      // Set default props for specific components
-      //
-      // Example:
-      // \`\`\`
-      // 'ToastCloseButton': {
-      //   defaultProps: {
-      //     'aria-label': 'Close toast',
-      //   },
-      // },
-      // \`\`\`
-    },
-    config: {
-      // Enable CSS variables replacement
-      useCSSVariables: true,
-    },
-  }));
+const customTheme = createTheme(theme, {
+  config: {
+    // Enable CSS variables replacement
+    useCSSVariables: true,
+  },
+  components: {
+    // Set default props for specific components
+    //
+    // Example:
+    // \`\`\`
+    // 'ToastCloseButton': {
+    //   defaultProps: {
+    //     'aria-label': 'Close toast',
+    //   },
+    // },
+    // \`\`\`
+  },
+});
 
+const Root = (props) => {
   return (
     <TonicProvider
       colorMode={{

From c58827d8d2a7e5babda0e87388c2c1acefd0c5dc Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sat, 23 Nov 2024 22:18:02 +0800
Subject: [PATCH 04/18] chore: add `tonic-ui-945.md` changeset

---
 .changeset/tonic-ui-945.md | 6 ++++++
 1 file changed, 6 insertions(+)
 create mode 100644 .changeset/tonic-ui-945.md

diff --git a/.changeset/tonic-ui-945.md b/.changeset/tonic-ui-945.md
new file mode 100644
index 0000000000..690a3d6553
--- /dev/null
+++ b/.changeset/tonic-ui-945.md
@@ -0,0 +1,6 @@
+---
+"@tonic-ui/react": patch
+"@tonic-ui/theme": minor
+---
+
+feat(react): add `createTheme` for theme customization

From 1f415b9ff8dc7a68bb501b8be9b36532ee814103 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sun, 24 Nov 2024 10:44:01 +0800
Subject: [PATCH 05/18] docs: update getting started usage guide

---
 .../getting-started/usage/index.page.mdx      | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/packages/react-docs/pages/getting-started/usage/index.page.mdx b/packages/react-docs/pages/getting-started/usage/index.page.mdx
index 8c7e564996..dba000b734 100644
--- a/packages/react-docs/pages/getting-started/usage/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/usage/index.page.mdx
@@ -12,10 +12,10 @@ Go to the root of your application and do the following:
 import React from 'react';
 import {
   Box,
-  TonicProvider,
-  colorStyle, // The default color style object
-  createTheme, // The function for theme customization
-  theme, // The default theme configuration
+  TonicProvider, // Provides theme and context for Tonic UI components
+  colorStyle,    // Default color style object
+  createTheme,   // For theme customization (introduced in v2.5.0)
+  theme,         // Default theme configuration
 } from '@tonic-ui/react';
 
 const customTheme = createTheme(theme, {
@@ -62,14 +62,15 @@ import { Global, css } from '@emotion/react';
 import React from 'react';
 import {
   Box,
-  PortalManager, // allows you to create and manage portals in the application
-  ToastManager, // allows you to create and manage toasts in the application
-  TonicProvider,
-  colorStyle,
-  createTheme,
-  theme,
-  useColorMode,
-  useTheme,
+  PortalManager, // Manages portals in the application
+  ToastManager,  // Manages toasts in the application
+  TonicProvider, // Provides theme and context for Tonic UI components
+  colorStyle,    // Default color style object
+  createTheme,   // For theme customization (introduced in v2.5.0)
+  theme,         // Default theme configuration
+  useColorMode,  // Hook to manage color mode (e.g., light/dark)
+  useColorStyle, // Hook to manage color style
+  useTheme,      // Hook to access the theme object
 } from '@tonic-ui/react';
 
 const customTheme = createTheme(theme, {
@@ -133,7 +134,7 @@ function App(props) {
 
 function Layout(props) {
   const [colorMode] = useColorMode();
-  const [colorStyle] = useColorStyle({ colorMode });
+  const [colorStyle] = useColorStyle();
   const { colors, fontSizes, lineHeights } = useTheme();
   const backgroundColor = colorStyle.background.primary;
   const color = colorStyle.color.primary;
@@ -202,7 +203,9 @@ function Layout(props) {
 Sometimes you may need to apply base CSS styles to your application. Tonic UI provides an optional `CSSBaseline` component that fixes some inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements. `CSSBaseline` is recommended to add at the root to ensure all components work correctly.
 
 ```jsx disabled
-<TonicProvider useCSSBaseline={true}>
+<TonicProvider
+  useCSSBaseline={true}
+>
   <App />
 </TonicProvider>
 ```
@@ -296,14 +299,9 @@ const customColorStyle = merge(colorStyle, {
 
 ```jsx disabled
 <TonicProvider
-  colorMode={{
-    defaultValue: 'dark',
-  }}
   colorStyle={{
     defaultValue: customColorStyle,
   }}
-  theme={customTheme}
-  useCSSBaseline={true}
 >
   {children}
 </TonicProvider>
@@ -349,7 +347,9 @@ const customTheme = createTheme(theme, {
 #### 2. Setting up the provider
 
 ```jsx
-<TonicProvider theme={customTheme}>
+<TonicProvider
+  theme={customTheme}
+>
   {children}
 </TonicProvider>
 ```

From 67fd9bdfaa26eab2e7a6868532cbf2aa9c09f4f3 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Sun, 24 Nov 2024 11:03:51 +0800
Subject: [PATCH 06/18] docs: replace `\`\`\`jsx disabled` with `\`\`\`jsx` for
 the code block

---
 .../pages/components/alert/index.page.mdx     |  4 ++--
 .../pages/components/button/index.page.mdx    |  4 ++--
 .../pages/components/checkbox/index.page.mdx  |  2 +-
 .../components/color-mode/index.page.mdx      | 16 +++++++--------
 .../color-mode/useColorMode.page.mdx          |  2 +-
 .../components/color-style/index.page.mdx     |  6 +++---
 .../components/css-baseline/index.page.mdx    |  2 +-
 .../date-pickers/date-picker/index.page.mdx   |  4 ++--
 .../pages/components/drawer/index.page.mdx    |  4 ++--
 .../pages/components/menu/index.page.mdx      |  2 +-
 .../pages/components/modal/index.page.mdx     |  4 ++--
 .../pages/components/popover/index.page.mdx   | 12 +++++------
 .../components/portal-manager/index.page.mdx  | 10 +++++-----
 .../pages/components/radio/index.page.mdx     |  2 +-
 .../pages/components/scrollbar/index.page.mdx |  4 ++--
 .../pages/components/skeleton/index.page.mdx  |  2 +-
 .../pages/components/switch/index.page.mdx    |  2 +-
 .../pages/components/table/index.page.mdx     | 10 +++++-----
 .../pages/components/tag/index.page.mdx       |  4 ++--
 .../components/toast-manager/index.page.mdx   |  8 ++++----
 .../pages/components/toast/index.page.mdx     |  4 ++--
 .../pages/components/tooltip/index.page.mdx   |  6 +++---
 .../pages/components/tree/index.page.mdx      |  6 +++---
 .../getting-started/security/index.page.mdx   |  4 ++--
 .../the-sx-prop/index.page.mdx                |  2 +-
 .../getting-started/usage/index.page.mdx      | 20 +++++++++----------
 26 files changed, 73 insertions(+), 73 deletions(-)

diff --git a/packages/react-docs/pages/components/alert/index.page.mdx b/packages/react-docs/pages/components/alert/index.page.mdx
index 4f96319ddb..5765451185 100644
--- a/packages/react-docs/pages/components/alert/index.page.mdx
+++ b/packages/react-docs/pages/components/alert/index.page.mdx
@@ -52,7 +52,7 @@ If not specified, the default icon will be used based on the `severity` prop.
 
 The `isClosable` prop is used to make an alert closable by adding a close button to it. By default, the value of `isClosable` is false. To make an alert closable, set `isClosable` to true.
 
-```jsx disabled
+```jsx
 <Alert variant="solid" severity="success" isClosable onClose={onClose}>
   <Text>This is a success alert.</Text>
 </Alert>
@@ -66,7 +66,7 @@ The `AlertCloseButton` component provides an easy way to add a close button to a
 
 Besides the default functionality of the `AlertCloseButton`, you can also pass additional props, such as `data-test` or `data-tracking` attributes, to the `AlertCloseButton` component as needed.
 
-```jsx disabled
+```jsx
 <Alert variant="solid" severity="success" onClose={onClose}>
   <Text pr="10x">This is a success alert.</Text>
   <AlertCloseButton top={3} right={7} position="absolute" data-test="alert-close-button" />
diff --git a/packages/react-docs/pages/components/button/index.page.mdx b/packages/react-docs/pages/components/button/index.page.mdx
index f2988f9004..fc703d74ba 100644
--- a/packages/react-docs/pages/components/button/index.page.mdx
+++ b/packages/react-docs/pages/components/button/index.page.mdx
@@ -34,7 +34,7 @@ You can make buttons look inactive or active by adding the `disabled` or `select
 
 If the `disabled` prop is set (or set to `true`), the button will have a `disabled` attribute and not respond to user interactions.
 
-```jsx disabled
+```jsx
 <button type="button" disabled aria-disabled="true">Button</button>
 ```
 
@@ -46,7 +46,7 @@ To customize the visual appearance of the disabled state, pass the `_disabled` s
 
 If the `selected` prop is set (or set to `true`), the button will have both `pointer-events: none` style and `tabindex="-1"` attribute. This will prevent the button from receiving pointer events and will not be reachable via sequential keyboard navigation.
 
-```jsx disabled
+```jsx
 <button type="button" aria-selected="true" tabindex="-1">Button</button>
 ```
 
diff --git a/packages/react-docs/pages/components/checkbox/index.page.mdx b/packages/react-docs/pages/components/checkbox/index.page.mdx
index a1c0ae4be9..220e6c9c6b 100644
--- a/packages/react-docs/pages/components/checkbox/index.page.mdx
+++ b/packages/react-docs/pages/components/checkbox/index.page.mdx
@@ -45,7 +45,7 @@ WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
 * All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the `<label>` element.
 * When a label can't be used, it's necessary to add an attribute directly to the input component. In this case, you can apply the additional attribute (e.g. `aria-label`, `aria-labelledby`, `title`) via the `inputProps` prop.
 
-```jsx disabled
+```jsx
 <Checkbox
   inputProps={{
     'aria-label': 'Label',
diff --git a/packages/react-docs/pages/components/color-mode/index.page.mdx b/packages/react-docs/pages/components/color-mode/index.page.mdx
index bcc49ef2da..13d315dba8 100644
--- a/packages/react-docs/pages/components/color-mode/index.page.mdx
+++ b/packages/react-docs/pages/components/color-mode/index.page.mdx
@@ -8,7 +8,7 @@ By using `TonicProvider` at root of your application, it will add `ColorModeProv
 
 To get color mode working correctly, you may have to pass `colorMode` config to `TonicProvider` with `defaultValue` set to `dark` or `light`.
 
-```jsx disabled
+```jsx
 import React from 'react';
 import { Box, TonicProvider } from '@tonic-ui/react';
 
@@ -34,7 +34,7 @@ function App(props) {
 
 The above setup is equivalent to:
 
-```jsx disabled
+```jsx
 <ColorModeProvider defaultValue="dark">
   <Box {...props} />
 </ColorModeProvider>
@@ -44,11 +44,11 @@ The above setup is equivalent to:
 
 To opt the entire page into the user's color scheme preferences declare `color-scheme` on the document's root element.
 
-```jsx disabled
+```jsx
 import { Global, css } from '@emotion/react';
 ```
 
-```jsx disabled
+```jsx
 <Global
   styles={css`
     :root, :host {
@@ -62,7 +62,7 @@ import { Global, css } from '@emotion/react';
 
 ### Use default color mode
 
-```jsx disabled
+```jsx
 <TonicProvider
   colorMode={{
     defaultValue: 'dark',
@@ -76,7 +76,7 @@ import { Global, css } from '@emotion/react';
 
 This example uses the default color mode for the first render, and then switches to the system color mode for the rest of time.
 
-```jsx disabled
+```jsx
 <TonicProvider
   colorMode={{
     defaultValue: 'dark', // optional
@@ -89,7 +89,7 @@ This example uses the default color mode for the first render, and then switches
 
 ### Controlled color mode
 
-```jsx disabled
+```jsx
 <TonicProvider
   colorMode={{
     value: 'dark',
@@ -101,7 +101,7 @@ This example uses the default color mode for the first render, and then switches
 
 ### Controlled color mode with a toggle function
 
-```jsx disabled
+```jsx
 function App({ children }) {
   const [colorMode, toggleColorMode] = useToggle();
 
diff --git a/packages/react-docs/pages/components/color-mode/useColorMode.page.mdx b/packages/react-docs/pages/components/color-mode/useColorMode.page.mdx
index 6043ee0588..ea0c1316f3 100644
--- a/packages/react-docs/pages/components/color-mode/useColorMode.page.mdx
+++ b/packages/react-docs/pages/components/color-mode/useColorMode.page.mdx
@@ -10,7 +10,7 @@ import { useColorStyle } from '@tonic-ui/react';
 
 ## Usage
 
-```jsx disabled
+```jsx
 import { Global, css } from '@emotion/react';
 import {
   Button,
diff --git a/packages/react-docs/pages/components/color-style/index.page.mdx b/packages/react-docs/pages/components/color-style/index.page.mdx
index 85829122ea..2696bd9b84 100644
--- a/packages/react-docs/pages/components/color-style/index.page.mdx
+++ b/packages/react-docs/pages/components/color-style/index.page.mdx
@@ -28,7 +28,7 @@ Tonic UI comes with a color style system that defines functional color values.
 
 By using `TonicProvider` at root of your application, it will add `ColorStyleProvider` internally to provide the color style context to all components. The default color style will be added automatically.
 
-```jsx disabled
+```jsx
 import React from 'react';
 import { Box, TonicProvider } from '@tonic-ui/react';
 import { colorStyle } from '@tonic-ui/react';
@@ -55,7 +55,7 @@ function App(props) {
 
 The above setup is equivalent to:
 
-```jsx disabled
+```jsx
 <ColorStyleProvider>
   <Box {...props} />
 </ColorStyleProvider>
@@ -81,7 +81,7 @@ To manage color style in your application, you can use the [useColorStyle](../co
 
 To override default color style, you can create a color style object in accordance to the color mode, and pass the object to `TonicProvider` with either the `value` or the `defaultValue` property.
 
-```jsx disabled
+```jsx
 import { Box, TonicProvider, colorStyle } from '@tonic-ui/react';
 import { merge } from '@tonic-ui/utils';
 import React from 'react';
diff --git a/packages/react-docs/pages/components/css-baseline/index.page.mdx b/packages/react-docs/pages/components/css-baseline/index.page.mdx
index f5ce6ebf67..e48bf41a03 100644
--- a/packages/react-docs/pages/components/css-baseline/index.page.mdx
+++ b/packages/react-docs/pages/components/css-baseline/index.page.mdx
@@ -16,7 +16,7 @@ import { CSSBaseline } from '@tonic-ui/react';
 
 ## Usage
 
-```jsx disabled
+```jsx
 <>
   <CSSBaseline />
   <App />
diff --git a/packages/react-docs/pages/components/date-pickers/date-picker/index.page.mdx b/packages/react-docs/pages/components/date-pickers/date-picker/index.page.mdx
index 4d17bdfbd6..d1dd574cc7 100644
--- a/packages/react-docs/pages/components/date-pickers/date-picker/index.page.mdx
+++ b/packages/react-docs/pages/components/date-pickers/date-picker/index.page.mdx
@@ -14,7 +14,7 @@ import {
 
 The following example demonstrates a simple example of the `DatePicker` component.
 
-```jsx disabled
+```jsx
 <DatePicker
   closeOnSelect={true}
   inputFormat="yyyy-MM-dd"
@@ -38,7 +38,7 @@ The following example demonstrates a simple example of the `DatePicker` componen
 
 Note that the `DateInput` component is currently not provided by the `@tonic-ui/react` package. You have to write your own or refer to the following code to [get started](../../components/input-control).
 
-```jsx disabled
+```jsx
 // import
 import { InputControl, InputAdornment } from '@tonic-ui/react';
 import { CalendarIcon } from '@tonic-ui/react-icons';
diff --git a/packages/react-docs/pages/components/drawer/index.page.mdx b/packages/react-docs/pages/components/drawer/index.page.mdx
index c36655fde2..a6fbbaae20 100644
--- a/packages/react-docs/pages/components/drawer/index.page.mdx
+++ b/packages/react-docs/pages/components/drawer/index.page.mdx
@@ -31,7 +31,7 @@ Click the button below to toggle a drawer. The drawer will show up on either sid
 
 The `isClosable` prop is used to make a drawer closable by adding a close button to it. By default, the value of `isClosable` is false. To make a drawer closable, set `isClosable` to true.
 
-```jsx disabled
+```jsx
 <Drawer isOpen={isOpen} isClosable onClose={onClose}>
   <DrawerOverlay />
   <DrawerContent>
@@ -48,7 +48,7 @@ The `DrawerCloseButton` component provides an easy way to add a close button to
 
 Besides the default functionality of the `DrawerCloseButton`, you can also pass additional props, such as `data-test` or `data-tracking` attributes, to the `DrawerCloseButton` component as needed.
 
-```jsx disabled
+```jsx
 <Drawer isOpen={isOpen} onClose={onClose}>
   <DrawerOverlay />
   <DrawerContent>
diff --git a/packages/react-docs/pages/components/menu/index.page.mdx b/packages/react-docs/pages/components/menu/index.page.mdx
index 2f5360a936..8bef1f4e90 100644
--- a/packages/react-docs/pages/components/menu/index.page.mdx
+++ b/packages/react-docs/pages/components/menu/index.page.mdx
@@ -86,7 +86,7 @@ You can also customize the indicator by passing a component as children or a fun
 
 `MenuButton` composes `Button`, `MenuToggle`, and `MenuToggleIcon` to create a button that opens the menu. It's an useful alternative to `MenuToggle` when the toggle is a button.
 
-```jsx disabled
+```jsx
 const MenuButton = (props) => {
   // Define custom styles for the menu button
   const styleProps = {
diff --git a/packages/react-docs/pages/components/modal/index.page.mdx b/packages/react-docs/pages/components/modal/index.page.mdx
index af477858c8..1367ab65bb 100644
--- a/packages/react-docs/pages/components/modal/index.page.mdx
+++ b/packages/react-docs/pages/components/modal/index.page.mdx
@@ -37,7 +37,7 @@ Click the button below to toggle a modal. The modal will show up in the center o
 
 The `isClosable` prop is used to make a modal closable by adding a close button to it. By default, the value of `isClosable` is false. To make a modal closable, set `isClosable` to true.
 
-```jsx disabled
+```jsx
 <Modal isOpen={isOpen} isClosable onClose={onClose}>
   <ModalOverlay />
   <ModalContent>
@@ -54,7 +54,7 @@ The `ModalCloseButton` component provides an easy way to add a close button to a
 
 Besides the default functionality of the `ModalCloseButton`, you can also pass additional props, such as `data-test` or `data-tracking` attributes, to the `ModalCloseButton` component as needed.
 
-```jsx disabled
+```jsx
 <Modal isOpen={isOpen} onClose={onClose}>
   <ModalOverlay />
   <ModalContent>
diff --git a/packages/react-docs/pages/components/popover/index.page.mdx b/packages/react-docs/pages/components/popover/index.page.mdx
index f8e4f7f531..0e79a9cb84 100644
--- a/packages/react-docs/pages/components/popover/index.page.mdx
+++ b/packages/react-docs/pages/components/popover/index.page.mdx
@@ -25,7 +25,7 @@ import {
 
 To create an accessible popover, it should allow users to access it using the tab key on a keyboard. When it opens, the focus status will be set to `PopoverContent`. When it closes, the focus status will return to `PopoverTrigger`.
 
-```jsx disabled
+```jsx
 <Popover>
   <PopoverTrigger>
     <Button variant="secondary">
@@ -42,7 +42,7 @@ To create an accessible popover, it should allow users to access it using the ta
 
 By default, you can only pass a single React element child to the `PopoverTrigger` component.
 
-```jsx disabled
+```jsx
 <PopoverTrigger>
   <Button variant="secondary">
     Interactive Trigger
@@ -52,7 +52,7 @@ By default, you can only pass a single React element child to the `PopoverTrigge
 
 If you need to pass more than one child element or non-element children, wrap them in an element or pass the `shouldWrapChildren` prop.
 
-```jsx disabled
+```jsx
 <PopoverTrigger outline={0} tabIndex={-1}>
   <Text display="inline-block">
     Non-interactive Trigger
@@ -60,13 +60,13 @@ If you need to pass more than one child element or non-element children, wrap th
 </PopoverTrigger>
 ```
 
-```jsx disabled
+```jsx
 <PopoverTrigger outline={0} shouldWrapChildren tabIndex={-1}>
   Non-interactive Trigger
 </PopoverTrigger>
 ```
 
-```jsx disabled
+```jsx
 <PopoverTrigger outline={0} shouldWrapChildren tabIndex={-1}>
   <MenuIcon height="5x" mr="2x" />
   <Text display="inline-block">Non-interactive Trigger</Text>
@@ -171,7 +171,7 @@ To access the internal state of the popover, you can use the Function as Child C
 
 Use the `placement` prop to control the placement of the popover.
 
-```jsx disabled
+```jsx
 <Popover placement="top" trigger="hover">
   <PopoverTrigger>
     <LinkButton>Trigger</LinkButton>
diff --git a/packages/react-docs/pages/components/portal-manager/index.page.mdx b/packages/react-docs/pages/components/portal-manager/index.page.mdx
index 5f796eda76..9e67b252a1 100644
--- a/packages/react-docs/pages/components/portal-manager/index.page.mdx
+++ b/packages/react-docs/pages/components/portal-manager/index.page.mdx
@@ -14,7 +14,7 @@ import {
 
 Next, wrap your application with `PortalManager`:
 
-```jsx disabled
+```jsx
 <PortalManager>
   <App />
 </PortalManager>
@@ -22,7 +22,7 @@ Next, wrap your application with `PortalManager`:
 
 Once `PortalManager` is set up, any component can use the `usePortalManager` Hook to create and manage portals.
 
-```jsx disabled
+```jsx
 import { usePortalManager } from '@tonic-ui/react';
 
 function MyComponent() {
@@ -41,7 +41,7 @@ function MyComponent() {
 
 In the example above, `MyModal` is a wrapper component that represents the modal you want to render. The `onClose` prop is a function that is passed to the modal component, and can be used to close the modal.
 
-```jsx disabled
+```jsx
 const MyModal = forwardRef(
   {
     onClose,
@@ -76,7 +76,7 @@ const MyModal = forwardRef(
 
 To remove a portal, call the callback function passed by the `portal` method.
 
-```jsx disabled
+```jsx
 const id = portal((close) => (
   <MyModal onClose={close} />
 ));
@@ -84,7 +84,7 @@ const id = portal((close) => (
 
 Or use the `remove` method by passing the portal's unique id as an argument.
 
-```jsx disabled
+```jsx
 portal.remove(id);
 ```
 
diff --git a/packages/react-docs/pages/components/radio/index.page.mdx b/packages/react-docs/pages/components/radio/index.page.mdx
index b72e6f7bd4..e2f24de5f8 100644
--- a/packages/react-docs/pages/components/radio/index.page.mdx
+++ b/packages/react-docs/pages/components/radio/index.page.mdx
@@ -39,7 +39,7 @@ WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/radio/
 * All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the `<label>` element.
 * When a label can't be used, it's necessary to add an attribute directly to the input component. In this case, you can apply the additional attribute (e.g. `aria-label`, `aria-labelledby`, `title`) via the `inputProps` prop.
 
-```jsx disabled
+```jsx
 <Radio
   inputProps={{
     'aria-label': 'Label',
diff --git a/packages/react-docs/pages/components/scrollbar/index.page.mdx b/packages/react-docs/pages/components/scrollbar/index.page.mdx
index e2b4cccd39..83fab84b37 100644
--- a/packages/react-docs/pages/components/scrollbar/index.page.mdx
+++ b/packages/react-docs/pages/components/scrollbar/index.page.mdx
@@ -88,7 +88,7 @@ Check out the demo below to see how you can integrate React Virtuoso with a cust
 
 To achieve this, you'll need to create a `CustomScrollbar` component and pass it as the `Scroller` for the `Virtuoso` component.
 
-```jsx disabled
+```jsx
 <Virtuoso
   components={{
     Scroller: CustomScrollbar,
@@ -105,7 +105,7 @@ To achieve this, you'll need to create a `CustomScrollbar` component and pass it
 
 In the `CustomScrollbar` component, pass `props` and `ref` to `scrollViewProps` and `scrollViewRef`, respectively. This ensures that the props coming from React Virtuoso are passed down correctly, allowing its scrolling behavior to integrate seamlessly into the `Scrollbar`.
 
-```jsx disabled
+```jsx
 const CustomScrollbar = forwardRef((inProps, ref) => {
   const { children, ...props } = inProps;
 
diff --git a/packages/react-docs/pages/components/skeleton/index.page.mdx b/packages/react-docs/pages/components/skeleton/index.page.mdx
index 1bd431575e..eb189d264a 100644
--- a/packages/react-docs/pages/components/skeleton/index.page.mdx
+++ b/packages/react-docs/pages/components/skeleton/index.page.mdx
@@ -12,7 +12,7 @@ import { Skeleton } from '@tonic-ui/react';
 
 The component is designed to be used when the data for your component might not be immediately available. For instance:
 
-```jsx disabled
+```jsx
 {image
   ? <Image src={image} width={240} height={180} />
   : <Skeleton variant="rectangle" width={240} height={120} />
diff --git a/packages/react-docs/pages/components/switch/index.page.mdx b/packages/react-docs/pages/components/switch/index.page.mdx
index e3551c21ed..71943d05e5 100644
--- a/packages/react-docs/pages/components/switch/index.page.mdx
+++ b/packages/react-docs/pages/components/switch/index.page.mdx
@@ -41,7 +41,7 @@ WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/switch/
 * All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the `<label>` element.
 * When a label can't be used, it's necessary to add an attribute directly to the input component. In this case, you can apply the additional attribute (e.g. `aria-label`, `aria-labelledby`, `title`) via the `inputProps` prop.
 
-```jsx disabled
+```jsx
 <Switch
   inputProps={{
     'aria-label': 'Label',
diff --git a/packages/react-docs/pages/components/table/index.page.mdx b/packages/react-docs/pages/components/table/index.page.mdx
index 870fab887c..fa6c7b2f24 100644
--- a/packages/react-docs/pages/components/table/index.page.mdx
+++ b/packages/react-docs/pages/components/table/index.page.mdx
@@ -74,7 +74,7 @@ If the `layout` prop is set to `flexbox`, the expanded row will appear below the
 
 Below are the code snippets that demonstrate how to render the expanded row based on the `layout` prop:
 
-```jsx disabled
+```jsx
 // layout='flexbox'
 <TableRow>
   <TableCell>Cell 1</TableCell>
@@ -91,7 +91,7 @@ Below are the code snippets that demonstrate how to render the expanded row base
 )}
 ````
 
-```jsx disabled
+```jsx
 // layout='table'
 <TableRow>
   <TableCell>Cell 1</TableCell>
@@ -149,7 +149,7 @@ const tableHeight = headerHeight + rowsToDisplay * cellHeight;
 
 2. Wrap the `TableBody` component with a `TableScrollbar` component, and set the `height` and `overflow` props of the `TableScrollbar` component to control the scrolling behavior.
 
-```jsx disabled
+```jsx
 <Table
   layout="flexbox"
   height={tableHeight}
@@ -180,7 +180,7 @@ If you want to control whether to enable the scrolling feature dynamically, you
 
 Here's an example implementation of the `ConditionalWrapper` component:
 
-```jsx disabled
+```jsx
 const ConditionalWrapper = ({
   children,
   condition,
@@ -192,7 +192,7 @@ const ConditionalWrapper = ({
 
 And here's how you can use it in your code:
 
-```jsx disabled
+```jsx
 <Table
   height={isTableScrollingEnabled ? tableHeight : undefined}
 >
diff --git a/packages/react-docs/pages/components/tag/index.page.mdx b/packages/react-docs/pages/components/tag/index.page.mdx
index b0a71c5d0f..205c5abc8a 100644
--- a/packages/react-docs/pages/components/tag/index.page.mdx
+++ b/packages/react-docs/pages/components/tag/index.page.mdx
@@ -43,7 +43,7 @@ Use the `size` prop to change the size of the `Tag`. You can set the value to `s
 
 The `isClosable` prop is used to make a tag closable by adding a close button to it. By default, the value of `isClosable` is false. To make an alert closable, set `isClosable` to true.
 
-```jsx disabled
+```jsx
 <Tag variant="solid" isClosable onClose={onClose}>
   <Text>This is a tag</Text>
 </Tag>
@@ -57,7 +57,7 @@ The `TagCloseButton` component provides an easy way to add a close button to a t
 
 Besides the default functionality of the `TagCloseButton`, you can also pass additional props, such as `data-test` or `data-tracking` attributes, to the `TagCloseButton` component as needed.
 
-```jsx disabled
+```jsx
 <Tag variant="solid" onClose={onClose}>
   <Text>This is a tag</Text>
   <TagCloseButton ml="2x" data-test="tag-close-button" />
diff --git a/packages/react-docs/pages/components/toast-manager/index.page.mdx b/packages/react-docs/pages/components/toast-manager/index.page.mdx
index 791011fa4b..ce343672a1 100644
--- a/packages/react-docs/pages/components/toast-manager/index.page.mdx
+++ b/packages/react-docs/pages/components/toast-manager/index.page.mdx
@@ -12,7 +12,7 @@ import { ToastManager } from '@tonic-ui/react';
 
 Next, wrap your application with `ToastManager`:
 
-```jsx disabled
+```jsx
 <ToastManager
   TransitionProps={{
     sx: {
@@ -38,7 +38,7 @@ Next, wrap your application with `ToastManager`:
 
 Once `ToastManager` is set up, you can use the `useToastManager` Hook to create and manage toasts from any component:
 
-```jsx disabled
+```jsx
 import { useToastManager } from '@tonic-ui/react';
 
 function MyComponent() {
@@ -78,7 +78,7 @@ function MyComponent() {
 
 The `toast` method accepts a function that generates the toast element to display. This function receives `id`, `data`, `onClose`, and `placement` as arguments.
 
-```jsx disabled
+```jsx
 toast(({ id, data, onClose, placement }) => (
   <Toast isClosable onClose={onClose}>
     This is a toast notification
@@ -100,7 +100,7 @@ See the [useToastManager](./toast-manager/useToastManager) Hook for detailed usa
 
 To control the spacing to the edges of the screen, make use of the `TransitionProps` prop in the `ToastManager`. Pass the `sx` prop to the transition component with your preferred spacing.
 
-```jsx disabled
+```jsx
 <ToastManager
   TransitionProps={{
     sx: {
diff --git a/packages/react-docs/pages/components/toast/index.page.mdx b/packages/react-docs/pages/components/toast/index.page.mdx
index dadc44a378..72ce217a0b 100644
--- a/packages/react-docs/pages/components/toast/index.page.mdx
+++ b/packages/react-docs/pages/components/toast/index.page.mdx
@@ -46,7 +46,7 @@ Setting the `icon` prop to `false` will remove the icon altogether.
 
 The `isClosable` prop is used to make a toast closable by adding a close button to it. By default, the value of `isClosable` is false. To make a toast closable, set `isClosable` to true.
 
-```jsx disabled
+```jsx
 <Toast appearance="success" isClosable onClose={onClose} width={320}>
   <Text>This is a success toast.</Text>
 </Toast>
@@ -60,7 +60,7 @@ The `ToastCloseButton` component provides an easy way to add a close button to a
 
 Besides the default functionality of the `ToastCloseButton`, you can also pass additional props, such as `data-test` or `data-tracking` attributes, to the `ToastCloseButton` component as needed.
 
-```jsx disabled
+```jsx
 <Toast appearance="success" onClose={onClose} width={320}>
   <Text pr="10x">This is a success toast.</Text>
   <ToastCloseButton top={10} right={8} position="absolute" data-test="toast-close-button" />
diff --git a/packages/react-docs/pages/components/tooltip/index.page.mdx b/packages/react-docs/pages/components/tooltip/index.page.mdx
index 6df8cfa1a6..2dacd24d91 100644
--- a/packages/react-docs/pages/components/tooltip/index.page.mdx
+++ b/packages/react-docs/pages/components/tooltip/index.page.mdx
@@ -23,7 +23,7 @@ import { Tooltip } from '@tonic-ui/react';
 
 By default, you have to pass a single React element child to the `Tooltip` component.
 
-```jsx disabled
+```jsx
 <Tooltip label="This is a tooltip">
   <Text display="inline-block">Text content</Text>
 </Tooltip>
@@ -31,7 +31,7 @@ By default, you have to pass a single React element child to the `Tooltip` compo
 
 If you need to pass more than one child element or non-element children, wrap them in an element or pass the `shouldWrapChildren` prop.
 
-```jsx disabled
+```jsx
 <Tooltip label="This is a tooltip">
   <Text display="inline-block">Text content</Text>
 </Tooltip>
@@ -132,7 +132,7 @@ To customize the appearance of a tooltip, you can pass style props to the Toolti
 
 Use the `placement` prop to control the placement of the tooltip.
 
-```jsx disabled
+```jsx
 <Tooltip label="Tooltip" placement="top">
   Tooltip anchor
 </Tooltip>
diff --git a/packages/react-docs/pages/components/tree/index.page.mdx b/packages/react-docs/pages/components/tree/index.page.mdx
index bf855dbd5f..85876e5a01 100644
--- a/packages/react-docs/pages/components/tree/index.page.mdx
+++ b/packages/react-docs/pages/components/tree/index.page.mdx
@@ -26,7 +26,7 @@ To render a tree, you'll need to use the `Tree` component along with one or more
 
 The `TreeItem` component requires two props: `nodeId` and `render`.
 
-```jsx disabled
+```jsx
 <TreeItem nodeId={nodeId} render={render} />
 ```
 
@@ -37,7 +37,7 @@ In the render function, you can use the provided `TreeItemContent`, `TreeItemTog
 
 Here is the recommended structure for rendering a tree node:
 
-```jsx disabled
+```jsx
 function render({ isExpanded }) {
   return (
     <TreeItemContent>
@@ -77,7 +77,7 @@ Refer to the [Accessibility](#accessibility) section for more keyboard shortcuts
 
 For checkboxes used in multi-selection, consider enhancing accessibility by adjusting the background color when the checkbox is selected.
 
-```jsx disabled
+```jsx
 const render = ({ isExpanded, isSelected }) => {
   return (
     <TreeItemContent
diff --git a/packages/react-docs/pages/getting-started/security/index.page.mdx b/packages/react-docs/pages/getting-started/security/index.page.mdx
index e7f1c10e71..2050df83e1 100644
--- a/packages/react-docs/pages/getting-started/security/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/security/index.page.mdx
@@ -8,7 +8,7 @@ Tonic UI relies on [Emotion](https://emotion.sh/) for its styling system. To sea
 
 ### Step 1: Implement a `EmotionCacheProvider` component
 
-```jsx disabled
+```jsx
 const EmotionCacheProvider = ({
   children,
   nonce,
@@ -26,7 +26,7 @@ const EmotionCacheProvider = ({
 
 Wrap the `TonicProvider` component with the `EmotionCacheProvider` and provide the relevant `nonce` value. This value will be utilized by [Emotion](https://emotion.sh/) to generate a style tag with the necessary `nonce` attribute.
 
-```jsx disabled
+```jsx
 <EmotionCacheProvider nonce={nonce}>
   <TonicProvider
     colorMode={colorMode}
diff --git a/packages/react-docs/pages/getting-started/the-sx-prop/index.page.mdx b/packages/react-docs/pages/getting-started/the-sx-prop/index.page.mdx
index f354c6a304..a0f2f6dacb 100644
--- a/packages/react-docs/pages/getting-started/the-sx-prop/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/the-sx-prop/index.page.mdx
@@ -31,7 +31,7 @@ To get started with the `sx` prop, check out the demo below. It shows how to pas
 
 Each property in the `sx` prop can receive a function callback as a value. This is useful when you want to use the `theme` for calculating a value:
 
-```jsx disabled
+```jsx
 <Box sx={{ color: (theme) => theme.sizes['2x'] }} />
 ```
 
diff --git a/packages/react-docs/pages/getting-started/usage/index.page.mdx b/packages/react-docs/pages/getting-started/usage/index.page.mdx
index dba000b734..e4b4b24a39 100644
--- a/packages/react-docs/pages/getting-started/usage/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/usage/index.page.mdx
@@ -8,7 +8,7 @@ For Tonic UI to work, you will need to setup the `TonicProvder` at the root of y
 
 Go to the root of your application and do the following:
 
-```jsx disabled
+```jsx
 import React from 'react';
 import {
   Box,
@@ -57,7 +57,7 @@ function App(props) {
 
 See below for a more complete example:
 
-```jsx disabled
+```jsx
 import { Global, css } from '@emotion/react';
 import React from 'react';
 import {
@@ -202,7 +202,7 @@ function Layout(props) {
 
 Sometimes you may need to apply base CSS styles to your application. Tonic UI provides an optional `CSSBaseline` component that fixes some inconsistencies across browsers and devices while providing slightly more opinionated resets to common HTML elements. `CSSBaseline` is recommended to add at the root to ensure all components work correctly.
 
-```jsx disabled
+```jsx
 <TonicProvider
   useCSSBaseline={true}
 >
@@ -297,7 +297,7 @@ const customColorStyle = merge(colorStyle, {
 
 #### 2. Setting up the provider
 
-```jsx disabled
+```jsx
 <TonicProvider
   colorStyle={{
     defaultValue: customColorStyle,
@@ -309,7 +309,7 @@ const customColorStyle = merge(colorStyle, {
 
 #### 3. Using the color style
 
-```jsx disabled
+```jsx
 const [colorStyle] = useColorStyle()
 console.log(colorStyle?.risk?.medium); // 'yellow:50'
 console.log(colorStyle?.severity?.critical); // 'magenta:60'
@@ -356,7 +356,7 @@ const customTheme = createTheme(theme, {
 
 #### 3. Using the theme
 
-```jsx disabled
+```jsx
 const theme = useTheme();
 const brandColor = theme?.colors?.brand?.[90];
 ```
@@ -382,7 +382,7 @@ You can customize the styling and layout of your components using the various st
 
 There are some shorthands available for various CSS properties. These are documentated on the [style props](../styled-system/style-props) page.
 
-```jsx disabled
+```jsx
 <Box
   bg="white:primary" // backgroundColor: 'white:primary'
   mb="3x" // marginBottom: '3x'
@@ -399,7 +399,7 @@ The `sx` prop supports CSS syntax including child and pseudo-selectors, media qu
 
 * Using pseudo-selectors:
 
-  ```jsx disabled
+  ```jsx
   <Box
     sx={{
       ':hover': {
@@ -411,7 +411,7 @@ The `sx` prop supports CSS syntax including child and pseudo-selectors, media qu
 
 * Using media queries:
 
-  ```jsx disabled
+  ```jsx
   <Box
     sx={{
       '@media print': {
@@ -423,7 +423,7 @@ The `sx` prop supports CSS syntax including child and pseudo-selectors, media qu
 
 * Using nested selectors:
 
-  ```jsx disabled
+  ```jsx
   <Box
     sx={{
       '& .child-selector': {

From 754d9f599a7c94c56d891c5be68d90828d9d281d Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Tue, 26 Nov 2024 22:45:59 +0800
Subject: [PATCH 07/18] feat: enhance the `createTheme` function

---
 packages/react-docs/pages/_app.page.js        | 10 +--
 .../react-components-part-1.page.mdx          |  2 +-
 .../css-variables/default-css-variables.js    | 13 +--
 .../css-variables/index.page.mdx              | 15 ++--
 .../getting-started/usage/index.page.mdx      | 53 ++----------
 .../migrating-from-v1-to-v2.page.mdx          |  2 +-
 .../responsive-values/index.page.mdx          | 10 +--
 .../pages/theme/breakpoints/index.page.mdx    | 13 +--
 .../react-docs/sandbox/create-react-app.js    |  8 +-
 .../src/accordion/__tests__/Accordion.test.js |  2 +-
 .../react/src/badge/__tests__/Badge.test.js   |  2 +-
 .../src/button/__tests__/ButtonBase.test.js   |  2 +-
 .../src/checkbox/__tests__/Checkbox.test.js   |  2 +-
 .../react/src/code/__tests__/Code.test.js     |  2 +-
 .../DatePicker/__tests__/DatePicker.test.js   |  2 +-
 .../src/divider/__tests__/Divider.test.js     |  2 +-
 .../react/src/drawer/__tests__/Drawer.test.js |  2 +-
 .../react/src/input/__tests__/Input.test.js   |  2 +-
 .../src/input/__tests__/InputControl.test.js  |  2 +-
 .../react/src/menu/__tests__/Menu.test.js     |  2 +-
 .../react/src/modal/__tests__/Modal.test.js   |  2 +-
 .../src/popover/__tests__/Popover.test.js     |  2 +-
 .../react/src/portal/__tests__/Portal.test.js |  2 +-
 .../src/progress/__tests__/Progress.test.js   |  2 +-
 .../react/src/radio/__tests__/Radio.test.js   |  2 +-
 .../__tests__/SearchInput.test.js             |  2 +-
 .../react/src/stack/__tests__/Stack.test.js   |  4 +-
 .../react/src/switch/__tests__/Switch.test.js |  2 +-
 .../react/src/table/__tests__/Table.test.js   |  4 +-
 .../react/src/tabs/__tests__/Tabs.test.js     |  2 +-
 .../react/src/text/__tests__/Text.test.js     |  2 +-
 .../src/text/__tests__/TextLabel.test.js      |  2 +-
 .../src/textarea/__tests__/Textarea.test.js   |  2 +-
 packages/react/src/theme/CSSVariables.js      |  2 +-
 .../src/theme/__tests__/createTheme.test.js   | 60 ++++++++++++++
 packages/react/src/theme/createTheme.js       | 82 +++++++++----------
 packages/react/src/theme/theme.js             |  3 +-
 .../src/theme/utils/createCSSVariableMap.js   | 40 ---------
 packages/react/src/theme/utils/css-vars.js    | 59 +++++++++++++
 .../react/src/theme/utils/toCSSVariable.js    | 23 ------
 .../src/tooltip/__tests__/Tooltip.test.js     |  2 +-
 .../react/src/tree/__tests__/Tree.test.js     |  2 +-
 .../src/truncate/__tests__/Truncate.test.js   |  2 +-
 packages/react/test-utils/render.js           | 12 +--
 .../styled-system/src/__tests__/sx.test.js    |  5 +-
 .../src/config/__tests__/margin.test.js       |  5 +-
 .../src/config/__tests__/position.test.js     |  5 +-
 .../styled-system/src/utils/transforms.js     | 18 ++--
 packages/theme/src/createTheme.js             |  1 +
 49 files changed, 254 insertions(+), 245 deletions(-)
 create mode 100644 packages/react/src/theme/__tests__/createTheme.test.js
 delete mode 100644 packages/react/src/theme/utils/createCSSVariableMap.js
 create mode 100644 packages/react/src/theme/utils/css-vars.js
 delete mode 100644 packages/react/src/theme/utils/toCSSVariable.js

diff --git a/packages/react-docs/pages/_app.page.js b/packages/react-docs/pages/_app.page.js
index 212207afae..c9909bb8b9 100644
--- a/packages/react-docs/pages/_app.page.js
+++ b/packages/react-docs/pages/_app.page.js
@@ -7,8 +7,7 @@ import {
   ToastManager,
   TonicProvider,
   colorStyle as defaultColorStyle,
-  createTheme,
-  theme,
+  createTheme, // For theme customization (introduced in v2.5.0)
   useTheme,
 } from '@tonic-ui/react';
 import {
@@ -51,7 +50,8 @@ const EmotionCacheProvider = ({
 };
 
 const App = (props) => {
-  const customTheme = useConst(() => createTheme(theme, {
+  const customTheme = useConst(() => createTheme({
+    cssVariables: true, // Enable CSS variables replacement
     components: {
       // Set default props for specific components
       //
@@ -64,10 +64,6 @@ const App = (props) => {
       // },
       // ```
     },
-    config: {
-      // Enable CSS variables replacement
-      useCSSVariables: true,
-    },
   }));
   const [initialColorMode, setColorMode] = useState(null);
   const router = useRouter();
diff --git a/packages/react-docs/pages/contributing/react-components-part-1.page.mdx b/packages/react-docs/pages/contributing/react-components-part-1.page.mdx
index cd068f786d..3f33b609c5 100644
--- a/packages/react-docs/pages/contributing/react-components-part-1.page.mdx
+++ b/packages/react-docs/pages/contributing/react-components-part-1.page.mdx
@@ -103,7 +103,7 @@ import React from 'react';
 describe('Code', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true, // Enable CSS variables replacement
     };
     const { container } = render((
       <Code>Hello World</Code>
diff --git a/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js b/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js
index 5691889820..b539ff082d 100644
--- a/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js
+++ b/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js
@@ -6,11 +6,10 @@ const isColorCode = value => String(value).startsWith('#') || String(value).star
 const App = () => {
   const theme = useTheme();
   const [colorMode] = useColorMode();
-  const cssVariableMap = theme.__cssVariableMap;
-  const borderColor = {         
+  const borderColor = {
     dark: 'gray:60',
-    light: 'gray:30',                                  
-  }[colorMode]; 
+    light: 'gray:30',
+  }[colorMode];
   const tokenColor = {
     dark: 'red:50',
     light: 'red:60',
@@ -18,7 +17,11 @@ const App = () => {
 
   return (
     <Box fontFamily="mono">
-      {Object.entries(cssVariableMap).map(([name, value]) => {
+      {Object.entries(theme?.vars).map(([name, value]) => {
+        if (!name.startsWith('--')) {
+          return null;
+        }
+
         return (
           <Flex key={name} columnGap="2x">
             <Text color={tokenColor}>{name}:</Text>
diff --git a/packages/react-docs/pages/getting-started/css-variables/index.page.mdx b/packages/react-docs/pages/getting-started/css-variables/index.page.mdx
index c32a97818b..bff7624152 100644
--- a/packages/react-docs/pages/getting-started/css-variables/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/css-variables/index.page.mdx
@@ -5,18 +5,17 @@
 Tonic UI supports converting theme tokens defined in the theme to CSS variables. You can enable this behavior by configuring the theme as shown below:
 
 ```jsx
-import { TonicProvider, theme } from '@tonic-ui/react';
-
-// Enable CSS variables
-theme.config.useCSSVariables = true;
-
-// Pass `theme` to the `TonicProvider`
-<TonicProvider theme={theme} />
+// Use `createTheme` to provide custom configuration
+<TonicProvider
+  theme={createTheme({ // `createTheme` was introduced in v2.5.0
+    cssVariables: true, // Enable CSS variables replacement
+  })}
+/>
 ```
 
 For example, consider a theme object that looks like this:
 
-```js disabled
+```js
 const theme = {
   colors: {
     'gray:10': '#fafafa',
diff --git a/packages/react-docs/pages/getting-started/usage/index.page.mdx b/packages/react-docs/pages/getting-started/usage/index.page.mdx
index e4b4b24a39..e055669beb 100644
--- a/packages/react-docs/pages/getting-started/usage/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/usage/index.page.mdx
@@ -13,40 +13,14 @@ import React from 'react';
 import {
   Box,
   TonicProvider, // Provides theme and context for Tonic UI components
-  colorStyle,    // Default color style object
-  createTheme,   // For theme customization (introduced in v2.5.0)
-  theme,         // Default theme configuration
 } from '@tonic-ui/react';
 
-const customTheme = createTheme(theme, {
-  config: {
-    // Enable CSS variables replacement
-    useCSSVariables: true,
-  },
-  components: {
-    // Set default props for specific components
-    //
-    // Example:
-    // ```
-    // 'ToastCloseButton': {
-    //   defaultProps: {
-    //     'aria-label': 'Close toast',
-    //   },
-    // },
-    // ```
-  },
-});
-
 function App(props) {
   return (
     <TonicProvider
       colorMode={{
         defaultValue: 'dark', // One of: 'dark', 'light'
       }}
-      colorStyle={{
-        defaultValue: colorStyle, // optional
-      }}
-      theme={customTheme} // optional
       useCSSBaseline={true} // If `true`, apply CSS reset and base styles
     >
       <Box {...props} />
@@ -67,17 +41,13 @@ import {
   TonicProvider, // Provides theme and context for Tonic UI components
   colorStyle,    // Default color style object
   createTheme,   // For theme customization (introduced in v2.5.0)
-  theme,         // Default theme configuration
   useColorMode,  // Hook to manage color mode (e.g., light/dark)
   useColorStyle, // Hook to manage color style
   useTheme,      // Hook to access the theme object
 } from '@tonic-ui/react';
 
-const customTheme = createTheme(theme, {
-  config: {
-    // Enable CSS variables replacement
-    useCSSVariables: true,
-  },
+const customTheme = createTheme({
+  cssVariables: true, // Enable CSS variables replacement
   components: {
     // Set default props for specific components
     //
@@ -99,9 +69,9 @@ function App(props) {
         defaultValue: 'dark', // One of: 'dark', 'light'
       }}
       colorStyle={{
-        defaultValue: colorStyle, // optional
+        defaultValue: colorStyle,
       }}
-      theme={customTheme} // optional
+      theme={customTheme}
       useCSSBaseline={true} // If `true`, apply CSS reset and base styles
     >
       <ToastManager
@@ -218,10 +188,8 @@ Tonic UI supports converting theme tokens defined in the theme to CSS variables.
 
 ```jsx
 <TonicProvider
-  theme={merge(theme, {
-    config: {
-      useCSSVariables: true,
-    },
+  theme={createTheme({
+    cssVariables: true, // Enable CSS variables replacement
   })}
 />
 ```
@@ -325,15 +293,12 @@ Override the theme object and pass it to the `<ThemeProvider>` component.
 
 ```js
 import {
-  createTheme,
-  theme,
+  createTheme, // For theme customization (introduced in v2.5.0)
 } from '@tonic-ui/react';
 
 // Let's say you want to add more colors
-const customTheme = createTheme(theme, {
-  config: {
-    useCSSVariables: true,
-  },
+const customTheme = createTheme({
+  cssVariables: true, // Enable CSS variables replacement
   colors: {
     brand: {
       90: "#1a365d",
diff --git a/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx b/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx
index 9f6994495b..b8a80d7bda 100644
--- a/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx
+++ b/packages/react-docs/pages/migrations/migrating-from-v1-to-v2.page.mdx
@@ -37,7 +37,7 @@ console.log(colorStyle.chart.classic.colors[0]);
 
 To use previously defined `severity` and `chart` colors, you need to pass a custom color style to `TonicProvider`. Follow the setup below to use previous `severity` and `chart` colors:
 
-```jsx disabled
+```jsx
 import React from 'react';
 import { Box, TonicProvider, colorStyle } from '@tonic-ui/react';
 import { merge } from '@tonic-ui/utils';
diff --git a/packages/react-docs/pages/styled-system/responsive-values/index.page.mdx b/packages/react-docs/pages/styled-system/responsive-values/index.page.mdx
index b8825ccc2c..8f79fadbe5 100644
--- a/packages/react-docs/pages/styled-system/responsive-values/index.page.mdx
+++ b/packages/react-docs/pages/styled-system/responsive-values/index.page.mdx
@@ -16,7 +16,7 @@ To use the responsive values, you can use either the array or object syntax.
 
 Let's say you have a `Box` component that looks like this:
 
-```jsx disabled
+```jsx
 <Box backgroundColor="red:50" width="50%">
   This is a box
 </Box>
@@ -24,7 +24,7 @@ Let's say you have a `Box` component that looks like this:
 
 To make the `width` responsive, you can use the array syntax as follows:
 
-```jsx disabled
+```jsx
 <Box backgroundColor="red:50" width={["25%","50%","75%","100%"]}>
   This is a box
 </Box>
@@ -45,7 +45,7 @@ You can also use the object syntax to define responsive values. It's also the re
 
 Let's say you have a `Text` component that looks like this:
 
-```jsx disabled
+```jsx
 <Text fontSize={32}>
   This is a text
 </Text>
@@ -53,7 +53,7 @@ Let's say you have a `Text` component that looks like this:
 
 To make the `fontSize` responsive, you can use the object syntax as follows:
 
-```jsx disabled
+```jsx
 <Text fontSize={{ _: 24, md: 32, lg: 40, xl: 48 }}>
   This is a text
 </Text>
@@ -72,7 +72,7 @@ Here is how to interpret the object syntax:
 
 Given the following example:
 
-```jsx disabled
+```jsx
 <Box width={{ _: '100%', sm: '50%', md: '25%' }}>
   This is a box
 </Box>
diff --git a/packages/react-docs/pages/theme/breakpoints/index.page.mdx b/packages/react-docs/pages/theme/breakpoints/index.page.mdx
index 1e37bbb031..79bd307db5 100644
--- a/packages/react-docs/pages/theme/breakpoints/index.page.mdx
+++ b/packages/react-docs/pages/theme/breakpoints/index.page.mdx
@@ -40,9 +40,12 @@ For more control over the breakpoints, you can define custom breakpoints for you
 
 To do this, add a `breakpoints` array with additional aliases (e.g. `sm`, `md`, `lg`, `xl`, and `2xl`) to your theme.
 
-```jsx disabled
+```jsx
 // 1. Import the theme
-import { ThemeProvider, createTheme, theme } from '@tonic-ui/react';
+import {
+  TonicProvider, // Provides theme and context for Tonic UI components
+  createTheme,   // For theme customization (introduced in v2.5.0)
+} from '@tonic-ui/react';
 
 // 2. Update the breakpoints
 const breakpoints = [
@@ -59,16 +62,16 @@ breakpoints.xl = breakpoints[3];
 breakpoints['2xl'] = breakpoints[4];
 
 // 3. Extend the theme
-const customTheme = createTheme(theme, {
+const customTheme = createTheme({
   breakpoints,
 });
 
 // 4. Pass the custom theme to the theme provider
 function App() {
   return (
-    <ThemeProvider theme={customTheme}>
+    <TonicProvider theme={customTheme}>
       {children}
-    </ThemeProvider>
+    </TonicProvider>
   );
 }
 ```
diff --git a/packages/react-docs/sandbox/create-react-app.js b/packages/react-docs/sandbox/create-react-app.js
index db90238ef8..02fd3caa1e 100644
--- a/packages/react-docs/sandbox/create-react-app.js
+++ b/packages/react-docs/sandbox/create-react-app.js
@@ -29,7 +29,6 @@ import {
   TonicProvider,
   colorStyle,
   createTheme,
-  theme,
   useColorMode,
   useColorStyle,
   useTheme,
@@ -74,11 +73,8 @@ const customColorStyle = merge(colorStyle, {
   },
 });
 
-const customTheme = createTheme(theme, {
-  config: {
-    // Enable CSS variables replacement
-    useCSSVariables: true,
-  },
+const customTheme = createTheme({
+  cssVariables: true, // Enable CSS variables replacement
   components: {
     // Set default props for specific components
     //
diff --git a/packages/react/src/accordion/__tests__/Accordion.test.js b/packages/react/src/accordion/__tests__/Accordion.test.js
index d191a81598..6cbba8f801 100644
--- a/packages/react/src/accordion/__tests__/Accordion.test.js
+++ b/packages/react/src/accordion/__tests__/Accordion.test.js
@@ -15,7 +15,7 @@ import React from 'react';
 describe('Accordion', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Accordion rowGap={1}>
diff --git a/packages/react/src/badge/__tests__/Badge.test.js b/packages/react/src/badge/__tests__/Badge.test.js
index cabd1e088b..6df4ded73b 100644
--- a/packages/react/src/badge/__tests__/Badge.test.js
+++ b/packages/react/src/badge/__tests__/Badge.test.js
@@ -7,7 +7,7 @@ import React from 'react';
 describe('Badge', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Flex columnGap="4x">
diff --git a/packages/react/src/button/__tests__/ButtonBase.test.js b/packages/react/src/button/__tests__/ButtonBase.test.js
index 03fc43f2bd..54172e8bf3 100644
--- a/packages/react/src/button/__tests__/ButtonBase.test.js
+++ b/packages/react/src/button/__tests__/ButtonBase.test.js
@@ -6,7 +6,7 @@ import React from 'react';
 describe('ButtonBase', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/checkbox/__tests__/Checkbox.test.js b/packages/react/src/checkbox/__tests__/Checkbox.test.js
index 8070a89b7a..478f1f35ff 100644
--- a/packages/react/src/checkbox/__tests__/Checkbox.test.js
+++ b/packages/react/src/checkbox/__tests__/Checkbox.test.js
@@ -6,7 +6,7 @@ import React, { useEffect, useRef } from 'react';
 describe('Checkbox', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/code/__tests__/Code.test.js b/packages/react/src/code/__tests__/Code.test.js
index 41e7eed588..7828b0c080 100644
--- a/packages/react/src/code/__tests__/Code.test.js
+++ b/packages/react/src/code/__tests__/Code.test.js
@@ -7,7 +7,7 @@ import React from 'react';
 describe('Code', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Code data-testid="Code">
diff --git a/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js b/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js
index cba47cfe8f..095496bf0c 100644
--- a/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js
+++ b/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js
@@ -66,7 +66,7 @@ describe('DatePicker', () => {
   it('should render correctly', async () => {
     const user = userEvent.setup();
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const defaultValue = new Date('2024-08-01');
     const inputFormat = 'yyyy-MM-dd';
diff --git a/packages/react/src/divider/__tests__/Divider.test.js b/packages/react/src/divider/__tests__/Divider.test.js
index 867cfa5cc8..2b89e55ec6 100644
--- a/packages/react/src/divider/__tests__/Divider.test.js
+++ b/packages/react/src/divider/__tests__/Divider.test.js
@@ -6,7 +6,7 @@ import React from 'react';
 describe('Divider', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/drawer/__tests__/Drawer.test.js b/packages/react/src/drawer/__tests__/Drawer.test.js
index 626ab3434c..7d40476342 100644
--- a/packages/react/src/drawer/__tests__/Drawer.test.js
+++ b/packages/react/src/drawer/__tests__/Drawer.test.js
@@ -19,7 +19,7 @@ import React, { useCallback, useRef, useState } from 'react';
 describe('Drawer', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { baseElement } = render((
       <Drawer
diff --git a/packages/react/src/input/__tests__/Input.test.js b/packages/react/src/input/__tests__/Input.test.js
index a1a9944ac8..e84b52963a 100644
--- a/packages/react/src/input/__tests__/Input.test.js
+++ b/packages/react/src/input/__tests__/Input.test.js
@@ -10,7 +10,7 @@ describe('Input', () => {
     const sizes = ['sm', 'md', 'lg'];
     const variants = ['outline', 'filled', 'flush', 'unstyled'];
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/input/__tests__/InputControl.test.js b/packages/react/src/input/__tests__/InputControl.test.js
index 819a29fe37..da95df68a1 100644
--- a/packages/react/src/input/__tests__/InputControl.test.js
+++ b/packages/react/src/input/__tests__/InputControl.test.js
@@ -10,7 +10,7 @@ describe('InputControl', () => {
     const sizes = ['sm', 'md', 'lg'];
     const variants = ['outline', 'filled', 'flush', 'unstyled'];
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/menu/__tests__/Menu.test.js b/packages/react/src/menu/__tests__/Menu.test.js
index 2f10482a48..82ce68611a 100644
--- a/packages/react/src/menu/__tests__/Menu.test.js
+++ b/packages/react/src/menu/__tests__/Menu.test.js
@@ -41,7 +41,7 @@ describe('Menu', () => {
   it('should render correctly', async () => {
     const user = userEvent.setup();
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <TestComponent />
diff --git a/packages/react/src/modal/__tests__/Modal.test.js b/packages/react/src/modal/__tests__/Modal.test.js
index 9108e6c5c3..076e32ab74 100644
--- a/packages/react/src/modal/__tests__/Modal.test.js
+++ b/packages/react/src/modal/__tests__/Modal.test.js
@@ -19,7 +19,7 @@ import React, { useCallback, useRef, useState } from 'react';
 describe('Modal', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { baseElement } = render((
       <Modal isOpen onClose={jest.fn()}>
diff --git a/packages/react/src/popover/__tests__/Popover.test.js b/packages/react/src/popover/__tests__/Popover.test.js
index 7a08e09737..68d3b616a8 100644
--- a/packages/react/src/popover/__tests__/Popover.test.js
+++ b/packages/react/src/popover/__tests__/Popover.test.js
@@ -9,7 +9,7 @@ describe('Popover', () => {
   it('should render correctly', async () => {
     const user = userEvent.setup();
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Popover>
diff --git a/packages/react/src/portal/__tests__/Portal.test.js b/packages/react/src/portal/__tests__/Portal.test.js
index e50316f451..55b17acb19 100644
--- a/packages/react/src/portal/__tests__/Portal.test.js
+++ b/packages/react/src/portal/__tests__/Portal.test.js
@@ -6,7 +6,7 @@ import React from 'react';
 describe('Portal', () => {
   it('should render correctly', () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Portal>
diff --git a/packages/react/src/progress/__tests__/Progress.test.js b/packages/react/src/progress/__tests__/Progress.test.js
index 6b44c13673..fe9708b23d 100644
--- a/packages/react/src/progress/__tests__/Progress.test.js
+++ b/packages/react/src/progress/__tests__/Progress.test.js
@@ -6,7 +6,7 @@ import React from 'react';
 describe('LinearProgress', () => {
   it('renders correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/radio/__tests__/Radio.test.js b/packages/react/src/radio/__tests__/Radio.test.js
index cafc02f694..8d9bf8afee 100644
--- a/packages/react/src/radio/__tests__/Radio.test.js
+++ b/packages/react/src/radio/__tests__/Radio.test.js
@@ -6,7 +6,7 @@ import React, { useEffect, useRef } from 'react';
 describe('Radio', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/search-input/__tests__/SearchInput.test.js b/packages/react/src/search-input/__tests__/SearchInput.test.js
index 320ff502c3..0ebd40f631 100644
--- a/packages/react/src/search-input/__tests__/SearchInput.test.js
+++ b/packages/react/src/search-input/__tests__/SearchInput.test.js
@@ -10,7 +10,7 @@ describe('SearchInput', () => {
     const sizes = ['sm', 'md', 'lg'];
     const variants = ['outline', 'filled', 'flush', 'unstyled'];
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/stack/__tests__/Stack.test.js b/packages/react/src/stack/__tests__/Stack.test.js
index 51e9e28866..631843fea4 100644
--- a/packages/react/src/stack/__tests__/Stack.test.js
+++ b/packages/react/src/stack/__tests__/Stack.test.js
@@ -7,7 +7,7 @@ import React from 'react';
 describe('Stack', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Stack spacing="4x">
@@ -54,7 +54,7 @@ describe('Stack', () => {
 
   it('should apply spacing between child elements', () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     render((
       <Stack data-testid="stack" spacing="2x">
diff --git a/packages/react/src/switch/__tests__/Switch.test.js b/packages/react/src/switch/__tests__/Switch.test.js
index 7c76750937..e818943901 100644
--- a/packages/react/src/switch/__tests__/Switch.test.js
+++ b/packages/react/src/switch/__tests__/Switch.test.js
@@ -6,7 +6,7 @@ import React, { useEffect, useRef } from 'react';
 describe('Switch', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/table/__tests__/Table.test.js b/packages/react/src/table/__tests__/Table.test.js
index 2e78179726..4351fd1674 100644
--- a/packages/react/src/table/__tests__/Table.test.js
+++ b/packages/react/src/table/__tests__/Table.test.js
@@ -61,7 +61,7 @@ describe('Table', () => {
 
   it('should render correctly with `flexbox` layout', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
 
     const { container } = render((
@@ -104,7 +104,7 @@ describe('Table', () => {
 
   it('should render correctly with `table` layout', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
 
     const { container } = render((
diff --git a/packages/react/src/tabs/__tests__/Tabs.test.js b/packages/react/src/tabs/__tests__/Tabs.test.js
index dd2304cd7d..aeb4b76add 100644
--- a/packages/react/src/tabs/__tests__/Tabs.test.js
+++ b/packages/react/src/tabs/__tests__/Tabs.test.js
@@ -6,7 +6,7 @@ import React from 'react';
 describe('Tabs', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Tabs>
diff --git a/packages/react/src/text/__tests__/Text.test.js b/packages/react/src/text/__tests__/Text.test.js
index 155d947726..03d0a6efe2 100644
--- a/packages/react/src/text/__tests__/Text.test.js
+++ b/packages/react/src/text/__tests__/Text.test.js
@@ -7,7 +7,7 @@ import React from 'react';
 describe('TextLabel', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Text>
diff --git a/packages/react/src/text/__tests__/TextLabel.test.js b/packages/react/src/text/__tests__/TextLabel.test.js
index 502ca46a5d..85b44d9890 100644
--- a/packages/react/src/text/__tests__/TextLabel.test.js
+++ b/packages/react/src/text/__tests__/TextLabel.test.js
@@ -7,7 +7,7 @@ import React from 'react';
 describe('TextLabel', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <TextLabel data-testid="TextLabel">
diff --git a/packages/react/src/textarea/__tests__/Textarea.test.js b/packages/react/src/textarea/__tests__/Textarea.test.js
index 0b078bb0cc..5df956b83d 100644
--- a/packages/react/src/textarea/__tests__/Textarea.test.js
+++ b/packages/react/src/textarea/__tests__/Textarea.test.js
@@ -9,7 +9,7 @@ describe('Textarea', () => {
   it('should render correctly', async () => {
     const variants = ['outline', 'filled', 'unstyled'];
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <>
diff --git a/packages/react/src/theme/CSSVariables.js b/packages/react/src/theme/CSSVariables.js
index cedc64b7eb..b1be78580e 100644
--- a/packages/react/src/theme/CSSVariables.js
+++ b/packages/react/src/theme/CSSVariables.js
@@ -8,7 +8,7 @@ const CSSVariables = ({
   const styles = useCallback((theme) => {
     const selector = ensureArray(root).join(',');
     return {
-      [selector]: { ...theme?.__cssVariableMap },
+      [selector]: { ...theme?.vars },
     };
   }, [root]);
 
diff --git a/packages/react/src/theme/__tests__/createTheme.test.js b/packages/react/src/theme/__tests__/createTheme.test.js
new file mode 100644
index 0000000000..760d592df2
--- /dev/null
+++ b/packages/react/src/theme/__tests__/createTheme.test.js
@@ -0,0 +1,60 @@
+import createTheme from '../createTheme';
+
+describe('createTheme', () => {
+  it('should create a default theme', () => {
+    const theme = createTheme();
+    expect(theme).toHaveProperty('borders');
+    expect(theme).toHaveProperty('breakpoints');
+    expect(theme).toHaveProperty('colors');
+    expect(theme).toHaveProperty('fonts');
+    expect(theme).toHaveProperty('fontSizes');
+    expect(theme).toHaveProperty('fontWeights');
+    expect(theme).toHaveProperty('letterSpacings');
+    expect(theme).toHaveProperty('lineHeights');
+    expect(theme).toHaveProperty('outlines');
+    expect(theme).toHaveProperty('radii');
+    expect(theme).toHaveProperty('shadows');
+    expect(theme).toHaveProperty('sizes');
+    expect(theme).toHaveProperty('space');
+    expect(theme).toHaveProperty('zIndices');
+  });
+
+  it('should merge custom theme options', () => {
+    const theme = createTheme();
+    const customTheme = createTheme(theme, {
+      colors: {
+        'black:emphasis': 'rgb(0, 0, 0)',
+        'white:emphasis': 'rgb(255, 255, 255)',
+      },
+    });
+    expect(theme.colors['black:emphasis']).toBe('rgba(0, 0, 0, 1.0)');
+    expect(theme.colors['white:emphasis']).toBe('rgba(255, 255, 255, 1.0)');
+    expect(customTheme.colors['black:emphasis']).toBe('rgb(0, 0, 0)');
+    expect(customTheme.colors['white:emphasis']).toBe('rgb(255, 255, 255)');
+  });
+
+  it('should merge additional arguments into the theme', () => {
+    const additionalConfig = { components: { Button: { defaultProps: { size: 'large' } } } };
+    const theme = createTheme({}, additionalConfig);
+    expect(theme.components.Button.defaultProps.size).toBe('large');
+  });
+
+  it('should not generate CSS variables with default configuration', () => {
+    const theme = createTheme();
+    expect(theme.vars).not.toBeDefined();
+  });
+
+  it('should generate CSS variables', () => {
+    const theme = createTheme({ cssVariables: true });
+    expect(theme.vars).toBeDefined();
+    expect(theme.vars.prefix).toBe('tonic');
+    expect(Object.keys(theme.vars).filter(x => x.startsWith('--'))[0]).toMatch(/^--tonic-/);
+  });
+
+  it('should apply custom prefix to CSS variables', () => {
+    const theme = createTheme({ cssVariables: { prefix: 'custom' } });
+    expect(theme.vars).toBeDefined();
+    expect(theme.vars.prefix).toBe('custom');
+    expect(Object.keys(theme.vars).filter(x => x.startsWith('--'))[0]).toMatch(/^--custom-/);
+  });
+});
diff --git a/packages/react/src/theme/createTheme.js b/packages/react/src/theme/createTheme.js
index bbee4058ed..58158f94ba 100644
--- a/packages/react/src/theme/createTheme.js
+++ b/packages/react/src/theme/createTheme.js
@@ -1,55 +1,55 @@
+import tonicTheme from '@tonic-ui/theme';
 import { merge } from '@tonic-ui/utils';
 import { ensurePlainObject } from 'ensure-type';
-import createCSSVariableMap from './utils/createCSSVariableMap';
+import { mapThemeToCSSVariables } from './utils/css-vars';
 
 const defaultCSSVariablePrefix = 'tonic';
 
-const cssVariableScales = [
-  'borders',
-  'breakpoints',
-  'colors',
-  'fonts',
-  'fontSizes',
-  'fontWeights',
-  'letterSpacings',
-  'lineHeights',
-  'outlines',
-  'radii',
-  'shadows',
-  'sizes',
-  'space',
-  'zIndices',
-];
-
 const createTheme = (options = {}, ...args) => {
-  // Merge provided options with default configurations
-  let theme = merge(options, {
-    config: {
-      prefix: defaultCSSVariablePrefix,
-      useCSSVariables: false,
+  const {
+    // Configure CSS variables for the theme:
+    // - `false` (default): Disable CSS variables.
+    // - `true`: Enable CSS variables with default settings.
+    // - `{ prefix: 'tonic' }`: Enable CSS variables with a custom prefix.
+    cssVariables: cssVariableConfig = false,
+    ...rest
+  } = options;
+
+  let theme = merge(
+    {
+      ...tonicTheme,
     },
-  });
-
-  // Ensure the components field is initialized
-  theme.components = theme.components ?? {};
+    rest,
+  );
 
   // Merge additional arguments into the theme
   theme = args.reduce((acc, arg) => merge(acc, arg), theme);
 
-  // Generate a theme object filtered to include only scales supported by CSS variables
-  const cssVariableTheme = Object.fromEntries(
-    Object.entries(ensurePlainObject(theme)).filter(
-      ([key]) => cssVariableScales.includes(key)
-    )
-  );
-
-  // Create a map of CSS variables with the appropriate prefix
-  const cssVariableMap = createCSSVariableMap(cssVariableTheme, { prefix: theme?.config?.prefix });
-
-  // Merge the CSS variable map into the theme
-  theme = merge(theme, {
-    __cssVariableMap: cssVariableMap,
-  });
+  if (cssVariableConfig) {
+    // Determine the prefix for CSS variables:
+    // - Uses the `prefix` property if provided (e.g., `createTheme({ cssVariables: { prefix: 'tonic' } })`).
+    // - Defaults to `defaultCSSVariablePrefix` if no custom prefix is specified.
+    const cssVariablePrefix = cssVariableConfig?.prefix ?? defaultCSSVariablePrefix;
+
+    // Generate a theme object filtered to include only scales supported by CSS variables
+    const cssVariableScales = Object.keys(tonicTheme);
+    const cssVariableTheme = Object.fromEntries(
+      Object.entries(ensurePlainObject(theme)).filter(
+        ([key]) => cssVariableScales.includes(key)
+      )
+    );
+
+    // Create CSS variables with the appropriate prefix
+    const cssVariables = mapThemeToCSSVariables(cssVariableTheme, { prefix: cssVariablePrefix });
+
+    // Merge CSS variables into the theme
+    theme = merge(theme, {
+      vars: {
+        prefix: cssVariablePrefix,
+        ...cssVariables,
+      },
+    });
+  }
 
   return theme;
 };
diff --git a/packages/react/src/theme/theme.js b/packages/react/src/theme/theme.js
index 7c89066a20..0c3fe92d5e 100644
--- a/packages/react/src/theme/theme.js
+++ b/packages/react/src/theme/theme.js
@@ -1,6 +1,5 @@
-import tonicTheme from '@tonic-ui/theme';
 import createTheme from './createTheme';
 
-const theme = createTheme(tonicTheme);
+const theme = createTheme();
 
 export default theme;
diff --git a/packages/react/src/theme/utils/createCSSVariableMap.js b/packages/react/src/theme/utils/createCSSVariableMap.js
deleted file mode 100644
index 8fcf409fe4..0000000000
--- a/packages/react/src/theme/utils/createCSSVariableMap.js
+++ /dev/null
@@ -1,40 +0,0 @@
-import { ensureString } from 'ensure-type';
-import flatten from './flatten';
-import toCSSVariable from './toCSSVariable';
-
-/**
- * Generate CSS variable map for a given theme object.
- *
- * @param {object} theme - The object containing the theme values.
- * @param {object} [options] - The options object.
- * @param {string} [options.prefix] - A prefix to prepend to each generated CSS variable.
- *
- * @example
- * ```js
- * const theme = {
- *   colors: {
- *     'blue:50': '#578aef',
- *   },
- * };
- * createCSSVariableMap(theme, { prefix: 'tonic' });
- * // => {
- * //   '--tonic-colors-blue-50': '#578aef'
- * // }
- * ```
- */
-const createCSSVariableMap = (theme, options) => {
-  const prefix = ensureString(options?.prefix);
-  const tokens = flatten(theme);
-  const cssVariableMap = {};
-
-  for (const [name, value] of Object.entries(tokens)) {
-    // name='colors.blue:50', prefix='tonic'
-    // => '--tonic-colors-blue-50'
-    const variable = toCSSVariable(name, { prefix });
-    cssVariableMap[variable] = value;
-  }
-
-  return cssVariableMap;
-};
-
-export default createCSSVariableMap;
diff --git a/packages/react/src/theme/utils/css-vars.js b/packages/react/src/theme/utils/css-vars.js
new file mode 100644
index 0000000000..d6b36a8481
--- /dev/null
+++ b/packages/react/src/theme/utils/css-vars.js
@@ -0,0 +1,59 @@
+import { ensureString } from 'ensure-type';
+import flatten from './flatten';
+
+/**
+ * Returns a CSS variable name formatted from the given name and options.
+ *
+ * @param {string} name - The name of the variable.
+ * @param {object} [options] - The options object.
+ * @param {string} [options.prefix=''] - The prefix to use for the variable name.
+ * @param {string} [options.delimiter='-'] - The delimiter to use between the prefix and name.
+ *
+ * @return {string} The CSS variable name.
+*/
+export const toCSSVariable = (name, options) => {
+  const {
+    prefix = '',
+    delimiter = '-',
+  } = { ...options };
+  const variableName = ([prefix, name].filter(Boolean).join(delimiter))
+    .replace(/\s+/g, delimiter) // replace whitespace characters
+    .replace(/[^a-zA-Z0-9-_]/g, delimiter) // replace non-alphanumeric, non-hyphen, non-underscore characters
+    .replace(/^-+|-+$/g, ''); // trim hyphens from beginning and end of string
+  return `--${variableName}`;
+};
+
+/**
+ * Generates CSS variables from a theme object.
+ *
+ * @param {object} theme - The theme object containing key-value pairs for the variables.
+ * @param {object} [options] - Optional configuration for variable generation.
+ * @param {string} [options.prefix] - A prefix to prepend to each generated CSS variable.
+ *
+ * @example
+ * ```js
+ * const theme = {
+ *   colors: {
+ *     'blue:50': '#578aef',
+ *   },
+ * };
+ * mapThemeToCSSVariables(theme, { prefix: 'tonic' });
+ * // => {
+ * //   '--tonic-colors-blue-50': '#578aef'
+ * // }
+ * ```
+ */
+export const mapThemeToCSSVariables = (theme, options) => {
+  const prefix = ensureString(options?.prefix);
+  const tokens = flatten(theme);
+  const cssVariables = {};
+
+  for (const [name, value] of Object.entries(tokens)) {
+    // name='colors.blue:50', prefix='tonic'
+    // => '--tonic-colors-blue-50'
+    const variable = toCSSVariable(name, { prefix });
+    cssVariables[variable] = value;
+  }
+
+  return cssVariables;
+};
diff --git a/packages/react/src/theme/utils/toCSSVariable.js b/packages/react/src/theme/utils/toCSSVariable.js
deleted file mode 100644
index 9c1a94d225..0000000000
--- a/packages/react/src/theme/utils/toCSSVariable.js
+++ /dev/null
@@ -1,23 +0,0 @@
-/**
- * Returns a CSS variable name formatted from the given name and options.
- *
- * @param {string} name - The name of the variable.
- * @param {object} [options] - The options object.
- * @param {string} [options.prefix=''] - The prefix to use for the variable name.
- * @param {string} [options.delimiter='-'] - The delimiter to use between the prefix and name.
- *
- * @return {string} The CSS variable name.
-*/
-const toCSSVariable = (name, options) => {
-  const {
-    prefix = '',
-    delimiter = '-',
-  } = { ...options };
-  const variableName = ([prefix, name].filter(Boolean).join(delimiter))
-    .replace(/\s+/g, delimiter) // replace whitespace characters
-    .replace(/[^a-zA-Z0-9-_]/g, delimiter) // replace non-alphanumeric, non-hyphen, non-underscore characters
-    .replace(/^-+|-+$/g, ''); // trim hyphens from beginning and end of string
-  return `--${variableName}`;
-};
-
-export default toCSSVariable;
diff --git a/packages/react/src/tooltip/__tests__/Tooltip.test.js b/packages/react/src/tooltip/__tests__/Tooltip.test.js
index dc18f571d7..01fb0409c0 100644
--- a/packages/react/src/tooltip/__tests__/Tooltip.test.js
+++ b/packages/react/src/tooltip/__tests__/Tooltip.test.js
@@ -17,7 +17,7 @@ describe('Tooltip', () => {
   it('should render correctly', async () => {
     const user = userEvent.setup();
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <TestComponent />
diff --git a/packages/react/src/tree/__tests__/Tree.test.js b/packages/react/src/tree/__tests__/Tree.test.js
index 164ca1dcbb..f8d27d89ab 100644
--- a/packages/react/src/tree/__tests__/Tree.test.js
+++ b/packages/react/src/tree/__tests__/Tree.test.js
@@ -182,7 +182,7 @@ const TreeItemRender = ({
 describe('Tree', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const treeNodes = buildTreeNodes();
     const treeMap = buildTreeMap(treeNodes);
diff --git a/packages/react/src/truncate/__tests__/Truncate.test.js b/packages/react/src/truncate/__tests__/Truncate.test.js
index ad93b56201..a7133551ef 100644
--- a/packages/react/src/truncate/__tests__/Truncate.test.js
+++ b/packages/react/src/truncate/__tests__/Truncate.test.js
@@ -6,7 +6,7 @@ import React from 'react';
 describe('Truncate', () => {
   it('should render correctly', async () => {
     const renderOptions = {
-      useCSSVariables: true,
+      cssVariables: true,
     };
     const { container } = render((
       <Truncate width={120}>
diff --git a/packages/react/test-utils/render.js b/packages/react/test-utils/render.js
index 51f7ccd1a4..43f74d6674 100644
--- a/packages/react/test-utils/render.js
+++ b/packages/react/test-utils/render.js
@@ -6,7 +6,7 @@ import {
   PortalManager,
   ToastManager,
   TonicProvider,
-  theme,
+  createTheme,
 } from '../src';
 
 // https://emotion.sh/docs/@emotion/jest#tohavestylerule
@@ -20,13 +20,9 @@ const customRender = (ui, options) => {
       colorMode={{
         defaultValue: 'dark',
       }}
-      theme={{
-        ...theme,
-        config: {
-          ...theme.config,
-          useCSSVariables: options?.useCSSVariables,
-        },
-      }}
+      theme={createTheme({
+        cssVariables: options?.cssVariables,
+      })}
     >
       <PortalManager>
         <ToastManager>
diff --git a/packages/styled-system/src/__tests__/sx.test.js b/packages/styled-system/src/__tests__/sx.test.js
index 62007ae858..5a59919f38 100644
--- a/packages/styled-system/src/__tests__/sx.test.js
+++ b/packages/styled-system/src/__tests__/sx.test.js
@@ -280,11 +280,8 @@ const defaultTheme = {
 test('should pass', () => {
   const theme = {
     ...defaultTheme,
-    config: {
+    vars: {
       prefix: 'tonic',
-      useCSSVariables: true,
-    },
-    __cssVariableMap: {
       '--tonic-borders-1': '.0625rem solid',
       '--tonic-borders-2': '.125rem solid',
       '--tonic-borders-3': '.1875rem solid',
diff --git a/packages/styled-system/src/config/__tests__/margin.test.js b/packages/styled-system/src/config/__tests__/margin.test.js
index 8084feaf1a..b8985e7f7e 100644
--- a/packages/styled-system/src/config/__tests__/margin.test.js
+++ b/packages/styled-system/src/config/__tests__/margin.test.js
@@ -7,11 +7,8 @@ const defaultTheme = {
 
 const defaultThemeWithCSSVariables = {
   ...defaultTheme,
-  config: {
+  vars: {
     prefix: 'tonic',
-    useCSSVariables: true,
-  },
-  __cssVariableMap: {
     '--tonic-breakpoints-0': '40em',
     '--tonic-breakpoints-1': '52em',
     '--tonic-breakpoints-2': '64em',
diff --git a/packages/styled-system/src/config/__tests__/position.test.js b/packages/styled-system/src/config/__tests__/position.test.js
index 39752d7b02..3477f7b9cf 100644
--- a/packages/styled-system/src/config/__tests__/position.test.js
+++ b/packages/styled-system/src/config/__tests__/position.test.js
@@ -6,11 +6,8 @@ const defaultTheme = {
 
 const defaultThemeWithCSSVariables = {
   ...defaultTheme,
-  config: {
+  vars: {
     prefix: 'tonic',
-    useCSSVariables: true,
-  },
-  __cssVariableMap: {
     '--tonic-space-0': 0,
     '--tonic-space-1': 4,
     '--tonic-space-2': 8,
diff --git a/packages/styled-system/src/utils/transforms.js b/packages/styled-system/src/utils/transforms.js
index 4f7e816df5..6ba97a5fc7 100644
--- a/packages/styled-system/src/utils/transforms.js
+++ b/packages/styled-system/src/utils/transforms.js
@@ -11,11 +11,11 @@ const isSimpleCSSVariable = (value) => {
 // Negate the value, handling CSS variables and numeric values
 const toNegativeValue = (scale, absoluteValue, options) => {
   const theme = options?.props?.theme;
-  const useCSSVariables = !!(theme?.config?.useCSSVariables); // defaults to false
+  const hasCSSVariables = !!theme?.vars; // Defaults to false
   const n = getter(scale, absoluteValue, options);
 
   // Handle CSS variables for negative values
-  if (useCSSVariables && isSimpleCSSVariable(n)) {
+  if (hasCSSVariables && isSimpleCSSVariable(n)) {
     // https://stackoverflow.com/questions/49469344/using-negative-css-custom-properties
     return `calc(0px - ${n})`;
   }
@@ -30,11 +30,15 @@ const toNegativeValue = (scale, absoluteValue, options) => {
 
 export const getter = (scale, value, options) => {
   const theme = options?.props?.theme;
-  const prefix = theme?.config?.prefix; // defaults to 'tonic'
-  const useCSSVariables = !!(theme?.config?.useCSSVariables); // defaults to false
+  const hasCSSVariables = !!theme?.vars; // Defaults to false
   const result = get(scale, value);
 
-  if (result !== undefined && useCSSVariables) {
+  if (result !== undefined && hasCSSVariables) {
+    // TODO: `theme?.config?.prefix` and `theme?.__cssVariableMap` are deprecated and will be removed in the next major release
+    const cssVariablePrefixFallback = theme?.config?.prefix;
+    const cssVariablePrefix = (theme?.vars?.prefix) ?? cssVariablePrefixFallback;
+    const cssVariablesFallback = theme?.__cssVariableMap;
+    const cssVariables = (theme?.vars) ?? cssVariablesFallback;
     const contextScale = options?.context?.scale;
     const cssVariable = toCSSVariable(
       // | contextScale | value     |
@@ -42,9 +46,9 @@ export const getter = (scale, value, options) => {
       // | colors       | 'blue:50' |
       // | space        | 0         |
       [contextScale, String(value ?? '')].filter(Boolean).join('.'), // => 'colors.blue:50'
-      { prefix, delimiter: '-' },
+      { prefix: cssVariablePrefix, delimiter: '-' },
     ); // => '--tonic-colors-blue-50'
-    const cssVariableValue = theme?.__cssVariableMap?.[cssVariable]; // => '#578aef'
+    const cssVariableValue = cssVariables?.[cssVariable]; // => '#578aef'
     if (cssVariableValue !== undefined) {
       // => Replace '#578aef' with 'var(--tonic-colors-blue-50)'
       return String(result ?? '').replaceAll(cssVariableValue, `var(${cssVariable})`);
diff --git a/packages/theme/src/createTheme.js b/packages/theme/src/createTheme.js
index 04e41841ad..3f228c448c 100644
--- a/packages/theme/src/createTheme.js
+++ b/packages/theme/src/createTheme.js
@@ -168,6 +168,7 @@ const createTheme = (unit) => {
     'px': _px(foundation),
   }[unit] ?? foundation;
 
+  // TODO: Consider adding `Object.freeze(theme)` in a future major release
   return theme;
 };
 

From 45c3ba9cc0c9fb14d1d0b11c582ed0c69277f119 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Wed, 27 Nov 2024 15:03:08 +0800
Subject: [PATCH 08/18] docs: update package description

---
 packages/changelog-github/README.md           |  3 ++
 packages/changelog-github/package.json        |  2 +-
 packages/codemod/README.md                    |  2 +-
 packages/codemod/package.json                 |  2 +-
 packages/react-base/README.md                 |  2 +-
 packages/react-base/package.json              |  2 +-
 .../pages/components/index.page.mdx           |  4 ++-
 .../installation/index.page.mdx               | 29 ++++++++++++++-----
 .../react-docs/pages/hooks/index.page.mdx     |  4 ++-
 .../react-docs/pages/icons/index.page.mdx     |  4 ++-
 .../pages/styled-system/index.page.mdx        |  4 ++-
 .../react-docs/pages/theme/index.page.mdx     |  4 ++-
 packages/react-hooks/README.md                |  2 +-
 packages/react-hooks/package.json             |  2 +-
 packages/react-icons/README.md                |  2 +-
 packages/react-icons/package.json             |  2 +-
 packages/react/README.md                      |  2 +-
 packages/react/package.json                   |  2 +-
 packages/styled-system/README.md              |  2 +-
 packages/styled-system/package.json           |  2 +-
 packages/theme/README.md                      |  2 +-
 packages/theme/package.json                   |  2 +-
 packages/utils/README.md                      |  2 +-
 packages/utils/package.json                   |  2 +-
 24 files changed, 56 insertions(+), 30 deletions(-)
 create mode 100644 packages/changelog-github/README.md

diff --git a/packages/changelog-github/README.md b/packages/changelog-github/README.md
new file mode 100644
index 0000000000..360a5409a8
--- /dev/null
+++ b/packages/changelog-github/README.md
@@ -0,0 +1,3 @@
+# @tonic-ui/changelog-github
+
+A tool for generating changelogs with links to GitHub commits, PRs, and users.
diff --git a/packages/changelog-github/package.json b/packages/changelog-github/package.json
index 7fb64bedca..3cd816436d 100644
--- a/packages/changelog-github/package.json
+++ b/packages/changelog-github/package.json
@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "@tonic-ui/changelog-github",
-  "description": "A changelog entry generator for GitHub that links to commits, PRs and users",
+  "description": "A tool for generating changelogs with links to GitHub commits, PRs, and users.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/codemod/README.md b/packages/codemod/README.md
index b5dc821808..93a53754b2 100644
--- a/packages/codemod/README.md
+++ b/packages/codemod/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/codemod
 
-This repository contains a collection of codemod scripts based for use with [jscodeshift](https://github.com/facebook/jscodeshift) that help update the APIs.
+A set of codemod scripts designed to simplify the migration and updating of Tonic UI applications.
 
 ## Usage
 
diff --git a/packages/codemod/package.json b/packages/codemod/package.json
index 93cfc2f37b..c3e6aea72d 100644
--- a/packages/codemod/package.json
+++ b/packages/codemod/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/codemod",
   "version": "2.1.0",
-  "description": "Codemod scripts for Tonic UI",
+  "description": "A set of codemod scripts designed to simplify the migration and updating of Tonic UI applications.",
   "bin": "./codemod-cli.js",
   "files": [
     "codemod-cli.js",
diff --git a/packages/react-base/README.md b/packages/react-base/README.md
index 5d4a651a77..2661b56987 100644
--- a/packages/react-base/README.md
+++ b/packages/react-base/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/react-base
 
-A library of headless React UI components.
+Headless React components intended for creating custom UI elements.
 
 ## Installation
 
diff --git a/packages/react-base/package.json b/packages/react-base/package.json
index 19cad70d26..c3dcde8f4a 100644
--- a/packages/react-base/package.json
+++ b/packages/react-base/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/react-base",
   "version": "2.0.1",
-  "description": "A library of headless React UI components.",
+  "description": "Headless React components intended for creating custom UI elements.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/react-docs/pages/components/index.page.mdx b/packages/react-docs/pages/components/index.page.mdx
index 1828e15d46..0ef32bd95a 100644
--- a/packages/react-docs/pages/components/index.page.mdx
+++ b/packages/react-docs/pages/components/index.page.mdx
@@ -1,6 +1,8 @@
+import pkg from '@tonic-ui/react/package.json';
+
 # React Components
 
-React Tonic UI component library.
+{pkg.description}
 
 ## Installation
 
diff --git a/packages/react-docs/pages/getting-started/installation/index.page.mdx b/packages/react-docs/pages/getting-started/installation/index.page.mdx
index 964129497c..4c578ec3b3 100644
--- a/packages/react-docs/pages/getting-started/installation/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/installation/index.page.mdx
@@ -1,3 +1,13 @@
+import pkg_changelog_github from '@tonic-ui/changelog-github/package.json';
+import pkg_codemod from '@tonic-ui/codemod/package.json';
+import pkg_react from '@tonic-ui/react/package.json';
+import pkg_react_base from '@tonic-ui/react-base/package.json';
+import pkg_react_hooks from '@tonic-ui/react-hooks/package.json';
+import pkg_react_icons from '@tonic-ui/react-icons/package.json';
+import pkg_styled_system from '@tonic-ui/styled-system/package.json';
+import pkg_theme from '@tonic-ui/theme/package.json';
+import pkg_utils from '@tonic-ui/utils/package.json';
+
 # Installation
 
 Inside your React project directory, install React Tonic UI component library either using npm or yarn:
@@ -14,11 +24,14 @@ It will install all the dependencies for you.
 
 ## Packages
 
-| Name | Description | [GitHub](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages) | [NPM](https://www.npmjs.com/settings/tonic-ui/packages) | [Documentation](../getting-started) |
-| :--- | :---------- | :----------------------------------------------------------------------------- | :------------------------------------------------------ | :---------------------------------- |
-| `@tonic-ui/react` | React Tonic UI component library. | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react) | [View](https://www.npmjs.com/package/@tonic-ui/react) | [View](../components) |
-| `@tonic-ui/react-base` | A library of headless React UI components. | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react-base) | [View](https://www.npmjs.com/package/@tonic-ui/react-base) | [View](../base) |
-| `@tonic-ui/react-hooks` | A collection of React Hooks for Tonic UI components. | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react-hooks) | [View](https://www.npmjs.com/package/@tonic-ui/react-hooks) | [View](../hooks) |
-| `@tonic-ui/react-icons` | Tonic icons distributed as SVG React components. | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react-icons) | [View](https://www.npmjs.com/package/@tonic-ui/react-icons) | [View](../icons) |
-| `@tonic-ui/styled-system` | The framework agnostic styling engine for Tonic UI. | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/styled-system) | [View](https://www.npmjs.com/package/@tonic-ui/styled-system) | [View](../styled-system) |
-| `@tonic-ui/theme` | The default theme package for Tonic UI components. | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/theme) | [View](https://www.npmjs.com/package/@tonic-ui/theme) | [View](../theme) |
+| Name | Description | GitHub | NPM | Documentation |
+| :--- | :---------- | :----- | :-- | :------------ |
+| `@tonic-ui/changelog-github` | {pkg_changelog_github.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/changelog-github) | - | - |
+| `@tonic-ui/codemod` | {pkg_codemod.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/codemod) | [View](https://www.npmjs.com/package/@tonic-ui/codemod) | - |
+| `@tonic-ui/react` | {pkg_react.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react) | [View](https://www.npmjs.com/package/@tonic-ui/react) | [View](../components) |
+| `@tonic-ui/react-base` | {pkg_react_base.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react-base) | [View](https://www.npmjs.com/package/@tonic-ui/react-base) | - |
+| `@tonic-ui/react-hooks` | {pkg_react_hooks.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react-hooks) | [View](https://www.npmjs.com/package/@tonic-ui/react-hooks) | [View](../hooks) |
+| `@tonic-ui/react-icons` | {pkg_react_icons.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/react-icons) | [View](https://www.npmjs.com/package/@tonic-ui/react-icons) | [View](../icons) |
+| `@tonic-ui/styled-system` | {pkg_styled_system.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/styled-system) | [View](https://www.npmjs.com/package/@tonic-ui/styled-system) | [View](../styled-system) |
+| `@tonic-ui/theme` | {pkg_theme.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/theme) | [View](https://www.npmjs.com/package/@tonic-ui/theme) | [View](../theme) |
+| `@tonic-ui/utils` | {pkg_utils.description} | [View](https://github.com/trendmicro-frontend/tonic-ui/tree/master/packages/utils) | [View](https://www.npmjs.com/package/@tonic-ui/utils) | - |
diff --git a/packages/react-docs/pages/hooks/index.page.mdx b/packages/react-docs/pages/hooks/index.page.mdx
index 6f2688be3f..b88d2345d9 100644
--- a/packages/react-docs/pages/hooks/index.page.mdx
+++ b/packages/react-docs/pages/hooks/index.page.mdx
@@ -1,6 +1,8 @@
+import pkg from '@tonic-ui/react-hooks/package.json';
+
 # React Hooks
 
-A collection of React Hooks for Tonic UI components.
+{pkg.description}
 
 ## Installation
 
diff --git a/packages/react-docs/pages/icons/index.page.mdx b/packages/react-docs/pages/icons/index.page.mdx
index 2b08578387..48c3ac8408 100644
--- a/packages/react-docs/pages/icons/index.page.mdx
+++ b/packages/react-docs/pages/icons/index.page.mdx
@@ -1,6 +1,8 @@
+import pkg from '@tonic-ui/react-icons/package.json';
+
 # React Icons
 
-Tonic icons distributed as SVG React components.
+{pkg.description}
 
 ## Installation
 
diff --git a/packages/react-docs/pages/styled-system/index.page.mdx b/packages/react-docs/pages/styled-system/index.page.mdx
index 592a5e0f33..1396c779be 100644
--- a/packages/react-docs/pages/styled-system/index.page.mdx
+++ b/packages/react-docs/pages/styled-system/index.page.mdx
@@ -1,6 +1,8 @@
+import pkg from '@tonic-ui/styled-system/package.json';
+
 # Styled System
 
-The framework agnostic styling engine for Tonic UI.
+{pkg.description}
 
 ## Installation
 
diff --git a/packages/react-docs/pages/theme/index.page.mdx b/packages/react-docs/pages/theme/index.page.mdx
index 95ccd7a55a..c57ccbbcab 100644
--- a/packages/react-docs/pages/theme/index.page.mdx
+++ b/packages/react-docs/pages/theme/index.page.mdx
@@ -1,6 +1,8 @@
+import pkg from '@tonic-ui/theme/package.json';
+
 # Theme
 
-The default theme package for Tonic UI components.
+{pkg.description}
 
 ## Installation
 
diff --git a/packages/react-hooks/README.md b/packages/react-hooks/README.md
index a9ef4b6249..98eaf3de8c 100644
--- a/packages/react-hooks/README.md
+++ b/packages/react-hooks/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/react-hooks
 
-A collection of React Hooks for Tonic UI components.
+A set of React Hooks specifically for use with Tonic UI components.
 
 ## Installation
 
diff --git a/packages/react-hooks/package.json b/packages/react-hooks/package.json
index 8dbe871f04..0084affbc2 100644
--- a/packages/react-hooks/package.json
+++ b/packages/react-hooks/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/react-hooks",
   "version": "2.0.0",
-  "description": "A collection of React Hooks for Tonic UI components.",
+  "description": "A set of React Hooks specifically for use with Tonic UI components.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/react-icons/README.md b/packages/react-icons/README.md
index b879a029cd..e1c5dc852b 100644
--- a/packages/react-icons/README.md
+++ b/packages/react-icons/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/react-icons
 
-Tonic icons distributed as SVG React components.
+A set of SVG icons available as React components for use in Tonic UI.
 
 ## Installation
 
diff --git a/packages/react-icons/package.json b/packages/react-icons/package.json
index ceca843743..a9e2071496 100644
--- a/packages/react-icons/package.json
+++ b/packages/react-icons/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/react-icons",
   "version": "2.1.0",
-  "description": "Tonic icons distributed as SVG React components.",
+  "description": "A set of SVG icons available as React components for use in Tonic UI.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/react/README.md b/packages/react/README.md
index 9d1e597ada..31756acfe3 100644
--- a/packages/react/README.md
+++ b/packages/react/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/react
 
-React Tonic UI component library.
+A comprehensive React component library for Tonic UI.
 
 ## Installation
 
diff --git a/packages/react/package.json b/packages/react/package.json
index 1f9167bee4..03958d77e9 100644
--- a/packages/react/package.json
+++ b/packages/react/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/react",
   "version": "2.4.0",
-  "description": "React Tonic UI component library.",
+  "description": "A comprehensive React component library for Tonic UI.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/styled-system/README.md b/packages/styled-system/README.md
index 8c53a03b90..41c4387b61 100644
--- a/packages/styled-system/README.md
+++ b/packages/styled-system/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/styled-system
 
-The framework agnostic styling engine for Tonic UI.
+A framework-independent styling engine for Tonic UI.
 
 ## Installation
 
diff --git a/packages/styled-system/package.json b/packages/styled-system/package.json
index 56c9f277aa..da12db9812 100644
--- a/packages/styled-system/package.json
+++ b/packages/styled-system/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/styled-system",
   "version": "2.0.2",
-  "description": "The framework agnostic styling engine for Tonic UI.",
+  "description": "A framework-independent styling engine for Tonic UI.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/theme/README.md b/packages/theme/README.md
index 2fa8b4f711..0b1c0ee478 100644
--- a/packages/theme/README.md
+++ b/packages/theme/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/theme
 
-The default theme package for Tonic UI components.
+The default theme configuration for Tonic UI components.
 
 ## Installation
 
diff --git a/packages/theme/package.json b/packages/theme/package.json
index 57589500af..d61a56fe9d 100644
--- a/packages/theme/package.json
+++ b/packages/theme/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/theme",
   "version": "2.0.0",
-  "description": "The default theme package for Tonic UI components.",
+  "description": "The default theme configuration for Tonic UI components.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [
diff --git a/packages/utils/README.md b/packages/utils/README.md
index c25888dc53..45e18adc32 100644
--- a/packages/utils/README.md
+++ b/packages/utils/README.md
@@ -1,6 +1,6 @@
 # @tonic-ui/utils
 
-Common utilities for various Tonic UI components and packages.
+A set of utility functions shared across Tonic UI components and packages.
 
 ## Installation
 
diff --git a/packages/utils/package.json b/packages/utils/package.json
index 5e24cb4123..6bd71c6f00 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@tonic-ui/utils",
   "version": "2.1.0",
-  "description": "Common utilities for various Tonic UI components and packages.",
+  "description": "A set of utility functions shared across Tonic UI components and packages.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "files": [

From 6931f950c26d56934c6bb84f7159ae14d27412bf Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Wed, 27 Nov 2024 23:17:36 +0800
Subject: [PATCH 09/18] docs: update docs

---
 packages/react-docs/components/Demo.js        | 10 ++---
 .../{CodeBlock.js => PreformattedText.js}     |  8 ++--
 packages/react-docs/components/ThemeParser.js |  6 +--
 .../components/color-style/index.page.mdx     | 40 +++++++++----------
 .../components/date-pickers/calendar/usage.js | 29 +++-----------
 .../date-pickers/date-picker/usage.js         | 27 +++----------
 .../pages/components/drawer/usage.js          | 23 ++---------
 .../pages/components/modal/usage.js           | 27 +++----------
 .../react-docs/pages/hooks/useOutsideClick.js | 31 ++++----------
 9 files changed, 57 insertions(+), 144 deletions(-)
 rename packages/react-docs/components/{CodeBlock.js => PreformattedText.js} (79%)

diff --git a/packages/react-docs/components/Demo.js b/packages/react-docs/components/Demo.js
index 19e49ff556..59762e0f43 100644
--- a/packages/react-docs/components/Demo.js
+++ b/packages/react-docs/components/Demo.js
@@ -113,8 +113,8 @@ const Demo = ({
       >
         <IconButton
           data-track={showSourceCode
-            ? `CodeBlock|hide_source|${x({ path: router.pathname })}`
-            : `CodeBlock|show_source|${x({ path: router.pathname })}`
+            ? `Code|hide_source|${x({ path: router.pathname })}`
+            : `Code|show_source|${x({ path: router.pathname })}`
           }
           onClick={toggleShowSourceCode}
         >
@@ -123,7 +123,7 @@ const Demo = ({
           </Tooltip>
         </IconButton>
         <IconButton
-          data-track={`CodeBlock|copy_source|${x({ path: router.pathname })}`}
+          data-track={`Code|copy_source|${x({ path: router.pathname })}`}
           onClick={handleClickCopySource}
         >
           <Tooltip label={hasCopiedSource ? 'Copied' : 'Copy the source'}>
@@ -131,7 +131,7 @@ const Demo = ({
           </Tooltip>
         </IconButton>
         <IconButton
-          data-track={`CodeBlock|edit_in_codesandbox|${router.pathname}`}
+          data-track={`Code|edit_in_codesandbox|${router.pathname}`}
           onClick={handleClickEditInCodeSandbox}
         >
           <Tooltip label="Edit in CodeSandbox">
@@ -139,7 +139,7 @@ const Demo = ({
           </Tooltip>
         </IconButton>
         <IconButton
-          data-track={`CodeBlock|reset|${router.pathname}`}
+          data-track={`Code|reset|${router.pathname}`}
           onClick={reset}
         >
           <Tooltip label="Reset the demo">
diff --git a/packages/react-docs/components/CodeBlock.js b/packages/react-docs/components/PreformattedText.js
similarity index 79%
rename from packages/react-docs/components/CodeBlock.js
rename to packages/react-docs/components/PreformattedText.js
index c39bcc1893..f5e0753730 100644
--- a/packages/react-docs/components/CodeBlock.js
+++ b/packages/react-docs/components/PreformattedText.js
@@ -1,14 +1,14 @@
 import {
-  Box,
+  Text,
   useColorStyle,
 } from '@tonic-ui/react';
 import React from 'react';
 
-const CodeBlock = (props) => {
+const PreformattedText = (props) => {
   const [colorStyle] = useColorStyle();
 
   return (
-    <Box
+    <Text
       backgroundColor={colorStyle.background.secondary}
       border={1}
       borderColor={colorStyle.divider}
@@ -21,4 +21,4 @@ const CodeBlock = (props) => {
   );
 };
 
-export default CodeBlock;
+export default PreformattedText;
diff --git a/packages/react-docs/components/ThemeParser.js b/packages/react-docs/components/ThemeParser.js
index b8d199b275..6a4dd82f35 100644
--- a/packages/react-docs/components/ThemeParser.js
+++ b/packages/react-docs/components/ThemeParser.js
@@ -5,7 +5,7 @@ import {
   useTheme,
 } from '@tonic-ui/react';
 import React from 'react';
-import CodeBlock from './CodeBlock';
+import PreformattedText from './PreformattedText';
 import jsonPrettify from '../utils/json-prettify';
 
 const ThemeParser = ({
@@ -33,9 +33,9 @@ const ThemeParser = ({
 
   return (
     <Box mb="6x">
-      <CodeBlock>
+      <PreformattedText>
         {`const ${themeKey} = ${jsonPrettify(token, indent)}`}
-      </CodeBlock>
+      </PreformattedText>
     </Box>
   );
 };
diff --git a/packages/react-docs/pages/components/color-style/index.page.mdx b/packages/react-docs/pages/components/color-style/index.page.mdx
index 2696bd9b84..c5dcb26c7c 100644
--- a/packages/react-docs/pages/components/color-style/index.page.mdx
+++ b/packages/react-docs/pages/components/color-style/index.page.mdx
@@ -13,11 +13,11 @@ import {
   MoonIcon,
   SunIcon,
 } from '@tonic-ui/react-icons';
-import CodeBlock from '@/components/CodeBlock';
+import colorStyle from '@/pages/components/color-style/color-style';
 import ColorStyleBody from '@/components/ColorStyleBody';
 import ColorStyleContent from '@/components/ColorStyleContent';
 import ColorStyleHeader from '@/components/ColorStyleHeader';
-import colorStyle from '@/pages/components/color-style/color-style';
+import PreformattedText from '@/components/PreformattedText';
 import jsonPrettify from "@/utils/json-prettify";
 
 # Color Style
@@ -71,9 +71,9 @@ import { colorStyle } from '@tonic-ui/react';
 
 The full configuration is displayed below:
 
-<CodeBlock mb="4x">
+<PreformattedText mb="4x">
   {jsonPrettify(colorStyle)}
-</CodeBlock>
+</PreformattedText>
 
 To manage color style in your application, you can use the [useColorStyle](../components/color-style/useColorStyle) hook.
 
@@ -290,7 +290,7 @@ const App = () => (
 
 Here is the deprecated configuration for the severity:
 
-<CodeBlock>
+<PreformattedText>
   {jsonPrettify({
     dark: {
       severity: {
@@ -315,7 +315,7 @@ Here is the deprecated configuration for the severity:
       },
     },
   })}
-</CodeBlock>
+</PreformattedText>
 
 ### Chart (deprecated)
 
@@ -324,7 +324,7 @@ Here is the deprecated configuration for the severity:
 
 Here is the deprecated configuration for the chart:
 
-<CodeBlock>
+<PreformattedText>
   {jsonPrettify({
     dark: {
       chart: {
@@ -365,7 +365,7 @@ Here is the deprecated configuration for the chart:
       },
     },
   })}
-</CodeBlock>
+</PreformattedText>
 
 ## Custom Color Values
 
@@ -378,7 +378,7 @@ The purpose of notifications is to provide feedback to users regarding the succe
 See the example configuration below:
 
 <Stack spacing="4x">
-  <CodeBlock>
+  <PreformattedText>
     {jsonPrettify({
       dark: {
         notification: {
@@ -397,7 +397,7 @@ See the example configuration below:
         },
       },
     })}
-  </CodeBlock>
+  </PreformattedText>
   <DarkMode>
     <ColorStyleContent>
       <ColorStyleHeader>
@@ -456,7 +456,7 @@ None | N/A | Used when it's impossible to determine either the likelihood or pot
 See the example configuration below:
 
 <Stack spacing="4x">
-  <CodeBlock>
+  <PreformattedText>
     {jsonPrettify({
       dark: {
         risk: {
@@ -475,7 +475,7 @@ See the example configuration below:
         },
       },
     })}
-  </CodeBlock>
+  </PreformattedText>
   <DarkMode>
     <ColorStyleContent>
       <ColorStyleHeader>
@@ -537,7 +537,7 @@ Informational | Used for non-severe information and general guidance.
 See the example configuration below:
 
 <Stack spacing="4x">
-  <CodeBlock>
+  <PreformattedText>
     {jsonPrettify({
       dark: {
         severity: {
@@ -558,7 +558,7 @@ See the example configuration below:
         },
       },
     })}
-  </CodeBlock>
+  </PreformattedText>
   <DarkMode>
     <ColorStyleContent>
       <ColorStyleHeader>
@@ -612,7 +612,7 @@ See the example configuration below:
 See the example configuration below:
 
 <Stack spacing="4x">
-  <CodeBlock>
+  <PreformattedText>
     {jsonPrettify({
       dark: {
         chart: {
@@ -653,7 +653,7 @@ See the example configuration below:
         },
       },
     })}
-  </CodeBlock>
+  </PreformattedText>
   <DarkMode>
     <ColorStyleContent>
       <ColorStyleHeader>
@@ -729,7 +729,7 @@ See the example configuration below:
 See the example configuration below:
 
 <Stack spacing="4x">
-  <CodeBlock>
+  <PreformattedText>
     {jsonPrettify({
       dark: {
         gradient: {
@@ -752,7 +752,7 @@ See the example configuration below:
         },
       },
     })}
-  </CodeBlock>
+  </PreformattedText>
   <ColorStyleContent
     display="flex"
     flexDirection="column"
@@ -812,7 +812,7 @@ See the example configuration below:
 See the example configuration below:
 
 <Stack spacing="4x">
-  <CodeBlock>
+  <PreformattedText>
     {jsonPrettify({
       dark: {
         blindness: {
@@ -852,7 +852,7 @@ See the example configuration below:
         },
       },
     })}
-  </CodeBlock>
+  </PreformattedText>
   <ColorStyleContent
     display="flex"
     flexDirection="column"
diff --git a/packages/react-docs/pages/components/date-pickers/calendar/usage.js b/packages/react-docs/pages/components/date-pickers/calendar/usage.js
index a351427a15..405f8afc66 100644
--- a/packages/react-docs/pages/components/date-pickers/calendar/usage.js
+++ b/packages/react-docs/pages/components/date-pickers/calendar/usage.js
@@ -14,30 +14,11 @@ import {
   MenuList,
   Text,
   TextLabel,
-  useColorMode,
-  useColorStyle,
 } from '@tonic-ui/react';
 import * as dateFns from 'date-fns'
 import * as dateFnsLocale from 'date-fns/locale'
 import React, { useEffect, useState } from 'react';
-
-const CodeBlock = (props) => {
-  const [colorMode] = useColorMode();
-  const [colorStyle] = useColorStyle({ colorMode });
-
-  return (
-    <Box
-      backgroundColor={colorStyle.background.secondary}
-      border={1}
-      borderColor={colorStyle.divider}
-      fontFamily="mono"
-      py="3x"
-      px="3x"
-      whiteSpace="pre"
-      {...props}
-    />
-  );
-};
+import PreformattedText from '@/components/PreformattedText';
 
 const FormGroup = (props) => (
   <Box mb="4x" {...props} />
@@ -185,12 +166,12 @@ const App = () => {
         <TextLabel>
           You can use the <Code>formatDate</Code> prop to return a formatted date string in the given format and locale.
         </TextLabel>
-        <CodeBlock>
+        <PreformattedText>
           {`// format\nimport format from 'date-fns/format';\n\n// locale\nimport enLocale from 'date-fns/locale/en-US'; // English (United States)\nimport deLocale from 'date-fns/locale/de'; // Deutsch\nimport esLocale from 'date-fns/locale/es'; // Español\nimport frLocale from 'date-fns/locale/fr'; // Français\nimport itLocale from 'date-fns/locale/it'; // Italiano\nimport jaLocale from 'date-fns/locale/ja'; // 日本語\nimport koLocale from 'date-fns/locale/ko'; // 한국어\nimport zhCNLocale from 'date-fns/locale/zh-CN'; // 简体中文\nimport zhTWLocale from 'date-fns/locale/zh-TW'; // 繁體中文`}
-        </CodeBlock>
-        <CodeBlock>
+        </PreformattedText>
+        <PreformattedText>
           {`// Calendar component\nformatDate={(date, format, options) => {\n  return format(date, format, { locale: enLocale });\n}}`}
-        </CodeBlock>
+        </PreformattedText>
       </Flex>
       <Divider my="4x" />
       <Box mb="4x">
diff --git a/packages/react-docs/pages/components/date-pickers/date-picker/usage.js b/packages/react-docs/pages/components/date-pickers/date-picker/usage.js
index 5adb2a1357..4904ab4a08 100644
--- a/packages/react-docs/pages/components/date-pickers/date-picker/usage.js
+++ b/packages/react-docs/pages/components/date-pickers/date-picker/usage.js
@@ -28,24 +28,7 @@ import {
 import * as dateFns from 'date-fns'
 import * as dateFnsLocale from 'date-fns/locale'
 import React, { useEffect, useState } from 'react';
-
-const CodeBlock = (props) => {
-  const [colorMode] = useColorMode();
-  const [colorStyle] = useColorStyle({ colorMode });
-
-  return (
-    <Box
-      backgroundColor={colorStyle.background.secondary}
-      border={1}
-      borderColor={colorStyle.divider}
-      fontFamily="mono"
-      py="3x"
-      px="3x"
-      whiteSpace="pre"
-      {...props}
-    />
-  );
-};
+import PreformattedText from '@/components/PreformattedText';
 
 const FormGroup = (props) => (
   <Box mb="4x" {...props} />
@@ -239,12 +222,12 @@ const App = () => {
         <TextLabel>
           You can use the <Code>formatDate</Code> prop to return a formatted date string in the given format and locale.
         </TextLabel>
-        <CodeBlock>
+        <PreformattedText>
           {`// format\nimport format from 'date-fns/format';\n\n// locale\nimport enLocale from 'date-fns/locale/en-US'; // English (United States)\nimport deLocale from 'date-fns/locale/de'; // Deutsch\nimport esLocale from 'date-fns/locale/es'; // Español\nimport frLocale from 'date-fns/locale/fr'; // Français\nimport itLocale from 'date-fns/locale/it'; // Italiano\nimport jaLocale from 'date-fns/locale/ja'; // 日本語\nimport koLocale from 'date-fns/locale/ko'; // 한국어\nimport zhCNLocale from 'date-fns/locale/zh-CN'; // 简体中文\nimport zhTWLocale from 'date-fns/locale/zh-TW'; // 繁體中文`}
-        </CodeBlock>
-        <CodeBlock>
+        </PreformattedText>
+        <PreformattedText>
           {`// DatePicker component\nformatDate={(date, format, options) => {\n  return format(date, format, { locale: enLocale });\n}}`}
-        </CodeBlock>
+        </PreformattedText>
       </Flex>
       <Divider my="4x" />
       <Box mb="4x">
diff --git a/packages/react-docs/pages/components/drawer/usage.js b/packages/react-docs/pages/components/drawer/usage.js
index 4a07397d0c..0232489fc9 100644
--- a/packages/react-docs/pages/components/drawer/usage.js
+++ b/packages/react-docs/pages/components/drawer/usage.js
@@ -31,26 +31,9 @@ import {
   useToggle,
 } from '@tonic-ui/react-hooks';
 import React, { useRef, useState } from 'react';
+import PreformattedText from '@/components/PreformattedText';
 import SkeletonBlock from '@/components/SkeletonBlock';
 
-const CodeBlock = (props) => {
-  const [colorMode] = useColorMode();
-  const [colorStyle] = useColorStyle({ colorMode });
-
-  return (
-    <Box
-      backgroundColor={colorStyle.background.secondary}
-      border={1}
-      borderColor={colorStyle.divider}
-      fontFamily="mono"
-      py="3x"
-      px="3x"
-      whiteSpace="pre"
-      {...props}
-    />
-  );
-};
-
 const FormGroup = (props) => (
   <Box mb="4x" {...props} />
 );
@@ -318,9 +301,9 @@ const App = () => {
             <strong>Body Scroll Locking</strong> is currently not available with default setup, you can follow the instructions below to append global styles to the body to prevent scrolling.
           </Text>
         </Box>
-        <CodeBlock>
+        <PreformattedText>
           {bodyScrollLockCode}
-        </CodeBlock>
+        </PreformattedText>
       </Box>
     </FormGroup>
     <Drawer
diff --git a/packages/react-docs/pages/components/modal/usage.js b/packages/react-docs/pages/components/modal/usage.js
index 36036437a6..d0657c5f1c 100644
--- a/packages/react-docs/pages/components/modal/usage.js
+++ b/packages/react-docs/pages/components/modal/usage.js
@@ -33,26 +33,9 @@ import {
   useToggle,
 } from '@tonic-ui/react-hooks';
 import React, { useRef, useState } from 'react';
+import PreformattedText from '@/components/PreformattedText';
 import SkeletonBlock from '@/components/SkeletonBlock';
 
-const CodeBlock = (props) => {
-  const [colorMode] = useColorMode();
-  const [colorStyle] = useColorStyle({ colorMode });
-
-  return (
-    <Box
-      backgroundColor={colorStyle.background.secondary}
-      border={1}
-      borderColor={colorStyle.divider}
-      fontFamily="mono"
-      py="3x"
-      px="3x"
-      whiteSpace="pre"
-      {...props}
-    />
-  );
-};
-
 const FormGroup = (props) => (
   <Box mb="4x" {...props} />
 );
@@ -336,9 +319,9 @@ const App = () => {
           Pass below props to ModalContent for settings initial height and vertical margins. Note that the props are different when <Code>scrollBehavior</Code> changes.
         </TextLabel>
       </Box>
-      <CodeBlock>
+      <PreformattedText>
         {`const modalStyleProps = ${JSON.stringify(modalStyleProps, null, 2)};\nconst modalContentStyleProps = ${JSON.stringify(modalContentStyleProps, null, 2)};\n\n// example\n<Modal\n  scrollBehavior="${scrollBehavior}"\n  {...modalStyleProps}\n>\n  <ModalOverlay />\n  <ModalContent {...contentStyleProps}>\n    <ModalHeader />\n    <ModalBody />\n    <ModalFooter />\n  </ModalContent>\n</Modal>`}
-      </CodeBlock>
+      </PreformattedText>
     </FormGroup>
     <Divider my="4x" />
     <Box mb="4x">
@@ -400,9 +383,9 @@ const App = () => {
             <strong>Body Scroll Locking</strong> is currently not available with default setup, you can follow the instructions below to append global styles to the body to prevent scrolling.
           </Text>
         </Box>
-        <CodeBlock>
+        <PreformattedText>
           {bodyScrollLockCode}
-        </CodeBlock>
+        </PreformattedText>
       </Box>
     </FormGroup>
     <Modal
diff --git a/packages/react-docs/pages/hooks/useOutsideClick.js b/packages/react-docs/pages/hooks/useOutsideClick.js
index 1e25c67614..b76cd5747d 100644
--- a/packages/react-docs/pages/hooks/useOutsideClick.js
+++ b/packages/react-docs/pages/hooks/useOutsideClick.js
@@ -1,24 +1,7 @@
 import { Box, Divider, Flex, Radio, RadioGroup, Text, TextLabel, useColorMode, useColorStyle } from '@tonic-ui/react';
 import { useOutsideClick } from '@tonic-ui/react-hooks';
 import React, { useCallback, useRef, useState } from 'react';
-
-const CodeBlock = (props) => {
-  const [colorMode] = useColorMode();
-  const [colorStyle] = useColorStyle({ colorMode });
-
-  return (
-    <Box
-      backgroundColor={colorStyle.background.secondary}
-      border={1}
-      borderColor={colorStyle.divider}
-      fontFamily="mono"
-      py="3x"
-      px="3x"
-      whiteSpace="pre"
-      {...props}
-    />
-  );
-};
+import PreformattedText from '@/components/PreformattedText';
 
 const FormGroup = (props) => (
   <Box mb="4x" {...props} />
@@ -73,19 +56,19 @@ const App = () => {
         </RadioGroup>
       </FormGroup>
       {eventOption === 'pointerDown' && (
-        <CodeBlock>
+        <PreformattedText>
           {`useOutsideClick(ref, handler, [${pointerDownEvents.map(x => `'${x}'`).join(', ')}]); // or "useOutsideClick(ref, handler)"`}
-        </CodeBlock>
+        </PreformattedText>
       )}
       {eventOption === 'pointerUp' && (
-        <CodeBlock>
+        <PreformattedText>
           {`useOutsideClick(ref, handler, [${pointerUpEvents.map(x => `'${x}'`).join(', ')}]);`}
-        </CodeBlock>
+        </PreformattedText>
       )}
       {eventOption === 'none' && (
-        <CodeBlock>
+        <PreformattedText>
           {'useOutsideClick(ref, handler, false);'}
-        </CodeBlock>
+        </PreformattedText>
       )}
       <Divider my="4x" />
       <Box mb="4x">

From 6b4e3e87979f3f77f2c2246081cfa5919085e154 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Thu, 28 Nov 2024 09:44:18 +0800
Subject: [PATCH 10/18] docs: update the package installation command

---
 packages/react-docs/pages/components/index.page.mdx           | 4 ++--
 .../pages/getting-started/installation/index.page.mdx         | 4 ++--
 packages/react-docs/pages/hooks/index.page.mdx                | 4 ++--
 packages/react-docs/pages/icons/index.page.mdx                | 4 ++--
 packages/react-docs/pages/styled-system/index.page.mdx        | 4 ++--
 packages/react-docs/pages/theme/index.page.mdx                | 4 ++--
 6 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/react-docs/pages/components/index.page.mdx b/packages/react-docs/pages/components/index.page.mdx
index 0ef32bd95a..cf4380e6a7 100644
--- a/packages/react-docs/pages/components/index.page.mdx
+++ b/packages/react-docs/pages/components/index.page.mdx
@@ -8,8 +8,8 @@ import pkg from '@tonic-ui/react/package.json';
 
 ```bash
 // with npm
-npm install @tonic-ui/react@2.x
+npm install @tonic-ui/react
 
 // with yarn
-yarn add @tonic-ui/react@2.x
+yarn add @tonic-ui/react
 ```
diff --git a/packages/react-docs/pages/getting-started/installation/index.page.mdx b/packages/react-docs/pages/getting-started/installation/index.page.mdx
index 4c578ec3b3..9b9cc0a536 100644
--- a/packages/react-docs/pages/getting-started/installation/index.page.mdx
+++ b/packages/react-docs/pages/getting-started/installation/index.page.mdx
@@ -13,11 +13,11 @@ import pkg_utils from '@tonic-ui/utils/package.json';
 Inside your React project directory, install React Tonic UI component library either using npm or yarn:
 
 ```bash
-npm install @tonic-ui/react@2.x
+npm install @tonic-ui/react
 ```
 
 ```bash
-yarn add @tonic-ui/react@2.x
+yarn add @tonic-ui/react
 ```
 
 It will install all the dependencies for you.
diff --git a/packages/react-docs/pages/hooks/index.page.mdx b/packages/react-docs/pages/hooks/index.page.mdx
index b88d2345d9..6486243947 100644
--- a/packages/react-docs/pages/hooks/index.page.mdx
+++ b/packages/react-docs/pages/hooks/index.page.mdx
@@ -8,8 +8,8 @@ import pkg from '@tonic-ui/react-hooks/package.json';
 
 ```bash
 // with npm
-npm install @tonic-ui/react-hooks@2.x
+npm install @tonic-ui/react-hooks
 
 // with yarn
-yarn add @tonic-ui/react-hooks@2.x
+yarn add @tonic-ui/react-hooks
 ```
diff --git a/packages/react-docs/pages/icons/index.page.mdx b/packages/react-docs/pages/icons/index.page.mdx
index 48c3ac8408..c66c58207c 100644
--- a/packages/react-docs/pages/icons/index.page.mdx
+++ b/packages/react-docs/pages/icons/index.page.mdx
@@ -8,10 +8,10 @@ import pkg from '@tonic-ui/react-icons/package.json';
 
 ```bash
 // with npm
-npm install @tonic-ui/react-icons@2.x
+npm install @tonic-ui/react-icons
 
 // with yarn
-yarn add @tonic-ui/react-icons@2.x
+yarn add @tonic-ui/react-icons
 ```
 
 ## Usage
diff --git a/packages/react-docs/pages/styled-system/index.page.mdx b/packages/react-docs/pages/styled-system/index.page.mdx
index 1396c779be..305d3731cb 100644
--- a/packages/react-docs/pages/styled-system/index.page.mdx
+++ b/packages/react-docs/pages/styled-system/index.page.mdx
@@ -8,8 +8,8 @@ import pkg from '@tonic-ui/styled-system/package.json';
 
 ```bash
 // with npm
-npm install @tonic-ui/styled-system@2.x
+npm install @tonic-ui/styled-system
 
 // with yarn
-yarn add @tonic-ui/styled-system@2.x
+yarn add @tonic-ui/styled-system
 ```
diff --git a/packages/react-docs/pages/theme/index.page.mdx b/packages/react-docs/pages/theme/index.page.mdx
index c57ccbbcab..5cde721f54 100644
--- a/packages/react-docs/pages/theme/index.page.mdx
+++ b/packages/react-docs/pages/theme/index.page.mdx
@@ -8,8 +8,8 @@ import pkg from '@tonic-ui/theme/package.json';
 
 ```bash
 // with npm
-npm install @tonic-ui/theme@2.x
+npm install @tonic-ui/theme
 
 // with yarn
-yarn add @tonic-ui/theme@2.x
+yarn add @tonic-ui/theme
 ```

From 398f5e7c1b6bcba84a35ea00a9d4beff18b38a0a Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 14:20:39 +0800
Subject: [PATCH 11/18] refactor: add type validation for the `cssVariables`
 configuration parameter

---
 packages/react/src/theme/createTheme.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/react/src/theme/createTheme.js b/packages/react/src/theme/createTheme.js
index 58158f94ba..632d1b8fc0 100644
--- a/packages/react/src/theme/createTheme.js
+++ b/packages/react/src/theme/createTheme.js
@@ -26,6 +26,10 @@ const createTheme = (options = {}, ...args) => {
   theme = args.reduce((acc, arg) => merge(acc, arg), theme);
 
   if (cssVariableConfig) {
+    if (typeof cssVariableConfig !== 'boolean' && typeof cssVariableConfig !== 'object') {
+      throw new Error('The `cssVariables` config must be a boolean or an object');
+    }
+
     // Determine the prefix for CSS variables:
     // - Uses the `prefix` property if provided (e.g., `createTheme({ cssVariables: { prefix: 'tonic' } })`).
     // - Defaults to `defaultCSSVariablePrefix` if no custom prefix is specified.

From 5275339cae569c770c8e3453039aee0285b78dee Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 14:25:36 +0800
Subject: [PATCH 12/18] refactor: add input validation for the CSS variable
 name

---
 packages/react/src/theme/utils/css-vars.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/react/src/theme/utils/css-vars.js b/packages/react/src/theme/utils/css-vars.js
index d6b36a8481..7990d6fba6 100644
--- a/packages/react/src/theme/utils/css-vars.js
+++ b/packages/react/src/theme/utils/css-vars.js
@@ -51,6 +51,10 @@ export const mapThemeToCSSVariables = (theme, options) => {
   for (const [name, value] of Object.entries(tokens)) {
     // name='colors.blue:50', prefix='tonic'
     // => '--tonic-colors-blue-50'
+    if (!name) {
+      // Skip if name is empty
+      continue;
+    }
     const variable = toCSSVariable(name, { prefix });
     cssVariables[variable] = value;
   }

From 782ad843291070b5bbcc2ac50b46cc910b9c83c2 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 15:16:17 +0800
Subject: [PATCH 13/18] test: update tests

---
 .../src/accordion/__tests__/Accordion.test.js |  4 +---
 .../react/src/badge/__tests__/Badge.test.js   |  4 +---
 .../src/button/__tests__/ButtonBase.test.js   |  4 +---
 .../src/checkbox/__tests__/Checkbox.test.js   |  4 +---
 .../react/src/code/__tests__/Code.test.js     |  4 +---
 .../DatePicker/__tests__/DatePicker.test.js   |  4 +---
 .../src/divider/__tests__/Divider.test.js     |  4 +---
 .../react/src/drawer/__tests__/Drawer.test.js |  4 +---
 .../react/src/input/__tests__/Input.test.js   | 10 ++++----
 .../src/input/__tests__/InputControl.test.js  | 14 +++++------
 .../react/src/menu/__tests__/Menu.test.js     |  4 +---
 .../react/src/modal/__tests__/Modal.test.js   |  4 +---
 .../src/popover/__tests__/Popover.test.js     |  4 +---
 .../react/src/portal/__tests__/Portal.test.js |  4 +---
 .../src/progress/__tests__/Progress.test.js   |  4 +---
 .../react/src/radio/__tests__/Radio.test.js   |  4 +---
 .../__snapshots__/Scrollbar.test.js.snap      | 24 +++++++++----------
 .../__tests__/SearchInput.test.js             | 14 +++++------
 .../react/src/stack/__tests__/Stack.test.js   |  8 ++-----
 .../react/src/switch/__tests__/Switch.test.js |  4 +---
 .../react/src/table/__tests__/Table.test.js   |  8 ++-----
 .../react/src/tabs/__tests__/Tabs.test.js     |  4 +---
 .../react/src/text/__tests__/Text.test.js     |  4 +---
 .../src/text/__tests__/TextLabel.test.js      |  4 +---
 .../src/textarea/__tests__/Textarea.test.js   | 10 ++++----
 .../src/tooltip/__tests__/Tooltip.test.js     |  4 +---
 .../react/src/tree/__tests__/Tree.test.js     |  4 +---
 .../src/truncate/__tests__/Truncate.test.js   |  4 +---
 packages/react/test-utils/render.js           |  2 +-
 29 files changed, 58 insertions(+), 116 deletions(-)

diff --git a/packages/react/src/accordion/__tests__/Accordion.test.js b/packages/react/src/accordion/__tests__/Accordion.test.js
index 6cbba8f801..cb3bd128e8 100644
--- a/packages/react/src/accordion/__tests__/Accordion.test.js
+++ b/packages/react/src/accordion/__tests__/Accordion.test.js
@@ -14,9 +14,7 @@ import React from 'react';
 
 describe('Accordion', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Accordion rowGap={1}>
         <AccordionItem defaultIsExpanded>
diff --git a/packages/react/src/badge/__tests__/Badge.test.js b/packages/react/src/badge/__tests__/Badge.test.js
index 6df4ded73b..6052390117 100644
--- a/packages/react/src/badge/__tests__/Badge.test.js
+++ b/packages/react/src/badge/__tests__/Badge.test.js
@@ -6,9 +6,7 @@ import React from 'react';
 
 describe('Badge', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Flex columnGap="4x">
         <Badge variant="dot" />
diff --git a/packages/react/src/button/__tests__/ButtonBase.test.js b/packages/react/src/button/__tests__/ButtonBase.test.js
index 54172e8bf3..c5b3a770b1 100644
--- a/packages/react/src/button/__tests__/ButtonBase.test.js
+++ b/packages/react/src/button/__tests__/ButtonBase.test.js
@@ -5,9 +5,7 @@ import React from 'react';
 
 describe('ButtonBase', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         <ButtonBase>
diff --git a/packages/react/src/checkbox/__tests__/Checkbox.test.js b/packages/react/src/checkbox/__tests__/Checkbox.test.js
index 478f1f35ff..e0a40bd058 100644
--- a/packages/react/src/checkbox/__tests__/Checkbox.test.js
+++ b/packages/react/src/checkbox/__tests__/Checkbox.test.js
@@ -5,9 +5,7 @@ import React, { useEffect, useRef } from 'react';
 
 describe('Checkbox', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {/* Sizes */}
diff --git a/packages/react/src/code/__tests__/Code.test.js b/packages/react/src/code/__tests__/Code.test.js
index 7828b0c080..b80d41b3ec 100644
--- a/packages/react/src/code/__tests__/Code.test.js
+++ b/packages/react/src/code/__tests__/Code.test.js
@@ -6,9 +6,7 @@ import React from 'react';
 
 describe('Code', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Code data-testid="Code">
         Code
diff --git a/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js b/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js
index 095496bf0c..04c9cb3930 100644
--- a/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js
+++ b/packages/react/src/date-pickers/DatePicker/__tests__/DatePicker.test.js
@@ -65,9 +65,7 @@ describe('DatePicker', () => {
 
   it('should render correctly', async () => {
     const user = userEvent.setup();
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const defaultValue = new Date('2024-08-01');
     const inputFormat = 'yyyy-MM-dd';
     const mockOnChange = jest.fn();
diff --git a/packages/react/src/divider/__tests__/Divider.test.js b/packages/react/src/divider/__tests__/Divider.test.js
index 2b89e55ec6..6f5900db3b 100644
--- a/packages/react/src/divider/__tests__/Divider.test.js
+++ b/packages/react/src/divider/__tests__/Divider.test.js
@@ -5,9 +5,7 @@ import React from 'react';
 
 describe('Divider', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         <Stack direction="column" spacing="4x">
diff --git a/packages/react/src/drawer/__tests__/Drawer.test.js b/packages/react/src/drawer/__tests__/Drawer.test.js
index 7d40476342..456bfafcec 100644
--- a/packages/react/src/drawer/__tests__/Drawer.test.js
+++ b/packages/react/src/drawer/__tests__/Drawer.test.js
@@ -18,9 +18,7 @@ import React, { useCallback, useRef, useState } from 'react';
 
 describe('Drawer', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { baseElement } = render((
       <Drawer
         isOpen
diff --git a/packages/react/src/input/__tests__/Input.test.js b/packages/react/src/input/__tests__/Input.test.js
index e84b52963a..73b5a5a043 100644
--- a/packages/react/src/input/__tests__/Input.test.js
+++ b/packages/react/src/input/__tests__/Input.test.js
@@ -9,9 +9,7 @@ describe('Input', () => {
   it('should render correctly', async () => {
     const sizes = ['sm', 'md', 'lg'];
     const variants = ['outline', 'filled', 'flush', 'unstyled'];
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {sizes.map(size => (
@@ -88,9 +86,9 @@ describe('Input', () => {
       <Input data-testid="input" />
     );
     const input = screen.getByTestId('input');
-    const defaultBorderColor = '#5e5e5e'; // [dark] gray:60 / [light] gray:30
-    const focusBorderColor = '#1e5ede'; // [dark] blue:60 / [light] blue:60
-    const hoverBorderColor = '#578aef'; // [dark] blue:50 / [light] blue:50
+    const defaultBorderColor = 'var(--tonic-colors-gray-60)'; // [dark] gray:60 / [light] gray:30
+    const focusBorderColor = 'var(--tonic-colors-blue-60)'; // [dark] blue:60 / [light] blue:60
+    const hoverBorderColor = 'var(--tonic-colors-blue-50)'; // [dark] blue:50 / [light] blue:50
 
     expect(input).toBeValid();
     expect(document.body).toHaveFocus();
diff --git a/packages/react/src/input/__tests__/InputControl.test.js b/packages/react/src/input/__tests__/InputControl.test.js
index da95df68a1..cbff758bc7 100644
--- a/packages/react/src/input/__tests__/InputControl.test.js
+++ b/packages/react/src/input/__tests__/InputControl.test.js
@@ -9,9 +9,7 @@ describe('InputControl', () => {
   it('should render correctly', async () => {
     const sizes = ['sm', 'md', 'lg'];
     const variants = ['outline', 'filled', 'flush', 'unstyled'];
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {sizes.map(size => (
@@ -94,9 +92,9 @@ describe('InputControl', () => {
     );
     const inputControl = screen.getByTestId('input');
     const input = inputControl.querySelector('input');
-    const defaultBorderColor = '#5e5e5e'; // [dark] gray:60 / [light] gray:30
-    const focusBorderColor = '#1e5ede'; // [dark] blue:60 / [light] blue:60
-    const hoverBorderColor = '#578aef'; // [dark] blue:50 / [light] blue:50
+    const defaultBorderColor = 'var(--tonic-colors-gray-60)'; // [dark] gray:60 / [light] gray:30
+    const focusBorderColor = 'var(--tonic-colors-blue-60)'; // [dark] blue:60 / [light] blue:60
+    const hoverBorderColor = 'var(--tonic-colors-blue-50)'; // [dark] blue:50 / [light] blue:50
 
     expect(input).toBeValid();
     expect(document.body).toHaveFocus();
@@ -121,8 +119,8 @@ describe('InputControl', () => {
     );
     const inputControl = screen.getByTestId('input');
     const input = inputControl.querySelector('input');
-    const errorBorderColor = '#f24c4f'; // [dark] red:50 / [light] red:60
-    const focusBorderColor = '#1e5ede'; // [dark] blue:60 / [light] blue:60
+    const errorBorderColor = 'var(--tonic-colors-red-50)'; // [dark] red:50 / [light] red:60
+    const focusBorderColor = 'var(--tonic-colors-blue-60)'; // [dark] blue:60 / [light] blue:60
 
     expect(input).toBeInvalid();
     expect(document.body).toHaveFocus();
diff --git a/packages/react/src/menu/__tests__/Menu.test.js b/packages/react/src/menu/__tests__/Menu.test.js
index 82ce68611a..008ef080a8 100644
--- a/packages/react/src/menu/__tests__/Menu.test.js
+++ b/packages/react/src/menu/__tests__/Menu.test.js
@@ -40,9 +40,7 @@ describe('Menu', () => {
 
   it('should render correctly', async () => {
     const user = userEvent.setup();
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <TestComponent />
     ), renderOptions);
diff --git a/packages/react/src/modal/__tests__/Modal.test.js b/packages/react/src/modal/__tests__/Modal.test.js
index 076e32ab74..905254bdeb 100644
--- a/packages/react/src/modal/__tests__/Modal.test.js
+++ b/packages/react/src/modal/__tests__/Modal.test.js
@@ -18,9 +18,7 @@ import React, { useCallback, useRef, useState } from 'react';
 
 describe('Modal', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { baseElement } = render((
       <Modal isOpen onClose={jest.fn()}>
         <ModalOverlay />
diff --git a/packages/react/src/popover/__tests__/Popover.test.js b/packages/react/src/popover/__tests__/Popover.test.js
index 68d3b616a8..92bb158e1a 100644
--- a/packages/react/src/popover/__tests__/Popover.test.js
+++ b/packages/react/src/popover/__tests__/Popover.test.js
@@ -8,9 +8,7 @@ import React from 'react';
 describe('Popover', () => {
   it('should render correctly', async () => {
     const user = userEvent.setup();
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Popover>
         <PopoverTrigger data-testid="popover-trigger">
diff --git a/packages/react/src/portal/__tests__/Portal.test.js b/packages/react/src/portal/__tests__/Portal.test.js
index 55b17acb19..4a089e1ec5 100644
--- a/packages/react/src/portal/__tests__/Portal.test.js
+++ b/packages/react/src/portal/__tests__/Portal.test.js
@@ -5,9 +5,7 @@ import React from 'react';
 
 describe('Portal', () => {
   it('should render correctly', () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Portal>
         This is a portal
diff --git a/packages/react/src/progress/__tests__/Progress.test.js b/packages/react/src/progress/__tests__/Progress.test.js
index fe9708b23d..9f185de6c9 100644
--- a/packages/react/src/progress/__tests__/Progress.test.js
+++ b/packages/react/src/progress/__tests__/Progress.test.js
@@ -5,9 +5,7 @@ import React from 'react';
 
 describe('LinearProgress', () => {
   it('renders correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         <LinearProgress aria-label="usage" size="xs" value={20} />
diff --git a/packages/react/src/radio/__tests__/Radio.test.js b/packages/react/src/radio/__tests__/Radio.test.js
index 8d9bf8afee..ea591b489a 100644
--- a/packages/react/src/radio/__tests__/Radio.test.js
+++ b/packages/react/src/radio/__tests__/Radio.test.js
@@ -5,9 +5,7 @@ import React, { useEffect, useRef } from 'react';
 
 describe('Radio', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {/* Sizes */}
diff --git a/packages/react/src/scrollbar/__tests__/__snapshots__/Scrollbar.test.js.snap b/packages/react/src/scrollbar/__tests__/__snapshots__/Scrollbar.test.js.snap
index 55f8380991..758ab805fa 100644
--- a/packages/react/src/scrollbar/__tests__/__snapshots__/Scrollbar.test.js.snap
+++ b/packages/react/src/scrollbar/__tests__/__snapshots__/Scrollbar.test.js.snap
@@ -30,7 +30,7 @@ exports[`Scrollbar should render correctly 1`] = `
 
 .emotion-6 {
   position: absolute;
-  height: .5rem;
+  height: var(--tonic-sizes-2x);
   right: 0;
   bottom: 0;
   left: 0;
@@ -44,21 +44,21 @@ exports[`Scrollbar should render correctly 1`] = `
   position: relative;
   height: 100%;
   cursor: pointer;
-  background-color: rgba(255, 255, 255, .28);
+  background-color: var(--tonic-colors-white-disabled);
   border-radius: inherit;
-  border: .0625rem solid;
-  border-color: transparent;
+  border: var(--tonic-borders-1);
+  border-color: var(--tonic-colors-transparent);
 }
 
 .emotion-8:hover,
 .emotion-8[data-hover] {
-  background-color: rgba(255, 255, 255, .47);
-  border-color: rgba(255, 255, 255, .60);
+  background-color: var(--tonic-colors-white-tertiary);
+  border-color: var(--tonic-colors-white-secondary);
 }
 
 .emotion-10 {
   position: absolute;
-  width: .5rem;
+  width: var(--tonic-sizes-2x);
   right: 0;
   bottom: 0;
   top: 0;
@@ -73,16 +73,16 @@ exports[`Scrollbar should render correctly 1`] = `
   display: block;
   width: 100%;
   cursor: pointer;
-  background-color: rgba(255, 255, 255, .28);
+  background-color: var(--tonic-colors-white-disabled);
   border-radius: inherit;
-  border: .0625rem solid;
-  border-color: transparent;
+  border: var(--tonic-borders-1);
+  border-color: var(--tonic-colors-transparent);
 }
 
 .emotion-12:hover,
 .emotion-12[data-hover] {
-  background-color: rgba(255, 255, 255, .47);
-  border-color: rgba(255, 255, 255, .60);
+  background-color: var(--tonic-colors-white-tertiary);
+  border-color: var(--tonic-colors-white-secondary);
 }
 
 <div>
diff --git a/packages/react/src/search-input/__tests__/SearchInput.test.js b/packages/react/src/search-input/__tests__/SearchInput.test.js
index 0ebd40f631..cd5ac422a0 100644
--- a/packages/react/src/search-input/__tests__/SearchInput.test.js
+++ b/packages/react/src/search-input/__tests__/SearchInput.test.js
@@ -9,9 +9,7 @@ describe('SearchInput', () => {
   it('should render correctly', async () => {
     const sizes = ['sm', 'md', 'lg'];
     const variants = ['outline', 'filled', 'flush', 'unstyled'];
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {sizes.map(size => (
@@ -94,9 +92,9 @@ describe('SearchInput', () => {
     );
     const inputControl = screen.getByTestId('input');
     const input = inputControl.querySelector('input');
-    const defaultBorderColor = '#5e5e5e'; // [dark] gray:60 / [light] gray:30
-    const focusBorderColor = '#1e5ede'; // [dark] blue:60 / [light] blue:60
-    const hoverBorderColor = '#578aef'; // [dark] blue:50 / [light] blue:50
+    const defaultBorderColor = 'var(--tonic-colors-gray-60)'; // [dark] gray:60 / [light] gray:30
+    const focusBorderColor = 'var(--tonic-colors-blue-60)'; // [dark] blue:60 / [light] blue:60
+    const hoverBorderColor = 'var(--tonic-colors-blue-50)'; // [dark] blue:50 / [light] blue:50
 
     expect(input).toBeValid();
     expect(document.body).toHaveFocus();
@@ -121,8 +119,8 @@ describe('SearchInput', () => {
     );
     const inputControl = screen.getByTestId('input');
     const input = inputControl.querySelector('input');
-    const errorBorderColor = '#f24c4f'; // [dark] red:50 / [light] red:60
-    const focusBorderColor = '#1e5ede'; // [dark] blue:60 / [light] blue:60
+    const errorBorderColor = 'var(--tonic-colors-red-50)'; // [dark] red:50 / [light] red:60
+    const focusBorderColor = 'var(--tonic-colors-blue-60)'; // [dark] blue:60 / [light] blue:60
 
     expect(input).toBeInvalid();
     expect(document.body).toHaveFocus();
diff --git a/packages/react/src/stack/__tests__/Stack.test.js b/packages/react/src/stack/__tests__/Stack.test.js
index 631843fea4..750eb4a347 100644
--- a/packages/react/src/stack/__tests__/Stack.test.js
+++ b/packages/react/src/stack/__tests__/Stack.test.js
@@ -6,9 +6,7 @@ import React from 'react';
 
 describe('Stack', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Stack spacing="4x">
         <Box />
@@ -53,9 +51,7 @@ describe('Stack', () => {
   });
 
   it('should apply spacing between child elements', () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     render((
       <Stack data-testid="stack" spacing="2x">
         <Box />
diff --git a/packages/react/src/switch/__tests__/Switch.test.js b/packages/react/src/switch/__tests__/Switch.test.js
index e818943901..26cc8cadac 100644
--- a/packages/react/src/switch/__tests__/Switch.test.js
+++ b/packages/react/src/switch/__tests__/Switch.test.js
@@ -5,9 +5,7 @@ import React, { useEffect, useRef } from 'react';
 
 describe('Switch', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {/* Sizes */}
diff --git a/packages/react/src/table/__tests__/Table.test.js b/packages/react/src/table/__tests__/Table.test.js
index 4351fd1674..c4fffcdd6f 100644
--- a/packages/react/src/table/__tests__/Table.test.js
+++ b/packages/react/src/table/__tests__/Table.test.js
@@ -60,9 +60,7 @@ describe('Table', () => {
   ];
 
   it('should render correctly with `flexbox` layout', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
 
     const { container } = render((
       <Table layout="flexbox">
@@ -103,9 +101,7 @@ describe('Table', () => {
   });
 
   it('should render correctly with `table` layout', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
 
     const { container } = render((
       <Table layout="table">
diff --git a/packages/react/src/tabs/__tests__/Tabs.test.js b/packages/react/src/tabs/__tests__/Tabs.test.js
index aeb4b76add..1d541db517 100644
--- a/packages/react/src/tabs/__tests__/Tabs.test.js
+++ b/packages/react/src/tabs/__tests__/Tabs.test.js
@@ -5,9 +5,7 @@ import React from 'react';
 
 describe('Tabs', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Tabs>
         <TabList>
diff --git a/packages/react/src/text/__tests__/Text.test.js b/packages/react/src/text/__tests__/Text.test.js
index 03d0a6efe2..295f694411 100644
--- a/packages/react/src/text/__tests__/Text.test.js
+++ b/packages/react/src/text/__tests__/Text.test.js
@@ -6,9 +6,7 @@ import React from 'react';
 
 describe('TextLabel', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Text>
         Text
diff --git a/packages/react/src/text/__tests__/TextLabel.test.js b/packages/react/src/text/__tests__/TextLabel.test.js
index 85b44d9890..e1d2eea2f7 100644
--- a/packages/react/src/text/__tests__/TextLabel.test.js
+++ b/packages/react/src/text/__tests__/TextLabel.test.js
@@ -6,9 +6,7 @@ import React from 'react';
 
 describe('TextLabel', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <TextLabel data-testid="TextLabel">
         TextLabel
diff --git a/packages/react/src/textarea/__tests__/Textarea.test.js b/packages/react/src/textarea/__tests__/Textarea.test.js
index 5df956b83d..f66d1f5b26 100644
--- a/packages/react/src/textarea/__tests__/Textarea.test.js
+++ b/packages/react/src/textarea/__tests__/Textarea.test.js
@@ -8,9 +8,7 @@ import React from 'react';
 describe('Textarea', () => {
   it('should render correctly', async () => {
     const variants = ['outline', 'filled', 'unstyled'];
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <>
         {variants.map(variant => (
@@ -113,9 +111,9 @@ describe('Textarea', () => {
       <Textarea data-testid="textarea" />
     );
     const textarea = screen.getByTestId('textarea');
-    const defaultBorderColor = '#5e5e5e'; // [dark] gray:60 / [light] gray:30
-    const focusBorderColor = '#1e5ede'; // [dark] blue:60 / [light] blue:60
-    const hoverBorderColor = '#578aef'; // [dark] blue:50 / [light] blue:50
+    const defaultBorderColor = 'var(--tonic-colors-gray-60)'; // [dark] gray:60 / [light] gray:30
+    const focusBorderColor = 'var(--tonic-colors-blue-60)'; // [dark] blue:60 / [light] blue:60
+    const hoverBorderColor = 'var(--tonic-colors-blue-50)'; // [dark] blue:50 / [light] blue:50
 
     expect(textarea).toBeValid();
     expect(document.body).toHaveFocus();
diff --git a/packages/react/src/tooltip/__tests__/Tooltip.test.js b/packages/react/src/tooltip/__tests__/Tooltip.test.js
index 01fb0409c0..079517ed8d 100644
--- a/packages/react/src/tooltip/__tests__/Tooltip.test.js
+++ b/packages/react/src/tooltip/__tests__/Tooltip.test.js
@@ -16,9 +16,7 @@ describe('Tooltip', () => {
 
   it('should render correctly', async () => {
     const user = userEvent.setup();
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <TestComponent />
     ), renderOptions);
diff --git a/packages/react/src/tree/__tests__/Tree.test.js b/packages/react/src/tree/__tests__/Tree.test.js
index f8d27d89ab..a2c434e8ea 100644
--- a/packages/react/src/tree/__tests__/Tree.test.js
+++ b/packages/react/src/tree/__tests__/Tree.test.js
@@ -181,9 +181,7 @@ const TreeItemRender = ({
 
 describe('Tree', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const treeNodes = buildTreeNodes();
     const treeMap = buildTreeMap(treeNodes);
     const expandableNodeIds = findExpandableNodeIds(treeNodes);
diff --git a/packages/react/src/truncate/__tests__/Truncate.test.js b/packages/react/src/truncate/__tests__/Truncate.test.js
index a7133551ef..36fb90d963 100644
--- a/packages/react/src/truncate/__tests__/Truncate.test.js
+++ b/packages/react/src/truncate/__tests__/Truncate.test.js
@@ -5,9 +5,7 @@ import React from 'react';
 
 describe('Truncate', () => {
   it('should render correctly', async () => {
-    const renderOptions = {
-      cssVariables: true,
-    };
+    const renderOptions = {};
     const { container } = render((
       <Truncate width={120}>
         This is a very long text that will be truncated
diff --git a/packages/react/test-utils/render.js b/packages/react/test-utils/render.js
index 43f74d6674..9447cc7563 100644
--- a/packages/react/test-utils/render.js
+++ b/packages/react/test-utils/render.js
@@ -21,7 +21,7 @@ const customRender = (ui, options) => {
         defaultValue: 'dark',
       }}
       theme={createTheme({
-        cssVariables: options?.cssVariables,
+        cssVariables: true,
       })}
     >
       <PortalManager>

From 03e7d1177384114498bdbccc4de8161375ee1f53 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 16:40:57 +0800
Subject: [PATCH 14/18] feat: extract `theme.vars` into `theme.cssVariables`
 and `theme.cssVariablePrefix` for improved clarity

---
 .../css-variables/default-css-variables.js    |  2 +-
 packages/react/src/theme/CSSVariables.js      |  8 ++-
 .../src/theme/__tests__/createTheme.test.js   | 62 ++++++++++++-------
 packages/react/src/theme/createTheme.js       |  6 +-
 .../styled-system/src/__tests__/sx.test.js    |  4 +-
 .../src/config/__tests__/margin.test.js       |  4 +-
 .../src/config/__tests__/position.test.js     |  4 +-
 .../utils/{toCSSVariable.js => css-vars.js}   |  4 +-
 .../styled-system/src/utils/transforms.js     | 14 ++---
 9 files changed, 63 insertions(+), 45 deletions(-)
 rename packages/styled-system/src/utils/{toCSSVariable.js => css-vars.js} (91%)

diff --git a/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js b/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js
index b539ff082d..170858872d 100644
--- a/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js
+++ b/packages/react-docs/pages/getting-started/css-variables/default-css-variables.js
@@ -17,7 +17,7 @@ const App = () => {
 
   return (
     <Box fontFamily="mono">
-      {Object.entries(theme?.vars).map(([name, value]) => {
+      {Object.entries(theme?.cssVariables).map(([name, value]) => {
         if (!name.startsWith('--')) {
           return null;
         }
diff --git a/packages/react/src/theme/CSSVariables.js b/packages/react/src/theme/CSSVariables.js
index b1be78580e..f14f00e18d 100644
--- a/packages/react/src/theme/CSSVariables.js
+++ b/packages/react/src/theme/CSSVariables.js
@@ -1,14 +1,18 @@
 import { Global } from '@emotion/react';
-import { ensureArray } from 'ensure-type';
+import { ensureArray, ensurePlainObject } from 'ensure-type';
 import React, { useCallback } from 'react';
 
 const CSSVariables = ({
   root = [':root', ':host'],
 }) => {
   const styles = useCallback((theme) => {
+    const cssVariables = ensurePlainObject(theme?.cssVariables);
+    if (Object.keys(cssVariables) === 0) {
+      return {};
+    }
     const selector = ensureArray(root).join(',');
     return {
-      [selector]: { ...theme?.vars },
+      [selector]: cssVariables,
     };
   }, [root]);
 
diff --git a/packages/react/src/theme/__tests__/createTheme.test.js b/packages/react/src/theme/__tests__/createTheme.test.js
index 760d592df2..775215f0a1 100644
--- a/packages/react/src/theme/__tests__/createTheme.test.js
+++ b/packages/react/src/theme/__tests__/createTheme.test.js
@@ -1,22 +1,26 @@
 import createTheme from '../createTheme';
 
 describe('createTheme', () => {
+  const defaultThemeScales = [
+    'borders',
+    'breakpoints',
+    'colors',
+    'fonts',
+    'fontSizes',
+    'fontWeights',
+    'letterSpacings',
+    'lineHeights',
+    'outlines',
+    'radii',
+    'shadows',
+    'sizes',
+    'space',
+    'zIndices',
+  ];
+
   it('should create a default theme', () => {
     const theme = createTheme();
-    expect(theme).toHaveProperty('borders');
-    expect(theme).toHaveProperty('breakpoints');
-    expect(theme).toHaveProperty('colors');
-    expect(theme).toHaveProperty('fonts');
-    expect(theme).toHaveProperty('fontSizes');
-    expect(theme).toHaveProperty('fontWeights');
-    expect(theme).toHaveProperty('letterSpacings');
-    expect(theme).toHaveProperty('lineHeights');
-    expect(theme).toHaveProperty('outlines');
-    expect(theme).toHaveProperty('radii');
-    expect(theme).toHaveProperty('shadows');
-    expect(theme).toHaveProperty('sizes');
-    expect(theme).toHaveProperty('space');
-    expect(theme).toHaveProperty('zIndices');
+    defaultThemeScales.forEach(scale => expect(theme).toHaveProperty(scale));
   });
 
   it('should merge custom theme options', () => {
@@ -41,20 +45,36 @@ describe('createTheme', () => {
 
   it('should not generate CSS variables with default configuration', () => {
     const theme = createTheme();
-    expect(theme.vars).not.toBeDefined();
+    expect(theme.cssVariables).not.toBeDefined();
   });
 
   it('should generate CSS variables', () => {
     const theme = createTheme({ cssVariables: true });
-    expect(theme.vars).toBeDefined();
-    expect(theme.vars.prefix).toBe('tonic');
-    expect(Object.keys(theme.vars).filter(x => x.startsWith('--'))[0]).toMatch(/^--tonic-/);
+    expect(theme.cssVariables).toBeDefined();
+    expect(theme.cssVariablePrefix).toBe('tonic');
+    const cssVariableKeys = Object.keys(theme.cssVariables).filter(x => x.startsWith('--'));
+    expect(cssVariableKeys.length).toBeGreaterThan(0);
+    expect(cssVariableKeys[0]).toMatch(/^--tonic-/);
   });
 
   it('should apply custom prefix to CSS variables', () => {
     const theme = createTheme({ cssVariables: { prefix: 'custom' } });
-    expect(theme.vars).toBeDefined();
-    expect(theme.vars.prefix).toBe('custom');
-    expect(Object.keys(theme.vars).filter(x => x.startsWith('--'))[0]).toMatch(/^--custom-/);
+    expect(theme.cssVariables).toBeDefined();
+    expect(theme.cssVariablePrefix).toBe('custom');
+    const cssVariableKeys = Object.keys(theme.cssVariables).filter(x => x.startsWith('--'));
+    expect(cssVariableKeys.length).toBeGreaterThan(0);
+    expect(cssVariableKeys[0]).toMatch(/^--custom-/);
+  });
+
+  it('should allow an empty prefix for CSS variables', () => {
+    const theme = createTheme({ cssVariables: { prefix: '' } });
+    expect(theme.cssVariables).toBeDefined();
+    expect(theme.cssVariablePrefix).toBe('');
+    const cssVariableKeys = Object.keys(theme.cssVariables).filter(x => x.startsWith('--'));
+    expect(cssVariableKeys.length).toBeGreaterThan(0);
+    cssVariableKeys.forEach(key => {
+      const isValid = defaultThemeScales.some(scale => key.startsWith(`--${scale}`));
+      expect(isValid).toBe(true);
+    });
   });
 });
diff --git a/packages/react/src/theme/createTheme.js b/packages/react/src/theme/createTheme.js
index 632d1b8fc0..c66b42e7a8 100644
--- a/packages/react/src/theme/createTheme.js
+++ b/packages/react/src/theme/createTheme.js
@@ -48,10 +48,8 @@ const createTheme = (options = {}, ...args) => {
 
     // Merge CSS variables into the theme
     theme = merge(theme, {
-      vars: {
-        prefix: cssVariablePrefix,
-        ...cssVariables,
-      },
+      cssVariablePrefix,
+      cssVariables,
     });
   }
 
diff --git a/packages/styled-system/src/__tests__/sx.test.js b/packages/styled-system/src/__tests__/sx.test.js
index 5a59919f38..2496ebe21f 100644
--- a/packages/styled-system/src/__tests__/sx.test.js
+++ b/packages/styled-system/src/__tests__/sx.test.js
@@ -280,8 +280,8 @@ const defaultTheme = {
 test('should pass', () => {
   const theme = {
     ...defaultTheme,
-    vars: {
-      prefix: 'tonic',
+    cssVariablePrefix: 'tonic',
+    cssVariables: {
       '--tonic-borders-1': '.0625rem solid',
       '--tonic-borders-2': '.125rem solid',
       '--tonic-borders-3': '.1875rem solid',
diff --git a/packages/styled-system/src/config/__tests__/margin.test.js b/packages/styled-system/src/config/__tests__/margin.test.js
index b8985e7f7e..1ace6fe9fb 100644
--- a/packages/styled-system/src/config/__tests__/margin.test.js
+++ b/packages/styled-system/src/config/__tests__/margin.test.js
@@ -7,8 +7,8 @@ const defaultTheme = {
 
 const defaultThemeWithCSSVariables = {
   ...defaultTheme,
-  vars: {
-    prefix: 'tonic',
+  cssVariablePrefix: 'tonic',
+  cssVariables: {
     '--tonic-breakpoints-0': '40em',
     '--tonic-breakpoints-1': '52em',
     '--tonic-breakpoints-2': '64em',
diff --git a/packages/styled-system/src/config/__tests__/position.test.js b/packages/styled-system/src/config/__tests__/position.test.js
index 3477f7b9cf..3c03a873d0 100644
--- a/packages/styled-system/src/config/__tests__/position.test.js
+++ b/packages/styled-system/src/config/__tests__/position.test.js
@@ -6,8 +6,8 @@ const defaultTheme = {
 
 const defaultThemeWithCSSVariables = {
   ...defaultTheme,
-  vars: {
-    prefix: 'tonic',
+  cssVariablePrefix: 'tonic',
+  cssVariables: {
     '--tonic-space-0': 0,
     '--tonic-space-1': 4,
     '--tonic-space-2': 8,
diff --git a/packages/styled-system/src/utils/toCSSVariable.js b/packages/styled-system/src/utils/css-vars.js
similarity index 91%
rename from packages/styled-system/src/utils/toCSSVariable.js
rename to packages/styled-system/src/utils/css-vars.js
index 9c1a94d225..b7c0dfd441 100644
--- a/packages/styled-system/src/utils/toCSSVariable.js
+++ b/packages/styled-system/src/utils/css-vars.js
@@ -8,7 +8,7 @@
  *
  * @return {string} The CSS variable name.
 */
-const toCSSVariable = (name, options) => {
+export const toCSSVariable = (name, options) => {
   const {
     prefix = '',
     delimiter = '-',
@@ -19,5 +19,3 @@ const toCSSVariable = (name, options) => {
     .replace(/^-+|-+$/g, ''); // trim hyphens from beginning and end of string
   return `--${variableName}`;
 };
-
-export default toCSSVariable;
diff --git a/packages/styled-system/src/utils/transforms.js b/packages/styled-system/src/utils/transforms.js
index 6ba97a5fc7..ba3059def4 100644
--- a/packages/styled-system/src/utils/transforms.js
+++ b/packages/styled-system/src/utils/transforms.js
@@ -1,5 +1,5 @@
 import get from './get';
-import toCSSVariable from './toCSSVariable';
+import { toCSSVariable } from './css-vars';
 
 // Check if a value is a simple CSS variable
 // e.g. var(--tonic-spacing-1)
@@ -11,11 +11,10 @@ const isSimpleCSSVariable = (value) => {
 // Negate the value, handling CSS variables and numeric values
 const toNegativeValue = (scale, absoluteValue, options) => {
   const theme = options?.props?.theme;
-  const hasCSSVariables = !!theme?.vars; // Defaults to false
   const n = getter(scale, absoluteValue, options);
 
   // Handle CSS variables for negative values
-  if (hasCSSVariables && isSimpleCSSVariable(n)) {
+  if (!!theme?.cssVariables && isSimpleCSSVariable(n)) {
     // https://stackoverflow.com/questions/49469344/using-negative-css-custom-properties
     return `calc(0px - ${n})`;
   }
@@ -30,15 +29,14 @@ const toNegativeValue = (scale, absoluteValue, options) => {
 
 export const getter = (scale, value, options) => {
   const theme = options?.props?.theme;
-  const hasCSSVariables = !!theme?.vars; // Defaults to false
   const result = get(scale, value);
 
-  if (result !== undefined && hasCSSVariables) {
-    // TODO: `theme?.config?.prefix` and `theme?.__cssVariableMap` are deprecated and will be removed in the next major release
+  if (result !== undefined && !!theme?.cssVariables) {
+    // TODO: `theme.config.prefix` and `theme.__cssVariableMap` are deprecated and will be removed in the next major release
     const cssVariablePrefixFallback = theme?.config?.prefix;
-    const cssVariablePrefix = (theme?.vars?.prefix) ?? cssVariablePrefixFallback;
+    const cssVariablePrefix = (theme?.cssVariablePrefix) ?? cssVariablePrefixFallback;
     const cssVariablesFallback = theme?.__cssVariableMap;
-    const cssVariables = (theme?.vars) ?? cssVariablesFallback;
+    const cssVariables = (theme?.cssVariables) ?? cssVariablesFallback;
     const contextScale = options?.context?.scale;
     const cssVariable = toCSSVariable(
       // | contextScale | value     |

From 1a06b8ddba04d383e974fe88383d0110ed9f9576 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 17:02:24 +0800
Subject: [PATCH 15/18] refactor(styled-system): improve transforms for
 detecting CSS variable presence

---
 .../styled-system/src/utils/transforms.js     | 20 ++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/packages/styled-system/src/utils/transforms.js b/packages/styled-system/src/utils/transforms.js
index ba3059def4..544a54be8c 100644
--- a/packages/styled-system/src/utils/transforms.js
+++ b/packages/styled-system/src/utils/transforms.js
@@ -28,15 +28,17 @@ const toNegativeValue = (scale, absoluteValue, options) => {
 };
 
 export const getter = (scale, value, options) => {
-  const theme = options?.props?.theme;
   const result = get(scale, value);
+  if (result === undefined) {
+    return value; // fallback to value if result is undefined
+  }
 
-  if (result !== undefined && !!theme?.cssVariables) {
-    // TODO: `theme.config.prefix` and `theme.__cssVariableMap` are deprecated and will be removed in the next major release
-    const cssVariablePrefixFallback = theme?.config?.prefix;
-    const cssVariablePrefix = (theme?.cssVariablePrefix) ?? cssVariablePrefixFallback;
-    const cssVariablesFallback = theme?.__cssVariableMap;
-    const cssVariables = (theme?.cssVariables) ?? cssVariablesFallback;
+  const theme = options?.props?.theme;
+  // FIXME: `theme.config.prefix` and `theme.__cssVariableMap` are deprecated and will be removed in the next major release
+  const hasCSSVariables = !!(theme?.cssVariables ?? theme?.__cssVariableMap);
+  if (hasCSSVariables) {
+    const cssVariablePrefix = (theme?.cssVariablePrefix) ?? (theme?.config?.prefix);
+    const cssVariables = (theme?.cssVariables) ?? (theme?.__cssVariableMap);
     const contextScale = options?.context?.scale;
     const cssVariable = toCSSVariable(
       // | contextScale | value     |
@@ -51,10 +53,10 @@ export const getter = (scale, value, options) => {
       // => Replace '#578aef' with 'var(--tonic-colors-blue-50)'
       return String(result ?? '').replaceAll(cssVariableValue, `var(${cssVariable})`);
     }
-    // fallback to the original value
+    // fallback to the original result
   }
 
-  return result ?? value; // fallback to value if result is null or undefined
+  return result;
 };
 
 export const positiveOrNegative = (scale, value, options) => {

From d8d01712329b79725e85ecd54510bb0c5cc10197 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 18:24:05 +0800
Subject: [PATCH 16/18] feat: set the default root selector to `:root`

---
 packages/react/src/theme/CSSVariables.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/theme/CSSVariables.js b/packages/react/src/theme/CSSVariables.js
index f14f00e18d..30ea9f72d7 100644
--- a/packages/react/src/theme/CSSVariables.js
+++ b/packages/react/src/theme/CSSVariables.js
@@ -3,7 +3,7 @@ import { ensureArray, ensurePlainObject } from 'ensure-type';
 import React, { useCallback } from 'react';
 
 const CSSVariables = ({
-  root = [':root', ':host'],
+  root = [':root'],
 }) => {
   const styles = useCallback((theme) => {
     const cssVariables = ensurePlainObject(theme?.cssVariables);

From 83288bcf44e4d1446168139a84380e4cc0b99c23 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 20:37:07 +0800
Subject: [PATCH 17/18] feat: add custom root selector support for CSS
 variables

---
 packages/react/src/theme/CSSVariables.js | 14 ++++++--------
 packages/react/src/theme/createTheme.js  | 19 ++++++++++++-------
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/packages/react/src/theme/CSSVariables.js b/packages/react/src/theme/CSSVariables.js
index 30ea9f72d7..22dd8f09dd 100644
--- a/packages/react/src/theme/CSSVariables.js
+++ b/packages/react/src/theme/CSSVariables.js
@@ -1,20 +1,18 @@
 import { Global } from '@emotion/react';
-import { ensureArray, ensurePlainObject } from 'ensure-type';
+import { ensurePlainObject } from 'ensure-type';
 import React, { useCallback } from 'react';
 
-const CSSVariables = ({
-  root = [':root'],
-}) => {
+const CSSVariables = () => {
   const styles = useCallback((theme) => {
+    const rootSelector = theme?.rootSelector;
     const cssVariables = ensurePlainObject(theme?.cssVariables);
-    if (Object.keys(cssVariables) === 0) {
+    if (!rootSelector || Object.keys(cssVariables) === 0) {
       return {};
     }
-    const selector = ensureArray(root).join(',');
     return {
-      [selector]: cssVariables,
+      [rootSelector]: cssVariables,
     };
-  }, [root]);
+  }, []);
 
   return (
     <Global styles={styles} />
diff --git a/packages/react/src/theme/createTheme.js b/packages/react/src/theme/createTheme.js
index c66b42e7a8..692a2164a5 100644
--- a/packages/react/src/theme/createTheme.js
+++ b/packages/react/src/theme/createTheme.js
@@ -4,13 +4,16 @@ import { ensurePlainObject } from 'ensure-type';
 import { mapThemeToCSSVariables } from './utils/css-vars';
 
 const defaultCSSVariablePrefix = 'tonic';
+const defaultCSSVariableRootSelector = ':root';
 
 const createTheme = (options = {}, ...args) => {
   const {
-    // Configure CSS variables for the theme:
-    // - `false` (default): Disable CSS variables.
-    // - `true`: Enable CSS variables with default settings.
-    // - `{ prefix: 'tonic' }`: Enable CSS variables with a custom prefix.
+    // CSS variables configuration for the theme:
+    // - false (default): Disables CSS variables.
+    // - true: Enables CSS variables with default settings.
+    // - Object: Enables CSS variables with custom settings:
+    //   - prefix: 'tonic' (default) — Custom prefix for CSS variables.
+    //   - rootSelector: ':root' (default) — Root selector where CSS variables are defined.
     cssVariables: cssVariableConfig = false,
     ...rest
   } = options;
@@ -30,10 +33,11 @@ const createTheme = (options = {}, ...args) => {
       throw new Error('The `cssVariables` config must be a boolean or an object');
     }
 
-    // Determine the prefix for CSS variables:
-    // - Uses the `prefix` property if provided (e.g., `createTheme({ cssVariables: { prefix: 'tonic' } })`).
-    // - Defaults to `defaultCSSVariablePrefix` if no custom prefix is specified.
+    // Configure the prefix and root selector for CSS variables:
+    // - `cssVariablePrefix`: Uses `cssVariables.prefix` if available; otherwise, defaults to 'tonic'.
+    // - `rootSelector`: Uses `cssVariables.rootSelector` if available; otherwise, defaults to ':root'.
     const cssVariablePrefix = cssVariableConfig?.prefix ?? defaultCSSVariablePrefix;
+    const rootSelector = cssVariableConfig?.rootSelector ?? defaultCSSVariableRootSelector;
 
     // Generate a theme object filtered to include only scales supported by CSS variables
     const cssVariableScales = Object.keys(tonicTheme);
@@ -50,6 +54,7 @@ const createTheme = (options = {}, ...args) => {
     theme = merge(theme, {
       cssVariablePrefix,
       cssVariables,
+      rootSelector,
     });
   }
 

From db02958457cef7228149a52b17b19b3255424f35 Mon Sep 17 00:00:00 2001
From: cheton <cheton@gmail.com>
Date: Fri, 29 Nov 2024 21:54:04 +0800
Subject: [PATCH 18/18] test: add a test for the custom root selector

---
 .../__snapshots__/createTheme.test.js.snap    | 11 ++++++++++
 .../src/theme/__tests__/createTheme.test.js   | 22 +++++++++++++++++++
 packages/react/test-utils/render.js           | 16 ++++++++++----
 3 files changed, 45 insertions(+), 4 deletions(-)
 create mode 100644 packages/react/src/theme/__tests__/__snapshots__/createTheme.test.js.snap

diff --git a/packages/react/src/theme/__tests__/__snapshots__/createTheme.test.js.snap b/packages/react/src/theme/__tests__/__snapshots__/createTheme.test.js.snap
new file mode 100644
index 0000000000..4c7cf12202
--- /dev/null
+++ b/packages/react/src/theme/__tests__/__snapshots__/createTheme.test.js.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`createTheme should apply custom \`rootSelector\` for CSS variables 1`] = `
+<style
+  data-emotion="css-global"
+  data-s=""
+>
+  
+  :root[data-color-scheme]{--tonic-borders-1:.0625rem solid;--tonic-borders-2:.125rem solid;--tonic-borders-3:.1875rem solid;--tonic-borders-4:.25rem solid;--tonic-borders-5:.3125rem solid;--tonic-breakpoints-0:320px;--tonic-breakpoints-1:640px;--tonic-breakpoints-2:1024px;--tonic-breakpoints-3:1280px;--tonic-breakpoints-4:1680px;--tonic-breakpoints-sm:320px;--tonic-breakpoints-md:640px;--tonic-breakpoints-lg:1024px;--tonic-breakpoints-xl:1280px;--tonic-breakpoints-2xl:1680px;--tonic-colors-transparent:transparent;--tonic-colors-current:currentColor;--tonic-colors-red-100:#6e0002;--tonic-colors-red-90:#9d0003;--tonic-colors-red-80:#b80003;--tonic-colors-red-70:#d71920;--tonic-colors-red-60:#e52630;--tonic-colors-red-50:#f24c4f;--tonic-colors-red-40:#f46f71;--tonic-colors-red-30:#fd999a;--tonic-colors-red-20:#fcc3c4;--tonic-colors-red-10:#fee1e2;--tonic-colors-magenta-100:#750037;--tonic-colors-magenta-90:#960043;--tonic-colors-magenta-80:#b3004c;--tonic-colors-magenta-70:#ca0455;--tonic-colors-magenta-60:#dc1d68;--tonic-colors-magenta-50:#e94181;--tonic-colors-magenta-40:#f36fa0;--tonic-colors-magenta-30:#f9a0c1;--tonic-colors-magenta-20:#fcc3d8;--tonic-colors-magenta-10:#fee1ec;--tonic-colors-purple-100:#460086;--tonic-colors-purple-90:#5300a5;--tonic-colors-purple-80:#6304ca;--tonic-colors-purple-70:#771ddc;--tonic-colors-purple-60:#8f41e9;--tonic-colors-purple-50:#ab6ff3;--tonic-colors-purple-40:#bb89f6;--tonic-colors-purple-30:#cca6f9;--tonic-colors-purple-20:#ddc3fc;--tonic-colors-purple-10:#eee1fe;--tonic-colors-blue-100:#002a7e;--tonic-colors-blue-90:#00349d;--tonic-colors-blue-80:#003db8;--tonic-colors-blue-70:#0547cd;--tonic-colors-blue-60:#1e5ede;--tonic-colors-blue-50:#578aef;--tonic-colors-blue-40:#6f9bf4;--tonic-colors-blue-30:#95b7fc;--tonic-colors-blue-20:#c3d6fc;--tonic-colors-blue-10:#e1ebfe;--tonic-colors-green-100:#003011;--tonic-colors-green-90:#00461a;--tonic-colors-green-80:#005c24;--tonic-colors-green-70:#00712e;--tonic-colors-green-60:#008539;--tonic-colors-green-50:#00a94f;--tonic-colors-green-40:#04c45a;--tonic-colors-green-30:#40e884;--tonic-colors-green-20:#89f6b2;--tonic-colors-green-10:#c3fcd8;--tonic-colors-teal-100:#004034;--tonic-colors-teal-90:#005242;--tonic-colors-teal-80:#006451;--tonic-colors-teal-70:#00755f;--tonic-colors-teal-60:#00866c;--tonic-colors-teal-50:#00a584;--tonic-colors-teal-40:#04caa1;--tonic-colors-teal-30:#41e9c5;--tonic-colors-teal-20:#89f6df;--tonic-colors-teal-10:#c3fcf0;--tonic-colors-cyan-100:#003664;--tonic-colors-cyan-90:#004575;--tonic-colors-cyan-80:#005486;--tonic-colors-cyan-70:#006496;--tonic-colors-cyan-60:#0075a5;--tonic-colors-cyan-50:#0095bf;--tonic-colors-cyan-40:#10b4d3;--tonic-colors-cyan-30:#41d8e9;--tonic-colors-cyan-20:#89f0f6;--tonic-colors-cyan-10:#c3f9fc;--tonic-colors-gray-100:#151515;--tonic-colors-gray-90:#212121;--tonic-colors-gray-80:#303030;--tonic-colors-gray-70:#424242;--tonic-colors-gray-60:#5e5e5e;--tonic-colors-gray-50:#8a8a8a;--tonic-colors-gray-40:#adadad;--tonic-colors-gray-30:#c9c9c9;--tonic-colors-gray-20:#e0e0e0;--tonic-colors-gray-10:#f2f2f2;--tonic-colors-orange-50:#ff7633;--tonic-colors-yellow-50:#faba2a;--tonic-colors-white-emphasis:rgba(255, 255, 255, 1.0);--tonic-colors-white-primary:rgba(255, 255, 255, .92);--tonic-colors-white-secondary:rgba(255, 255, 255, .60);--tonic-colors-white-tertiary:rgba(255, 255, 255, .47);--tonic-colors-white-disabled:rgba(255, 255, 255, .28);--tonic-colors-black-emphasis:rgba(0, 0, 0, 1.0);--tonic-colors-black-primary:rgba(0, 0, 0, .92);--tonic-colors-black-secondary:rgba(0, 0, 0, .65);--tonic-colors-black-tertiary:rgba(0, 0, 0, .54);--tonic-colors-black-disabled:rgba(0, 0, 0, .30);--tonic-fonts-base:"Segoe UI",-apple-system,BlinkMacSystemFont,"Helvetica Neue",Helvetica,Arial,sans-serif;--tonic-fonts-mono:"Segoe UI Mono","SFMono-Medium","SF Mono",Menlo,Consolas,Courier,monospace;--tonic-fontSizes-xs:.75rem;--tonic-fontSizes-sm:.875rem;--tonic-fontSizes-md:1rem;--tonic-fontSizes-lg:1.125rem;--tonic-fontSizes-xl:1.25rem;--tonic-fontSizes-2xl:1.5rem;--tonic-fontSizes-3xl:1.75rem;--tonic-fontSizes-4xl:2rem;--tonic-fontWeights-thin:100;--tonic-fontWeights-extralight:200;--tonic-fontWeights-light:300;--tonic-fontWeights-normal:400;--tonic-fontWeights-medium:500;--tonic-fontWeights-semibold:600;--tonic-fontWeights-bold:700;--tonic-fontWeights-extrabold:800;--tonic-fontWeights-black:900;--tonic-lineHeights-normal:normal;--tonic-lineHeights-base:1.5;--tonic-lineHeights-xs:1.125rem;--tonic-lineHeights-sm:1.25rem;--tonic-lineHeights-md:1.375rem;--tonic-lineHeights-lg:1.5rem;--tonic-lineHeights-xl:1.75rem;--tonic-lineHeights-2xl:2rem;--tonic-lineHeights-3xl:2.25rem;--tonic-lineHeights-4xl:2.5rem;--tonic-outlines-1:.0625rem solid;--tonic-outlines-2:.125rem solid;--tonic-outlines-3:.1875rem solid;--tonic-outlines-4:.25rem solid;--tonic-outlines-5:.3125rem solid;--tonic-radii-circle:50%;--tonic-radii-none:0;--tonic-radii-sm:.1875rem;--tonic-radii-md:.375rem;--tonic-radii-lg:.75rem;--tonic-shadows-none:none;--tonic-sizes-1q:.0625rem;--tonic-sizes-2q:.125rem;--tonic-sizes-3q:.1875rem;--tonic-sizes-4q:.25rem;--tonic-sizes-5q:.3125rem;--tonic-sizes-6q:.375rem;--tonic-sizes-7q:.4375rem;--tonic-sizes-8q:.5rem;--tonic-sizes-9q:.5625rem;--tonic-sizes-10q:.625rem;--tonic-sizes-1h:.125rem;--tonic-sizes-2h:.25rem;--tonic-sizes-3h:.375rem;--tonic-sizes-4h:.5rem;--tonic-sizes-5h:.625rem;--tonic-sizes-6h:.75rem;--tonic-sizes-7h:.875rem;--tonic-sizes-8h:1rem;--tonic-sizes-9h:1.125rem;--tonic-sizes-10h:1.25rem;--tonic-sizes-1x:.25rem;--tonic-sizes-2x:.5rem;--tonic-sizes-3x:.75rem;--tonic-sizes-4x:1rem;--tonic-sizes-5x:1.25rem;--tonic-sizes-6x:1.5rem;--tonic-sizes-7x:1.75rem;--tonic-sizes-8x:2rem;--tonic-sizes-9x:2.25rem;--tonic-sizes-10x:2.5rem;--tonic-sizes-11x:2.75rem;--tonic-sizes-12x:3rem;--tonic-sizes-13x:3.25rem;--tonic-sizes-14x:3.5rem;--tonic-sizes-15x:3.75rem;--tonic-sizes-16x:4rem;--tonic-sizes-17x:4.25rem;--tonic-sizes-18x:4.5rem;--tonic-sizes-19x:4.75rem;--tonic-sizes-20x:5rem;--tonic-sizes-24x:6rem;--tonic-sizes-32x:8rem;--tonic-sizes-40x:10rem;--tonic-sizes-48x:12rem;--tonic-sizes-56x:14rem;--tonic-sizes-64x:16rem;--tonic-space-1q:.0625rem;--tonic-space-2q:.125rem;--tonic-space-3q:.1875rem;--tonic-space-4q:.25rem;--tonic-space-5q:.3125rem;--tonic-space-6q:.375rem;--tonic-space-7q:.4375rem;--tonic-space-8q:.5rem;--tonic-space-9q:.5625rem;--tonic-space-10q:.625rem;--tonic-space-1h:.125rem;--tonic-space-2h:.25rem;--tonic-space-3h:.375rem;--tonic-space-4h:.5rem;--tonic-space-5h:.625rem;--tonic-space-6h:.75rem;--tonic-space-7h:.875rem;--tonic-space-8h:1rem;--tonic-space-9h:1.125rem;--tonic-space-10h:1.25rem;--tonic-space-1x:.25rem;--tonic-space-2x:.5rem;--tonic-space-3x:.75rem;--tonic-space-4x:1rem;--tonic-space-5x:1.25rem;--tonic-space-6x:1.5rem;--tonic-space-7x:1.75rem;--tonic-space-8x:2rem;--tonic-space-9x:2.25rem;--tonic-space-10x:2.5rem;--tonic-space-11x:2.75rem;--tonic-space-12x:3rem;--tonic-space-13x:3.25rem;--tonic-space-14x:3.5rem;--tonic-space-15x:3.75rem;--tonic-space-16x:4rem;--tonic-space-17x:4.25rem;--tonic-space-18x:4.5rem;--tonic-space-19x:4.75rem;--tonic-space-20x:5rem;--tonic-space-24x:6rem;--tonic-space-32x:8rem;--tonic-space-40x:10rem;--tonic-space-48x:12rem;--tonic-space-56x:14rem;--tonic-space-64x:16rem;--tonic-zIndices-hide:-1;--tonic-zIndices-auto:auto;--tonic-zIndices-base:0;--tonic-zIndices-dropdown:1000;--tonic-zIndices-sticky:1100;--tonic-zIndices-fixed:1200;--tonic-zIndices-overlay:1300;--tonic-zIndices-drawer:1400;--tonic-zIndices-modal:1500;--tonic-zIndices-popover:1600;--tonic-zIndices-toast:1700;--tonic-zIndices-tooltip:1800;}
+</style>
+`;
diff --git a/packages/react/src/theme/__tests__/createTheme.test.js b/packages/react/src/theme/__tests__/createTheme.test.js
index 775215f0a1..8d0c7f6c2b 100644
--- a/packages/react/src/theme/__tests__/createTheme.test.js
+++ b/packages/react/src/theme/__tests__/createTheme.test.js
@@ -1,3 +1,5 @@
+import { Box } from '@tonic-ui/react/src';
+import { render } from '@tonic-ui/react/test-utils/render';
 import createTheme from '../createTheme';
 
 describe('createTheme', () => {
@@ -77,4 +79,24 @@ describe('createTheme', () => {
       expect(isValid).toBe(true);
     });
   });
+
+  it('should apply custom `rootSelector` for CSS variables', () => {
+    const customRootSelector = ':root[data-color-scheme]';
+    const themeOptions = {
+      cssVariables: {
+        rootSelector: customRootSelector,
+      },
+    };
+
+    const theme = createTheme(themeOptions);
+    expect(theme.rootSelector).toBe(customRootSelector);
+
+    const TestComponent = (props) => (
+      <Box backgroundColor="gray:50" {...props} />
+    );
+    render(<TestComponent />, { theme: themeOptions });
+
+    const styleElement = document.querySelector('style[data-emotion="css-global"]');
+    expect(styleElement).toMatchSnapshot();
+  });
 });
diff --git a/packages/react/test-utils/render.js b/packages/react/test-utils/render.js
index 9447cc7563..a6cb8e8f01 100644
--- a/packages/react/test-utils/render.js
+++ b/packages/react/test-utils/render.js
@@ -15,14 +15,22 @@ import {
 expect.extend(matchers);
 
 const customRender = (ui, options) => {
+  const {
+    theme: themeOptions = {
+      cssVariables: {
+        prefix: 'tonic',
+        rootSelector: ':root',
+      },
+    },
+    ...rest
+  } = { ...options };
+
   const wrapper = ({ children }) => (
     <TonicProvider
       colorMode={{
         defaultValue: 'dark',
       }}
-      theme={createTheme({
-        cssVariables: true,
-      })}
+      theme={createTheme(themeOptions)}
     >
       <PortalManager>
         <ToastManager>
@@ -32,7 +40,7 @@ const customRender = (ui, options) => {
     </TonicProvider>
   );
 
-  return render(ui, { wrapper, ...options });
+  return render(ui, { wrapper, ...rest });
 };
 
 // re-export everything