Skip to content

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

TypeScript

docs: fix storybook autodocs compatibility in docblocks (#426)

Cindy Zhang22de188ae068
diff --git a/packages/core/src/Icon/XDSIcon.tsx b/packages/core/src/Icon/XDSIcon.tsx
index 89775c186c..007932a997 100644
--- a/packages/core/src/Icon/XDSIcon.tsx
+++ b/packages/core/src/Icon/XDSIcon.tsx
@@ -182,6 +182,14 @@ export interface XDSIconProps extends Omit<
// Component
// =============================================================================
+/**
+ * Renders an icon from the icon registry or a custom SVG component.
+ *
+ * @example
+ * ```
+ * <XDSIcon icon="close" size="md" color="primary" />
+ * ```
+ */
export const XDSIcon = forwardRef<SVGSVGElement, XDSIconProps>(
({icon, color = 'primary', size = 'md', ...props}, ref) => {
// Get theme context for component-level overrides (optional)
diff --git a/packages/core/src/Layer/XDSPopover.tsx b/packages/core/src/Layer/XDSPopover.tsx
index d20f67d46f..60da7478ed 100644
--- a/packages/core/src/Layer/XDSPopover.tsx
+++ b/packages/core/src/Layer/XDSPopover.tsx
@@ -227,7 +227,7 @@ const styles = stylex.create({
* For hover-triggered overlays, use {@link XDSHoverCard} instead.
*
* @example
- * ```tsx
+ * ```
* // Basic popover
* <XDSPopover label="Settings" content={<SettingsPanel />} placement="below">
* <XDSButton label="Settings" />
diff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsx
index 1f67fd1abe..a88a6ea43b 100644
--- a/packages/core/src/Layout/XDSLayout.tsx
+++ b/packages/core/src/Layout/XDSLayout.tsx
@@ -146,7 +146,6 @@ function AreaProvider({
*
* @example
* ```
- * // Full-page app shell with sidebar navigation
* <XDSLayout
* header={<XDSLayoutHeader hasDivider>App Name</XDSLayoutHeader>}
* start={
@@ -160,26 +159,6 @@ function AreaProvider({
* </XDSLayoutContent>
* }
* />
- *
- * // With XDSTopNav — no wrapper needed, TopNav manages its own chrome
- * <XDSLayout
- * header={
- * <XDSTopNav
- * label="Main navigation"
- * title={<XDSTopNavTitle title="My App" logo={<Logo />} />}
- * startContent={<XDSTopNavItem label="Home" href="/" isSelected />}
- * />
- * }
- * content={<XDSLayoutContent role="main">...</XDSLayoutContent>}
- * />
- *
- * // Card with structured content
- * <XDSCard>
- * <XDSLayout
- * header={<XDSLayoutHeader hasDivider>Title</XDSLayoutHeader>}
- * content={<XDSLayoutContent>Body</XDSLayoutContent>}
- * />
- * </XDSCard>
* ```
*/
export function XDSLayout({
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index 2c09a95225..afc6a958af 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -114,7 +114,7 @@ export interface XDSStackProps extends Omit<
* - `direction='vertical'`: hAlign → align-items, vAlign → justify-content
*
* @example
- * ```tsx
+ * ```
* // Vertical stack
* <XDSStack direction="vertical" gap="space2">
* <Item />
diff --git a/packages/core/src/TabList/XDSTab.tsx b/packages/core/src/TabList/XDSTab.tsx
index 4fe22d8353..5c24efeb3a 100644
--- a/packages/core/src/TabList/XDSTab.tsx
+++ b/packages/core/src/TabList/XDSTab.tsx
@@ -163,6 +163,14 @@ const iconSizeStyles = stylex.create({
/**
* Tab item component. Renders as an anchor when `href` is provided,
* otherwise as a button.
+ *
+ * @example
+ * ```
+ * <XDSTabList value={tab} onChange={setTab}>
+ * <XDSTab value="general" label="General" />
+ * <XDSTab value="advanced" label="Advanced" />
+ * </XDSTabList>
+ * ```
*/
export function XDSTab({
as,
diff --git a/packages/core/src/TabList/XDSTabMenu.tsx b/packages/core/src/TabList/XDSTabMenu.tsx
index 4c46e32471..4dbc3d69ed 100644
--- a/packages/core/src/TabList/XDSTabMenu.tsx
+++ b/packages/core/src/TabList/XDSTabMenu.tsx
@@ -211,6 +211,17 @@ const sizeStyles = stylex.create({
* Tab menu trigger that opens a dropdown of additional tab options.
* Shows the selected option's label as trigger text when an option is active.
* Dropdown includes a heading showing the menu's label prop.
+ *
+ * @example
+ * ```
+ * <XDSTabList value={tab} onChange={setTab}>
+ * <XDSTab value="overview" label="Overview" />
+ * <XDSTabMenu label="More" options={[
+ * { value: "settings", label: "Settings" },
+ * { value: "history", label: "History" },
+ * ]} />
+ * </XDSTabList>
+ * ```
*/
export function XDSTabMenu({label, options}: XDSTabMenuProps) {
const tabListCtx = useXDSTabListContext();
diff --git a/packages/core/src/Tokenizer/XDSTokenizer.tsx b/packages/core/src/Tokenizer/XDSTokenizer.tsx
index fff9a4293d..9c8a48024f 100644
--- a/packages/core/src/Tokenizer/XDSTokenizer.tsx
+++ b/packages/core/src/Tokenizer/XDSTokenizer.tsx
@@ -277,7 +277,7 @@ const statusFocusStyles = stylex.create({
* and clears the query. Backspace on empty input removes the last token.
*
* @example
- * ```tsx
+ * ```
* // Basic
* const [members, setMembers] = useState<UserItem[]>([]);
*
diff --git a/packages/core/src/Typeahead/XDSTypeaheadItem.tsx b/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
index cbd0011250..b9b588e718 100644
--- a/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
+++ b/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
@@ -104,7 +104,7 @@ const styles = stylex.create({
* Exported for use in custom `renderItem` implementations.
*
* @example
- * ```tsx
+ * ```
* // Default usage (automatic)
* <XDSTypeahead searchSource={source} value={v} onChange={setV} label="Search" />
*
diff --git a/packages/core/src/theme/XDSTheme.tsx b/packages/core/src/theme/XDSTheme.tsx
index f7dcfd6c3e..54d1b3ab8e 100644
--- a/packages/core/src/theme/XDSTheme.tsx
+++ b/packages/core/src/theme/XDSTheme.tsx
@@ -73,6 +73,13 @@ const wrapperStyles = stylex.create({
*
* Applies StyleX theme variables and sets color-scheme for light-dark() to work.
* Use mode prop to override system preference.
+ *
+ * @example
+ * ```
+ * <XDSTheme theme={myTheme} mode="system">
+ * <App />
+ * </XDSTheme>
+ * ```
*/
export function XDSTheme({
theme,