Docs: Improve error message and docs for mixing Storybook and React hooks in render functions

code/core/src/preview-api/modules/addons/hooks.ts

@@ -218,7 +218,10 @@ const areDepsEqual = (deps: any[], nextDeps: any[]) =>
   deps.length === nextDeps.length && deps.every((dep, i) => dep === nextDeps[i]);
 
 const invalidHooksError = () =>
-  new Error('Storybook preview hooks can only be called inside decorators and story functions.');
+  new Error(
+    'Storybook preview hooks can only be called inside decorators and story functions.\n\n' +
+      "When combining Storybook hooks (e.g. useArgs) with framework hooks (e.g. React's useState, useEffect, useRef) in the same render function, use Storybook's equivalents from 'storybook/preview-api' instead: useState, useEffect, useRef, useMemo, useCallback, useReducer."
+  );
 
 function getHooksContextOrNull<
   TRenderer extends Renderer,

docs/writing-stories/args.mdx

@@ -145,6 +145,12 @@ Args specified through the URL will extend and override any default values of ar
   <CodeSnippets path="page-story-args-within-story.md" />
 
   {/* prettier-ignore-end */}
+
+  <Callout variant="warning">
+
+    If you're using Storybook's hooks API in the story's render function, **do not** mix them with React's hooks such as `useState`, `useEffect`, or `useRef`. This is because side effects and re-rendering triggered by React's hooks do not run through Storybook's hook context, which can cause an error on re-render. To manage state and side effects within a story, you must use Storybook's equivalent hooks, such as `useState`, `useEffect`, and `useRef` from `storybook/preview-api`.
+
+  </Callout>
 </IfRenderer>
 
 ## Mapping to complex arg values

docs/writing-stories/decorators.mdx

@@ -62,7 +62,7 @@ The second argument to a decorator function is the **story context** which conta
 * `args` - the story arguments. You can use some [`args`](./args.mdx) in your decorators and drop them in the story implementation itself.
 * `argTypes`- Storybook's [argTypes](../api/arg-types.mdx) allow you to customize and fine-tune your stories [`args`](./args.mdx).
 * `globals` - Storybook-wide [globals](../essentials/toolbars-and-globals.mdx#globals). In particular you can use the [toolbars feature](../essentials/toolbars-and-globals.mdx#global-types-and-the-toolbar-annotation) to allow you to change these values using Storybook’s UI.
-* `hooks` - Storybook's API hooks (e.g., useArgs).
+* `hooks` - Storybook's API hooks (e.g., `useArgs`, `useGlobals`). These are available in both decorators and story render functions. When using these hooks in a render function alongside framework hooks (e.g., React's `useState`, `useEffect`), use Storybook's hook equivalents from `storybook/preview-api` instead to avoid errors on re-render.
 * `parameters`- the story's static metadata, most commonly used to control Storybook's behavior of features and addons.
 * `viewMode`- Storybook's current active window (e.g., canvas, docs).