Skip to content

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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.ts
index 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.