Skip to content

The open alternative to Salesforce, designed for AI.

Split Twenty UI docs into primitives and components (#26045)

Raphaël Bosi6f99ef9af001
diff --git a/packages/twenty-docs/README.md b/packages/twenty-docs/README.md
index cd6befa145a..fe7be256846 100644
--- a/packages/twenty-docs/README.md
+++ b/packages/twenty-docs/README.md
@@ -11,7 +11,7 @@ Visit the documentation at [docs.twenty.com](https://docs.twenty.com)
This repository contains:
- **User Guide** (46 pages) - Complete guide for Twenty users
- **Developers** (24 pages) - Technical documentation for developers
-- **UI Library** - Guides and component references
+- **UI Library** - Guides, primitives, and components
## 🚀 Local Development
@@ -31,7 +31,7 @@ The documentation will be available at `http://localhost:3000`
1. Edit MDX files in the appropriate directory:
- `user-guide/` - User documentation
- `developers/` - Developer documentation
- - `ui/` - UI library guides and component references
+ - `ui/` - UI library guides, with primitive references under `ui/primitives/` and app building blocks under `ui/components/`
2. Update `navigation/base-structure.json` if you need to change the tab/group hierarchy or add/remove pages. This file stays in the repo and is **not** uploaded to Crowdin.
3. Keep the translation template (`navigation/navigation.template.json`) in sync by running `yarn docs:generate-navigation-template` after editing the base structure. This template is the only file that should be pushed to Crowdin.
diff --git a/packages/twenty-docs/docs.json b/packages/twenty-docs/docs.json
index c288de634cf..dcdc87488e1 100644
--- a/packages/twenty-docs/docs.json
+++ b/packages/twenty-docs/docs.json
@@ -511,54 +511,66 @@
]
},
{
- "group": "Data display",
+ "group": "Primitives",
"pages": [
- "ui/components/data-display/avatar",
- "ui/components/data-display/chip",
- "ui/components/data-display/tag",
- "ui/components/data-display/status"
- ]
- },
- {
- "group": "Forms",
- "pages": [
- "ui/components/input/field",
- "ui/components/input/input",
- "ui/components/input/input-group",
- "ui/components/input/textarea",
- "ui/components/input/checkbox",
- "ui/components/input/radio",
- "ui/components/input/radio-group",
- "ui/components/input/select",
- "ui/components/input/slider",
- "ui/components/input/switch"
- ]
- },
- {
- "group": "Navigation",
- "pages": [
- "ui/components/navigation/list-item",
- "ui/components/navigation/tabs"
- ]
- },
- {
- "group": "Surfaces",
- "pages": [
- "ui/components/surfaces/alert-dialog",
- "ui/components/surfaces/menu",
- "ui/components/surfaces/popover"
- ]
- },
- {
- "group": "Feedback",
- "pages": [
- "ui/components/feedback/toast"
+ "ui/primitives/overview",
+ {
+ "group": "Data display",
+ "pages": [
+ "ui/primitives/data-display/avatar",
+ "ui/primitives/data-display/chip",
+ "ui/primitives/data-display/tag",
+ "ui/primitives/data-display/status"
+ ]
+ },
+ {
+ "group": "Forms",
+ "pages": [
+ "ui/primitives/input/field",
+ "ui/primitives/input/input",
+ "ui/primitives/input/input-group",
+ "ui/primitives/input/textarea",
+ "ui/primitives/input/checkbox",
+ "ui/primitives/input/radio",
+ "ui/primitives/input/radio-group",
+ "ui/primitives/input/select",
+ "ui/primitives/input/slider",
+ "ui/primitives/input/switch"
+ ]
+ },
+ {
+ "group": "Navigation",
+ "pages": [
+ "ui/primitives/navigation/list-item",
+ "ui/primitives/navigation/tabs"
+ ]
+ },
+ {
+ "group": "Surfaces",
+ "pages": [
+ "ui/primitives/surfaces/alert-dialog",
+ "ui/primitives/surfaces/menu",
+ "ui/primitives/surfaces/popover"
+ ]
+ },
+ {
+ "group": "Feedback",
+ "pages": [
+ "ui/primitives/feedback/toast"
+ ]
+ },
+ {
+ "group": "Typography",
+ "pages": [
+ "ui/primitives/typography/text"
+ ]
+ }
]
},
{
- "group": "Typography",
+ "group": "Components",
"pages": [
- "ui/components/typography/text"
+ "ui/components/overview"
]
}
]
@@ -6598,27 +6610,27 @@
"redirects": [
{
"source": "/twenty-ui/input/checkbox",
- "destination": "/ui/components/input/checkbox"
+ "destination": "/ui/primitives/input/checkbox"
},
{
"source": "/twenty-ui/input/radio",
- "destination": "/ui/components/input/radio"
+ "destination": "/ui/primitives/input/radio"
},
{
"source": "/twenty-ui/input/select",
- "destination": "/ui/components/input/select"
+ "destination": "/ui/primitives/input/select"
},
{
"source": "/twenty-ui/input/text",
- "destination": "/ui/components/input/input"
+ "destination": "/ui/primitives/input/input"
},
{
"source": "/twenty-ui/input/toggle",
- "destination": "/ui/components/input/switch"
+ "destination": "/ui/primitives/input/switch"
},
{
"source": "/twenty-ui/navigation/menu-item",
- "destination": "/ui/components/navigation/list-item"
+ "destination": "/ui/primitives/navigation/list-item"
},
{
"source": "/twenty-ui",
diff --git a/packages/twenty-docs/navigation/base-structure.json b/packages/twenty-docs/navigation/base-structure.json
index c26460db52a..13b5c00be1f 100644
--- a/packages/twenty-docs/navigation/base-structure.json
+++ b/packages/twenty-docs/navigation/base-structure.json
@@ -519,61 +519,69 @@
]
},
{
- "key": "uiDataDisplay",
- "label": "Data display",
+ "key": "uiPrimitives",
+ "label": "Primitives",
"pages": [
- "ui/components/data-display/avatar",
- "ui/components/data-display/chip",
- "ui/components/data-display/tag",
- "ui/components/data-display/status"
- ]
- },
- {
- "key": "uiForms",
- "label": "Forms",
- "pages": [
- "ui/components/input/field",
- "ui/components/input/input",
- "ui/components/input/input-group",
- "ui/components/input/textarea",
- "ui/components/input/checkbox",
- "ui/components/input/radio",
- "ui/components/input/radio-group",
- "ui/components/input/select",
- "ui/components/input/slider",
- "ui/components/input/switch"
- ]
- },
- {
- "key": "uiNavigation",
- "label": "Navigation",
- "pages": [
- "ui/components/navigation/list-item",
- "ui/components/navigation/tabs"
- ]
- },
- {
- "key": "uiSurfaces",
- "label": "Surfaces",
- "pages": [
- "ui/components/surfaces/alert-dialog",
- "ui/components/surfaces/menu",
- "ui/components/surfaces/popover"
- ]
- },
- {
- "key": "uiFeedback",
- "label": "Feedback",
- "pages": [
- "ui/components/feedback/toast"
+ "ui/primitives/overview",
+ {
+ "key": "uiDataDisplay",
+ "label": "Data display",
+ "pages": [
+ "ui/primitives/data-display/avatar",
+ "ui/primitives/data-display/chip",
+ "ui/primitives/data-display/tag",
+ "ui/primitives/data-display/status"
+ ]
+ },
+ {
+ "key": "uiForms",
+ "label": "Forms",
+ "pages": [
+ "ui/primitives/input/field",
+ "ui/primitives/input/input",
+ "ui/primitives/input/input-group",
+ "ui/primitives/input/textarea",
+ "ui/primitives/input/checkbox",
+ "ui/primitives/input/radio",
+ "ui/primitives/input/radio-group",
+ "ui/primitives/input/select",
+ "ui/primitives/input/slider",
+ "ui/primitives/input/switch"
+ ]
+ },
+ {
+ "key": "uiNavigation",
+ "label": "Navigation",
+ "pages": [
+ "ui/primitives/navigation/list-item",
+ "ui/primitives/navigation/tabs"
+ ]
+ },
+ {
+ "key": "uiSurfaces",
+ "label": "Surfaces",
+ "pages": [
+ "ui/primitives/surfaces/alert-dialog",
+ "ui/primitives/surfaces/menu",
+ "ui/primitives/surfaces/popover"
+ ]
+ },
+ {
+ "key": "uiFeedback",
+ "label": "Feedback",
+ "pages": ["ui/primitives/feedback/toast"]
+ },
+ {
+ "key": "uiTypography",
+ "label": "Typography",
+ "pages": ["ui/primitives/typography/text"]
+ }
]
},
{
- "key": "uiTypography",
- "label": "Typography",
- "pages": [
- "ui/components/typography/text"
- ]
+ "key": "uiComponents",
+ "label": "Components",
+ "pages": ["ui/components/overview"]
}
]
}
diff --git a/packages/twenty-docs/navigation/navigation.template.json b/packages/twenty-docs/navigation/navigation.template.json
index 532c673609f..8717d50f5c8 100644
--- a/packages/twenty-docs/navigation/navigation.template.json
+++ b/packages/twenty-docs/navigation/navigation.template.json
@@ -203,23 +203,31 @@
"uiGuides": {
"label": "Guides"
},
- "uiDataDisplay": {
- "label": "Data display"
- },
- "uiForms": {
- "label": "Forms"
- },
- "uiNavigation": {
- "label": "Navigation"
- },
- "uiSurfaces": {
- "label": "Surfaces"
- },
- "uiFeedback": {
- "label": "Feedback"
+ "uiPrimitives": {
+ "label": "Primitives",
+ "groups": {
+ "uiDataDisplay": {
+ "label": "Data display"
+ },
+ "uiForms": {
+ "label": "Forms"
+ },
+ "uiNavigation": {
+ "label": "Navigation"
+ },
+ "uiSurfaces": {
+ "label": "Surfaces"
+ },
+ "uiFeedback": {
+ "label": "Feedback"
+ },
+ "uiTypography": {
+ "label": "Typography"
+ }
+ }
},
- "uiTypography": {
- "label": "Typography"
+ "uiComponents": {
+ "label": "Components"
}
}
}
diff --git a/packages/twenty-docs/ui/components/overview.mdx b/packages/twenty-docs/ui/components/overview.mdx
new file mode 100644
index 00000000000..645f2738408
--- /dev/null
+++ b/packages/twenty-docs/ui/components/overview.mdx
@@ -0,0 +1,9 @@
+---
+title: Components
+sidebarTitle: Overview
+description: Reusable app building blocks composed from Twenty UI primitives.
+---
+
+Components combine [primitives](/ui/primitives/overview) into reusable app building blocks, such as tables, boards, and pickers. Like primitives, they receive data and callbacks from your application.
+
+The `twenty-ui/components` entry point is reserved for this layer. It does not export any components yet. All currently available controls are documented under [Primitives](/ui/primitives/overview).
diff --git a/packages/twenty-docs/ui/getting-started.mdx b/packages/twenty-docs/ui/getting-started.mdx
index 904ea133d5d..48e5573bc33 100644
--- a/packages/twenty-docs/ui/getting-started.mdx
+++ b/packages/twenty-docs/ui/getting-started.mdx
@@ -82,15 +82,7 @@ Import individual icons, such as `IconCheck`, from `twenty-ui/icon`. The dynamic
- [Theming](/ui/theming): use semantic tokens and scoped overrides.
- [Dark mode](/ui/dark-mode): switch between light and dark palettes.
-## Components
-
-Each page includes usage examples, interaction guidance, and a generated API reference.
-
-| Family | Components |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Data display | [Avatar](/ui/components/data-display/avatar), [Chip](/ui/components/data-display/chip), [Tag](/ui/components/data-display/tag), [Status](/ui/components/data-display/status) |
-| Forms | [Field](/ui/components/input/field), [Input](/ui/components/input/input), [InputGroup](/ui/components/input/input-group), [Textarea](/ui/components/input/textarea), [Checkbox](/ui/components/input/checkbox), [Radio](/ui/components/input/radio), [RadioGroup](/ui/components/input/radio-group), [Select](/ui/components/input/select), [Slider](/ui/components/input/slider), [Switch](/ui/components/input/switch) |
-| Navigation | [ListItem](/ui/components/navigation/list-item), [Tabs](/ui/components/navigation/tabs) |
-| Surfaces | [AlertDialog](/ui/components/surfaces/alert-dialog), [Menu](/ui/components/surfaces/menu), [Popover](/ui/components/surfaces/popover) |
-| Feedback | [Toast](/ui/components/feedback/toast) |
-| Typography | [Text](/ui/components/typography/text) |
+## Browse the library
+
+- [Primitives](/ui/primitives/overview): foundational controls grouped by family, with usage examples and API references.
+- [Components](/ui/components/overview): reusable app building blocks composed from primitives.
diff --git a/packages/twenty-docs/ui/components/data-display/avatar.mdx b/packages/twenty-docs/ui/primitives/data-display/avatar.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/data-display/avatar.mdx
rename to packages/twenty-docs/ui/primitives/data-display/avatar.mdx
index 5010291024f..5f36a58a557 100644
--- a/packages/twenty-docs/ui/components/data-display/avatar.mdx
+++ b/packages/twenty-docs/ui/primitives/data-display/avatar.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import AvatarReference from '/snippets/ui/generated/data-display/avatar.mdx';
-`Avatar` shows an image with a first-letter fallback. Use it beside a record name or inside a [Chip](/ui/components/data-display/chip).
+`Avatar` shows an image with a first-letter fallback. Use it beside a record name or inside a [Chip](/ui/primitives/data-display/chip).
<StoryEmbed storyId="ui-data-display-avatar--app" title="Avatar example" />
diff --git a/packages/twenty-docs/ui/components/data-display/chip.mdx b/packages/twenty-docs/ui/primitives/data-display/chip.mdx
similarity index 95%
rename from packages/twenty-docs/ui/components/data-display/chip.mdx
rename to packages/twenty-docs/ui/primitives/data-display/chip.mdx
index 27db04bd831..046e77ee21c 100644
--- a/packages/twenty-docs/ui/components/data-display/chip.mdx
+++ b/packages/twenty-docs/ui/primitives/data-display/chip.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import ChipReference from '/snippets/ui/generated/data-display/chip.mdx';
-Use `Chip` for compact references to people, records, or files. Use [Tag](/ui/components/data-display/tag) for colored categories and [Status](/ui/components/data-display/status) for workflow states.
+Use `Chip` for compact references to people, records, or files. Use [Tag](/ui/primitives/data-display/tag) for colored categories and [Status](/ui/primitives/data-display/status) for workflow states.
<StoryEmbed
storyId="ui-data-display-chip--with-left-avatar"
diff --git a/packages/twenty-docs/ui/components/data-display/status.mdx b/packages/twenty-docs/ui/primitives/data-display/status.mdx
similarity index 94%
rename from packages/twenty-docs/ui/components/data-display/status.mdx
rename to packages/twenty-docs/ui/primitives/data-display/status.mdx
index ae32472e49e..a7fafa67554 100644
--- a/packages/twenty-docs/ui/components/data-display/status.mdx
+++ b/packages/twenty-docs/ui/primitives/data-display/status.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import StatusReference from '/snippets/ui/generated/data-display/status.mdx';
-`Status` combines a colored dot, a text label, and an optional loader. Use it for workflow or record states. Use [Tag](/ui/components/data-display/tag) for a category without the status indicator.
+`Status` combines a colored dot, a text label, and an optional loader. Use it for workflow or record states. Use [Tag](/ui/primitives/data-display/tag) for a category without the status indicator.
<StoryEmbed storyId="ui-data-display-status--default" title="Status example" />
diff --git a/packages/twenty-docs/ui/components/data-display/tag.mdx b/packages/twenty-docs/ui/primitives/data-display/tag.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/data-display/tag.mdx
rename to packages/twenty-docs/ui/primitives/data-display/tag.mdx
index 6800bd2ed98..f739df05532 100644
--- a/packages/twenty-docs/ui/components/data-display/tag.mdx
+++ b/packages/twenty-docs/ui/primitives/data-display/tag.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import TagReference from '/snippets/ui/generated/data-display/tag.mdx';
-Use `Tag` for categories, priorities, or other short attributes. Keep a text label so the meaning does not depend on color. Use [Status](/ui/components/data-display/status) when you need a state indicator and loading feedback.
+Use `Tag` for categories, priorities, or other short attributes. Keep a text label so the meaning does not depend on color. Use [Status](/ui/primitives/data-display/status) when you need a state indicator and loading feedback.
<StoryEmbed storyId="ui-data-display-tag--default" title="Tag example" />
diff --git a/packages/twenty-docs/ui/components/feedback/toast.mdx b/packages/twenty-docs/ui/primitives/feedback/toast.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/feedback/toast.mdx
rename to packages/twenty-docs/ui/primitives/feedback/toast.mdx
diff --git a/packages/twenty-docs/ui/components/input/checkbox.mdx b/packages/twenty-docs/ui/primitives/input/checkbox.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/input/checkbox.mdx
rename to packages/twenty-docs/ui/primitives/input/checkbox.mdx
index eb46c2325d2..173dda45ece 100644
--- a/packages/twenty-docs/ui/components/input/checkbox.mdx
+++ b/packages/twenty-docs/ui/primitives/input/checkbox.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import CheckboxReference from '/snippets/ui/generated/input/checkbox.mdx';
-Use `Checkbox` when each option can be selected independently. For a mutually exclusive choice, use [RadioGroup](/ui/components/input/radio-group).
+Use `Checkbox` when each option can be selected independently. For a mutually exclusive choice, use [RadioGroup](/ui/primitives/input/radio-group).
<StoryEmbed
storyId="ui-input-checkbox-checkbox--default"
diff --git a/packages/twenty-docs/ui/components/input/field.mdx b/packages/twenty-docs/ui/primitives/input/field.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/input/field.mdx
rename to packages/twenty-docs/ui/primitives/input/field.mdx
index aa0752923e7..a604b6ee36f 100644
--- a/packages/twenty-docs/ui/components/input/field.mdx
+++ b/packages/twenty-docs/ui/primitives/input/field.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import FieldReference from '/snippets/ui/generated/input/field.mdx';
-Use `Field` to group one control with its accessible label and helper text. Components such as [Input](/ui/components/input/input) integrate with the field directly.
+Use `Field` to group one control with its accessible label and helper text. Components such as [Input](/ui/primitives/input/input) integrate with the field directly.
<StoryEmbed
storyId="ui-input-field--default"
diff --git a/packages/twenty-docs/ui/components/input/input-group.mdx b/packages/twenty-docs/ui/primitives/input/input-group.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/input/input-group.mdx
rename to packages/twenty-docs/ui/primitives/input/input-group.mdx
index a516582f003..4c745357820 100644
--- a/packages/twenty-docs/ui/components/input/input-group.mdx
+++ b/packages/twenty-docs/ui/primitives/input/input-group.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import InputGroupReference from '/snippets/ui/generated/input/input-group.mdx';
-`InputGroup` gives an [Input](/ui/components/input/input) a shared border and optional leading or trailing content. Set `size` on the group to size both the container and its input.
+`InputGroup` gives an [Input](/ui/primitives/input/input) a shared border and optional leading or trailing content. Set `size` on the group to size both the container and its input.
<StoryEmbed
storyId="ui-input-inputgroup--default"
diff --git a/packages/twenty-docs/ui/components/input/input.mdx b/packages/twenty-docs/ui/primitives/input/input.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/input/input.mdx
rename to packages/twenty-docs/ui/primitives/input/input.mdx
diff --git a/packages/twenty-docs/ui/components/input/radio-group.mdx b/packages/twenty-docs/ui/primitives/input/radio-group.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/input/radio-group.mdx
rename to packages/twenty-docs/ui/primitives/input/radio-group.mdx
index e593b0e467b..19cfd5638ab 100644
--- a/packages/twenty-docs/ui/components/input/radio-group.mdx
+++ b/packages/twenty-docs/ui/primitives/input/radio-group.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import RadioGroupReference from '/snippets/ui/generated/input/radio-group.mdx';
-`RadioGroup` coordinates the value, keyboard navigation, and form submission of its [Radio](/ui/components/input/radio) children.
+`RadioGroup` coordinates the value, keyboard navigation, and form submission of its [Radio](/ui/primitives/input/radio) children.
<StoryEmbed
storyId="ui-input-radiogroup--default"
diff --git a/packages/twenty-docs/ui/components/input/radio.mdx b/packages/twenty-docs/ui/primitives/input/radio.mdx
similarity index 92%
rename from packages/twenty-docs/ui/components/input/radio.mdx
rename to packages/twenty-docs/ui/primitives/input/radio.mdx
index 66c5581f371..02a84bd0813 100644
--- a/packages/twenty-docs/ui/components/input/radio.mdx
+++ b/packages/twenty-docs/ui/primitives/input/radio.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import RadioReference from '/snippets/ui/generated/input/radio.mdx';
-`Radio` represents one option inside [RadioGroup](/ui/components/input/radio-group). Give each option a distinct `value` and a visible label. The group owns the selected value.
+`Radio` represents one option inside [RadioGroup](/ui/primitives/input/radio-group). Give each option a distinct `value` and a visible label. The group owns the selected value.
<StoryEmbed
storyId="ui-input-radio--documentation"
@@ -46,7 +46,7 @@ The `size` prop accepts `sm` or `md` and defaults to `sm`. Use the same size for
## Keyboard and selection
-Tab enters or leaves the group. Arrow keys move between enabled options and select the focused option. Space selects the focused radio. Selection and change handlers belong on `RadioGroup`; see its [controlled example](/ui/components/input/radio-group#controlled-state).
+Tab enters or leaves the group. Arrow keys move between enabled options and select the focused option. Space selects the focused radio. Selection and change handlers belong on `RadioGroup`; see its [controlled example](/ui/primitives/input/radio-group#controlled-state).
`Radio` is generic over the value type. Keep that type consistent with its group. Native attributes such as `aria-describedby` can associate an option with additional help text.
diff --git a/packages/twenty-docs/ui/components/input/select.mdx b/packages/twenty-docs/ui/primitives/input/select.mdx
similarity index 96%
rename from packages/twenty-docs/ui/components/input/select.mdx
rename to packages/twenty-docs/ui/primitives/input/select.mdx
index 1db72d3d6ca..76a1a98ef77 100644
--- a/packages/twenty-docs/ui/components/input/select.mdx
+++ b/packages/twenty-docs/ui/primitives/input/select.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import SelectReference from '/snippets/ui/generated/input/select.mdx';
-Use `Select` for a form value chosen from a list. Use [Menu](/ui/components/surfaces/menu) for commands and actions.
+Use `Select` for a form value chosen from a list. Use [Menu](/ui/primitives/surfaces/menu) for commands and actions.
<StoryEmbed
storyId="ui-input-select--documentation"
@@ -97,7 +97,7 @@ With `multiple`, the value is an array. The generic root types represent the opt
`Popup` defaults to `side="bottom"`, `align="start"`, and `sideOffset={8}`. Set `alignItemWithTrigger` to align the selected option over the trigger. It uses the [theme's portal container](/ui/theming#scope-an-override) unless you provide `container`.
-Keyboard users can open the list from the trigger, navigate options with arrow keys, and type to find an option. Escape dismisses the popup. Label the trigger or integrate the select with [Field](/ui/components/input/field); a placeholder alone does not name the control.
+Keyboard users can open the list from the trigger, navigate options with arrow keys, and type to find an option. Escape dismisses the popup. Label the trigger or integrate the select with [Field](/ui/primitives/input/field); a placeholder alone does not name the control.
## Props
diff --git a/packages/twenty-docs/ui/components/input/slider.mdx b/packages/twenty-docs/ui/primitives/input/slider.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/input/slider.mdx
rename to packages/twenty-docs/ui/primitives/input/slider.mdx
diff --git a/packages/twenty-docs/ui/components/input/switch.mdx b/packages/twenty-docs/ui/primitives/input/switch.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/input/switch.mdx
rename to packages/twenty-docs/ui/primitives/input/switch.mdx
diff --git a/packages/twenty-docs/ui/components/input/textarea.mdx b/packages/twenty-docs/ui/primitives/input/textarea.mdx
similarity index 96%
rename from packages/twenty-docs/ui/components/input/textarea.mdx
rename to packages/twenty-docs/ui/primitives/input/textarea.mdx
index 19e827f0acd..895617d15a8 100644
--- a/packages/twenty-docs/ui/components/input/textarea.mdx
+++ b/packages/twenty-docs/ui/primitives/input/textarea.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import TextareaReference from '/snippets/ui/generated/input/textarea.mdx';
-Use `Textarea` for notes, descriptions, and other multiline values. It integrates with [Field](/ui/components/input/field) for labels and validation.
+Use `Textarea` for notes, descriptions, and other multiline values. It integrates with [Field](/ui/primitives/input/field) for labels and validation.
<StoryEmbed
storyId="ui-input-textarea--default"
diff --git a/packages/twenty-docs/ui/components/navigation/list-item.mdx b/packages/twenty-docs/ui/primitives/navigation/list-item.mdx
similarity index 92%
rename from packages/twenty-docs/ui/components/navigation/list-item.mdx
rename to packages/twenty-docs/ui/primitives/navigation/list-item.mdx
index 9d2bc542767..c4c8fca34b5 100644
--- a/packages/twenty-docs/ui/components/navigation/list-item.mdx
+++ b/packages/twenty-docs/ui/primitives/navigation/list-item.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import ListItemReference from '/snippets/ui/generated/navigation/list-item.mdx';
-`ListItem` supplies the visual layout shared by list and menu rows. Use [Menu](/ui/components/surfaces/menu) or [Select](/ui/components/input/select) when you need their selection and keyboard behavior.
+`ListItem` supplies the visual layout shared by list and menu rows. Use [Menu](/ui/primitives/surfaces/menu) or [Select](/ui/primitives/input/select) when you need their selection and keyboard behavior.
<StoryEmbed
storyId="ui-navigation-listitem--default"
@@ -59,7 +59,7 @@ export const ShowArchivedToggle = () => {
};
```
-`selected`, `focused`, and `disabled` control row styling. The `check` and `checkbox` indicators are visual; use a real [Checkbox](/ui/components/input/checkbox) for a form control. When using a disabled button or link through `render`, also supply the element's appropriate disabled behavior and semantics.
+`selected`, `focused`, and `disabled` control row styling. The `check` and `checkbox` indicators are visual; use a real [Checkbox](/ui/primitives/input/checkbox) for a form control. When using a disabled button or link through `render`, also supply the element's appropriate disabled behavior and semantics.
## Slots
diff --git a/packages/twenty-docs/ui/components/navigation/tabs.mdx b/packages/twenty-docs/ui/primitives/navigation/tabs.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/navigation/tabs.mdx
rename to packages/twenty-docs/ui/primitives/navigation/tabs.mdx
diff --git a/packages/twenty-docs/ui/primitives/overview.mdx b/packages/twenty-docs/ui/primitives/overview.mdx
new file mode 100644
index 00000000000..c115225ab17
--- /dev/null
+++ b/packages/twenty-docs/ui/primitives/overview.mdx
@@ -0,0 +1,24 @@
+---
+title: Primitives
+sidebarTitle: Overview
+description: Foundational controls for building interfaces with Twenty UI.
+---
+
+Primitives are the foundational controls in Twenty UI. They include inputs, display elements, navigation, and compound controls such as Select, Menu, and AlertDialog. Each primitive receives data and callbacks from your application.
+
+Import primitives from a family entry point, such as `twenty-ui/primitives/input`. See [Getting started](/ui/getting-started) for installation and theme setup.
+
+All existing UI controls belong to the primitives layer, including controls still being migrated to the new API. [Components](/ui/components/overview) are reserved for larger, reusable app building blocks composed from these primitives.
+
+## Browse primitives
+
+Each page includes usage examples, interaction guidance, and a generated API reference.
+
+| Family | Primitives |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Data display | [Avatar](/ui/primitives/data-display/avatar), [Chip](/ui/primitives/data-display/chip), [Tag](/ui/primitives/data-display/tag), [Status](/ui/primitives/data-display/status) |
+| Forms | [Field](/ui/primitives/input/field), [Input](/ui/primitives/input/input), [InputGroup](/ui/primitives/input/input-group), [Textarea](/ui/primitives/input/textarea), [Checkbox](/ui/primitives/input/checkbox), [Radio](/ui/primitives/input/radio), [RadioGroup](/ui/primitives/input/radio-group), [Select](/ui/primitives/input/select), [Slider](/ui/primitives/input/slider), [Switch](/ui/primitives/input/switch) |
+| Navigation | [ListItem](/ui/primitives/navigation/list-item), [Tabs](/ui/primitives/navigation/tabs) |
+| Surfaces | [AlertDialog](/ui/primitives/surfaces/alert-dialog), [Menu](/ui/primitives/surfaces/menu), [Popover](/ui/primitives/surfaces/popover) |
+| Feedback | [Toast](/ui/primitives/feedback/toast) |
+| Typography | [Text](/ui/primitives/typography/text) |
diff --git a/packages/twenty-docs/ui/components/surfaces/alert-dialog.mdx b/packages/twenty-docs/ui/primitives/surfaces/alert-dialog.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/surfaces/alert-dialog.mdx
rename to packages/twenty-docs/ui/primitives/surfaces/alert-dialog.mdx
diff --git a/packages/twenty-docs/ui/components/surfaces/menu.mdx b/packages/twenty-docs/ui/primitives/surfaces/menu.mdx
similarity index 97%
rename from packages/twenty-docs/ui/components/surfaces/menu.mdx
rename to packages/twenty-docs/ui/primitives/surfaces/menu.mdx
index 4773bd3b83c..2591abd7632 100644
--- a/packages/twenty-docs/ui/components/surfaces/menu.mdx
+++ b/packages/twenty-docs/ui/primitives/surfaces/menu.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import MenuReference from '/snippets/ui/generated/surfaces/menu.mdx';
-Use `Menu` for actions opened from a trigger. Its items supply keyboard navigation and the visual layout of [ListItem](/ui/components/navigation/list-item).
+Use `Menu` for actions opened from a trigger. Its items supply keyboard navigation and the visual layout of [ListItem](/ui/primitives/navigation/list-item).
<StoryEmbed
storyId="ui-surfaces-menu--documentation"
diff --git a/packages/twenty-docs/ui/components/surfaces/popover.mdx b/packages/twenty-docs/ui/primitives/surfaces/popover.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/surfaces/popover.mdx
rename to packages/twenty-docs/ui/primitives/surfaces/popover.mdx
diff --git a/packages/twenty-docs/ui/components/typography/text.mdx b/packages/twenty-docs/ui/primitives/typography/text.mdx
similarity index 100%
rename from packages/twenty-docs/ui/components/typography/text.mdx
rename to packages/twenty-docs/ui/primitives/typography/text.mdx
diff --git a/packages/twenty-shared/src/constants/DocumentationPaths.ts b/packages/twenty-shared/src/constants/DocumentationPaths.ts
index c0641763af5..a12a7952ee6 100644
--- a/packages/twenty-shared/src/constants/DocumentationPaths.ts
+++ b/packages/twenty-shared/src/constants/DocumentationPaths.ts
@@ -128,29 +128,31 @@ export const DOCUMENTATION_PATHS = {
GETTING_STARTED_KEY_FEATURES: '/getting-started/key-features',
GETTING_STARTED_QUICKSTART: '/getting-started/quickstart',
UI_ACCESSIBILITY: '/ui/accessibility',
- UI_COMPONENTS_DATA_DISPLAY_AVATAR: '/ui/components/data-display/avatar',
- UI_COMPONENTS_DATA_DISPLAY_CHIP: '/ui/components/data-display/chip',
- UI_COMPONENTS_DATA_DISPLAY_STATUS: '/ui/components/data-display/status',
- UI_COMPONENTS_DATA_DISPLAY_TAG: '/ui/components/data-display/tag',
- UI_COMPONENTS_FEEDBACK_TOAST: '/ui/components/feedback/toast',
- UI_COMPONENTS_INPUT_CHECKBOX: '/ui/components/input/checkbox',
- UI_COMPONENTS_INPUT_FIELD: '/ui/components/input/field',
- UI_COMPONENTS_INPUT_INPUT: '/ui/components/input/input',
- UI_COMPONENTS_INPUT_INPUT_GROUP: '/ui/components/input/input-group',
- UI_COMPONENTS_INPUT_RADIO: '/ui/components/input/radio',
- UI_COMPONENTS_INPUT_RADIO_GROUP: '/ui/components/input/radio-group',
- UI_COMPONENTS_INPUT_SELECT: '/ui/components/input/select',
- UI_COMPONENTS_INPUT_SLIDER: '/ui/components/input/slider',
- UI_COMPONENTS_INPUT_SWITCH: '/ui/components/input/switch',
- UI_COMPONENTS_INPUT_TEXTAREA: '/ui/components/input/textarea',
- UI_COMPONENTS_NAVIGATION_LIST_ITEM: '/ui/components/navigation/list-item',
- UI_COMPONENTS_NAVIGATION_TABS: '/ui/components/navigation/tabs',
- UI_COMPONENTS_SURFACES_ALERT_DIALOG: '/ui/components/surfaces/alert-dialog',
- UI_COMPONENTS_SURFACES_MENU: '/ui/components/surfaces/menu',
- UI_COMPONENTS_SURFACES_POPOVER: '/ui/components/surfaces/popover',
- UI_COMPONENTS_TYPOGRAPHY_TEXT: '/ui/components/typography/text',
+ UI_COMPONENTS_OVERVIEW: '/ui/components/overview',
UI_DARK_MODE: '/ui/dark-mode',
UI_GETTING_STARTED: '/ui/getting-started',
+ UI_PRIMITIVES_DATA_DISPLAY_AVATAR: '/ui/primitives/data-display/avatar',
+ UI_PRIMITIVES_DATA_DISPLAY_CHIP: '/ui/primitives/data-display/chip',
+ UI_PRIMITIVES_DATA_DISPLAY_STATUS: '/ui/primitives/data-display/status',
+ UI_PRIMITIVES_DATA_DISPLAY_TAG: '/ui/primitives/data-display/tag',
+ UI_PRIMITIVES_FEEDBACK_TOAST: '/ui/primitives/feedback/toast',
+ UI_PRIMITIVES_INPUT_CHECKBOX: '/ui/primitives/input/checkbox',
+ UI_PRIMITIVES_INPUT_FIELD: '/ui/primitives/input/field',
+ UI_PRIMITIVES_INPUT_INPUT: '/ui/primitives/input/input',
+ UI_PRIMITIVES_INPUT_INPUT_GROUP: '/ui/primitives/input/input-group',
+ UI_PRIMITIVES_INPUT_RADIO: '/ui/primitives/input/radio',
+ UI_PRIMITIVES_INPUT_RADIO_GROUP: '/ui/primitives/input/radio-group',
+ UI_PRIMITIVES_INPUT_SELECT: '/ui/primitives/input/select',
+ UI_PRIMITIVES_INPUT_SLIDER: '/ui/primitives/input/slider',
+ UI_PRIMITIVES_INPUT_SWITCH: '/ui/primitives/input/switch',
+ UI_PRIMITIVES_INPUT_TEXTAREA: '/ui/primitives/input/textarea',
+ UI_PRIMITIVES_NAVIGATION_LIST_ITEM: '/ui/primitives/navigation/list-item',
+ UI_PRIMITIVES_NAVIGATION_TABS: '/ui/primitives/navigation/tabs',
+ UI_PRIMITIVES_OVERVIEW: '/ui/primitives/overview',
+ UI_PRIMITIVES_SURFACES_ALERT_DIALOG: '/ui/primitives/surfaces/alert-dialog',
+ UI_PRIMITIVES_SURFACES_MENU: '/ui/primitives/surfaces/menu',
+ UI_PRIMITIVES_SURFACES_POPOVER: '/ui/primitives/surfaces/popover',
+ UI_PRIMITIVES_TYPOGRAPHY_TEXT: '/ui/primitives/typography/text',
UI_SSR: '/ui/ssr',
UI_THEMING: '/ui/theming',
UI_TOKENS: '/ui/tokens',