snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/ui/primitives/data-display/avatar.mdx

@@ -0,0 +1,78 @@
+---
+title: Avatar
+description: Represent a person or record with an image, initial, or icon.
+---
+
+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/primitives/data-display/chip).
+
+<StoryEmbed storyId="ui-data-display-avatar--app" title="Avatar example" />
+
+## Image and fallback
+
+```tsx
+import { Avatar } from 'twenty-ui/primitives/data-display';
+
+type PersonAvatarProps = { name: string; imageUrl?: string | null };
+
+export const PersonAvatar = ({ name, imageUrl }: PersonAvatarProps) => (
+  <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+    <Avatar src={imageUrl} name={name} shape="circle" size="lg" />
+    {name}
+  </span>
+);
+```
+
+When the image is absent or fails to load, the fallback shows the first letter of the trimmed name in uppercase. An empty name shows `-`. `colorSeed` chooses stable fallback colors and defaults to `name`; use a record identifier to keep the color stable when the name changes.
+
+The image and fallback are decorative. Keep the visible name beside the avatar, as above. For a standalone avatar that conveys information, supply `role="img"` and an `aria-label`.
+
+## Shape and appearance
+
+`shape` accepts `square`, `rounded-square`, or `circle`. Sizes run from `xs` (12px) to `xl` (40px); `md` is 16px. `variant="outline"` adds a border to the fallback. The `color`, `backgroundColor`, and `borderColor` overrides customize the fallback, while a loaded image keeps its original appearance.
+
+```tsx
+import { IconUser } from 'twenty-ui/icon';
+import { Avatar } from 'twenty-ui/primitives/data-display';
+
+export const ContactIcon = () => (
+  <Avatar
+    icon={<IconUser />}
+    shape="rounded-square"
+    size="xl"
+    role="img"
+    aria-label="Contact"
+  />
+);
+```
+
+An `icon` takes precedence over both the image and the first-letter fallback. `pulsing` animates opacity and respects reduced-motion preferences.
+
+## Open a profile
+
+```tsx
+import { Avatar } from 'twenty-ui/primitives/data-display';
+
+type ProfileAvatarProps = { onOpenProfile: () => void };
+
+export const ProfileAvatar = ({ onOpenProfile }: ProfileAvatarProps) => (
+  <Avatar
+    name="Jane"
+    shape="circle"
+    size="lg"
+    aria-label="Open Jane's profile"
+    onClick={onOpenProfile}
+  />
+);
+```
+
+Supplying `onClick` renders a button with pointer, Enter, and Space activation. Use `disabled` to prevent activation. The default accessible name comes from `name`, but an action-specific `aria-label` makes the purpose clearer. When replacing the button through `render`, set `nativeButton={false}` for a non-button element.
+
+## Props
+
+Types and defaults are generated from the public component types. Native attributes and event handlers are also accepted.
+
+<AvatarReference />

packages/twenty-docs/ui/primitives/data-display/chip.mdx

@@ -0,0 +1,80 @@
+---
+title: Chip
+description: Show a compact record label with optional leading and trailing content.
+---
+
+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/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"
+  title="Chip example"
+/>
+
+## Record label
+
+```tsx
+import { Avatar, Chip } from 'twenty-ui/primitives/data-display';
+
+export const AssigneeChip = () => (
+  <Chip
+    variant="soft"
+    startElement={<Avatar name="Jane" size="sm" shape="circle" />}
+  >
+    Jane
+  </Chip>
+);
+```
+
+Use `startElement` and `endElement` for avatars, icons, or other content. `endElementDivider` adds a separator before the trailing content. The default chip is a `div`; its slots can contain an action when the chip itself is not interactive.
+
+## Open a record
+
+```tsx
+import { Avatar, Chip } from 'twenty-ui/primitives/data-display';
+
+type AssigneeActionProps = { onOpenAssignee: () => void };
+
+export const AssigneeAction = ({ onOpenAssignee }: AssigneeActionProps) => (
+  <Chip
+    onClick={onOpenAssignee}
+    aria-label="Open Jane's record"
+    startElement={<Avatar name="Jane" size="sm" shape="circle" />}
+  >
+    Jane
+  </Chip>
+);
+```
+
+`onClick` renders a button with keyboard activation. `clickable` controls hover and pointer styling only; setting it alone does not create a button or add an action. `disabled` prevents activation of the button. Do not nest buttons or links inside an interactive chip.
+
+Use `render` to replace the root element. If an `onClick` chip renders a non-button element, set `nativeButton={false}`. When `isLabelHidden` hides the label, give an interactive chip an `aria-label`.
+
+## Width and empty labels
+
+```tsx
+import { Chip } from 'twenty-ui/primitives/data-display';
+
+export const FileChip = () => (
+  <Chip variant="soft" maxWidth={180}>
+    Quarterly customer research.pdf
+  </Chip>
+);
+```
+
+`maxWidth` constrains the chip in pixels. String labels truncate and show their full text in a tooltip on hover. `tooltipLabel` changes the tooltip text; `alwaysShowTooltip` also enables it when the label fits. Keep essential information available without relying on hover.
+
+Missing, empty-string, or `false` children show `emptyLabel`, which defaults to `Untitled`. `forceEmptyText` suppresses that placeholder. `isLabelHidden` hides both the content label and the placeholder while preserving the slots.
+
+## Appearance
+
+`size` accepts `sm` or `md`. `variant` accepts `ghost`, `soft`, or `solid`; `ghost` is the default. Use `shape="round"` for a pill, `weight="medium"` for emphasis, and `color="secondary"` for secondary text.
+
+## Props
+
+Types and defaults are generated from the public component types. Native attributes and event handlers are also accepted.
+
+<ChipReference />

