Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): add item examples and media slot defaults (#2773)

Cindy Zhanged7d4f399d59
diff --git a/packages/cli/templates/blocks/components/AppShell/AppShellTopNavWithSideNav.doc.mjs b/packages/cli/templates/blocks/components/AppShell/AppShellTopNavWithSideNav.doc.mjs
index 73be6835f1..c7d3b43991 100644
--- a/packages/cli/templates/blocks/components/AppShell/AppShellTopNavWithSideNav.doc.mjs
+++ b/packages/cli/templates/blocks/components/AppShell/AppShellTopNavWithSideNav.doc.mjs
@@ -4,6 +4,7 @@
export const doc = {
type: 'block',
exampleFor: 'AppShell',
+ alsoExampleFor: ['useXDSAppShellMobile'],
name: 'AppShell — Top Nav with Side Nav',
displayName: 'AppShell — Top Nav with Side Nav',
description:
diff --git a/packages/cli/templates/blocks/components/Item/ItemBasicItem.doc.mjs b/packages/cli/templates/blocks/components/Item/ItemBasicItem.doc.mjs
new file mode 100644
index 0000000000..4beddbd2bb
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Item/ItemBasicItem.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Item',
+ name: 'Item — Basic',
+ displayName: 'Item — Basic',
+ description:
+ 'A basic item with a label, supporting description, and trailing timestamp. Use this for simple rows that need consistent text alignment and spacing.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Item', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Item/ItemBasicItem.tsx b/packages/cli/templates/blocks/components/Item/ItemBasicItem.tsx
new file mode 100644
index 0000000000..102397f3ed
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Item/ItemBasicItem.tsx
@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSItem} from '@xds/core/Item';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ItemBasicItem() {
+ return (
+ <XDSStack gap={0}>
+ <XDSItem
+ label="Quarterly planning"
+ description="Agenda, notes, and action items"
+ trailing={<XDSText color="secondary">Today</XDSText>}
+ />
+ <XDSItem
+ label="Customer research"
+ description="Interview notes from the latest study"
+ trailing={<XDSText color="secondary">Yesterday</XDSText>}
+ />
+ <XDSItem
+ label="Launch checklist"
+ description="Remaining tasks before release"
+ trailing={<XDSText color="secondary">Fri</XDSText>}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Item/ItemWithMedia.doc.mjs b/packages/cli/templates/blocks/components/Item/ItemWithMedia.doc.mjs
new file mode 100644
index 0000000000..f04338b2a2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Item/ItemWithMedia.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Item',
+ name: 'Item — Media',
+ displayName: 'Item — Media',
+ description:
+ 'Items with leading avatars and icons in the media slot. Keep media small so the row stays compact and easy to scan.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Item', 'Avatar', 'Badge', 'Icon', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Item/ItemWithMedia.tsx b/packages/cli/templates/blocks/components/Item/ItemWithMedia.tsx
new file mode 100644
index 0000000000..120ea467ba
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Item/ItemWithMedia.tsx
@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSItem} from '@xds/core/Item';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ItemWithMedia() {
+ return (
+ <XDSStack gap={0}>
+ <XDSItem
+ media={<XDSAvatar name="Ada Lovelace" size="xsmall" />}
+ label="Ada Lovelace"
+ description="Design systems engineer"
+ trailing={<XDSBadge label="Owner" variant="purple" />}
+ onClick={() => {}}
+ />
+ <XDSItem
+ media={<XDSAvatar name="Grace Hopper" size="xsmall" />}
+ label="Grace Hopper"
+ description="Compiler platform"
+ trailing={<XDSText color="secondary">Online</XDSText>}
+ onClick={() => {}}
+ />
+ <XDSItem
+ media={<XDSIcon icon="info" size="sm" color="secondary" />}
+ label="Review handoff notes"
+ description="Updated guidance is ready for the team"
+ trailing={<XDSBadge label="New" variant="blue" />}
+ onClick={() => {}}
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Item/ItemWithMetadata.doc.mjs b/packages/cli/templates/blocks/components/Item/ItemWithMetadata.doc.mjs
new file mode 100644
index 0000000000..23a9b7246e
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Item/ItemWithMetadata.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'Item',
+ name: 'Item — Metadata',
+ displayName: 'Item — Metadata',
+ description:
+ 'Items with end-aligned metadata and badges. Use the trailing slot for counts, status, timestamps, and other secondary row information.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Item', 'Badge', 'Icon', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/Item/ItemWithMetadata.tsx b/packages/cli/templates/blocks/components/Item/ItemWithMetadata.tsx
new file mode 100644
index 0000000000..52883bc8a0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Item/ItemWithMetadata.tsx
@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSItem} from '@xds/core/Item';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ItemWithMetadata() {
+ return (
+ <XDSStack gap={0}>
+ <XDSItem
+ media={<XDSIcon icon="check" size="sm" color="success" />}
+ label="Build passed"
+ description="Production deploy completed"
+ trailing={<XDSText color="secondary">2m ago</XDSText>}
+ />
+ <XDSItem
+ media={<XDSIcon icon="warning" size="sm" color="warning" />}
+ label="High memory usage"
+ description="Worker pool is above the warning threshold"
+ trailing={<XDSBadge label="Warning" variant="warning" />}
+ isHighlighted
+ />
+ <XDSItem
+ media={<XDSIcon icon="error" size="sm" color="error" />}
+ label="Sync failed"
+ description="Retry after checking service credentials"
+ trailing={<XDSBadge label="Action" variant="error" />}
+ isSelected
+ />
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemBasicItem.doc.mjs b/packages/cli/templates/blocks/components/ListItem/ListItemBasicItem.doc.mjs
new file mode 100644
index 0000000000..4e7fe7f2b9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemBasicItem.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ListItem',
+ name: 'List Item — Basic',
+ displayName: 'List Item — Basic',
+ description:
+ 'Basic list items with labels and descriptions. Use this structure for settings, navigation summaries, and other simple collections.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['List', 'ListItem'],
+};
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemBasicItem.tsx b/packages/cli/templates/blocks/components/ListItem/ListItemBasicItem.tsx
new file mode 100644
index 0000000000..c9a6bff8e5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemBasicItem.tsx
@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSList, XDSListItem} from '@xds/core/List';
+
+export default function ListItemBasicItem() {
+ return (
+ <XDSList header="Account settings" hasDividers>
+ <XDSListItem label="Profile" description="Name, avatar, and bio" />
+ <XDSListItem label="Notifications" description="Email and push alerts" />
+ <XDSListItem
+ label="Security"
+ description="Password and two-factor auth"
+ />
+ </XDSList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemWithMedia.doc.mjs b/packages/cli/templates/blocks/components/ListItem/ListItemWithMedia.doc.mjs
new file mode 100644
index 0000000000..bfad15f656
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemWithMedia.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ListItem',
+ name: 'List Item — Media',
+ displayName: 'List Item — Media',
+ description:
+ 'List items with leading avatars and icons. Use startContent for compact visual identifiers that help users scan the collection.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['List', 'ListItem', 'Avatar', 'Badge', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemWithMedia.tsx b/packages/cli/templates/blocks/components/ListItem/ListItemWithMedia.tsx
new file mode 100644
index 0000000000..e8775caf7d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemWithMedia.tsx
@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSList, XDSListItem} from '@xds/core/List';
+
+export default function ListItemWithMedia() {
+ return (
+ <XDSList header="Team" hasDividers>
+ <XDSListItem
+ label="Ada Lovelace"
+ description="Design systems engineer"
+ startContent={<XDSAvatar name="Ada Lovelace" size="xsmall" />}
+ endContent={<XDSBadge label="Owner" variant="purple" />}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Grace Hopper"
+ description="Platform infrastructure"
+ startContent={<XDSAvatar name="Grace Hopper" size="xsmall" />}
+ endContent={<XDSBadge label="On call" variant="blue" />}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Invite teammate"
+ description="Send an invitation to collaborate"
+ startContent={<XDSIcon icon="info" size="sm" color="secondary" />}
+ onClick={() => {}}
+ />
+ </XDSList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemWithMetadata.doc.mjs b/packages/cli/templates/blocks/components/ListItem/ListItemWithMetadata.doc.mjs
new file mode 100644
index 0000000000..2bf182b7b4
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemWithMetadata.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'ListItem',
+ name: 'List Item — Metadata',
+ displayName: 'List Item — Metadata',
+ description:
+ 'List items with end-aligned metadata. Use endContent for badges, counts, timestamps, and compact status details.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['List', 'ListItem', 'Badge', 'Icon', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/ListItem/ListItemWithMetadata.tsx b/packages/cli/templates/blocks/components/ListItem/ListItemWithMetadata.tsx
new file mode 100644
index 0000000000..597721037d
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ListItem/ListItemWithMetadata.tsx
@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSList, XDSListItem} from '@xds/core/List';
+import {XDSText} from '@xds/core/Text';
+
+export default function ListItemWithMetadata() {
+ return (
+ <XDSList header="Inbox" density="compact" hasDividers>
+ <XDSListItem
+ label="Launch checklist"
+ description="3 tasks still need an owner"
+ startContent={<XDSIcon icon="check" size="sm" color="success" />}
+ endContent={<XDSBadge label="3" variant="blue" />}
+ isSelected
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Security review"
+ description="Waiting on approval"
+ startContent={<XDSIcon icon="warning" size="sm" color="warning" />}
+ endContent={<XDSText color="secondary">Yesterday</XDSText>}
+ onClick={() => {}}
+ />
+ <XDSListItem
+ label="Old incident report"
+ description="Archived and read-only"
+ startContent={<XDSIcon icon="copy" size="sm" color="secondary" />}
+ endContent={<XDSText color="secondary">Apr 12</XDSText>}
+ isDisabled
+ />
+ </XDSList>
+ );
+}
diff --git a/packages/core/src/Item/Item.doc.mjs b/packages/core/src/Item/Item.doc.mjs
index 6cf3c26617..4395526e36 100644
--- a/packages/core/src/Item/Item.doc.mjs
+++ b/packages/core/src/Item/Item.doc.mjs
@@ -27,7 +27,7 @@ export const docs = {
description: 'A universal item primitive that unifies the "media + label + description + trailing content" layout pattern. Use as a building block for list items, menu items, contact rows, notifications, and more.',
props: [
{name: 'label', type: 'ReactNode', description: 'Primary text identifying this item. Accepts string (auto-truncated) or ReactNode (for rich content).', required: true},
- {name: 'media', type: 'ReactNode', description: 'Leading visual — avatar, icon, image, or any ReactNode.', slotElements: [{__element: 'XDSAvatar', props: {size: 'sm'}}, {__element: 'XDSIcon', props: {icon: 'user', size: 'sm'}}]},
+ {name: 'media', type: 'ReactNode', description: 'Leading visual — avatar, icon, image, or any ReactNode.', slotElements: [{__element: 'XDSAvatar', props: {name: 'Ada Lovelace', size: 'xsmall'}}, {__element: 'XDSIcon', props: {icon: 'info', size: 'sm', color: 'secondary'}}]},
{name: 'description', type: 'ReactNode', description: 'Secondary text — subtitle, description, or supporting info.'},
{name: 'trailing', type: 'ReactNode', description: 'Trailing content — badges, metadata, timestamps, action buttons. Positioned at the end, flex-shrink: 0.', slotElements: [{__element: 'XDSBadge', props: {label: 3}}, {__element: 'XDSText', props: {color: 'secondary'}, children: '2h ago'}]},
{name: 'as', type: "'div' | 'li' | 'span'", description: 'HTML element to render as the root.', default: "'div'"},