Skip to content

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.js
index 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.md
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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, // January
diff --git a/packages/core/src/Calendar/hooks/useCalendarNavigation.ts b/packages/core/src/Calendar/hooks/useCalendarNavigation.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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 XDSTopNavTitle
diff --git a/packages/core/src/NumberInput/XDSNumberInput.tsx b/packages/core/src/NumberInput/XDSNumberInput.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.tsx
index 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 (
<span
ref={ref}
diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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>