An open source design system that's fully customizable and agent ready
TypeScript
docs: update theming sections to className-based model (#518)
Cindy Zhang3b67d98f54e9
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjsindex e7552d6184..38f414250d 100644--- a/packages/core/src/AppShell/AppShell.doc.mjs+++ b/packages/core/src/AppShell/AppShell.doc.mjs@@ -221,6 +221,11 @@ const isMobile = useMediaQuery('(max-width: 768px)');'Skip-to-content link is visually hidden but shown on focus for keyboard users.','Escape key closes the mobile sideNav overlay.',],+ theming: {+ targets: [+ {className: 'xds-app-shell', visualProps: ['background', 'height']},+ ],+ },notes: ['When a TopNav is present, omit XDSSideNavHeader from the SideNav — the TopNav already provides app identity. Adding both would double the identity.','When there is no TopNav, include XDSSideNavHeader inside the SideNav so the app name and logo are present.',diff --git a/packages/core/src/AspectRatio/AspectRatio.doc.mjs b/packages/core/src/AspectRatio/AspectRatio.doc.mjsindex d84f2ac34a..79cf719bfa 100644--- a/packages/core/src/AspectRatio/AspectRatio.doc.mjs+++ b/packages/core/src/AspectRatio/AspectRatio.doc.mjs@@ -43,12 +43,8 @@ export const docs = {},],theming: {- componentKey: 'aspectRatio',- surfaces: [- {- name: 'root',- description: 'Root container styles.',- },+ targets: [+ {className: 'xds-aspect-ratio'},],},};diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjsindex 813a6c28d6..cfdd5264e2 100644--- a/packages/core/src/Avatar/Avatar.doc.mjs+++ b/packages/core/src/Avatar/Avatar.doc.mjs@@ -43,10 +43,9 @@ export const docs = {},],theming: {- componentKey: 'avatar',- surfaces: [- {name: 'root', description: 'Root wrapper styles'},- {name: 'fallback', description: 'Fallback/initials container styles'},+ targets: [+ {className: 'xds-avatar', visualProps: ['size']},+ {className: 'xds-avatar-status-dot', visualProps: ['variant']},],},notes: [diff --git a/packages/core/src/Badge/Badge.doc.mjs b/packages/core/src/Badge/Badge.doc.mjsindex e8c355936f..4e433e62b3 100644--- a/packages/core/src/Badge/Badge.doc.mjs+++ b/packages/core/src/Badge/Badge.doc.mjs@@ -43,17 +43,8 @@ export const docs = {},],theming: {- componentKey: 'badge',- surfaces: [- {- name: 'root',- description: 'Root badge styles.',- },- {- name: 'variants',- description:- 'Per-variant overrides (Partial<Record<XDSBadgeVariant, StyleXStyles>>).',- },+ targets: [+ {className: 'xds-badge', visualProps: ['variant']},],},};diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjsindex f6f2a5c218..9b2c813d3f 100644--- a/packages/core/src/Banner/Banner.doc.mjs+++ b/packages/core/src/Banner/Banner.doc.mjs@@ -109,6 +109,11 @@ export const docs = {'Status icon is aria-hidden="true" — status is conveyed by the ARIA role instead',],+ theming: {+ targets: [+ {className: 'xds-banner', visualProps: ['variant']},+ ],+ },notes: ['Collapsible support is planned: the content area will support collapsing via useXDSCollapsible (issue #187)',],diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjsindex bddebdbb94..5ab8cf1cef 100644--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs@@ -44,6 +44,12 @@ export const docs = {</XDSBreadcrumbItem>`,},],+ theming: {+ targets: [+ {className: 'xds-breadcrumb-item'},+ {className: 'xds-breadcrumbs', visualProps: ['variant']},+ ],+ },accessibility: ['Container renders as a <nav aria-label> landmark; the label defaults to "Breadcrumb" and is customizable via the label prop','Items are placed inside an <ol> with individual <li> wrappers for correct list semantics',diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjsindex 912eb08ef8..dec1d01aef 100644--- a/packages/core/src/Button/Button.doc.mjs+++ b/packages/core/src/Button/Button.doc.mjs@@ -128,6 +128,11 @@ export const docs = {},],+ theming: {+ targets: [+ {className: 'xds-button', visualProps: ['size', 'variant']},+ ],+ },notes: ['XDSButtonVariant type is derived from the variants StyleX object using keyof typeof variants.','Hover/active states use backgroundImage with linear-gradient to layer overlay colors on top of the base background.',diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjsindex eed8f94535..96300bb3aa 100644--- a/packages/core/src/Calendar/Calendar.doc.mjs+++ b/packages/core/src/Calendar/Calendar.doc.mjs@@ -117,12 +117,8 @@ export const docs = {},],theming: {- componentKey: 'calendar',- surfaces: [- {- name: 'root',- description: 'Root container styles',- },+ targets: [+ {className: 'xds-calendar', visualProps: ['mode']},],},notes: [diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex f47f8a4636..fd55eb9dc8 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -87,10 +87,8 @@ export const docs = {},],theming: {- componentKey: 'card',- surfaces: [- {name: 'container', description: 'Outer card wrapper element'},- {name: 'content', description: 'Inner content area with padding'},+ targets: [+ {className: 'xds-card'},],},};diff --git a/packages/core/src/Center/Center.doc.mjs b/packages/core/src/Center/Center.doc.mjsindex 9dfd0581cc..ee10383e32 100644--- a/packages/core/src/Center/Center.doc.mjs+++ b/packages/core/src/Center/Center.doc.mjs@@ -58,12 +58,8 @@ export const docs = {},],theming: {- componentKey: 'center',- surfaces: [- {- name: 'root',- description: 'Root container styles',- },+ targets: [+ {className: 'xds-center', visualProps: ['axis']},],},};diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjsindex 737c8c85cc..e68afda127 100644--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs@@ -95,10 +95,8 @@ export const docs = {},],theming: {- componentKey: 'checkboxInput',- surfaces: [- {name: 'root', description: 'Root container styles'},- {name: 'checkbox', description: 'Visual checkbox element styles'},+ targets: [+ {className: 'xds-checkbox-input', visualProps: ['size']},],},notes: [diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjsindex 1f4d016be5..2bc614de28 100644--- a/packages/core/src/Collapsible/Collapsible.doc.mjs+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs@@ -17,6 +17,11 @@ export const docs = {'Trigger renders as a <button> with aria-expanded reflecting the current open state','A chevron indicator provides a visual affordance for the expanded/collapsed state',],+ theming: {+ targets: [+ {className: 'xds-collapsible'},+ ],+ },notes: ['XDSCollapsible manages its own open/close state by default (uncontrolled)','When nested inside an XDSCollapsibleGroup with a matching value prop, it defers to the group context',diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjsindex b68778c018..ccb60ca8e9 100644--- a/packages/core/src/DateInput/DateInput.doc.mjs+++ b/packages/core/src/DateInput/DateInput.doc.mjs@@ -159,10 +159,8 @@ export const docs = {'Invalid input reverts to the previous valid value on blur.',],theming: {- componentKey: 'dateInput',- surfaces: [- {name: 'wrapper', description: 'Input wrapper element styles'},- {name: 'input', description: 'Text input element styles'},+ targets: [+ {className: 'xds-date-input', visualProps: ['size']},],},};diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex 5b2eba48cb..04dff963db 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -102,10 +102,8 @@ function Example() {},],theming: {- componentKey: 'dialog',- surfaces: [- {name: 'root', description: 'Dialog element styles'},- {name: 'backdrop', description: 'Backdrop overlay styles'},+ targets: [+ {className: 'xds-dialog', visualProps: ['variant']},],},keyboard:diff --git a/packages/core/src/Divider/Divider.doc.mjs b/packages/core/src/Divider/Divider.doc.mjsindex 1943cc0a31..19b08297a6 100644--- a/packages/core/src/Divider/Divider.doc.mjs+++ b/packages/core/src/Divider/Divider.doc.mjs@@ -8,7 +8,7 @@ export const docs = {'Optional label centered on the divider line','Subtle and strong visual weight variants','Full-bleed mode extends the divider to container edges via negative margins',- 'Themeable via ComponentStyles — exposes root, line, and label surfaces',+ 'Themeable via className — target .xds-divider with variant and orientation classes',],examples: [{@@ -59,11 +59,8 @@ export const docs = {},],theming: {- componentKey: 'divider',- surfaces: [- {name: 'root', description: 'Root container element'},- {name: 'line', description: 'Divider line element'},- {name: 'label', description: 'Label text element'},+ targets: [+ {className: 'xds-divider', visualProps: ['orientation', 'variant']},],},};diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjsindex eb42a65603..499157c90d 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs@@ -97,10 +97,8 @@ export const docs = {},],theming: {- componentKey: 'dropdownMenu',- surfaces: [- {name: 'root', description: 'Dropdown container styles'},- {name: 'item', description: 'Menu item styles'},+ targets: [+ {className: 'xds-dropdown-menu-item'},],},keyboard:diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjsindex 548c96c8b1..f7cd09d686 100644--- a/packages/core/src/EmptyState/EmptyState.doc.mjs+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs@@ -10,7 +10,7 @@ export const docs = {'Title renders as an <h3> heading element for correct document outline','Actions are laid out horizontally by default and stack vertically in compact mode','Compact variant reduces spacing for constrained content areas',- 'Accepts StyleX override styles via xstyle for custom container adjustments',+ 'Accepts xstyle, className, and style props for custom container adjustments','Forwarded ref lands on the root <div> container',],examples: [@@ -77,6 +77,11 @@ export const docs = {default: 'false',},],+ theming: {+ targets: [+ {className: 'xds-emptystate'},+ ],+ },accessibility: ['Container uses role="status" to announce the empty state content to screen readers.','Icon wrapper has aria-hidden="true" so decorative icons are ignored by assistive technology.',diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjsindex 4d7d7f86c5..35f0173b1b 100644--- a/packages/core/src/Field/Field.doc.mjs+++ b/packages/core/src/Field/Field.doc.mjs@@ -68,10 +68,10 @@ const bioDescId = useId();},],theming: {- componentKey: 'field',- surfaces: [- {name: 'root', description: 'Root container styles'},- {name: 'description', description: 'Description text styles'},+ targets: [+ {className: 'xds-field'},+ {className: 'xds-field-label'},+ {className: 'xds-field-status', visualProps: ['type', 'variant']},],},notes: [diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjsindex 77525c2777..05bc60fd0a 100644--- a/packages/core/src/FormLayout/FormLayout.doc.mjs+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs@@ -72,6 +72,11 @@ export const docs = {'Nestable: inner FormLayout overrides context for its children','Purely spatial: does not manage form state or render <form> — form submission is separate',],+ theming: {+ targets: [+ {className: 'xds-form-layout', visualProps: ['direction']},+ ],+ },notes: ['Renders a <div>, not a <form>. Use a separate <form> element and connect submit buttons via the HTML form attribute.','XDSFormLayoutContext provides { direction } to children. Import from @xds/core/FormLayout to read layout direction in custom components.',diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjsindex da70b3c6f1..727e5c1361 100644--- a/packages/core/src/Grid/Grid.doc.mjs+++ b/packages/core/src/Grid/Grid.doc.mjs@@ -52,8 +52,10 @@ export const docs = {},],theming: {- componentKey: 'grid',- surfaces: [{name: 'root', description: 'Root grid container styles'}],+ targets: [+ {className: 'xds-grid', visualProps: ['align', 'columns', 'gap', 'justify']},+ {className: 'xds-grid-span'},+ ],},notes: ['Use XDSGrid for any grid layout instead of manual CSS grid (`display: "grid"`, `gridTemplateColumns`). It handles gap tokens and works with any column count.',diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjsindex ca138029f5..9f411bc4b4 100644--- a/packages/core/src/Icon/Icon.doc.mjs+++ b/packages/core/src/Icon/Icon.doc.mjs@@ -72,12 +72,8 @@ import {Home} from 'lucide-react';},],theming: {- componentKey: 'icon',- surfaces: [- {- name: 'root',- description: 'Root SVG element styles',- },+ targets: [+ {className: 'xds-icon', visualProps: ['color', 'size']},],},accessibility: [diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjsindex 41eb544a28..8262abe6bb 100644--- a/packages/core/src/Layer/Layer.doc.mjs+++ b/packages/core/src/Layer/Layer.doc.mjs@@ -452,13 +452,8 @@ layer.show();},],theming: {- componentKey: 'popover',- surfaces: [- {- name: 'container',- description:- 'Inner content container of the popover (background, border-radius, shadow, padding).',- },+ targets: [+ {className: 'xds-popover'},],},};diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsindex 2d9f8e674a..e352387da4 100644--- a/packages/core/src/Layout/Layout.doc.mjs+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -56,6 +56,15 @@ export const docs = {</XDSCard>`,},],+ theming: {+ targets: [+ {className: 'xds-layout', visualProps: ['height']},+ {className: 'xds-layout-content'},+ {className: 'xds-layout-footer'},+ {className: 'xds-layout-header'},+ {className: 'xds-layout-panel'},+ ],+ },notes: ['Use XDSLayout for page shells and app layouts — any UI with a header bar, sidebar navigation, scrollable content area, or action footer. Do not use for simple stacking (use XDSVStack/XDSHStack instead).','XDSLayoutContainer sets CSS variables that child components read: --layout-padding-outer-x (outer horizontal padding), --layout-padding-outer-y (outer vertical padding), --layout-padding-inner-x (inner horizontal padding used by Header, Footer, Content, Panel), --layout-padding-inner-y (inner vertical padding used by Header, Footer, Content, Panel).',diff --git a/packages/core/src/Link/Link.doc.mjs b/packages/core/src/Link/Link.doc.mjsindex 4b4822894e..8302a6c848 100644--- a/packages/core/src/Link/Link.doc.mjs+++ b/packages/core/src/Link/Link.doc.mjs@@ -74,8 +74,9 @@ function MyComponent({as}: {as?: XDSLinkComponentType}) {},],theming: {- componentKey: 'link',- surfaces: [{name: 'root', description: 'Root anchor element styles'}],+ targets: [+ {className: 'xds-link', visualProps: ['color']},+ ],},notes: ['By default, links inherit font family, size, line-height, and weight from parent elements',diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjsindex 6e3a746db9..c3783ae9fb 100644--- a/packages/core/src/List/List.doc.mjs+++ b/packages/core/src/List/List.doc.mjs@@ -60,6 +60,12 @@ export const docs = {'Dividers are aria-hidden="true"','Interactive items are keyboard-focusable via Tab',],+ theming: {+ targets: [+ {className: 'xds-list', visualProps: ['density', 'listStyle']},+ {className: 'xds-list-item'},+ ],+ },notes: ['Invisible button pattern: when onClick is provided, an invisible <button> wraps the label + description for accessibility. The <li> is the visual container with hover/press styles. startContent and endContent are siblings to the button (not inside it). Container click fires onClick unless the click originated from an interactive child. :focus-within on the container shows the focus outline.','When href is provided instead of onClick, the same invisible pattern uses an <a> element.',diff --git a/packages/core/src/MobileNav/MobileNav.doc.mjs b/packages/core/src/MobileNav/MobileNav.doc.mjsindex bbb8828834..ad181e6660 100644--- a/packages/core/src/MobileNav/MobileNav.doc.mjs+++ b/packages/core/src/MobileNav/MobileNav.doc.mjs@@ -141,10 +141,8 @@ const navSections = (keyboard:'Escape closes the drawer; Tab/Shift+Tab cycles focus within the drawer (browser-native focus trapping)',theming: {- componentKey: 'mobileNav',- surfaces: [- {name: 'root', description: 'Root dialog element styles'},- {name: 'drawer', description: 'Drawer panel styles'},+ targets: [+ {className: 'xds-mobile-nav', visualProps: ['side']},],},};diff --git a/packages/core/src/NavIcon/NavIcon.doc.mjs b/packages/core/src/NavIcon/NavIcon.doc.mjsindex fe7e2ecac3..0c269cecae 100644--- a/packages/core/src/NavIcon/NavIcon.doc.mjs+++ b/packages/core/src/NavIcon/NavIcon.doc.mjs@@ -47,4 +47,9 @@ export const docs = {/>`,},],+ theming: {+ targets: [+ {className: 'xds-navicon'},+ ],+ },};diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjsindex 2c97ca7714..b4dd352104 100644--- a/packages/core/src/NumberInput/NumberInput.doc.mjs+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs@@ -219,10 +219,8 @@ export const docs = {},],theming: {- componentKey: 'numberInput',- surfaces: [- {name: 'wrapper', description: 'Input wrapper styles'},- {name: 'input', description: 'Number input element styles'},+ targets: [+ {className: 'xds-number-input', visualProps: ['size']},],},accessibility: [diff --git a/packages/core/src/Pagination/Pagination.doc.mjs b/packages/core/src/Pagination/Pagination.doc.mjsindex 2dfa8cd82e..04f2d5cee0 100644--- a/packages/core/src/Pagination/Pagination.doc.mjs+++ b/packages/core/src/Pagination/Pagination.doc.mjs@@ -147,9 +147,8 @@ export const docs = {'All interactive elements are keyboard accessible.',],theming: {- componentKey: 'pagination',- surfaces: [- {name: 'root', description: 'Root nav container styles'},+ targets: [+ {className: 'xds-pagination', visualProps: ['size', 'variant']},],},notes: [diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjsindex 6e76b0f680..b370e23b9d 100644--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs@@ -102,6 +102,11 @@ export const docs = {code: `<XDSProgressBar value={50} label="Loading" isLabelHidden />`,},],+ theming: {+ targets: [+ {className: 'xds-progressbar', visualProps: ['size', 'variant']},+ ],+ },accessibility: ['Determinate: uses role="meter" with aria-valuenow, aria-valuemin, aria-valuemax','Indeterminate: uses role="progressbar" without value attributes',diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjsindex f88aaf161a..1848047b13 100644--- a/packages/core/src/RadioList/RadioList.doc.mjs+++ b/packages/core/src/RadioList/RadioList.doc.mjs@@ -85,8 +85,10 @@ export const docs = {},],theming: {- componentKey: 'radioList',- surfaces: [{name: 'root', description: 'Root radio group styles'}],+ targets: [+ {className: 'xds-radio-list', visualProps: ['orientation', 'size']},+ {className: 'xds-radio-list-item'},+ ],},notes: ['XDSRadioList creates a RadioListContext that provides name, value, onChange, isDisabled, isRequired, size, and status to child items',diff --git a/packages/core/src/Section/Section.doc.mjs b/packages/core/src/Section/Section.doc.mjsindex 4ea97e5fb0..2f928aabc8 100644--- a/packages/core/src/Section/Section.doc.mjs+++ b/packages/core/src/Section/Section.doc.mjs@@ -91,4 +91,9 @@ export const docs = {default: 'false',},],+ theming: {+ targets: [+ {className: 'xds-section', visualProps: ['variant']},+ ],+ },};diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjsindex 201ada2e39..7ef6fd9ff1 100644--- a/packages/core/src/Selector/Selector.doc.mjs+++ b/packages/core/src/Selector/Selector.doc.mjs@@ -21,10 +21,9 @@ export const docs = {'aria-activedescendant tracks the focused option.',],theming: {- componentKey: 'selector',- surfaces: [- {name: 'trigger', description: 'Trigger button styles'},- {name: 'dropdown', description: 'Dropdown container styles'},+ targets: [+ {className: 'xds-selector', visualProps: ['size']},+ {className: 'xds-selector-option'},],},examples: [diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjsindex af07f05d9e..4b7cff1be2 100644--- a/packages/core/src/SideNav/SideNav.doc.mjs+++ b/packages/core/src/SideNav/SideNav.doc.mjs@@ -20,6 +20,14 @@ export const docs = {'isHeaderHidden visually hides the section title while keeping it accessible to screen readers',],keyboard: 'Tab through items, Enter/Space to activate links',+ theming: {+ targets: [+ {className: 'xds-side-nav'},+ {className: 'xds-side-nav-header'},+ {className: 'xds-side-nav-item'},+ {className: 'xds-side-nav-section'},+ ],+ },notes: ['When used inside XDSAppShell alongside XDSTopNav, omit XDSSideNavHeader — the TopNav already provides app identity and including the header would duplicate it.','Without a TopNav, include XDSSideNavHeader to provide app identity.',diff --git a/packages/core/src/Skeleton/Skeleton.doc.mjs b/packages/core/src/Skeleton/Skeleton.doc.mjsindex 8ccd4fa5e4..2bedabb096 100644--- a/packages/core/src/Skeleton/Skeleton.doc.mjs+++ b/packages/core/src/Skeleton/Skeleton.doc.mjs@@ -62,12 +62,8 @@ export const docs = {},],theming: {- componentKey: 'skeleton',- surfaces: [- {- name: 'root',- description: 'Root skeleton element styles',- },+ targets: [+ {className: 'xds-skeleton'},],},notes: [diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjsindex 99a50878cf..e1194a8d30 100644--- a/packages/core/src/Slider/Slider.doc.mjs+++ b/packages/core/src/Slider/Slider.doc.mjs@@ -215,15 +215,6 @@ export const docs = {description: 'Tooltip text for an info icon displayed next to the label.',},],- theming: {- componentKey: 'slider',- surfaces: [- {name: 'root', description: 'Root container element'},- {name: 'track', description: 'Background track element'},- {name: 'filledTrack', description: 'Filled/active portion of the track'},- {name: 'thumb', description: 'Draggable thumb handle'},- ],- },accessibility: ['Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.','The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',diff --git a/packages/core/src/Spinner/Spinner.doc.mjs b/packages/core/src/Spinner/Spinner.doc.mjsindex b33a107a58..516be1abe7 100644--- a/packages/core/src/Spinner/Spinner.doc.mjs+++ b/packages/core/src/Spinner/Spinner.doc.mjs@@ -46,12 +46,8 @@ export const docs = {},],theming: {- componentKey: 'spinner',- surfaces: [- {- name: 'root',- description: 'Root spinner element styles',- },+ targets: [+ {className: 'xds-spinner', visualProps: ['size']},],},notes: [diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjsindex bd75fe3cc3..665b842437 100644--- a/packages/core/src/Stack/Stack.doc.mjs+++ b/packages/core/src/Stack/Stack.doc.mjs@@ -69,6 +69,12 @@ import * as stylex from '@stylexjs/stylex';</div>`,},],+ theming: {+ targets: [+ {className: 'xds-stack', visualProps: ['direction', 'gap', 'wrap']},+ {className: 'xds-stack-item', visualProps: ['size']},+ ],+ },notes: ["Import from '@xds/core/Layout': XDSHStack, XDSVStack, XDSStackItem, stack, stackItem.",'The gap prop accepts spacing tokens: space0, space0.5, space1, space2, space3, space4, space5, space6, space7.',diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjsindex 7c028d2313..eb1a0af0bd 100644--- a/packages/core/src/StatusDot/StatusDot.doc.mjs+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs@@ -54,6 +54,11 @@ export const docs = {code: `<XDSStatusDot variant="positive" label="Live" isPulsing />`,},],+ theming: {+ targets: [+ {className: 'xds-statusdot', visualProps: ['size', 'variant']},+ ],+ },accessibility: ['Renders as <span role="img" aria-label={label}> for screen reader support.','Not focusable — intended as a decorative indicator only.',diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjsindex e550b40c9e..7c7114a1f3 100644--- a/packages/core/src/Switch/Switch.doc.mjs+++ b/packages/core/src/Switch/Switch.doc.mjs@@ -181,11 +181,8 @@ export const docs = {},],theming: {- componentKey: 'switch',- surfaces: [- {name: 'root', description: 'Root container flex wrapper'},- {name: 'track', description: 'Switch track background element'},- {name: 'thumb', description: 'Animated circular thumb inside the track'},+ targets: [+ {className: 'xds-switch'},],},accessibility: [diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjsindex 34844ed1b4..44608a0c12 100644--- a/packages/core/src/TabList/TabList.doc.mjs+++ b/packages/core/src/TabList/TabList.doc.mjs@@ -60,8 +60,10 @@ export const docs = {},],theming: {- componentKey: 'tabList',- surfaces: [{name: 'root', description: 'Root nav container styles'}],+ targets: [+ {className: 'xds-tab-list', visualProps: ['size']},+ {className: 'xds-tab'},+ ],},accessibility: ['XDSTabList renders as a <nav> landmark with aria-label="Tabs"',diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjsindex 28d168d483..4207d44bb9 100644--- a/packages/core/src/Table/Table.doc.mjs+++ b/packages/core/src/Table/Table.doc.mjs@@ -15,7 +15,7 @@ export const docs = {'Selection via useXDSTableSelection — checkboxes, select-all, aria-selected','Body rows memoized with custom comparison — only changed rows re-render','Auto-generated columns from data object keys when columns prop is omitted',- 'Theming — root, headerRow, bodyRow, headerCell, bodyCell surfaces via ComponentStyles',+ 'Themeable via className — target .xds-base-table, .xds-table-row, .xds-table-cell, .xds-table-header-cell',],examples: [{@@ -182,13 +182,11 @@ const selectionPlugin = useXDSTableSelection<User>({},],theming: {- componentKey: 'table',- surfaces: [- {name: 'root', description: 'Root table element styles'},- {name: 'headerRow', description: 'Header row styles'},- {name: 'bodyRow', description: 'Body row styles'},- {name: 'headerCell', description: 'Header cell styles'},- {name: 'bodyCell', description: 'Body cell styles'},+ targets: [+ {className: 'xds-base-table'},+ {className: 'xds-table-row'},+ {className: 'xds-table-cell'},+ {className: 'xds-table-header-cell'},],},accessibility: [diff --git a/packages/core/src/Text/Text.doc.mjs b/packages/core/src/Text/Text.doc.mjsindex 344277c29b..c248954ed7 100644--- a/packages/core/src/Text/Text.doc.mjs+++ b/packages/core/src/Text/Text.doc.mjs@@ -42,6 +42,12 @@ export const docs = {'Tabular number support for aligned numeric data','All typography driven by CSS custom properties — fully themeable per-component',],+ theming: {+ targets: [+ {className: 'xds-heading', visualProps: ['level', 'variant']},+ {className: 'xds-text', visualProps: ['type']},+ ],+ },accessibility: ['XDSHeading renders the correct semantic h1–h6 element based on the `level` prop.','When `accessibilityLevel` differs from `level`, `aria-level` is set so screen readers announce the correct document outline position while preserving the visual style.',diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjsindex f156d58882..55b8211e8f 100644--- a/packages/core/src/TextArea/TextArea.doc.mjs+++ b/packages/core/src/TextArea/TextArea.doc.mjs@@ -179,16 +179,8 @@ export const docs = {},],theming: {- componentKey: 'textArea',- surfaces: [- {- name: 'wrapper',- description: 'Outer wrapper div that contains the textarea and icons.',- },- {- name: 'textarea',- description: 'The textarea element itself.',- },+ targets: [+ {className: 'xds-text-input', visualProps: ['size']},],},accessibility: [diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjsindex 8b223c6c5d..0c5ca134ea 100644--- a/packages/core/src/TextInput/TextInput.doc.mjs+++ b/packages/core/src/TextInput/TextInput.doc.mjs@@ -182,10 +182,8 @@ export const docs = {},],theming: {- componentKey: 'textInput',- surfaces: [- {name: 'wrapper', description: 'Wrapper container element'},- {name: 'input', description: 'Input element'},+ targets: [+ {className: 'xds-text-input', visualProps: ['size']},],},accessibility: [diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjsindex b793a1b19f..b7149e0716 100644--- a/packages/core/src/TimeInput/TimeInput.doc.mjs+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs@@ -193,10 +193,8 @@ export const docs = {},],theming: {- componentKey: 'timeInput',- surfaces: [- {name: 'wrapper', description: 'Outer input wrapper div'},- {name: 'input', description: 'Text input element'},+ targets: [+ {className: 'xds-date-input', visualProps: ['size']},],},accessibility: [diff --git a/packages/core/src/Token/Token.doc.mjs b/packages/core/src/Token/Token.doc.mjsindex a2bb01c335..9e76c9f29a 100644--- a/packages/core/src/Token/Token.doc.mjs+++ b/packages/core/src/Token/Token.doc.mjs@@ -102,6 +102,11 @@ export const docs = {code: '<XDSToken label="User" icon={<UserIcon />} isLabelHidden />',},],+ theming: {+ targets: [+ {className: 'xds-token', visualProps: ['color']},+ ],+ },accessibility: ['When isLabelHidden is true, the label is clipped visually but exposed via aria-label on the root element so screen readers still announce it.','The description prop maps to aria-description on the root element for supplementary context.',diff --git a/packages/core/src/TopNav/TopNav.doc.mjs b/packages/core/src/TopNav/TopNav.doc.mjsindex bbbc516146..2fd719c4f1 100644--- a/packages/core/src/TopNav/TopNav.doc.mjs+++ b/packages/core/src/TopNav/TopNav.doc.mjs@@ -9,7 +9,7 @@ export const docs = {'Three-column centering — when centerContent is provided, switches to CSS grid (1fr auto 1fr) for true horizontal centering','Companion components — XDSTopNavTitle, XDSTopNavItem, XDSTopNavMenu, XDSTopNavMegaMenu','Accessible — uses role="navigation" with aria-label, aria-current="page" on selected items',- 'Themeable — supports root style override via theme ComponentStyles',+ 'Themeable via className — target .xds-top-nav and sub-component classes','Link customization — XDSTopNavItem accepts an as prop to swap the anchor element (e.g. for React Router)',],examples: [@@ -114,8 +114,12 @@ export const docs = {},],theming: {- componentKey: 'topNav',- surfaces: [{name: 'root', description: 'Root nav bar element'}],+ targets: [+ {className: 'xds-top-nav'},+ {className: 'xds-top-nav-item'},+ {className: 'xds-top-nav-title'},+ {className: 'xds-top-nav-mega-menu'},+ ],},accessibility: ['XDSTopNav renders a <nav> element with role="navigation" and aria-label set from the label prop',diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjsindex 8cb13f5faf..e7e7e58884 100644--- a/packages/core/src/Typeahead/Typeahead.doc.mjs+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs@@ -396,6 +396,11 @@ export const docs = {],keyboard:'Arrow keys navigate dropdown items; Enter selects highlighted item; Escape closes dropdown or restores previous value in edit mode; Home/End jump to first/last item',+ theming: {+ targets: [+ {className: 'xds-typeahead-item'},+ ],+ },notes: ['XDSSearchSource requires items to implement XDSSearchableItem ({ id: string; label: string; [key: string]: unknown }).','Edit mode in XDSTypeahead: clicking the selected token removes it visually, populates the input with the label text, and selects all. Blurring without selecting restores the original token.',diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.tsindex 616590fd0a..ea1eb3cdd7 100644--- a/packages/core/src/docs-types.ts+++ b/packages/core/src/docs-types.ts@@ -70,24 +70,27 @@ export interface Example {}/**- * A themeable style surface that consumers can override via their theme's- * `ComponentStyles`. Each component exposes named surfaces (e.g. `root`,- * `trigger`, `track`) that map to internal styled elements.+ * A theming target — a stable CSS class name that `defineTheme` can target+ * via `@scope` selectors. Each component renders one or more class names+ * via `xdsClassName()`, and themes can override styles for each.** @example* ```- * {name: 'root', description: 'Outer wrapper element'}- * {name: 'track', description: 'Slider track background'}+ * {className: 'xds-button', visualProps: ['variant', 'size']}+ * {className: 'xds-avatar-status-dot', visualProps: ['variant']}+ * {className: 'xds-card'}* ```*/-export interface ThemingSurface {- /** Surface key as used in the theme object, always camelCase.- * e.g. `"root"`, `"track"`, `"filledTrack"`, `"headerRow"`, `"bodyCell"` */- name: string;- /** Short noun phrase describing the DOM element or visual region.- * No trailing period. e.g. `"Outer wrapper element"`,- * `"Animated circular thumb inside the track"` */- description: string;+export interface ThemingTarget {+ /** The stable CSS class name rendered by the component.+ * Always starts with `xds-`.+ * e.g. `"xds-button"`, `"xds-avatar-status-dot"`, `"xds-card"` */+ className: string;+ /** Visual prop names that produce variant classes on this element.+ * These are the props passed to `xdsClassName()` as the second argument.+ * Themes can target specific variants via `.xds-button.secondary`.+ * Omit if the component has no visual props (class name only). */+ visualProps?: string[];}/**@@ -135,15 +138,13 @@ interface BaseDoc {* e.g. `"Variants: 'primary', 'secondary', 'ghost', 'destructive'"`,* `"Single & range modes: pass a number or [number, number]"` */features?: string[];- /** Theming configuration. Include only if the component supports- * style overrides via the theme's `ComponentStyles`. */+ /** Theming configuration. Documents the stable CSS class names+ * rendered by this component that themes can target via `@scope`+ * selectors in `defineTheme`. */theming?: {- /** The key used in the theme's `components` object.- * Always lowercase, matches the directory name.- * e.g. `"button"`, `"switch"`, `"table"` */- componentKey: string;- /** All styleable surfaces this component exposes. */- surfaces: ThemingSurface[];+ /** CSS class targets rendered by this component.+ * Each entry corresponds to an `xdsClassName()` call in the source. */+ targets: ThemingTarget[];};/** Accessibility notes — ARIA patterns, screen reader behavior.* Each string is one self-contained, declarative note.