docs: add README for compat package

docs/ReadMeCompat.mdx

@@ -0,0 +1,38 @@
+import { Footer, TableOfContent, FilterBarExample } from '@sb/components';
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Legacy Components / Docs" />
+
+<TableOfContent />
+
+# @ui5/webcomponents-react-compat
+
+The `compat` (compatibility) package provides components that were removed in the v2 release but are still available for backwards compatibility.
+
+Some of these components lack accessibility or design support, while others have been replaced by UI5 web components. In general, we recommend using components from this package only as a temporary solution.
+
+## Component Support
+
+Components in this package will not receive any new features. Only critical bugs, that are outside the component's inherent limitations, will be addressed. This package will be maintained until the next major release (which is not currently on our roadmap).
+
+## Installation
+
+```bash
+npm install @ui5/webcomponents-react-compat
+```
+
+## Importing Components
+
+As the v1 `ui5-table` (`Table`) component is part of this package and some custom element names are equal to the new v2 `ui5-table`, importing components from the root (`import { Table } from "@ui5/webcomponents-react-compat"`) is discouraged.
+The primary reason is that tree-shaking capabilities are limited in the default configurations of most bundlers. As a result, custom elements for the v1 table will still be defined, even if only the `Toolbar` is imported. This can cause unexpected behavior if the v2 table is also used in the same app.
+
+**Please only import components from the file path!**
+
+E.g.:
+
+- `import { Table } from '@ui5/webcomponents-react-compat/dist/components/Table/index.js';`
+- `import { Toolbar } from '@ui5/webcomponents-react-compat/dist/components/Toolbar/index.js';`
+
+**It is not supported using the v1 `Table` and the v2 `Table` in the same application!**
+
+<Footer />

packages/compat/README.md

@@ -1,13 +1,33 @@
 # @ui5/webcomponents-react-compat
 
-React wrappers for the [@ui5/webcomponents-compat](https://www.npmjs.com/package/@ui5/webcomponents-compat) package.
+The `compat` (compatibility) package provides components that were removed in the v2 release but are still available for backwards compatibility.
+
+Some of these components lack accessibility or design support, while others have been replaced by UI5 web components. In general, we recommend using components from this package only as a temporary solution.
+
+## Component Support
+
+Components in this package will not receive any new features. Only critical bugs, that are outside the component's inherent limitations, will be addressed. This package will be maintained until the next major release (which is not currently on our roadmap).
 
 ## Installation
 
 ```bash
 npm install @ui5/webcomponents-react-compat
 ```
 
+## Importing Components
+
+As the v1 `ui5-table` (`Table`) component is part of this package and some custom element names are equal to the new v2 `ui5-table`, importing components from the root (`import { Table } from "@ui5/webcomponents-react-compat"`) is discouraged.
+The primary reason is that tree-shaking capabilities are limited in the default configurations of most bundlers. As a result, custom elements for the v1 table will still be defined, even if only the `Toolbar` is imported. This can cause unexpected behavior if the v2 table is also used in the same app.
+
+**Please only import components from the file path!**
+
+E.g.:
+
+- `import { Table } from '@ui5/webcomponents-react-compat/dist/components/Table/index.js';`
+- `import { Toolbar } from '@ui5/webcomponents-react-compat/dist/components/Toolbar/index.js';`
+
+**It is not supported using the v1 `Table` and the v2 `Table` in the same application!**
+
 ## Documentation
 
 You can find an interactive documentation in our [Storybook](https://sap.github.io/ui5-webcomponents-react/) (Legacy Components).