Skip to content

The open alternative to Salesforce, designed for AI.

Use Twenty UI by default in app agent guidance (#28419)

Raphaël Bosicc92b7773ec3
diff --git a/packages/create-twenty-app/src/constants/template/AGENTS.md b/packages/create-twenty-app/src/constants/template/AGENTS.md
index 94bf1d31580..3c41037aa36 100644
--- a/packages/create-twenty-app/src/constants/template/AGENTS.md
+++ b/packages/create-twenty-app/src/constants/template/AGENTS.md
@@ -118,10 +118,17 @@ The table below lists what `dev:add` can generate.
### Front components
- The file is `.tsx` and ends with `export default defineFrontComponent({ ... })` in exactly that shape; the build rewrites it.
-- Components run in a Web Worker with a sandboxed, partial `window` and `document`: DOM queries, measurements and `matchMedia` work, but `ResizeObserver`, `canvas`, `scrollIntoView` and portals into `document.body` do not, and most unsupported calls fail silently. Base layout on width, never on height. Import UI from `twenty-ui` subpaths and never `IconsProvider` or `useIcons`.
+- For every visible front component, follow the `develop-app` skill when installed and use `twenty-ui` components by default. Reuse an equivalent Twenty UI control before writing a custom control or adding another UI library. Plain HTML is appropriate for layout containers and content without a Twenty UI equivalent.
+- Import from public family subpaths: `twenty-ui/components/input` for `MainButton` and `LightButton`, `twenty-ui/primitives/input` for foundational controls, `twenty-ui/primitives/typography` for text, and the matching family for other components. Import individual icons from `twenty-ui/icon`, never `IconsProvider` or `useIcons`. Keep `twenty-ui`, `twenty-sdk` and `twenty-client-sdk` pinned to the same version in `devDependencies`.
+- The renderer supplies styles and the workspace theme. Use `useTheme()` from `twenty-ui/theme` inside the component for spacing, colors, typography and radii. Do not add a root `ThemeProvider`, force a color scheme, or copy standalone stylesheet setup into a front component. Never dereference theme tokens at module top level, since entity files also run during manifest extraction.
+- Use component props before custom styles. Keep layouts compact and responsive to widget width, give inputs visible labels and icon-only actions accessible names, and handle loading, empty, error, disabled and saving states. Verify light and dark themes, narrow widths and long values.
+- Use `openCommandConfirmationModal` or `CommandModal` from `twenty-sdk/front-component` for confirmation dialogs and `enqueueSnackbar` for notifications. Do not render `Dialog`, `AlertDialog`, native `dialog` elements or native browser popovers directly. Use Twenty UI `Dropdown` for menus and pickers.
+- Components run in a Web Worker with a sandboxed, partial `window` and `document`. Prefer CSS for layout and width-based queries. `canvas` and `scrollIntoView` are unsupported; consult the current runtime limitations before using other browser APIs.
- Read workspace data with `CoreApiClient` from `twenty-client-sdk/core`. Call third-party APIs from a logic function, not from the component. Secret application variables never reach a front component.
- `useRecordId()` is deprecated; use `useSelectedRecordIds()` from `twenty-sdk/front-component`.
+Read the [front component guide](https://docs.twenty.com/developers/extend/apps/layout/front-components.md) before implementation for the renderer setup and runtime limitations. Use [Twenty UI getting started](https://docs.twenty.com/ui/getting-started.md), [components](https://docs.twenty.com/ui/components/overview.md), [primitives](https://docs.twenty.com/ui/primitives/overview.md) and [theming](https://docs.twenty.com/ui/theming.md) to find the relevant component page and check its current props and composition.
+
### Logic functions
- The handler is `(payload, context)`. The payload shape follows the trigger: `RoutePayload` for HTTP routes, `DatabaseEventPayload` (or the batch variant, up to 200 events) for database events, `{}` for cron, `{ previousVersion?, newVersion }` for install hooks.
diff --git a/packages/twenty-agent-skills/CHANGELOG.md b/packages/twenty-agent-skills/CHANGELOG.md
index 0dc05bde739..130640a2485 100644
--- a/packages/twenty-agent-skills/CHANGELOG.md
+++ b/packages/twenty-agent-skills/CHANGELOG.md
@@ -10,6 +10,7 @@ Entries reference the canonical skills (`create-app`, `develop-app`, `manage-app
### Changed
+- Made Twenty UI the default for visible front components in `develop-app` and both app bootstrap instruction files, with essential renderer rules and links to current component APIs.
- Consolidated canonical skills, shared references, and Codex metadata into `packages/twenty-agent-skills`, replacing the separate source and generated packages. The Codex plugin identifier remains `twenty`.
- Build one distribution in ignored `dist/` for both the `skills` CLI and Codex. Individual skills contain their required references; only the publishing branch contains generated copies.
- Publish the built distribution at the root of the `agent-skills` branch from `main`. Installation instructions use that branch and explain local installation before the first publish.
diff --git a/packages/twenty-agent-skills/references/design/front-component-ui.md b/packages/twenty-agent-skills/references/design/front-component-ui.md
index a4a4ae7f906..9e7f92f7372 100644
--- a/packages/twenty-agent-skills/references/design/front-component-ui.md
+++ b/packages/twenty-agent-skills/references/design/front-component-ui.md
@@ -1,464 +1,113 @@
# When to Use
-Use this when the user wants to design or polish a Twenty front component UI.
-
-Examples:
-
-- Make a front component look better.
-- Create a clean layout for a front component.
-- Improve loading, empty, error, or disabled states.
-- Make a front component responsive and easier to scan.
+Use this reference when creating, designing, or polishing a Twenty front component UI, including its layout, controls, responsive behavior, and visible states.
# Boundaries
Do not scaffold a new app here. Use `create-app` first when the app does not exist.
-Do not use this reference for source files, registration, runtime imports, data access, CLI commands, or browser verification.
+Do not use this reference for source files, registration, runtime imports, data access, CLI commands, or browser verification. Those rules live in `../develop-app/front-components.md`. Use `../develop-app/layout.md` for placement and `../develop-app/standalone-pages.md` for full-page UI.
# Design Rules
-Design front components as compact CRM product UI, not marketing pages. The goal is a surface that scans quickly, feels native inside Twenty, and keeps actions predictable.
-
-Use Figma measurements as evidence for the current Twenty rhythm, not as implementation literals. Source code should use Twenty primitives, component props, and `themeCssVariables` instead of hardcoded visual values.
-
-## Twenty UI Defaults
-
-Prefer Twenty UI primitives for CRM-native front component UI:
-
-- Use `Dialog.Title` from `twenty-ui/primitives/surfaces` inside `Modal` for its visible title and accessible name.
-- Use `Heading` from `twenty-ui/primitives/typography` for compact headings, or `Section.Header` from `twenty-ui/components` for a heading with a description or action.
-- Use `Callout` with a matching icon for loading, empty, error, and blocked states.
-- Use `Button` for primary and secondary actions.
-- Use `Tag`, `Status`, `Chip`, `Label`, and `Avatar` for metadata, state, people, and small summaries.
-- Use `themeCssVariables` for spacing, colors, border radius, typography, borders, icon sizing, shadows, and backgrounds.
-
-Use local inline styles for layout containers and custom data displays, but keep them aligned with Twenty tokens. Use `../develop-app/front-components.md` for exact imports and runtime rules.
-
-Use Twenty UI icons before custom SVG. Use `themeCssVariables.icon.size.md` for default row and action icons, `themeCssVariables.icon.size.sm` for quiet chevrons, and `themeCssVariables.spacing[6]` for icon-only action targets.
-
-## Dropdowns
-
-Use `Dropdown` from `twenty-ui/components` for action menus, searchable pickers, and compact editor panels. Compose `Dropdown.Root`, `Dropdown.Trigger`, and `Dropdown.Content`; render a Twenty `Button` through the trigger's `render` prop and give the content an accessible label.
-
-Choose the root's `type` for the interaction:
-
-- `type="menu"`: use `Dropdown.ActionItem` for commands and `Dropdown.OptionItem` for selectable settings.
-- `type="picker"`: combine `Dropdown.Search` with `Dropdown.OptionItem`. Own the search and selection state in the component, filter the displayed options, and pass each option's `selected` and `onSelect` props. Set `multiple` on the root for multiple selections that keep the picker open.
-- `type="panel"`: compose form controls inside the content, with normal Tab navigation.
-
-Group rows with `Dropdown.Section` and `Dropdown.Separator`. Use `Dropdown.Loading` and `Dropdown.Empty` for loading and empty results. For navigation within the same popup, use `Dropdown.Page` with an `id`, an action item's matching `page` prop, and `Dropdown.Back`; a page can override `type`. For a nested popup, compose `Dropdown.Submenu`, `Dropdown.SubmenuTrigger`, and `Dropdown.Content`.
-
-## Token-First Implementation
-
-When turning a Figma observation into code, translate the visual target into a token:
-
-- Typography uses `themeCssVariables.font.size.*`, `themeCssVariables.font.weight.*`, and `themeCssVariables.text.lineHeight.*`.
-- Spacing uses `themeCssVariables.spacing[...]` and `themeCssVariables.betweenSiblingsGap`.
-- Radius uses `themeCssVariables.border.radius.sm` for compact controls and `themeCssVariables.border.radius.md` for cards or panels.
-- Colors use `themeCssVariables.font.color.*`, `themeCssVariables.background.*`, `themeCssVariables.border.color.*`, or component props.
-- Icons use `themeCssVariables.icon.size.*` or native Twenty UI icon sizing.
-- Borders use `themeCssVariables.border.color.*`; avoid raw border colors.
-- Shadows use `themeCssVariables.boxShadow.*`; avoid custom shadow stacks unless mirroring an existing Twenty overlay exactly.
-
-Do not create source constants named after raw visual measurements. Use semantic names that point to tokens:
-
-```tsx
-const compactControlHeight = themeCssVariables.spacing[6];
-const denseRowHeight = themeCssVariables.spacing[8];
-const panelRadius = themeCssVariables.border.radius.md;
-```
-
-Avoid source constants named after raw measurements, such as `rowHeight` or `cardRadius`, when they hide a token choice. Prefer semantic names like `denseRowHeight` and `panelRadius`.
-
-## Base Scale
-
-Use the same small scale across the whole component:
-
-- Body text: `themeCssVariables.font.size.md`, regular weight, medium line height.
-- Section titles and row titles: `themeCssVariables.font.size.md`, medium weight, medium line height.
-- Descriptions and helper text: `themeCssVariables.font.size.sm`, regular weight, medium line height.
-- Metadata labels and table headers: medium body text with `themeCssVariables.font.color.tertiary`.
-- Compact controls: use Twenty `Button` sizing or `themeCssVariables.spacing[6]` for custom control height.
-- Navigation and menu rows: use the native component when available; otherwise use the nearest theme spacing token that matches the host row rhythm.
-- Dense table, list, and input-like rows: use `themeCssVariables.spacing[8]` for custom row height.
-- Toolbars and view bars: use `themeCssVariables.spacing[10]` for custom toolbar height.
-
-Do not increase type size to create hierarchy inside compact widgets. Use weight, color, alignment, spacing, and order first.
-
-Applied example:
-
-```tsx
-const titleStyle = {
- fontSize: themeCssVariables.font.size.md,
- fontWeight: themeCssVariables.font.weight.medium,
- lineHeight: themeCssVariables.text.lineHeight.md,
- letterSpacing: 0,
- color: themeCssVariables.font.color.primary,
-};
-
-const descriptionStyle = {
- fontSize: themeCssVariables.font.size.sm,
- fontWeight: themeCssVariables.font.weight.regular,
- lineHeight: themeCssVariables.text.lineHeight.md,
- letterSpacing: 0,
- color: themeCssVariables.font.color.secondary,
-};
-```
-
-## Radius And Shape
-
-Use a small, consistent radius system:
-
-- Cards, popovers, notification containers, and framed panels use `themeCssVariables.border.radius.md`.
-- Buttons, chips, toolbar controls, menu hover fills, skeletons, and small fields use `themeCssVariables.border.radius.sm`.
-- Checkbox shape and target sizing should come from the native Twenty checkbox pattern when available.
-- Do not use pill or rounded radius for cards, rows, or toolbar buttons unless the existing Twenty primitive already does.
-- Do not mix several custom radii in one component. Pick the matching Twenty radius token for each element role.
-
-Applied example:
-
-```tsx
-const cardStyle = {
- borderRadius: themeCssVariables.border.radius.md,
- padding: themeCssVariables.spacing[2],
- background: themeCssVariables.background.primary,
-};
-
-const toolbarButtonStyle = {
- minHeight: themeCssVariables.spacing[6],
- padding: `0 ${themeCssVariables.spacing[2]}`,
- borderRadius: themeCssVariables.border.radius.sm,
-};
-```
-
-## Spacing
-
-Use the theme spacing scale instead of raw dimensions:
-
-- `themeCssVariables.betweenSiblingsGap`: tightly grouped toolbar actions or small separators.
-- `themeCssVariables.spacing[1]`: icon-to-label gaps, chip internals, compact row gaps.
-- `themeCssVariables.spacing[2]`: default card padding, row horizontal padding, toolbar padding, title-row gaps.
-- `themeCssVariables.spacing[4]`: section gaps inside larger panels or between unrelated groups.
-- `themeCssVariables.spacing[6]`: left indentation for description text that belongs to a row with a leading icon and label.
-
-Do not jump to large padding inside ordinary CRM controls. If a compact widget starts needing generous whitespace, the layout probably needs fewer sections or better grouping.
-
-Applied example:
-
-```tsx
-const titleRowStyle = {
- display: 'flex',
- alignItems: 'center',
- gap: themeCssVariables.spacing[2],
- minHeight: themeCssVariables.spacing[6],
-};
-
-const descriptionRowStyle = {
- paddingLeft: themeCssVariables.spacing[6],
- paddingBottom: themeCssVariables.spacing[2],
-};
-```
-
-## Information Hierarchy
-
-Make hierarchy visible without making the component loud:
-
-- Put the record, object, or task name first. Use medium body text with primary color.
-- Put the explanation second. Use small regular text with secondary color.
-- Put metadata third. Use `Tag`, `Status`, `Chip`, `Label`, `Avatar`, or tertiary text.
-- Put counters and quiet totals in light text, not primary text.
-- Use one primary action per small surface. Put secondary actions beside it or behind a menu.
-- Use color for state and meaning, not decoration.
-- Keep descriptions aligned under the title text, not under the leading icon.
-- In a card with a leading icon, use a medium icon, a standard spacing gap, then text. The description starts at the same x-position as the title text.
-- In a list or table, reserve the left edge for the most important identifier and keep it stable across every row.
-
-Good hierarchy:
+Design front components as compact CRM product UI. Reuse Twenty UI controls before creating custom equivalents or adding another component library. Use local layout styles for app-specific structure and data displays.
-```tsx
-<div style={{ display: 'grid', gap: themeCssVariables.spacing[1] }}>
- <div
- style={{
- display: 'flex',
- alignItems: 'center',
- gap: themeCssVariables.spacing[2],
- }}
- >
- <Avatar name={ownerName} />
- <span style={titleStyle}>{companyName}</span>
- <Status color="green" text="Active" />
- </div>
- <span style={descriptionStyle}>Renewal due in 12 days</span>
-</div>
-```
-
-Avoid hierarchy that relies on oversized type, all caps, bright backgrounds, or extra padding. That breaks the compact CRM rhythm and makes dense data harder to scan.
-
-## Alignment
+Keep the essentials below in mind, then read the relevant official component page for its current props and composition:
-Twenty UI looks precise because repeated edges line up:
+- [Getting started](https://docs.twenty.com/ui/getting-started): public entry points and library setup. Follow the front component runtime reference for host-provided styling and theme setup.
+- [Components](https://docs.twenty.com/ui/components/overview) and [Primitives](https://docs.twenty.com/ui/primitives/overview): find an existing control and its API.
+- [Theming](https://docs.twenty.com/ui/theming) and [Tokens](https://docs.twenty.com/ui/tokens): semantic styling and token names.
+- [Icons](https://docs.twenty.com/ui/icons): individual icon exports and supported props.
-- Align every custom surface to the theme spacing grid.
-- Use `themeCssVariables.spacing[2]` horizontal padding for compact rows and cards.
-- Use `themeCssVariables.spacing[6]` for icon-only action targets so icons share a stable center.
-- Align row icons, avatars, labels, and actions vertically center.
-- Keep list text left-aligned. Do not center-align row content.
-- Keep toolbar context on the left and actions on the right.
-- Keep repeated rows the same x-position, width, height, and action position.
-- In menus, use a small inset from the menu edge and keep rows full width inside that inset.
-- In tables, use the table theme tokens when available, especially `themeCssVariables.table.horizontalCellPadding`.
-- Do not let a long value push action buttons out of alignment. Truncate text before actions move.
-
-Toolbar pattern:
-
-```tsx
-const toolbarStyle = {
- minHeight: themeCssVariables.spacing[10],
- padding: themeCssVariables.spacing[2],
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'space-between',
- gap: themeCssVariables.spacing[2],
-};
-
-const toolbarActionsStyle = {
- display: 'flex',
- alignItems: 'center',
- gap: themeCssVariables.betweenSiblingsGap,
-};
-```
-
-Table/list row pattern:
-
-```tsx
-const rowStyle = {
- minHeight: themeCssVariables.spacing[8],
- padding: `0 ${themeCssVariables.table.horizontalCellPadding}`,
- display: 'grid',
- gridTemplateColumns: 'minmax(0, 1fr) auto',
- alignItems: 'center',
- columnGap: themeCssVariables.spacing[2],
-};
-
-const cellLabelStyle = {
- overflow: 'hidden',
- textOverflow: 'ellipsis',
- whiteSpace: 'nowrap',
-};
-```
+## Twenty UI Defaults
-## Consistency
+Prefer Twenty UI primitives and shared components for native-looking controls:
-Keep visual decisions repeatable:
+- Use `MainButton` for prominent actions and `LightButton` for lightweight actions, from `twenty-ui/components/input`. Use `Button` from `twenty-ui/primitives/input` when the foundational control is sufficient.
+- Use `Field`, `Input`, `Select`, `Checkbox`, and other controls from `twenty-ui/primitives/input` for forms. Compose their documented parts rather than recreating labels, selection, and focus behavior.
+- Use `Heading` and `Text` from `twenty-ui/primitives/typography`, or `Section.Header` from `twenty-ui/components/layout` for a heading with a description or action.
+- Use `Tag`, `Status`, `Chip`, and `Avatar` from `twenty-ui/primitives/data-display` for metadata, state, people, and small summaries.
+- Use `Callout` from `twenty-ui/components/feedback` for explanatory loading, empty, error, and blocked states; use a loader or progress primitive when progress alone is enough.
+- Use individual icons from `twenty-ui/icon`. Follow Twenty's established icon for the product concept before creating custom SVG.
+- Use the host confirmation dialog for confirmation actions. Keep forms inline or in a side panel; follow `../develop-app/front-components.md` for supported overlay APIs.
-- Use the same row height token for every row in the same list.
-- Use the same action placement in loading, empty, error, and ready states.
-- Use the same radius token for the same kind of element everywhere in the component.
-- Use the same icon size token for the same role.
-- Use the same label for the same action everywhere. Do not mix "Open", "View", and "See record" for one action.
-- Use the same empty-state structure across related components: icon, short title, one sentence, one action.
-- Use the same loading skeleton geometry as the final content. Do not replace compact rows with centered spinners unless the whole panel is blocked.
-- Use Twenty tokens for color and spacing. Use raw values only for semantic data visualization that cannot be represented by existing tokens.
+## Menus And Pickers
-State backgrounds should follow the existing Twenty pattern:
+Use `Dropdown` from `twenty-ui/components/navigation` for action menus, searchable pickers, and compact form panels. Compose `Dropdown.Root`, `Dropdown.Trigger`, and `Dropdown.Content`; provide a Twenty button through the trigger's `render` prop and give the content an accessible label.
-- Default: transparent or `themeCssVariables.background.primary`.
-- Hover: `themeCssVariables.background.transparent.light` or `themeCssVariables.background.secondary`.
-- Pressed/clicked: `themeCssVariables.background.tertiary`.
-- Selected: same shape and height as the default row, with selected color treatment from the nearest Twenty primitive.
-- Disabled: same layout, lower contrast, no new decorative color.
-- Loading: same dimensions as ready content, with skeleton blocks using the compact radius token.
+Choose the root's `type` for its interaction:
-## Cards And Panels
+- `menu`: `Dropdown.ActionItem` for commands and `Dropdown.OptionItem` for selectable settings.
+- `picker`: `Dropdown.Search` and `Dropdown.OptionItem`, with application-owned search and selection state. Set `multiple` on the root when selections should keep the picker open.
+- `panel`: form controls with normal Tab navigation.
-Use cards only for individual repeated items, notifications, popovers, or genuinely framed tools. Do not put cards inside cards.
+Use `Dropdown.Loading`, `Dropdown.Empty`, sections, and separators before building custom equivalents. Read the [Dropdown documentation](https://docs.twenty.com/ui/components/navigation/dropdown) for nested pages and submenus.
-Card defaults:
+## Semantic Tokens
-- Radius: `themeCssVariables.border.radius.md`.
-- Padding: `themeCssVariables.spacing[2]` for compact cards.
-- Title-to-body gap: `themeCssVariables.spacing[2]` only when the body is visually separate.
-- Divider: `themeCssVariables.border.color.light` when sections need separation.
-- Shadow: prefer `themeCssVariables.boxShadow.light` or the native host surface treatment. Do not combine a strong border with a strong shadow.
+Use `themeCssVariables` for styles instead of copying visual measurements from a screenshot or Figma. Prefer semantic paths such as `font.color.primary`, `background.secondary`, `border.color.light`, `border.radius.md`, and `spacing[...]` so the UI follows the workspace palette and scale.
-Overlay feedback pattern:
+Read tokens inside the component body. The style declarations below belong inside render-time code, following `../develop-app/front-components.md`; do not evaluate token-based styles at module scope.
```tsx
-const overlayFeedbackStyle = {
- borderRadius: themeCssVariables.border.radius.md,
- padding: `${themeCssVariables.spacing[2]} ${themeCssVariables.spacing[2]} ${themeCssVariables.spacing[1]}`,
- display: 'flex',
- flexDirection: 'column',
- gap: themeCssVariables.spacing[1],
- background: themeCssVariables.background.overlayPrimary,
- backdropFilter: `blur(${themeCssVariables.blur.medium})`,
- boxShadow: themeCssVariables.boxShadow.strong,
-};
-```
-
-Use overlay styling for small feedback surfaces only. Normal embedded widgets should usually use the host background, a subtle border, or no frame.
+import { LightButton } from 'twenty-ui/components/input';
+import { Section } from 'twenty-ui/components/layout';
+import { themeCssVariables } from 'twenty-ui/theme';
-## Buttons And Actions
-
-Use actions that feel like Twenty toolbar controls:
-
-- Use `Button` for actual commands.
-- Use Twenty button `size` and `variant` props before custom button styling.
-- For custom compact controls, use `themeCssVariables.spacing[6]` as the control height token.
-- Use `themeCssVariables.spacing[2]` for horizontal padding.
-- Use `themeCssVariables.spacing[1]` for icon-label gaps.
-- Use `themeCssVariables.border.radius.sm` for custom compact action radius.
-- Use medium body text for labels.
-- Use medium icons for primary actions and small icons for quiet chevrons.
-- Use `themeCssVariables.spacing[6]` for icon-only action targets.
-
-Applied example:
-
-```tsx
-<div
- style={{
+const ActivitySummary = ({ onRefresh }: { onRefresh: () => void }) => {
+ const containerStyle = {
display: 'flex',
- alignItems: 'center',
- gap: themeCssVariables.betweenSiblingsGap,
- }}
->
- <Button variant="secondary" size="small" title="Open record" />
- <Button variant="secondary" size="small" title="Add note" />
-</div>
-```
-
-## Tables And Dense Lists
-
-Use table-like rhythm for CRM data:
-
-- Header and row height: use `themeCssVariables.spacing[8]` for custom dense rows.
-- Header text: medium body text with tertiary color.
-- Cell text: regular body text with primary or secondary color.
-- Cell padding: use `themeCssVariables.table.horizontalCellPadding`.
-- Icon-label gap: use `themeCssVariables.spacing[1]`.
-- Checkbox column: use `themeCssVariables.table.checkboxColumnWidth` when building table-like custom rows.
-- First data column: make it the flexible `minmax(0, 1fr)` column so names get priority and actions stay aligned.
-- Truncate long names with ellipsis. Do not wrap names in dense rows unless the row is intentionally two-line.
-
-Applied example:
-
-```tsx
-const headerCellStyle = {
- minHeight: themeCssVariables.spacing[8],
- padding: `0 ${themeCssVariables.table.horizontalCellPadding}`,
- display: 'flex',
- alignItems: 'center',
- gap: themeCssVariables.spacing[1],
- fontSize: themeCssVariables.font.size.md,
- fontWeight: themeCssVariables.font.weight.medium,
- color: themeCssVariables.font.color.tertiary,
+ flexDirection: 'column' as const,
+ gap: themeCssVariables.spacing[2],
+ padding: themeCssVariables.spacing[2],
+ background: themeCssVariables.background.secondary,
+ color: themeCssVariables.font.color.primary,
+ borderRadius: themeCssVariables.border.radius.md,
+ };
+
+ return (
+ <section style={containerStyle}>
+ <Section.Header title="Activity" description="Recent record changes" />
+ <LightButton size="sm" onClick={onRefresh}>
+ Refresh
+ </LightButton>
+ </section>
+ );
};
```
-## Empty, Loading, Error, Disabled, Success
-
-Design the visible states before polishing the ready state:
-
-- Loading: preserve final layout dimensions with skeletons that use the same row, text, and radius tokens as the ready content.
-- Empty: use `Callout` or a compact empty block with one short title, one sentence, and one clear action.
-- Error: use `Callout` with an error icon, explain what failed, and offer retry or recovery.
-- Disabled: keep the same control size and placement. Lower contrast and explain the blocking condition if it is not obvious.
-- Success: use a small status, toast-style card, or inline confirmation. Do not redesign the whole panel for success.
+Every `themeCssVariables` value is a CSS reference string. Do not perform arithmetic on it. Use numeric tokens from `useTheme()` when a component prop expects a number, such as an icon's `size`.
-Loading example:
+Prefer component `size`, `variant`, and color props before overriding their styles. Keep custom spacing, radii, borders, and typography consistent with nearby Twenty UI controls. Avoid adding a heavy card frame or shadow when the host already provides the surface.
-```tsx
-const skeletonStyle = {
- height: themeCssVariables.spacing[4],
- width: '60%',
- borderRadius: themeCssVariables.border.radius.sm,
- background: themeCssVariables.background.transparent.light,
-};
-```
-
-Empty example:
-
-```tsx
-<Callout
- status="neutral"
- title="No activity yet"
- description="Activity will appear here once this record has timeline events."
-/>
-```
+## Compact Responsive Layouts
-## Text And Copy
+Design for a narrow widget first. Use a single column by default and let data columns shrink with `minmax(0, 1fr)` and `minWidth: 0`. Keep the primary action visible and move secondary actions into a menu when space is tight.
-Make text fit in real Twenty widths:
+Align repeated rows, labels, icons, and actions. Use consistent row height, padding, and gaps. Truncate long names, emails, and URLs before they overlap an action; preserve access to the full value when it matters.
-- Use sentence case.
-- Use short labels.
-- Use short button text.
-- Use one-sentence descriptions.
-- Put dynamic values in stable containers with ellipsis.
-- Never let a record name, email, URL, or amount overlap an action.
-- Prefer exact object names over generic labels. Use "Open company", not "Open item", when the object is known.
-- Keep units and counts close to the value: `12 opportunities`, `$4,200`, `3 tasks`.
+Use weight, color, spacing, and order for hierarchy before increasing text size. Prefer compact headings and sentence case. Keep units and counts beside their values and use specific action labels such as "Open company".
-Text truncation pattern:
+## Visible States And Accessibility
-```tsx
-const truncateStyle = {
- minWidth: 0,
- overflow: 'hidden',
- textOverflow: 'ellipsis',
- whiteSpace: 'nowrap',
-};
-```
-
-## Responsive Rules
-
-Front components often render in narrow widgets:
+Design the visible states before polishing the ready state:
-- Design compact widths first.
-- Use a single column by default.
-- Move secondary actions into a menu before wrapping the whole toolbar.
-- Keep the primary action visible when space is tight.
-- Let content columns shrink with `minmax(0, 1fr)`.
-- Use ellipsis for long identifiers instead of horizontal scroll in small widgets.
-- Do not use hero-scale text, marketing sections, or wide decorative imagery in embedded CRM widgets.
+- Loading: preserve the content's layout with a loader or skeleton; prevent duplicate submissions while saving.
+- Empty: explain what is missing and provide a useful next action when one exists.
+- Error: explain what failed and offer retry or recovery.
+- Disabled: keep the control's placement and explain a non-obvious blocking condition.
+- Success: use a small status or inline confirmation without replacing the whole panel.
-Narrow layout pattern:
+Give inputs visible labels with `Field.Label` and associate help and errors through the component's documented composition. Put visible action text in button children; `title` alone does not provide a visible label. Give icon-only actions an `aria-label` and hide decorative icons from assistive technology.
-```tsx
-const compactGridStyle = {
- display: 'grid',
- gridTemplateColumns: 'minmax(0, 1fr) auto',
- alignItems: 'center',
- gap: themeCssVariables.spacing[2],
-};
-```
+Preserve keyboard navigation, focus handling, and accessible names when composing triggers. Prefer the library's interaction behavior over hand-written clickable containers.
## Quick Checks
-Before considering a UI done, check this list:
-
-- The component uses Twenty typography tokens, not custom text sizes.
-- Cards use the medium radius token or a smaller existing primitive radius.
-- Buttons and action controls use Twenty `Button` props or compact spacing tokens.
-- Table/list rows use a consistent row-height token.
-- Icons use `themeCssVariables.icon.size.*` or native Twenty icon sizing.
-- Spacing uses `themeCssVariables.spacing[...]` and `themeCssVariables.betweenSiblingsGap`.
-- Ready, loading, empty, error, and disabled states share the same structure.
-- Important text has a stable left edge and truncates before it overlaps actions.
-- Repeated rows have identical height, padding, icon size, action placement, and state behavior.
-- The UI uses Twenty primitives and `themeCssVariables` before custom styling.
-
-# Workflow
-
-First, identify the target front component file and the user workflow it supports.
-
-Design the visible states the user will naturally encounter: loading, empty, error, disabled, success, and the primary working state.
-
-Then apply the rules in this order:
+Before handing off to the runtime verification in `../develop-app/front-components.md`, check:
-1. Set the information hierarchy: title, description, metadata, actions.
-2. Lock the structural dimensions with Twenty primitives and `themeCssVariables`.
-3. Align repeated edges and action positions.
-4. Apply Twenty primitives and tokens.
-5. Add hover, pressed, selected, loading, disabled, empty, error, and success states.
-6. Test with long names, empty values, narrow widths, and multiple records.
+- Equivalent Twenty UI controls are reused and their public family entry points are used.
+- Tokens and component props provide consistent spacing, typography, colors, and radii in light and dark themes.
+- Long values, empty values, narrow widths, and multiple records keep actions reachable.
+- Ready, loading, empty, error, disabled, and saving states are understandable.
+- Inputs have labels, icon-only actions have accessible names, and keyboard users can reach each action.
diff --git a/packages/twenty-agent-skills/references/develop-app/front-components.md b/packages/twenty-agent-skills/references/develop-app/front-components.md
index d82b100ce6e..74f2da48b2b 100644
--- a/packages/twenty-agent-skills/references/develop-app/front-components.md
+++ b/packages/twenty-agent-skills/references/develop-app/front-components.md
@@ -4,6 +4,12 @@ Use this reference for Twenty app front component source files, registration, da
Use `layout.md` for placing a front component in a page layout. Use `standalone-pages.md` for full-page custom UI rendered through a front component widget. Use `../design/front-component-ui.md` for visual design, spacing, states, and polish. Use `app-structure.md` for the develop-app validation checklist and `../manage-app/cli-and-sync.md` for command behavior or troubleshooting.
+## Documentation
+
+Use these instructions for essential app defaults and the official docs for detailed APIs. Start with the [front component guide](https://docs.twenty.com/developers/extend/apps/layout/front-components.md) for app-specific setup and runtime limitations. [Twenty UI getting started](https://docs.twenty.com/ui/getting-started.md) describes the library; its standalone React setup does not apply inside a front component.
+
+Find the relevant component page through the [components](https://docs.twenty.com/ui/components/overview.md) or [primitives](https://docs.twenty.com/ui/primitives/overview.md) index, then read its current props and composition before implementation. Use [theming](https://docs.twenty.com/ui/theming.md) for semantic tokens. When the app pins an older version, check its installed public types before using an API from the latest docs.
+
## Source And Registration
By convention, keep front components under `src/front-components/`, often as `<name>.front-component.tsx`.
@@ -37,14 +43,24 @@ Keep imports narrow:
- Use `twenty-client-sdk/core` or `twenty-client-sdk/metadata` for data access.
- Install `twenty-ui` from npm at the same version as `twenty-sdk` and `twenty-client-sdk` and import Twenty UI components, icons, and theme tokens from its subpaths (`twenty-ui/primitives/input`, `twenty-ui/primitives/data-display`, `twenty-ui/icon`, `twenty-ui/primitives/typography`, `twenty-ui/theme`, and others) before adding external UI libraries.
-The front component renderer provides a Twenty `ThemeProvider` around the remote root. For isolated examples or local story-style verification, wrapping the component in `ThemeProvider` from `twenty-ui/theme` is also acceptable.
+Keep the SDK packages and `twenty-ui` in `devDependencies`. Import shared components from their family entry point, such as `twenty-ui/components/input` for `MainButton` and `LightButton`, `twenty-ui/components/feedback` for `Callout`, `twenty-ui/components/layout` for `Section`, and `twenty-ui/components/navigation` for `Dropdown`. Use `twenty-ui/primitives/input` for foundational controls such as `Button`, `Field` and `Input`.
+
+The front component renderer provides the styles and a Twenty `ThemeProvider` around the remote root. In the app, inherit the workspace color scheme without adding another root provider, forcing light or dark mode, or importing the standalone stylesheets. For isolated examples or local story-style verification, wrapping the component in `ThemeProvider` from `twenty-ui/theme` is also acceptable.
-The canonical Twenty UI front component example is `packages/twenty-front-component-renderer/src/__stories__/showcase/twenty-ui-example.front-component.tsx`. It imports `Button` from `twenty-ui/primitives/input`; `Chip`, `Status`, and `Tag` from `twenty-ui/primitives/data-display`; `Section` from `twenty-ui/components`; and `ThemeProvider` from `twenty-ui/theme`.
+The canonical Twenty UI front component example is `packages/twenty-front-component-renderer/src/__stories__/showcase/twenty-ui-example.front-component.tsx`. It imports `Button` from `twenty-ui/primitives/input`; `Chip`, `Status`, and `Tag` from `twenty-ui/primitives/data-display`; `Section` from `twenty-ui/components/layout`; and `ThemeProvider` from `twenty-ui/theme`. Its explicit provider is for the isolated showcase.
Read theme tokens with the `useTheme()` hook from `twenty-ui/theme` inside the component body. The same tokens are also exported as the `themeCssVariables` constant, but the SDK mocks `twenty-ui` during manifest extraction, so a module-level constant that dereferences `themeCssVariables` can fail before the component renders — prefer `useTheme()`.
Prefer Twenty UI icons from `twenty-ui/icon` when one exists. Use inline SVG only for app-specific marks or icons that are not available from `twenty-ui/icon`.
+Import individual icons, not `IconsProvider` or `useIcons`, which bundle the dynamic icon catalog. Use `themeCssVariables` only for CSS values inside render-time code; its values are CSS reference strings, so do not perform arithmetic on them. Use `useTheme()` when a prop needs a resolved value.
+
+## Host UI And Runtime Constraints
+
+Use `openCommandConfirmationModal` from `twenty-sdk/front-component` for confirmation dialogs, or `CommandModal` for a headless confirmation action. Use `enqueueSnackbar` for notifications. Do not render Twenty UI `Dialog` or `AlertDialog`, native `dialog` elements or native browser popovers directly. Use Twenty UI `Dropdown` for menus, pickers and nonmodal form panels.
+
+The component runs in a Web Worker with a partial DOM. Prefer CSS flexbox, grid and width-based container queries for layout. Avoid height-based breakpoints, which can oscillate when content determines widget height. `canvas`, `scrollIntoView` and native top-layer APIs are unsupported. Check the current limitations in the front component guide before depending on other browser APIs.
+
## Record Context And Data
For record-page components, read selection from front component context:
@@ -122,5 +138,7 @@ A clean typecheck and sync is not runtime verification. After the standard valid
- The widget mounts without a `FrontComponent error` in the widget body or toast.
- The component renders loading, empty, and error states correctly.
+- The UI works in both workspace color schemes, at narrow widget widths and with long text values.
+- Inputs have visible labels, icon-only actions have accessible names, and the main controls work with a keyboard.
- The main user action works against a real record.
- The page still renders after a hard refresh.
diff --git a/packages/twenty-agent-skills/references/develop-app/standalone-pages.md b/packages/twenty-agent-skills/references/develop-app/standalone-pages.md
index e63709fd701..b08388934bb 100644
--- a/packages/twenty-agent-skills/references/develop-app/standalone-pages.md
+++ b/packages/twenty-agent-skills/references/develop-app/standalone-pages.md
@@ -60,6 +60,8 @@ export const MISSION_CONTROL_PAGE_LAYOUT_UNIVERSAL_IDENTIFIER =
```tsx src/front-components/mission-control.front-component.tsx
import { defineFrontComponent } from 'twenty-sdk/define';
+import { Heading } from 'twenty-ui/primitives/typography';
+import { themeCssVariables } from 'twenty-ui/theme';
import {
MISSION_CONTROL_FRONT_COMPONENT_UNIVERSAL_IDENTIFIER,
@@ -72,12 +74,12 @@ const MissionControl = () => {
boxSizing: 'border-box',
display: 'grid',
minHeight: '100%',
- padding: 24,
+ padding: themeCssVariables.spacing[4],
placeItems: 'center',
width: '100%',
}}
>
- <h1 style={{ margin: 0 }}>Mission Control</h1>
+ <Heading level={1}>Mission Control</Heading>
</main>
);
};
@@ -157,42 +159,55 @@ Use a `VERTICAL_LIST` tab and give its single widget `TAB_VIEWPORT` height behav
After the tiny page renders, replace the component body with a full-screen structure:
```tsx
+import { LightButton } from 'twenty-ui/components/input';
+import { Section } from 'twenty-ui/components/layout';
+import { Text } from 'twenty-ui/primitives/typography';
+import { themeCssVariables } from 'twenty-ui/theme';
+
const MissionControl = () => {
return (
<main
style={{
boxSizing: 'border-box',
display: 'grid',
- gap: 16,
+ gap: themeCssVariables.spacing[4],
gridTemplateRows: 'auto minmax(0, 1fr)',
height: '100%',
minHeight: '100%',
overflow: 'hidden',
- padding: 16,
+ padding: themeCssVariables.spacing[4],
width: '100%',
}}
>
- <header style={{ display: 'flex', justifyContent: 'space-between' }}>
- <h1 style={{ margin: 0 }}>Mission Control</h1>
- <button type="button">Refresh</button>
- </header>
+ <Section.Header
+ level={1}
+ title="Mission Control"
+ actions={<LightButton>Refresh</LightButton>}
+ />
<section
style={{
display: 'grid',
- gridTemplateColumns: '280px minmax(0, 1fr)',
+ gridTemplateColumns: 'minmax(0, 1fr) minmax(0, 3fr)',
+ gap: themeCssVariables.spacing[4],
minHeight: 0,
overflow: 'hidden',
}}
>
- <aside style={{ minHeight: 0, overflow: 'auto' }}>Filters</aside>
- <div style={{ minHeight: 0, overflow: 'auto' }}>Workspace data</div>
+ <aside style={{ minHeight: 0, overflow: 'auto' }}>
+ <Text>Filters</Text>
+ </aside>
+ <div style={{ minHeight: 0, overflow: 'auto' }}>
+ <Text>Workspace data</Text>
+ </div>
</section>
</main>
);
};
```
+Connect Refresh to the page's data-loading action using `front-components.md`.
+
## API Reference
This section only calls out the fields that matter for standalone pages. Use `layout.md` and `front-components.md` for broader entity guidance.
@@ -253,104 +268,32 @@ Avoid hidden overflow traps. `overflow: 'hidden'` is useful for map and canvas r
## Data And Interactivity
-Fetch live workspace records from the front component when the page reflects workspace state:
+Use `front-components.md` for fetching live workspace records, client APIs, hooks, and runtime behavior. A standalone page adds full-page loading, empty, and error states, plus navigation from its surface back into Twenty records.
-Use `front-components.md` for general client/runtime rules. In standalone pages, the key additions are visible full-page loading, empty, and error states, plus navigation from the standalone surface back into Twenty records.
+Keep a record action focused on its destination and use a Twenty UI control:
```tsx
-import { useEffect, useState } from 'react';
-import { CoreApiClient, type CoreSchema } from 'twenty-client-sdk/core';
-import { defineFrontComponent } from 'twenty-sdk/define';
-import {
- AppPath,
- enqueueSnackbar,
- navigate,
-} from 'twenty-sdk/front-component';
-
-type CompanySummary = Pick<CoreSchema.Company, 'id' | 'name'>;
-
-const CompaniesStandalonePage = () => {
- const [companies, setCompanies] = useState<CompanySummary[]>([]);
- const [loading, setLoading] = useState(true);
- const [error, setError] = useState<string | null>(null);
-
- useEffect(() => {
- let cancelled = false;
-
- const loadCompanies = async () => {
- try {
- setLoading(true);
- setError(null);
-
- const client = new CoreApiClient();
- const result = await client.query({
- companies: {
- edges: {
- node: {
- id: true,
- name: true,
- },
- },
- },
- });
-
- if (!cancelled) {
- setCompanies(result.companies.edges.map((edge) => edge.node));
- }
- } catch (err) {
- const message =
- err instanceof Error ? err.message : 'Failed to load companies';
-
- if (!cancelled) {
- setError(message);
- enqueueSnackbar({ message, variant: 'error' });
- }
- } finally {
- if (!cancelled) {
- setLoading(false);
- }
- }
- };
-
- loadCompanies();
-
- return () => {
- cancelled = true;
- };
- }, []);
-
- if (loading) return <div style={{ padding: 24 }}>Loading companies...</div>;
- if (error) return <div style={{ padding: 24 }}>{error}</div>;
- if (companies.length === 0) {
- return <div style={{ padding: 24 }}>No companies yet.</div>;
- }
-
- return (
- <div style={{ display: 'grid', gap: 8, padding: 24 }}>
- {companies.map((company) => (
- <button
- key={company.id}
- type="button"
- onClick={() =>
- navigate(AppPath.RecordShowPage, {
- objectNameSingular: 'company',
- objectRecordId: company.id,
- })
- }
- >
- {company.name}
- </button>
- ))}
- </div>
- );
-};
-
-export default defineFrontComponent({
- universalIdentifier: '5aa8c51f-72a4-4929-a6ab-2d4ea9d2a6df',
- name: 'companies-standalone-page',
- description: 'Lists companies and opens related records.',
- component: CompaniesStandalonePage,
-});
+import { AppPath, navigate } from 'twenty-sdk/front-component';
+import { LightButton } from 'twenty-ui/components/input';
+
+const CompanyRecordAction = ({
+ companyId,
+ companyName,
+}: {
+ companyId: string;
+ companyName: string;
+}) => (
+ <LightButton
+ onClick={() =>
+ navigate(AppPath.RecordShowPage, {
+ objectNameSingular: 'company',
+ objectRecordId: companyId,
+ })
+ }
+ >
+ {companyName}
+ </LightButton>
+);
```
Always model these states:
@@ -393,9 +336,14 @@ Installed-app checks:
Known-good component test:
```tsx
+import { Heading } from 'twenty-ui/primitives/typography';
+import { themeCssVariables } from 'twenty-ui/theme';
+
const KnownGoodStandalonePage = () => (
- <main style={{ minHeight: '100%', padding: 24 }}>
- <h1>Standalone page runtime is working</h1>
+ <main
+ style={{ minHeight: '100%', padding: themeCssVariables.spacing[4] }}
+ >
+ <Heading level={1}>Standalone page runtime is working</Heading>
</main>
);
```
diff --git a/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js
index df8fdc40ccd..46356936c6e 100644
--- a/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js
+++ b/packages/twenty-agent-skills/scripts/validators/cross-doc-contracts.js
@@ -139,7 +139,7 @@ const assertFrontComponentGuidance = (fail) => {
'Prefer Twenty UI primitives',
'Use `Callout`',
'Use `Button`',
- 'Use `Tag`, `Status`, `Chip`, `Label`, and `Avatar`',
+ 'Use `Tag`, `Status`, `Chip`, and `Avatar`',
'Use `themeCssVariables`',
'Design the visible states',
];
diff --git a/packages/twenty-agent-skills/skills/develop-app/SKILL.md b/packages/twenty-agent-skills/skills/develop-app/SKILL.md
index 42cffe142d7..cb7bfbf042f 100644
--- a/packages/twenty-agent-skills/skills/develop-app/SKILL.md
+++ b/packages/twenty-agent-skills/skills/develop-app/SKILL.md
@@ -77,6 +77,12 @@ command -v twenty && twenty app add object --name invoice --name-plural invoices
Otherwise run `yarn twenty dev:add` in an interactive terminal. The full order of options, including what to do when neither CLI can run, is rule 3 of the operating rules linked above.
+## Front Component Defaults
+
+For every visible front component, use `twenty-ui` components and individual icons by default. Reuse an equivalent Twenty UI component before writing a custom control or adding another UI library. Plain HTML is appropriate for layout containers and content without a Twenty UI equivalent.
+
+Before creating or editing front component UI, read `../../references/develop-app/front-components.md` for imports and renderer constraints and `../../references/design/front-component-ui.md` for component selection, theme tokens, accessibility and visible states. This applies to the first implementation as well as later visual polish. Use the linked official component pages for current props and composition instead of guessing APIs or copying the full documentation into the app.
+
## After Entity Changes
Once all edits for the change are complete, run lint and typecheck once at the end (not after each individual edit), then sync the app to the active remote:
@@ -109,6 +115,6 @@ For front components, read `front-components.md` before implementation. Use `lay
# Handoffs
-Use `../../references/design/front-component-ui.md` when the entity work turns into front component UI design.
+Use `../../references/design/front-component-ui.md` for every visible front component, including its first implementation.
Use `publish-app` when the task turns into README, marketplace copy, screenshots, logos, or listing assets.
diff --git a/packages/twenty-cli/app-template/AGENTS.md b/packages/twenty-cli/app-template/AGENTS.md
index 7629e26d549..de6d6045ef4 100644
--- a/packages/twenty-cli/app-template/AGENTS.md
+++ b/packages/twenty-cli/app-template/AGENTS.md
@@ -37,6 +37,21 @@
- https://docs.twenty.com/developers/extend/apps/operations/publishing.md
- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples/postcard
+## Front components
+
+For front component work, follow the official `develop-app` skill when installed. Install the official skills with `npx skills add https://github.com/twentyhq/twenty/tree/agent-skills --skill '*'`. Apply these essentials even when no skills are installed:
+
+- For every visible front component, use `twenty-ui` components by default. Reuse an equivalent Twenty UI control before writing a custom control or adding another UI library. Plain HTML is appropriate for layout containers and content without a Twenty UI equivalent.
+- Import from public family subpaths: `twenty-ui/components/input` for `MainButton` and `LightButton`, `twenty-ui/primitives/input` for foundational controls, `twenty-ui/primitives/typography` for text, and the matching family for other components. Import individual icons from `twenty-ui/icon`, never `IconsProvider` or `useIcons`. Keep `twenty-ui`, `twenty-sdk` and `twenty-client-sdk` pinned to the same version in `devDependencies`.
+- The renderer supplies styles and the workspace theme. Use `useTheme()` from `twenty-ui/theme` inside the component for spacing, colors, typography and radii. Do not add a root `ThemeProvider`, force a color scheme, or copy standalone stylesheet setup into a front component. Never dereference theme tokens at module top level, since entity files also run during manifest extraction.
+- Use component props before custom styles. Keep layouts compact and responsive to widget width, give inputs visible labels and icon-only actions accessible names, and handle loading, empty, error, disabled and saving states. Verify light and dark themes, narrow widths and long values.
+- Use `openCommandConfirmationModal` or `CommandModal` from `twenty-sdk/front-component` for confirmation dialogs and `enqueueSnackbar` for notifications. Do not render `Dialog`, `AlertDialog`, native `dialog` elements or native browser popovers directly. Use Twenty UI `Dropdown` for menus and pickers.
+- Components run in a Web Worker with a sandboxed, partial `window` and `document`. Prefer CSS for layout and width-based queries. `canvas` and `scrollIntoView` are unsupported; consult the current runtime limitations before using other browser APIs.
+- Keep the `.tsx` entity's direct `export default defineFrontComponent({ ... })` call. The SDK mounts the component, so do not call `react-dom/client` or use browser globals at module top level.
+- Read workspace data with `CoreApiClient` from `twenty-client-sdk/core` and selection with `useSelectedRecordIds()` from `twenty-sdk/front-component`. Call third-party APIs from logic functions; secret application variables never reach a front component.
+
+Read the [front component guide](https://docs.twenty.com/developers/extend/apps/layout/front-components.md) before implementation for the renderer setup and runtime limitations. Use [Twenty UI getting started](https://docs.twenty.com/ui/getting-started.md), [components](https://docs.twenty.com/ui/components/overview.md), [primitives](https://docs.twenty.com/ui/primitives/overview.md) and [theming](https://docs.twenty.com/ui/theming.md) to find the relevant component page and check its current props and composition.
+
## UUID requirement
- All generated UUIDs must be valid UUID v4.
@@ -44,7 +59,7 @@
## Common Pitfalls
- Creating a view without a navigationMenuItem associated. This will make the view available on the left sidebar.
-- Creating a front-end component that has a scroll instead of being responsive to its fixed widget height and width, unless it is specifically meant to be used in a canvas tab.
+- Creating a front component that overflows its widget. Fit the available width and let content determine height, unless the component is the tab's single `heightBehavior: 'TAB_VIEWPORT'` widget and owns internal scrolling.
## Best practice