docs: add "CSS Theme Variables" page

packages/react-docs/config/sidebar-routes.js

@@ -34,7 +34,6 @@ export const routes = [
       { title: 'Usage', path: 'getting-started/usage' },
       { title: 'Color Mode', path: 'getting-started/color-mode' },
       { title: 'Color Style', path: 'getting-started/color-style' },
-      { title: 'CSS Variables', path: 'getting-started/css-variables' },
       { title: 'Icons', path: 'getting-started/icons' },
       { title: 'The sx prop', path: 'getting-started/the-sx-prop' },
       { title: 'Security', path: 'getting-started/security' },
@@ -68,6 +67,7 @@ export const routes = [
       <ToolsConfigurationIcon size="4x" {...props} />
     ),
     routes: [
+      { title: 'CSS Theme Variables', path: 'customization/css-theme-variables' },
       { title: 'Shadow DOM', path: 'customization/shadow-dom' },
     ],
   },

packages/react-docs/pages/getting-started/css-variables/default-css-variables.js → packages/react-docs/pages/customization/css-theme-variables.js

@@ -17,23 +17,23 @@ const App = () => {
 
   return (
     <Box fontFamily="mono">
-      {Object.entries(theme?.cssVariables).map(([name, value]) => {
-        if (!name.startsWith('--')) {
-          return null;
-        }
-
-        return (
-          <Flex key={name} columnGap="2x">
-            <Text color={tokenColor}>{name}:</Text>
-            <Flex alignItems="center" columnGap="1x">
-              {isColorCode(value) && (
-                <Box backgroundColor={value} border={1} borderColor={borderColor} width="3x" height="3x" />
-              )}
-              <Text>{value};</Text>
+      {':root {'}
+      <Box ml="4x">
+        {Object.entries(theme?.cssVariables).map(([name, value]) => {
+          return (
+            <Flex key={name} columnGap="2x">
+              <Text color={tokenColor}>{name}:</Text>
+              <Flex alignItems="center" columnGap="1x">
+                {isColorCode(value) && (
+                  <Box backgroundColor={value} border={1} borderColor={borderColor} width="3x" height="3x" />
+                )}
+                <Text>{value};</Text>
+              </Flex>
             </Flex>
-          </Flex>
-        );
-      })}
+          );
+        })}
+      </Box>
+      {'}'}
     </Box>
   );
 };

packages/react-docs/pages/customization/css-theme-variables.page.mdx

@@ -0,0 +1,87 @@
+# CSS Theme Variables
+
+Learn how to adopt CSS theme variables.
+
+## Getting Started
+
+To use CSS theme variables, create a theme with `cssVariables: true` and wrap your app with `TonicProvider`:
+
+```jsx
+import {
+  TonicProvider,
+  createTheme,
+} from '@tonic-ui/react';
+
+// `createTheme` was introduced in v2.5.0
+const theme = createTheme({ cssVariables: true });
+
+function App() {
+  return (
+    <TonicProvider theme={theme}>
+      {/* Your app content */}
+    </TonicProvider>
+  );
+}
+```
+
+After rendering, you will see all CSS theme variables in the `:root` stylesheet of the HTML document. By default, these variables are prefixed with `--tonic`. You can open the **Developer Tools** and go to the **Elements** tab to see all the CSS theme variables being used on the webpage.
+
+{render('./css-theme-variables')}
+
+## Customizing Variable Prefix
+
+You can customize the variable prefix by providing a string to the `prefix` property in the theme configuration.
+
+```js
+createTheme({
+  cssVariables: {
+    prefix: 'custom',
+  },
+});
+```
+
+```css
+:root {
+  --custom-borders-1: .0625rem solid;
+  --custom-borders-2: .125rem solid;
+  /* More variables */
+}
+```
+
+If you prefer not to use any prefix, set `prefix` to an empty string:
+
+```js
+createTheme({
+  cssVariables: {
+    prefix: '',
+  },
+});
+```
+
+```css
+:root {
+  --borders-1: .0625rem solid;
+  --borders-2: .125rem solid;
+  /* More variables */
+}
+```
+
+## Variables Inside Shadow DOM
+
+To apply CSS theme variables inside shadow DOM, specify a different root selector using the `rootSelector` option:
+
+```js
+createTheme({
+  cssVariables: {
+    rootSelector: ':host',
+  },
+});
+```
+
+```css
+:host {
+  --tonic-borders-1: .0625rem solid;
+  --tonic-borders-2: .125rem solid;
+  /* More variables */
+}
+```