diff --git a/packages/blade/.storybook/react/preview.js b/packages/blade/.storybook/react/preview.js
index 2e0f1469cd5..58ff3c8df2c 100644
--- a/packages/blade/.storybook/react/preview.js
+++ b/packages/blade/.storybook/react/preview.js
@@ -34,6 +34,7 @@ export const parameters = {
'Motion',
'CSS Variables',
],
+ 'Utils',
'Components',
'Recipes',
],
diff --git a/packages/blade/docs/utils/useTheme.stories.mdx b/packages/blade/docs/utils/useTheme.stories.mdx
new file mode 100644
index 00000000000..f13ba4d27db
--- /dev/null
+++ b/packages/blade/docs/utils/useTheme.stories.mdx
@@ -0,0 +1,108 @@
+import { Meta } from '@storybook/addon-docs';
+
+
+
+## useTheme
+
+- [Overview](#overview)
+- [Usage](#usage)
+- [Types](#types)
+ - [`Theme`](#theme)
+ - [`ColorScheme`](#colorscheme)
+ - [`Platform`](#platform)
+ - [`ColorSchemeInput`](#colorschemeinput)
+
+### Overview
+
+`useTheme` is a custom React hook provided by the `@razorpay/blade/utils` that allows you to access the current theme and color scheme of your application.
+
+The `useTheme` hook returns a `ThemeContext` object that contains the following properties:
+
+| Property | Type | Description |
+| ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `theme` | [`Theme`](#theme) | The current theme object, which contains the values for various design tokens such as colors, typography, and spacing. |
+| `colorScheme` | [`ColorScheme`](#colorscheme) | The current color scheme of the application, which can be either 'light' or 'dark'. |
+| `platform` | [`Platform`](#platform) | The current platform of the application, which can be either 'onDesktop' or 'onMobile'. |
+| `setColorScheme` | `(colorScheme: `[`ColorSchemeInput`](#colorschemeinput)`) => void` | A function that allows you to set the color scheme of the application. |
+
+### Usage
+
+To use the `useTheme` hook, you must first wrap your application with a `BladeProvider` component, which provides the theme context to all child components. Here's an example of how to use the `useTheme` hook in a React component:
+
+```tsx
+import React from 'react';
+import { useTheme, Heading, Text, Button } from '@razorpay/blade/utis';
+
+const MyComponent = () => {
+ const { theme, colorScheme, platform, setColorScheme } = useTheme();
+
+ return (
+ <>
+ Hello, world!
+ The current color scheme is: {colorScheme}
+ The current platform is: {platform}
+
+ >
+ );
+};
+
+export default MyComponent;
+```
+
+### Types
+
+#### `Theme`
+
+```tsx
+type Theme = {
+ name: 'paymentTheme' | 'bankingTheme';
+ border: Border;
+ breakpoints: Breakpoints;
+ colors: Colors;
+ spacing: Spacing;
+ motion: Motion;
+ elevation: Elevation;
+ typography: Typography;
+};
+```
+
+To further explore the tokens in Theme, you can navigate to their respective documentations:
+
+- [Border](?path=/story/tokens-border--page)
+- [Breakpoints](?path=/story/tokens-breakpoints--page)
+- [Colors](?path=/story/tokens-colors--page)
+- [Spacing](?path=/story/tokens-spacing--page)
+- [Motion](?path=/story/tokens-motion--page)
+- [Elevation](?path=/story/tokens-elevation--page)
+- [Typography](?path=/story/tokens-typography--page)
+
+#### `ColorScheme`
+
+The current color scheme of the application. Can be either `'dark'` or `'light'`.
+If color scheme is set to 'system' using `setColorScheme`, the colorScheme property will return `'dark'` or `'light'` based on the user's system preferences.
+
+```tsx
+type ColorScheme = 'dark' | 'light';
+```
+
+#### `Platform`
+
+The current platform of the application. Can be either `'onDesktop'` or `'onMobile'`.
+Platform will be set to `'onDesktop'` or `'onMobile'` based on the [breakpoints](?path=/story/tokens-breakpoints--page&globals=measureEnabled:false) defined in the theme.
+
+> Note: Platform will always be `'onMobile'` for React Native
+
+```tsx
+type Platform = 'onDesktop' | 'onMobile';
+```
+
+#### `ColorSchemeInput`
+
+You can set the color scheme of your application to either `'dark'`, `'light'` or `'system'` using `setColorScheme`.
+Selecting `system` will set the color scheme of your application based on the user's system preferences.
+
+```tsx
+type ColorSchemeInput = 'dark' | 'light' | 'system';
+```
diff --git a/packages/blade/src/tokens/theme/overrideTheme.stories.tsx b/packages/blade/src/tokens/theme/overrideTheme.stories.tsx
index d39be847656..43bdc5a105a 100644
--- a/packages/blade/src/tokens/theme/overrideTheme.stories.tsx
+++ b/packages/blade/src/tokens/theme/overrideTheme.stories.tsx
@@ -55,7 +55,7 @@ const Page = (): ReactElement => {
};
export default {
- title: 'Utilities/overrideTheme',
+ title: 'Utils/overrideTheme',
args: {
hue: 259,
},
diff --git a/packages/blade/src/utils/index.ts b/packages/blade/src/utils/index.ts
index 2997e7970d0..1acb4a01f1e 100644
--- a/packages/blade/src/utils/index.ts
+++ b/packages/blade/src/utils/index.ts
@@ -15,3 +15,5 @@ export * from './makeSize';
// https://github.com/razorpay/blade/pull/1193#issuecomment-1609122359
export * from './toTitleCase';
export * from './usePrevious';
+
+export { default as useTheme, ThemeContext } from '~components/BladeProvider/useTheme';