Skip to content

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

TypeScript

docs: fix @example blocks — remove comments and blank lines, preserve indentation (#529)

Cindy Zhang93149847623c
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index ccebe42b6c..326c8ed2ff 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -287,8 +287,7 @@ const styles = stylex.create({
* <XDSMobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} title="My App">
* {navSections}
* </XDSMobileNav>
- * }
- * >
+ * }>
* <Content />
* </XDSAppShell>
* ```
diff --git a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
index b56ed4a7bf..27d24a0751 100644
--- a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
+++ b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
@@ -138,14 +138,11 @@ const variantStyleMap: Record<XDSAvatarStatusDotVariant, stylex.StyleXStyles> =
*
* @example
* ```
- * // Presence indicator
* <XDSAvatar
* name="John Doe"
* size="medium"
* status={<XDSAvatarStatusDot variant="positive" label="Online" />}
* />
- *
- * // With icon (e.g. verified badge)
* <XDSAvatar
* name="Jane Smith"
* size="large"
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index 4f97df5546..029403365b 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -306,10 +306,7 @@ const statusStyles = stylex.create({
*
* @example
* ```
- * // Simple banner — just the colored header
* <XDSBanner status="info" title="New update available" />
- *
- * // With description and dismiss
* <XDSBanner
* status="error"
* title="Something went wrong"
@@ -317,26 +314,20 @@ const statusStyles = stylex.create({
* isDismissable
* onDismiss={() => logDismiss()}
* />
- *
- * // With collapsible content area
* <XDSBanner
* status="error"
* title="Multiple errors found"
* description="The following issues need to be resolved:"
- * isDismissable
- * >
+ * isDismissable>
* <ul>
* <li>Email address is invalid</li>
* <li>Password must be at least 8 characters</li>
* </ul>
* </XDSBanner>
- *
- * // Content area expanded by default
* <XDSBanner
* status="warning"
* title="Configuration changes"
- * defaultIsExpanded
- * >
+ * defaultIsExpanded>
* <p>Details here...</p>
* </XDSBanner>
* ```
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index 42507ab86e..bf2c6d54e1 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -304,15 +304,9 @@ const edgeCompStyles = stylex.create({
* <XDSButton label="Click me" />
* <XDSButton label="Primary action" variant="primary" />
* <XDSButton label="Delete" variant="destructive" />
- *
- * // Icon-only (square) — pass icon without children
* <XDSButton label="Settings" icon={<GearIcon />} variant="ghost" />
* <XDSButton label="Pick emoji" icon={<span>🚀</span>} variant="ghost" size="sm" />
- *
- * // Icon + visible label
* <XDSButton label="Edit" icon={<PencilIcon />}>Edit</XDSButton>
- *
- * // With endSlot (badge or icon)
* <XDSButton label="Messages" endSlot={<XDSBadge>3</XDSBadge>} />
* <XDSButton label="Edit" icon={<PencilIcon />} endSlot={<XDSBadge>New</XDSBadge>}>Edit</XDSButton>
* ```
diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsx
index 355d84059b..a61b8387c0 100644
--- a/packages/core/src/Collapsible/XDSCollapsible.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx
@@ -127,13 +127,11 @@ export interface XDSCollapsibleProps {
* <XDSCollapsible trigger="Details">
* <XDSText type="body">Collapsible content</XDSText>
* </XDSCollapsible>
- *
* <XDSCard>
* <XDSCollapsible trigger="Settings">
* <SettingsForm />
* </XDSCollapsible>
* </XDSCard>
- *
* <XDSCollapsibleGroup type="single" defaultValue="general">
* <XDSVStack gap="space2">
* <XDSCard>
diff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsx
index 6b11c44e61..0c6b1d2594 100644
--- a/packages/core/src/Dialog/XDSDialog.tsx
+++ b/packages/core/src/Dialog/XDSDialog.tsx
@@ -209,7 +209,6 @@ export interface XDSDialogProps extends XDSBaseProps<HTMLDialogElement> {
* @example
* ```
* const [isOpen, setIsOpen] = useState(false);
- *
* <XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
* <XDSLayout
* header={<XDSDialogHeader title="Title" onOpenChange={open => setIsOpen(open)} />}
diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsx
index ec789a49c4..6cc1b44235 100644
--- a/packages/core/src/EmptyState/XDSEmptyState.tsx
+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx
@@ -143,7 +143,6 @@ export interface XDSEmptyStateProps {
* title="No results found"
* description="Try adjusting your search or filters."
* />
- *
* <XDSEmptyState
* icon={<XDSIcon icon={InboxIcon} size="lg" />}
* title="No messages"
diff --git a/packages/core/src/Layer/XDSHoverCard.tsx b/packages/core/src/Layer/XDSHoverCard.tsx
index 7310318259..625a6cacc8 100644
--- a/packages/core/src/Layer/XDSHoverCard.tsx
+++ b/packages/core/src/Layer/XDSHoverCard.tsx
@@ -142,8 +142,7 @@ function mergeIds(...ids: (string | undefined | null)[]): string | undefined {
* ```
* <XDSHoverCard
* content={<ProfileCard user={user} />}
- * placement="above"
- * >
+ * placement="above">
* <XDSButton>Hover me</XDSButton>
* </XDSHoverCard>
* ```
diff --git a/packages/core/src/Layer/XDSPopover.tsx b/packages/core/src/Layer/XDSPopover.tsx
index 68a6eac5c1..db7edd57ab 100644
--- a/packages/core/src/Layer/XDSPopover.tsx
+++ b/packages/core/src/Layer/XDSPopover.tsx
@@ -235,22 +235,16 @@ const styles = stylex.create({
*
* @example
* ```
- * // Basic popover
* <XDSPopover label="Settings" content={<SettingsPanel />} placement="below">
* <XDSButton label="Settings" />
* </XDSPopover>
- *
- * // Controlled popover
* <XDSPopover
* isOpen={isOpen}
* onOpenChange={setIsOpen}
* label="Filter"
- * content={<FilterForm />}
- * >
+ * content={<FilterForm />}>
* <XDSButton label="Filter" />
* </XDSPopover>
- *
- * // Sibling mode with anchorRef
* <XDSPopover
* anchorRef={myButtonRef}
* label="Actions"
diff --git a/packages/core/src/Layout/XDSLayoutContent.tsx b/packages/core/src/Layout/XDSLayoutContent.tsx
index 25a5caa7bb..8e249e33cb 100644
--- a/packages/core/src/Layout/XDSLayoutContent.tsx
+++ b/packages/core/src/Layout/XDSLayoutContent.tsx
@@ -109,8 +109,6 @@ export interface XDSLayoutContentProps extends XDSBaseProps<HTMLDivElement> {
* content={<XDSLayoutContent>Main body content</XDSLayoutContent>}
* />
* </XDSLayoutContainer>
- *
- * // Full bleed for edge-to-edge content
* <XDSLayoutContainer variant="card">
* <XDSLayout
* content={
@@ -120,8 +118,6 @@ export interface XDSLayoutContentProps extends XDSBaseProps<HTMLDivElement> {
* }
* />
* </XDSLayoutContainer>
- *
- * // Non-scrollable for auto-height layouts with sticky elements
* <XDSLayoutContainer variant="card">
* <XDSLayout
* content={
diff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsx
index 36e0564e72..ef70678785 100644
--- a/packages/core/src/Link/XDSLink.tsx
+++ b/packages/core/src/Link/XDSLink.tsx
@@ -215,16 +215,9 @@ export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {
*
* @example
* ```
- * // Basic link
* <XDSLink label="Documentation" href="/docs">Documentation</XDSLink>
- *
- * // External link (opens in new tab with icon)
* <XDSLink label="GitHub" href="https://github.com" isExternalLink>GitHub</XDSLink>
- *
- * // Link with custom color
* <XDSLink label="Settings" href="/settings" color="secondary">Settings</XDSLink>
- *
- * // Always underlined link
* <XDSLink label="Privacy Policy" href="/privacy" hasUnderline>Privacy Policy</XDSLink>
* ```
*/
diff --git a/packages/core/src/Link/XDSLinkProvider.tsx b/packages/core/src/Link/XDSLinkProvider.tsx
index 79f00d7384..e4597cc83e 100644
--- a/packages/core/src/Link/XDSLinkProvider.tsx
+++ b/packages/core/src/Link/XDSLinkProvider.tsx
@@ -10,7 +10,6 @@
* @example
* ```
* import Link from 'next/link';
- *
* <XDSLinkProvider component={Link}>
* <App />
* </XDSLinkProvider>
diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsx
index db3b50ca5b..245bd1adf6 100644
--- a/packages/core/src/List/XDSList.tsx
+++ b/packages/core/src/List/XDSList.tsx
@@ -145,7 +145,6 @@ const listStyleTypes = stylex.create({
* <XDSListItem label="Notifications" description="Manage your alerts" />
* <XDSListItem label="Privacy" description="Control your data" />
* </XDSList>
- *
* <XDSList listStyle="decimal" density="compact">
* <XDSListItem label="First step" />
* <XDSListItem label="Second step" />
diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsx
index b465aa8652..8a22a4124f 100644
--- a/packages/core/src/MobileNav/XDSMobileNav.tsx
+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx
@@ -223,8 +223,7 @@ export interface XDSMobileNavProps extends Omit<XDSBaseProps, 'title'> {
* <XDSMobileNav
* isOpen={isOpen}
* onOpenChange={(open) => setIsOpen(open)}
- * title="Navigation"
- * >
+ * title="Navigation">
* <XDSSideNavSection title="Main">
* <XDSSideNavItem label="Home" icon={HomeIcon} isSelected href="/" />
* <XDSSideNavItem label="Settings" icon={SettingsIcon} href="/settings" />
diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsx
index 2f4b50c699..86d0ed396b 100644
--- a/packages/core/src/NavIcon/XDSNavIcon.tsx
+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx
@@ -52,14 +52,10 @@ export interface XDSNavIconProps extends XDSBaseProps<HTMLDivElement> {
* @example
* ```
* import {HomeIcon} from '@heroicons/react/24/solid';
- *
- * // In XDSTopNavHeading
* <XDSTopNavHeading
* heading="Dashboard"
* logo={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
* />
- *
- * // In XDSPageNavHeader
* <XDSPageNavHeader
* icon={<XDSNavIcon icon={<HomeIcon style={{width: 16, height: 16}} />} />}
* heading="My App"
diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsx
index 0504e63402..ac508766b3 100644
--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx
+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx
@@ -242,13 +242,8 @@ function defaultFormatValueLabel(value: number, max: number): string {
*
* @example
* ```
- * // Determinate
* <XDSProgressBar value={75} label="Upload progress" />
- *
- * // Indeterminate
* <XDSProgressBar isIndeterminate label="Loading..." />
- *
- * // Custom format
* <XDSProgressBar value={3.2} max={5} label="Disk usage" hasValueLabel
* formatValueLabel={(v, m) => `${v} GB / ${m} GB`} />
* ```
diff --git a/packages/core/src/RadioList/XDSRadioList.tsx b/packages/core/src/RadioList/XDSRadioList.tsx
index 1ba66f6fc8..d0e6b4dfc9 100644
--- a/packages/core/src/RadioList/XDSRadioList.tsx
+++ b/packages/core/src/RadioList/XDSRadioList.tsx
@@ -150,8 +150,7 @@ export interface XDSRadioListProps {
* <XDSRadioList
* label="Notification preference"
* value={selected}
- * onChange={setSelected}
- * >
+ * onChange={setSelected}>
* <XDSRadioListItem label="Email" value="email" />
* <XDSRadioListItem label="SMS" value="sms" />
* <XDSRadioListItem label="Push" value="push" />
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index 3d88c92e3c..847c9ed374 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -143,8 +143,7 @@ export interface XDSSideNavProps extends XDSBaseProps<HTMLElement> {
* ```
* <XDSSideNav
* header={<XDSSideNavHeading heading="My App" headingHref="/" />}
- * topContent={<XDSButton label="Create new" variant="primary" />}
- * >
+ * topContent={<XDSButton label="Create new" variant="primary" />}>
* <XDSSideNavSection heading="Main">
* <XDSSideNavItem label="Dashboard" isSelected href="/dashboard" />
* <XDSSideNavItem label="Projects" href="/projects" />
diff --git a/packages/core/src/SideNav/XDSSideNavHeading.tsx b/packages/core/src/SideNav/XDSSideNavHeading.tsx
index 1839372260..b041e349fd 100644
--- a/packages/core/src/SideNav/XDSSideNavHeading.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeading.tsx
@@ -240,10 +240,7 @@ function ChevronDownIcon() {
*
* @example
* ```
- * // Single product
* <XDSSideNavHeading icon={<AppIcon />} heading="My App" headingHref="/" />
- *
- * // Suite with menu
* <XDSSideNavHeading
* icon={<SuiteIcon />}
* superheading="Suite Name"
@@ -252,8 +249,6 @@ function ChevronDownIcon() {
* headingHref="/product"
* menu={<ProductSwitcher />}
* />
- *
- * // Account context with menu
* <XDSSideNavHeading
* icon={<AppIcon />}
* heading="Product Name"
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index 0a88bb3ba0..cdb14cf4b5 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -171,7 +171,6 @@ export interface XDSSideNavItemProps {
* isSelected
* href="/dashboard"
* />
- *
* <XDSSideNavItem label="Settings" icon={CogIcon}>
* <XDSSideNavItem label="General" href="/settings/general" />
* <XDSSideNavItem label="Security" href="/settings/security" />
diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsx
index 24c3d484c3..dd02ee88fb 100644
--- a/packages/core/src/Slider/XDSSlider.tsx
+++ b/packages/core/src/Slider/XDSSlider.tsx
@@ -313,10 +313,7 @@ function getPercent(val: number, min: number, max: number): number {
*
* @example
* ```
- * // Single value
* <XDSSlider label="Volume" value={50} onChange={setValue} />
- *
- * // Range
* <XDSSlider label="Price range" value={[20, 80]} onChange={setRange} />
* ```
*/
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index 1552e57549..016219ae88 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -131,13 +131,10 @@ export interface XDSStackProps extends XDSBaseProps<HTMLDivElement> {
*
* @example
* ```
- * // Vertical stack
* <XDSStack direction="vertical" gap="space2">
* <Item />
* <Item />
* </XDSStack>
- *
- * // Horizontal stack
* <XDSStack direction="horizontal" gap="space4" vAlign="center">
* <Item />
* <Item />
diff --git a/packages/core/src/Text/XDSFontWrapper.tsx b/packages/core/src/Text/XDSFontWrapper.tsx
index 661e1dde13..892517ab92 100644
--- a/packages/core/src/Text/XDSFontWrapper.tsx
+++ b/packages/core/src/Text/XDSFontWrapper.tsx
@@ -48,7 +48,6 @@ export interface XDSFontWrapperProps {
*
* @example
* ```
- * // Default variant (dense scale)
* <XDSFontWrapper>
* <h1>Page Title</h1>
* <p>Body text with <strong>bold</strong> and <em>italic</em>.</p>
@@ -57,16 +56,10 @@ export interface XDSFontWrapperProps {
* <li>List item 2</li>
* </ul>
* </XDSFontWrapper>
- *
- * // Editorial variant (larger heading scale)
* <XDSFontWrapper variant="editorial">
* <h1>Article Title</h1>
* <p>Body text for long-form content.</p>
* </XDSFontWrapper>
- *
- * // For global usage, apply to body:
- * // import '@xds/core/typography.css';
- * // <body className="xds-typography">
* ```
*/
export function XDSFontWrapper({
diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsx
index 8edb887935..a07f915d79 100644
--- a/packages/core/src/Text/XDSHeading.tsx
+++ b/packages/core/src/Text/XDSHeading.tsx
@@ -73,7 +73,6 @@ export interface XDSHeadingProps {
*
* @example
* ```
- * // Visually styled as h2, but semantically h3 in document outline
* <XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>
* ```
*/
@@ -191,11 +190,7 @@ const levelToTag = {
* <XDSHeading level={2}>Section</XDSHeading>
* <XDSHeading level={1} variant="editorial">Article Title</XDSHeading>
* <XDSHeading level={2} accessibilityLevel={3}>Sidebar Section</XDSHeading>
- *
- * // With truncation
* <XDSHeading level={2} maxLines={1}>Very Long Section Title...</XDSHeading>
- *
- * // With color
* <XDSHeading level={3} color="secondary">Muted Heading</XDSHeading>
* ```
*/
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.tsx b/packages/core/src/Tokenizer/XDSTokenizer.tsx
index 462e87aa4a..0d84030085 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.tsx
@@ -213,9 +213,7 @@ const styles = stylex.create({
*
* @example
* ```
- * // Basic
* const [members, setMembers] = useState<UserItem[]>([]);
- *
* <XDSTokenizer
* label="Team members"
* searchSource={userSource}
@@ -226,8 +224,6 @@ const styles = stylex.create({
* }}
* placeholder="Search people..."
* />
- *
- * // Custom rendering
* <XDSTokenizer
* label="Tags"
* searchSource={tagSource}
diff --git a/packages/core/src/TopNav/XDSTopNavHeading.tsx b/packages/core/src/TopNav/XDSTopNavHeading.tsx
index 78d05c6f4d..e68307085d 100644
--- a/packages/core/src/TopNav/XDSTopNavHeading.tsx
+++ b/packages/core/src/TopNav/XDSTopNavHeading.tsx
@@ -76,20 +76,15 @@ export interface XDSTopNavHeadingProps extends XDSBaseProps<HTMLElement> {
*
* @example
* ```
- * // Logo with text
* <XDSTopNavHeading
* heading="My App"
* logo={<img src="/logo.svg" alt="" width={24} height={24} />}
* href="/"
* />
- *
- * // With circular icon
* <XDSTopNavHeading
* heading="Dashboard"
* logo={<XDSNavIcon icon={<HomeIcon />} />}
* />
- *
- * // Logo only
* <XDSTopNavHeading logo={<BrandLogo />} href="/" />
* ```
*/
diff --git a/packages/core/src/Typeahead/XDSTypeaheadItem.tsx b/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
index e6e65306ef..00f18ec8c9 100644
--- a/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
+++ b/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
@@ -106,10 +106,7 @@ const styles = stylex.create({
*
* @example
* ```
- * // Default usage (automatic)
* <XDSTypeahead searchSource={source} value={v} onChange={setV} label="Search" />
- *
- * // Custom renderItem using XDSTypeaheadItem
* <XDSTypeahead
* searchSource={source}
* value={v}