diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000000..f6f035bce00
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,289 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## Overview
+
+UI5 Web Components for React is a React wrapper library for SAP's UI5 Web Components. It provides Fiori-compliant React components by wrapping native UI5 Web Components with React-specific implementations. The project is a monorepo managed with Lerna and Yarn workspaces.
+
+## Critical: Working with Web Components
+
+### Event Handling (MUST KNOW)
+
+Web components emit **CustomEvents** with data in the `detail` property:
+
+```tsx
+// ❌ WRONG - won't work with web components
+const handleChange = (e) => {
+ console.log(e.selectedOption); // undefined!
+ console.log(e.value); // undefined!
+};
+
+// ✅ CORRECT - access via e.detail
+const handleChange = (e) => {
+ console.log(e.detail.selectedOption);
+ console.log(e.detail.value);
+};
+```
+
+For enriching events with additional data (internal use):
+
+```tsx
+import { enrichEventWithDetails } from '@ui5/webcomponents-react-base/internal/utils';
+
+onLoadMore(enrichEventWithDetails(e, { rowCount, totalRowCount }));
+```
+
+### Ref Handling (MUST KNOW)
+
+**Never use `useRef()` directly for forwarded refs** - use `useSyncRef()`:
+
+```tsx
+import { useSyncRef } from '@ui5/webcomponents-react-base/internal/hooks';
+
+const MyComponent = forwardRef((props, ref) => {
+ // ✅ CORRECT - syncs forwarded ref with internal ref
+ const [componentRef, internalRef] = useSyncRef(ref);
+
+ return ;
+});
+```
+
+### Slot Props (MUST KNOW)
+
+When passing custom React components to slot props, they **must forward the `slot` prop**:
+
+```tsx
+// ❌ WRONG - slot won't render correctly
+const CustomHeader = ({ children }) => {children}
;
+
+// ✅ CORRECT - forwards slot prop to root element
+const CustomHeader = ({ children, slot }) => {children}
;
+
+// Usage
+