diff --git a/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx
index aa4afb936d..ed32d31bab 100644
--- a/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/l/pt/developers/extend/apps/layout/front-components.mdx
@@ -523,15 +523,43 @@ Veja a [seção de recursos públicos](/l/pt/developers/extend/apps/config/publi
Componentes de front-end suportam várias abordagens de estilização. Você pode usar:
* **Estilos inline** — `style={{ color: 'red' }}`
-* **Componentes de UI do Twenty** — importe de `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar e mais)
+* **Twenty UI components** — Twenty's own component library; see [Using Twenty UI components](#using-twenty-ui-components) below
* **Emotion** — CSS-in-JS com `@emotion/react`
* **Styled-components** — padrões `styled.div`
* **Tailwind CSS** — classes utilitárias
* **Qualquer biblioteca CSS-in-JS** compatível com React
+## Using Twenty UI components
+
+Twenty ships its component library as the [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1) package. Front components can use it for buttons, tags, status pills, chips, avatars, icons, typography, and theme tokens that automatically match the workspace's light and dark theme.
+
+### Installation
+
+Add the package to your app, pinned to the version your Twenty instance ships:
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` is bundled into your front component at build time, so it only needs to be a dependency of your app — there is nothing to configure at runtime.
+
+### Importing components
+
+Import from the matching subpath rather than the package root, so only the components you use end up in your bundle:
+
+| Subpath | What it exports |
+| --------------------------- | -------------------------------------------------- |
+| `twenty-ui/input` | `Button` and form inputs |
+| `twenty-ui/data-display` | `Tag`, `Status`, `Chip`, `Avatar`, and more |
+| `twenty-ui/feedback` | `Callout`, `Banner`, `Info`, and more |
+| `twenty-ui/typography` | `H1Title`, `H2Title`, `H3Title`, `Label`, and more |
+| `twenty-ui/icon` | `Icon*` components (e.g. `IconCheck`) |
+| `twenty-ui/theme-constants` | `ThemeProvider`, `themeCssVariables` |
+
```tsx
import { defineFrontComponent } from 'twenty-sdk/define';
-import { Button, Tag, Status } from 'twenty-sdk/ui';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
const StyledWidget = () => {
return (
@@ -549,3 +577,43 @@ export default defineFrontComponent({
component: StyledWidget,
});
```
+
+### Icons
+
+Import individual icons from `twenty-ui/icon`:
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+Each named icon is tree-shaken, so importing a handful adds little to your bundle. Avoid `IconsProvider`, `useIcons`, and `iconsState` — they pull in the full Tabler icon set (several MB).
+
+### Theming and theme tokens
+
+Twenty UI components automatically match the workspace's light and dark theme — the renderer applies the active color scheme on the host, and the components resolve their colors against it.
+
+To use the same design tokens in your own inline styles, call the `useTheme()` hook. It returns Twenty's theme tokens (spacing, colors, radii, fonts) wired to the active theme, with no `ThemeProvider` setup needed in your component:
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+ const theme = useTheme();
+
+ return (
+
+ Themed card
+
+ );
+};
+```
+
+Because `useTheme()` is a hook, you read tokens inside the component body, so the values always reflect the live theme. The same token map is also exported as the `themeCssVariables` constant, but prefer `useTheme()` in front components — a module-level constant that dereferences `themeCssVariables` can be undefined while the app manifest is extracted.
+
+To branch on the active scheme explicitly, read it with `useColorScheme()` from `twenty-sdk/front-component`, which returns `'light'` or `'dark'`.
diff --git a/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx
index c38e56bd42..c27887416f 100644
--- a/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/l/ro/developers/extend/apps/layout/front-components.mdx
@@ -523,15 +523,43 @@ Consultați [secțiunea despre resurse publice](/l/ro/developers/extend/apps/con
Componentele front-end acceptă mai multe abordări de stilizare. Puteți folosi:
* **Stiluri inline** — `style={{ color: 'red' }}`
-* **Componente Twenty UI** — import din `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar și altele)
+* **Twenty UI components** — Twenty's own component library; see [Using Twenty UI components](#using-twenty-ui-components) below
* **Emotion** — CSS-in-JS cu `@emotion/react`
* **Styled-components** — pattern-uri `styled.div`
* **Tailwind CSS** — clase utilitare
* **Orice bibliotecă CSS-in-JS** compatibilă cu React
+## Using Twenty UI components
+
+Twenty ships its component library as the [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1) package. Front components can use it for buttons, tags, status pills, chips, avatars, icons, typography, and theme tokens that automatically match the workspace's light and dark theme.
+
+### Instalare
+
+Add the package to your app, pinned to the version your Twenty instance ships:
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` is bundled into your front component at build time, so it only needs to be a dependency of your app — there is nothing to configure at runtime.
+
+### Importing components
+
+Import from the matching subpath rather than the package root, so only the components you use end up in your bundle:
+
+| Subpath | What it exports |
+| --------------------------- | -------------------------------------------------- |
+| `twenty-ui/input` | `Button` and form inputs |
+| `twenty-ui/data-display` | `Tag`, `Status`, `Chip`, `Avatar`, and more |
+| `twenty-ui/feedback` | `Callout`, `Banner`, `Info`, and more |
+| `twenty-ui/typography` | `H1Title`, `H2Title`, `H3Title`, `Label`, and more |
+| `twenty-ui/icon` | `Icon*` components (e.g. `IconCheck`) |
+| `twenty-ui/theme-constants` | `ThemeProvider`, `themeCssVariables` |
+
```tsx
import { defineFrontComponent } from 'twenty-sdk/define';
-import { Button, Tag, Status } from 'twenty-sdk/ui';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
const StyledWidget = () => {
return (
@@ -549,3 +577,43 @@ export default defineFrontComponent({
component: StyledWidget,
});
```
+
+### Pictograme
+
+Import individual icons from `twenty-ui/icon`:
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+Each named icon is tree-shaken, so importing a handful adds little to your bundle. Avoid `IconsProvider`, `useIcons`, and `iconsState` — they pull in the full Tabler icon set (several MB).
+
+### Theming and theme tokens
+
+Twenty UI components automatically match the workspace's light and dark theme — the renderer applies the active color scheme on the host, and the components resolve their colors against it.
+
+To use the same design tokens in your own inline styles, call the `useTheme()` hook. It returns Twenty's theme tokens (spacing, colors, radii, fonts) wired to the active theme, with no `ThemeProvider` setup needed in your component:
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+ const theme = useTheme();
+
+ return (
+
+ Themed card
+
+ );
+};
+```
+
+Because `useTheme()` is a hook, you read tokens inside the component body, so the values always reflect the live theme. The same token map is also exported as the `themeCssVariables` constant, but prefer `useTheme()` in front components — a module-level constant that dereferences `themeCssVariables` can be undefined while the app manifest is extracted.
+
+To branch on the active scheme explicitly, read it with `useColorScheme()` from `twenty-sdk/front-component`, which returns `'light'` or `'dark'`.
diff --git a/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx
index 717e15ba1e..492d18577d 100644
--- a/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/l/ru/developers/extend/apps/layout/front-components.mdx
@@ -523,15 +523,43 @@ export default defineFrontComponent({
Компоненты фронтенда поддерживают несколько подходов к стилизации. Вы можете использовать:
* **Встроенные стили** — `style={{ color: 'red' }}`
-* **Компоненты Twenty UI** — импорт из `twenty-sdk/ui` (Button, Tag, Status, Chip, Avatar и другие)
+* **Twenty UI components** — собственная библиотека компонентов Twenty; см. раздел [Using Twenty UI components](#using-twenty-ui-components) ниже
* **Emotion** — CSS-in-JS с `@emotion/react`
* **Styled-components** — паттерны `styled.div`
* **Tailwind CSS** — утилитарные классы
* **Любая библиотека CSS-in-JS**, совместимая с React
+## Using Twenty UI components
+
+Twenty поставляет свою библиотеку компонентов как пакет [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1). Front components can use it for buttons, tags, status pills, chips, avatars, icons, typography, and theme tokens that automatically match the workspace's light and dark theme.
+
+### Установка
+
+Add the package to your app, pinned to the version your Twenty instance ships:
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` is bundled into your front component at build time, so it only needs to be a dependency of your app — there is nothing to configure at runtime.
+
+### Importing components
+
+Import from the matching subpath rather than the package root, so only the components you use end up in your bundle:
+
+| Subpath | What it exports |
+| --------------------------- | -------------------------------------------------- |
+| `twenty-ui/input` | `Button` and form inputs |
+| `twenty-ui/data-display` | `Tag`, `Status`, `Chip`, `Avatar`, and more |
+| `twenty-ui/feedback` | `Callout`, `Banner`, `Info`, and more |
+| `twenty-ui/typography` | `H1Title`, `H2Title`, `H3Title`, `Label`, and more |
+| `twenty-ui/icon` | `Icon*` components (e.g. `IconCheck`) |
+| `twenty-ui/theme-constants` | `ThemeProvider`, `themeCssVariables` |
+
```tsx
import { defineFrontComponent } from 'twenty-sdk/define';
-import { Button, Tag, Status } from 'twenty-sdk/ui';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
const StyledWidget = () => {
return (
@@ -549,3 +577,43 @@ export default defineFrontComponent({
component: StyledWidget,
});
```
+
+### Иконки
+
+Import individual icons from `twenty-ui/icon`:
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+Each named icon is tree-shaken, so importing a handful adds little to your bundle. Avoid `IconsProvider`, `useIcons`, and `iconsState` — they pull in the full Tabler icon set (several MB).
+
+### Theming and theme tokens
+
+Twenty UI components automatically match the workspace's light and dark theme — the renderer applies the active color scheme on the host, and the components resolve their colors against it.
+
+To use the same design tokens in your own inline styles, call the `useTheme()` hook. It returns Twenty's theme tokens (spacing, colors, radii, fonts) wired to the active theme, with no `ThemeProvider` setup needed in your component:
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+ const theme = useTheme();
+
+ return (
+
+ Themed card
+
+ );
+};
+```
+
+Because `useTheme()` is a hook, you read tokens inside the component body, so the values always reflect the live theme. The same token map is also exported as the `themeCssVariables` constant, but prefer `useTheme()` in front components — a module-level constant that dereferences `themeCssVariables` can be undefined while the app manifest is extracted.
+
+To branch on the active scheme explicitly, read it with `useColorScheme()` from `twenty-sdk/front-component`, which returns `'light'` or `'dark'`.
diff --git a/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx
index 2872da17e7..81687947d6 100644
--- a/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/l/tr/developers/extend/apps/layout/front-components.mdx
@@ -523,15 +523,43 @@ Ayrıntılar için [genel varlıklar bölümüne](/l/tr/developers/extend/apps/c
Ön uç bileşenleri birden fazla biçimlendirme yaklaşımını destekler. Şunları kullanabilirsiniz:
* **Satır içi stiller** — `style={{ color: 'red' }}`
-* **Twenty UI bileşenleri** — `twenty-sdk/ui` içinden içe aktarın (Button, Tag, Status, Chip, Avatar ve daha fazlası)
+* **Twenty UI bileşenleri** — Twenty'nin kendi bileşen kitaplığı; aşağıda [Twenty UI bileşenlerini kullanma](#using-twenty-ui-components) bölümüne bakın
* **Emotion** — `@emotion/react` ile CSS-in-JS
* **Styled-components** — `styled.div` kalıpları
* **Tailwind CSS** — yardımcı sınıflar
* **React ile uyumlu herhangi bir CSS-in-JS kitaplığı**
+## Twenty UI bileşenlerini kullanma
+
+Twenty, bileşen kitaplığını [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1) paketi olarak sunar. Front components can use it for buttons, tags, status pills, chips, avatars, icons, typography, and theme tokens that automatically match the workspace's light and dark theme.
+
+### Kurulum
+
+Add the package to your app, pinned to the version your Twenty instance ships:
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` is bundled into your front component at build time, so it only needs to be a dependency of your app — there is nothing to configure at runtime.
+
+### Importing components
+
+Import from the matching subpath rather than the package root, so only the components you use end up in your bundle:
+
+| Subpath | What it exports |
+| --------------------------- | -------------------------------------------------- |
+| `twenty-ui/input` | `Button` and form inputs |
+| `twenty-ui/data-display` | `Tag`, `Status`, `Chip`, `Avatar`, and more |
+| `twenty-ui/feedback` | `Callout`, `Banner`, `Info`, and more |
+| `twenty-ui/typography` | `H1Title`, `H2Title`, `H3Title`, `Label`, and more |
+| `twenty-ui/icon` | `Icon*` components (e.g. `IconCheck`) |
+| `twenty-ui/theme-constants` | `ThemeProvider`, `themeCssVariables` |
+
```tsx
import { defineFrontComponent } from 'twenty-sdk/define';
-import { Button, Tag, Status } from 'twenty-sdk/ui';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
const StyledWidget = () => {
return (
@@ -549,3 +577,43 @@ export default defineFrontComponent({
component: StyledWidget,
});
```
+
+### İkonlar
+
+Import individual icons from `twenty-ui/icon`:
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+Each named icon is tree-shaken, so importing a handful adds little to your bundle. Avoid `IconsProvider`, `useIcons`, and `iconsState` — they pull in the full Tabler icon set (several MB).
+
+### Theming and theme tokens
+
+Twenty UI components automatically match the workspace's light and dark theme — the renderer applies the active color scheme on the host, and the components resolve their colors against it.
+
+To use the same design tokens in your own inline styles, call the `useTheme()` hook. It returns Twenty's theme tokens (spacing, colors, radii, fonts) wired to the active theme, with no `ThemeProvider` setup needed in your component:
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+ const theme = useTheme();
+
+ return (
+
+ Themed card
+
+ );
+};
+```
+
+Because `useTheme()` is a hook, you read tokens inside the component body, so the values always reflect the live theme. The same token map is also exported as the `themeCssVariables` constant, but prefer `useTheme()` in front components — a module-level constant that dereferences `themeCssVariables` can be undefined while the app manifest is extracted.
+
+To branch on the active scheme explicitly, read it with `useColorScheme()` from `twenty-sdk/front-component`, which returns `'light'` or `'dark'`.
diff --git a/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx
index c4fcbb9772..56aaaddc88 100644
--- a/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/l/zh/developers/extend/apps/layout/front-components.mdx
@@ -523,15 +523,43 @@ export default defineFrontComponent({
前端组件支持多种样式方案。 你可以使用：
* **内联样式** — `style={{ color: 'red' }}`
-* **Twenty UI 组件** — 从 `twenty-sdk/ui` 导入（Button、Tag、Status、Chip、Avatar 等）
+* **Twenty UI 组件** — Twenty 自身的组件库；请参阅下文的 [使用 Twenty UI 组件](#using-twenty-ui-components)
* **Emotion** — 使用 `@emotion/react` 的 CSS-in-JS
* **Styled-components** — `styled.div` 模式
* **Tailwind CSS** — 工具类
* **任何 CSS-in-JS 库**（与 React 兼容）
+## 使用 Twenty UI 组件
+
+Twenty 通过 [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.1) 包提供其组件库。 前端组件可以将其用于按钮、标签、状态徽章、Chip、头像、图标、排版，以及能够自动匹配工作区明暗主题的主题令牌。
+
+### 安装
+
+将该包添加到你的应用中，并固定为你的 Twenty 实例所提供的版本：
+
+```bash
+yarn add twenty-ui@1.0.0-alpha.1
+```
+
+`twenty-ui` 会在构建时被打包进你的前端组件中，因此它只需要作为你的应用的依赖——在运行时无需任何配置。
+
+### 导入组件
+
+请从匹配的子路径而不是包根路径导入，这样只有你使用到的组件才会被打包进你的 bundle：
+
+| 子路径 | 导出内容 |
+| --------------------------- | --------------------------------------- |
+| `twenty-ui/input` | `Button` 和表单输入组件 |
+| `twenty-ui/data-display` | `Tag`、`Status`、`Chip`、`Avatar` 等 |
+| `twenty-ui/feedback` | `Callout`、`Banner`、`Info` 等 |
+| `twenty-ui/typography` | `H1Title`、`H2Title`、`H3Title`、`Label` 等 |
+| `twenty-ui/icon` | `Icon*` 组件（例如 `IconCheck`） |
+| `twenty-ui/theme-constants` | `ThemeProvider`、`themeCssVariables` |
+
```tsx
import { defineFrontComponent } from 'twenty-sdk/define';
-import { Button, Tag, Status } from 'twenty-sdk/ui';
+import { Status, Tag } from 'twenty-ui/data-display';
+import { Button } from 'twenty-ui/input';
const StyledWidget = () => {
return (
@@ -549,3 +577,43 @@ export default defineFrontComponent({
component: StyledWidget,
});
```
+
+### 图标
+
+从 `twenty-ui/icon` 导入单个图标：
+
+```tsx
+import { IconBox, IconCheck } from 'twenty-ui/icon';
+```
+
+每个具名图标都支持 tree-shaking，因此只导入少量图标对 bundle 体积影响很小。 避免使用 `IconsProvider`、`useIcons` 和 `iconsState`——它们会引入完整的 Tabler 图标集（数 MB 大小）。
+
+### 主题和主题令牌
+
+Twenty UI 组件会自动匹配工作区的明暗主题——渲染器会在宿主上应用当前启用的配色方案，组件会基于该方案解析自己的颜色。
+
+要在你自己的行内样式中使用相同的设计令牌，请调用 `useTheme()` hook。 它会返回与当前主题关联的 Twenty 主题令牌（间距、颜色、圆角、字体），你的组件中无需设置 `ThemeProvider`：
+
+```tsx
+import { useTheme } from 'twenty-ui/theme-constants';
+
+const Card = () => {
+ const theme = useTheme();
+
+ return (
+
+ Themed card
+
+ );
+};
+```
+
+由于 `useTheme()` 是一个 hook，你需要在组件主体内部读取令牌，因此这些值始终能反映实时的主题。 同一份令牌映射也作为常量 `themeCssVariables` 导出，但在前端组件中更推荐使用 `useTheme()`——在应用清单被抽取时，解引用 `themeCssVariables` 的模块级常量可能会是 undefined。
+
+如果需要显式地根据当前配色方案做分支判断，可从 `twenty-sdk/front-component` 中使用 `useColorScheme()` 读取，它会返回 `'light'` 或 `'dark'`。