Skip to content

The open alternative to Salesforce, designed for AI.

Add live previews to Twenty UI documentation (#25889)

Raphaël Bosia3ba7be23d59
diff --git a/.github/workflows/cd-storybook-ui.yaml b/.github/workflows/cd-storybook-ui.yaml
new file mode 100644
index 00000000000..ef055baf66d
--- /dev/null
+++ b/.github/workflows/cd-storybook-ui.yaml
@@ -0,0 +1,75 @@
+name: CD Storybook UI
+
+on:
+ push:
+ branches: [main]
+ tags: ['sdk/v*', 'ui/v*']
+ paths:
+ - .github/workflows/cd-storybook-ui.yaml
+ - .github/actions/yarn-install/**
+ - package.json
+ - yarn.lock
+ - nx.json
+ - tsconfig.base.json
+ - packages/twenty-ui/**
+ - packages/twenty-shared/**
+ - packages/twenty-docs/**
+
+permissions: {}
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: ${{ github.ref == 'refs/heads/main' }}
+
+jobs:
+ build:
+ permissions:
+ contents: read
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ steps:
+ - name: Checkout source
+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+ with:
+ persist-credentials: false
+
+ - name: Install dependencies
+ uses: ./.github/actions/yarn-install
+
+ - name: Build public Storybook
+ run: npx nx storybook:build twenty-ui --configuration=docs
+
+ - name: Check embedded stories against the build
+ run: npx tsx packages/twenty-docs/scripts/check-ui-story-embeds.mts packages/twenty-ui/storybook-static/index.json
+
+ - name: Upload public Storybook
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+ with:
+ name: storybook-twenty-ui-public
+ path: packages/twenty-ui/storybook-static
+ if-no-files-found: error
+ retention-days: 7
+
+ dispatch:
+ needs: build
+ permissions: {}
+ runs-on: ubuntu-latest
+ timeout-minutes: 3
+ steps:
+ - name: Mint twenty-factory dispatch token
+ id: app-token
+ uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
+ with:
+ client-id: ${{ vars.TWENTY_WORKFLOW_DISPATCHER_CLIENT_ID }}
+ private-key: ${{ secrets.TWENTY_WORKFLOW_DISPATCHER_PRIVATE_KEY }}
+ owner: twentyhq
+ repositories: twenty-factory
+ permission-actions: write
+
+ - name: Request Storybook deployment
+ env:
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
+ SOURCE_RUN_ID: ${{ github.run_id }}
+ run: |
+ gh workflow run deploy-storybook-ui.yaml --repo twentyhq/twenty-factory --ref main \
+ -f source_run_id="$SOURCE_RUN_ID"
diff --git a/.github/workflows/ci-docs.yaml b/.github/workflows/ci-docs.yaml
index a6a9bd29e7f..b433a93098f 100644
--- a/.github/workflows/ci-docs.yaml
+++ b/.github/workflows/ci-docs.yaml
@@ -22,6 +22,7 @@ jobs:
package.json
yarn.lock
packages/twenty-ui/**
+ packages/twenty-shared/**
.github/workflows/ci-docs.yaml
packages/twenty-docs/**
@@ -47,3 +48,6 @@ jobs:
- name: Docs / Generated UI references
run: npx nx check:ui twenty-docs
+
+ - name: Docs / Storybook embeds
+ run: npx nx check:ui-stories twenty-docs
diff --git a/packages/twenty-docs/package.json b/packages/twenty-docs/package.json
index 7cc36a56d2e..9661c8ba828 100644
--- a/packages/twenty-docs/package.json
+++ b/packages/twenty-docs/package.json
@@ -14,8 +14,12 @@
"mintlify": "^4.2.790"
},
"devDependencies": {
+ "@mdx-js/mdx": "^3.1.1",
+ "@sniptt/guards": "^0.2.0",
+ "remark-frontmatter": "^5.0.0",
"tsx": "^4.19.3",
"twenty-shared": "workspace:*",
+ "unist-util-visit": "^5.0.0",
"vitest": "^4.1.0"
},
"engines": {
diff --git a/packages/twenty-docs/project.json b/packages/twenty-docs/project.json
index 62637b690cc..27fdfc3f8c7 100644
--- a/packages/twenty-docs/project.json
+++ b/packages/twenty-docs/project.json
@@ -73,6 +73,14 @@
],
"parallel": false
}
+ },
+ "check:ui-stories": {
+ "executor": "nx:run-commands",
+ "cache": false,
+ "dependsOn": ["twenty-ui:storybook:index"],
+ "options": {
+ "command": "tsx packages/twenty-docs/scripts/check-ui-story-embeds.mts .cache/ui-docs/storybook-index.json"
+ }
}
}
}
diff --git a/packages/twenty-docs/scripts/check-ui-story-embeds.mts b/packages/twenty-docs/scripts/check-ui-story-embeds.mts
new file mode 100644
index 00000000000..08fe9f9dcf0
--- /dev/null
+++ b/packages/twenty-docs/scripts/check-ui-story-embeds.mts
@@ -0,0 +1,41 @@
+import { globSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { isNonEmptyString } from '@sniptt/guards';
+
+import { checkStoryEmbeds } from './ui/check-story-embeds.mjs';
+
+const indexPath = process.argv[2];
+
+if (!isNonEmptyString(indexPath)) {
+ throw new Error('Pass the path to the generated Storybook index.json.');
+}
+
+const index: { entries: Record<string, { id: string; type: string }> } =
+ JSON.parse(readFileSync(resolve(indexPath), 'utf8'));
+const storyIds = new Set(
+ Object.values(index.entries)
+ .filter((entry) => entry.type === 'story')
+ .map((entry) => entry.id),
+);
+const documentationRoot = fileURLToPath(new URL('..', import.meta.url));
+const pages = globSync(
+ ['ui/**/*.mdx', 'l/*/ui/**/*.mdx', 'snippets/ui/**/*.mdx'],
+ { cwd: documentationRoot },
+).sort();
+const errors = pages.flatMap((page) =>
+ checkStoryEmbeds({
+ content: readFileSync(resolve(documentationRoot, page), 'utf8'),
+ storyIds,
+ }).map((error) => `${page}: ${error}`),
+);
+
+if (errors.length > 0) {
+ process.stderr.write(`${errors.join('\n')}\n`);
+ process.exitCode = 1;
+} else {
+ process.stdout.write(
+ `Checked UI documentation embeds against ${storyIds.size} Storybook stories.\n`,
+ );
+}
diff --git a/packages/twenty-docs/scripts/ui/__tests__/check-story-embeds.spec.ts b/packages/twenty-docs/scripts/ui/__tests__/check-story-embeds.spec.ts
new file mode 100644
index 00000000000..6dfb65557f4
--- /dev/null
+++ b/packages/twenty-docs/scripts/ui/__tests__/check-story-embeds.spec.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+
+import { checkStoryEmbeds } from '../check-story-embeds.mjs';
+
+const storyIds = new Set(['ui-input-input--default']);
+
+describe('checkStoryEmbeds', () => {
+ it('accepts an existing story inside a nested preview', () => {
+ expect(
+ checkStoryEmbeds({
+ content: `<Tabs>
+ <Tab title="Preview">
+ <StoryEmbed storyId="ui-input-input--default" />
+ </Tab>
+</Tabs>`,
+ storyIds,
+ }),
+ ).toEqual([]);
+ });
+
+ it('reports a renamed or deleted story with its line number', () => {
+ expect(
+ checkStoryEmbeds({
+ content: '\n<StoryEmbed storyId="ui-input-input--removed" />',
+ storyIds,
+ }),
+ ).toEqual([
+ 'Line 2: Storybook story "ui-input-input--removed" does not exist.',
+ ]);
+ });
+
+ it.each([
+ '<StoryEmbed />',
+ '<StoryEmbed storyId={selectedStory} />',
+ '<StoryEmbed storyId="" />',
+ '<StoryEmbed storyId="ui-input-input--default" {...props} />',
+ ])('rejects an unverifiable story ID in %s', (content) => {
+ expect(checkStoryEmbeds({ content, storyIds })).toEqual([
+ 'Line 1: StoryEmbed needs a literal storyId.',
+ ]);
+ });
+
+ it('checks a renamed snippet import', () => {
+ expect(
+ checkStoryEmbeds({
+ content: `import { StoryEmbed as Preview } from '/snippets/ui/StoryEmbed.mdx';
+
+<Preview storyId="removed-story" />`,
+ storyIds,
+ }),
+ ).toEqual(['Line 3: Storybook story "removed-story" does not exist.']);
+ });
+
+ it('ignores examples and comments while parsing page metadata', () => {
+ expect(
+ checkStoryEmbeds({
+ content: `---
+title: Preview
+description: "A {component} preview"
+---
+
+\`\`\`mdx
+<StoryEmbed storyId="not-a-live-embed" />
+\`\`\`
+
+\`<StoryEmbed storyId="inline-code" />\`
+
+{/* <StoryEmbed storyId="commented-out" /> */}`,
+ storyIds,
+ }),
+ ).toEqual([]);
+ });
+});
diff --git a/packages/twenty-docs/scripts/ui/check-story-embeds.mts b/packages/twenty-docs/scripts/ui/check-story-embeds.mts
new file mode 100644
index 00000000000..ece385664ad
--- /dev/null
+++ b/packages/twenty-docs/scripts/ui/check-story-embeds.mts
@@ -0,0 +1,73 @@
+import { createProcessor } from '@mdx-js/mdx';
+import remarkFrontmatter from 'remark-frontmatter';
+import { isNonEmptyString } from '@sniptt/guards';
+import { visit } from 'unist-util-visit';
+
+export const checkStoryEmbeds = ({
+ content,
+ storyIds,
+}: {
+ content: string;
+ storyIds: Set<string>;
+}): string[] => {
+ const errors: string[] = [];
+ const tree = createProcessor({
+ remarkPlugins: [remarkFrontmatter],
+ }).parse(content);
+ const embedNames = new Set(['StoryEmbed']);
+
+ visit(tree, 'mdxjsEsm', (node) => {
+ for (const statement of node.data?.estree?.body ?? []) {
+ if (
+ statement.type !== 'ImportDeclaration' ||
+ statement.source.value !== '/snippets/ui/StoryEmbed.mdx'
+ ) {
+ continue;
+ }
+
+ for (const specifier of statement.specifiers) {
+ const isNamedEmbed =
+ specifier.type === 'ImportSpecifier' &&
+ specifier.imported.type === 'Identifier' &&
+ specifier.imported.name === 'StoryEmbed';
+
+ if (specifier.type === 'ImportDefaultSpecifier' || isNamedEmbed) {
+ embedNames.add(specifier.local.name);
+ }
+ }
+ }
+ });
+
+ visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+ if (
+ (node.type !== 'mdxJsxFlowElement' &&
+ node.type !== 'mdxJsxTextElement') ||
+ !embedNames.has(node.name ?? '')
+ ) {
+ return;
+ }
+
+ const storyId = node.attributes.find(
+ (attribute) =>
+ attribute.type === 'mdxJsxAttribute' && attribute.name === 'storyId',
+ );
+ const value =
+ storyId?.type === 'mdxJsxAttribute' ? storyId.value : undefined;
+ const line = node.position?.start.line;
+
+ const hasSpreadAttributes = node.attributes.some(
+ (attribute) => attribute.type === 'mdxJsxExpressionAttribute',
+ );
+
+ if (!isNonEmptyString(value) || hasSpreadAttributes) {
+ errors.push(`Line ${line}: StoryEmbed needs a literal storyId.`);
+ return;
+ }
+
+ if (!storyIds.has(value)) {
+ errors.push(`Line ${line}: Storybook story "${value}" does not exist.`);
+ }
+ });
+
+ return errors;
+};
diff --git a/packages/twenty-docs/snippets/ui/StoryEmbed.mdx b/packages/twenty-docs/snippets/ui/StoryEmbed.mdx
new file mode 100644
index 00000000000..011f326cce3
--- /dev/null
+++ b/packages/twenty-docs/snippets/ui/StoryEmbed.mdx
@@ -0,0 +1,29 @@
+export const StoryEmbed = ({ storyId, title, height = 240 }) => (
+ <>
+ <Tabs>
+ <Tab title="Light">
+ <iframe
+ title={`${title} (light)`}
+ src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:light`}
+ width="100%"
+ height={height}
+ loading="lazy"
+ style={{ border: 0 }}
+ />
+ </Tab>
+ <Tab title="Dark">
+ <iframe
+ title={`${title} (dark)`}
+ src={`https://storybook.twenty.com/iframe.html?id=${storyId}&viewMode=story&globals=colorScheme:dark`}
+ width="100%"
+ height={height}
+ loading="lazy"
+ style={{ border: 0 }}
+ />
+ </Tab>
+ </Tabs>
+ <a href={`https://storybook.twenty.com/?path=/story/${storyId}`}>
+ Open in Storybook
+ </a>
+ </>
+);
diff --git a/packages/twenty-docs/ui/components/feedback/toast.mdx b/packages/twenty-docs/ui/components/feedback/toast.mdx
index ceafa27a986..6b23b5aa3bc 100644
--- a/packages/twenty-docs/ui/components/feedback/toast.mdx
+++ b/packages/twenty-docs/ui/components/feedback/toast.mdx
@@ -3,10 +3,18 @@ title: Toast
description: Display status messages with optional details, actions, and progress.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import ToastReference from '/snippets/ui/generated/feedback/toast.mdx';
`Toast` renders one notification. Your application controls when it appears, its position, and when it is removed.
+<StoryEmbed
+ storyId="ui-feedback-toast--documentation"
+ title="Toast example"
+ height={240}
+/>
+
## Dismissible notification
```tsx
diff --git a/packages/twenty-docs/ui/components/input/checkbox.mdx b/packages/twenty-docs/ui/components/input/checkbox.mdx
index 0ad787f0d56..ab562cec803 100644
--- a/packages/twenty-docs/ui/components/input/checkbox.mdx
+++ b/packages/twenty-docs/ui/components/input/checkbox.mdx
@@ -3,10 +3,18 @@ title: Checkbox
description: Select independent options with checked and indeterminate states.
---
+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).
+<StoryEmbed
+ storyId="ui-input-checkbox-checkbox--default"
+ title="Checkbox example"
+ height={240}
+/>
+
## Uncontrolled state
```tsx
diff --git a/packages/twenty-docs/ui/components/input/field.mdx b/packages/twenty-docs/ui/components/input/field.mdx
index da50db4f847..e99bb134951 100644
--- a/packages/twenty-docs/ui/components/input/field.mdx
+++ b/packages/twenty-docs/ui/components/input/field.mdx
@@ -3,10 +3,18 @@ title: Field
description: Connect a form control to its label, description, and validation feedback.
---
+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.
+<StoryEmbed
+ storyId="ui-input-field--default"
+ title="Field example"
+ height={240}
+/>
+
## Labeled control
```tsx
diff --git a/packages/twenty-docs/ui/components/input/input-group.mdx b/packages/twenty-docs/ui/components/input/input-group.mdx
index c0df0c4d498..194f4dc4032 100644
--- a/packages/twenty-docs/ui/components/input/input-group.mdx
+++ b/packages/twenty-docs/ui/components/input/input-group.mdx
@@ -3,10 +3,18 @@ title: InputGroup
description: Add prefixes, suffixes, and actions around a text input.
---
+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.
+<StoryEmbed
+ storyId="ui-input-inputgroup--default"
+ title="InputGroup example"
+ height={240}
+/>
+
## Prefix and suffix
```tsx
diff --git a/packages/twenty-docs/ui/components/input/input.mdx b/packages/twenty-docs/ui/components/input/input.mdx
index 9fe6c573515..c6c7eb1662c 100644
--- a/packages/twenty-docs/ui/components/input/input.mdx
+++ b/packages/twenty-docs/ui/components/input/input.mdx
@@ -3,10 +3,18 @@ title: Input
description: A text input with native attributes, field integration, and two sizes.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import InputReference from '/snippets/ui/generated/input/input.mdx';
`Input` renders a text input and accepts native input attributes such as `type`, `name`, `required`, `disabled`, and `autoComplete`.
+<StoryEmbed
+ storyId="ui-input-input--default"
+ title="Input example"
+ height={240}
+/>
+
## Label an input
```tsx
diff --git a/packages/twenty-docs/ui/components/input/radio-group.mdx b/packages/twenty-docs/ui/components/input/radio-group.mdx
index 5a36a1f31dd..cee51cd9f91 100644
--- a/packages/twenty-docs/ui/components/input/radio-group.mdx
+++ b/packages/twenty-docs/ui/components/input/radio-group.mdx
@@ -3,10 +3,18 @@ title: RadioGroup
description: Manage a single selection across a set of radio options.
---
+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.
+<StoryEmbed
+ storyId="ui-input-radiogroup--default"
+ title="RadioGroup example"
+ height={240}
+/>
+
## Default selection
```tsx
diff --git a/packages/twenty-docs/ui/components/input/radio.mdx b/packages/twenty-docs/ui/components/input/radio.mdx
index 68cd5e132a1..6bdedd47090 100644
--- a/packages/twenty-docs/ui/components/input/radio.mdx
+++ b/packages/twenty-docs/ui/components/input/radio.mdx
@@ -3,10 +3,18 @@ title: Radio
description: Render one option in a mutually exclusive radio group.
---
+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.
+<StoryEmbed
+ storyId="ui-input-radio--documentation"
+ title="Radio example"
+ height={240}
+/>
+
## Labeled options
```tsx
diff --git a/packages/twenty-docs/ui/components/input/select.mdx b/packages/twenty-docs/ui/components/input/select.mdx
index 9d7b0db9fdc..8237d450cca 100644
--- a/packages/twenty-docs/ui/components/input/select.mdx
+++ b/packages/twenty-docs/ui/components/input/select.mdx
@@ -3,10 +3,18 @@ title: Select
description: Choose one or more values from a popup list of options.
---
+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.
+<StoryEmbed
+ storyId="ui-input-select--documentation"
+ title="Select example"
+ height={400}
+/>
+
## Single selection
```tsx
diff --git a/packages/twenty-docs/ui/components/input/slider.mdx b/packages/twenty-docs/ui/components/input/slider.mdx
index 983909bfd15..c72b609d9a5 100644
--- a/packages/twenty-docs/ui/components/input/slider.mdx
+++ b/packages/twenty-docs/ui/components/input/slider.mdx
@@ -3,10 +3,18 @@ title: Slider
description: Choose a numeric value or range with draggable, keyboard-accessible thumbs.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import SliderReference from '/snippets/ui/generated/input/slider.mdx';
`Slider` supports a single number or an array of numbers for a range. Compose its label, track, indicator, and thumbs inside `Root`.
+<StoryEmbed
+ storyId="ui-input-slider--default"
+ title="Slider example"
+ height={240}
+/>
+
## Single value
```tsx
diff --git a/packages/twenty-docs/ui/components/input/switch.mdx b/packages/twenty-docs/ui/components/input/switch.mdx
index 1010b5eb696..19c73a5d073 100644
--- a/packages/twenty-docs/ui/components/input/switch.mdx
+++ b/packages/twenty-docs/ui/components/input/switch.mdx
@@ -3,10 +3,18 @@ title: Switch
description: A labeled on or off control with controlled and uncontrolled state.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import SwitchReference from '/snippets/ui/generated/input/switch.mdx';
Use `Switch` for an on or off preference. Give the control a visible label or an accessible name.
+<StoryEmbed
+ storyId="ui-input-switch-switch--default"
+ title="Switch example"
+ height={240}
+/>
+
## Uncontrolled state
```tsx
diff --git a/packages/twenty-docs/ui/components/input/textarea.mdx b/packages/twenty-docs/ui/components/input/textarea.mdx
index 17d4681f552..5e3f2c80b33 100644
--- a/packages/twenty-docs/ui/components/input/textarea.mdx
+++ b/packages/twenty-docs/ui/components/input/textarea.mdx
@@ -3,10 +3,18 @@ title: Textarea
description: Enter multiple lines of text with optional automatic resizing.
---
+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.
+<StoryEmbed
+ storyId="ui-input-textarea--default"
+ title="Textarea example"
+ height={240}
+/>
+
## Basic textarea
```tsx
diff --git a/packages/twenty-docs/ui/components/navigation/list-item.mdx b/packages/twenty-docs/ui/components/navigation/list-item.mdx
index 009b617328e..fde77356750 100644
--- a/packages/twenty-docs/ui/components/navigation/list-item.mdx
+++ b/packages/twenty-docs/ui/components/navigation/list-item.mdx
@@ -3,10 +3,18 @@ title: ListItem
description: Compose consistent rows with icons, descriptions, indicators, and actions.
---
+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.
+<StoryEmbed
+ storyId="ui-navigation-listitem--default"
+ title="ListItem example"
+ height={240}
+/>
+
## Action row
```tsx
diff --git a/packages/twenty-docs/ui/components/navigation/tabs.mdx b/packages/twenty-docs/ui/components/navigation/tabs.mdx
index 7770af1e27a..f3ab180124e 100644
--- a/packages/twenty-docs/ui/components/navigation/tabs.mdx
+++ b/packages/twenty-docs/ui/components/navigation/tabs.mdx
@@ -3,10 +3,18 @@ title: Tabs
description: Switch between related panels with accessible tab navigation.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import TabsReference from '/snippets/ui/generated/navigation/tabs.mdx';
`Tabs` connects each tab to a panel using a shared `value`. Keep the values unique within a root.
+<StoryEmbed
+ storyId="ui-navigation-tabs--documentation"
+ title="Tabs example"
+ height={240}
+/>
+
## Tab panels
```tsx
diff --git a/packages/twenty-docs/ui/components/surfaces/alert-dialog.mdx b/packages/twenty-docs/ui/components/surfaces/alert-dialog.mdx
index f2d05f4770f..1c2dea26e89 100644
--- a/packages/twenty-docs/ui/components/surfaces/alert-dialog.mdx
+++ b/packages/twenty-docs/ui/components/surfaces/alert-dialog.mdx
@@ -3,10 +3,18 @@ title: AlertDialog
description: Ask for confirmation before an action that needs an explicit decision.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import AlertDialogReference from '/snippets/ui/generated/surfaces/alert-dialog.mdx';
Use `AlertDialog` for a decision that interrupts the current workflow, such as confirming deletion. It provides an accessible modal with a backdrop and focus management.
+<StoryEmbed
+ storyId="ui-surfaces-alertdialog--documentation"
+ title="AlertDialog example"
+ height={440}
+/>
+
## Confirmation
```tsx
diff --git a/packages/twenty-docs/ui/components/surfaces/menu.mdx b/packages/twenty-docs/ui/components/surfaces/menu.mdx
index ac81e35e5e9..d5fb65e3cc3 100644
--- a/packages/twenty-docs/ui/components/surfaces/menu.mdx
+++ b/packages/twenty-docs/ui/components/surfaces/menu.mdx
@@ -3,10 +3,18 @@ title: Menu
description: Present commands, checked options, radio choices, and nested menus.
---
+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).
+<StoryEmbed
+ storyId="ui-surfaces-menu--documentation"
+ title="Menu example"
+ height={440}
+/>
+
## Action menu
```tsx
diff --git a/packages/twenty-docs/ui/components/surfaces/popover.mdx b/packages/twenty-docs/ui/components/surfaces/popover.mdx
index bf5f06099d8..53f03f5862a 100644
--- a/packages/twenty-docs/ui/components/surfaces/popover.mdx
+++ b/packages/twenty-docs/ui/components/surfaces/popover.mdx
@@ -3,10 +3,18 @@ title: Popover
description: Display contextual content anchored to a trigger.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import PopoverReference from '/snippets/ui/generated/surfaces/popover.mdx';
Use `Popover` for contextual information or lightweight controls. `Popup` includes positioning and a portal, so you can compose content directly inside it.
+<StoryEmbed
+ storyId="ui-surfaces-popover--documentation"
+ title="Popover example"
+ height={440}
+/>
+
## Contextual content
```tsx
diff --git a/packages/twenty-docs/ui/components/typography/text.mdx b/packages/twenty-docs/ui/components/typography/text.mdx
index 95d8e4d81da..f04b319b5ac 100644
--- a/packages/twenty-docs/ui/components/typography/text.mdx
+++ b/packages/twenty-docs/ui/components/typography/text.mdx
@@ -3,10 +3,18 @@ title: Text
description: Render text with single-line truncation or a limited number of lines.
---
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+
import TextReference from '/snippets/ui/generated/typography/text.mdx';
`Text` provides overflow handling. It renders a `div` by default and inherits typography from its surroundings.
+<StoryEmbed
+ storyId="ui-typography-text--truncate"
+ title="Text example"
+ height={240}
+/>
+
## Truncate one line
Give the text a constrained width, then set `truncate` to show an ellipsis when it overflows:
diff --git a/packages/twenty-ui/.storybook/main.ts b/packages/twenty-ui/.storybook/main.ts
index e79c72ab860..abd81a423cd 100644
--- a/packages/twenty-ui/.storybook/main.ts
+++ b/packages/twenty-ui/.storybook/main.ts
@@ -9,6 +9,7 @@ const dirname =
: path.dirname(fileURLToPath(import.meta.url));
const isVitest = Boolean(process.env.VITEST);
+const isDocumentationBuild = process.env.STORYBOOK_DOCS === 'true';
const config: StorybookConfig = {
stories: ['../src/**/*.@(mdx|stories.@(js|jsx|ts|tsx))'],
@@ -16,7 +17,7 @@ const config: StorybookConfig = {
addons: [
'@storybook-community/storybook-addon-cookie',
'@storybook/addon-links',
- '@storybook/addon-coverage',
+ ...(isDocumentationBuild ? [] : ['@storybook/addon-coverage']),
'@storybook/addon-a11y',
'storybook-addon-pseudo-states',
'@storybook/addon-vitest',
diff --git a/packages/twenty-ui/project.json b/packages/twenty-ui/project.json
index 09546d2b0c2..43a0441a4bb 100644
--- a/packages/twenty-ui/project.json
+++ b/packages/twenty-ui/project.json
@@ -111,7 +111,22 @@
}
},
"typecheck": {},
- "storybook:build": { "configurations": { "test": {} } },
+ "storybook:build": {
+ "configurations": {
+ "test": {},
+ "docs": {
+ "command": "STORYBOOK_DOCS=true NODE_OPTIONS='--max-old-space-size=10240' storybook build --disable-telemetry"
+ }
+ }
+ },
+ "storybook:index": {
+ "executor": "nx:run-commands",
+ "cache": false,
+ "options": {
+ "cwd": "{projectRoot}",
+ "command": "mkdir -p ../../.cache/ui-docs && storybook index --output-file ../../.cache/ui-docs/storybook-index.json --disable-telemetry"
+ }
+ },
"storybook:serve:dev": { "options": { "port": 6008 } },
"storybook:serve:static": {
"options": { "buildTarget": "twenty-ui:storybook:build", "port": 6008 },
diff --git a/packages/twenty-ui/src/feedback/Toast/__stories__/Toast.stories.tsx b/packages/twenty-ui/src/feedback/Toast/__stories__/Toast.stories.tsx
index 29305d39aae..7eaeb41473a 100644
--- a/packages/twenty-ui/src/feedback/Toast/__stories__/Toast.stories.tsx
+++ b/packages/twenty-ui/src/feedback/Toast/__stories__/Toast.stories.tsx
@@ -35,6 +35,12 @@ export const Default: Story = {
},
};
+export const Documentation: Story = {
+ ...Default,
+ render: (args) => <DismissibleToast {...args} />,
+ play: undefined,
+};
+
export const WithDescriptionAndAction: Story = {
...Default,
parameters: { a11y: A11Y_DEFER_COLOR_CONTRAST },
diff --git a/packages/twenty-ui/src/input/Radio/__stories__/Radio.stories.tsx b/packages/twenty-ui/src/input/Radio/__stories__/Radio.stories.tsx
index 2d3a7bb74b7..ba7b5009aab 100644
--- a/packages/twenty-ui/src/input/Radio/__stories__/Radio.stories.tsx
+++ b/packages/twenty-ui/src/input/Radio/__stories__/Radio.stories.tsx
@@ -1,4 +1,5 @@
import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, within } from 'storybook/test';
import { RadioGroup } from '@ui/input/RadioGroup/RadioGroup';
import {
@@ -15,7 +16,7 @@ const RadioExample = ({
selected = false,
...props
}: RadioProps & { selected?: boolean }) => (
- <RadioGroup value={selected ? props.value : ''}>
+ <RadioGroup defaultValue={selected ? props.value : ''}>
<Radio {...props} />
</RadioGroup>
);
@@ -39,7 +40,20 @@ const STATE_PROPS: Record<RadioState, Partial<RadioProps>> = {
readOnly: { readOnly: true },
};
-export const Default: Story = { decorators: [ComponentDecorator] };
+export const Default: Story = {
+ decorators: [ComponentDecorator],
+ play: async ({ canvasElement }) => {
+ const radio = within(canvasElement).getByRole('radio');
+
+ await userEvent.click(radio);
+ await expect(radio).toBeChecked();
+ },
+};
+
+export const Documentation: Story = {
+ ...Default,
+ play: undefined,
+};
export const Catalog: CatalogStory<Story, typeof RadioExample> = {
parameters: {
diff --git a/packages/twenty-ui/src/input/RadioGroup/__stories__/RadioGroup.stories.tsx b/packages/twenty-ui/src/input/RadioGroup/__stories__/RadioGroup.stories.tsx
new file mode 100644
index 00000000000..f97677f1694
--- /dev/null
+++ b/packages/twenty-ui/src/input/RadioGroup/__stories__/RadioGroup.stories.tsx
@@ -0,0 +1,28 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { Radio } from '@ui/input/Radio/Radio';
+import { ComponentDecorator } from '@ui/testing';
+
+import { RadioGroup } from '../RadioGroup';
+
+const meta: Meta<typeof RadioGroup> = {
+ title: 'UI/Input/RadioGroup',
+ component: RadioGroup,
+ args: {
+ 'aria-label': 'Billing frequency',
+ defaultValue: 'monthly',
+ children: (
+ <>
+ <Radio value="monthly">Monthly</Radio>
+ <Radio value="yearly">Yearly</Radio>
+ </>
+ ),
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof RadioGroup>;
+
+export const Default: Story = {
+ decorators: [ComponentDecorator],
+};
diff --git a/packages/twenty-ui/src/input/Select/__stories__/Select.stories.tsx b/packages/twenty-ui/src/input/Select/__stories__/Select.stories.tsx
index b15da2041e5..2cbc8c92252 100644
--- a/packages/twenty-ui/src/input/Select/__stories__/Select.stories.tsx
+++ b/packages/twenty-ui/src/input/Select/__stories__/Select.stories.tsx
@@ -48,6 +48,11 @@ export const Default: Story = {
},
};
+export const Documentation: Story = {
+ ...Default,
+ play: undefined,
+};
+
export const Placeholder: Story = {
...Default,
args: {},
diff --git a/packages/twenty-ui/src/navigation/Tabs/__stories__/Tabs.stories.tsx b/packages/twenty-ui/src/navigation/Tabs/__stories__/Tabs.stories.tsx
index e34f59b1ac2..331965fad3c 100644
--- a/packages/twenty-ui/src/navigation/Tabs/__stories__/Tabs.stories.tsx
+++ b/packages/twenty-ui/src/navigation/Tabs/__stories__/Tabs.stories.tsx
@@ -110,6 +110,11 @@ export const Default: Story = {
},
};
+export const Documentation: Story = {
+ ...Default,
+ play: undefined,
+};
+
export const Controlled: Story = {
decorators: [ComponentDecorator],
parameters: { container: { width: 360 } },
diff --git a/packages/twenty-ui/src/surfaces/AlertDialog/__stories__/AlertDialog.stories.tsx b/packages/twenty-ui/src/surfaces/AlertDialog/__stories__/AlertDialog.stories.tsx
index fe5c86b51e6..ac69490c682 100644
--- a/packages/twenty-ui/src/surfaces/AlertDialog/__stories__/AlertDialog.stories.tsx
+++ b/packages/twenty-ui/src/surfaces/AlertDialog/__stories__/AlertDialog.stories.tsx
@@ -47,6 +47,12 @@ export const Default: Story = {
},
};
+export const Documentation: Story = {
+ ...Default,
+ args: { defaultOpen: false },
+ play: undefined,
+};
+
export const Small: Story = {
...Default,
args: { defaultOpen: true, size: 'sm' },
diff --git a/packages/twenty-ui/src/surfaces/Menu/__stories__/Menu.stories.tsx b/packages/twenty-ui/src/surfaces/Menu/__stories__/Menu.stories.tsx
index 6285b0eebd6..321da28e189 100644
--- a/packages/twenty-ui/src/surfaces/Menu/__stories__/Menu.stories.tsx
+++ b/packages/twenty-ui/src/surfaces/Menu/__stories__/Menu.stories.tsx
@@ -149,6 +149,12 @@ export const Default: Story = {
await waitFor(() => expect(item).toHaveAttribute('data-highlighted'));
},
};
+
+export const Documentation: Story = {
+ ...Default,
+ args: { defaultOpen: false },
+ play: undefined,
+};
export const Selection: Story = {
decorators: [ComponentDecorator],
parameters: { container: { width: 240, height: 320 } },
diff --git a/packages/twenty-ui/src/surfaces/Popover/__stories__/Popover.stories.tsx b/packages/twenty-ui/src/surfaces/Popover/__stories__/Popover.stories.tsx
index 032785c4c35..fe32ef7c0fd 100644
--- a/packages/twenty-ui/src/surfaces/Popover/__stories__/Popover.stories.tsx
+++ b/packages/twenty-ui/src/surfaces/Popover/__stories__/Popover.stories.tsx
@@ -122,6 +122,52 @@ export const Default: Story = {
},
};
+export const Documentation: Story = {
+ decorators: [ComponentDecorator],
+ parameters: { container: { width: 240, height: 200 } },
+ render: () => (
+ <Popover.Root>
+ <Popover.Trigger style={{ alignSelf: 'flex-start' }}>
+ Show details
+ </Popover.Trigger>
+ <Popover.Popup>
+ <Popover.Title>Contact details</Popover.Title>
+ <Popover.Description>
+ Add notes and contact information here.
+ </Popover.Description>
+ <Popover.Close>Close</Popover.Close>
+ </Popover.Popup>
+ </Popover.Root>
+ ),
+};
+
+export const DocumentationInteractions: Story = {
+ ...Documentation,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const body = within(canvasElement.ownerDocument.body);
+ const trigger = canvas.getByRole('button', { name: 'Show details' });
+
+ await expect(body.queryByRole('dialog')).not.toBeInTheDocument();
+ await userEvent.click(trigger);
+ const dialog = await body.findByRole('dialog', {
+ name: 'Contact details',
+ });
+
+ await waitFor(() => expect(dialog).toBeVisible());
+ await userEvent.keyboard('{Escape}');
+ await waitFor(() =>
+ expect(body.queryByRole('dialog')).not.toBeInTheDocument(),
+ );
+ await expect(trigger).toHaveFocus();
+ await userEvent.keyboard(' ');
+ await userEvent.click(await body.findByRole('button', { name: 'Close' }));
+ await waitFor(() =>
+ expect(body.queryByRole('dialog')).not.toBeInTheDocument(),
+ );
+ },
+};
+
const ArrowPopoverStory = (props: PopoverStoryProps) => {
const [arrow, setArrow] = useState(true);
diff --git a/yarn.lock b/yarn.lock
index 618838b4651..23019a016e0 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -49140,9 +49140,13 @@ __metadata:
version: 0.0.0-use.local
resolution: "twenty-docs@workspace:packages/twenty-docs"
dependencies:
+ "@mdx-js/mdx": "npm:^3.1.1"
+ "@sniptt/guards": "npm:^0.2.0"
mintlify: "npm:^4.2.790"
+ remark-frontmatter: "npm:^5.0.0"
tsx: "npm:^4.19.3"
twenty-shared: "workspace:*"
+ unist-util-visit: "npm:^5.0.0"
vitest: "npm:^4.1.0"
languageName: unknown
linkType: soft