element."},{"name":"contentPadding","type":"0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10","description":"Padding for the main content area. Set based on the dominant content pattern: 4 (16px) for forms/settings/text, 0 for dashboards/maps/tables. Override individual sections with XDSSection.","default":"0"},{"name":"topNav","type":"ReactNode","description":"Top navigation slot, typically XDSTopNav.","slotElements":[{"__element":"XDSTopNav","props":{"label":"Navigation"}}]},{"name":"sideNav","type":"ReactNode","description":"Side navigation slot, typically XDSSideNav.","slotElements":[{"__element":"XDSSideNav","props":{}}]},{"name":"mobileNav","type":"ReactNode","description":"Mobile navigation configuration. Accepts false (disable), config object (tune auto behavior), or ReactNode (full custom drawer).","slotElements":[{"__element":"XDSMobileNav","props":{}}]},{"name":"banner","type":"ReactNode","description":"Banner slot for system-wide announcements, placed above the topNav.","slotElements":[{"__element":"XDSBanner","props":{"title":"Info","status":"info","container":"section"}}]},{"name":"height","type":"'fill' | 'auto'","description":"Height behavior: 'fill' makes the shell fill the viewport (100dvh) with independent scroll containers; 'auto' lets the shell grow with content and uses sticky positioning for nav.","default":"'fill'"},{"name":"isSideNavCollapsed","type":"boolean","description":"Whether the sideNav is collapsed (controlled mode)."},{"name":"defaultIsSideNavCollapsed","type":"boolean","description":"Initial collapsed state for uncontrolled mode.","default":"false"},{"name":"onSideNavCollapsedChange","type":"(isCollapsed: boolean) => void","description":"Callback fired when the sideNav collapse state changes."},{"name":"variant","type":"'wash' | 'surface' | 'section' | 'elevated'","description":"Navigation background style controlling how nav areas contrast with content. 'wash' uses wash background, 'surface' uses surface background, 'section' adds dividers between nav and content, 'elevated' uses wash nav with elevated surface content and border radius.","default":"'elevated'"},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"The outermost layout for an application. Provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page — it handles responsive collapse, skip-to-content, and mobile navigation automatically.","bestPractices":[{"guidance":true,"description":"Choose the right height — use \"fill\" for dashboards with internal scrolling and \"auto\" for pages that grow with content."},{"guidance":true,"description":"Set `contentPadding` based on content type — 4 for forms and settings, 0 for tables and dashboards."},{"guidance":false,"description":"Nest one AppShell inside another — it's the outermost layout frame."},{"guidance":false,"description":"Use for sub-page layouts — use Layout for content areas within AppShell."}]},"theming":{"targets":[{"className":"xds-app-shell","visualProps":["variant"]},{"className":"xds-app-shell-header","visualProps":["variant"]},{"className":"xds-app-shell-sidenav","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"variant":"surface","contentPadding":4,"topNav":{"__element":"XDSTopNav","props":{"label":"Navigation","heading":{"__element":"XDSTopNavHeading","props":{"heading":"My App"}}}},"sideNav":{"__element":"XDSSideNav","props":{},"children":[{"__element":"XDSSideNavItem","props":{"label":"Dashboard","isSelected":true}},{"__element":"XDSSideNavItem","props":{"label":"Settings"}},{"__element":"XDSSideNavItem","props":{"label":"Help"}}]},"children":{"__element":"XDSVStack","props":{"gap":3},"children":[{"__element":"XDSHeading","props":{"level":2},"children":"Dashboard"},{"__element":"XDSText","props":{"type":"body","color":"secondary"},"children":"Welcome back. Here is an overview of your workspace."}]}}}},{"name":"AspectRatio","moduleName":"XDSAspectRatio","directory":"AspectRatio","group":null,"description":"Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.","keywords":["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],"hidden":false,"parentDoc":null,"props":[{"name":"ratio","type":"number","description":"Aspect ratio as width/height (e.g. 16/9, 1).","required":true},{"name":"children","type":"ReactNode","description":"Content positioned absolutely to fill the container.","required":true},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.","bestPractices":[{"guidance":true,"description":"Express the ratio as a fraction like `16/9` or `4/3` for readability."},{"guidance":true,"description":"Use for media that needs consistent proportions across screen sizes."},{"guidance":false,"description":"Use for general layout containers — use standard layout components instead."},{"guidance":false,"description":"Nest AspectRatio containers — one level is sufficient."}]},"theming":{"targets":[{"className":"xds-aspect-ratio"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"ratio":1.7777777777777777,"children":{"__element":"XDSCenter","props":{"height":"100%"},"children":{"__element":"XDSText","props":{"color":"secondary"},"children":"16:9"}}}}},{"name":"Avatar","moduleName":"XDSAvatar","directory":"Avatar","group":"Avatar","description":"Displays a user avatar with image, initials fallback, and optional status indicator.","keywords":["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],"hidden":false,"parentDoc":"Avatar","props":[{"name":"src","type":"string","description":"Primary image source URL."},{"name":"fallbackSrc","type":"string","description":"Fallback image when primary fails."},{"name":"name","type":"string","description":"User name for initials and alt text."},{"name":"alt","type":"string","description":"Alt text (falls back to name)."},{"name":"size","type":"XDSAvatarSize","description":"Avatar size (named or numeric pixel value).","default":"'small'"},{"name":"status","type":"ReactNode","description":"Corner content for status indicators.","slotElements":[{"__element":"XDSStatusDot","props":{"variant":"online"}}]}],"usage":{"description":"Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.","bestPractices":[{"guidance":true,"description":"Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents."},{"guidance":true,"description":"Pick a size that matches the context — tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers."},{"guidance":true,"description":"Add a status dot when knowing someone's availability matters, like in chat or team views."},{"guidance":false,"description":"Use Avatar for logos, product images, or anything that isn't a person or team — use an image or icon instead."},{"guidance":false,"description":"Force a square or custom shape — avatars are always circular to stay consistent across the system."}],"anatomy":[{"name":"Photo","required":false,"description":"The profile image, loaded from the src URL. Shown when available."},{"name":"Initials","required":false,"description":"One or two letters extracted from the name. Shown when no photo is available."},{"name":"Default icon","required":false,"description":"A generic person silhouette. Shown when there is no photo or name."},{"name":"Status dot","required":false,"description":"A small indicator in the bottom-right corner showing availability (online, away, busy)."}]},"theming":{"targets":[{"className":"xds-avatar","visualProps":["size"]},{"className":"xds-avatar-status-dot","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"AvatarStatusDot","moduleName":"XDSAvatarStatusDot","directory":"Avatar","group":"Avatar","description":"Size-aware status indicator dot that reads avatar size from context and scales proportionally.","keywords":["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],"hidden":false,"parentDoc":"Avatar","props":[{"name":"variant","type":"'positive' | 'neutral' | 'negative'","description":"Semantic color variant of the dot.","default":"'positive'"},{"name":"label","type":"string","description":"Accessible label for screen readers."},{"name":"icon","type":"ReactNode","description":"Icon centered inside the dot (hidden at tiny sizes).","slotElements":[{"__element":"XDSIcon","props":{"icon":"check","size":"sm"}}]}],"usage":{"description":"Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.","bestPractices":[{"guidance":true,"description":"Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents."},{"guidance":true,"description":"Pick a size that matches the context — tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers."},{"guidance":true,"description":"Add a status dot when knowing someone's availability matters, like in chat or team views."},{"guidance":false,"description":"Use Avatar for logos, product images, or anything that isn't a person or team — use an image or icon instead."},{"guidance":false,"description":"Force a square or custom shape — avatars are always circular to stay consistent across the system."}],"anatomy":[{"name":"Photo","required":false,"description":"The profile image, loaded from the src URL. Shown when available."},{"name":"Initials","required":false,"description":"One or two letters extracted from the name. Shown when no photo is available."},{"name":"Default icon","required":false,"description":"A generic person silhouette. Shown when there is no photo or name."},{"name":"Status dot","required":false,"description":"A small indicator in the bottom-right corner showing availability (online, away, busy)."}]},"theming":{"targets":[{"className":"xds-avatar","visualProps":["size"]},{"className":"xds-avatar-status-dot","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Badge","moduleName":"XDSBadge","directory":"Badge","group":null,"description":"Badge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.","keywords":["badge","tag","chip","label","status","indicator","count","counter","pill","notification","marker"],"hidden":false,"parentDoc":null,"props":[{"name":"variant","type":"'neutral' | 'info' | 'success' | 'warning' | 'error' | 'blue' | 'cyan' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'","description":"Visual style variant. Semantic variants (neutral, info, success, warning, error) use solid backgrounds. Non-semantic color variants use tinted backgrounds with colored text for categorization and tagging.","default":"'neutral'"},{"name":"label","type":"ReactNode","description":"Badge text content."},{"name":"icon","type":"ReactNode","description":"Optional leading icon.","slotElements":[{"__element":"XDSIcon","props":{"icon":"check","size":"sm"}}]}],"usage":{"description":"Badge shows a short label like a status, count, or category. Use it in table rows, list items, navigation, and anywhere you need to call out a state or group at a glance.","bestPractices":[{"guidance":true,"description":"Use success, warning, and error variants for system status like \"Active\", \"Pending\", or \"Failed\". Use color variants like blue, purple, or teal for categories and tags."},{"guidance":true,"description":"Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge."},{"guidance":true,"description":"Add an icon when it helps identify the badge type quickly, but always include a text label alongside it."},{"guidance":false,"description":"Make badges clickable — they are read-only indicators. Use a button or link if the user needs to take action."}],"anatomy":[{"name":"Icon","required":false,"description":"An optional leading icon that helps identify the badge type at a glance."},{"name":"Label","required":true,"description":"The text or number shown inside the badge."}]},"theming":{"targets":[{"className":"xds-badge","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Badge","variant":"neutral"}}},{"name":"Banner","moduleName":"XDSBanner","directory":"Banner","group":null,"description":"Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.","keywords":["banner","alert","notification","callout","notice","status","message","info","warning","error","success","toast"],"hidden":false,"parentDoc":null,"props":[{"name":"status","type":"'info' | 'warning' | 'error' | 'success'","description":"Status type controlling icon and color.","required":true},{"name":"title","type":"ReactNode","description":"Title text or ReactNode displayed in the header.","required":true},{"name":"description","type":"ReactNode","description":"Description text rendered below the title in the header."},{"name":"icon","type":"ReactNode","description":"Override the default status icon.","slotElements":[{"__element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"isDismissable","type":"boolean","description":"Whether the banner can be dismissed by the user.","default":"false"},{"name":"onDismiss","type":"() => void","description":"Called when the dismiss button is clicked; banner hides itself regardless of whether this is provided."},{"name":"endContent","type":"ReactNode","description":"Action content rendered in the header area, end-aligned. Typically a button or link.","slotElements":[{"__element":"XDSIcon","props":{"icon":"chevronDown","size":"sm"}},{"__element":"XDSBadge","props":{"label":"3"}}]},{"name":"container","type":"'card' | 'section'","description":"Container type: card has border-radius; section is full-width with no border-radius for page-level use.","default":"'card'"},{"name":"children","type":"ReactNode","description":"Content rendered in the card-background area below the colored header."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.","bestPractices":[{"guidance":true,"description":"Pick a status that matches the message: info for updates, warning for caution, error for problems, success for confirmations."},{"guidance":true,"description":"Use the card container inside page content and the section container for full-width messages that span the entire page."},{"guidance":true,"description":"Make info and success banners dismissable. Keep error banners visible until the user fixes the issue."},{"guidance":true,"description":"Keep titles short and scannable — \"Payment failed\" not \"There was a problem processing your most recent payment.\""},{"guidance":false,"description":"Use Banner for short-lived messages that disappear on their own — use Toast instead."},{"guidance":false,"description":"Stack multiple banners with the same status — combine related messages into one banner."}],"anatomy":[{"name":"Icon","required":true,"description":"Automatically set based on the status (info, warning, error, success)."},{"name":"Title","required":false,"description":"The main message. Required if no description is provided."},{"name":"Description","required":false,"description":"Additional detail below the title. Required if no title is provided."},{"name":"Action button","required":false,"description":"A button for the user to act on the message, like \"Review\" or \"Retry\"."},{"name":"Dismiss button","required":false,"description":"Lets the user close the banner. Enabled by setting isDismissable."},{"name":"Collapsible content","required":false,"description":"Extra detail that expands below the banner header, like a list of errors."}]},"theming":{"targets":[{"className":"xds-banner","visualProps":["container","status"]},{"className":"xds-banner-icon","visualProps":["status"]}],"vars":[{"name":"--_banner-radius","description":"Border radius (card container only)","default":"var(--radius-container)","private":true}],"derived":[{"property":"borderRadius","vars":["--_banner-radius"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"title":"System maintenance scheduled","description":"The platform will be briefly unavailable on Sunday from 2–4 AM PST.","status":"info"}}},{"name":"BaseTable","moduleName":"XDSBaseTable","directory":"Table","group":"Table","description":"Unstyled structural table component with a plugin transform pipeline and a components prop for swapping in custom row/cell renderers.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"data","type":"T[]","description":"Array of data items to render as rows."},{"name":"columns","type":"XDSTableColumn[]","description":"Column definitions. If omitted, columns are auto-generated from data object keys."},{"name":"idKey","type":"(keyof T & string) | ((item: T) => string | number)","description":"Row key for React reconciliation. Pass a property name string or a function. Falls back to row index if omitted."},{"name":"plugins","type":"TablePlugin[]","description":"Ordered array of plugins applied as a sequential transform pipeline."},{"name":"components","type":"{Row?: ComponentType; Cell?: ComponentType; HeaderCell?: ComponentType}","description":"Component overrides for row and cell elements. When provided, these components receive xstyle from plugin transforms."},{"name":"children","type":"ReactNode","description":"Children mode — render rows directly in the tbody instead of using data-driven rendering."},{"name":"tableProps","type":"HTMLAttributes","description":"Additional HTML attributes passed directly to the root element."}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"BaseTypeahead","moduleName":"XDSBaseTypeahead","directory":"Typeahead","group":"Typeahead","description":"Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by XDSTypeahead and XDSTokenizer for custom compositions.","keywords":["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],"hidden":false,"parentDoc":"Typeahead","props":[{"name":"searchSource","type":"XDSSearchSource","description":"Data source providing search and bootstrap methods.","required":true},{"name":"value","type":"T | null","description":"Currently selected item.","required":true},{"name":"onChange","type":"(item: T | null) => void","description":"Called when the selection changes.","required":true},{"name":"renderItem","type":"(item: T) => ReactNode","description":"Custom render function for dropdown items."},{"name":"placeholder","type":"string","description":"Input placeholder text.","default":"'Search...'"},{"name":"hasEntriesOnFocus","type":"boolean","description":"Show bootstrap results on focus before typing.","default":"false"},{"name":"maxMenuItems","type":"number","description":"Maximum dropdown items to display.","default":"10"},{"name":"emptySearchResultsText","type":"string","description":"Text shown when search returns no results.","default":"'No results found'"},{"name":"isDisabled","type":"boolean","description":"Whether the input is disabled.","default":"false"},{"name":"hasAutoFocus","type":"boolean","description":"Auto-focus the input on mount.","default":"false"},{"name":"debounceMs","type":"number","description":"Debounce delay in ms before triggering search. Set to 0 for synchronous sources.","default":"150"},{"name":"anchorRef","type":"RefObject","description":"Ref to the anchor element for dropdown positioning. If not provided, the input itself is used."},{"name":"inputXStyle","type":"StyleXStyles","description":"Additional StyleX styles for the input element."},{"name":"onKeyDown","type":"(e: React.KeyboardEvent) => void","description":"Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling."},{"name":"onChangeQuery","type":"(query: string) => void","description":"Callback fired when the search query text changes."},{"name":"onOpenChange","type":"(isOpen: boolean) => void","description":"Callback when the dropdown opens or closes."},{"name":"inputId","type":"string","description":"ID for the input element (for label association)."},{"name":"ariaDescribedBy","type":"string","description":"Additional aria-describedby IDs."}],"usage":{"description":"A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.","bestPractices":[{"guidance":true,"description":"Provide descriptive placeholder text that hints at what users can search for."},{"guidance":true,"description":"Show suggestions on focus when users benefit from seeing popular or recent options before typing."},{"guidance":true,"description":"Add a search delay for remote data sources to avoid excessive network requests."},{"guidance":false,"description":"Use for short, static option lists — use Selector for better discoverability."},{"guidance":false,"description":"Use for multi-selection — use Tokenizer instead."},{"guidance":false,"description":"Place multiple Typeaheads adjacent to each other without clear labels differentiating them."}]},"theming":{"targets":[{"className":"xds-typeahead","visualProps":["status"]},{"className":"xds-typeahead-dropdown"},{"className":"xds-typeahead-item"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"BreadcrumbItem","moduleName":"XDSBreadcrumbItem","directory":"Breadcrumbs","group":"Breadcrumbs","description":"Individual breadcrumb item that renders as a link when href is provided, or as plain text for the current page.","keywords":["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],"hidden":false,"parentDoc":"Breadcrumbs","props":[{"name":"children","type":"ReactNode","description":"Label content for the breadcrumb item.","required":true},{"name":"href","type":"string","description":"URL the breadcrumb links to; omit for non-navigable items."},{"name":"onClick","type":"(e: MouseEvent) => void","description":"Click handler for the breadcrumb item."},{"name":"isCurrent","type":"boolean","description":"Marks this item as the current page, applying aria-current=\"page\".","default":"false"},{"name":"startIcon","type":"ReactNode","description":"Icon rendered before the item label.","slotElements":[{"__element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"as","type":"XDSLinkComponentType","description":"Custom link component to render instead of . Overrides the provider-level default from XDSLinkProvider. Only applies to non-current items."}],"usage":{"description":"Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.","bestPractices":[{"guidance":true,"description":"Place breadcrumbs above the page heading so the user sees their location before reading the content."},{"guidance":true,"description":"Keep labels short and match the page titles they link to — \"Settings\" not \"Application Settings Page\"."},{"guidance":true,"description":"Use the supporting variant in dense UIs like admin panels or sidebars where the breadcrumb should be subtle."},{"guidance":true,"description":"Make the last item plain text, not a link — it represents the current page. The component does this automatically when you set isCurrent."},{"guidance":false,"description":"Use breadcrumbs as the primary navigation — they supplement a sidebar or top nav, not replace it."},{"guidance":false,"description":"Show breadcrumbs on top-level pages that have no parent — they add clutter without helping the user."},{"guidance":false,"description":"Let the trail grow beyond 5 levels — if you need more, consider simplifying the page hierarchy instead."}],"anatomy":[{"name":"Trail","required":true,"description":"The ordered list of links from root to current page."},{"name":"Item","required":true,"description":"A single step in the trail. Renders as a link or plain text for the current page."},{"name":"Separator","required":true,"description":"The character between items. Defaults to \"/\" but can be customized."},{"name":"Icon","required":false,"description":"An optional icon before an item label, like a home icon on the first item."}]},"theming":{"targets":[{"className":"xds-breadcrumb-item"},{"className":"xds-breadcrumbs","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Breadcrumbs","moduleName":"XDSBreadcrumbs","directory":"Breadcrumbs","group":"Breadcrumbs","description":"Navigation container that renders a wrapper that reads XDSTableContext to apply striped, hover, and divider styles when used inside XDSTable.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"children","type":"ReactNode","description":"Row cell elements.","required":true}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"TabList","moduleName":"XDSTabList","directory":"TabList","group":"Tabs","description":"Nav wrapper that provides XDSTabListContext (value, onChange, size) to XDSTab and XDSTabMenu children.","keywords":["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],"hidden":false,"parentDoc":"TabList","props":[{"name":"value","type":"string","description":"The currently selected tab value.","required":true},{"name":"onChange","type":"(value: string) => void","description":"Callback fired when a tab is selected.","required":true},{"name":"size","type":"'sm' | 'md' | 'lg'","description":"Size variant applied to all child tabs.","default":"'md'"},{"name":"hasDivider","type":"boolean","description":"Whether to show a bottom border divider under the tab list.","default":"false"},{"name":"children","type":"ReactNode","description":"XDSTab and XDSTabMenu items to render inside the nav.","slotElements":[{"__element":"XDSTab","props":{"label":"Tab","value":"tab"}}],"required":true},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in \"more\" menu.","bestPractices":[{"guidance":true,"description":"Keep tab labels short and descriptive so users can quickly scan available sections."},{"guidance":true,"description":"Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen."},{"guidance":true,"description":"When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don’t overpower the tab row."},{"guidance":false,"description":"Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead."},{"guidance":false,"description":"Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories."},{"guidance":false,"description":"Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off."}],"anatomy":[{"name":"Left Content","required":false,"description":"Most important area; hugs content width."},{"name":"Center-Fill Content","required":false,"description":"Stretches to fill available space."},{"name":"Right Content","required":false,"description":"Hugs content width."}]},"theming":{"targets":[{"className":"xds-tab-list","visualProps":["size"]},{"className":"xds-tab","states":["selected"]},{"className":"xds-tab-indicator","states":["selected"]},{"className":"xds-tab-menu"},{"className":"xds-tab-menu-dropdown"},{"className":"xds-tab-menu-item"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"value":"tab-1"}}},{"name":"TabMenu","moduleName":"XDSTabMenu","directory":"TabList","group":"Tabs","description":"Overflow menu trigger that opens a dropdown of additional tab options, showing the selected option's label as the trigger text.","keywords":["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],"hidden":false,"parentDoc":"TabList","props":[{"name":"label","type":"string","description":"Label for the trigger button (shown when no option is selected) and the dropdown heading divider.","required":true},{"name":"options","type":"XDSTabMenuOption[]","description":"Array of menu options rendered in the dropdown.","required":true}],"usage":{"description":"TabList provides tab-style navigation for organizing content into categorized sections. Use it to let users switch between related views without leaving the page, with overflow items handled by a built-in \"more\" menu.","bestPractices":[{"guidance":true,"description":"Keep tab labels short and descriptive so users can quickly scan available sections."},{"guidance":true,"description":"Use XDSTabMenu to group overflow items when horizontal space is limited rather than scrolling tabs off-screen."},{"guidance":true,"description":"When using hasDivider with action buttons alongside tabs, use a smaller button size (sm) so the actions don’t overpower the tab row."},{"guidance":false,"description":"Use tabs for sequential steps or workflows — use a stepper or wizard pattern instead."},{"guidance":false,"description":"Place more than 6–8 visible tabs before the overflow menu — prioritize the most important categories."},{"guidance":false,"description":"Confuse TabList with XDSSegmentedControl or XDSToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls — SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off."}],"anatomy":[{"name":"Left Content","required":false,"description":"Most important area; hugs content width."},{"name":"Center-Fill Content","required":false,"description":"Stretches to fill available space."},{"name":"Right Content","required":false,"description":"Hugs content width."}]},"theming":{"targets":[{"className":"xds-tab-list","visualProps":["size"]},{"className":"xds-tab","states":["selected"]},{"className":"xds-tab-indicator","states":["selected"]},{"className":"xds-tab-menu"},{"className":"xds-tab-menu-dropdown"},{"className":"xds-tab-menu-item"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"value":"tab-1"}}},{"name":"Text","moduleName":"XDSText","directory":"Text","group":null,"description":"Semantic body text component that renders text with type-based styling from the theme, with optional truncation, decoration, and layout props.","keywords":["text","typography","label","paragraph","heading","caption","font","body","subtitle"],"hidden":false,"parentDoc":"Text","props":[{"name":"type","type":"'body' | 'large' | 'label' | 'supporting' | 'code'","description":"Semantic text type. Determines size, weight, and line-height from the theme.","default":"'body'"},{"name":"children","type":"ReactNode","description":"Text content.","required":true},{"name":"size","type":"'4xs' | '3xs' | '2xs' | 'xsm' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl'","description":"Explicit font size override. Overrides the size from `type` but preserves other type properties. Prefer using `type` alone."},{"name":"color","type":"'primary' | 'secondary' | 'disabled' | 'placeholder' | 'active' | 'inherit'","description":"Text color. Defaults to 'secondary' for the 'supporting' type, 'primary' for all others."},{"name":"weight","type":"'normal' | 'medium' | 'semibold' | 'bold'","description":"Font weight override."},{"name":"display","type":"'inline' | 'block'","description":"Display type. Silently overridden to 'block' when maxLines > 0 or hasCapsize is true.","default":"'inline'"},{"name":"as","type":"'span' | 'p' | 'div' | 'label'","description":"HTML element to render.","default":"'span'"},{"name":"maxLines","type":"number","description":"Maximum lines before truncation. 0 means no truncation. When set, shows a tooltip on hover if content is truncated.","default":"0"},{"name":"hasTruncateTooltip","type":"boolean | LayerPlacement","description":"Controls tooltip behavior for truncated text. true shows the tooltip at the default position, false disables it, or a LayerPlacement string sets a specific position.","default":"true"},{"name":"wordBreak","type":"'break-word' | 'break-all'","description":"Word break behavior when truncating. Defaults to 'break-all' for single-line truncation, 'break-word' otherwise."},{"name":"textWrap","type":"'wrap' | 'nowrap' | 'balance' | 'pretty'","description":"Text wrapping behavior."},{"name":"hasCapsize","type":"boolean","description":"Enable optical alignment using text-box-trim. Forces block display.","default":"false"},{"name":"hasStrikethrough","type":"boolean","description":"Apply strikethrough text decoration.","default":"false"},{"name":"hasTabularNumbers","type":"boolean","description":"Use tabular (monospace) numbers for aligned numeric data.","default":"false"},{"name":"id","type":"string","description":"HTML id attribute."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"Text renders styled body text and headings from the theme. Use XDSText with a semantic type for body copy, labels, and captions, and XDSHeading for section titles that output the correct h1–h6 element.","bestPractices":[{"guidance":true,"description":"Pick a semantic type (body, label, supporting, large, code) instead of manually setting size and weight — the theme handles the details."},{"guidance":true,"description":"Set accessibilityLevel on XDSHeading when the visual level differs from the document outline so screen readers announce the correct hierarchy."},{"guidance":true,"description":"Use maxLines with a number to truncate long content — a tooltip appears automatically on hover so no text is lost."},{"guidance":true,"description":"Enable hasTabularNumbers for columns of numeric data so digits align vertically across rows."},{"guidance":false,"description":"Override size and weight when a semantic type already matches — extra overrides fight the theme and break when themes change."},{"guidance":false,"description":"Skip heading levels in the document outline — go h1 then h2 then h3, never h1 then h3."},{"guidance":false,"description":"Use raw HTML tags like

–

, or for text — XDSText and XDSHeading apply the correct theme tokens automatically."}]},"theming":{"targets":[{"className":"xds-heading","visualProps":["level","color"]},{"className":"xds-text","visualProps":["type","color"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"children":"The quick brown fox jumps over the lazy dog.","type":"body"}}},{"name":"TextArea","moduleName":"XDSTextArea","directory":"TextArea","group":null,"description":"TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.","keywords":["textarea","textfield","multiline","comment","message","autoresize","autosize","charlimit"],"hidden":false,"parentDoc":null,"props":[{"name":"ref","type":"React.Ref","description":"Ref forwarded to the underlying element."},{"name":"label","type":"string","description":"Label text for the textarea — always rendered for accessibility.","required":true},{"name":"value","type":"string","description":"Current value of the textarea.","required":true},{"name":"onChange","type":"(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void","description":"Callback fired when the textarea value changes."},{"name":"changeAction","type":"(value: string, e: ChangeEvent<HTMLTextAreaElement>) => void | Promise<void>","description":"Async action fired after onChange inside a React transition. Enables optimistic updates via useOptimistic."},{"name":"isLabelHidden","type":"boolean","description":"Visually hides the label while keeping it accessible to screen readers.","default":"false"},{"name":"description","type":"string","description":"Helper text displayed between the label and textarea."},{"name":"isOptional","type":"boolean","description":"Displays an \"Optional\" indicator next to the label. Mutually exclusive with isRequired.","default":"false"},{"name":"isRequired","type":"boolean","description":"Displays a \"Required\" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.","default":"false"},{"name":"isDisabled","type":"boolean","description":"Disables the textarea, preventing interaction.","default":"false"},{"name":"isLoading","type":"boolean","description":"Puts the textarea in a loading state, showing a spinner inside the input.","default":"false"},{"name":"placeholder","type":"string","description":"Placeholder text shown when the textarea is empty."},{"name":"rows","type":"number","description":"Number of visible text rows.","default":"3"},{"name":"maxLength","type":"number","description":"Maximum number of characters allowed. When set, a character counter (current/max) is displayed below the textarea. Does not enforce the limit natively — the counter shows error styling when exceeded."},{"name":"status","type":"{ type: 'warning' | 'error' | 'success'; message?: string }","description":"Status indicator that applies a colored border and icon. An optional message is displayed in a floating box below the textarea."},{"name":"labelTooltip","type":"string","description":"Tooltip text displayed in an info icon at the end of the label."},{"name":"startIcon","type":"XDSIconType","description":"Icon component rendered inside the leading edge of the textarea wrapper. See `npx xds docs icons` for valid semantic names."},{"name":"hasSpellCheck","type":"boolean","description":"Enables or disables browser spell checking.","default":"true"},{"name":"hasAutoFocus","type":"boolean","description":"Automatically focuses the textarea on mount.","default":"false"},{"name":"onPaste","type":"(e: ClipboardEvent<HTMLTextAreaElement>) => void","description":"Callback fired when content is pasted into the textarea."},{"name":"htmlName","type":"string","description":"HTML name attribute for the textarea element, useful for form submissions."},{"name":"onFocus","type":"(e: FocusEvent<HTMLTextAreaElement>) => void","description":"Callback fired when the textarea receives focus."},{"name":"onBlur","type":"(e: FocusEvent<HTMLTextAreaElement>) => void","description":"Callback fired when the textarea loses focus."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"TextArea is a multi-line text input for collecting longer-form content like comments, descriptions, or messages. Use it when the expected input spans multiple lines. For shorter, single-line values, use TextInput.","bestPractices":[{"guidance":true,"description":"Provide a visible label so users know what to enter. If the label must be hidden, set isLabelHidden with a descriptive label for screen readers."},{"guidance":true,"description":"Set maxLength with a character counter when there is a defined limit — it helps users stay within bounds before they submit."},{"guidance":true,"description":"Use the status prop to surface validation feedback inline — show success when input is valid, warning for soft limits, and error for hard failures."},{"guidance":true,"description":"Add a description or placeholder to clarify expected content, like \"Describe the issue in detail\" — but never rely on placeholder alone as the only label."},{"guidance":false,"description":"Avoid using TextArea for short, single-line values like names or emails — use TextInput instead."},{"guidance":false,"description":"Don't rely solely on placeholder text to communicate the purpose of the field — placeholders disappear on focus and are not accessible labels."},{"guidance":false,"description":"Don't show a status message without also setting the status type — the colored border and icon are what draw the user's attention to the message."}]},"theming":{"targets":[{"className":"xds-textarea","visualProps":["status"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"TextInput","moduleName":"XDSTextInput","directory":"TextInput","group":null,"description":"TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.","keywords":["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],"hidden":false,"parentDoc":null,"props":[{"name":"type","type":"'text' | 'password' | 'email'","description":"The HTML input type.","default":"'text'"},{"name":"label","type":"string","description":"Label text for the input — always rendered for accessibility.","required":true},{"name":"value","type":"string","description":"Current value of the input.","required":true},{"name":"onChange","type":"(value: string, e: ChangeEvent<HTMLInputElement>) => void","description":"Callback fired when the input value changes."},{"name":"changeAction","type":"(value: string, e: ChangeEvent<HTMLInputElement>) => void | Promise<void>","description":"Async action fired after onChange (if not prevented). Triggers optimistic update and shows a loading spinner while pending."},{"name":"size","type":"'sm' | 'md' | 'lg'","description":"Size variant of the input.","default":"'md'"},{"name":"isLabelHidden","type":"boolean","description":"Visually hides the label while keeping it accessible to screen readers.","default":"false"},{"name":"description","type":"string","description":"Description text displayed between the label and input."},{"name":"isOptional","type":"boolean","description":"Displays an \"Optional\" indicator next to the label. Mutually exclusive with isRequired.","default":"false"},{"name":"isRequired","type":"boolean","description":"Displays a \"Required\" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.","default":"false"},{"name":"isDisabled","type":"boolean","description":"Disables the input, preventing interaction and dimming the element.","default":"false"},{"name":"isLoading","type":"boolean","description":"Puts the input in a loading state, showing a spinner and setting aria-busy.","default":"false"},{"name":"placeholder","type":"string","description":"Placeholder text shown when the input is empty."},{"name":"labelTooltip","type":"string","description":"Tooltip text displayed in an info icon at the end of the label."},{"name":"startIcon","type":"XDSIconType","description":"SVG icon component displayed at the start of the input. See `npx xds docs icons` for valid semantic names."},{"name":"status","type":"{type: 'error' | 'warning' | 'success', message?: string}","description":"Validation status — applies a colored border and status icon. If message is provided, displays a floating message below the input. Error type also sets aria-invalid."},{"name":"hasClear","type":"boolean","description":"Shows a clear (×) button when the input has a value. Clicking it clears the value and returns focus to the input.","default":"false"},{"name":"hasAutoFocus","type":"boolean","description":"Automatically focuses the input on mount.","default":"false"},{"name":"htmlName","type":"string","description":"The HTML name attribute for the input, useful for form submissions."}],"usage":{"description":"TextInput collects short-form text like names, emails, or search queries. Use it for single-line values where the expected input is brief. Pair it with validation status to guide users through required or formatted fields.","bestPractices":[{"guidance":true,"description":"Always provide a visible label so users know what the field is for. Only hide the label when surrounding context makes it obvious, like a search bar with a magnifying-glass icon."},{"guidance":true,"description":"Use validation status with a message to explain what went wrong — \"Email must include @\" is better than just turning the border red."},{"guidance":true,"description":"Size the input to match the expected content length so users can gauge how much to type — small for zip codes, medium for names, large for URLs."},{"guidance":true,"description":"Add a clear button for search and filter inputs so users can quickly reset without selecting all text."},{"guidance":false,"description":"Don't use placeholder text as a replacement for a label — placeholders disappear on focus and are not reliably read by screen readers."},{"guidance":false,"description":"Don't use TextInput for multi-line content like comments or descriptions — use TextArea instead."},{"guidance":false,"description":"Don't mark every field as required — only flag truly mandatory fields so users are not overwhelmed by validation errors."}],"anatomy":[{"name":"Label","required":true,"description":"Text that identifies the field. Always rendered for accessibility even when visually hidden."},{"name":"Description","required":false,"description":"Helper text between the label and the input that provides additional context or formatting hints."},{"name":"Start icon","required":false,"description":"A leading icon inside the input that hints at the expected content, like a magnifying glass for search."},{"name":"Placeholder","required":false,"description":"Hint text shown when the input is empty. Disappears on focus."},{"name":"Clear button","required":false,"description":"A trailing × button that resets the value and returns focus to the input."},{"name":"Spinner","required":false,"description":"Loading indicator that appears during async actions like server-side validation."},{"name":"Status icon","required":false,"description":"A trailing icon (error, warning, or success) that communicates validation state."}]},"theming":{"targets":[{"className":"xds-text-input","visualProps":["size","status"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Theme","moduleName":"XDSTheme","directory":"theme","group":"Utilities","description":"Wraps a subtree with a specific XDS theme. Use at the app root or around sections that need a different visual treatment.","keywords":["theme","theming","provider","color-scheme"],"hidden":false,"parentDoc":null,"props":[{"name":"theme","type":"XDSDefinedTheme","required":true,"description":"Theme created by defineTheme()."},{"name":"mode","type":"'light' | 'dark' | 'system'","default":"'system'","description":"Color mode — system follows OS preference."},{"name":"children","type":"ReactNode","required":true,"description":"Content to render with the theme."}],"usage":{"description":"Wraps a subtree with a specific XDS theme. Use at the app root or around sections that need a different visual treatment."},"theming":null,"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Thumbnail","moduleName":"XDSThumbnail","directory":"Thumbnail","group":null,"description":"Thumbnail displays a compact, square preview of an image attachment. It shows a shimmer effect while uploading, the image on success, and a placeholder icon when no source is set. Use it in chat composers, file upload lists, or anywhere you need a small image preview with optional remove and click actions.","keywords":["thumbnail","attachment","preview","image","upload","dismiss","remove","loading"],"hidden":false,"parentDoc":null,"props":[{"name":"src","type":"string","description":"Image source URL."},{"name":"alt","type":"string","description":"Alt text for the image."},{"name":"label","type":"string","description":"Accessible label (e.g. file name). Shown as tooltip on hover."},{"name":"onRemove","type":"(e: React.MouseEvent) => void","description":"Callback for the overlaid remove button."},{"name":"onClick","type":"(e: React.MouseEvent) => void","description":"Click handler. Adds button semantics and hover shadow."},{"name":"isLoading","type":"boolean","description":"Shows skeleton (no src) or upload overlay (with src).","default":"false"},{"name":"isDisabled","type":"boolean","description":"Whether the thumbnail is disabled.","default":"false"},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."},{"name":"className","type":"string","description":"CSS class name for the root element. Prefer xstyle for styling — className is provided for integration with non-StyleX systems."},{"name":"style","type":"CSSProperties","description":"Inline styles for the root element. Prefer xstyle for styling — inline styles bypass StyleX optimization."},{"name":"data-testid","type":"string","description":"Test selector for automated testing frameworks."}],"usage":{"description":"Thumbnail displays a compact, square preview of an image attachment. It shows a shimmer effect while uploading, the image on success, and a placeholder icon when no source is set. Use it in chat composers, file upload lists, or anywhere you need a small image preview with optional remove and click actions.","bestPractices":[{"guidance":true,"description":"Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover."},{"guidance":true,"description":"Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available."},{"guidance":true,"description":"Pair onClick with a lightbox or detail view so users can inspect the full image — the thumbnail adds button semantics and a hover shadow automatically."},{"guidance":false,"description":"Don't use Thumbnail for non-image file types like PDFs or spreadsheets — use a file attachment component with an appropriate icon instead."},{"guidance":false,"description":"Don't omit alt text when a src is provided — screen readers need a description of the image content, not just the file name from label."}],"anatomy":[{"name":"Image","required":false,"description":"The preview image, displayed as a square with cover fit."},{"name":"Placeholder","required":false,"description":"An image silhouette icon shown when no src is provided."},{"name":"Remove button","required":false,"description":"An overlaid close button in the top-right corner. Appears when onRemove is set. Uses APCA luminance detection to stay visible on any image."},{"name":"Upload overlay","required":false,"description":"A semi-transparent overlay with a spinner, shown when isLoading is true and a src preview is available."},{"name":"Skeleton","required":false,"description":"A shimmer animation shown when isLoading is true and no src is set."}]},"theming":{"targets":[{"className":"xds-thumbnail"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"TimeInput","moduleName":"XDSTimeInput","directory":"TimeInput","group":null,"description":"TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.","keywords":["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield","schedule"],"hidden":false,"parentDoc":null,"props":[{"name":"label","type":"string","description":"Label text for the input (required for accessibility).","required":true},{"name":"isLabelHidden","type":"boolean","description":"Visually hides the label while keeping it accessible to screen readers.","default":"false"},{"name":"description","type":"string","description":"Description text displayed between the label and input."},{"name":"isOptional","type":"boolean","description":"Shows an \"(optional)\" indicator next to the label. Mutually exclusive with isRequired.","default":"false"},{"name":"isRequired","type":"boolean","description":"Marks the field as required and sets aria-required. Mutually exclusive with isOptional.","default":"false"},{"name":"isDisabled","type":"boolean","description":"Disables the input and suppresses interactions.","default":"false"},{"name":"value","type":"ISOTimeString","description":"Controlled time value in ISO format (HH:MM or HH:MM:SS)."},{"name":"onChange","type":"(value: ISOTimeString | undefined) => void","description":"Callback fired when the time changes. Receives undefined when the input is cleared."},{"name":"changeAction","type":"(value: ISOTimeString | undefined) => void | Promise<void>","description":"Async action fired after onChange. Wrapped in a React transition to provide optimistic UI; triggers the loading spinner while pending."},{"name":"isLoading","type":"boolean","description":"Puts the input into a loading state, displaying a spinner.","default":"false"},{"name":"min","type":"ISOTimeString","description":"Minimum selectable time in ISO format. Values outside the range are rejected."},{"name":"max","type":"ISOTimeString","description":"Maximum selectable time in ISO format. Values outside the range are rejected."},{"name":"hasSeconds","type":"boolean","description":"Includes seconds in the time display and parsing.","default":"false"},{"name":"hasClear","type":"boolean","description":"Shows a clear button when a value is set and the input is not disabled.","default":"false"},{"name":"hourFormat","type":"'12h' | '24h'","description":"Controls the display format. '12h' shows AM/PM (e.g. '2:30 PM'); '24h' uses 24-hour notation (e.g. '14:30').","default":"'12h'"},{"name":"increment","type":"number","description":"Number of minutes to add or subtract when the user presses the up or down arrow key.","default":"1"},{"name":"placeholder","type":"string","description":"Placeholder text shown when no time is selected. When the input is focused and empty, a format hint overrides this text.","default":"'Select a time'"},{"name":"size","type":"'sm' | 'md' | 'lg'","description":"Controls the height of the input element.","default":"'md'"},{"name":"status","type":"XDSInputStatus","description":"Status indicator that colors the border and displays an icon. When a message is provided it is rendered below the input."},{"name":"labelTooltip","type":"string","description":"Tooltip text rendered as an info icon at the end of the label row."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"TimeInput lets users enter a time of day and converts it to a standard format. It also allows users to adjust times using the arrow keys. Use it in forms, scheduling flows, or any interface where users need to select a specific time.","bestPractices":[{"guidance":true,"description":"Choose the hour format (12h or 24h) that matches your audience’s locale — 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts."},{"guidance":true,"description":"Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time."},{"guidance":true,"description":"Provide a description or placeholder that hints at the expected format or purpose, like “Business hours: 9 AM – 5 PM”."},{"guidance":true,"description":"Use the status prop to surface validation errors inline — show a message like “Time must be during business hours” so users know exactly what to fix."},{"guidance":true,"description":"Enable hasClear when the field is optional, so users can easily remove a previously selected time."},{"guidance":false,"description":"Don’t use TimeInput for combined date-and-time selection — pair it with a separate DateInput instead."},{"guidance":false,"description":"Don’t hide the label — even when space is tight, keep the label visible or provide a description so the purpose is clear."}],"anatomy":[{"name":"Clock icon","required":false,"description":"A leading clock icon that identifies the field as a time input."},{"name":"Text input","required":true,"description":"The editable text field where users type or see the formatted time."},{"name":"Clear button","required":false,"description":"A trailing button to reset the value, shown when hasClear is true and a value is set."},{"name":"Status icon","required":false,"description":"A trailing icon indicating error, warning, or success state."},{"name":"Spinner","required":false,"description":"Replaces trailing content during loading to show an async action is in progress."}]},"theming":{"targets":[{"className":"xds-time-input","visualProps":["size","status"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Timestamp","moduleName":"XDSTimestamp","directory":"Timestamp","group":null,"description":"Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled — picking relative for recency, absolute for precision, or auto to let the component decide.","keywords":["date","time","datetime","relative","ago","clock","format","duration"],"hidden":false,"parentDoc":null,"props":[{"name":"value","type":"string | number","description":"The date/time to display. Accepts Unix timestamps (seconds) or ISO 8601 strings.","required":true},{"name":"format","type":"'relative' | 'auto' | 'date' | 'date_time' | 'time' | 'system_date' | 'system_date_time' | 'system_time'","description":"Display format. 'relative' shows '2 hours ago', 'date' shows 'Mar 21, 2025', 'date_time' shows 'Mar 21, 2025, 2:51 PM', 'time' shows '2:51 PM', 'system_' variants use ISO-style formatting, 'auto' switches from relative to date_time based on recency.","default":"'auto'"},{"name":"autoThreshold","type":"number","description":"Threshold in seconds for 'auto' format to switch from relative to date_time.","default":"604800"},{"name":"hasTooltip","type":"boolean","description":"Whether to show a tooltip with the full date/time on hover when displaying relative time.","default":"true"},{"name":"isTimezoneShown","type":"boolean","description":"Whether to append the timezone abbreviation. Applies to date_time, time, system_date_time, and system_time formats.","default":"false"},{"name":"isLive","type":"boolean","description":"Whether the relative time should update live (e.g. \"2 min ago\" → \"3 min ago\").","default":"false"},{"name":"type","type":"XDSTextType","description":"Semantic text type from XDSText. Determines size, weight, and line-height.","default":"'supporting'"},{"name":"size","type":"XDSTextSize","description":"Explicit font size override. Overrides the size from type."},{"name":"color","type":"XDSTextColor","description":"Text color.","default":"'secondary'"},{"name":"weight","type":"XDSTextWeight","description":"Font weight override."}],"usage":{"description":"Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled — picking relative for recency, absolute for precision, or auto to let the component decide.","bestPractices":[{"guidance":true,"description":"Use the auto format in feeds and lists so recent items show “2 hours ago” and older items show the full date automatically."},{"guidance":true,"description":"Keep formatting consistent within the same list or table — mixing relative and absolute timestamps in the same column confuses scanning."},{"guidance":true,"description":"Enable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log."},{"guidance":true,"description":"Use isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh."},{"guidance":false,"description":"Don’t display raw Unix timestamps or ISO strings to users — always pass them through Timestamp to get a human-readable format."},{"guidance":false,"description":"Avoid system_date or system_time formats in user-facing UI — they are meant for developer tools, logs, and machine-readable contexts."},{"guidance":false,"description":"Don’t disable the tooltip on relative timestamps — users expect to hover for the full date when they see “3 hours ago”."}],"anatomy":[{"name":"Formatted text","required":true,"description":"The rendered date, time, or relative label like “2 hours ago” or “Mar 21, 2025”."},{"name":"Tooltip","required":false,"description":"A hover card showing the full absolute date and time when the display is relative."}]},"theming":{"targets":[{"className":"xds-timestamp","visualProps":["type","color"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Toast","moduleName":"XDSToast","directory":"Toast","group":"Toast","description":"Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.\n\nFor production use, prefer the `useXDSToast()` hook — it handles positioning, stacking, auto-dismiss, and deduplication via `XDSToastViewport`. The `XDSToast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.","keywords":["toast","notification","snackbar","alert","message","feedback","status"],"hidden":false,"parentDoc":null,"props":[{"name":"body","type":"ReactNode","description":"Primary message content.","required":true,"slotElements":[{"element":"XDSText","props":{"type":"body"},"children":"Toast message"}]},{"name":"type","type":"'info' | 'error'","description":"Toast type controlling background color. Error toasts persist until dismissed.","default":"'info'"},{"name":"isAutoHide","type":"boolean","description":"Whether the toast auto-dismisses. Defaults to true for info, false for error."},{"name":"autoHideDuration","type":"number","description":"Duration in ms before auto-dismiss.","default":"5000"},{"name":"endContent","type":"ReactNode","description":"Content rendered at the trailing end (e.g. Undo button, link).","slotElements":[{"element":"XDSIcon","props":{"icon":"chevronDown","size":"sm"}},{"element":"XDSBadge","props":{"label":"3"}}]},{"name":"uniqueID","type":"string","description":"Unique identifier for deduplication."},{"name":"collisionBehavior","type":"'overwrite' | 'ignore'","description":"Behavior when a toast with matching uniqueID already exists.","default":"'overwrite'"},{"name":"onHide","type":"(reason: \"auto\" | \"manual\") => void","description":"Callback fired when the toast is removed."}],"usage":{"description":"Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.\n\nFor production use, prefer the `useXDSToast()` hook — it handles positioning, stacking, auto-dismiss, and deduplication via `XDSToastViewport`. The `XDSToast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.","bestPractices":[{"guidance":true,"description":"Keep messages short - only a few words that tell the user what happened, like \"Changes saved\" or \"Message sent\"."},{"guidance":true,"description":"Add an undo action in the endContent slot for reversible operations like deleting an item, so the user can recover without navigating away."},{"guidance":true,"description":"Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times."},{"guidance":true,"description":"Use error type for failures that need attention but not immediate action — it persists until dismissed so the user won't miss it."},{"guidance":false,"description":"Don't use a toast for critical errors that block the user — use Banner for persistent, in-context messaging that requires acknowledgment."},{"guidance":false,"description":"Don't put long or multi-line content in a toast — it disappears after 5 seconds and the user may not finish reading."},{"guidance":false,"description":"Don't show form validation errors as toasts — use inline field validation so the user can see exactly which field needs fixing."}],"anatomy":[{"name":"Body","required":true,"description":"The primary message text describing what happened or what the user should know."},{"name":"End content","required":false,"description":"A trailing action like an Undo button or a link, placed after the body text."},{"name":"Dismiss button","required":true,"description":"A close button that lets the user manually dismiss the toast before auto-hide."}]},"theming":{"targets":[{"className":"xds-toast","visualProps":["type"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"ToggleButton","moduleName":"XDSToggleButton","directory":"ToggleButton","group":"Button","description":"A button that toggles between pressed and unpressed states. Thin wrapper over XDSButton with controlled toggle pattern, icon swap, and font weight emphasis.","keywords":["toggle","togglebutton","pressed","toolbar","formatting","segmented","button-group","exclusive","multi-select"],"hidden":false,"parentDoc":"ToggleButton","props":[{"name":"label","type":"string","description":"Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.","required":true},{"name":"isPressed","type":"boolean","description":"Whether the button is currently pressed. Ignored when inside a group."},{"name":"onPressedChange","type":"(isPressed: boolean) => void","description":"Called when pressed state should change. Ignored when inside a group."},{"name":"pressedChangeAction","type":"(isPressed: boolean) => Promise<void>","description":"Async action handler for API-backed toggles. Shows loading spinner while pending."},{"name":"size","type":"'sm' | 'md' | 'lg'","description":"Button size. Defaults to group size when inside a group.","default":"'md'"},{"name":"isDisabled","type":"boolean","description":"Whether the button is disabled.","default":"false"},{"name":"isLoading","type":"boolean","description":"Whether the button shows a loading spinner.","default":"false"},{"name":"icon","type":"ReactNode","description":"Icon element. When provided without children, button becomes icon-only with tooltip from label.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"pressedIcon","type":"ReactNode","description":"Icon shown when pressed. Falls back to icon if not provided.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"children","type":"ReactNode","description":"Visible content. If omitted with icon, button becomes icon-only."},{"name":"tooltip","type":"string","description":"Tooltip text shown on hover."},{"name":"value","type":"string","description":"Value identifier when used inside XDSToggleButtonGroup. Required in groups."},{"name":"data-testid","type":"string","description":"Test selector for automated testing frameworks."}],"usage":{"description":"ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.","bestPractices":[{"guidance":true,"description":"Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example."},{"guidance":true,"description":"Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change."},{"guidance":true,"description":"Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set."},{"guidance":false,"description":"Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\" — those are regular Buttons, not toggles."},{"guidance":false,"description":"Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup."},{"guidance":false,"description":"Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates \"setting\" semantics."}],"anatomy":[{"name":"Icon","required":false,"description":"A leading icon that represents the toggle action, like a star for favorite or bold \"B\" for formatting."},{"name":"Pressed icon","required":false,"description":"An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state."},{"name":"Label","required":true,"description":"The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip."},{"name":"Spinner","required":false,"description":"Replaces the icon during async operations triggered by pressedChangeAction."}]},"theming":{"targets":[{"className":"xds-toggle-button-group"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"value":"option-1","label":"Toggle Group"}}},{"name":"ToggleButtonGroup","moduleName":"XDSToggleButtonGroup","directory":"ToggleButton","group":"Button","description":"Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.","keywords":["toggle","togglebutton","pressed","toolbar","formatting","segmented","button-group","exclusive","multi-select"],"hidden":false,"parentDoc":"ToggleButton","props":[{"name":"children","type":"ReactNode","description":"XDSToggleButton children.","required":true,"slotElements":[{"element":"XDSToggleButton","props":{"label":"Option","value":"option"}}]},{"name":"label","type":"string","description":"Accessible label for the group (aria-label).","required":true},{"name":"type","type":"'single' | 'multiple'","description":"Selection mode. Single allows one active button, multiple allows many.","default":"'single'"},{"name":"value","type":"string | null | string[]","description":"Currently selected value(s). Type depends on selection mode.","required":true},{"name":"onChange","type":"(value: string | null | string[]) => void","description":"Called when selection changes.","required":true},{"name":"orientation","type":"'horizontal' | 'vertical'","description":"Layout direction of the button group.","default":"'horizontal'"},{"name":"size","type":"'sm' | 'md' | 'lg'","description":"Default size for buttons in the group. Individual buttons can override.","default":"'md'"},{"name":"isDisabled","type":"boolean","description":"Whether all buttons in the group are disabled.","default":"false"},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value."},{"name":"data-testid","type":"string","description":"Test selector for automated testing frameworks."}],"usage":{"description":"ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.","bestPractices":[{"guidance":true,"description":"Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example."},{"guidance":true,"description":"Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change."},{"guidance":true,"description":"Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set."},{"guidance":false,"description":"Don't use a ToggleButton for one-time actions like \"Submit\" or \"Delete\" — those are regular Buttons, not toggles."},{"guidance":false,"description":"Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup."},{"guidance":false,"description":"Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates \"setting\" semantics."}],"anatomy":[{"name":"Icon","required":false,"description":"A leading icon that represents the toggle action, like a star for favorite or bold \"B\" for formatting."},{"name":"Pressed icon","required":false,"description":"An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state."},{"name":"Label","required":true,"description":"The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip."},{"name":"Spinner","required":false,"description":"Replaces the icon during async operations triggered by pressedChangeAction."}]},"theming":{"targets":[{"className":"xds-toggle-button-group"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"value":"option-1","label":"Toggle Group"}}},{"name":"Token","moduleName":"XDSToken","directory":"Token","group":null,"description":"Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.","keywords":["token","chip","tag","pill","label","removable","dismissible","filter chip","closable"],"hidden":false,"parentDoc":null,"props":[{"name":"label","type":"string","description":"Text label displayed inside the token.","required":true},{"name":"size","type":"'sm' | 'md'","description":"The size of the token.","default":"'md'"},{"name":"color","type":"'default' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'purple' | 'pink' | 'gray'","description":"Color variant of the token.","default":"'default'"},{"name":"icon","type":"ReactNode","description":"Optional icon rendered before the label.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"isDisabled","type":"boolean","description":"Whether the token is disabled; reduces opacity and blocks interactions.","default":"false"},{"name":"onRemove","type":"(e: React.MouseEvent) => void","description":"Callback fired when the remove button is clicked. When provided, an X button is rendered inside the token."},{"name":"onClick","type":"(e: React.MouseEvent) => void","description":"Click handler. When provided, the token renders as a <span> container with an invisible <button> inside for accessibility."},{"name":"href","type":"string","description":"Link URL. When provided, the token renders as an <a> element."},{"name":"description","type":"string","description":"Accessible description applied via aria-description on the root element."},{"name":"endContent","type":"ReactNode","description":"Content rendered after the label and before the remove button.","slotElements":[{"element":"XDSIcon","props":{"icon":"chevronDown","size":"sm"}},{"element":"XDSBadge","props":{"label":"3"}}]},{"name":"isLabelHidden","type":"boolean","description":"Visually hides the label using a screen-reader-only clip technique; the label remains accessible.","default":"false"},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"Token is a small, inline element for representing discrete pieces of associated data — like tags, categories, or selections. Use it to label content, show active filters, or represent removable items like selected recipients in a compose field.","bestPractices":[{"guidance":true,"description":"Use color to distinguish categories — for example, green for \"Active\", red for \"Blocked\", blue for \"In Review\" — so users can scan status at a glance."},{"guidance":true,"description":"Provide an onRemove callback when tokens represent user selections that can be undone, like filters or multi-select values."},{"guidance":true,"description":"Add a leading icon when it helps identify the token type faster, like a person icon for user tokens or a tag icon for labels."},{"guidance":true,"description":"Keep labels short — one to three words. Tokens truncate with ellipsis when the text overflows."},{"guidance":false,"description":"Don't use tokens for primary actions or navigation — use Button or Link instead. Tokens are for displaying metadata, not triggering workflows."},{"guidance":false,"description":"Don't hide the label unless the icon alone is universally understood. A color dot without text is ambiguous."},{"guidance":false,"description":"Don't mix too many colors in one token group. Stick to two or three meaningful colors so the palette stays scannable."}],"anatomy":[{"name":"Icon","required":false,"description":"A leading icon that identifies the token type, like a user avatar or category symbol."},{"name":"Label","required":true,"description":"The visible text. Also used as the accessible name when isLabelHidden is true."},{"name":"End content","required":false,"description":"Trailing content after the label, like a count badge or status dot."},{"name":"Remove button","required":false,"description":"An X button that appears when onRemove is provided, letting users dismiss the token."}]},"theming":{"targets":[{"className":"xds-token","visualProps":["color","size"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Tokenizer","moduleName":"XDSTokenizer","directory":"Tokenizer","group":null,"description":"Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.","keywords":["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],"hidden":false,"parentDoc":null,"props":[{"name":"label","type":"string","description":"Accessible label for the input.","required":true},{"name":"searchSource","type":"XDSSearchSource<T>","description":"Data source providing search and bootstrap methods for populating the dropdown.","required":true},{"name":"value","type":"T[]","description":"Array of currently selected items.","required":true},{"name":"onChange","type":"(items: T[], change: XDSTokenizerChange<T>) => void","description":"Called when selection changes. The change argument includes the affected item and type ('add' | 'create' | 'remove' | 'reorder').","required":true},{"name":"placeholder","type":"string","description":"Input placeholder text. Only shown when no tokens are selected."},{"name":"maxEntries","type":"number","description":"Maximum number of selections allowed. Input is hidden when the limit is reached."},{"name":"hasClear","type":"boolean","description":"Show a clear-all button for bulk removal of all tokens.","default":"false"},{"name":"renderToken","type":"(item: T, onRemove: () => void) => ReactNode","description":"Custom render function for selected tokens. Default renders XDSToken with label and onRemove."},{"name":"renderItem","type":"(item: T) => ReactNode","description":"Custom render function for dropdown items. Default renders XDSTypeaheadItem."},{"name":"isDisabled","type":"boolean","description":"Disables the input and all token interactions.","default":"false"},{"name":"status","type":"XDSInputStatus","description":"Validation status object with type and message for error/warning/success states."},{"name":"isLabelHidden","type":"boolean","description":"Visually hides the label while keeping it accessible.","default":"false"},{"name":"description","type":"string","description":"Helper text displayed below the label."},{"name":"isRequired","type":"boolean","description":"Marks the field as required.","default":"false"},{"name":"isOptional","type":"boolean","description":"Shows an optional indicator on the label.","default":"false"},{"name":"labelTooltip","type":"string","description":"Tooltip text shown on the label."},{"name":"hasEntriesOnFocus","type":"boolean","description":"Show bootstrap results on focus before typing.","default":"false"},{"name":"maxMenuItems","type":"number","description":"Maximum number of dropdown items to display.","default":"10"},{"name":"emptySearchResultsText","type":"string","description":"Text shown when search returns no results.","default":"'No results found'"},{"name":"hasAutoFocus","type":"boolean","description":"Auto-focus the input on mount.","default":"false"},{"name":"size","type":"'sm' | 'md'","description":"Input and token size.","default":"'md'"},{"name":"debounceMs","type":"number","description":"Debounce delay in ms before triggering search. Set to 0 for synchronous sources.","default":"150"},{"name":"hasCreate","type":"boolean","description":"Allow users to create new tokens from free-text input. When true, a \"Create\" option appears in the dropdown for typed text that doesn't match existing results. The onChange change type is 'create' for these items.","default":"false"},{"name":"onChangeQuery","type":"(query: string) => void","description":"Callback fired when the search query text changes."},{"name":"endContent","type":"ReactNode","description":"Content to display at the end of the input row. Useful for buttons, result counts, or other controls.","slotElements":[{"element":"XDSIcon","props":{"icon":"chevronDown","size":"sm"}},{"element":"XDSBadge","props":{"label":"3"}}]},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"Tokenizer is a multi-select input that lets users search, select, and manage multiple items displayed as removable chips. Use it when users need to build a set of selections from a searchable data source, like adding team members, applying tags, or choosing filters.","bestPractices":[{"guidance":true,"description":"Write a placeholder that tells users what they can search for — \"Search people…\" or \"Add tags…\" — so the input is not a blank mystery."},{"guidance":true,"description":"Set maxEntries when the number of selections should be bounded, like limiting a review to 5 approvers."},{"guidance":true,"description":"Use hasCreate for free-form tagging where users need to enter values that do not exist in the search source."},{"guidance":true,"description":"Show validation status with the status prop so users know immediately when a selection is missing or invalid."},{"guidance":false,"description":"Don’t use Tokenizer for single-item selection — use Typeahead instead. Tokenizer is for building sets of two or more items."},{"guidance":false,"description":"Avoid applying custom colors to individual tokens inside a Tokenizer — use the default token style for visual consistency across the set."},{"guidance":false,"description":"Don’t hide the label — every Tokenizer needs a visible label so users understand what they are selecting. Use isLabelHidden only when surrounding context makes the purpose obvious."}],"anatomy":[{"name":"Label","required":true,"description":"The visible text above the input describing what the user is selecting. Also used as the accessible name."},{"name":"Token chips","required":false,"description":"Removable chips representing each selected item. Each chip shows a label and a remove button."},{"name":"Search input","required":true,"description":"The text input where users type to search the data source. Hides when maxEntries is reached."},{"name":"Dropdown menu","required":false,"description":"The search results list that appears below the input as the user types."},{"name":"End content","required":false,"description":"A trailing slot after the input for action buttons, counts, or other controls."},{"name":"Clear button","required":false,"description":"A button that removes all selected tokens at once. Shown when hasClear is true and tokens are present."}]},"theming":{"targets":[{"className":"xds-tokenizer","visualProps":["size"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Toolbar","moduleName":"XDSToolbar","directory":"Toolbar","group":null,"description":"General-purpose toolbar container with three content slots and roving tabindex.","keywords":["toolbar","nav","bar","actions","buttonbar","header","footer","action-bar","control-bar"],"hidden":false,"parentDoc":"Toolbar","props":[{"name":"label","type":"string","description":"Accessible label for the toolbar, applied as aria-label.","required":true},{"name":"startContent","type":"ReactNode","description":"Content aligned to the start (left in LTR).","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"centerContent","type":"ReactNode","description":"Centered content. Switches layout to CSS grid (1fr auto 1fr).","slotElements":[{"element":"XDSText","props":{"type":"body","weight":"bold"},"children":"Center"}]},{"name":"endContent","type":"ReactNode","description":"Content aligned to the end (right in LTR).","slotElements":[{"element":"XDSIcon","props":{"icon":"chevronDown","size":"sm"}},{"element":"XDSBadge","props":{"label":"3"}}]},{"name":"density","type":"'compact' | 'default'","description":"Toolbar density. Controls minimum height.","default":"'default'"},{"name":"gap","type":"SpacingStep","description":"Gap between items within each slot.","default":"2"},{"name":"orientation","type":"'horizontal' | 'vertical'","description":"Orientation for keyboard navigation. Controls arrow key direction.","default":"'horizontal'"},{"name":"variant","type":"XDSSectionVariant","description":"Visual variant passed to XDSSection.","default":"'transparent'"},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization. Must be a stylex.create() value."}],"usage":{"description":"Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area — above a table, inside a card, or in a panel — not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.","bestPractices":[{"guidance":true,"description":"Put secondary actions like \"Back\" on the left, and primary actions like \"Save\" on the right."},{"guidance":true,"description":"Make temporary toolbars like bulk selection visually distinct so users can tell they're contextual — for example, with a background color or border."},{"guidance":true,"description":"Visually separate the toolbar from the content below it — with a divider, a background variant, or both."},{"guidance":true,"description":"Use Toolbar as a card header when the header has interactive actions like filter or add — it gives you slot layout, keyboard navigation, and size cascading. If the header is just a title with no actions, a LayoutHeader or Section is enough."},{"guidance":false,"description":"Put too many actions in one toolbar — move less common items into a MoreMenu."},{"guidance":false,"description":"Set size on individual child buttons — set it once on the toolbar and it cascades automatically."},{"guidance":false,"description":"Use Toolbar for app-wide navigation like main menu links or sign out — use TopNav or LayoutHeader for that."}]},"theming":{"targets":[{"className":"xds-toolbar","states":["density"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Tooltip","moduleName":"XDSTooltip","directory":"Tooltip","group":"Tooltip","description":"Component wrapper for tooltip display triggered on hover or focus.","keywords":["tooltip","hint","infotip","title","hover","flyout","balloon","helpertext"],"hidden":false,"parentDoc":"Tooltip","props":[{"name":"children","type":"ReactNode","description":"Trigger element(s) that activate the tooltip."},{"name":"anchorRef","type":"RefObject<HTMLElement>","description":"External anchor ref for sibling mode."},{"name":"content","type":"ReactNode","description":"Tooltip content, typically short text.","slotElements":[{"element":"XDSText","props":{"type":"body"},"children":"Content text"}]},{"name":"placement","type":"LayerPlacement","description":"Position relative to the anchor element.","default":"'above'"},{"name":"alignment","type":"LayerAlignment","description":"Alignment along the placement axis.","default":"'center'"},{"name":"delay","type":"number","description":"Show delay in milliseconds.","default":"200"},{"name":"hideDelay","type":"number","description":"Hide delay in milliseconds.","default":"0"},{"name":"focusTrigger","type":"'auto' | 'always' | 'never'","description":"Controls when focus events trigger the tooltip.","default":"'auto'"},{"name":"isEnabled","type":"boolean","description":"Enables or disables the tooltip triggers.","default":"true"},{"name":"onOpenChange","type":"(isOpen: boolean) => void","description":"Callback fired when tooltip visibility changes. Called with true when shown and false when hidden."},{"name":"hasHoverIndication","type":"'auto' | boolean","description":"Shows a dashed underline on the trigger element.","default":"'auto'"},{"name":"isDefaultOpen","type":"boolean","description":"Whether the tooltip should be shown on mount. Still dismissible."}],"usage":{"description":"A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.","bestPractices":[{"guidance":true,"description":"Keep tooltip content concise — aim for under 140 characters of plain text."},{"guidance":true,"description":"Add a tooltip to icon-only buttons and controls that lack a visible label."},{"guidance":false,"description":"Place interactive elements like links or buttons inside a tooltip — use HoverCard or Popover instead."},{"guidance":false,"description":"Use tooltips for essential information that users must see to complete a task."}]},"theming":{"targets":[{"className":"xds-tooltip"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"content":"Helpful tooltip text","children":{"element":"XDSButton","props":{"label":"Hover me","variant":"secondary"}}}}},{"name":"TopNav","moduleName":"XDSTopNav","directory":"TopNav","group":"TopNav","description":"Main navigation bar container with slot-based layout.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"heading","type":"ReactNode","description":"Heading slot content (logo, brand) — positioned at the left edge of the nav bar.","slotElements":[{"element":"XDSText","props":{"type":"body","weight":"bold"},"children":"Heading"}]},{"name":"startContent","type":"ReactNode","description":"Start content slot for navigation items or breadcrumbs — positioned after the heading, left-aligned.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"centerContent","type":"ReactNode","description":"Center content slot (tabs, search bar, primary navigation) — when provided, switches the layout to a three-column CSS grid for true horizontal centering.","slotElements":[{"element":"XDSText","props":{"type":"body","weight":"bold"},"children":"Center"}]},{"name":"endContent","type":"ReactNode","description":"End content slot for search, icons, or user profile — positioned at the right edge.","slotElements":[{"element":"XDSIcon","props":{"icon":"chevronDown","size":"sm"}},{"element":"XDSBadge","props":{"label":"3"}}]},{"name":"label","type":"string","description":"Accessible label for the navigation landmark, applied as aria-label on the <nav> element."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TopNavHeading","moduleName":"XDSTopNavHeading","directory":"TopNav","group":"TopNav","description":"Product/suite/account heading for the XDSTopNav heading slot. Supports smart interaction boundary logic: logo, heading text, superheading/subheading with independent links, and an optional menu popover with automatic chevron indicator.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"logo","type":"ReactNode","description":"Logo element to display before the heading text. Can be an image, XDSNavIcon, or any ReactNode.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"heading","type":"string","description":"Product/app name displayed as the primary heading text."},{"name":"headingHref","type":"string","description":"Link for the heading text (e.g. product home). When no menu is present and this is the only href, the whole heading becomes one clickable link."},{"name":"href","type":"string","description":"Deprecated — use headingHref instead. URL to navigate to when clicked."},{"name":"superheading","type":"string","description":"Text above the heading (e.g. suite name). Rendered in a smaller secondary style."},{"name":"superheadingHref","type":"string","description":"Link for the superheading text (e.g. suite home). When provided alongside a menu, renders as an independent inline link."},{"name":"subheading","type":"string","description":"Text below the heading (e.g. account context). Rendered in a smaller secondary style."},{"name":"subheadingHref","type":"string","description":"Link for the subheading text. When provided alongside a menu, renders as an independent inline link."},{"name":"headerEndContent","type":"ReactNode","description":"Content rendered at the trailing edge of the heading row (e.g. a badge or status indicator).","slotElements":[{"element":"XDSButton","props":{"label":"Action","variant":"ghost","size":"sm"}}]},{"name":"menu","type":"ReactNode","description":"Menu content shown in a popover dropdown. When provided, a chevron indicator appears automatically. Interaction boundary is determined by the presence of hrefs: no hrefs means the whole header is the trigger; with hrefs, links are independent and the chevron area is the trigger.","slotElements":[{"element":"XDSButton","props":{"label":"Action","variant":"ghost","size":"sm"}}]},{"name":"as","type":"XDSLinkComponentType","description":"Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization. Must be a stylex.create() value."}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TopNavItem","moduleName":"XDSTopNavItem","directory":"TopNav","group":"TopNav","description":"Navigation link item for use in XDSTopNav startContent — renders as an anchor with hover and selected states.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"label","type":"string","description":"Accessible label for the nav item. Rendered as visible text by default. When isIconOnly is true, used as aria-label instead.","required":true},{"name":"href","type":"string","description":"Navigation target URL."},{"name":"isSelected","type":"boolean","description":"Whether this nav item is currently selected. Sets aria-current=\"page\" and applies highlighted styles.","default":"false"},{"name":"isDisabled","type":"boolean","description":"Whether the nav item is disabled. Sets aria-disabled and prevents interaction.","default":"false"},{"name":"isIconOnly","type":"boolean","description":"Renders the item as a square icon-only element. When true, label becomes the aria-label and visible text is hidden. Requires icon to be set.","default":"false"},{"name":"icon","type":"ReactNode","description":"Optional icon to display before the label.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"children","type":"ReactNode","description":"Custom content to render instead of the label text."},{"name":"as","type":"XDSLinkComponentType","description":"Custom component to render instead of <a>. Overrides the provider-level default set by XDSLinkProvider. Must accept href, className, style, and children props."}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TopNavMegaMenu","moduleName":"XDSTopNavMegaMenu","directory":"TopNav","group":"TopNav","description":"Navigation item that displays a full-width mega menu panel on hover. Uses a slots API with items and featured props. XDSTopNavMegaMenuItem renders itself in both desktop and mobile drawer modes. Supports inline collapsible drawer via render mode context.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"label","type":"string","description":"Visible label for the trigger button.","required":true},{"name":"items","type":"ReactNode","description":"Menu items slot — typically XDSTopNavMegaMenuItem components, but accepts any ReactNode.","slotElements":[{"element":"XDSTopNavItem","props":{"label":"Item","href":"#"}}]},{"name":"featured","type":"ReactNode","description":"Featured content slot — rendered in the right panel on desktop, below items in the mobile drawer.","slotElements":[{"element":"XDSCard","props":{"padding":4},"children":"Featured content"}]},{"name":"delay","type":"number","description":"Delay in milliseconds before showing the menu on hover.","default":"150"},{"name":"hideDelay","type":"number","description":"Delay in milliseconds before hiding the menu after the mouse leaves.","default":"250"},{"name":"onOpenChange","type":"(isOpen: boolean) => void","description":"Callback fired when the mega menu opens or closes. Useful for coordinating wrapper styles."}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TopNavMegaMenuFeaturedCard","moduleName":"XDSTopNavMegaMenuFeaturedCard","directory":"TopNav","group":"TopNav","description":"Standard featured card for the XDSTopNavMegaMenu featured slot. Provides a consistent card with optional image, title, description, and CTA link.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"title","type":"string","description":"Card title.","required":true},{"name":"description","type":"string","description":"Description text below the title."},{"name":"image","type":"string","description":"Optional image URL displayed above the body."},{"name":"imageAlt","type":"string","description":"Alt text for the image."},{"name":"linkLabel","type":"string","description":"CTA link text."},{"name":"linkHref","type":"string","description":"CTA link URL."},{"name":"children","type":"ReactNode","description":"Custom content rendered below the standard body."}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TopNavMegaMenuItem","moduleName":"XDSTopNavMegaMenuItem","directory":"TopNav","group":"TopNav","description":"An individual item inside an XDSTopNavMegaMenu. Renders itself in both desktop (popover grid) and mobile drawer modes via render mode context.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"title","type":"string","description":"Display title for the menu item.","required":true},{"name":"description","type":"string","description":"Optional description text displayed below the title."},{"name":"icon","type":"ReactNode","description":"Optional icon element displayed to the left.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"href","type":"string","description":"URL to navigate to when clicked."},{"name":"onClick","type":"() => void","description":"Callback when item is clicked."},{"name":"as","type":"XDSLinkComponentType","description":"Custom component to render instead of <a> for link items. Overrides the provider-level default set by XDSLinkProvider."}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TopNavMenu","moduleName":"XDSTopNavMenu","directory":"TopNav","group":"TopNav","description":"Navigation item that displays a hover-triggered popover menu with rich items containing an icon, title, and optional description.","keywords":["topnav","navbar","appbar","header","toolbar","navigation","menubar","topbar"],"hidden":false,"parentDoc":"TopNav","props":[{"name":"label","type":"string","description":"Visible label for the trigger button.","required":true},{"name":"items","type":"XDSTopNavMenuItemData[]","description":"Menu items to display in the hover popover.","required":true},{"name":"delay","type":"number","description":"Delay in milliseconds before showing the menu on hover.","default":"150"},{"name":"hideDelay","type":"number","description":"Delay in milliseconds before hiding the menu after the mouse leaves.","default":"200"}],"usage":{"description":"TopNav is a horizontal navigation bar for product-level navigation in application headers. Use TopNav for 5 or fewer always-visible navigation items, or minimal navigation paired with search and controls. For complex navigation hierarchies, use a sidebar; to filter content, use tabs or filter buttons instead.","bestPractices":[{"guidance":true,"description":"Include a product logo and name in the heading slot to clearly identify the application."},{"guidance":true,"description":"Limit primary navigation items to 5 or fewer for quick scanning and minimal cognitive load."},{"guidance":false,"description":"Avoid using TopNav to filter page content — use Tabs or filter controls instead."},{"guidance":false,"description":"Avoid deeply nested navigation hierarchies — keep menus to one level of depth."}],"anatomy":[{"name":"Product icon and name","required":true,"description":"Identifies the product in the navigation bar."},{"name":"Navigation items","required":true,"description":"Primary links for product-level destinations."},{"name":"More menu","required":false,"description":"Overflow menu for additional navigation items."},{"name":"Flex area","required":false,"description":"Flexible region for search, primary action buttons, or other controls."}]},"theming":{"targets":[{"className":"xds-top-nav","states":["mode"]},{"className":"xds-top-nav-item","states":["mode"]},{"className":"xds-top-nav-heading"},{"className":"xds-top-nav-mega-menu","states":["mode"]},{"className":"xds-top-nav-mega-menu-item","states":["mode"]},{"className":"xds-top-nav-mega-menu-featured-card"},{"className":"xds-top-nav-menu"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Navigation","heading":{"element":"XDSTopNavHeading","props":{"heading":"My App"}}}}},{"name":"TreeList","moduleName":"XDSTreeList","directory":"TreeList","group":"TreeList","description":"Tree list container. Accepts items data and rendering configuration. Expansion state is managed internally.","keywords":["tree","hierarchy","nested","accordion","folder","expand","collapse","treeview","outline"],"hidden":false,"parentDoc":"TreeList","props":[{"name":"items","type":"XDSTreeListItemData[]","description":"Recursive tree item data. Each item has id, label, optional children array, and optional isExpanded boolean for initial state.","required":true},{"name":"density","type":"'compact' | 'balanced' | 'spacious'","description":"Spacing density for items.","default":"'balanced'"},{"name":"header","type":"ReactNode","description":"Header content, associated with the tree via aria-labelledby.","slotElements":[{"element":"XDSText","props":{"type":"body"},"children":"Header"}]},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization. Must be a stylex.create() value."}],"usage":{"description":"An expandable tree structure for displaying hierarchical data with branch connector lines. Use it for file explorers, nested category browsers, or any interface that visualizes parent-child relationships.","bestPractices":[{"guidance":true,"description":"Provide meaningful labels and icons for each node to make the hierarchy easy to scan."},{"guidance":true,"description":"Pre-expand important branches so users see key content immediately."},{"guidance":false,"description":"Nest more than 4–5 levels deep — flatten the structure or use a different pattern."},{"guidance":false,"description":"Use a tree for flat, non-hierarchical data — use a List instead."}]},"theming":{"targets":[{"className":"xds-tree-list","visualProps":["density"]},{"className":"xds-tree-list-item","states":["selected","disabled"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"items":[{"id":"1","label":"Documents","children":[{"id":"1a","label":"Report.pdf"},{"id":"1b","label":"Notes.md"}]},{"id":"2","label":"Images","children":[{"id":"2a","label":"Photo.jpg"}]},{"id":"3","label":"README.md"}]}}},{"name":"Typeahead","moduleName":"XDSTypeahead","directory":"Typeahead","group":"Typeahead","description":"Styled typeahead with label, description, validation, and all field features. Wraps XDSBaseTypeahead with XDSField for the primary use case.","keywords":["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],"hidden":false,"parentDoc":"Typeahead","props":[{"name":"label","type":"string","description":"Accessible label for the input.","required":true},{"name":"searchSource","type":"XDSSearchSource<T>","description":"Data source providing search and bootstrap methods for populating the dropdown.","required":true},{"name":"value","type":"T | null","description":"Currently selected item, or null if nothing is selected.","required":true},{"name":"onChange","type":"(item: T | null) => void","description":"Called when the selection changes.","required":true},{"name":"placeholder","type":"string","description":"Input placeholder text."},{"name":"hasEntriesOnFocus","type":"boolean","description":"Show bootstrap results on focus before typing.","default":"false"},{"name":"hasClear","type":"boolean","description":"Show clear button to deselect the current value.","default":"true"},{"name":"isDisabled","type":"boolean","description":"Disables the input.","default":"false"},{"name":"maxMenuItems","type":"number","description":"Maximum number of dropdown items to display.","default":"10"},{"name":"status","type":"XDSInputStatus","description":"Validation status object with type and message for error/warning/success states."},{"name":"renderItem","type":"(item: T) => ReactNode","description":"Custom render function for dropdown items. Default renders XDSTypeaheadItem."},{"name":"isLabelHidden","type":"boolean","description":"Visually hides the label while keeping it accessible.","default":"false"},{"name":"description","type":"string","description":"Helper text displayed below the label."},{"name":"isRequired","type":"boolean","description":"Marks the field as required.","default":"false"},{"name":"isOptional","type":"boolean","description":"Shows an optional indicator on the label.","default":"false"},{"name":"labelTooltip","type":"string","description":"Tooltip text shown on the label."},{"name":"emptySearchResultsText","type":"string","description":"Text shown when search returns no results.","default":"'No results found'"},{"name":"hasAutoFocus","type":"boolean","description":"Auto-focus the input on mount.","default":"false"},{"name":"size","type":"'sm' | 'md'","description":"Input and token size.","default":"'md'"},{"name":"debounceMs","type":"number","description":"Debounce delay in ms before triggering search. Set to 0 for synchronous sources.","default":"150"},{"name":"onChangeQuery","type":"(query: string) => void","description":"Callback fired when the search query text changes."},{"name":"onOpenChange","type":"(isOpen: boolean) => void","description":"Callback when the dropdown opens or closes."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.","bestPractices":[{"guidance":true,"description":"Provide descriptive placeholder text that hints at what users can search for."},{"guidance":true,"description":"Show suggestions on focus when users benefit from seeing popular or recent options before typing."},{"guidance":true,"description":"Add a search delay for remote data sources to avoid excessive network requests."},{"guidance":false,"description":"Use for short, static option lists — use Selector for better discoverability."},{"guidance":false,"description":"Use for multi-selection — use Tokenizer instead."},{"guidance":false,"description":"Place multiple Typeaheads adjacent to each other without clear labels differentiating them."}]},"theming":{"targets":[{"className":"xds-typeahead","visualProps":["status"]},{"className":"xds-typeahead-dropdown"},{"className":"xds-typeahead-item"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"TypeaheadItem","moduleName":"XDSTypeaheadItem","directory":"Typeahead","group":"Typeahead","description":"Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.","keywords":["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],"hidden":false,"parentDoc":"Typeahead","props":[{"name":"item","type":"XDSSearchableItem","description":"The search result item to render.","required":true},{"name":"icon","type":"ReactNode","description":"Icon or avatar to display before the label.","slotElements":[{"element":"XDSIcon","props":{"icon":"check","size":"sm"}}]},{"name":"description","type":"string","description":"Description text displayed below the label."},{"name":"isDisabled","type":"boolean","description":"Whether this item is visually disabled.","default":"false"},{"name":"group","type":"string","description":"Group label for grouping items visually."}],"usage":{"description":"A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.","bestPractices":[{"guidance":true,"description":"Provide descriptive placeholder text that hints at what users can search for."},{"guidance":true,"description":"Show suggestions on focus when users benefit from seeing popular or recent options before typing."},{"guidance":true,"description":"Add a search delay for remote data sources to avoid excessive network requests."},{"guidance":false,"description":"Use for short, static option lists — use Selector for better discoverability."},{"guidance":false,"description":"Use for multi-selection — use Tokenizer instead."},{"guidance":false,"description":"Place multiple Typeaheads adjacent to each other without clear labels differentiating them."}]},"theming":{"targets":[{"className":"xds-typeahead","visualProps":["status"]},{"className":"xds-typeahead-dropdown"},{"className":"xds-typeahead-item"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"useClickableContainer","moduleName":"useClickableContainer","directory":"hooks","group":null,"description":"Makes a container element clickable while preserving nested interactive element behavior. Solves the \"nested interactive elements\" problem: when a card is clickable but contains buttons/links, clicking those should NOT trigger the card's action. Detects interactive ancestors between the click target and the container, and ignores text selections. Supports href navigation (including middle-click and Ctrl/Cmd+click for new tabs).","keywords":["click","container","card","pressable","interactive","nested","link","button","delegate"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Makes a container element clickable while preserving nested interactive element behavior. Solves the \"nested interactive elements\" problem: when a card is clickable but contains buttons/links, clicking those should NOT trigger the card's action. Detects interactive ancestors between the click target and the container, and ignores text selections. Supports href navigation (including middle-click and Ctrl/Cmd+click for new tabs).","bestPractices":[{"guidance":true,"description":"Attach both onClick and onMouseUp to the container element for full click handling including middle-click."},{"guidance":true,"description":"Use inside XDSClickableCard or XDSSelectableCard for the standard card interaction pattern."},{"guidance":false,"description":"Use when the entire container is a single interactive element — just use a <button> or <a> directly."}]},"theming":null,"params":[{"name":"options","type":"UseClickableContainerOptions","description":"Configuration object for the clickable container.","required":true},{"name":"options.containerRef","type":"RefObject<HTMLElement | null>","description":"Ref to the outer container element.","required":true},{"name":"options.interactiveRef","type":"RefObject<HTMLElement | null>","description":"Ref to the primary interactive element inside (link, button). If no onClick or href is provided, clicks are proxied to this element.","required":false},{"name":"options.onClick","type":"(event: MouseEvent<HTMLElement>) => void","description":"Click handler fired when the container surface (not a nested interactive element) is clicked.","required":false},{"name":"options.href","type":"string","description":"Navigation URL. When provided, clicking the container navigates to this URL.","required":false},{"name":"options.target","type":"string","description":"Link target (e.g., '_blank'). Used with href for navigation behavior.","required":false},{"name":"options.disabled","type":"boolean","description":"Whether the container is disabled.","default":"false","required":false}],"returns":[{"name":"onClick","type":"(event: MouseEvent<HTMLElement>) => void","description":"Click handler to attach to the container element."},{"name":"onMouseUp","type":"(event: MouseEvent<HTMLElement>) => void","description":"Mouse up handler to attach to the container (handles middle-click navigation for href)."}],"relatedComponents":["ClickableCard","SelectableCard"],"relatedHooks":["useInputContainer"],"playground":null},{"name":"useEntryAnimation","moduleName":"useEntryAnimation","directory":"hooks","group":null,"description":"Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint — elements rendered on page load are not animated. Uses XDS motion tokens (duration, easing) for consistent animation timing. Requires \"use client\" — does not support SSR.","keywords":["animation","entry","mount","transition","slide","fade","scale","motion","stylex"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint — elements rendered on page load are not animated. Uses XDS motion tokens (duration, easing) for consistent animation timing. Requires \"use client\" — does not support SSR.","bestPractices":[{"guidance":true,"description":"Use for conditionally rendered elements like validation messages, toasts, or expanding sections."},{"guidance":true,"description":"Spread the returned style into stylex.props() alongside other styles."},{"guidance":false,"description":"Use for elements that should be visible on initial page load — they will not animate."}]},"theming":null,"params":[{"name":"preset","type":"'slideDown' | 'slideUp' | 'fadeIn' | 'scaleIn'","description":"Animation preset to apply on mount.","default":"'slideDown'","required":false}],"returns":[{"name":"entryStyle","type":"StyleXStyles | null","description":"A StyleX style object for the entry animation, or null if the element was rendered on initial page load (no animation needed)."}],"relatedComponents":["FieldStatus"],"relatedHooks":[],"playground":null},{"name":"useFocusTrap","moduleName":"useFocusTrap","directory":"hooks","group":null,"description":"Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted — use a light-dismiss handler for that.","keywords":["focus","trap","modal","dialog","accessibility","a11y","keyboard","tab","escape","wai-aria"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Traps focus within a container element following the WAI-ARIA dialog focus trap pattern. Listens to focus events on the document and redirects focus back into the container if it escapes via keyboard navigation. Handles both Tab and Shift+Tab wrapping. Mouse clicks outside the container are not intercepted — use a light-dismiss handler for that.","bestPractices":[{"guidance":true,"description":"Call focusFirst() when opening a dialog/modal to move focus into the trapped region."},{"guidance":true,"description":"Provide an onEscape callback to close the dialog when Escape is pressed."},{"guidance":false,"description":"Use on non-modal content like tooltips or dropdowns — those need light-dismiss, not focus trapping."}]},"theming":null,"params":[{"name":"options","type":"UseFocusTrapOptions","description":"Configuration object for the focus trap.","required":true},{"name":"options.isActive","type":"boolean","description":"Whether the focus trap is currently active.","required":true},{"name":"options.onEscape","type":"() => void","description":"Callback when Escape key is pressed inside the trapped container.","required":false}],"returns":[{"name":"containerRef","type":"React.RefObject<HTMLElement | null>","description":"Ref to attach to the container element that should trap focus."},{"name":"focusFirst","type":"() => void","description":"Focuses the first focusable element inside the container."}],"relatedComponents":["Dialog","DatePicker"],"relatedHooks":["useListFocus","useScrollLock"],"playground":null},{"name":"useGridFocus","moduleName":"useGridFocus","directory":"hooks","group":null,"description":"Manages keyboard navigation within a 2D grid following the WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, and Page Up/Down for custom callbacks (e.g., month navigation in calendars). Boundary navigation callbacks allow seamless cross-grid navigation.","keywords":["grid","focus","keyboard","navigation","arrow","calendar","a11y","wai-aria","cells"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Manages keyboard navigation within a 2D grid following the WAI-ARIA grid pattern. Supports arrow keys for cell-to-cell navigation, Home/End for row boundaries, Ctrl+Home/Ctrl+End for grid boundaries, and Page Up/Down for custom callbacks (e.g., month navigation in calendars). Boundary navigation callbacks allow seamless cross-grid navigation.","bestPractices":[{"guidance":true,"description":"Use for calendar date grids — wire onPageUp/onPageDown to month navigation and onNavigateBefore/onNavigateAfter for cross-month arrow key navigation."},{"guidance":true,"description":"Attach both gridRef and handleKeyDown to the grid container element."},{"guidance":false,"description":"Use for simple linear lists — prefer useListFocus for 1D navigation."}]},"theming":null,"params":[{"name":"options","type":"UseGridFocusOptions","description":"Configuration object for grid focus behavior.","required":true},{"name":"options.columns","type":"number","description":"Number of columns in the grid. Used for up/down navigation (moves by this many cells).","required":true},{"name":"options.cellSelector","type":"string","description":"Selector for focusable cells within the grid.","default":"'button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])'","required":false},{"name":"options.onNavigateBefore","type":"(column: number, offset: number) => void","description":"Callback when navigation would go before the first cell. Receives the column index and offset (1 for horizontal, columns for vertical).","required":false},{"name":"options.onNavigateAfter","type":"(column: number, offset: number) => void","description":"Callback when navigation would go after the last cell. Receives the column index and offset.","required":false},{"name":"options.onPageUp","type":"() => void","description":"Callback for Page Up key (e.g., navigate to previous month in calendars).","required":false},{"name":"options.onPageDown","type":"() => void","description":"Callback for Page Down key (e.g., navigate to next month in calendars).","required":false}],"returns":[{"name":"gridRef","type":"React.RefObject<HTMLElement | null>","description":"Ref to attach to the grid container element."},{"name":"handleKeyDown","type":"(e: React.KeyboardEvent) => void","description":"Key down handler to attach to the grid container."},{"name":"focusCell","type":"(index: number) => void","description":"Focus a specific cell by index (clamped to valid range)."},{"name":"focusFirst","type":"() => void","description":"Focus the first focusable cell in the grid."},{"name":"focusLast","type":"() => void","description":"Focus the last focusable cell in the grid."}],"relatedComponents":["Calendar"],"relatedHooks":["useListFocus","useFocusTrap"],"playground":null},{"name":"useImageMode","moduleName":"useImageMode","directory":"hooks","group":null,"description":"Detects whether an image is predominantly dark or light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading and falls back gracefully on CORS or network errors.","keywords":["image","dark","light","mode","luminance","color","detect","theme","media","apca","contrast"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Detects whether an image is predominantly dark or light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path — no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading and falls back gracefully on CORS or network errors.","bestPractices":[{"guidance":true,"description":"Pair with XDSMediaTheme to automatically adapt text color over dynamic background images."},{"guidance":true,"description":"Use the region option to sample only the area where text overlays will appear for more accurate results."},{"guidance":false,"description":"Use for images that change rapidly (e.g., video frames) — each src change triggers a new fetch and analysis."}]},"theming":null,"params":[{"name":"src","type":"string | null | undefined","description":"Image source URL to analyze. When null/undefined, returns the fallback value.","required":true},{"name":"options","type":"UseImageModeOptions","description":"Optional configuration for image analysis.","required":false},{"name":"options.region","type":"ImageSampleRegion","description":"Region to sample within the image using normalized 0-1 coordinates ({ x, y, width, height }). Defaults to the full image.","required":false},{"name":"options.threshold","type":"number","description":"Luminance threshold for the dark/light split. Below = dark, above = light.","default":"0.5","required":false},{"name":"options.fallback","type":"'dark' | 'light' | null","description":"Fallback value while loading or on error.","default":"null","required":false}],"returns":[{"name":"mode","type":"'dark' | 'light' | null","description":"Detected luminance mode of the image. Returns null while loading or if src is null/undefined."}],"relatedComponents":["MediaTheme"],"relatedHooks":["useMediaQuery"],"playground":null},{"name":"useInputContainer","moduleName":"useInputContainer","directory":"hooks","group":null,"description":"Makes an input container wrapper clickable, delegating focus to the inner input/textarea when the user clicks non-interactive areas (icons, padding, status indicators). Built on top of useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) are handled safely — clicking them does NOT steal focus from the input. Automatically detects input type: text-like inputs receive .focus(), while other types (checkbox, radio, file) receive .click().","keywords":["input","container","focus","delegate","wrapper","text","textarea","click","icon","padding"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Makes an input container wrapper clickable, delegating focus to the inner input/textarea when the user clicks non-interactive areas (icons, padding, status indicators). Built on top of useClickableContainer, so nested interactive elements (clear buttons, calendar toggles, links) are handled safely — clicking them does NOT steal focus from the input. Automatically detects input type: text-like inputs receive .focus(), while other types (checkbox, radio, file) receive .click().","bestPractices":[{"guidance":true,"description":"Use inside input wrapper components (XDSTextInput, XDSNumberInput, XDSTimeInput, XDSTextArea) to make the full container area clickable."},{"guidance":true,"description":"Attach both onClick and onMouseUp to the wrapper div for full interaction handling."},{"guidance":false,"description":"Use on bare inputs without a wrapper — there is no benefit if the input already fills the full clickable area."}]},"theming":null,"params":[{"name":"options","type":"UseInputContainerOptions","description":"Configuration object for the input container.","required":true},{"name":"options.containerRef","type":"RefObject<HTMLElement | null>","description":"Ref to the outer container/wrapper element.","required":true},{"name":"options.inputRef","type":"RefObject<HTMLInputElement | HTMLTextAreaElement | HTMLElement | null>","description":"Ref to the inner input or textarea element.","required":true},{"name":"options.disabled","type":"boolean","description":"Whether the input is disabled.","default":"false","required":false}],"returns":[{"name":"onClick","type":"(event: MouseEvent<HTMLElement>) => void","description":"Click handler to attach to the container wrapper."},{"name":"onMouseUp","type":"(event: MouseEvent<HTMLElement>) => void","description":"Mouse up handler to attach to the container wrapper."}],"relatedComponents":["TextInput","NumberInput","TimeInput","TextArea"],"relatedHooks":["useClickableContainer"],"playground":null},{"name":"useListFocus","moduleName":"useListFocus","directory":"hooks","group":null,"description":"Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical or horizontal), Home/End for boundaries, optional wrap-around, and Escape to close. Suitable for dropdown menus, toolbars, and any 1D focusable list.","keywords":["list","focus","keyboard","navigation","menu","toolbar","roving","tabindex","a11y","arrow","wai-aria"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Manages keyboard navigation within a linear list following WAI-ARIA menu/listbox/toolbar patterns. Supports arrow key navigation (vertical or horizontal), Home/End for boundaries, optional wrap-around, and Escape to close. Suitable for dropdown menus, toolbars, and any 1D focusable list.","bestPractices":[{"guidance":true,"description":"Set orientation to 'horizontal' for toolbars and tab bars, 'vertical' for dropdown menus."},{"guidance":true,"description":"Provide an onEscape callback for menus/dropdowns to return focus to the trigger."},{"guidance":false,"description":"Use for 2D grid navigation — prefer useGridFocus for grids and calendars."}]},"theming":null,"params":[{"name":"options","type":"UseListFocusOptions","description":"Configuration object for list focus behavior. All fields are optional.","required":false},{"name":"options.itemSelector","type":"string","description":"Selector for focusable items within the list.","default":"'[role=\"menuitem\"]'","required":false},{"name":"options.wrap","type":"boolean","description":"Whether arrow navigation wraps around at the ends.","default":"true","required":false},{"name":"options.onEscape","type":"() => void","description":"Callback when Escape key is pressed (e.g., close menu).","required":false},{"name":"options.orientation","type":"'horizontal' | 'vertical'","description":"Navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown.","default":"'vertical'","required":false}],"returns":[{"name":"listRef","type":"React.RefObject<HTMLElement | null>","description":"Ref to attach to the list container element."},{"name":"handleKeyDown","type":"(e: React.KeyboardEvent) => void","description":"Key down handler to attach to the list container."},{"name":"focusItem","type":"(index: number) => void","description":"Focus a specific item by index (clamped to valid range)."},{"name":"focusFirst","type":"() => void","description":"Focus the first focusable item in the list."},{"name":"focusLast","type":"() => void","description":"Focus the last focusable item in the list."}],"relatedComponents":["TabMenu","Toolbar"],"relatedHooks":["useGridFocus","useFocusTrap"],"playground":null},{"name":"useMediaQuery","moduleName":"useMediaQuery","directory":"hooks","group":null,"description":"SSR-safe media query hook that subscribes to window.matchMedia changes. Returns whether the given media query matches. Always returns false on first render for SSR compatibility.","keywords":["responsive","breakpoint","media","mobile","desktop","screen","matchmedia"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"SSR-safe media query hook that subscribes to window.matchMedia changes. Returns whether the given media query matches. Always returns false on first render for SSR compatibility.","bestPractices":[{"guidance":true,"description":"Use for responsive layout switching based on viewport width, color scheme, or motion preferences."},{"guidance":true,"description":"Prefer XDS responsive tokens and component props over manual breakpoint logic when possible."},{"guidance":false,"description":"Use for server-rendered content that must match on first paint — the hook always returns false initially."}]},"theming":null,"params":[{"name":"query","type":"string","description":"CSS media query string to evaluate.","required":true}],"returns":[{"name":"matches","type":"boolean","description":"Whether the media query currently matches. Always false on first render (SSR-safe)."}],"relatedComponents":[],"relatedHooks":["useImageMode"],"playground":null},{"name":"useOverflow","moduleName":"useOverflow","directory":"hooks","group":null,"description":"Measures children rendered in a hidden container to determine how many fit in the available width without flickering. Uses ResizeObserver to react to container size changes. The measurement container should hold all items plus an optional overflow indicator element (identified by a data-overflow-indicator attribute).","keywords":["overflow","truncate","responsive","collapse","resize","measure","hidden","more","breadcrumb"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Measures children rendered in a hidden container to determine how many fit in the available width without flickering. Uses ResizeObserver to react to container size changes. The measurement container should hold all items plus an optional overflow indicator element (identified by a data-overflow-indicator attribute).","bestPractices":[{"guidance":true,"description":"Render all items into the measureRef container (hidden) and only the first visibleCount items into the containerRef container (visible)."},{"guidance":true,"description":"Include an overflow indicator (e.g., \"+N more\" button) as the last child of the measurement container with a data-overflow-indicator attribute."},{"guidance":false,"description":"Use for vertical overflow — this hook measures horizontal width only."}]},"theming":null,"params":[{"name":"itemCount","type":"number","description":"Total number of items to measure for overflow.","required":true},{"name":"options","type":"UseOverflowOptions","description":"Configuration object for overflow behavior.","required":false},{"name":"options.gap","type":"number","description":"Gap between items in pixels. Used in width calculations.","default":"0","required":false},{"name":"options.minVisibleItems","type":"number","description":"Minimum number of items to always show, even if they don't fit.","default":"0","required":false},{"name":"options.collapseFrom","type":"'start' | 'end'","description":"Which end to collapse items from.","default":"'end'","required":false},{"name":"options.behavior","type":"'observeParent' | 'observeSelf'","description":"Which element to observe for overflow calculations. 'observeParent' uses the container's parent element width, allowing the visible container to remain content-sized.","default":"'observeSelf'","required":false}],"returns":[{"name":"containerRef","type":"React.RefCallback<HTMLElement>","description":"Ref callback to attach to the visible container element."},{"name":"measureRef","type":"React.RefCallback<HTMLElement>","description":"Ref callback to attach to the hidden measurement container that holds all items."},{"name":"visibleCount","type":"number","description":"Number of items that fit in the visible container."},{"name":"hasOverflow","type":"boolean","description":"Whether any items are overflowing (visibleCount < itemCount)."}],"relatedComponents":["OverflowList","Breadcrumb"],"relatedHooks":["useScrollOverflow"],"playground":null},{"name":"useScrollLock","moduleName":"useScrollLock","directory":"hooks","group":null,"description":"Locks body scroll when active by pinning the body with position: fixed. This prevents background scrolling behind modals and dialogs, which is necessary for iOS Safari where overscroll-behavior: contain does not work. Restores the original scroll position when unlocked.","keywords":["scroll","lock","modal","dialog","body","prevent","background","ios","safari","fixed"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Locks body scroll when active by pinning the body with position: fixed. This prevents background scrolling behind modals and dialogs, which is necessary for iOS Safari where overscroll-behavior: contain does not work. Restores the original scroll position when unlocked.","bestPractices":[{"guidance":true,"description":"Use when opening full-screen modals or dialogs to prevent background content from scrolling."},{"guidance":true,"description":"Pass the same boolean that controls dialog visibility (e.g., isOpen) as the isLocked parameter."},{"guidance":false,"description":"Use for non-modal overlays like popovers or tooltips — users should be able to scroll away from those."}]},"theming":null,"params":[{"name":"isLocked","type":"boolean","description":"Whether body scroll should be locked.","required":true}],"returns":[],"relatedComponents":["Dialog"],"relatedHooks":["useFocusTrap"],"playground":null},{"name":"useScrollOverflow","moduleName":"useScrollOverflow","directory":"hooks","group":null,"description":"Tracks scroll overflow state for a horizontally scrollable container. Returns a ref callback and state booleans that update as the user scrolls or the container resizes. Uses scroll event listeners and ResizeObserver for reactive updates. Tolerance of 1px is applied to avoid sub-pixel false positives.","keywords":["scroll","overflow","carousel","fade","edge","horizontal","scrollable","resize"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Tracks scroll overflow state for a horizontally scrollable container. Returns a ref callback and state booleans that update as the user scrolls or the container resizes. Uses scroll event listeners and ResizeObserver for reactive updates. Tolerance of 1px is applied to avoid sub-pixel false positives.","bestPractices":[{"guidance":true,"description":"Use to show/hide scroll navigation buttons or fade edges on carousels and horizontal lists."},{"guidance":true,"description":"Apply the scrollRef to a container with overflow-x: auto or overflow-x: scroll."},{"guidance":false,"description":"Use for vertical scroll tracking — this hook only measures horizontal overflow."}]},"theming":null,"params":[],"returns":[{"name":"scrollRef","type":"React.RefCallback<HTMLElement>","description":"Ref callback to attach to the horizontally scrollable container element."},{"name":"overflowStart","type":"boolean","description":"Whether content overflows the start edge (left in LTR, right in RTL)."},{"name":"overflowEnd","type":"boolean","description":"Whether content overflows the end edge (right in LTR, left in RTL)."},{"name":"hasOverflow","type":"boolean","description":"Whether the container has any scroll overflow at all (scrollWidth > clientWidth)."}],"relatedComponents":["Carousel"],"relatedHooks":["useOverflow"],"playground":null},{"name":"useXDSCollapsible","moduleName":"useXDSCollapsible","directory":"Collapsible","group":"Collapsible","description":"Reusable hook that encapsulates the collapsible state machine. Supports three modes: group-controlled (inside XDSCollapsibleGroup), controlled (isOpen + onOpenChange), and uncontrolled (self-managed with defaultIsOpen). Used internally by XDSCard and XDSSection.","keywords":["collapsible","collapse","expand","toggle","accordion","disclosure","fold"],"hidden":false,"parentDoc":"Collapsible","props":[],"usage":{"description":"Reusable hook that encapsulates the collapsible state machine. Supports three modes: group-controlled (inside XDSCollapsibleGroup), controlled (isOpen + onOpenChange), and uncontrolled (self-managed with defaultIsOpen). Used internally by XDSCard and XDSSection.","bestPractices":[{"guidance":true,"description":"Use the hook directly when building custom collapsible components that need XDS collapsible behavior without XDSCollapsible wrapper."},{"guidance":true,"description":"For accordion behavior, wrap items in XDSCollapsibleGroup and pass unique value props."},{"guidance":false,"description":"Implement your own open/close state when useXDSCollapsible already provides it — the hook handles group coordination automatically."}]},"theming":null,"params":[{"name":"isCollapsible","type":"boolean | XDSCollapsibleConfig","description":"Enable collapsible behavior. true = self-managed (starts open). Pass config object for controlled mode or custom defaults."},{"name":"value","type":"string","description":"Unique identifier within an XDSCollapsibleGroup. When present and inside a group, state is managed by the group."}],"returns":[{"name":"isEnabled","type":"boolean","description":"Whether collapsible behavior is active."},{"name":"isOpen","type":"boolean","description":"Whether the content is currently expanded."},{"name":"toggle","type":"() => void","description":"Toggle open/closed state. Dispatches to group, controlled callback, or internal state."}],"relatedComponents":["Collapsible","Card","Section"],"relatedHooks":[],"playground":null},{"name":"useXDSHoverCard","moduleName":"useXDSHoverCard","directory":"HoverCard","group":"HoverCard","description":"Headless hook for hover-triggered floating cards. Builds on useXDSLayer with hover/focus intent detection, delay, and safe triangle hover zones. Use for rich previews on hover without building the interaction logic.","keywords":["hovercard","hover","preview","card","tooltip","popup","floating","anchor"],"hidden":false,"parentDoc":"HoverCard","props":[],"usage":{"description":"Headless hook for hover-triggered floating cards. Builds on useXDSLayer with hover/focus intent detection, delay, and safe triangle hover zones. Use for rich previews on hover without building the interaction logic.","bestPractices":[{"guidance":true,"description":"Use for rich content previews (user profiles, link previews) that benefit from hover interaction."},{"guidance":true,"description":"Prefer the XDSHoverCard component for standard cases — use the hook when you need full control over rendering."},{"guidance":false,"description":"Use for simple text hints — use XDSTooltip or useXDSTooltip instead."}]},"theming":null,"params":[{"name":"content","type":"ReactNode | ((props: ContextRenderProps) => ReactNode)","description":"Content to display in the hover card. Can be a render function receiving layer props.","required":true},{"name":"placement","type":"LayerPlacement","description":"Position relative to the trigger.","default":"'below'"},{"name":"alignment","type":"LayerAlignment","description":"Alignment along the placement axis.","default":"'center'"},{"name":"delayMs","type":"number","description":"Delay before showing the hover card on hover.","default":"300"},{"name":"onShow","type":"() => void","description":"Callback fired when the hover card becomes visible."},{"name":"onHide","type":"() => void","description":"Callback fired when the hover card is hidden."}],"returns":[{"name":"triggerProps","type":"object","description":"Props to spread on the trigger element (ref, event handlers)."},{"name":"layerNode","type":"ReactNode","description":"The hover card layer to render (include in JSX output)."}],"relatedComponents":["HoverCard","Tooltip","Popover"],"relatedHooks":["useXDSLayer","useXDSTooltip","useXDSPopover"],"playground":null},{"name":"useXDSImperativeAlertDialog","moduleName":"useXDSImperativeAlertDialog","directory":"AlertDialog","group":"Dialog","description":"Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.","keywords":["alert","alertdialog","confirm","confirmation","destructive","delete","modal","dialog","imperative"],"hidden":false,"parentDoc":"AlertDialog","props":[{"name":"show","type":"(options: AlertDialogOptions) => void","description":"Show the alert dialog with the given options. Options are the same as XDSAlertDialog props minus isOpen/onOpenChange."},{"name":"hide","type":"() => void","description":"Hide the alert dialog."},{"name":"isOpen","type":"boolean","description":"Whether the dialog is currently open."},{"name":"element","type":"ReactNode","description":"The dialog element — render this in your JSX tree."}],"usage":{"description":"AlertDialog asks the user to confirm a destructive or irreversible action before it happens. Use it for things like deleting content, revoking access, or discarding unsaved changes.\n\nFor cases where you want to show an alert without managing open state, use the `useXDSImperativeAlertDialog` hook — call `alert.show(options)` and render `alert.element` in your tree.","bestPractices":[{"guidance":true,"description":"Make the action button label specific — \"Delete project\" is better than \"OK\" or \"Confirm\"."},{"guidance":true,"description":"Describe what will happen in the description so the user knows the consequences before confirming."},{"guidance":false,"description":"Use AlertDialog for non-destructive actions — use a standard Dialog instead."}]},"theming":null,"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"isOpen":true,"isInline":true,"title":"Delete item?","description":"This action cannot be undone. The item and all its data will be permanently removed.","actionLabel":"Delete"}}},{"name":"useXDSImperativeDialog","moduleName":"useXDSImperativeDialog","directory":"Dialog","group":"Dialog","description":"Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.","keywords":["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap","imperative"],"hidden":false,"parentDoc":"Dialog","props":[{"name":"show","type":"(content: ReactNode, options?: DialogOptions) => void","description":"Show the dialog with the given content. Options are the same as XDSDialog props minus isOpen/onOpenChange/children."},{"name":"hide","type":"() => void","description":"Hide the dialog."},{"name":"isOpen","type":"boolean","description":"Whether the dialog is currently open."},{"name":"element","type":"ReactNode","description":"The dialog element — render this in your JSX tree."}],"usage":{"description":"Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.\n\nFor cases where you want to show a dialog without managing open state, use the `useXDSImperativeDialog` hook — call `dialog.show(content)` and render `dialog.element` in your tree.","bestPractices":[{"guidance":true,"description":"Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond."},{"guidance":true,"description":"Include a clear title in the header so users immediately understand what the dialog is asking."},{"guidance":true,"description":"Use purpose=\"form\" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop."},{"guidance":true,"description":"Keep dialogs focused on a single task — if the content grows beyond what fits, consider a full page instead."},{"guidance":false,"description":"Use a dialog for simple messages that could be shown inline or as a toast notification."},{"guidance":false,"description":"Nest dialogs inside other dialogs — restructure the flow into steps within a single dialog instead."},{"guidance":false,"description":"Use the fullscreen variant for simple confirmations — it is meant for complex content like editors or long forms."}],"anatomy":[{"name":"Header","required":true,"description":"Title, optional subtitle, and close button. The title receives focus on open for accessibility."},{"name":"Body","required":true,"description":"The main content area — text, forms, lists, or any layout."},{"name":"Footer","required":false,"description":"Action buttons like Save/Cancel or Accept/Decline, aligned to the end."},{"name":"Backdrop","required":true,"description":"Semi-transparent overlay behind the dialog that blocks page interaction."}]},"theming":{"container":true,"targets":[{"className":"xds-dialog","visualProps":["variant"]}],"vars":[{"name":"--_dialog-radius","description":"Border radius of the dialog","default":"var(--radius-container)","private":true}],"derived":[{"property":"borderRadius","vars":["--_dialog-radius"]},{"property":"padding","expand":"container"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"isOpen":true,"isInline":true,"width":400,"children":{"element":"XDSVStack","props":{"gap":2},"children":[{"element":"XDSHeading","props":{"level":3},"children":"Dialog Title"},{"element":"XDSText","props":{"type":"body"},"children":"Are you sure you want to proceed? This action can be undone later from settings."}]}}}},{"name":"useXDSLayer","moduleName":"useXDSLayer","directory":"Layer","group":"Utilities","description":"Layer is a core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for building popovers, hover cards, and tooltips without React portals.","keywords":["layer","overlay","popover","positioning","anchor","floating","dropdown","popper","popup","portal"],"hidden":false,"parentDoc":null,"props":[{"name":"mode","type":"'context' | 'fixed'","description":"Positioning strategy: context uses CSS anchor positioning relative to a trigger ref; fixed uses explicit x/y coordinates.","required":true},{"name":"onShow","type":"() => void","description":"Callback fired when the layer becomes visible."},{"name":"onHide","type":"() => void","description":"Callback fired when the layer is hidden."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}."}],"usage":{"description":"Layer is a core positioning hook for rendering overlay content using CSS Anchor Positioning and the Popover API. Use it as the foundation for building popovers, hover cards, and tooltips without React portals.","bestPractices":[{"guidance":true,"description":"Use context mode for anchor-positioned overlays relative to a trigger element, and fixed mode for manually positioned overlays at specific coordinates."},{"guidance":true,"description":"Build on higher-level components like Popover, HoverCard, and Tooltip instead of using Layer directly for common overlay patterns."},{"guidance":false,"description":"Implement ARIA patterns directly in a Layer — leave accessibility semantics to the higher-level components that build on it."}]},"theming":null,"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"useXDSPopover","moduleName":"useXDSPopover","directory":"Popover","group":"Popover","description":"Headless hook for click-triggered popovers with focus trapping. Combines useXDSLayer with useFocusTrap for dialog-like popover behavior. Use for interactive floating content that needs keyboard navigation.","keywords":["popover","popup","dropdown","floating","anchor","dialog","overlay","flyout"],"hidden":false,"parentDoc":"Popover","props":[],"usage":{"description":"Headless hook for click-triggered popovers with focus trapping. Combines useXDSLayer with useFocusTrap for dialog-like popover behavior. Use for interactive floating content that needs keyboard navigation.","bestPractices":[{"guidance":true,"description":"Use for interactive content (forms, menus, pickers) that needs focus trapping and light dismiss."},{"guidance":true,"description":"Prefer the XDSPopover component for standard trigger-content pairs — use the hook for custom trigger patterns."},{"guidance":false,"description":"Use for non-interactive hover previews — use useXDSHoverCard or useXDSTooltip instead."}]},"theming":null,"params":[{"name":"content","type":"ReactNode | ((props: ContextRenderProps) => ReactNode)","description":"Content to display in the popover. Can be a render function receiving layer props.","required":true},{"name":"placement","type":"LayerPlacement","description":"Position relative to the trigger.","default":"'below'"},{"name":"alignment","type":"LayerAlignment","description":"Alignment along the placement axis.","default":"'start'"},{"name":"hasLightDismiss","type":"boolean","description":"Whether clicking outside dismisses the popover.","default":"true"},{"name":"hasSurface","type":"boolean","description":"Whether to apply the default popover surface styles (background, shadow, radius).","default":"true"},{"name":"onShow","type":"() => void","description":"Callback fired when the popover becomes visible."},{"name":"onHide","type":"() => void","description":"Callback fired when the popover is hidden."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for the popover surface (margins, sizing). Must be a stylex.create() value — not an inline style object. Note: for styles that interact with :popover-open, pass xstyle via the render() call props instead."}],"returns":[{"name":"triggerProps","type":"object","description":"Props to spread on the trigger element (ref, aria-expanded, event handlers)."},{"name":"layerNode","type":"ReactNode","description":"The popover layer to render (include in JSX output)."},{"name":"isOpen","type":"boolean","description":"Whether the popover is currently visible."},{"name":"show","type":"() => void","description":"Imperatively show the popover."},{"name":"hide","type":"() => void","description":"Imperatively hide the popover."}],"relatedComponents":["Popover","DropdownMenu","HoverCard"],"relatedHooks":["useXDSLayer","useFocusTrap","useXDSHoverCard","useXDSTooltip"],"playground":null},{"name":"useXDSResizable","moduleName":"useXDSResizable","directory":"Resizable","group":"Resizable","description":"Hook for adding drag-to-resize behavior to layout regions. Supports single-region and multi-region configurations with snap points, collapsible panels, localStorage persistence, and cascade resize ordering.","keywords":["resize","resizable","drag","split","panel","sidebar","divider","splitter"],"hidden":false,"parentDoc":"Resizable","props":[],"usage":{"description":"Hook for adding drag-to-resize behavior to layout regions. Supports single-region and multi-region configurations with snap points, collapsible panels, localStorage persistence, and cascade resize ordering.","bestPractices":[{"guidance":true,"description":"Use with XDSLayout or XDSAppShell sidebar for resizable navigation panels."},{"guidance":true,"description":"Set autoSaveId to persist user-chosen sizes across page reloads."},{"guidance":false,"description":"Set minSizePx too small — content becomes unreadable. Prefer collapsible for panels that can hide entirely."}]},"theming":null,"params":[{"name":"defaultSize","type":"number | string","description":"Initial size in pixels or percentage string (e.g. \"20%\")."},{"name":"minSizePx","type":"number","description":"Minimum size in pixels.","default":"50"},{"name":"maxSizePx","type":"number","description":"Maximum size in pixels.","default":"Infinity"},{"name":"collapsible","type":"boolean","description":"Whether dragging below the collapsed threshold collapses the region to zero.","default":"false"},{"name":"snaps","type":"number[]","description":"Pixel values to snap to during drag."},{"name":"autoSaveId","type":"string","description":"Key for localStorage persistence of size across sessions."}],"returns":[{"name":"size","type":"number","description":"Current size in pixels."},{"name":"isCollapsed","type":"boolean","description":"Whether the region is currently collapsed."},{"name":"collapse","type":"() => void","description":"Programmatically collapse the region."},{"name":"expand","type":"() => void","description":"Expand from collapsed state."},{"name":"resize","type":"(size: number) => void","description":"Resize to a specific pixel value."},{"name":"props","type":"ResizableProps","description":"Props to spread on the resizable component or pass to XDSResizeHandle."}],"relatedComponents":["Resizable","AppShell","Layout","SideNav"],"relatedHooks":["useXDSCollapsible"],"playground":null},{"name":"useXDSStreamingText","moduleName":"useXDSStreamingText","directory":"hooks","group":null,"description":"Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from XDS motion tokens via useXDSTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.","keywords":["streaming","text","typewriter","animation","ai","chat","markdown","reveal","llm","chunked"],"hidden":false,"parentDoc":null,"props":[],"usage":{"description":"Smooths bursty streamed text into a steady character-by-character reveal using requestAnimationFrame. Decouples arrival rate from display rate. Advances on word and syntax boundaries to avoid slicing mid-markdown or mid-word, preventing visual glitches with markdown renderers. Animation timing derives from XDS motion tokens via useXDSTheme when available, with sensible fallbacks outside a theme provider. Snaps to full text when isStreaming becomes false.","bestPractices":[{"guidance":true,"description":"Pass the accumulated text (not individual chunks) as targetText — the hook handles incremental reveal internally."},{"guidance":true,"description":"Set isStreaming to false when the stream completes to snap to the final text."},{"guidance":true,"description":"Use speed='instant' for non-animated contexts like search results or when reduced motion is preferred."},{"guidance":false,"description":"Use for static text that does not change — the hook adds unnecessary overhead for non-streaming content."}]},"theming":null,"params":[{"name":"targetText","type":"string","description":"The full target text to reveal. As new chunks arrive, update this value with the accumulated text.","required":true},{"name":"isStreaming","type":"boolean","description":"Whether text is currently being streamed. When false, the hook returns the full targetText immediately.","required":true},{"name":"options","type":"UseStreamingTextOptions","description":"Optional configuration for streaming behavior.","required":false},{"name":"options.speed","type":"'natural' | 'fast' | 'instant'","description":"Speed preset for text reveal. 'natural' is steady ~2 chars/frame, 'fast' scales with backlog ~4 chars/frame, 'instant' returns full text with no animation.","default":"'natural'","required":false}],"returns":[{"name":"displayedText","type":"string","description":"The portion of targetText to render. Grows steadily toward the full targetText during streaming, or equals targetText when not streaming."}],"relatedComponents":["Markdown"],"relatedHooks":[],"playground":null},{"name":"useXDSTableColumnSettings","moduleName":"useXDSTableColumnSettings","directory":"Table","group":"Table","description":"Headless column visibility and ordering management for XDSTable. Provides filtered columns, toggle helpers, and pre-built XDSMultiSelector options for a column picker UI.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"columns","type":"XDSColumnSettingsOption[]","description":"All available columns with metadata for the settings UI. Each entry has key, label, optional isAlwaysVisible and group.","required":true},{"name":"activeColumnKeys","type":"string[]","description":"Currently active column keys, in display order. Only columns with keys in this array are shown.","required":true},{"name":"onChangeActiveColumnKeys","type":"(keys: string[]) => void","description":"Called when active columns change (toggle, reorder).","required":true},{"name":"defaultColumnKeys","type":"string[]","description":"Default column set for \"Reset to default\". When omitted, reset shows all columns."}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"useXDSTablePagination","moduleName":"useXDSTablePagination","directory":"Table","group":"Table","description":"Headless pagination plugin for XDSTable. Supports client-side slicing, server-side pagination, and cursor-based pagination. Renders XDSPagination controls automatically above, below, or both.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"page","type":"number","description":"Current page number (1-based).","required":true},{"name":"onPageChange","type":"(page: number) => void","description":"Called when the page changes.","required":true},{"name":"totalItems","type":"number","description":"Total number of items across all pages. Used to calculate total page count."},{"name":"totalPages","type":"number","description":"Total number of pages. Use when you know the page count but not item count."},{"name":"hasMore","type":"boolean","description":"Whether more pages exist. Use for cursor-based pagination where the total is unknown."},{"name":"pageSize","type":"number","description":"Number of items per page.","default":"10"},{"name":"onPageSizeChange","type":"(pageSize: number) => void","description":"Called when the user changes the page size. Shows a page size dropdown when provided with pageSizeOptions."},{"name":"pageSizeOptions","type":"number[]","description":"Available page size options. Shows a page size selector when provided."},{"name":"variant","type":"'pages' | 'count' | 'compact' | 'dots' | 'none'","description":"Visual variant for the pagination controls.","default":"'pages'"},{"name":"position","type":"'below' | 'above' | 'both' | 'none'","description":"Where to render pagination controls relative to the table.","default":"'below'"},{"name":"align","type":"'start' | 'center' | 'end'","description":"Horizontal alignment of the pagination controls.","default":"'center'"}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"useXDSTableSelection","moduleName":"useXDSTableSelection","directory":"Table","group":"Table","description":"Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"getIsItemSelected","type":"(item: T) => boolean","description":"Returns whether the given item is currently selected.","required":true},{"name":"onSelectItem","type":"(event: {item: T; isSelected: boolean}) => void","description":"Called when a row checkbox is toggled. isSelected is the new desired state.","required":true},{"name":"onSelectAll","type":"(event: {isAllSelected: boolean}) => void","description":"Called when the select-all header checkbox is toggled.","required":true},{"name":"getIsAllSelected","type":"() => boolean","description":"Returns whether all selectable items are currently selected.","required":true},{"name":"getIsIndeterminate","type":"() => boolean","description":"Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state."},{"name":"getIsItemSelectable","type":"(item: T) => boolean","description":"Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.","default":"() => true"},{"name":"getIsItemEnabled","type":"(item: T) => boolean","description":"Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.","default":"() => true"}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"useXDSTableSelectionState","moduleName":"useXDSTableSelectionState","directory":"Table","group":"Table","description":"State management companion for useXDSTableSelection. Handles disabled/selectable row filtering for select-all automatically — disabled rows are frozen (preserved across select-all/deselect-all), non-selectable rows are excluded.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"data","type":"T[]","description":"The full data array rendered in the table.","required":true},{"name":"idKey","type":"(keyof T & string) | ((item: T) => string)","description":"Key extractor — property name or function returning a unique string ID.","required":true},{"name":"selectedKeys","type":"Set<string>","description":"Controlled set of selected item IDs.","required":true},{"name":"setSelectedKeys","type":"Dispatch<SetStateAction<Set<string>>>","description":"Setter for the controlled selected keys.","required":true},{"name":"getIsItemSelectable","type":"(item: T) => boolean","description":"Should this row show a checkbox? Non-selectable rows are excluded from select-all.","default":"() => true"},{"name":"getIsItemEnabled","type":"(item: T) => boolean","description":"Is this row checkbox interactive? Disabled rows are frozen — select-all preserves their state.","default":"() => true"}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"useXDSTableSortable","moduleName":"useXDSTableSortable","directory":"Table","group":"Table","description":"Headless multi-sort plugin for XDSTable. The consumer owns sort state and provides a callback. Shift+click enables secondary sort columns. Sort indicators render in header cells automatically.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"sort","type":"XDSTableSortState<TSortKey>","description":"Current sort state. Ordered array of {sortKey, direction} entries. First entry is the primary sort.","required":true},{"name":"onSortChange","type":"(sort: XDSTableSortState<TSortKey>) => void","description":"Called when the user clicks a header cell to change sort.","required":true},{"name":"allowUnsortedState","type":"boolean","description":"Allow cycling back to unsorted. When true: asc, desc, unsorted. When false: asc, desc, asc.","default":"false"},{"name":"isMultiSortEnabled","type":"boolean","description":"Enable multi-sort via Shift+click. Regular click still replaces the entire sort state.","default":"false"}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"useXDSToast","moduleName":"useXDSToast","directory":"Toast","group":"Toast","description":"Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with XDSLayerProvider or self-mounts a fallback viewport.","keywords":["toast","notification","snackbar","alert","message","feedback","flash"],"hidden":false,"parentDoc":"Toast","props":[],"usage":{"description":"Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with XDSLayerProvider or self-mounts a fallback viewport.","bestPractices":[{"guidance":true,"description":"Use for transient success/error feedback that does not require user action."},{"guidance":true,"description":"Set uniqueID to deduplicate toasts from rapid user actions."},{"guidance":false,"description":"Use for critical errors that require acknowledgment — use AlertDialog instead."},{"guidance":false,"description":"Call useXDSToast in the same component that renders XDSLayerProvider — it must be called from a child component inside the provider."}]},"theming":null,"params":[],"returns":[{"name":"showToast","type":"(options: XDSToastOptions) => () => void","description":"Show a toast notification. Returns a dismiss function. Options include body (ReactNode), type (\"info\" | \"error\"), isAutoHide, autoHideDuration, endContent, uniqueID, and collisionBehavior."}],"relatedComponents":["Toast","Banner","AlertDialog"],"relatedHooks":[],"playground":null},{"name":"useXDSTooltip","moduleName":"useXDSTooltip","directory":"Tooltip","group":"Tooltip","description":"Headless hook for hover/focus-triggered tooltips. Builds on useXDSLayer with hover intent, delay, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior.","keywords":["tooltip","hint","label","hover","info","title","floating"],"hidden":false,"parentDoc":"Tooltip","props":[],"usage":{"description":"Headless hook for hover/focus-triggered tooltips. Builds on useXDSLayer with hover intent, delay, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior.","bestPractices":[{"guidance":true,"description":"Use for brief text labels that describe a UI element — icon buttons, truncated text, abbreviations."},{"guidance":true,"description":"Prefer the XDSTooltip component for standard wrapping — use the hook when the trigger is not a simple child."},{"guidance":false,"description":"Put interactive content (links, buttons) inside tooltips — use Popover or HoverCard instead."}]},"theming":null,"params":[{"name":"content","type":"ReactNode","description":"Text or content to display in the tooltip.","required":true},{"name":"placement","type":"LayerPlacement","description":"Position relative to the trigger.","default":"'above'"},{"name":"alignment","type":"LayerAlignment","description":"Alignment along the placement axis.","default":"'center'"},{"name":"delayMs","type":"number","description":"Delay before showing the tooltip on hover.","default":"300"}],"returns":[{"name":"triggerProps","type":"object","description":"Props to spread on the trigger element (ref, aria-describedby, event handlers)."},{"name":"layerNode","type":"ReactNode","description":"The tooltip layer to render (include in JSX output)."}],"relatedComponents":["Tooltip","HoverCard","Popover"],"relatedHooks":["useXDSLayer","useXDSHoverCard","useXDSPopover"],"playground":null},{"name":"VStack","moduleName":"XDSVStack","directory":"Layout","group":"Layout","description":"Vertical stack that arranges children top-to-bottom.","keywords":["layout","container","content","flex","box","wrapper","scaffold","page","shell"],"hidden":false,"parentDoc":"Layout","props":[],"usage":{"description":"Layout provides composable components for building structured page shells with header, sidebar, content, and footer slots. Use XDSLayout for full app layouts and XDSHStack/XDSVStack for simple directional stacking.","bestPractices":[{"guidance":true,"description":"Use XDSLayout for page shells that need distinct zones like header, sidebar(s), content, and footer."},{"guidance":true,"description":"Use XDSHStack and XDSVStack for simple directional stacking within a content area."},{"guidance":false,"description":"Use XDSLayout for simple stacking layouts — use XDSHStack or XDSVStack instead."},{"guidance":false,"description":"Nest multiple XDSLayout components — use one per page shell and compose content within its slots."}]},"theming":{"targets":[{"className":"xds-layout","visualProps":["height"]},{"className":"xds-layout-content"},{"className":"xds-layout-footer"},{"className":"xds-layout-header"},{"className":"xds-layout-panel"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"header":{"element":"XDSLayoutHeader","props":{},"children":{"element":"XDSHeading","props":{"level":3},"children":"Page Title"}},"content":{"element":"XDSLayoutContent","props":{},"children":{"element":"XDSText","props":{"type":"body","color":"secondary"},"children":"Main content area. This is the scrollable center section of the layout."}},"footer":{"element":"XDSLayoutFooter","props":{},"children":{"__element":"XDSText","props":{"type":"supporting","color":"secondary"},"children":"Footer — status bar or actions"}}}}}]},"packages":[{"name":"@xds/cli","displayName":"CLI","version":"0.0.13","description":"Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.","packagePath":"packages/cli","hasReadme":true,"hasChangelog":true,"readme":"$12","changelog":"$13"},{"name":"@xds/core","displayName":"XDS Core","version":"0.0.13","description":"The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.","packagePath":"packages/core","hasReadme":true,"hasChangelog":true,"readme":"$14","changelog":"$15"},{"name":"@xds/theme-chocolate","displayName":"Chocolate Theme","version":"0.0.13","description":"Warm chocolate theme for XDS — rich brown palette with Fraunces headings, Albert Sans body, and Lucide icons","packagePath":"packages/themes/chocolate","hasReadme":true,"hasChangelog":false,"readme":"$16","changelog":null},{"name":"@xds/theme-daily","displayName":"Theme: daily","version":"0.0.13","description":"Daily theme for XDS — warm, productivity-focused palette with Lucide icon set","packagePath":"packages/themes/daily","hasReadme":true,"hasChangelog":true,"readme":"$17","changelog":"# @xds/theme-daily\n\n# 0.0.13\n\n#### Changes\n\n- Fleshed out with complete token set and component overrides (#1802)\n\n#### Patch Changes\n\n- Updated dependencies\n - @xds/core@0.0.13\n"},{"name":"@xds/theme-default","displayName":"Default Theme","version":"0.0.13","description":"Clean neutrals with a blue accent. Pairs with Heroicons for a polished, professional look.","packagePath":"packages/themes/default","hasReadme":true,"hasChangelog":true,"readme":"$18","changelog":"# @xds/theme-default\n\n# 0.0.13\n\n#### Changes\n\n- Icon renames: `checkCircle`/`xCircle` → `success`/`error` (#1503)\n\n#### Patch Changes\n\n- Updated dependencies\n - @xds/core@0.0.13\n\n---\n\n# 0.0.5\n\n#### Changes\n\n- Updated token names to match naming audit (shadow, radius, elevation renames)\n- Motion token primitives: duration and easing values\n- Dynamic radius and type scale support via `defineTheme` config\n\n#### Patch Changes\n\n- Updated dependencies\n - @xds/core@0.0.5\n\n---\n\n# 0.0.4\n\n#### Patch Changes\n\n- Updated dependencies — aligned with @xds/core@0.0.4\n\n---\n\n# 0.0.3\n\n#### Patch Changes\n\n- Fix theme package to produce proper JS/TS module output via tsup (#541)\n\n---\n\n# 0.0.2\n\n#### Changes\n\n- Migrated to CSS-based theming with `defineTheme()`\n\n---\n\n# 0.0.1\n\n- Initial release — default theme with Heroicons\n"},{"name":"@xds/theme-gothic","displayName":"Gothic Theme","version":"0.0.13","description":"Dark gothic theme for XDS — deep blue-gray palette with Manufacturing Consent headings, Fustat body, and Lucide icons","packagePath":"packages/themes/gothic","hasReadme":true,"hasChangelog":false,"readme":"$19","changelog":null},{"name":"@xds/theme-matcha","displayName":"Theme: matcha","version":"0.0.13","description":"Matcha theme for XDS — earthy green palette with Figtree typography and Lucide icons","packagePath":"packages/themes/matcha","hasReadme":true,"hasChangelog":true,"readme":"$1a","changelog":"# @xds/theme-matcha\n\n# 0.0.13\n\n#### New\n\n- Initial release — earthy green palette with Figtree typography (#1803)\n"},{"name":"@xds/theme-neutral","displayName":"Neutral Theme","version":"0.0.13","description":"Understated warm grays with a subtle palette. Pairs with Lucide icons for a minimal, quiet aesthetic.","packagePath":"packages/themes/neutral","hasReadme":true,"hasChangelog":true,"readme":"$1b","changelog":"# @xds/theme-neutral\n\n# 0.0.13\n\n#### Changes\n\n- Icon renames: `checkCircle`/`xCircle` → `success`/`error` (#1503)\n\n#### Patch Changes\n\n- Updated dependencies\n - @xds/core@0.0.13\n\n---\n\n# 0.0.5\n\n#### Changes\n\n- Updated token names to match naming audit (shadow, radius, elevation renames)\n- Motion token primitives: duration and easing values\n- Dynamic radius and type scale support via `defineTheme` config\n\n#### Patch Changes\n\n- Updated dependencies\n - @xds/core@0.0.5\n\n---\n\n# 0.0.4\n\n#### Patch Changes\n\n- Updated dependencies — aligned with @xds/core@0.0.4\n\n---\n\n# 0.0.3\n\n#### Patch Changes\n\n- Fix theme package to produce proper JS/TS module output via tsup (#541)\n\n---\n\n# 0.0.2\n\n#### Changes\n\n- Migrated to CSS-based theming with `defineTheme()`\n\n---\n\n# 0.0.1\n\n- Initial release — neutral theme with Lucide icons\n"},{"name":"@xds/theme-stone","displayName":"Stone Theme","version":"0.0.13","description":"Warm stone and slate theme for XDS — earthy neutral palette with Montserrat headings, Figtree body, and Lucide icons","packagePath":"packages/themes/stone","hasReadme":true,"hasChangelog":false,"readme":"$1c","changelog":null}],"docTopics":[{"topic":"color","title":"Color","description":"Semantic color tokens for surfaces, text, icons, borders, and status indicators.","category":"foundations","sections":[{"title":"Overview","category":"foundations","content":[{"type":"prose","text":"XDS colors are semantic — tokens describe purpose, not appearance. Every color adapts automatically between light and dark modes via CSS light-dark(). Themes override the resolved values, so your code never references raw hex colors."}]},{"title":"Surface Colors","category":"foundations","content":[{"type":"prose","text":"Layered surface hierarchy: body → surface → card → popover. Each level sits visually above the previous one."},{"type":"token-ref","topic":"tokens","section":"Color Tokens"}]},{"title":"Usage","category":"foundations","content":[{"type":"code","lang":"tsx","label":"Applying color tokens","code":"import as stylex from '@stylexjs/stylex';\nimport {colorVars} from '@xds/core/theme/tokens.stylex';\n\nconst styles = stylex.create({\n container: {\n backgroundColor: colorVars['--color-background-surface'],\n color: colorVars['--color-text-primary'],\n borderColor: colorVars['--color-border'],\n },\n accent: {\n color: colorVars['--color-text-accent'],\n },\n});"}]},{"title":"Best Practices","category":"foundations","content":[{"type":"list","style":"do","items":["Use semantic tokens (--color-text-primary) instead of raw hex values.","Rely on the surface hierarchy (body → surface → card → popover) for layering.","Use status colors (success, error, warning) only for their semantic meaning."]},{"type":"list","style":"dont","items":["Hardcode hex values — they won't adapt to dark mode or custom themes.","Mix accent colors with status colors in the same context.","Use --color-on-accent on non-accent backgrounds."]}]}]},{"topic":"elevation","title":"Elevation","description":"Shadow tokens for visual elevation and inset state rings.","category":"foundations","sections":[{"title":"Overview","category":"foundations","content":[{"type":"prose","text":"Elevation tokens create depth through box-shadow. Three levels (low, med, high) establish a visual hierarchy for floating elements. Inset shadows provide focus and selection rings for interactive components."}]},{"title":"Elevation Scale","category":"foundations","content":[{"type":"prose","text":"Each level adds stronger offset and spread. Shadow color adapts to dark mode automatically via light-dark()."},{"type":"token-ref","topic":"tokens","section":"Shadow Tokens"}]},{"title":"Usage","category":"foundations","content":[{"type":"code","lang":"tsx","label":"Applying elevation","code":"import {shadowVars} from '@xds/core';\n\nconst styles = stylex.create({\n dropdown: {\n boxShadow: shadowVars['--shadow-med'],\n },\n dialog: {\n boxShadow: shadowVars['--shadow-high'],\n },\n inputFocused: {\n boxShadow: shadowVars['--shadow-inset-selected'],\n },\n});"}]},{"title":"Best Practices","category":"foundations","content":[{"type":"list","style":"do","items":["Match elevation to interaction context: low for tooltips, med for dropdowns, high for dialogs.","Use inset shadows for input focus/selection states — they compose better than outlines."]},{"type":"list","style":"dont","items":["Stack multiple elevation levels on the same element.","Use elevation shadows for decorative borders — use --color-border tokens instead."]}]}]},{"topic":"getting-started","title":"Getting Started","description":"Add XDS to your project and start building.","category":"guide","sections":[{"title":"Quick Start with AI","content":[{"type":"prose","text":"Paste this into your AI coding tool and let it handle the setup:"},{"type":"code","lang":"text","label":"Paste this into your AI","code":"Install @xds/core, @xds/theme-default, and @xds/cli in this project. Run `npx xds init` to set up agent docs. Read the generated files to learn the conventions."}]},{"title":"Install","content":[{"type":"prose","text":"Add the core package, a theme, and the CLI to your existing project."},{"type":"code","lang":"bash","label":"Terminal","code":"npm install @xds/core @xds/theme-default @xds/cli"},{"type":"prose","text":"Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming."},{"type":"code","lang":"bash","label":"Terminal","code":"npx xds init"}]},{"title":"Add the theme CSS","content":[{"type":"prose","text":"Import the reset stylesheet and a theme in your global CSS file. Themes provide all design tokens (colors, spacing, radius, typography) as CSS custom properties."},{"type":"code","lang":"css","label":"globals.css","code":"@import '@xds/core/reset.css';\n@import '@xds/core/xds.css';\n@import '@xds/theme-default/theme.css';"},{"type":"prose","text":"Available themes: @xds/theme-default (blue accent), @xds/theme-neutral (grayscale), @xds/theme-brutalist (zero radius, monospace). See `npx xds docs theme` for the full theming guide."}]},{"title":"Add your first component","content":[{"type":"prose","text":"XDS components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear."},{"type":"code","lang":"tsx","label":"app/page.tsx","code":"import {XDSButton} from '@xds/core/Button';\nimport {XDSVStack} from '@xds/core/Layout';\n\nexport default function Page() {\n return (\n <XDSVStack gap={2}>\n <XDSButton label=\"Hello XDS\" onClick={() => alert('Hi!')} />\n </XDSVStack>\n );\n}"}]},{"title":"Customize with xstyle","content":[{"type":"prose","text":"Every XDS component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`."},{"type":"code","lang":"tsx","label":"Style overrides","code":"import * as stylex from '@stylexjs/stylex';\n\nconst overrides = stylex.create({\n save: { alignSelf: 'flex-end', marginTop: 16 },\n});\n\n<XDSButton label=\"Save\" xstyle={overrides.save} />"}]},{"title":"Example Apps","content":[{"type":"prose","text":"For a full working project, clone one of the example apps from the XDS repo. These are complete setups with routing, theming, and components wired together."},{"type":"table","headers":["Example","Stack","Path"],"rows":[["Next.js","Next.js + XDS theme CSS","apps/example-nextjs"],["Next.js + StyleX","Next.js + StyleX for custom styles","apps/example-nextjs-stylex"],["Next.js + Tailwind","Next.js + Tailwind bridge","apps/example-nextjs-tailwind"],["Next.js Source","Next.js importing XDS from source","apps/example-nextjs-source"],["Vite","Vite + XDS","apps/example-vite"]]},{"type":"code","lang":"bash","label":"Clone and run an example","code":"git clone https://github.com/facebookexperimental/xds.git\ncd xds/apps/example-nextjs\nyarn install\nyarn dev"}]},{"title":"Explore the CLI","content":[{"type":"prose","text":"The CLI is your reference for components, tokens, templates, and docs. Use it to discover what’s available."},{"type":"code","lang":"bash","label":"Terminal","code":"npx xds component # list all components\nnpx xds component Button # props, usage, theming for Button\nnpx xds docs # list all doc topics\nnpx xds template --list # available page templates\nnpx xds docs tokens # spacing, color, radius reference"}]}]},{"topic":"icons","title":"Icons","description":"Semantic icon names available in XDS. These adapt to the active theme's icon registry.","category":"foundations","sections":[{"title":"Available Names","category":"foundations","content":[{"type":"prose","text":"Components that accept an icon prop use XDSIconType — either a semantic name string or a direct SVG component. The semantic names below are resolved through the global icon registry."},{"type":"table","headers":["Name","Usage"],"rows":[["close","Dismiss, close dialogs/panels"],["chevronDown","Dropdown triggers, expand/collapse"],["chevronLeft","Navigate back, previous"],["chevronRight","Navigate forward, next"],["check","Checkbox checked, confirm"],["success","Success status indicator"],["error","Error status indicator"],["warning","Warning status indicator"],["info","Info status indicator, tooltips"],["calendar","Date pickers, scheduling"],["clock","Time pickers, timestamps"],["externalLink","Links opening in new tab"],["menu","Hamburger menu, navigation toggle"],["moreHorizontal","Overflow menu, additional actions"],["search","Search inputs, find"],["arrowUp","Sort ascending, move up"],["arrowDown","Sort descending, move down"],["arrowsUpDown","Sortable column indicator"],["funnel","Filter controls"],["eyeSlash","Hidden/visibility toggle"],["viewColumns","Column visibility settings"],["copy","Copy to clipboard"],["checkDouble","Copied confirmation"],["wrench","Settings, configuration"],["stop","Stop/cancel action"],["microphone","Voice input, audio recording"]]}]},{"title":"Custom Icons","category":"foundations","content":[{"type":"prose","text":"For icons not in the semantic list, pass an SVG component directly. Any ComponentType<SVGProps<SVGSVGElement>> works — XDSIcon applies size and color styling automatically."},{"type":"code","lang":"tsx","label":"Using custom SVG components","code":"import { PhotoIcon } from '@heroicons/react/24/outline';\nimport { HeartIcon } from 'lucide-react';\n\n<XDSIcon icon={PhotoIcon} size=\"lg\" />\n<XDSIcon icon={HeartIcon} color=\"negative\" />"}]},{"title":"Theme Overrides","category":"foundations","content":[{"type":"prose","text":"Themes can replace the default SVGs for any semantic name using registerIcons(). This lets you swap the entire icon set (e.g. heroicons → lucide) without touching component code."},{"type":"code","lang":"tsx","label":"Registering theme icons","code":"import { registerIcons } from '@xds/core/Icon';\nimport { XMarkIcon, ChevronDownIcon } from '@heroicons/react/24/outline';\n\nregisterIcons({\n close: <XMarkIcon />,\n chevronDown: <ChevronDownIcon />,\n // ... override as many as needed\n});"}]},{"title":"Adding New Icons","category":"foundations","content":[{"type":"prose","text":"To add a new semantic icon name to XDS:"},{"type":"list","style":"ordered","items":["Add the name to XDSIconName type in packages/core/src/Icon/globalIconRegistry.tsx","Add the default SVG to packages/core/src/Icon/defaultIcons.tsx","Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs"]}]}]},{"topic":"illustrations","title":"Illustrations","description":"Illustration guidelines for empty states, onboarding flows, and feature highlights.","category":"foundations","sections":[{"title":"When to Use","category":"foundations","content":[{"type":"prose","text":"Consistent illustration usage reinforces brand identity and helps users understand context at a glance. Use illustrations in these contexts:"},{"type":"table","headers":["Context","Examples"],"rows":[["Empty states","No data, first-time experience, search with no results"],["Onboarding","Welcome screens, feature introduction, setup wizards"],["Feature highlights","New feature announcements, upgrade prompts"],["Error states","Permission denied, not found, service unavailable"]]}]},{"title":"Guidelines","category":"foundations","content":[{"type":"list","style":"do","items":["Keep illustrations consistent in style across the product.","Use simple, flat illustrations that work in both light and dark mode.","Size illustrations proportionally to the container — typically 120–240px.","Center illustrations with supporting text below."]},{"type":"list","style":"dont","items":["Mix illustration styles from different sources.","Use illustrations as decoration without purpose."]}]},{"title":"Placement","category":"foundations","content":[{"type":"prose","text":"Center illustrations inside XDSCenter with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next."},{"type":"code","lang":"tsx","label":"Empty state with illustration","code":"<XDSCenter>\n <XDSStack direction=\"vertical\" gap={3} hAlign=\"center\">\n <img\n src=\"/illustrations/empty-search.svg\"\n alt=\"No results\"\n style={{ width: 200, height: 200 }}\n />\n <XDSHeading level={3}>No results found</XDSHeading>\n <XDSText type=\"body\" color=\"secondary\">\n Try adjusting your search or filters to find what you’re\n looking for.\n </XDSText>\n </XDSStack>\n</XDSCenter>"}]}]},{"topic":"motion","title":"Motion","description":"Duration and easing tokens for animations and transitions.","category":"foundations","sections":[{"title":"Overview","category":"foundations","content":[{"type":"prose","text":"Motion serves two purposes: it makes interfaces easier to understand, and it makes them more pleasant to use. A panel animating open helps the eye track what changed and where new content sits in the layout. These moments reduce cognitive load and make the interface feel responsive."},{"type":"prose","text":"At the same time, well-tuned motion gives an application a sense of craft and polish that users notice, even if they can't name it."},{"type":"prose","text":"XDS provides duration and easing tokens that keep these moments consistent across your application."}]},{"title":"Duration","category":"foundations","content":[{"type":"token-ref","topic":"tokens","section":"Duration Tokens"}]},{"title":"Easing","category":"foundations","content":[{"type":"token-ref","topic":"tokens","section":"Easing Tokens"}]},{"title":"Where Motion Helps","category":"foundations","content":[{"type":"prose","text":"Some parts of the interface benefit from animation. Panels, dialogs, and collapsible sections are disorienting when they appear instantly — animation gives the eye something to follow. Toasts and notifications need just enough entrance to be noticed without startling. State changes like a switch flipping or a selection highlighting feel more intentional with a brief transition."},{"type":"prose","text":"The common thread is that these are moments where the user needs to understand what happened."}]},{"title":"Where Motion Hurts","category":"foundations","content":[{"type":"prose","text":"Table row hovers. List item highlights. Anything the user does dozens of times per minute. Adding perceptible duration to these interactions makes the interface feel like it’s catching up to the cursor. Keep these fast enough that the user never notices a delay."},{"type":"prose","text":"Animations that block interaction are worse. If a user has to wait for a panel to finish sliding before they can click something inside it, the animation has become an obstacle. Motion should never stand between the user and their next action."}]},{"title":"Movement Principles","category":"foundations","content":[{"type":"list","style":"unordered","items":["Not everything needs an animated exit. Elements the user is moving away from — tooltips, hover cards, dropdown menus — can disappear instantly. The user has already shifted their attention. Animate the exit only when it helps orient the user, like a panel closing or a dialog dismissing to reveal what’s underneath.","When you do animate exit, match the entrance. A panel that slides in from the right should slide back out to the right.","Direction should match the action. Navigating deeper into content should feel like moving forward. Going back should feel like returning. This keeps the user oriented in the structure of the application.","Contextual UI should feel connected to its trigger. A dropdown should expand from the button that opened it. A popover should appear near the element it describes. This doesn’t apply to global UI like command palettes or toasts, which have their own fixed positions."]}]},{"title":"Respecting User Preferences","category":"foundations","content":[{"type":"prose","text":"Some users experience motion sensitivity — animation that feels polished to one person can cause discomfort for another. XDS components should honor the operating system’s reduced motion setting. When it’s enabled, replace animations with instant state changes."}]},{"title":"Usage","category":"foundations","content":[{"type":"code","lang":"tsx","label":"Applying motion tokens","code":"import {durationVars, easeVars} from '@xds/core';\n\nconst styles = stylex.create({\n fadeIn: {\n transitionProperty: 'opacity',\n transitionDuration: durationVars['--duration-fast'],\n transitionTimingFunction: easeVars['--ease-standard'],\n },\n slideUp: {\n transitionProperty: 'transform, opacity',\n transitionDuration: durationVars['--duration-medium'],\n transitionTimingFunction: easeVars['--ease-standard'],\n },\n});"}]},{"title":"Best Practices","category":"foundations","content":[{"type":"list","style":"do","items":["Animate transitions that involve spatial change — panels opening, content expanding, elements entering the screen.","Use fast tokens for small, frequent interactions. Use medium tokens for larger transitions that rearrange the layout.","Honor reduced motion preferences at the OS level."]},{"type":"list","style":"dont","items":["Let hover states or high-frequency interactions feel like they’re lagging behind the user.","Let animation delay when a user can interact with new content. The transition should complete before — or not block — the next action.","Move elements in ways that contradict where they came from or where they’re going."]}]}]},{"topic":"principles","title":"Principles","description":"Core design principles and rules for building with XDS.","category":"guide","sections":[{"title":"Design Philosophy","category":"guide","content":[{"type":"prose","text":"XDS is a design system that prioritizes consistency, adaptability, and developer experience. Every decision flows from a few core ideas:"},{"type":"list","style":"unordered","items":["Components over primitives — use XDS components for everything they cover before reaching for raw HTML","Semantic tokens over hardcoded values — colors, spacing, and radii are named by purpose, not appearance","Theme-agnostic code — your app code never references specific colors or measurements, so themes and dark mode work automatically","Open internals — every primitive is exported and composable, so you can build on top of XDS without fighting it"]}]},{"title":"Rules","category":"guide","content":[{"type":"list","style":"ordered","items":["Use XDS components for everything they cover","StyleX or Tailwind for custom styling — both are first-class (see `npx xds docs styling`)","Semantic tokens, not hardcoded values (see `npx xds docs tokens`)","CSS custom properties for colors, not hex values","Form inputs are controlled (value + onChange)","Use useXDSLinkComponent() for navigation so consumers can plug in their framework router via XDSLinkProvider"]}]},{"title":"Styling Approach","category":"guide","content":[{"type":"prose","text":"XDS supports multiple styling approaches. Every component accepts an `xstyle` prop for StyleX style overrides via `stylex.create()`. For layout and wrapper styling outside of components, use StyleX or Tailwind utilities — both resolve to the same XDS design tokens."},{"type":"prose","text":"See `npx xds docs styling` for the complete guide with examples."}]},{"title":"Anti-Patterns","category":"guide","content":[{"type":"list","style":"dont","items":["Inline styles on raw elements. Use xstyle on XDS components","Hardcoded colors (#fff). Use var(--color-) or Tailwind semantic classes (text-primary, bg-surface)","Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities","Hardcoded <a> elements. Use useXDSLinkComponent() so consumers can swap in their framework router via XDSLinkProvider","Inventing props. Read component docs first"]}]},{"title":"Design Tokens","category":"guide","content":[{"type":"prose","text":"XDS provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run `npx xds docs tokens` for the full reference with all values."}]}]},{"topic":"shape","title":"Shape","description":"Border radius tokens for consistent component rounding — from sharp corners to full pills.","category":"foundations","sections":[{"title":"Overview","category":"foundations","content":[{"type":"prose","text":"The radius scale uses a semantic naming system: inner → element → container → page. Each level is designed for a specific context. Themes can multiply the entire scale via a radius multiplier, with --radius-none and --radius-full as fixed anchors."}]},{"title":"Radius Scale","category":"foundations","content":[{"type":"token-ref","topic":"tokens","section":"Radius Tokens"}]},{"title":"Concentric Radius","category":"foundations","content":[{"type":"prose","text":"When a rounded container has padding, inner elements need a smaller radius to appear concentric. XDS components like Card handle this automatically — the inner radius is computed as max(0, outerRadius - padding)."},{"type":"code","lang":"css","label":"Concentric radius formula","code":"/ Automatic in XDS Card /\n--card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));"}]},{"title":"Best Practices","category":"foundations","content":[{"type":"list","style":"do","items":["Use --radius-element for interactive controls (buttons, inputs, selectors).","Use --radius-container for content containers (cards, panels, dialogs).","Use --radius-full for pill shapes (badges, tags, avatar status dots)."]},{"type":"list","style":"dont","items":["Use --radius-page for small elements — it's designed for page-level containers.","Hardcode radius values — they won't scale with theme radius multipliers."]}]}]},{"topic":"spacing","title":"Spacing","description":"Spacing scale tokens for padding, gap, and margin — the rhythmic foundation of XDS layouts.","category":"foundations","sections":[{"title":"Overview","category":"foundations","content":[{"type":"prose","text":"XDS uses a 4px base-unit spacing scale. Component gap props accept step values that map to these tokens. The scale provides fine-grained control at the small end (2px, 4px, 6px) and consistent rhythm at larger sizes (multiples of 4px)."}]},{"title":"Scale","category":"foundations","content":[{"type":"token-ref","topic":"tokens","section":"Spacing Tokens"}]},{"title":"Usage","category":"foundations","content":[{"type":"prose","text":"Most components accept a `gap` prop using step values (0 through 12). For custom layouts, use the spacing tokens directly in StyleX."},{"type":"code","lang":"tsx","label":"Spacing via component props vs StyleX","code":"// Via component props (preferred)\n<XDSStack gap={4}>{/ 16px gap /}</XDSStack>\n\n// Via StyleX tokens (custom layouts)\nimport {spacingVars} from '@xds/core';\n\nconst styles = stylex.create({\n custom: {\n padding: spacingVars['--spacing-4'],\n gap: spacingVars['--spacing-3'],\n },\n});"}]},{"title":"Best Practices","category":"foundations","content":[{"type":"list","style":"do","items":["Use component gap props when available — they handle automatic spacing compensation.","Stick to the scale for consistency. If a value isn't on the scale, reconsider the design.","Use smaller steps (0.5–2) for tight internal spacing and larger steps (4–8) for section gaps."]},{"type":"list","style":"dont","items":["Use arbitrary pixel values outside the scale.","Mix spacing tokens with raw px/rem values in the same component."]}]}]},{"topic":"styling","title":"Styling Components","description":"How to customize component appearance: xstyle prop, Tailwind, StyleX, className, rest props, compound component patterns, and theming hooks.","category":"guide","sections":[{"title":"Overview","category":"guide","content":[{"type":"prose","text":"XDS gives you several ways to style things. Here is when to use each:"},{"type":"table","headers":["Approach","Use for","Example"],"rows":[["xstyle prop","Overriding a specific XDS component","xstyle={styles.override}"],["Tailwind utilities","Layout, wrappers, and utility styling","className=\"flex gap-3 p-4\""],["stylex.create","Reusable styles, pseudo-classes, typed tokens","stylex.create({ card: { ... } })"],["className","Integrating with external CSS or Tailwind on components","className=\"my-card shadow-lg\""]]},{"type":"prose","text":"All approaches resolve to the same XDS design tokens, so theming and dark mode work regardless of which you choose."}]},{"title":"xstyle Prop","category":"guide","content":[{"type":"prose","text":"Every XDS component accepts an xstyle prop for style customization. It accepts StyleX styles created via stylex.create() — not inline objects, not class name strings. StyleX styles are compiled at build time for optimal deduplication and dead-code elimination."},{"type":"code","lang":"tsx","label":"Simple overrides","code":"import as stylex from '@stylexjs/stylex';\n\nconst overrides = stylex.create({\n card: { maxWidth: 400, marginBlock: 16 },\n saveButton: { alignSelf: 'flex-end' },\n});\n\n<XDSCard xstyle={overrides.card} />\n<XDSButton label=\"Save\" xstyle={overrides.saveButton} />"},{"type":"code","lang":"tsx","label":"Pseudo-classes and conditional styles","code":"import * as stylex from '@stylexjs/stylex';\n\nconst overrides = stylex.create({\n card: {\n boxShadow: {\n default: 'none',\n ':hover': { '@media (hover: hover)': '0 4px 12px rgba(0,0,0,0.1)' },\n },\n },\n});\n\n<XDSCard xstyle={overrides.card}>...</XDSCard>"},{"type":"list","style":"unordered","items":["All xstyle values must come from stylex.create()","Pseudo-classes (:hover, :focus-visible) are supported inside stylex.create","All :hover styles MUST use @media (hover: hover) guard","For non-StyleX styling (Tailwind, external CSS), use className instead"]}]},{"title":"Tailwind Integration","category":"guide","content":[{"type":"prose","text":"XDS ships a Tailwind v4 theme bridge that maps all design tokens to Tailwind utility classes. Import it once and use Tailwind classes backed by XDS tokens — colors, spacing, radius, shadows, and typography all resolve to the active theme."},{"type":"code","lang":"css","label":"globals.css — import the bridge","code":"@import \"tailwindcss\";\n@import \"@xds/core/tailwind-theme.css\" layer(theme);"},{"type":"code","lang":"tsx","label":"Tailwind utilities alongside XDS components","code":"<div className=\"text-primary bg-surface rounded-container p-4 flex gap-3\">\n <XDSButton label=\"Save\" variant=\"primary\" />\n <XDSButton label=\"Cancel\" variant=\"secondary\" />\n</div>"},{"type":"prose","text":"The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that XDS components use."}]},{"title":"className and style Props","category":"guide","content":[{"type":"prose","text":"Every component also accepts standard className and style props. className is appended after the component's own classes. style is merged after StyleX inline styles, so consumer values win on conflict."},{"type":"code","lang":"tsx","label":"className with Tailwind utilities","code":"<XDSCard className=\"shadow-lg hover:shadow-xl transition-shadow\">\n ...\n</XDSCard>\n<XDSButton label=\"Save\" className=\"my-app-save-btn\" />"},{"type":"prose","text":"For layout and wrapper styling, Tailwind utilities on className work well. For component-specific overrides (padding, colors, borders), prefer xstyle — it integrates with StyleX deduplication and the component's internal style pipeline."}]},{"title":"Rest Props (Prop Drilling)","category":"guide","content":[{"type":"prose","text":"XDS components extend HTML attributes and spread rest props onto their root DOM element. This means data-* attributes, aria-* attributes, event handlers, and other HTML props pass through automatically."},{"type":"code","lang":"tsx","label":"Data attributes, event handlers, and ARIA","code":"<XDSCard\n data-testid=\"user-card\"\n data-user-id={user.id}\n onMouseEnter={handleHover}\n aria-label=\"User profile card\"\n>\n ...\n</XDSCard>"},{"type":"code","lang":"tsx","label":"Ref forwarding","code":"const cardRef = useRef<HTMLDivElement>(null);\n<XDSCard ref={cardRef}>...</XDSCard>"},{"type":"prose","text":"A few HTML attributes are intentionally omitted from the base type (contentEditable, dangerouslySetInnerHTML). children is not in the base type either — components that accept children declare it explicitly, so slot-based components don't silently drop JSX children."}]},{"title":"Compound Components","category":"guide","content":[{"type":"prose","text":"Complex components are composed from smaller XDS components. Each sub-component accepts its own xstyle, className, and rest props. You style the parts individually — there's no single \"drill into sub-part\" prop."},{"type":"code","lang":"tsx","label":"Dialog with individually styled parts","code":"import * as stylex from '@stylexjs/stylex';\n\nconst overrides = stylex.create({\n dialog: { maxWidth: 500 },\n content: { gap: 'var(--spacing-4)' },\n});\n\n<XDSDialog isOpen={isOpen} onClose={close} xstyle={overrides.dialog}>\n <XDSLayout\n header={\n <XDSLayoutHeader hasDivider>\n <XDSHeading level={2}>Edit Profile</XDSHeading>\n </XDSLayoutHeader>\n }\n content={\n <XDSLayoutContent xstyle={overrides.content}>\n <XDSTextInput label=\"Name\" value={name} onChange={setName} />\n </XDSLayoutContent>\n }\n footer={\n <XDSLayoutFooter hasDivider>\n <XDSButton label=\"Cancel\" variant=\"secondary\" onClick={close} />\n <XDSButton label=\"Save\" variant=\"primary\" onClick={save} />\n </XDSLayoutFooter>\n }\n />\n</XDSDialog>"},{"type":"prose","text":"The pattern: the parent component (Dialog) controls structure and behavior, child components (Layout, Header, Button) control their own appearance. Style each piece where it lives."}]},{"title":"Theming via xds-* Class Names","category":"guide","content":[{"type":"prose","text":"Every component renders a stable xds-* class name (e.g. xds-button, xds-card) plus variant classes. These are the targeting surface for theme overrides in defineTheme. You rarely need to use them directly, but they're useful for debugging and for external CSS that needs to target XDS components."},{"type":"code","lang":"tsx","label":"Class names rendered by components","code":"// <XDSButton variant=\"primary\" size=\"sm\" />\n// renders: class=\"xds-button primary sm ...\"\n\n// <XDSCard variant=\"elevated\" />\n// renders: class=\"xds-card elevated ...\"\n\n// <XDSHeading level={2} />\n// renders: class=\"xds-heading level-2 ...\""},{"type":"code","lang":"css","label":"Targeting in external CSS (escape hatch)","code":".my-app .xds-button.primary {\n /* override primary button in this app context /\n}"},{"type":"prose","text":"For systematic theming, use defineTheme component overrides instead of raw CSS selectors. Run `npx xds docs theme` for the full theming guide."}]},{"title":"Design Tokens","category":"guide","content":[{"type":"prose","text":"When writing custom styles, use design tokens instead of hardcoded values. Tokens are CSS custom properties that adapt to the active theme and color mode. XDS provides tokens for spacing, color, radius, shadow, typography, and size."},{"type":"code","lang":"tsx","label":"Using tokens in stylex.create","code":"import as stylex from '@stylexjs/stylex';\n\nconst styles = stylex.create({\n surface: {\n padding: 'var(--spacing-4)',\n borderRadius: 'var(--radius-container)',\n backgroundColor: 'var(--color-background-surface)',\n },\n});\n\n<XDSCard xstyle={styles.surface} />"},{"type":"code","lang":"tsx","label":"Using typed token imports in stylex.create","code":"import {colorVars, spacingVars, radiusVars} from '@xds/core/theme/tokens.stylex';\n\nconst styles = stylex.create({\n highlight: {\n backgroundColor: colorVars['--color-accent-muted'],\n padding: spacingVars['--spacing-3'],\n borderRadius: radiusVars['--radius-element'],\n },\n});"},{"type":"prose","text":"Both approaches work — var() strings or typed imports from tokens.stylex. The typed imports give autocomplete and catch typos at build time."},{"type":"prose","text":"See `npx xds docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `npx xds docs theme` for how to override tokens via defineTheme."}]},{"title":"What NOT to Do","category":"guide","content":[{"type":"list","style":"dont","items":["style={{}} on raw <div> wrappers. Use xstyle on the XDS component directly.","Hardcoded colors (#fff, rgb(...)). Use var(--color-) tokens or Tailwind semantic classes (text-primary, bg-surface).","Hardcoded spacing (16px, 1rem). Use var(--spacing-) tokens or Tailwind spacing utilities (p-4, gap-3).","Wrapping an XDS component in a <div> just to add margin. Use xstyle with stylex.create on the component.","Using !important. If styles aren't applying, check specificity — xstyle is merged last."]}]}]},{"topic":"theme","title":"Theme System","description":"XDSTheme provider, custom themes, theme build for production/SSR, light/dark mode, and component style overrides.","category":"guide","sections":[{"title":"Quick Start","category":"guide","content":[{"type":"code","lang":"tsx","label":"Basic theme setup (runtime injection)","code":"import {XDSTheme} from '@xds/core';\nimport {defaultTheme} from '@xds/theme-default';\n\nfunction App() {\n return (\n <XDSTheme theme={defaultTheme}>\n <YourApp />\n </XDSTheme>\n );\n}"},{"type":"code","lang":"tsx","label":"Optimized setup (pre-built CSS)","code":"import {XDSTheme} from '@xds/core';\nimport {defaultTheme} from '@xds/theme-default/built';\nimport '@xds/theme-default/theme.css';\n\nfunction App() {\n return (\n <XDSTheme theme={defaultTheme}>\n <YourApp />\n </XDSTheme>\n );\n}"},{"type":"prose","text":"The default import uses runtime style injection — works everywhere, no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support."}]},{"title":"Available Themes","category":"guide","content":[{"type":"table","headers":["Theme","Import","Description"],"rows":[["Default","import {defaultTheme} from '@xds/theme-default'","Blue accent, system fonts, light/dark"],["Neutral","import {neutralTheme} from '@xds/theme-neutral'","Grayscale, shadcn-inspired"],["Brutalist","import {brutalistTheme} from '@xds/theme-brutalist'","Zero radius, monospace, heavy borders"]]},{"type":"prose","text":"All theme packages export from two subpaths:\n- `@xds/theme-{name}` — source theme (runtime injection)\n- `@xds/theme-{name}/built` — pre-built theme (pair with `theme.css`)"}]},{"title":"XDSTheme Props","category":"guide","content":[{"type":"table","headers":["Prop","Type","Default","Description"],"rows":[["theme","XDSDefinedTheme","—","Theme object (required)"],["mode","'system' | 'light' | 'dark'","'system'","Color mode. system follows OS preference."],["children","ReactNode","—","App content"]]}]},{"title":"Creating a Custom Theme","category":"guide","content":[{"type":"prose","text":"Use the CLI wizard (recommended) or create manually with defineTheme. Only override tokens that differ from defaults — omitted tokens use the XDS defaults."},{"type":"code","lang":"bash","label":"Scaffold with CLI","code":"npx xds theme"}]},{"title":"defineTheme","category":"guide","content":[{"type":"prose","text":"defineTheme creates a theme from token overrides and optional scale configs. Scale configs generate tokens from parameters. Explicit token overrides always take precedence over scale-generated values."},{"type":"code","lang":"tsx","label":"defineTheme with scale configs","code":"import {defineTheme} from '@xds/core/theme';\n\nconst myTheme = defineTheme({\n name: 'my-theme',\n color: { accent: '#7B61FF', neutralStyle: 'cool' },\n typography: {\n scale: { base: 14, ratio: 1.2 },\n body: { family: 'Inter', fallbacks: '-apple-system, sans-serif' },\n },\n radius: { base: 4, multiplier: 1 },\n motion: { fast: 175, medium: 410, ratio: 0.75 },\n tokens: {\n // Explicit overrides take precedence over scale-generated values\n '--color-accent': ['#7B61FF', '#9B85FF'],\n },\n components: {\n button: { 'variant:primary': { color: 'white' } },\n },\n});"},{"type":"table","headers":["Config","Generates","Parameters"],"rows":[["color","--color-accent, --color-background-, --color-text-, --color-border, etc.","accent (hex), neutralStyle? (warm|cool|neutral), contrast? (standard|high)"],["typography.scale","--text-heading--size/weight/leading, --text-body-size/weight/leading","base (px), ratio"],["typography.body/heading/code","--font-family-body, --font-family-heading, --font-family-code","family, fallbacks?, url?, weight?"],["radius","--radius-1 through --radius-4, --radius-container, --radius-page","base (px), multiplier (0–2)"],["motion","--duration-fast-min/fast/fast-max, --duration-medium-min/medium/medium-max","fast (ms), medium (ms), ratio, easing?"]]}]},{"title":"Extending a Theme","category":"guide","content":[{"type":"prose","text":"`extends` lets you derive a new theme from an existing one — inheriting its tokens, component overrides, icons, and fonts. Only specify what you want to change; everything else carries over from the base theme."},{"type":"code","lang":"tsx","label":"Extending the default theme","code":"import {defineTheme} from '@xds/core/theme';\nimport {defaultTheme} from '@xds/theme-default';\nimport {myIcons} from './icons';\n\nconst brandTheme = defineTheme({\n name: 'brand',\n extends: defaultTheme,\n icons: myIcons,\n tokens: {\n '--color-accent': ['#7B61FF', '#9B85FF'],\n },\n});"},{"type":"table","headers":["Field","Merge behavior"],"rows":[["tokens","Base tokens are copied first, then child tokens override on top."],["components","Deep-merged — child component rules override matching keys from the base."],["icons","Shallow-merged — child icons override matching names from the base."],["fonts","Base fonts included first, then child fonts appended."],["typography, motion, radius, color","Child config replaces base entirely (these are scale inputs, not additive)."]]}]},{"title":"Component Style Overrides","category":"guide","content":[{"type":"prose","text":"The `components` field in defineTheme targets stable `.xds-` CSS class names. Use `base` for all instances, `variant:value` or `stateName` for specific states."},{"type":"code","lang":"tsx","label":"Component overrides with standard CSS","code":"components: {\n // Standard CSS properties are expanded automatically.\n // borderRadius also sets the internal radius var for concentric math.\n // padding on container components (card, section, dialog) expands to layout tokens.\n card: {\n base: { borderRadius: '20px', padding: '24px' },\n },\n button: {\n base: { borderRadius: '9999px', textTransform: 'uppercase' },\n 'variant:ghost': { borderWidth: '2px', borderStyle: 'solid' },\n },\n // Some components have public CSS vars for properties that don't map\n // to standard CSS. Set these directly.\n button: {\n base: { '--button-press-scale': 'scale(0.95)' },\n },\n}"},{"type":"prose","text":"Run `npx xds component <Name>` to see a component’s theming targets, public CSS variables, and which standard CSS properties are supported."},{"type":"list","style":"do","items":["Write standard CSS properties (borderRadius, padding) — the pipeline expands them into internal vars.","Set public CSS vars directly when no standard property equivalent exists."]},{"type":"list","style":"dont","items":["Set private CSS vars (prefixed --_) directly — use standard CSS properties instead. `xds theme build` will error."]}]},{"title":"Custom Variants","category":"guide","content":[{"type":"prose","text":"Themes can add new prop values to any component. Any `prop:value` key where the value isn’t a built-in gets treated as a new variant. Use `xds theme build` to generate TypeScript augmentations for type safety."},{"type":"code","lang":"tsx","label":"Adding custom variants","code":"components: {\n button: {\n // Override an existing variant\n 'variant:secondary': { backgroundColor: 'rgba(0,0,0,0.06)' },\n // Add a new variant — generates type augmentation on build\n 'variant:primary-muted': {\n backgroundColor: 'light-dark(#F2F4F6, #28292C)',\n color: 'var(--color-text-primary)',\n },\n },\n banner: {\n // Any extensible prop axis works — not just variant\n 'status:neutral': {\n backgroundColor: 'var(--color-muted)',\n color: 'var(--color-text-secondary)',\n },\n },\n}"},{"type":"prose","text":"After building, the new values are type-safe in JSX:"},{"type":"code","lang":"tsx","label":"Using custom variants","code":"// TypeScript knows about 'primary-muted' after xds theme build\n<XDSButton variant=\"primary-muted\" label=\"Save draft\" />\n<XDSBanner status=\"neutral\" title=\"Note\" />"},{"type":"prose","text":"Custom variants only work when the theme that defines them is active. The component’s variant map is extended via module augmentation — no changes to the component source needed."}]},{"title":"Building Themes for Production","category":"guide","content":[{"type":"prose","text":"`npx xds theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint."},{"type":"code","lang":"bash","label":"Build a theme","code":"npx xds theme build ./src/themes/ocean.ts"},{"type":"prose","text":"This generates the following files alongside the source:"},{"type":"table","headers":["File","Description"],"rows":[["ocean.css","Pre-compiled CSS with token overrides, component overrides, and prose element styles in @scope rules"],["ocean.js","ES module exporting the theme object with `built: true` and pre-resolved token values. Also re-exports the icon registry if the source theme declares one."],["ocean.d.ts","TypeScript declarations for the theme and icon registry exports"],["ocean.variants.d.ts","(Optional) Module augmentations for custom component prop values found in the theme’s component overrides"]]},{"type":"prose","text":"The `built: true` flag tells XDSTheme to skip runtime `<style>` injection — the CSS file handles it."},{"type":"code","lang":"tsx","label":"Using a custom built theme","code":"import {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<XDSTheme theme={oceanTheme}>\n <App />\n</XDSTheme>"}]},{"title":"Runtime vs Built Themes","category":"guide","content":[{"type":"prose","text":"XDS themes work in two modes:"},{"type":"table","headers":["","Runtime (source)","Built"],"rows":[["Import (published theme)","@xds/theme-{name}","@xds/theme-{name}/built + theme.css"],["Import (custom theme)","defineTheme() directly","Built .js + .css from `npx xds theme build`"],["How it works","useInsertionEffect injects <style> at hydration","Pre-compiled .css file loaded with the page"],["Component overrides","Injected client-only","In static CSS — present during SSR"],["SSR safe","Tokens yes, component overrides flash on hydration","Fully SSR safe — no flash"],["Best for","Dev, prototyping, client-only SPAs","Production, SSR apps (Next.js, Remix)"]]},{"type":"list","style":"do","items":["Use the /built subpath + theme.css for production SSR apps.","Use runtime themes during development for fast iteration.","Run `npx xds theme build` for custom themes to get the built artifacts."]},{"type":"list","style":"dont","items":["Use runtime themes in production SSR apps — component overrides will flash on hydration.","Import /built without the CSS file — component overrides won’t apply."]}]},{"title":"Light/Dark Mode","category":"guide","content":[{"type":"prose","text":"Use [light, dark] tuples in token values for automatic mode switching. Use mode='system' (default) on XDSTheme to follow OS preference."},{"type":"code","lang":"tsx","label":"Light/dark tuple","code":"'--color-accent': ['#0064E0', '#2694FE'],\n// ^light ^dark"},{"type":"code","lang":"tsx","label":"Toggle with a button","code":"const [mode, setMode] = useState<'light' | 'dark'>('light');\n\n<XDSTheme theme={myTheme} mode={mode}>\n <XDSButton\n label={mode === 'light' ? 'Switch to Dark' : 'Switch to Light'}\n onClick={() => setMode(m => (m === 'light' ? 'dark' : 'light'))}\n />\n</XDSTheme>;"}]},{"title":"Nesting Themes","category":"guide","content":[{"type":"prose","text":"Wrap different sections in separate <XDSTheme> providers."},{"type":"code","lang":"tsx","label":"Dark sidebar with light content","code":"<XDSTheme theme={lightTheme} mode=\"light\">\n <XDSLayout\n header={<XDSLayoutHeader>...</XDSLayoutHeader>}\n start={\n <XDSTheme theme={darkTheme} mode=\"dark\">\n <XDSLayoutPanel>{/* Dark sidebar /}</XDSLayoutPanel>\n </XDSTheme>\n }\n content={<XDSLayoutContent>{/ Light content /}</XDSLayoutContent>}\n />\n</XDSTheme>"}]},{"title":"useXDSTheme Hook","category":"guide","content":[{"type":"code","lang":"tsx","label":"Access current theme","code":"import {useXDSTheme} from '@xds/core';\n\nfunction MyComponent() {\n const ctx = useXDSTheme();\n // ctx.theme — the XDSDefinedTheme object\n // ctx.mode — 'system' | 'light' | 'dark'\n return null;\n}"},{"type":"prose","text":"This is read-only. To change the theme/mode, manage state at the app level and pass it to <XDSTheme>."},{"type":"prose","text":"See `npx xds docs styling` for component-level customization (xstyle, className, rest props). See `npx xds docs tokens` for the full token reference."}]}]},{"topic":"tokens","title":"All Tokens","description":"Complete reference for spacing, color, radius, typography, shadow, motion, and size tokens.","category":"foundations","sections":[{"title":"Color Tokens","content":[{"type":"prose","text":"Semantic colors for consistent theming. All colors use light-dark() for automatic mode switching."},{"type":"table","headers":["Token","Light","Dark"],"rows":[["--color-accent","#0064E0","#2694FE"],["--color-accent-muted","#0082FB33","#0082FB3F"],["--color-on-accent","#FFFFFF","#FFFFFF"],["--color-neutral","light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))","light-dark(rgba(5, 54, 89, 0.1), rgba(223, 226, 229, 0.2))"],["--color-background-surface","#FFFFFF","#1F1F22"],["--color-background-body","#F1F4F7","#111112"],["--color-overlay","#01122866","#11111299"],["--color-overlay-hover","#0536590C","#FFFFFF0C"],["--color-overlay-pressed","#05365919","#FFFFFF19"],["--color-background-muted","#0536590C","#1111127F"],["--color-text-primary","#0A1317","#DFE2E5"],["--color-text-secondary","#4E606F","#AAAFB5"],["--color-text-disabled","#A4B0BC","#6F747C"],["--color-text-accent","#0064E0","#3E9EFB"],["--color-on-dark","#FFFFFF","#FFFFFF"],["--color-on-light","#000000","#000000"],["--color-icon-accent","#0064E0","#2694FE"],["--color-icon-primary","#0A1317","#DFE2E5"],["--color-icon-secondary","#4E606F","#AAAFB5"],["--color-icon-disabled","#A4B0BC","#6F747C"],["--color-background-card","#FFFFFF","#1F1F22"],["--color-background-popover","#FFFFFF","#28292C"],["--color-background-inverted","#0A1317","#FFFFFF"],["--color-background-error-inverted","#AA071E","#E3193B"],["--color-success","#0D8626","#0D8626"],["--color-success-muted","#0B991F33","#0B991F3F"],["--color-on-success","#FFFFFF","#FFFFFF"],["--color-error","#E3193B","#F5394F"],["--color-error-muted","#E3193B33","#F5394F3F"],["--color-on-error","#FFFFFF","#FFFFFF"],["--color-warning","#E9AF08","#F2C00B"],["--color-warning-muted","#E2A40033","#E2A4003F"],["--color-on-warning","#0A1317","#0A1317"],["--color-border","#05365919","#F2F4F619"],["--color-border-emphasized","#CCD3DB","#494D53"],["--color-skeleton","#CCD3DB","#5A5E66"],["--color-track","#CCD3DB","#5A5E66"],["--color-shadow","light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))","light-dark(rgba(5, 54, 89, 0.1), rgba(0, 0, 0, 0.3))"],["--color-tint-hover","black","white"],["--color-background-blue","#0171E333","#0171E333"],["--color-border-blue","#0064E0","#2694FE"],["--color-icon-blue","#0064E0","#2694FE"],["--color-text-blue","#042F97","#AFD7FF"],["--color-background-cyan","#03A7D733","#03A7D733"],["--color-border-cyan","#089DD0","#0171A4"],["--color-icon-cyan","#00ACC1","#26C6DA"],["--color-text-cyan","#014975","#A1EEF9"],["--color-background-gray","#0A131733","#666A724C"],["--color-border-gray","#647685","#748695"],["--color-icon-gray","#4E606F","#AAAFB5"],["--color-text-gray","#0A1317","#E7EAED"],["--color-background-green","#24BB5E33","#24BB5E33"],["--color-border-green","#0D8626","#0B991F"],["--color-icon-green","#0D8626","#26A756"],["--color-text-green","#09441F","#A5F690"],["--color-background-orange","#F2790233","#F2790233"],["--color-border-orange","#EB6E00","#B34A01"],["--color-icon-orange","#E9690B","#FB8C00"],["--color-text-orange","#6B2203","#FDB876"],["--color-background-pink","#E638B333","#E638B333"],["--color-border-pink","#F351C0","#C02294"],["--color-icon-pink","#C2185B","#EC407A"],["--color-text-pink","#650053","#FEADE3"],["--color-background-purple","#7952FF33","#7952FF33"],["--color-border-purple","#9081FF","#7340FE"],["--color-icon-purple","#5B08D8","#7952FF"],["--color-text-purple","#3E0697","#B3B0FE"],["--color-background-red","#E3193B33","#E3193B33"],["--color-border-red","#E3193B","#F5394F"],["--color-icon-red","#D31130","#E3193B"],["--color-text-red","#7B0210","#FFB2B8"],["--color-background-teal","#0DB7AF33","#0DB7AF33"],["--color-border-teal","#08A3A3","#08767D"],["--color-icon-teal","#009688","#26A69A"],["--color-text-teal","#083943","#40DCCD"],["--color-background-yellow","#E2A40033","#E2A40033"],["--color-border-yellow","#C58600","#B47700"],["--color-icon-yellow","#FBC02D","#FFEE58"],["--color-text-yellow","#753F07","#FBCE03"]]}],"previewType":"swatch"},{"title":"Spacing Tokens","content":[{"type":"prose","text":"Spacing scale used for padding, gap, and margin. Component gap props map spacing steps to these tokens."},{"type":"table","headers":["Token","Value"],"rows":[["--spacing-0","0px"],["--spacing-0-5","2px"],["--spacing-1","4px"],["--spacing-1-5","6px"],["--spacing-2","8px"],["--spacing-3","12px"],["--spacing-4","16px"],["--spacing-5","20px"],["--spacing-6","24px"],["--spacing-7","28px"],["--spacing-8","32px"],["--spacing-9","36px"],["--spacing-10","40px"],["--spacing-11","44px"],["--spacing-12","48px"]]}],"previewType":"spacing-bar"},{"title":"Size Tokens","content":[{"type":"prose","text":"Control heights for consistent sizing across buttons, inputs, and selectors."},{"type":"table","headers":["Token","Value"],"rows":[["--size-element-sm","28px"],["--size-element-md","32px"],["--size-element-lg","36px"]]}],"previewType":"size-bar"},{"title":"Border Tokens","content":[{"type":"prose","text":"Border width for card and input borders."},{"type":"table","headers":["Token","Value"],"rows":[["--border-width","1px"]]}],"previewType":"border-line"},{"title":"Radius Tokens","content":[{"type":"prose","text":"Numeric scale based on a 4dp base unit. Tokens scale with the theme's radius multiplier; --radius-none and --radius-full are fixed."},{"type":"table","headers":["Token","Value"],"rows":[["--radius-none","0px"],["--radius-inner","4px"],["--radius-element","8px"],["--radius-container","12px"],["--radius-page","28px"],["--radius-full","9999px"]]}],"previewType":"radius-box"},{"title":"Shadow Tokens","content":[{"type":"prose","text":"Elevation shadows (low → med → high) and inset shadows for input state rings."},{"type":"table","headers":["Token","Value"],"rows":[["--shadow-low","0px 1px 1px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 8px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"],["--shadow-med","0px 1px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 2px 12px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2))"],["--shadow-high","0px 2px 2px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.2)), 0px 8px 24px light-dark(rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3))"],["--shadow-inset-hover","inset 0px 0px 0px 2px light-dark(rgba(5, 54, 89, 0.15), rgba(223, 226, 229, 0.2))"],["--shadow-inset-selected","inset 0px 0px 0px 2px rgba(1, 113, 227, 0.5)"],["--shadow-inset-success","inset 0px 0px 0px 2px rgba(38, 167, 86, 0.3)"],["--shadow-inset-warning","inset 0px 0px 0px 2px rgba(226, 164, 0, 0.3)"],["--shadow-inset-error","inset 0px 0px 0px 2px rgba(227, 25, 59, 0.3)"]]}],"previewType":"shadow-box"},{"title":"Duration Tokens","content":[{"type":"prose","text":"Motion duration primitives. Three bands: fast (micro-interactions), medium (entrance/exit), slow (continuous). Min/max variants derive from base × ratio."},{"type":"table","headers":["Token","Value"],"rows":[["--duration-fast-min","130ms"],["--duration-fast","175ms"],["--duration-fast-max","230ms"],["--duration-medium-min","310ms"],["--duration-medium","410ms"],["--duration-medium-max","550ms"],["--duration-slow-min","730ms"],["--duration-slow","975ms"],["--duration-slow-max","1300ms"]]}],"previewType":"duration-bar"},{"title":"Easing Tokens","content":[{"type":"prose","text":"Easing curves for animations and transitions."},{"type":"table","headers":["Token","Value"],"rows":[["--ease-standard","cubic-bezier(0.24, 1, 0.4, 1)"]]}],"previewType":"easing-curve"},{"title":"Font Family Tokens","content":[{"type":"prose","text":"Font family stacks for body, code, and heading text."},{"type":"table","headers":["Token","Value"],"rows":[["--font-family-body","-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"],["--font-family-code","\"SF Mono\", Monaco, Consolas, monospace"],["--font-family-heading","-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, Helvetica, Arial, sans-serif"]]}],"previewType":"font-sample"},{"title":"Font Size Tokens","content":[{"type":"prose","text":"Geometric type scale: round(14 × 1.2^step). Base is 14px (--font-size-base)."},{"type":"table","headers":["Token","Value"],"rows":[["--font-size-4xs","0.375rem"],["--font-size-3xs","0.4375rem"],["--font-size-2xs","0.5rem"],["--font-size-xs","0.625rem"],["--font-size-sm","0.75rem"],["--font-size-base","0.875rem"],["--font-size-lg","1.0625rem"],["--font-size-xl","1.25rem"],["--font-size-2xl","1.5rem"],["--font-size-3xl","1.8125rem"],["--font-size-4xl","2.1875rem"],["--font-size-5xl","2.625rem"]]}],"previewType":"font-sample"},{"title":"Font Weight Tokens","content":[{"type":"prose","text":"Font weight values for body, emphasis, and headings."},{"type":"table","headers":["Token","Value"],"rows":[["--font-weight-normal","400"],["--font-weight-medium","500"],["--font-weight-semibold","600"],["--font-weight-bold","700"]]}],"previewType":"font-sample"},{"title":"Type Scale Tokens","content":[{"type":"prose","text":"Semantic tokens for headings, body, labels, code, supporting text, and display text. References font size and weight tokens. Override via typography.scale in defineTheme."},{"type":"table","headers":["Token","Value"],"rows":[["--text-heading-1-size","var(--font-size-2xl)"],["--text-heading-1-weight","var(--font-weight-semibold)"],["--text-heading-1-leading","1.3333"],["--text-heading-2-size","var(--font-size-xl)"],["--text-heading-2-weight","var(--font-weight-semibold)"],["--text-heading-2-leading","1.4"],["--text-heading-3-size","var(--font-size-lg)"],["--text-heading-3-weight","var(--font-weight-semibold)"],["--text-heading-3-leading","1.4118"],["--text-heading-4-size","var(--font-size-base)"],["--text-heading-4-weight","var(--font-weight-semibold)"],["--text-heading-4-leading","1.4286"],["--text-heading-5-size","var(--font-size-sm)"],["--text-heading-5-weight","var(--font-weight-semibold)"],["--text-heading-5-leading","1.6667"],["--text-heading-6-size","var(--font-size-xs)"],["--text-heading-6-weight","var(--font-weight-semibold)"],["--text-heading-6-leading","1.6"],["--text-body-size","var(--font-size-base)"],["--text-body-weight","var(--font-weight-normal)"],["--text-body-leading","1.4286"],["--text-large-size","var(--font-size-lg)"],["--text-large-weight","var(--font-weight-semibold)"],["--text-large-leading","1.4118"],["--text-label-size","var(--font-size-base)"],["--text-label-weight","var(--font-weight-medium)"],["--text-label-leading","1.4286"],["--text-code-size","var(--font-size-base)"],["--text-code-weight","var(--font-weight-normal)"],["--text-code-leading","1.4286"],["--text-supporting-size","var(--font-size-sm)"],["--text-supporting-weight","var(--font-weight-normal)"],["--text-supporting-leading","1.6667"],["--text-display-1-size","var(--font-size-5xl)"],["--text-display-1-weight","var(--font-weight-normal)"],["--text-display-1-leading","1.2381"],["--text-display-2-size","var(--font-size-4xl)"],["--text-display-2-weight","var(--font-weight-normal)"],["--text-display-2-leading","1.2571"],["--text-display-3-size","var(--font-size-3xl)"],["--text-display-3-weight","var(--font-weight-normal)"],["--text-display-3-leading","1.2414"]]}],"previewType":"font-sample"},{"title":"Usage in StyleX","content":[{"type":"code","lang":"tsx","label":"Using token imports","code":"import as stylex from '@stylexjs/stylex';\nimport {colorVars, spacingVars, sizeVars, radiusVars} from '@xds/core';\n\nconst styles = stylex.create({\n card: {\n padding: spacingVars['--spacing-4'],\n backgroundColor: colorVars['--color-background-surface'],\n borderRadius: radiusVars['--radius-container'],\n },\n button: {\n height: sizeVars['--size-element-md'],\n },\n});"},{"type":"prose","text":"See `npx xds docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx xds docs theme` for overriding tokens with defineTheme."}]}]},{"topic":"typography","title":"Typography","description":"Font families, geometric type scale, weight, line-height, and semantic text tokens for consistent, accessible text styling.","category":"foundations","sections":[{"title":"Overview","category":"foundations","content":[{"type":"prose","text":"XDS typography is built on a geometric type scale: base size × ratio^step, with 14px and 1.2 as defaults. Every text style is a semantic token that composes font size, weight, and line-height — so components express intent (heading, body, label) rather than raw values."},{"type":"prose","text":"Two layers work together: raw size tokens (--font-size-xs … --font-size-5xl) form the geometric scale, and semantic type scale tokens (--text-heading-1-size, --text-body-leading, etc.) reference them by var(). Themes override the entire scale by adjusting base and ratio in defineTheme — all semantic tokens recompute automatically."}]},{"title":"Font Families","category":"foundations","content":[{"type":"prose","text":"Three font roles: body (UI text), heading (titles and headings), and code (monospace). By default, body and heading share the same system font stack; code uses a monospace stack. Custom themes can assign different families per role — heading inherits from body when not explicitly set."},{"type":"token-ref","topic":"tokens","section":"Font Family Tokens"}]},{"title":"Font Sizes","category":"foundations","content":[{"type":"prose","text":"Geometric scale: round(base × ratio^step), expressed in rem. The default scale is 14px × 1.2, producing 12 steps from 4xs (6px) to 5xl (42px). Adjusting base and ratio in defineTheme regenerates every size token while preserving proportional relationships."},{"type":"token-ref","topic":"tokens","section":"Font Size Tokens"}]},{"title":"Font Weights","category":"foundations","content":[{"type":"prose","text":"Four semantic weights: normal (400, body/code), medium (500, labels/data), semibold (600, headings/titles), bold (700, strong emphasis). Type scale tokens reference these by var() so themes can remap numeric values."},{"type":"token-ref","topic":"tokens","section":"Font Weight Tokens"}]},{"title":"Line Height","category":"foundations","content":[{"type":"prose","text":"Line heights are computed from a tiered target ratio and snapped to a 4px vertical grid. Small text (<20px) targets 1.5, medium text (20–31px) targets 1.4, and large text (≥32px) targets 1.25. A minimum gap of fontSize + 4px is enforced. The result is a unitless ratio stored in each --text--leading token."},{"type":"prose","text":"The 4px grid is critical: every line box aligns to 4px increments, which keeps baselines, spacing, and component heights predictable. The expandTypeScale utility computes these automatically when you provide a base and ratio — you should never need to set line-height manually."}]},{"title":"Type Scale","category":"foundations","content":[{"type":"prose","text":"Semantic tokens that combine size, weight, and line-height into a single type style. Each token triplet (--text--size, --text--weight, --text--leading) is consumed by XDSText and XDSHeading. Use the component props rather than composing raw font tokens."},{"type":"token-ref","topic":"tokens","section":"Type Scale Tokens"}]},{"title":"Display Text","category":"foundations","content":[{"type":"prose","text":"Display variants (display-1, display-2, display-3) continue the geometric progression above heading-1, at steps +6, +5, and +4. They use normal weight (400) instead of semibold, and tighter line-heights (~1.2) — large text reads better with less leading. Use display types for hero banners, marketing headlines, and data callouts — not for document headings."},{"type":"prose","text":"Display text often needs heading semantics for accessibility. Use the type prop on XDSHeading to apply display styling while preserving the correct HTML element: <XDSHeading level={1} type=\"display-1\"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline."}]},{"title":"Usage","category":"foundations","content":[{"type":"code","lang":"tsx","label":"XDSHeading for document structure","code":"import {XDSHeading} from '@xds/core';\n\n// Heading levels map to semantic tokens: level 1 → --text-heading-1-*\n<XDSHeading level={1}>Page Title</XDSHeading>\n<XDSHeading level={2}>Section</XDSHeading>\n<XDSHeading level={3}>Subsection</XDSHeading>\n\n// Display type for hero/marketing headings — level sets the HTML element\n<XDSHeading level={1} type=\"display-1\">Hero Title</XDSHeading>\n<XDSHeading level={2} type=\"display-2\">$1.2M Revenue</XDSHeading>\n\n// Override the accessibility level when visual ≠ document hierarchy\n<XDSHeading level={2} accessibilityLevel={3}>\n Sidebar Section\n</XDSHeading>"},{"type":"code","lang":"tsx","label":"XDSText for body, label, and display text","code":"import {XDSText} from '@xds/core';\n\n<XDSText type=\"body\">Body text at the base scale.</XDSText>\n<XDSText type=\"large\">Emphasized body text.</XDSText>\n<XDSText type=\"label\">Form label</XDSText>\n<XDSText type=\"supporting\">Helper text, timestamps, metadata.</XDSText>\n<XDSText type=\"code\">{'const x = 1;'}</XDSText>\n\n// Display without heading semantics (data callouts, decorative)\n<XDSText type=\"display-2\">$1.2M Revenue</XDSText>"},{"type":"code","lang":"tsx","label":"Customizing the type scale via defineTheme","code":"import {defineTheme} from '@xds/core';\n\n// Adjust the entire ramp holistically with base and ratio\nconst editorialTheme = defineTheme({\n name: 'editorial',\n typography: {\n scale: { base: 16, ratio: 1.25 }, // airy / article feel\n body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },\n heading: { weight: 'bold' },\n code: { family: 'Geist Mono', fallbacks: '\"SF Mono\", monospace' },\n },\n});\n\nconst denseTheme = defineTheme({\n name: 'dense',\n typography: {\n scale: { base: 12, ratio: 1.125 }, // compact / data-dense UI\n },\n});"}]},{"title":"Best Practices","category":"foundations","content":[{"type":"list","style":"do","items":["Use XDSHeading for document headings and XDSText for everything else — they apply the full type scale automatically.","Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI).","Use display types with as=\"h1\" (or h2/h3) when display text is a page heading — this preserves accessibility while giving you display-level sizing. Or better, use <XDSHeading level={1} type=\"display-1\"> which handles both semantics and styling.","Let line-height snap to the 4px grid via the type scale — expandTypeScale computes leading automatically from base and ratio.","Use the supporting type for secondary information: timestamps, helper text, metadata, captions.","Use accessibilityLevel on XDSHeading when the visual hierarchy doesn’t match the document outline (e.g. sidebar or card headings)."]},{"type":"list","style":"dont","items":["Set font-size or line-height manually — use the semantic type scale tokens so the full ramp stays consistent and 4px-grid-aligned.","Skip heading levels (e.g. h1 → h3) — screen readers rely on an unbroken hierarchy. Use accessibilityLevel to decouple visual from semantic level.","Use display types for body content or in-page sections — they’re designed for hero/marketing/data-callout contexts only.","Override individual size tokens (--font-size-lg) to \"tweak\" a heading — adjust base/ratio instead so proportions remain coherent across the entire scale.","Use raw numeric font-weight values (400, 600) — reference the semantic weight tokens so themes can remap them."]}]}]},{"topic":"working-with-ai","title":"Working with AI","description":"How to set up AI coding tools to generate correct XDS component code.","category":"guide","sections":[{"title":"Overview","content":[{"type":"prose","text":"XDS is designed to be AI-friendly — consistent naming, predictable prop patterns, and a CLI that feeds structured documentation directly into AI context windows. But models still need the right context to avoid falling back to generic React patterns or inventing props."},{"type":"prose","text":"The XDS CLI includes a built-in agent docs system that generates context files for your AI tool of choice. One command sets up everything your AI needs to write correct XDS code."}]},{"title":"Quick Start","content":[{"type":"prose","text":"Tell your AI to install the CLI and set itself up:"},{"type":"code","lang":"text","label":"Paste this into your AI","code":"Install @xds/cli and run `npx xds agent-docs` to set up your XDS context. Read the generated file."},{"type":"prose","text":"That's it. The agent-docs command generates everything your AI needs — component index, behavioral rules, CLI reference — pulled from your installed version. After a version bump, run it again to update in place."},{"type":"prose","text":"If you prefer to target a specific file format:"},{"type":"code","lang":"bash","label":"Manual options","code":"npx xds agent-docs --agent claude # CLAUDE.md\nnpx xds agent-docs --agent cursor # .cursorrules\nnpx xds agent-docs --agent codex # AGENTS.md (Copilot, Codex, etc.)"}]},{"title":"What Gets Generated","content":[{"type":"prose","text":"The generated context teaches your AI a 3-step workflow before writing any UI code:"},{"type":"list","style":"ordered","items":["`npx xds template --list` — find a related page pattern to use as reference","`npx xds template <name> --skeleton` — study the layout structure","`npx xds component <Name>` — read props and examples for every component used"]},{"type":"prose","text":"It also includes rules that prevent common mistakes (no raw divs, no style={{}}, use tokens not magic values) and a CLI quick reference. After setup, you shouldn't need to manually correct your AI on XDS conventions — the agent docs handle it at the system level."}]},{"title":"Cursor Setup","content":[{"type":"prose","text":"Cursor project rules aren't always picked up — it selects which rules to apply based on relevance. For reliable inclusion, install XDS context as a User Rule instead. User Rules live at ~/.cursor/rules/ and apply across all projects."},{"type":"code","lang":"bash","label":"Install as a Cursor user rule","code":"mkdir -p ~/.cursor/rules\nnpx xds agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc"}]},{"title":"Checking Your Setup","content":[{"type":"prose","text":"Paste this into your AI before writing any XDS code. These three questions have a 0% pass rate without docs — models confidently guess wrong on all of them. If your AI can't answer them, it'll know to install the agent docs first."},{"type":"code","lang":"text","label":"Paste this into your AI","code":"Before writing any XDS code, check your knowledge:\n\n1. What is the correct import path for XDSButton?\n2. How do you make an XDSDialog non-dismissible?\n3. What prop does XDSSelector use for its items?\n\nIf you don't know all three, run `npx xds init --features agents` to generate agent docs, then read the generated file."}]},{"title":"The --dense Flag","content":[{"type":"prose","text":"Every CLI command supports --dense, which outputs a token-efficient format designed for AI context windows. Use it when pasting CLI output into a web-based AI tool like ChatGPT or Claude."},{"type":"code","lang":"bash","label":"Dense output for pasting into AI conversations","code":"npx xds component Dialog --dense\nnpx xds docs styling --dense\nnpx xds docs tokens --dense"}]}]}],"templates":[{"slug":"ai-chat","name":"AI Chat","description":"AI assistant conversation view with tool calls, system messages, markdown, code blocks, and multi-bubble grouping","isReady":true},{"slug":"ai-chat-artifact","name":"AI Chat (Artifact)","description":"AI chat interface with a resizable chat panel on the left and an artifact preview area on the right for content being created via the conversation","isReady":true},{"slug":"ai-chat-landing","name":"AI Chat (Landing Page)","description":"AI assistant landing page with chat composer, greeting, and category toggles","isReady":true},{"slug":"centered-hero","name":"Centered Hero","description":"Centered headline, description, and CTA buttons above a full-width image.","isReady":false},{"slug":"classic-gallery","name":"Classic Gallery","description":"Clean 2×2 image grid with uniform sizing","isReady":true},{"slug":"documentation-design","name":"Component Reference","description":"Component documentation page with live preview, usage guide, best practices table, and code examples.","isReady":true},{"slug":"contact-form","name":"Contact Form","description":"Marketing lead-capture form with pill toggles, dropdowns, and full-width CTA.","isReady":true},{"slug":"dashboard","name":"Dashboard","description":"Analytics dashboard with KPI cards, charts, and data tables","isReady":true},{"slug":"dashboard-portfolio","name":"Dashboard (Portfolio)","description":"Investment portfolio dashboard with KPI metrics, area chart, and top asset holdings","isReady":true},{"slug":"detail-page","name":"Detail Page","description":"Order detail page with timeline and line items","isReady":true},{"slug":"documentation","name":"Documentation Home","description":"Documentation landing page with hero banner and component category grid organized by Core, Layout, Navigation, and Form.","isReady":true},{"slug":"file-explorer","name":"File Explorer","description":"Column-based file browser inspired by macOS Finder","isReady":true},{"slug":"form-two-column","name":"Form (Two-Column)","description":"Hero header with form card layout for data collection","isReady":true},{"slug":"gallery-hero","name":"Gallery Hero","description":"Centered headline, description, and CTA buttons above a three-image gallery grid.","isReady":false},{"slug":"ide","name":"IDE","description":"Code editor workspace with file explorer, tabbed editor, terminal panel, and properties sidebar — all resizable and collapsible.","isReady":true},{"slug":"library","name":"Library","description":"Browsable grid of XDS components organized by category with tabs and filters","isReady":true},{"slug":"login","name":"Login","description":"Auth form with email and password inputs","isReady":true},{"slug":"login-card","name":"Login (Card)","description":"Centered login card with social sign-in and email form","isReady":true},{"slug":"login-split","name":"Login (Split)","description":"Split-screen login with form and cover image","isReady":true},{"slug":"login-sso","name":"Login (SSO)","description":"SSO login with email-based provider detection","isReady":true},{"slug":"mixed-gallery","name":"Mixed Gallery","description":"Masonry-style image gallery with varying image sizes","isReady":true},{"slug":"editor","name":"Page Editor","description":"Block-based page builder with sidebar config and live preview","isReady":true},{"slug":"payment-form","name":"Payment Form","description":"Secure checkout page with billing info, card details, and order summary.","isReady":true},{"slug":"product-detail","name":"Product Detail","description":"Product page with image gallery and collapsible sections","isReady":true},{"slug":"product-gallery","name":"Product Gallery","description":"Card grid of products with images, titles, descriptions, and prices","isReady":true},{"slug":"settings","name":"Settings","description":"Account settings page with profile, password, and advanced configuration sections","isReady":true},{"slug":"settings-dialog","name":"Settings (Dialog)","description":"Account settings in a modal dialog with sidebar navigation and multi-section content","isReady":true},{"slug":"settings-sidebar","name":"Settings (Sidebar)","description":"Account settings with sidebar navigation, inline editing, and multi-section privacy controls","isReady":true},{"slug":"documentation-technical","name":"Setup Guide","description":"Getting started guide with install steps, AI assistance prompt card, theming setup, and next steps.","isReady":true},{"slug":"side-gallery","name":"Side Gallery","description":"Text and CTA on the left with an image collage on the right","isReady":true},{"slug":"table","name":"Table","description":"Data table with actions","isReady":false},{"slug":"table-grouped","name":"Table (Grouped)","description":"Grouped data table with collapsible status sections, PowerSearch, and detail panel","isReady":true},{"slug":"table-page","name":"Table Page","description":"Data table page with power search filtering and action toolbar.","isReady":true}],"defaultIsMobile":false,"children":"$L1d"}] </article></body></html>

wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"children","type":"ReactNode","description":"Cell content."}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"TableHeaderCell","moduleName":"XDSTableHeaderCell","directory":"Table","group":"Table","description":"	wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"children","type":"ReactNode","description":"Header cell content."}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"TableRow","moduleName":"XDSTableRow","directory":"Table","group":"Table","description":"

wrapper that reads XDSTableContext to apply density padding, font size, and divider borders when used inside XDSTable.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"children","type":"ReactNode","description":"Cell content."}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"TableHeaderCell","moduleName":"XDSTableHeaderCell","directory":"Table","group":"Table","description":"

wrapper that reads XDSTableContext to apply density padding, semibold weight, secondary text color, and divider borders when used inside XDSTable.","keywords":["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],"hidden":false,"parentDoc":"Table","props":[{"name":"children","type":"ReactNode","description":"Header cell content."}],"usage":{"description":"Table displays structured data in rows and columns with consistent dimensionality. It supports rich cell content, sorting, selection, pagination, and column management through a composable plugin system. Use Table for data sets with uniform structure; for simpler or inconsistent data, consider a list or card layout instead.","bestPractices":[{"guidance":true,"description":"Use density and divider variants to match the information density and scanning needs of your data."},{"guidance":true,"description":"Compose rich cell content with XDS components like XDSBadge, XDSStatusDot, and XDSAvatar via renderCell."},{"guidance":true,"description":"Set explicit width on every column using proportional() or pixel(). proportional(1) gives equal flex distribution with a 120px minimum that prevents columns from collapsing on narrow viewports. Omitting width skips the minimum."},{"guidance":false,"description":"Use a table for data without consistent columns — use a list or card layout for heterogeneous content."},{"guidance":false,"description":"Enable every plugin at once — add only the features your use case requires to keep the interface focused."},{"guidance":false,"description":"Omit width on text-heavy columns — without an explicit proportional() width they have no minimum and can squish to near-zero on mobile."}],"anatomy":[{"name":"Column Header","required":true,"description":"Displays titles, sorting controls, and bulk selection."},{"name":"Body Rows","required":true,"description":"Rows with consistent data structure."},{"name":"Footer","required":false,"description":"Displays summary or totals."},{"name":"Top Bar","required":false,"description":"Contains title, toolbar, and filters."},{"name":"Bottom Bar","required":false,"description":"Contains pagination controls."},{"name":"Support Panels","required":false,"description":"Displays row details in a side panel."}]},"theming":{"targets":[{"className":"xds-base-table"},{"className":"xds-table-row"},{"className":"xds-table-cell"},{"className":"xds-table-header-cell"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"data":[{"name":"Alice Chen","role":"Engineer","status":"Active"},{"name":"Bob Smith","role":"Designer","status":"Active"},{"name":"Carol Wu","role":"PM","status":"Away"}],"columns":[{"key":"name","header":"Name"},{"key":"role","header":"Role"},{"key":"status","header":"Status"}]}}},{"name":"TableRow","moduleName":"XDSTableRow","directory":"Table","group":"Table","description":"