diff --git a/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx
index 35c50a94da..3b561ff00e 100644
--- a/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/l/ar/developers/extend/apps/layout/front-components.mdx
@@ -6,6 +6,10 @@ icon: window-maximize
المكوّنات الأمامية هي مكوّنات React تُعرَض مباشرة داخل واجهة مستخدم Twenty. تعمل ضمن **Web Worker معزول** باستخدام Remote DOM — تُنفَّذ شيفرتك داخل iframe معزول ذو منشأ غير شفاف، ومع ذلك لا تزال واجهتها تُعرَض محليًا داخل الصفحة بدلًا من أن تظل محصورة داخل ذلك الـ iframe.
+
+Front components are still under active development. Your code runs against a partial DOM, not a real browser page, so advanced usages can fail, often silently. See [Current limitations](#current-limitations).
+
+
## أين يمكن استخدام مكوّنات الواجهة الأمامية
يمكن عرض مكوّنات الواجهة الأمامية في ثلاثة مواقع داخل Twenty:
@@ -69,10 +73,10 @@ export default defineCommandMenuItem({
| الحقل | مطلوب | الوصف |
| --------------------- | ----- | ------------------------------------------------------------- |
-| `universalIdentifier` | نعم | معرّف فريد ثابت لهذا المكوّن |
+| `universalIdentifier` | Yes | معرّف فريد ثابت لهذا المكوّن |
| `component` | نعم | دالة مكوّن React |
-| `name` | لا | الاسم المعروض |
-| `description` | لا | وصف لما يفعله المكوّن |
+| `name` | No | الاسم المعروض |
+| `description` | No | وصف لما يفعله المكوّن |
| `isHeadless` | لا | عيّنه على `true` إذا كان المكوّن بلا واجهة مرئية (انظر أدناه) |
## وضع مكوّن أمامي على صفحة
@@ -696,3 +700,72 @@ const Card = () => {
نظرًا لأن `useTheme()` خطّاف، فإنك تقرأ الرموز داخل جسم المكوّن، لذا تعكس القيم دائمًا النسق المباشر (الحالي). تُصدَّر خريطة الرموز نفسها أيضًا كثابت `themeCssVariables`، لكن يُفضَّل استخدام `useTheme()` في المكوّنات الأمامية — إذ يمكن أن يكون الثابت على مستوى الوحدة الذي يفكّ مرجعية `themeCssVariables` غير معرَّف أثناء استخراج بيان التطبيق (app manifest).
للتفرّع بناءً على النظام النشِط (active scheme) صراحةً، اقرأه باستخدام `useColorScheme()` من `twenty-sdk/front-component`، والذي يعيد `'light'` أو `'dark'`.
+
+## Current limitations
+
+Front components are under active development. Rendering, styling and handling events works well. Anything that reaches *past* rendering (measuring an element, calling a DOM method on a ref, portaling outside your tree, touching browser storage) is missing or incomplete today, and most of it fails silently: no exception, and no TypeScript error either, since the scaffold is typed against the full browser DOM.
+
+If one of these blocks you, [open an issue](https://github.com/twentyhq/twenty/issues/new/choose) so it gets prioritized.
+
+### Layout and measurement
+
+Nothing can measure itself yet.
+
+| API | What happens |
+| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `getBoundingClientRect()`, `getClientRects()` | Throws |
+| `offsetWidth`, `clientWidth`, `scrollWidth`, `offsetTop`, ... | Silently `undefined`, so `width ?? 0` yields `0` and `width > 600` is always false |
+| `ResizeObserver`, `IntersectionObserver` | `ReferenceError` (`typeof` guards do work) |
+| `window.matchMedia()`, `window.getComputedStyle()` | Throws |
+| `window.innerWidth`, `innerHeight`, `devicePixelRatio` | Silently `undefined` |
+| `new MutationObserver(fn)` | Constructs, then `.observe()` throws |
+
+So recharts `ResponsiveContainer`, Floating UI / Popper, list virtualization and drag-to-resize do not work yet. Do layout in CSS instead: your stylesheet reaches the real page, so flexbox, grid, `aspect-ratio`, `clamp()` and `@container` all behave normally.
+
+
+`requestAnimationFrame`, `fetch`, `setTimeout` and `queueMicrotask` work without the `window.` prefix. Only `window.requestAnimationFrame(...)` and friends throw.
+
+
+### DOM access
+
+A `ref` gives you a sandbox element, not an `HTMLElement`.
+
+| What you write | What happens | Use instead |
+| ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `ref.current.focus()`, `.click()`, `.select()`, `.setSelectionRange()`, `.scrollIntoView()`, `video.play()` | Throws | Controlled components; read values from `event.target` |
+| `element.classList.add(...)` | Throws (`classList` is `undefined`) | Build the `className` string yourself |
+| `document.getElementById()`, `getElementsByClassName()`, `createTreeWalker()` | Throws | `querySelector()` / `querySelectorAll()`, which work |
+| `document.activeElement` | Always `undefined` | Track focus with `onFocus` / `onBlur` |
+| `\