An open source design system that's fully customizable and agent ready
TypeScript
fix(storybook): clean up descriptions and example code blocks (#376)
Cindy Zhang2d0f2b0f80f3
diff --git a/.github/scripts/generate-pr-comment.js b/.github/scripts/generate-pr-comment.jsindex 3f51e75c71..f8131b9e56 100644--- a/.github/scripts/generate-pr-comment.js+++ b/.github/scripts/generate-pr-comment.js@@ -57,9 +57,12 @@ try {// Build a Storybook deep link URL for a component// Story titles like "Core/XDSButton" become path "/docs/core-xdsbutton--docs"function getStorybookLink(storybookBaseUrl, storyTitle) {- if (!storybookBaseUrl || !storyTitle || typeof storyTitle !== 'string') return null;+ if (!storybookBaseUrl || !storyTitle) return null;+ // storyTitle may be a single string or an array when multiple story files match+ const title = Array.isArray(storyTitle) ? storyTitle[0] : storyTitle;+ if (!title) return null;// Storybook converts "Core/XDSButton" to "core-xdsbutton" as the story ID prefix- const storyPath = storyTitle.toLowerCase().replace(/\//g, '-');+ const storyPath = title.toLowerCase().replace(/\//g, '-');return `${storybookBaseUrl}?path=/docs/${storyPath}--docs`;}diff --git a/CLAUDE.md b/CLAUDE.mdindex eca77a4dba..cb2bc31b43 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -79,3 +79,8 @@ Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.- **Testing**: Vitest (colocated tests)- **Components**: `packages/core/`- **Storybook**: `apps/storybook/`++## JSDoc Conventions++- **`@example` code fences must use plain ` ``` `, not ` ```tsx `.**+ Storybook's autodocs parser doesn't handle language-tagged fences in JSDoc correctly — the code block won't render as a proper code block. Always use untagged fences in `@example` blocks.diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsxindex 3da43116a2..3a891d5aa2 100644--- a/packages/core/src/AppShell/XDSAppShell.tsx+++ b/packages/core/src/AppShell/XDSAppShell.tsx@@ -264,60 +264,27 @@ const dynamicStyles = stylex.create({/*** Application-level layout shell. Provides the structural frame for an app:- * header, side navigation, and main content area.+ * top navigation, side navigation, and main content area.*- * Composes XDSLayout internally. Replaces internal XDSPage + XDSPageLayout pattern.- *- * Features:- * - Slot-based API: `topNav`, `sideNav`, `banner`, `children`- * - Two height modes: `fill` (100dvh, independent scroll) and `auto` (page scroll, sticky navs)- * - SideNav collapse: controlled + uncontrolled patterns- * - Responsive sideNav collapse via breakpoint- * - Mobile overlay sideNav with backdrop- * - Skip-to-content link- * - Semantic HTML: `<header>`, `<nav>`, `<main>`+ * Slot-based API with `topNav`, `sideNav`, `banner`, and `children`.+ * Supports two height modes (`fill` and `auto`), responsive side nav+ * collapse, and mobile overlay with backdrop.** @example- * ```tsx- * // TopNav + SideNav — the most common pattern.- * // SideNav omits its header because TopNav provides app identity.+ * ```* <XDSAppShell- * topNav={- * <XDSTopNav- * label="Main navigation"- * title={<XDSTopNavTitle title="My App" logo={<Logo />} />}- * startContent={<XDSTopNavItem label="Home" href="/" isSelected />}- * />- * }+ * topNav={<XDSTopNav label="Navigation" title={<XDSTopNavTitle title="My App" />} />}* sideNav={* <XDSSideNav>* <XDSSideNavSection title="Main" isHeaderHidden>- * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />- * <XDSSideNavItem label="Analytics" icon={ChartBarIcon} href="/analytics" />+ * <XDSSideNavItem label="Dashboard" isSelected href="/dashboard" />+ * <XDSSideNavItem label="Analytics" href="/analytics" />* </XDSSideNavSection>* </XDSSideNav>* }* >* <DashboardContent />* </XDSAppShell>- *- * // SideNav only — header provides app identity when there's no TopNav- * <XDSAppShell- * sideNav={- * <XDSSideNav header={<XDSSideNavHeader title="My App" titleHref="/" />}>- * <XDSSideNavSection title="Main" isHeaderHidden>- * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected />- * </XDSSideNavSection>- * </XDSSideNav>- * }- * >- * <DashboardContent />- * </XDSAppShell>- *- * // TopNav only (no sideNav)- * <XDSAppShell topNav={<XDSTopNav title="Landing" />}>- * <LandingContent />- * </XDSAppShell>* ```*/export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsxindex 6a66277aa0..ffebf0c09f 100644--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx@@ -76,7 +76,7 @@ const styles = stylex.create({* videos, embeds, and placeholders.** @example- * ```tsx+ * ```* <XDSAspectRatio ratio={16 / 9}>* <img src="image.jpg" alt="Widescreen image" style={{objectFit: 'cover'}} />* </XDSAspectRatio>diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsxindex 7971a668d4..519df9ae03 100644--- a/packages/core/src/Avatar/XDSAvatar.tsx+++ b/packages/core/src/Avatar/XDSAvatar.tsx@@ -251,7 +251,7 @@ function DefaultIcon({size}: {size: number}) {* the name prop, or a generic person icon if neither is provided.** @example- * ```tsx+ * ```* <XDSAvatar src="/user.jpg" name="John Doe" />* <XDSAvatar name="Jane Smith" size="large" />* <XDSAvatar src="/user.jpg" status={<OnlineIndicator />} />diff --git a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx b/packages/core/src/Avatar/XDSAvatarStatusDot.tsxindex e35dfdef72..7ce472ca8d 100644--- a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx+++ b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx@@ -74,7 +74,7 @@ export interface XDSAvatarStatusDotProps extends Omit<* at the smallest avatar sizes where there isn't enough room.** @example- * ```tsx+ * ```* <XDSAvatarStatusDot variant="positive" label="Verified" icon={<CheckIcon />} />* ```*/@@ -136,7 +136,7 @@ const variantStyleMap: Record<XDSAvatarStatusDotVariant, stylex.StyleXStyles> =* the avatar size from context.** @example- * ```tsx+ * ```* // Presence indicator* <XDSAvatar* name="John Doe"diff --git a/packages/core/src/Badge/XDSBadge.tsx b/packages/core/src/Badge/XDSBadge.tsxindex 41aed50a77..3c99b38ba3 100644--- a/packages/core/src/Badge/XDSBadge.tsx+++ b/packages/core/src/Badge/XDSBadge.tsx@@ -125,7 +125,7 @@ export interface XDSBadgeProps extends Omit<* Wrap your app in <Theme> to apply a theme.** @example- * ```tsx+ * ```* <XDSBadge>Default</XDSBadge>* <XDSBadge variant="success">Active</XDSBadge>* <XDSBadge variant="error">3</XDSBadge>diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsxindex e0dcc4706c..f31dbcd297 100644--- a/packages/core/src/Banner/XDSBanner.tsx+++ b/packages/core/src/Banner/XDSBanner.tsx@@ -279,7 +279,7 @@ const statusStyles = stylex.create({* Uses `role="alert"` for error/warning and `role="status"` for info/success.** @example- * ```tsx+ * ```* // Simple banner — just the colored header* <XDSBanner status="info" title="New update available" />*diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsxindex f2f57c067f..6a3ddc3d8a 100644--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx@@ -129,7 +129,7 @@ const itemStyles = stylex.create({* depending on whether it represents the current page.** @example- * ```tsx+ * ```* <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>* <XDSBreadcrumbItem isCurrent>My Project</XDSBreadcrumbItem>* ```diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsxindex a546eccd9b..cd8077e1ca 100644--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx@@ -140,7 +140,7 @@ const separatorStyles = stylex.create({* `isCurrent` explicitly set.** @example- * ```tsx+ * ```* <XDSBreadcrumbs>* <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>* <XDSBreadcrumbItem href="/projects">Projects</XDSBreadcrumbItem>diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsxindex d16b5f97de..889b036095 100644--- a/packages/core/src/Button/XDSButton.tsx+++ b/packages/core/src/Button/XDSButton.tsx@@ -287,7 +287,7 @@ const loadingStyles = stylex.create({* Themes can provide component-level variant overrides via theme.components.button.variants** @example- * ```tsx+ * ```* <XDSButton label="Click me" />* <XDSButton label="Primary action" variant="primary" />* <XDSButton label="Delete" variant="destructive" />diff --git a/packages/core/src/Calendar/hooks/useCalendarConstraints.ts b/packages/core/src/Calendar/hooks/useCalendarConstraints.tsindex 5db4e3b16c..cb543c5e34 100644--- a/packages/core/src/Calendar/hooks/useCalendarConstraints.ts+++ b/packages/core/src/Calendar/hooks/useCalendarConstraints.ts@@ -53,7 +53,7 @@ function parseISO(str: ISODateString): Date {* min/max bounds and custom constraint functions.** @example- * ```tsx+ * ```* const {isDateDisabled} = useCalendarConstraints({* min: '2026-01-01',* max: '2026-12-31',diff --git a/packages/core/src/Calendar/hooks/useCalendarDays.ts b/packages/core/src/Calendar/hooks/useCalendarDays.tsindex 37231e8183..6d0dc5009e 100644--- a/packages/core/src/Calendar/hooks/useCalendarDays.ts+++ b/packages/core/src/Calendar/hooks/useCalendarDays.ts@@ -70,7 +70,7 @@ function dateToISO(date: Date): ISODateString {* days from adjacent months to fill the grid.** @example- * ```tsx+ * ```* const {days, weeks, dayNames} = useCalendarDays({* year: 2026,* month: 0, // Januarydiff --git a/packages/core/src/Calendar/hooks/useCalendarNavigation.ts b/packages/core/src/Calendar/hooks/useCalendarNavigation.tsindex f4839c74ef..1cfcaf970e 100644--- a/packages/core/src/Calendar/hooks/useCalendarNavigation.ts+++ b/packages/core/src/Calendar/hooks/useCalendarNavigation.ts@@ -72,7 +72,7 @@ function parseISO(str: ISODateString): Date {* navigation, and pending focus for keyboard navigation across months.** @example- * ```tsx+ * ```* const {* visibleMonths,* monthYearLabel,diff --git a/packages/core/src/Calendar/hooks/useCalendarRovingTabindex.ts b/packages/core/src/Calendar/hooks/useCalendarRovingTabindex.tsindex 140ec8211e..a854e262ad 100644--- a/packages/core/src/Calendar/hooks/useCalendarRovingTabindex.ts+++ b/packages/core/src/Calendar/hooks/useCalendarRovingTabindex.ts@@ -59,7 +59,7 @@ function dateToISO(date: Date): ISODateString {* 2. First enabled day in the month** @example- * ```tsx+ * ```* const {tabbableDate, isTabbable} = useCalendarRovingTabindex({* days,* today: new Date(),diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsxindex 9dd763704d..ab31698b29 100644--- a/packages/core/src/Card/XDSCard.tsx+++ b/packages/core/src/Card/XDSCard.tsx@@ -130,7 +130,7 @@ export interface XDSCardProps {* Pair with XDSLayout for structured header/content/footer layouts.** @example- * ```tsx+ * ```* <XDSCard width={400} height={300}>* <XDSLayout* header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}diff --git a/packages/core/src/Center/XDSCenter.tsx b/packages/core/src/Center/XDSCenter.tsxindex dede797f28..d1ece70c5a 100644--- a/packages/core/src/Center/XDSCenter.tsx+++ b/packages/core/src/Center/XDSCenter.tsx@@ -108,7 +108,7 @@ export interface XDSCenterProps extends Omit<* Use the `axis` prop to center on only one axis.** @example- * ```tsx+ * ```* <XDSCenter width={300} height={200}>* <Content />* </XDSCenter>diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsxindex 0044b39f17..b738cd1141 100644--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx@@ -289,7 +289,7 @@ export interface XDSCheckboxInputProps {* A checkbox input component for toggling boolean values.** @example- * ```tsx+ * ```* <XDSCheckboxInput* label="Accept terms"* value={accepted}diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsxindex d4fc1acc06..b74fa8d74e 100644--- a/packages/core/src/Collapsible/XDSCollapsible.tsx+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx@@ -118,24 +118,21 @@ export interface XDSCollapsibleProps {* Handles its own state by default, or defers to XDSCollapsibleGroup* when a `value` prop is provided and a group is present.*- * @compositionHint Use inside XDSCard for elevated collapsible sections.+ * Use inside XDSCard for elevated collapsible sections.* Wrap multiple instances in XDSCollapsibleGroup for accordion behavior.** @example- * ```tsx- * // Standalone+ * ```* <XDSCollapsible trigger="Details">- * <p>Collapsible content</p>+ * <XDSText type="body">Collapsible content</XDSText>* </XDSCollapsible>*- * // Inside a card* <XDSCard>* <XDSCollapsible trigger="Settings">* <SettingsForm />* </XDSCollapsible>* </XDSCard>*- * // Accordion (coordinated group)* <XDSCollapsibleGroup type="single" defaultValue="general">* <XDSVStack gap="space2">* <XDSCard>diff --git a/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx b/packages/core/src/Collapsible/XDSCollapsibleGroup.tsxindex 64d8aedffb..ce1e69dc76 100644--- a/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx+++ b/packages/core/src/Collapsible/XDSCollapsibleGroup.tsx@@ -55,7 +55,7 @@ export interface XDSCollapsibleGroupProps {* Each XDSCollapsible needs a `value` prop to participate in the group.** @example- * ```tsx+ * ```* <XDSCollapsibleGroup type="single" defaultValue="general">* <XDSVStack gap="space2">* <XDSCard>@@ -91,7 +91,7 @@ function normalizeToArray(value: string | string[] | undefined): string[] {* Each XDSCollapsible needs a `value` prop to participate.** @example- * ```tsx+ * ```* <XDSCollapsibleGroup type="single" defaultValue="faq1">* <XDSVStack gap="space2">* <XDSCard>diff --git a/packages/core/src/Collapsible/useXDSCollapsible.ts b/packages/core/src/Collapsible/useXDSCollapsible.tsindex 512f3424bd..b51cd89d64 100644--- a/packages/core/src/Collapsible/useXDSCollapsible.ts+++ b/packages/core/src/Collapsible/useXDSCollapsible.ts@@ -65,7 +65,7 @@ export interface UseXDSCollapsibleReturn {* 3. **Uncontrolled**: Self-managed internal state with optional `initialIsOpen`.** @example- * ```tsx+ * ```* const {isEnabled, isOpen, toggle} = useXDSCollapsible({* isCollapsible: true,* value: 'section-1',diff --git a/packages/core/src/DateInput/XDSDateInput.tsx b/packages/core/src/DateInput/XDSDateInput.tsxindex 13d15fb8c0..16b28f78c5 100644--- a/packages/core/src/DateInput/XDSDateInput.tsx+++ b/packages/core/src/DateInput/XDSDateInput.tsx@@ -340,7 +340,7 @@ export interface XDSDateInputProps {* A date picker component combining a text input with a calendar popover.** @example- * ```tsx+ * ```* <XDSDateInput* label="Event date"* value={date}diff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsxindex 83066755a5..dcbc9f55a1 100644--- a/packages/core/src/Dialog/XDSDialog.tsx+++ b/packages/core/src/Dialog/XDSDialog.tsx@@ -221,7 +221,7 @@ export interface XDSDialogProps extends Omit<* Uses the browser's built-in modal behavior for optimal accessibility.** @example- * ```tsx+ * ```* const [isShown, setIsShown] = useState(false);** <XDSDialog isShown={isShown} onHide={() => setIsShown(false)}>diff --git a/packages/core/src/Dialog/XDSDialogHeader.tsx b/packages/core/src/Dialog/XDSDialogHeader.tsxindex 54a6b15808..56d3599d90 100644--- a/packages/core/src/Dialog/XDSDialogHeader.tsx+++ b/packages/core/src/Dialog/XDSDialogHeader.tsx@@ -92,7 +92,7 @@ export interface XDSDialogHeaderProps {* Uses XDSLayoutHeader internally for consistent styling with other layout headers.** @example- * ```tsx+ * ```* <XDSDialog isShown={isShown} onHide={() => setIsShown(false)}>* <XDSLayout* header={<XDSDialogHeader title="Modal Title" onHide={() => setIsShown(false)} />}diff --git a/packages/core/src/Divider/XDSDivider.tsx b/packages/core/src/Divider/XDSDivider.tsxindex 7ab8ddc980..06902ea130 100644--- a/packages/core/src/Divider/XDSDivider.tsx+++ b/packages/core/src/Divider/XDSDivider.tsx@@ -143,7 +143,7 @@ const fullBleedStyles = stylex.create({* Uses XDS design tokens for colors and spacing.** @example- * ```tsx+ * ```* <XDSDivider label="or" />* ```*/diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsxindex b475a46748..c6128e5787 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenu.tsx@@ -304,7 +304,7 @@ function DefaultItem({item}: {item: XDSDropdownMenuItemData}) {* it's purely for displaying a menu of clickable items.** @example- * ```tsx+ * ```* <XDSDropdownMenu* button={{ label: 'Actions' }}* items={[diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsxindex 8d6e3db6a2..b29f72c4cb 100644--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx@@ -68,7 +68,7 @@ export interface XDSDropdownMenuItemProps {* custom item layouts while maintaining design system consistency.** @example- * ```tsx+ * ```* <XDSDropdownMenu* button={{ label: 'Actions' }}* items={actions}>diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsxindex dce43aba49..6d6802780f 100644--- a/packages/core/src/EmptyState/XDSEmptyState.tsx+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx@@ -120,7 +120,7 @@ export interface XDSEmptyStateProps {* Styles use XDS theme tokens via StyleX. Wrap your app in <Theme> to apply a theme.** @example- * ```tsx+ * ```* <XDSEmptyState* title="No results found"* description="Try adjusting your search or filters."diff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsxindex 61e21adb27..243c62c157 100644--- a/packages/core/src/Field/XDSField.tsx+++ b/packages/core/src/Field/XDSField.tsx@@ -177,7 +177,7 @@ export interface XDSFieldProps extends Omit<* A form field wrapper that provides label and description.** @example- * ```tsx+ * ```* const id = useId();* const descID = useId();* <XDSField label="Email" description="We'll never share your email" inputID={id} descriptionID={descID}>diff --git a/packages/core/src/Field/XDSFieldLabel.tsx b/packages/core/src/Field/XDSFieldLabel.tsxindex 926ebcc39f..73e6a37e8a 100644--- a/packages/core/src/Field/XDSFieldLabel.tsx+++ b/packages/core/src/Field/XDSFieldLabel.tsx@@ -104,7 +104,7 @@ export interface XDSFieldLabelProps {* A label component for form fields with support for hidden and disabled states.** @example- * ```tsx+ * ```* <XDSFieldLabel label="Email" inputID={inputId} />* <XDSFieldLabel label="Hidden label" inputID={inputId} isLabelHidden />* ```diff --git a/packages/core/src/Field/XDSFieldStatus.tsx b/packages/core/src/Field/XDSFieldStatus.tsxindex 0e604ae377..fe25f0e2a1 100644--- a/packages/core/src/Field/XDSFieldStatus.tsx+++ b/packages/core/src/Field/XDSFieldStatus.tsx@@ -85,7 +85,7 @@ export interface XDSFieldStatusProps {* A status message component for form fields.** @example- * ```tsx+ * ```* <XDSFieldStatus* type="error"* message="This field is required"diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsxindex 8b4cb33bf5..d4f0c1302d 100644--- a/packages/core/src/Grid/XDSGrid.tsx+++ b/packages/core/src/Grid/XDSGrid.tsx@@ -332,7 +332,7 @@ function calculateMaxWidth(* - Both: Auto-fit responsive, capped at max columns** @example- * ```tsx+ * ```* <XDSGrid columns={3} gap="space4">* <Item />* <Item />diff --git a/packages/core/src/Grid/XDSGridSpan.tsx b/packages/core/src/Grid/XDSGridSpan.tsxindex 29d1382929..48bd5eeb57 100644--- a/packages/core/src/Grid/XDSGridSpan.tsx+++ b/packages/core/src/Grid/XDSGridSpan.tsx@@ -59,7 +59,7 @@ const baseStyles = stylex.create({* or rows.** @example- * ```tsx+ * ```* <XDSGrid columns={3} gap="space4">* <XDSGridSpan columns={2}>Wide item</XDSGridSpan>* <div>Normal</div>diff --git a/packages/core/src/Icon/IconRegistry.tsx b/packages/core/src/Icon/IconRegistry.tsxindex a4aed81a05..62e8693038 100644--- a/packages/core/src/Icon/IconRegistry.tsx+++ b/packages/core/src/Icon/IconRegistry.tsx@@ -72,7 +72,7 @@ export const IconRegistryContext =* 2. Built-in lightweight SVG fallback** @example- * ```tsx+ * ```* const closeIcon = useXDSIcon('close');* // Returns the theme's close icon, or the built-in SVG fallback* ```diff --git a/packages/core/src/Layer/XDSHoverCard.tsx b/packages/core/src/Layer/XDSHoverCard.tsxindex 402c66a67a..d668d30b92 100644--- a/packages/core/src/Layer/XDSHoverCard.tsx+++ b/packages/core/src/Layer/XDSHoverCard.tsx@@ -143,7 +143,7 @@ function mergeIds(...ids: (string | undefined | null)[]): string | undefined {* Uses CSS anchor positioning and the Popover API for optimal performance.** @example- * ```tsx+ * ```* <XDSHoverCard* content={<ProfileCard user={user} />}* placement="above"diff --git a/packages/core/src/Layer/XDSTooltip.tsx b/packages/core/src/Layer/XDSTooltip.tsxindex 4f0fd9b82e..655b3ce937 100644--- a/packages/core/src/Layer/XDSTooltip.tsx+++ b/packages/core/src/Layer/XDSTooltip.tsx@@ -155,7 +155,7 @@ function mergeIds(...ids: (string | undefined | null)[]): string | undefined {* Uses CSS anchor positioning and the Popover API for optimal performance.** @example- * ```tsx+ * ```* <XDSTooltip content="Helpful tooltip text" placement="above">* <XDSButton>Hover me</XDSButton>* </XDSTooltip>diff --git a/packages/core/src/Layer/useXDSHoverCard.tsx b/packages/core/src/Layer/useXDSHoverCard.tsxindex 0f071e586a..ae0646fdd2 100644--- a/packages/core/src/Layer/useXDSHoverCard.tsx+++ b/packages/core/src/Layer/useXDSHoverCard.tsx@@ -213,7 +213,7 @@ function isFocusable(element: HTMLElement): boolean {* - Stay-open behavior when mouse/focus moves into the hover card** @example- * ```tsx+ * ```* // Simple case: use combined ref* const hoverCard = useXDSHoverCard({ placement: 'above' });*diff --git a/packages/core/src/Layer/useXDSLayer.tsx b/packages/core/src/Layer/useXDSLayer.tsxindex ae041c4d52..0b81b3fa72 100644--- a/packages/core/src/Layer/useXDSLayer.tsx+++ b/packages/core/src/Layer/useXDSLayer.tsx@@ -231,7 +231,7 @@ function getPositionArea(* - `fixed`: Fixed positioning at specified coordinates** @example- * ```tsx+ * ```* // Context mode (anchor positioning)* const layer = useXDSLayer({ mode: 'context' });*diff --git a/packages/core/src/Layer/useXDSPopover.tsx b/packages/core/src/Layer/useXDSPopover.tsxindex 78aadbc272..8e423a992f 100644--- a/packages/core/src/Layer/useXDSPopover.tsx+++ b/packages/core/src/Layer/useXDSPopover.tsx@@ -190,7 +190,7 @@ export interface UseXDSPopoverReturn {* Automatically wraps content in a focus trap container with a hidden close button.** @example- * ```tsx+ * ```* {popover.render(* <Calendar />,* { placement: 'below', alignment: 'start' }@@ -224,7 +224,7 @@ export interface UseXDSPopoverReturn {* is visually hidden until focused, then shows a tooltip-like message (default: "Close popover").** @example- * ```tsx+ * ```* function DatePickerExample() {* const inputRef = useRef<HTMLInputElement>(null);* const popover = useXDSPopover({diff --git a/packages/core/src/Layer/useXDSTooltip.tsx b/packages/core/src/Layer/useXDSTooltip.tsxindex 94786cfb2f..0e224de735 100644--- a/packages/core/src/Layer/useXDSTooltip.tsx+++ b/packages/core/src/Layer/useXDSTooltip.tsx@@ -224,7 +224,7 @@ function isFocusable(element: HTMLElement): boolean {* - Are typically used for short, non-interactive text** @example- * ```tsx+ * ```* const tooltip = useXDSTooltip({ placement: 'above' });** <XDSButton ref={tooltip.ref} aria-describedby={tooltip.describedBy}>diff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsxindex 7908362783..1f67fd1abe 100644--- a/packages/core/src/Layout/XDSLayout.tsx+++ b/packages/core/src/Layout/XDSLayout.tsx@@ -145,7 +145,7 @@ function AreaProvider({* - Simple vertical stack of items → use XDSVStack instead** @example- * ```tsx+ * ```* // Full-page app shell with sidebar navigation* <XDSLayout* header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}diff --git a/packages/core/src/Layout/XDSLayoutContent.tsx b/packages/core/src/Layout/XDSLayoutContent.tsxindex ce3058c2fe..343d273cbf 100644--- a/packages/core/src/Layout/XDSLayoutContent.tsx+++ b/packages/core/src/Layout/XDSLayoutContent.tsx@@ -101,7 +101,7 @@ export interface XDSLayoutContentProps extends Omit<* overflow to children. Use `isFullBleed` if you need edge-to-edge content.** @example- * ```tsx+ * ```* <XDSLayoutContainer variant="card">* <XDSLayout* header={<XDSLayoutHeader>Title</XDSLayoutHeader>}diff --git a/packages/core/src/Layout/XDSLayoutFooter.tsx b/packages/core/src/Layout/XDSLayoutFooter.tsxindex 75fddc66f5..fe1b61bec5 100644--- a/packages/core/src/Layout/XDSLayoutFooter.tsx+++ b/packages/core/src/Layout/XDSLayoutFooter.tsx@@ -98,7 +98,7 @@ export interface XDSLayoutFooterProps extends Omit<* Use `isFullBleed` if your content manages its own padding.** @example- * ```tsx+ * ```* <XDSLayoutContainer variant="card">* <XDSLayout* content={<XDSLayoutContent>...</XDSLayoutContent>}diff --git a/packages/core/src/Layout/XDSLayoutHeader.tsx b/packages/core/src/Layout/XDSLayoutHeader.tsxindex c2d15fc7fd..3138395944 100644--- a/packages/core/src/Layout/XDSLayoutHeader.tsx+++ b/packages/core/src/Layout/XDSLayoutHeader.tsx@@ -98,7 +98,7 @@ export interface XDSLayoutHeaderProps extends Omit<* Use `isFullBleed` if your content manages its own padding (e.g. XDSTopNav).** @example- * ```tsx+ * ```* <XDSLayoutContainer variant="card">* <XDSLayout* header={<XDSLayoutHeader hasDivider>Page Title</XDSLayoutHeader>}diff --git a/packages/core/src/Layout/XDSLayoutPanel.tsx b/packages/core/src/Layout/XDSLayoutPanel.tsxindex fac6e9d720..806cbd7815 100644--- a/packages/core/src/Layout/XDSLayoutPanel.tsx+++ b/packages/core/src/Layout/XDSLayoutPanel.tsx@@ -144,7 +144,7 @@ export interface XDSLayoutPanelProps extends Omit<* overflow to children. Use `isFullBleed` if you need edge-to-edge content.** @example- * ```tsx+ * ```* <XDSLayoutContainer variant="card">* <XDSLayout* start={diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.tsindex 7860e90c13..c66461a610 100644--- a/packages/core/src/Layout/container.stylex.ts+++ b/packages/core/src/Layout/container.stylex.ts@@ -173,7 +173,7 @@ export interface ContainerOptions {* - `--layout-padding-inner-x`, `--layout-padding-inner-y`** @example- * ```tsx+ * ```* import { container } from '@xds/core/Layout';* import * as stylex from '@stylexjs/stylex';*diff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsxindex e11d757764..019242e8ac 100644--- a/packages/core/src/Link/XDSLink.tsx+++ b/packages/core/src/Link/XDSLink.tsx@@ -219,7 +219,7 @@ export interface XDSLinkProps extends Omit<* Wrap your app in <Theme> to apply a theme.** @example- * ```tsx+ * ```* // Basic link* <XDSLink label="Documentation" href="/docs">Documentation</XDSLink>*diff --git a/packages/core/src/Link/XDSLinkProvider.tsx b/packages/core/src/Link/XDSLinkProvider.tsxindex 88f7e5bd2b..a27957f04d 100644--- a/packages/core/src/Link/XDSLinkProvider.tsx+++ b/packages/core/src/Link/XDSLinkProvider.tsx@@ -8,7 +8,7 @@* Individual components can still override via the `as` prop.** @example- * ```tsx+ * ```* import Link from 'next/link';** <XDSLinkProvider component={Link}>@@ -33,7 +33,7 @@ export interface XDSLinkProviderProps {* Must accept href, className, style, and children props.** @example- * ```tsx+ * ```* import Link from 'next/link';* <XDSLinkProvider component={Link}>* ```diff --git a/packages/core/src/Link/useXDSLinkComponent.ts b/packages/core/src/Link/useXDSLinkComponent.tsindex 40146e4823..5f5f497f0e 100644--- a/packages/core/src/Link/useXDSLinkComponent.ts+++ b/packages/core/src/Link/useXDSLinkComponent.ts@@ -26,7 +26,7 @@ import type {XDSLinkComponentType} from './types';* @returns The resolved link component.** @example- * ```tsx+ * ```* function MyComponent({ as }: { as?: XDSLinkComponentType }) {* const LinkComponent = useXDSLinkComponent(as);* return <LinkComponent href="/foo">Click me</LinkComponent>;diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsxindex 4b969817cf..a29bbfed67 100644--- a/packages/core/src/List/XDSList.tsx+++ b/packages/core/src/List/XDSList.tsx@@ -120,7 +120,7 @@ const listStyleTypes = stylex.create({* dividers, marker styles, and an optional header.** @example- * ```tsx+ * ```* <XDSList>* <XDSListItem label="Notifications" description="Manage your alerts" />* <XDSListItem label="Privacy" description="Control your data" />diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsxindex 2b9c2637ef..a998c79752 100644--- a/packages/core/src/List/XDSListItem.tsx+++ b/packages/core/src/List/XDSListItem.tsx@@ -257,7 +257,7 @@ const descriptionSizeStyles = stylex.create({* When `href` is provided, uses an invisible anchor pattern.** @example- * ```tsx+ * ```* <XDSListItem label="Settings" description="Manage your preferences" />* <XDSListItem label="Profile" onClick={() => navigate('/profile')} />* <XDSListItem label="Docs" href="/docs" target="_blank" />diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsxindex 12d61ba3e1..65975d71f9 100644--- a/packages/core/src/NavIcon/XDSNavIcon.tsx+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx@@ -51,7 +51,7 @@ export interface XDSNavIconProps extends Omit<* use as a logo in top navigation or side navigation title areas.** @example- * ```tsx+ * ```* import {HomeIcon} from '@heroicons/react/24/solid';** // In XDSTopNavTitlediff --git a/packages/core/src/NumberInput/XDSNumberInput.tsx b/packages/core/src/NumberInput/XDSNumberInput.tsxindex f2d9cf2e12..92a112541f 100644--- a/packages/core/src/NumberInput/XDSNumberInput.tsx+++ b/packages/core/src/NumberInput/XDSNumberInput.tsx@@ -371,7 +371,7 @@ function parseNumberInput(* Only calls onChange when the entered value passes validation.** @example- * ```tsx+ * ```* <XDSNumberInput label="Quantity" value={quantity} onChange={setQuantity} />* <XDSNumberInput label="Price" value={price} onChange={setPrice} min={0} step={0.01} />* ```diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsxindex 22d2e0367f..712b63657c 100644--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx@@ -221,7 +221,7 @@ function defaultFormatValueLabel(value: number, max: number): string {* Wrap your app in <Theme> to apply a theme.** @example- * ```tsx+ * ```* // Determinate* <XDSProgressBar value={75} label="Upload progress" />*diff --git a/packages/core/src/RadioList/XDSRadioList.tsx b/packages/core/src/RadioList/XDSRadioList.tsxindex ad6ed48669..4141e2d38f 100644--- a/packages/core/src/RadioList/XDSRadioList.tsx+++ b/packages/core/src/RadioList/XDSRadioList.tsx@@ -140,7 +140,7 @@ export interface XDSRadioListProps {* A radio group component for single-value selection.** @example- * ```tsx+ * ```* <XDSRadioList* label="Notification preference"* value={selected}diff --git a/packages/core/src/RadioList/XDSRadioListItem.tsx b/packages/core/src/RadioList/XDSRadioListItem.tsxindex eac8b804e9..164e662422 100644--- a/packages/core/src/RadioList/XDSRadioListItem.tsx+++ b/packages/core/src/RadioList/XDSRadioListItem.tsx@@ -222,7 +222,7 @@ export interface XDSRadioListItemProps {* An individual radio item within an XDSRadioList.** @example- * ```tsx+ * ```* <XDSRadioListItem label="Email" value="email" />* <XDSRadioListItem* label="SMS"diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsxindex a781a72700..143d342540 100644--- a/packages/core/src/Section/XDSSection.tsx+++ b/packages/core/src/Section/XDSSection.tsx@@ -191,7 +191,7 @@ export interface XDSSectionProps {* Sections automatically escape parent container padding for edge-to-edge fills.** @example- * ```tsx+ * ```* <XDSSection variant="wash" width={300} height={250}>* <XDSLayout* content={<XDSLayoutContent>Content in wash section</XDSLayoutContent>}diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsxindex 3327f6a4f2..df56a40739 100644--- a/packages/core/src/Selector/XDSSelector.tsx+++ b/packages/core/src/Selector/XDSSelector.tsx@@ -427,7 +427,7 @@ function DefaultItem({item}: {item: XDSSelectorItemData}) {* A selector/dropdown component for choosing from a list of options.** @example- * ```tsx+ * ```* <XDSSelector* label="Fruit"* items={['Apple', 'Banana', 'Orange']}diff --git a/packages/core/src/Selector/XDSSelectorItem.tsx b/packages/core/src/Selector/XDSSelectorItem.tsxindex b3eb486b94..b5b6078278 100644--- a/packages/core/src/Selector/XDSSelectorItem.tsx+++ b/packages/core/src/Selector/XDSSelectorItem.tsx@@ -62,7 +62,7 @@ export interface XDSSelectorItemProps {* custom item layouts while maintaining design system consistency.** @example- * ```tsx+ * ```* <XDSSelector* label="User"* items={users}diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsxindex b60889157e..4cafa9bac9 100644--- a/packages/core/src/SideNav/XDSSideNav.tsx+++ b/packages/core/src/SideNav/XDSSideNav.tsx@@ -140,19 +140,18 @@ export interface XDSSideNavProps extends Omit</*** Sidebar navigation container for application pages.*- * Provides five zones stacked vertically: a sticky header + action area (stuck together),- * scrollable nav content, and a sticky bottom footer + footer icon bar.+ * Five vertical zones: sticky header + action area at top,+ * scrollable nav content in the middle, and sticky footer + icon bar at bottom.** @example- * ```tsx+ * ```* <XDSSideNav- * header={<XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />}+ * header={<XDSSideNavHeader title="My App" titleHref="/" />}* topContent={<XDSButton label="Create new" variant="primary" />}- * footerIcons={<XDSButton icon={HelpIcon} variant="ghost" label="Help" />}* >* <XDSSideNavSection title="Main">- * <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected href="/dashboard" />- * <XDSSideNavItem label="Projects" icon={FolderIcon} href="/projects" />+ * <XDSSideNavItem label="Dashboard" isSelected href="/dashboard" />+ * <XDSSideNavItem label="Projects" href="/projects" />* </XDSSideNavSection>* </XDSSideNav>* ```diff --git a/packages/core/src/SideNav/XDSSideNavHeader.tsx b/packages/core/src/SideNav/XDSSideNavHeader.tsxindex 8f1938ceb8..82713c4b96 100644--- a/packages/core/src/SideNav/XDSSideNavHeader.tsx+++ b/packages/core/src/SideNav/XDSSideNavHeader.tsx@@ -221,7 +221,7 @@ function ChevronDownIcon() {* The chevron indicator is automatically shown when `menu` is provided.** @example- * ```tsx+ * ```* // Single product* <XDSSideNavHeader icon={<AppIcon />} title="My App" titleHref="/" />*diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsxindex fe5854c8ea..8bd985a888 100644--- a/packages/core/src/SideNav/XDSSideNavItem.tsx+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx@@ -162,7 +162,7 @@ export interface XDSSideNavItemProps {* Supports icons, selected state, nesting, and end content like badges or counts.** @example- * ```tsx+ * ```* <XDSSideNavItem* label="Dashboard"* icon={HomeIcon}diff --git a/packages/core/src/SideNav/XDSSideNavSection.tsx b/packages/core/src/SideNav/XDSSideNavSection.tsxindex 8299218a01..775fb2673b 100644--- a/packages/core/src/SideNav/XDSSideNavSection.tsx+++ b/packages/core/src/SideNav/XDSSideNavSection.tsx@@ -123,7 +123,7 @@ export interface XDSSideNavSectionProps {* Uses `role="group"` with `aria-labelledby` for accessibility.** @example- * ```tsx+ * ```* <XDSSideNavSection title="Main">* <XDSSideNavItem label="Dashboard" icon={HomeIcon} isSelected />* <XDSSideNavItem label="Projects" icon={FolderIcon} />diff --git a/packages/core/src/Skeleton/XDSSkeleton.tsx b/packages/core/src/Skeleton/XDSSkeleton.tsxindex 44b8902251..faa551056d 100644--- a/packages/core/src/Skeleton/XDSSkeleton.tsx+++ b/packages/core/src/Skeleton/XDSSkeleton.tsx@@ -162,6 +162,19 @@ export interface XDSSkeletonProps extends Omit<'data-testid'?: string;}+/**+ * A placeholder shape that indicates content is loading.+ * Renders a pulsing block with configurable width, height, and border radius.+ * Use the `index` prop to stagger animation timing across multiple skeletons.+ *+ * @example+ * ```+ * <XDSSkeleton width={200} height={20} />+ * <XDSSkeleton width={40} height={40} radius="rounded" />+ * <XDSSkeleton width={300} height={16} index={0} />+ * <XDSSkeleton width={280} height={16} index={1} />+ * ```+ */export const XDSSkeleton = forwardRef<HTMLDivElement, XDSSkeletonProps>(({diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsxindex 00a7fbe9bf..cc56ca4c80 100644--- a/packages/core/src/Slider/XDSSlider.tsx+++ b/packages/core/src/Slider/XDSSlider.tsx@@ -312,7 +312,7 @@ function getPercent(val: number, min: number, max: number): number {* A slider component for selecting numeric values or ranges.** @example- * ```tsx+ * ```* // Single value* <XDSSlider label="Volume" value={50} onChange={setValue} />*diff --git a/packages/core/src/Spinner/XDSSpinner.tsx b/packages/core/src/Spinner/XDSSpinner.tsxindex ae8908adb0..78b617f028 100644--- a/packages/core/src/Spinner/XDSSpinner.tsx+++ b/packages/core/src/Spinner/XDSSpinner.tsx@@ -106,13 +106,10 @@ export interface XDSSpinnerProps {// =============================================================================/**- * A pure spinner component for indicating loading state.- *- * Uses canvas rendering for crisp circles at any DPI/pixel ratio.- * No layout or text — compose with XDSVStack + XDSText for loading states.+ * An animated loading indicator. Available in three sizes and two color shades.** @example- * ```tsx+ * ```* <XDSSpinner />* <XDSSpinner size="sm" />* <XDSSpinner size="lg" shade="onMedia" />diff --git a/packages/core/src/Stack/XDSHStack.tsx b/packages/core/src/Stack/XDSHStack.tsxindex 107c22f09b..32e457f1f3 100644--- a/packages/core/src/Stack/XDSHStack.tsx+++ b/packages/core/src/Stack/XDSHStack.tsx@@ -42,7 +42,7 @@ export interface XDSHStackProps extends Omit<* @deprecated Use `XDSStack` with `direction="horizontal"` instead.** @example- * ```tsx+ * ```* // Before* <XDSHStack gap="space2">...</XDSHStack>*diff --git a/packages/core/src/Stack/XDSStackItem.tsx b/packages/core/src/Stack/XDSStackItem.tsxindex 943b766a31..d0c15f6270 100644--- a/packages/core/src/Stack/XDSStackItem.tsx+++ b/packages/core/src/Stack/XDSStackItem.tsx@@ -68,7 +68,7 @@ export interface XDSStackItemProps extends Omit<* Supports polymorphic rendering via the `element` prop.** @example- * ```tsx+ * ```* <XDSHStack gap="space2">* <XDSStackItem size="static">Logo</XDSStackItem>* <XDSStackItem size="fill">Content</XDSStackItem>diff --git a/packages/core/src/Stack/XDSVStack.tsx b/packages/core/src/Stack/XDSVStack.tsxindex 889eccd71e..0edcff80a9 100644--- a/packages/core/src/Stack/XDSVStack.tsx+++ b/packages/core/src/Stack/XDSVStack.tsx@@ -42,12 +42,12 @@ export interface XDSVStackProps extends Omit<* @deprecated Use `XDSStack` with `direction="vertical"` (or omit direction) instead.** @example- * ```tsx+ * ```* // Before* <XDSVStack gap="space2">...</XDSVStack>** // After- * <XDSStack gap="space2">...</XDSStack>+ * <XDSStack direction="vertical" gap="space2">...</XDSStack>* ```*/export const XDSVStack = forwardRef<HTMLElement, XDSVStackProps>(diff --git a/packages/core/src/Stack/stack.stylex.ts b/packages/core/src/Stack/stack.stylex.tsindex 68f8d0705b..d81c569ba8 100644--- a/packages/core/src/Stack/stack.stylex.ts+++ b/packages/core/src/Stack/stack.stylex.ts@@ -211,7 +211,7 @@ export interface StackOptions {* StyleX utility to add stack (flex container) styles to any element.** @example- * ```tsx+ * ```* import { stack } from '@xds/core/Layout';* import * as stylex from '@stylexjs/stylex';*diff --git a/packages/core/src/Stack/stackItem.stylex.ts b/packages/core/src/Stack/stackItem.stylex.tsindex e79f74aa99..f3b4d530a2 100644--- a/packages/core/src/Stack/stackItem.stylex.ts+++ b/packages/core/src/Stack/stackItem.stylex.ts@@ -96,7 +96,7 @@ export interface StackItemOptions {* direct control over flex behavior.** @example- * ```tsx+ * ```* import { stackItem } from '@xds/core/Layout';** <div {...stylex.props(...stackItem({ size: 'fill' }))}>diff --git a/packages/core/src/StatusDot/XDSStatusDot.tsx b/packages/core/src/StatusDot/XDSStatusDot.tsxindex d3f33991ee..cdc26cea5e 100644--- a/packages/core/src/StatusDot/XDSStatusDot.tsx+++ b/packages/core/src/StatusDot/XDSStatusDot.tsx@@ -129,17 +129,14 @@ export interface XDSStatusDotProps {* Styles use XDS theme tokens via StyleX. Wrap your app in `<Theme>` to apply a theme.** @example- * ```tsx+ * ```* <XDSStatusDot variant="positive" label="Online" />* <XDSStatusDot variant="negative" label="Offline" size="sm" />* <XDSStatusDot variant="positive" label="Live" isPulsing />* ```*/export const XDSStatusDot = forwardRef<HTMLSpanElement, XDSStatusDotProps>(- (- {variant, size = 'md', label, isPulsing = false, xstyle, ...props},- ref,- ) => {+ ({variant, size = 'md', label, isPulsing = false, xstyle, ...props}, ref) => {return (<spanref={ref}diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsxindex 3f22926a71..7e342fb452 100644--- a/packages/core/src/Switch/XDSSwitch.tsx+++ b/packages/core/src/Switch/XDSSwitch.tsx@@ -259,7 +259,7 @@ export interface XDSSwitchProps {* A toggle switch component for boolean values.** @example- * ```tsx+ * ```* <XDSSwitch* label="Enable notifications"* value={enabled}diff --git a/packages/core/src/TabList/XDSTabList.tsx b/packages/core/src/TabList/XDSTabList.tsxindex 369063f16e..e7ef95a074 100644--- a/packages/core/src/TabList/XDSTabList.tsx+++ b/packages/core/src/TabList/XDSTabList.tsx@@ -73,7 +73,7 @@ const styles = stylex.create({* to XDSTab and XDSTabMenu children.** @example- * ```tsx+ * ```* <XDSTabList value={activeTab} onChange={setActiveTab}>* <XDSTab value="home" label="Home" />* <XDSTab value="settings" label="Settings" />diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsxindex fcd3ff3929..37b52334a8 100644--- a/packages/core/src/Table/XDSBaseTable.tsx+++ b/packages/core/src/Table/XDSBaseTable.tsx@@ -309,7 +309,7 @@ function XDSBaseTableInner<T extends Record<string, unknown>>(* Accepts a `components` prop to render styled components instead of raw elements.** @example- * ```tsx+ * ```* <XDSBaseTable* data={[{ name: 'Alice', age: 30 }]}* columns={[diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsxindex 93b4a10966..60d290e2f4 100644--- a/packages/core/src/Table/XDSTable.tsx+++ b/packages/core/src/Table/XDSTable.tsx@@ -181,7 +181,7 @@ function XDSTableInner<T extends Record<string, unknown>>(* design tokens in the component styles.** @example- * ```tsx+ * ```* <XDSTable* data={users}* columns={[diff --git a/packages/core/src/Table/XDSTableCell.tsx b/packages/core/src/Table/XDSTableCell.tsxindex 383abc4f6d..b13b0669f3 100644--- a/packages/core/src/Table/XDSTableCell.tsx+++ b/packages/core/src/Table/XDSTableCell.tsx@@ -76,7 +76,7 @@ const dividerColumnStyles = stylex.create({* (density padding, divider borders). When used standalone, renders a plain `<td>`.** @example- * ```tsx+ * ```* <XDSTableRow>* <XDSTableCell>Alice</XDSTableCell>* <XDSTableCell>30</XDSTableCell>diff --git a/packages/core/src/Table/XDSTableHeaderCell.tsx b/packages/core/src/Table/XDSTableHeaderCell.tsxindex 7a40b2ad10..3e9bb7d885 100644--- a/packages/core/src/Table/XDSTableHeaderCell.tsx+++ b/packages/core/src/Table/XDSTableHeaderCell.tsx@@ -89,7 +89,7 @@ const dividerColumnStyles = stylex.create({* Accepts `xstyle` for plugin-provided styles that merge on top.** @example- * ```tsx+ * ```* <thead>* <tr>* <XDSTableHeaderCell>Name</XDSTableHeaderCell>diff --git a/packages/core/src/Table/XDSTableRow.tsx b/packages/core/src/Table/XDSTableRow.tsxindex 89d9a1298d..9013d6b27a 100644--- a/packages/core/src/Table/XDSTableRow.tsx+++ b/packages/core/src/Table/XDSTableRow.tsx@@ -81,7 +81,7 @@ const _lastBodyRowStyles = stylex.create({* (striped, hover, divider overrides). When used standalone, renders a plain `<tr>`.** @example- * ```tsx+ * ```* <XDSTable>* <XDSTableRow>* <XDSTableCell>Alice</XDSTableCell>diff --git a/packages/core/src/Table/useXDSBaseTablePlugins.ts b/packages/core/src/Table/useXDSBaseTablePlugins.tsindex 14281de142..ec6ebaf5a8 100644--- a/packages/core/src/Table/useXDSBaseTablePlugins.ts+++ b/packages/core/src/Table/useXDSBaseTablePlugins.ts@@ -23,7 +23,7 @@ import type {TablePlugin} from './types';* @returns Stable array of plugins suitable for XDSBaseTable** @example- * ```tsx+ * ```* const plugins = useXDSBaseTablePlugins([tablePlugin], userPlugins);* <XDSBaseTable plugins={plugins} ... />* ```diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsxindex 27674e46c3..984201c8d6 100644--- a/packages/core/src/Text/XDSHeading.tsx+++ b/packages/core/src/Text/XDSHeading.tsx@@ -178,7 +178,7 @@ const levelToKey: Record<XDSHeadingLevel, HeadingLevel> = {* Renders headings with semantic HTML (h1-h6) and themed styling.** @example- * ```tsx+ * ```* <XDSHeading level={1}>Page Title</XDSHeading>* <XDSHeading level={2}>Section</XDSHeading>* <XDSHeading level={1} variant="editorial">Article Title</XDSHeading>diff --git a/packages/core/src/Text/XDSText.tsx b/packages/core/src/Text/XDSText.tsxindex 8c8fad3e53..f1287e932f 100644--- a/packages/core/src/Text/XDSText.tsx+++ b/packages/core/src/Text/XDSText.tsx@@ -166,23 +166,16 @@ const defaultColorByType: Record<XDSTextType, XDSTextColor> = {};/**- * XDSText - Semantic text component- *- * Renders text with semantic styling from the theme.+ * Semantic text component. Renders text with type-based styling from the theme.** @example- * ```tsx+ * ```* <XDSText type="body">Body text</XDSText>* <XDSText type="large">Large body text</XDSText>* <XDSText type="label">Form label</XDSText>- * <XDSText type="large-label">Empty state label</XDSText>* <XDSText type="supporting">Helper text</XDSText>- * <XDSText type="code">const x = 1;</XDSText>- *- * // With truncation- * <XDSText type="body" maxLines={2}>Long text that will be clamped...</XDSText>- *- * // With color and weight+ * <XDSText type="code">{'const x = 1;'}</XDSText>+ * <XDSText type="body" maxLines={2}>Clamped text</XDSText>* <XDSText type="body" color="secondary" weight="bold">Styled text</XDSText>* ```*/diff --git a/packages/core/src/Text/useTruncation.ts b/packages/core/src/Text/useTruncation.tsindex cf42801448..a72abc6fe4 100644--- a/packages/core/src/Text/useTruncation.ts+++ b/packages/core/src/Text/useTruncation.ts@@ -43,7 +43,7 @@ export interface UseTruncationReturn {* - Multi-line: compares scrollHeight > offsetHeight** @example- * ```tsx+ * ```* const truncation = useTruncation({ maxLines: 2 });** <div ref={truncation.ref} style={{ WebkitLineClamp: 2 }}>diff --git a/packages/core/src/TextArea/XDSTextArea.tsx b/packages/core/src/TextArea/XDSTextArea.tsxindex 704589ee9f..847245d9f3 100644--- a/packages/core/src/TextArea/XDSTextArea.tsx+++ b/packages/core/src/TextArea/XDSTextArea.tsx@@ -298,7 +298,7 @@ export interface XDSTextAreaProps {* A multi-line text input component for collecting longer user input.** @example- * ```tsx+ * ```* <XDSTextArea label="Description" value={description} onChange={setDescription} />* <XDSTextArea label="Notes" rows={5} value={notes} onChange={setNotes} />* ```diff --git a/packages/core/src/TextInput/XDSTextInput.tsx b/packages/core/src/TextInput/XDSTextInput.tsxindex 3403f43a4c..38fb2dfd87 100644--- a/packages/core/src/TextInput/XDSTextInput.tsx+++ b/packages/core/src/TextInput/XDSTextInput.tsx@@ -281,7 +281,7 @@ export interface XDSTextInputProps {* A text input component for collecting user input.** @example- * ```tsx+ * ```* <XDSTextInput label="Name" value={name} onChange={setName} />* <XDSTextInput label="Search" isLabelHidden value={query} onChange={setQuery} />* ```diff --git a/packages/core/src/TimeInput/XDSTimeInput.tsx b/packages/core/src/TimeInput/XDSTimeInput.tsxindex 9ff73f5daf..b7e25914f7 100644--- a/packages/core/src/TimeInput/XDSTimeInput.tsx+++ b/packages/core/src/TimeInput/XDSTimeInput.tsx@@ -358,7 +358,7 @@ export interface XDSTimeInputProps {* A time input component with text input and keyboard navigation.** @example- * ```tsx+ * ```* <XDSTimeInput* label="Start time"* value={time}diff --git a/packages/core/src/Token/XDSToken.tsx b/packages/core/src/Token/XDSToken.tsxindex d7d9de9923..8dda754392 100644--- a/packages/core/src/Token/XDSToken.tsx+++ b/packages/core/src/Token/XDSToken.tsx@@ -263,7 +263,7 @@ const colorStyles = stylex.create({* entire token.** @example- * ```tsx+ * ```* <XDSToken label="Tag" />* <XDSToken label="Status" color="green" />* <XDSToken label="Removable" onRemove={() => {}} />diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsxindex 37021ec14c..e7f6a8a90f 100644--- a/packages/core/src/TopNav/XDSTopNav.tsx+++ b/packages/core/src/TopNav/XDSTopNav.tsx@@ -127,51 +127,19 @@ export interface XDSTopNavProps extends Omit<}/**- * Top navigation bar component for application headers.+ * Top navigation bar for application headers.*- * Uses a slot-based API with `title`, `startContent`, `centerContent`, and- * `endContent` props for flexible layout. Title and startContent are- * left-aligned, centerContent is centered, and endContent is right-aligned.- *- * When `centerContent` is provided, the layout switches to a three-column- * CSS grid (`1fr auto 1fr`) to ensure the center content is always at the- * exact horizontal center of the nav bar, regardless of left/right content- * widths.- *- * Positioning is handled by the layout system (e.g. XDSAppShell applies sticky- * behavior in auto height mode). TopNav itself is a pure content component.+ * Slot-based layout with `title`, `startContent`, `centerContent`, and+ * `endContent`. When `centerContent` is provided, the layout switches to a+ * three-column CSS grid to keep center content horizontally centered.** @example- * ```tsx- * // Standard layout (left + right)- * <XDSTopNav- * label="Main navigation"- * title={<XDSTopNavTitle title="My App" logo={<Logo />} />}- * startContent={- * <>- * <XDSTopNavItem label="Home" href="/" isSelected />- * <XDSTopNavItem label="Products" href="/products" />- * </>- * }- * endContent={- * <>- * <XDSButton label="Search" icon={<SearchIcon />} variant="ghost" />- * <Avatar />- * </>- * }- * />- *- * // Centered layout (left + center + right)+ * ```* <XDSTopNav* label="Main navigation"- * title={<XDSTopNavTitle title="My App" logo={<Logo />} />}- * centerContent={- * <>- * <XDSTopNavItem label="Home" href="/" isSelected />- * <XDSTopNavItem label="Products" href="/products" />- * </>- * }- * endContent={<Avatar />}+ * title={<XDSTopNavTitle title="My App" />}+ * startContent={<XDSTopNavItem label="Home" href="/" isSelected />}+ * endContent={<XDSButton label="Search" variant="ghost" />}* />* ```*/diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsxindex a0abb94fa0..656dd13aa4 100644--- a/packages/core/src/TopNav/XDSTopNavItem.tsx+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx@@ -127,7 +127,7 @@ export interface XDSTopNavItemProps extends Omit<* Supports icons and selected state indication with highlighted appearance.** @example- * ```tsx+ * ```* <XDSTopNav* startContent={* <>diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsxindex 815e7790f8..8a46ee1f2e 100644--- a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx+++ b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx@@ -329,7 +329,7 @@ function ChevronDown() {* the XDSTopNav in a container with `position: relative`.** @example- * ```tsx+ * ```* <div style={{ position: 'relative' }}>* <XDSTopNav* startContent={diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsxindex a9ccf0b6eb..e27a80e8ef 100644--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx@@ -193,7 +193,7 @@ export interface XDSTopNavMenuProps {* and optional description.** @example- * ```tsx+ * ```* <XDSTopNav* startContent={* <>diff --git a/packages/core/src/TopNav/XDSTopNavTitle.tsx b/packages/core/src/TopNav/XDSTopNavTitle.tsxindex fb1fca79f4..213fe11662 100644--- a/packages/core/src/TopNav/XDSTopNavTitle.tsx+++ b/packages/core/src/TopNav/XDSTopNavTitle.tsx@@ -76,7 +76,7 @@ export interface XDSTopNavTitleProps extends Omit<* Use with XDSNavIcon to create a circular icon background.** @example- * ```tsx+ * ```* // Logo with text* <XDSTopNavTitle* title="My App"diff --git a/packages/core/src/hooks/useFocusTrap.ts b/packages/core/src/hooks/useFocusTrap.tsindex 6d085f0c0f..d5e4251e5e 100644--- a/packages/core/src/hooks/useFocusTrap.ts+++ b/packages/core/src/hooks/useFocusTrap.ts@@ -107,7 +107,7 @@ export interface UseFocusTrapReturn {* - Handles both Tab and Shift+Tab navigation** @example- * ```tsx+ * ```* const {containerRef, focusFirst} = useFocusTrap({* isActive: isOpen,* onEscape: () => setIsOpen(false),diff --git a/packages/core/src/hooks/useGridFocus.ts b/packages/core/src/hooks/useGridFocus.tsindex b7d1adffb5..a7e026cf20 100644--- a/packages/core/src/hooks/useGridFocus.ts+++ b/packages/core/src/hooks/useGridFocus.ts@@ -96,7 +96,7 @@ export interface UseGridFocusReturn {* - Page Up/Down: Custom callbacks (e.g., month navigation)** @example- * ```tsx+ * ```* const {gridRef, handleKeyDown} = useGridFocus({* columns: 7,* onPageUp: () => navigateMonth(-1),diff --git a/packages/core/src/hooks/useListFocus.ts b/packages/core/src/hooks/useListFocus.tsindex fe09784d3a..ddb4657cde 100644--- a/packages/core/src/hooks/useListFocus.ts+++ b/packages/core/src/hooks/useListFocus.ts@@ -73,7 +73,7 @@ export interface UseListFocusReturn {* - Escape: Custom callback (e.g., close menu)** @example- * ```tsx+ * ```* const {listRef, handleKeyDown} = useListFocus({* onEscape: () => layer.hide(),* });diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsxindex 4290d09321..f7dcfd6c3e 100644--- a/packages/core/src/theme/XDSTheme.tsx+++ b/packages/core/src/theme/XDSTheme.tsx@@ -4,7 +4,7 @@* Applies StyleX theme and sets color-scheme for light-dark() to work.** Usage:- * ```tsx+ * ```* <XDSTheme theme={myTheme}>* <App />* </XDSTheme>