maxGraph · tbouffard · May 8, 2025 · May 7, 2025 · May 7, 2025 · May 7, 2025
diff --git a/packages/html/stories/Introduction.mdx b/packages/html/stories/Introduction.mdx
@@ -27,11 +27,46 @@
   `}
 </style>
 
-# Welcome to maxGraph Stories
 
-These Stories are built with Storybook and demonstrates some use-cases that can be solved with `maxGraph`.
+# Welcome to the maxGraph Demo ✨
+
+The demo, built with [Storybook](https://storybook.js.org/), showcases the features of `maxGraph` through interactive examples. Stories are organized by functionality, making it easy to explore different capabilities of the library.
+
+## 🔍 What You'll Find Here
+
+- **Feature Demonstrations**: Each story focuses on specific capabilities, from basic graph rendering to advanced interactions
+- **Combination Examples**: See how multiple features work together to create powerful graph applications
+- **Extension Patterns**: Learn how to extend `maxGraph` for custom requirements
+- **Interactive Controls**: Many stories include [Storybook controls](https://storybook.js.org/docs/7/essentials/controls) that let you experiment with parameters in real-time
+
+## 🚀 Continuous Improvement
+
+We regularly add new examples that:
+- Demonstrate recently added features
+- Cover additional use cases
+- Provide clearer documentation within the stories themselves
+- Link to detailed documentation for more complex topics
+
+## 💻 Technical Details
+
+- Stories are being progressively migrated from _JavaScript_ to _TypeScript_
+- The examples evolved from the original `mxGraph` codebase:
+  - [mxGraph live examples](https://jgraph.github.io/mxgraph/javascript/index.html)
+  - [mxGraph examples source](https://github.com/jgraph/mxgraph/tree/v4.2.2/javascript/examples/)
+- The source code of the stories is accessible in multiple ways:
+  - Within the demo via the "Code" tab in the Addon Panel ([Storysource Addon](https://www.npmjs.com/package/@storybook/addon-storysource))
+  - Source of all stories in [packages/html/stories](https://github.com/maxGraph/maxGraph/tree/main/packages/html/stories/)
+  - Global maxGraph configuration in [packages/html/.storybook/preview.ts](https://github.com/maxGraph/maxGraph/tree/main/packages/html/.storybook/preview.ts)
+- Some stories may still be under active development
+
+## 🤝 Support
+
+For more details about how to use maxGraph features, see the [documentation](https://maxgraph.github.io/maxGraph/docs/intro).
+
+If you encounter any issues, create a sub-issue under the [issue tracking all demo improvements](https://github.com/maxGraph/maxGraph/issues/505) issue.
+
+If you have any questions or suggestions, create a new discussion on the [GitHub repository](https://github.com/maxGraph/maxGraph/discussions/categories/q-a).
 
 <div className="tip-wrapper">
-  <span className="tip">Tip</span>Edit the Markdown in{' '}
-  <code>stories/Introduction.stories.mdx</code>
+  <span className="tip">Tip</span> To edit this page, update the <code>packages/html/stories/Introduction.mdx</code> file in the <i>maxGraph</i> repository.
 </div>
diff --git a/packages/website/docs/demo-and-examples.md b/packages/website/docs/demo-and-examples.md
@@ -21,7 +21,7 @@ Note that they are based on `maxGraph` features, which require the use of [CSS a
 
 ## Interactive Demos
 - the [storybook stories](https://github.com/maxGraph/maxGraph/tree/main/packages/html/stories) demonstrates various features of maxGraph.
-  - The stories are currently written in `JavaScript` and will be progressively migrated to `TypeScript`.
+  - The stories were originally written in `JavaScript` and are being progressively migrated to `TypeScript`.
   - A live instance is available on the [maxGraph website](https://maxgraph.github.io/maxGraph/demo).
 
 ## TypeScript Examples