packages/twenty-docs/ui/primitives/data-display/status.mdx

@@ -0,0 +1,77 @@
+---
+title: Status
+description: Show a named state with a colored indicator and optional loading feedback.
+---
+
+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/primitives/data-display/tag) for a category without the status indicator.
+
+<StoryEmbed
+  storyId="ui-data-display-status--documentation"
+  title="Status example"
+/>
+
+## Record state
+
+```tsx
+import { Status } from 'twenty-ui/primitives/data-display';
+
+export const RecordStatus = () => <Status color="green">Active</Status>;
+```
+
+`color` is required and uses the theme palette. The label communicates the meaning independently of the color. The default element is a `span`; `weight="medium"` emphasizes its text.
+
+## Loading and announcements
+
+```tsx
+import { Status } from 'twenty-ui/primitives/data-display';
+
+type SaveStatusProps = { isSaving: boolean };
+
+export const SaveStatus = ({ isSaving }: SaveStatusProps) => (
+  <div role="status">
+    <Status color={isSaving ? 'blue' : 'green'} loading={isSaving}>
+      {isSaving ? 'Saving' : 'Saved'}
+    </Status>
+  </div>
+);
+```
+
+`loading` shows a loader after the label. The component does not add a live region or change its text automatically. Keep a `role="status"` container mounted when updates should be announced to assistive technology, and provide a label that describes the current state.
+
+## Change a state
+
+```tsx
+import { Status } from 'twenty-ui/primitives/data-display';
+
+type ChangeStatusActionProps = {
+  isUpdating: boolean;
+  onChangeStatus: () => void;
+};
+
+export const ChangeStatusAction = ({
+  isUpdating,
+  onChangeStatus,
+}: ChangeStatusActionProps) => (
+  <Status
+    color="blue"
+    loading={isUpdating}
+    disabled={isUpdating}
+    onClick={onChangeStatus}
+    aria-label="Change record status"
+  >
+    {isUpdating ? 'Updating' : 'In progress'}
+  </Status>
+);
+```
+
+`onClick` renders a native button with pointer, Enter, and Space activation. `loading` does not prevent repeat activation; pass `disabled` when the action should wait. If `render` replaces the button with a non-button element, set `nativeButton={false}`.
+
+## Props
+
+Types and defaults are generated from the public component types. Native attributes and event handlers are also accepted.
+
+<StatusReference />

packages/twenty-docs/ui/primitives/data-display/tag.mdx

@@ -0,0 +1,81 @@
+---
+title: Tag
+description: Label a category or attribute with a theme color and optional icon.
+---
+
+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/primitives/data-display/status) when you need a state indicator and loading feedback.
+
+<StoryEmbed storyId="ui-data-display-tag--documentation" title="Tag example" />
+
+## Category label
+
+```tsx
+import { Tag } from 'twenty-ui/primitives/data-display';
+
+export const PriorityTag = () => <Tag color="red">Urgent</Tag>;
+```
+
+`color` is required and accepts a theme color or `transparent`. The default element is a `span`. Add a decorative icon with `startIcon`; the label supplies its accessible meaning.
+
+## Variants
+
+```tsx
+import { Tag } from 'twenty-ui/primitives/data-display';
+
+export const CategoryTags = () => (
+  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+    <Tag color="blue" variant="soft">
+      Customer
+    </Tag>
+    <Tag color="green" variant="solid">
+      Partner
+    </Tag>
+    <Tag color="orange" variant="outline">
+      Prospect
+    </Tag>
+    <Tag color="transparent" variant="outline" borderStyle="dashed">
+      Unassigned
+    </Tag>
+  </div>
+);
+```
+
+`soft` is the default treatment. `solid` emphasizes the label, `outline` adds a border, and `ghost` removes the background. Use `borderStyle="dashed"` with `outline` and `weight="medium"` for a stronger label.
+
+## Filter by a tag
+
+```tsx
+import { Tag } from 'twenty-ui/primitives/data-display';
+
+type CategoryFilterProps = {
+  selected: boolean;
+  onToggle: () => void;
+};
+
+export const CategoryFilter = ({ selected, onToggle }: CategoryFilterProps) => (
+  <Tag
+    color="blue"
+    variant={selected ? 'solid' : 'outline'}
+    aria-pressed={selected}
+    onClick={onToggle}
+  >
+    Customer
+  </Tag>
+);
+```
+
+Supplying `onClick` renders a button. Selection state belongs to your application; use `aria-pressed` for a toggle and a visible treatment for the selected state. `disabled` prevents pointer and keyboard activation. When `render` replaces an interactive tag with a non-button element, set `nativeButton={false}`.
+
+## Long labels
+
+By default, constrained string labels truncate and expose their full text in a tooltip on hover. `preventShrink` keeps the full label width and turns off that tooltip, so make sure the surrounding layout can accommodate it. `preventPadding` removes the horizontal padding for custom layouts.
+
+## Props
+
+Types and defaults are generated from the public component types. Native attributes and event handlers are also accepted.
+
+<TagReference />