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.mjsindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsindex 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'"},