Updating theme extension docs

apps/public-docsite-v9/src/Concepts/Theming.stories.mdx

@@ -123,25 +123,48 @@ export const customLightTheme: Theme = {
 
 ### Extending theme with new tokens
 
-Similarly to overriding existing tokens, you can add custom tokens as well.
+It's often useful to extend the base set of tokens from Fluent UI.
 
-⚠ Components which use custom tokens cannot be shared between applications. Keep in mind that any application which uses a component with custom tokens must also add the custom tokens to its own themes. Instead of adding custom tokens inside potentially reusable components, you should talk to design.
+⚠ Warning that adding more tokens adds more CSS variables which can effect run time performance as each DOM Node carries all the tokens.
 
 ```tsx
-import { webLightTheme, Theme } from '@fluentui/react-components';
+import { makeStyles, themeToTokensObject, webLightTheme, FluentProvider, Theme } from '@fluentui/react-components';
 
-export const customLightTheme: Theme & { customSpacingVerticalHuge: string } = {
-  ...webLightTheme,
-  customSpacingVerticalHuge: '128px',
+// You can pass your own custom tokens to a theme and pass that to the provider.
+type CustomTheme = Theme & {
+  tokenA: string;
+  tokenB: string;
+  tokenC: string;
 };
-```
+const customTheme: CustomTheme = { ...webLightTheme, tokenA: 'red', tokenB: 'blue', tokenC: 'green' };
+function App() {
+  return <FluentProvider theme={customTheme}>{/* ... */}</FluentProvider>;
+}
 
-To use the tokens in styles, one is supposed to import `tokens`. Obviously that object would not contain any custom tokens. For that reason you can use `themeToTokensObject()` utility which will create the tokens object with the custom tokens.
+// ...
 
-⚠ Keep in mind that the object generated by the `themeToTokensObject()` will contain all the tokens and will not be tree-shakeable.
+// You can construct a custom tokens object by yourself.
+const customTokens: Record<keyof CustomTheme, string> = {
+  ...tokens,
+  tokenA: `var(--tokenA)`,
+  tokenB: `var(--tokenB)`,
+  tokenC: `var(--tokenC)`,
+};
 
-```tsx
-import { themeToTokensObject } from '@fluentui/react-components';
+// You can alternatively use the themeToTokensObject function to construct the custom tokens object.
+// Note: If you do it via the themeToTokensObject you might see a negative effect on tree-shaking since bundles won't know the shape of the output.
+const alternativeCustomTokens = themeToTokensObject(customTheme);
+
+// You can then use this custom tokens object inside your styles.
+const useStyles = makeStyles({
+  base: {
+    color: customTokens.tokenA,
+    backgroundColor: customTokens.tokenB,
+    outlineColor: customTokens.tokenC,
+  },
+});
+```
+
+```
 
-export const customTokens = themeToTokensObject(customLightTheme);
 ```