docs(icons): update storybook with rem sizing instructions (#19148)

* docs(icons): update storybook with rem sizing instructions

* fix(icons): update story format, minor verbiage tweak

* fix(icon): reduce relative story down to just an icon

---------

Co-authored-by: Taylor Jones <[email protected]>
Co-authored-by: Taylor Jones <[email protected]>

Author: heloiselui

packages/react/src/components/Icons/Icons.mdx

@@ -0,0 +1,72 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+import * as IconsStories from './Icons.stories';
+import { stackblitzPrefillConfig } from '../../../previewer/codePreviewer';
+
+<Meta isTemplate />
+
+# Icons
+
+[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Icons)
+&nbsp;|&nbsp;
+[Usage guidelines](https://carbondesignsystem.com/elements/icons/usage/)
+
+## Table of Contents
+
+- [Icons](#Icons)
+  - [Overview](#overview)
+  - [Customizing icon size with rem units](#customizing-icon-size-with-rem-units)
+- [Feedback](#feedback)
+
+## Overview
+
+<Canvas
+  of={IconsStories.Default}
+  additionalActions={[
+    {
+      title: 'Open in Stackblitz',
+      onClick: () => stackblitzPrefillConfig(IconsStories.Default),
+    },
+  ]}
+/>
+
+This guide demonstrates how to make icons scale using `rem` units, without
+requiring any changes to the component’s default configuration. In Carbon, icons
+accept a `size` prop that can be a number or a string. Numbers are unitless and
+interpreted as pixels. This approach is effective for most scenarios, but if
+your goal is to improve accessibility or ensure that icons respond to changes in
+the browser’s font-size, using a string with `rem` units offers greater
+adaptability.
+
+### Customizing icon size with `rem` units
+
+To create scalable, responsive icons, you can pass a `rem` value to the `size`
+prop:
+
+```jsx
+<Edit size="1rem" />
+```
+
+<Canvas
+  of={IconsStories.WithRelativeSize}
+  additionalActions={[
+    {
+      title: 'Open in Stackblitz',
+      onClick: () => stackblitzPrefillConfig(IconsStories.WithRelativeSize),
+    },
+  ]}
+/>
+
+Some components use a `renderIcon` prop to display icons internally.
+
+In these cases, you can still pass a responsive size by using an inline function
+that returns the icon:
+
+```jsx
+<MenuItem renderIcon={(props) => <Edit size="1rem" {...props} />} />
+```
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions on Slack,
+or updating this file on
+[GitHub](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Icons/Icons.mdx).

packages/react/src/components/Icons/Icons.stories.js

@@ -1,28 +1,44 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2025
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
 import './Icons.stories.scss';
 import React from 'react';
-import { Bee, Bicycle, ChevronUp } from '../../../icons';
+import { Bee, Edit } from '../../../icons';
+import { IconButton } from '../IconButton';
+import mdx from './Icons.mdx';
 
 // eslint-disable-next-line storybook/csf-component
 export default {
   title: 'Elements/Icons',
+  parameters: {
+    docs: {
+      page: mdx,
+    },
+  },
+  decorators: [
+    (Story, { args }) => {
+      return (
+        <section className="demo-icon-example">
+          <h2>
+            {args.size} {typeof args.size === 'number' && 'pixel'}{' '}
+            {args.size === 16 && '(default)'}
+            {typeof args.size === 'string' &&
+              args.size.includes('rem') &&
+              '(responsive)'}
+          </h2>
+          <Story />
+        </section>
+      );
+    },
+  ],
 };
 
 export const Default = (args) => {
-  return (
-    <section className="demo-icon-example">
-      <h2>
-        {args.size} pixel {args.size === 16 ? '(default)' : ''}
-      </h2>
-      <Bee {...args} />
-    </section>
-  );
+  return <Bee {...args} />;
 };
 
 Default.args = {
@@ -35,3 +51,13 @@ Default.argTypes = {
     control: { type: 'select' },
   },
 };
+
+export const WithRelativeSize = (args) => {
+  return <Edit {...args} />;
+};
+
+WithRelativeSize.args = {
+  size: '1rem',
+};
+
+WithRelativeSize.argTypes = { size: { control: 'text' } };