Skip to content

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

TypeScript

feat(core): add xds-* class names to 20 components for CSS theming (#510)

Cindy Zhangf772f43b99ce
diff --git a/apps/storybook/.storybook/preview.tsx b/apps/storybook/.storybook/preview.tsx
index 985ef6f65c..0509e3e459 100644
--- a/apps/storybook/.storybook/preview.tsx
+++ b/apps/storybook/.storybook/preview.tsx
@@ -3,6 +3,7 @@ import * as React from 'react';
import {XDSTheme} from '@xds/core';
import {defaultTheme} from '@xds/theme-default';
import {neutralTheme} from '@xds/theme-neutral';
+import {brutalistTheme} from '@xds/theme-brutalist';
// Import the base reset and typography stylesheets
import '@xds/core/reset.css';
@@ -18,6 +19,7 @@ import '../../../packages/core/dist/index.css';
const themes = {
default: defaultTheme,
neutral: neutralTheme,
+ brutalist: brutalistTheme,
};
/**
@@ -94,6 +96,7 @@ const preview: Preview = {
{value: 'none', title: 'None (base tokens)', icon: 'close'},
{value: 'default', title: 'Default', icon: 'circlehollow'},
{value: 'neutral', title: 'Neutral', icon: 'circle'},
+ {value: 'brutalist', title: 'Brutalist', icon: 'lightning'},
],
dynamicTitle: true,
},
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjs
index 0a026d7b16..a9d952db8d 100644
--- a/packages/cli/src/commands/build-theme.mjs
+++ b/packages/cli/src/commands/build-theme.mjs
@@ -44,6 +44,10 @@ function resolveTokenValue(value) {
* - `variant:secondary` → '.secondary'
* - `level:1` → '.level-1' (digits get prefixed)
* - `variant:destructive+size:sm` → '.destructive.sm'
+ *
+ * <!-- SYNC: packages/core/src/utils/parseStyleKey.ts -->
+ * <!-- SYNC: packages/core/src/utils/xdsClassName.ts -->
+ * The digit-prefix and value-to-class logic must match across all three files.
*/
function parseStyleKey(key) {
if (key === 'base') return '';
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 31dd2692a0..c60007f377 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -31,6 +31,7 @@ import {XDSLayoutHeader} from '../Layout/XDSLayoutHeader';
import {XDSLayoutPanel} from '../Layout/XDSLayoutPanel';
import {XDSLayoutContent} from '../Layout/XDSLayoutContent';
import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Constants
@@ -482,11 +483,14 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
<div
ref={setShellRef}
data-testid={dataTestId}
- {...stylex.props(
- styles.root,
- background === 'wash' ? styles.rootBgWash : styles.rootBgSurface,
- isFill ? styles.rootFill : styles.rootAuto,
- xstyle,
+ {...mergeProps(
+ xdsClassName('app-shell', {background, height}),
+ stylex.props(
+ styles.root,
+ background === 'wash' ? styles.rootBgWash : styles.rootBgSurface,
+ isFill ? styles.rootFill : styles.rootAuto,
+ xstyle,
+ ),
)}>
{/* Skip-to-content link */}
<a
diff --git a/packages/core/src/AspectRatio/XDSAspectRatio.tsx b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
index af6892ed41..5949426d25 100644
--- a/packages/core/src/AspectRatio/XDSAspectRatio.tsx
+++ b/packages/core/src/AspectRatio/XDSAspectRatio.tsx
@@ -22,6 +22,7 @@ import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register component styles with ComponentStyles
@@ -91,7 +92,10 @@ export const XDSAspectRatio = forwardRef<HTMLElement, XDSAspectRatioProps>(
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
- {...stylex.props(styles.container, xstyle, rootOverride)}
+ {...mergeProps(
+ xdsClassName('aspect-ratio'),
+ stylex.props(styles.container, xstyle, rootOverride),
+ )}
style={{aspectRatio: ratio}}
{...props}>
<div {...stylex.props(styles.child)}>{children}</div>
diff --git a/packages/core/src/Avatar/XDSAvatar.tsx b/packages/core/src/Avatar/XDSAvatar.tsx
index f6d92e6424..6af75bf427 100644
--- a/packages/core/src/Avatar/XDSAvatar.tsx
+++ b/packages/core/src/Avatar/XDSAvatar.tsx
@@ -29,6 +29,7 @@ import {
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {XDSAvatarSizeContext} from './XDSAvatarSizeContext';
+import {xdsClassName, mergeProps} from '../utils';
/**
* The offset ratio for positioning elements on a circle's edge at 45°.
@@ -299,7 +300,10 @@ export const XDSAvatar = forwardRef<HTMLDivElement, XDSAvatarProps>(
role="img"
aria-label={accessibleName}
data-testid={testId}
- {...stylex.props(styles.wrapper, rootOverride)}
+ {...mergeProps(
+ xdsClassName('avatar', {size}),
+ stylex.props(styles.wrapper, rootOverride),
+ )}
{...props}>
<div
{...stylex.props(styles.content, dynamicStyles.size(numericSize))}>
diff --git a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
index 1b62c54283..63f2784772 100644
--- a/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
+++ b/packages/core/src/Avatar/XDSAvatarStatusDot.tsx
@@ -16,6 +16,7 @@ import {useContext, type HTMLAttributes, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
import {XDSAvatarSizeContext} from './XDSAvatarSizeContext';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Resolves the status dot size, border width, and icon size based on the
@@ -166,10 +167,13 @@ export function XDSAvatarStatusDot({
return (
<div
{...(label ? {'aria-label': label} : undefined)}
- {...stylex.props(
- styles.dot,
- variantStyleMap[variant],
- dynamicStyles.size(dotSize, borderWidth),
+ {...mergeProps(
+ xdsClassName('avatar-status-dot', {variant}),
+ stylex.props(
+ styles.dot,
+ variantStyleMap[variant],
+ dynamicStyles.size(dotSize, borderWidth),
+ ),
)}
{...props}>
{icon && iconSize > 0 && (
diff --git a/packages/core/src/Badge/XDSBadge.test.tsx b/packages/core/src/Badge/XDSBadge.test.tsx
index 9f09a7da91..65882a02e1 100644
--- a/packages/core/src/Badge/XDSBadge.test.tsx
+++ b/packages/core/src/Badge/XDSBadge.test.tsx
@@ -47,4 +47,11 @@ describe('XDSBadge', () => {
render(<XDSBadge data-testid="custom-badge">Test</XDSBadge>);
expect(screen.getByTestId('custom-badge')).toBeInTheDocument();
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ const {container} = render(<XDSBadge variant="success">Active</XDSBadge>);
+ const root = container.firstElementChild!;
+ expect(root.className).toContain('xds-badge');
+ expect(root.className).toContain('success');
+ });
});
diff --git a/packages/core/src/Badge/XDSBadge.tsx b/packages/core/src/Badge/XDSBadge.tsx
index 203ddb9b87..9a2c3b02a5 100644
--- a/packages/core/src/Badge/XDSBadge.tsx
+++ b/packages/core/src/Badge/XDSBadge.tsx
@@ -30,6 +30,7 @@ import {
} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Base badge styles
@@ -147,12 +148,15 @@ export const XDSBadge = forwardRef<HTMLSpanElement, XDSBadgeProps>(
return (
<span
ref={ref}
- {...stylex.props(
- styles.base,
- variants[variant],
- rootOverride,
- variantOverride,
- isDot && styles.dot,
+ {...mergeProps(
+ xdsClassName('badge', {variant}),
+ stylex.props(
+ styles.base,
+ variants[variant],
+ rootOverride,
+ variantOverride,
+ isDot && styles.dot,
+ ),
)}
{...props}>
{icon}
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index 49df65bba7..f1279c70f2 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -41,6 +41,7 @@ import {
fontWeightVars,
lineHeightVars,
} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -373,11 +374,14 @@ export const XDSBanner = forwardRef<HTMLDivElement, XDSBannerProps>(
ref={ref}
role={role}
data-testid={testId}
- {...stylex.props(
- styles.root,
- variant === 'card' && styles.card,
- variant === 'section' && styles.section,
- xstyle,
+ {...mergeProps(
+ xdsClassName('banner', {variant}),
+ stylex.props(
+ styles.root,
+ variant === 'card' && styles.card,
+ variant === 'section' && styles.section,
+ xstyle,
+ ),
)}>
{/* Header: colored status background */}
<div
diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx
index 82f426257f..94d16560e9 100644
--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx
+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbItem.tsx
@@ -24,6 +24,7 @@ import {
import {BreadcrumbCtx} from './XDSBreadcrumbs';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Props
@@ -158,9 +159,12 @@ export function XDSBreadcrumbItem({
if (isCurrent) {
return (
<li
- {...stylex.props(
- itemStyles.root,
- isSupporting ? itemStyles.supportingSize : itemStyles.defaultSize,
+ {...mergeProps(
+ xdsClassName('breadcrumb-item'),
+ stylex.props(
+ itemStyles.root,
+ isSupporting ? itemStyles.supportingSize : itemStyles.defaultSize,
+ ),
)}
data-testid={testId}>
<span
@@ -180,9 +184,12 @@ export function XDSBreadcrumbItem({
return (
<li
- {...stylex.props(
- itemStyles.root,
- isSupporting ? itemStyles.supportingSize : itemStyles.defaultSize,
+ {...mergeProps(
+ xdsClassName('breadcrumb-item'),
+ stylex.props(
+ itemStyles.root,
+ isSupporting ? itemStyles.supportingSize : itemStyles.defaultSize,
+ ),
)}
data-testid={testId}>
<LinkComponent
diff --git a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
index 647aeccb05..d244dadc96 100644
--- a/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
+++ b/packages/core/src/Breadcrumbs/XDSBreadcrumbs.tsx
@@ -29,6 +29,7 @@ import {
lineHeightVars,
} from '../theme/tokens.stylex';
import type {XDSBreadcrumbItemProps} from './XDSBreadcrumbItem';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Variant type
@@ -212,7 +213,10 @@ export const XDSBreadcrumbs = forwardRef<HTMLElement, XDSBreadcrumbsProps>(
ref={ref}
aria-label={label}
data-testid={testId}
- {...stylex.props(navStyles.root, xstyle)}>
+ {...mergeProps(
+ xdsClassName('breadcrumbs', {variant}),
+ stylex.props(navStyles.root, xstyle),
+ )}>
<ol {...stylex.props(listStyles.root)}>{rendered}</ol>
</nav>
);
diff --git a/packages/core/src/Button/XDSButton.test.tsx b/packages/core/src/Button/XDSButton.test.tsx
index 25063ac363..729d68284f 100644
--- a/packages/core/src/Button/XDSButton.test.tsx
+++ b/packages/core/src/Button/XDSButton.test.tsx
@@ -195,4 +195,12 @@ describe('XDSButton', () => {
expect(button).toBeDisabled();
expect(button).toHaveAttribute('aria-busy', 'true');
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ render(<XDSButton label="Test" variant="secondary" size="sm" />);
+ const button = screen.getByRole('button');
+ expect(button.className).toContain('xds-button');
+ expect(button.className).toContain('secondary');
+ expect(button.className).toContain('sm');
+ });
});
diff --git a/packages/core/src/Button/XDSButton.tsx b/packages/core/src/Button/XDSButton.tsx
index c9f1753f38..b9c6649266 100644
--- a/packages/core/src/Button/XDSButton.tsx
+++ b/packages/core/src/Button/XDSButton.tsx
@@ -40,6 +40,7 @@ import {XDSSpinner} from '../Spinner';
import type {XDSIconProps} from '../Icon/XDSIcon';
import type {XDSBadgeProps} from '../Badge/XDSBadge';
import {edgeCompensation} from '../Layout/edgeCompensation.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Base button styles
@@ -378,16 +379,19 @@ export const XDSButton = forwardRef<HTMLButtonElement, XDSButtonProps>(
disabled={buttonDisabled}
aria-label={isIconOnly ? label : undefined}
aria-busy={isLoadingState || undefined}
- {...stylex.props(
- styles.base,
- sizeStyles[size],
- variants[variant],
- themeVariantOverride,
- isIconOnly && styles.iconOnly,
- buttonDisabled && styles.disabled,
- isLoadingState && loadingStyles.loading,
- edgePaddingSignal,
- edgeCompStyle,
+ {...mergeProps(
+ xdsClassName('button', {variant, size}),
+ stylex.props(
+ styles.base,
+ sizeStyles[size],
+ variants[variant],
+ themeVariantOverride,
+ isIconOnly && styles.iconOnly,
+ buttonDisabled && styles.disabled,
+ isLoadingState && loadingStyles.loading,
+ edgePaddingSignal,
+ edgeCompStyle,
+ ),
)}
{...props}
onClick={handleClick}>
diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsx
index 60c663139b..a131154cb2 100644
--- a/packages/core/src/Calendar/XDSCalendar.tsx
+++ b/packages/core/src/Calendar/XDSCalendar.tsx
@@ -49,6 +49,7 @@ import {
} from './utils';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -360,7 +361,12 @@ export const XDSCalendar = forwardRef<XDSCalendarHandle, XDSCalendarProps>(
);
return (
- <div {...stylex.props(calendarStyles.calendar, rootOverride)} {...rest}>
+ <div
+ {...mergeProps(
+ xdsClassName('calendar', {mode}),
+ stylex.props(calendarStyles.calendar, rootOverride),
+ )}
+ {...rest}>
{/* Header with navigation */}
<div {...stylex.props(calendarStyles.header)}>
<XDSButton
diff --git a/packages/core/src/Card/XDSCard.test.tsx b/packages/core/src/Card/XDSCard.test.tsx
new file mode 100644
index 0000000000..34578c7d1f
--- /dev/null
+++ b/packages/core/src/Card/XDSCard.test.tsx
@@ -0,0 +1,16 @@
+import {describe, it, expect} from 'vitest';
+import {render} from '@testing-library/react';
+import {XDSCard} from './XDSCard';
+
+describe('XDSCard', () => {
+ it('renders children', () => {
+ const {getByText} = render(<XDSCard>Hello</XDSCard>);
+ expect(getByText('Hello')).toBeInTheDocument();
+ });
+
+ it('renders xds-* class names for theme targeting', () => {
+ const {container} = render(<XDSCard>Content</XDSCard>);
+ const root = container.firstElementChild!;
+ expect(root.className).toContain('xds-card');
+ });
+});
diff --git a/packages/core/src/Card/XDSCard.tsx b/packages/core/src/Card/XDSCard.tsx
index 44bdd649ae..e9883d2706 100644
--- a/packages/core/src/Card/XDSCard.tsx
+++ b/packages/core/src/Card/XDSCard.tsx
@@ -19,6 +19,7 @@ import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {container} from '../Layout/container.stylex';
import type {SizeValue} from '../utils/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register XDSCard's themeable properties
@@ -163,14 +164,17 @@ export const XDSCard = forwardRef<HTMLDivElement, XDSCardProps>(
return (
<div
ref={ref}
- {...stylex.props(
- styles.cardOuter,
- containerOverride,
- dynamicStyles.sizing(
- width ?? null,
- height ?? null,
- maxWidth ?? null,
- minHeight ?? null,
+ {...mergeProps(
+ xdsClassName('card'),
+ stylex.props(
+ styles.cardOuter,
+ containerOverride,
+ dynamicStyles.sizing(
+ width ?? null,
+ height ?? null,
+ maxWidth ?? null,
+ minHeight ?? null,
+ ),
),
)}
{...props}>
diff --git a/packages/core/src/Center/XDSCenter.tsx b/packages/core/src/Center/XDSCenter.tsx
index 77c00ff4bb..87d05e81fd 100644
--- a/packages/core/src/Center/XDSCenter.tsx
+++ b/packages/core/src/Center/XDSCenter.tsx
@@ -23,6 +23,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
import type {SizeValue} from '../utils/types';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
base: {
@@ -132,13 +133,17 @@ export const XDSCenter = forwardRef<HTMLDivElement, XDSCenterProps>(
const themeContext = useContext(ThemeContext);
const rootOverride = themeContext?.theme.components?.center?.root;
- const stylexProps = stylex.props(
- isInline ? styles.inline : styles.base,
- (axis === 'both' || axis === 'vertical') && styles.alignItemsCenter,
- (axis === 'both' || axis === 'horizontal') && styles.justifyContentCenter,
- dynamicStyles.sizing(width ?? null, height ?? null),
- xstyle,
- rootOverride,
+ const stylexProps = mergeProps(
+ xdsClassName('center', {axis}),
+ stylex.props(
+ isInline ? styles.inline : styles.base,
+ (axis === 'both' || axis === 'vertical') && styles.alignItemsCenter,
+ (axis === 'both' || axis === 'horizontal') &&
+ styles.justifyContentCenter,
+ dynamicStyles.sizing(width ?? null, height ?? null),
+ xstyle,
+ rootOverride,
+ ),
);
return (
diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
index f1cdc40bb7..a04ceaefae 100644
--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
@@ -38,6 +38,7 @@ import type {XDSInputStatus} from '../Field/types';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {XDSSpinner} from '../Spinner';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
container: {
@@ -354,7 +355,7 @@ export const XDSCheckboxInput = forwardRef<
describedByParts.length > 0 ? describedByParts.join(' ') : undefined;
return (
- <div>
+ <div className={xdsClassName('checkbox-input', {size})}>
<div
{...stylex.props(
styles.container,
diff --git a/packages/core/src/Collapsible/XDSCollapsible.tsx b/packages/core/src/Collapsible/XDSCollapsible.tsx
index 3ba15d07cb..355d84059b 100644
--- a/packages/core/src/Collapsible/XDSCollapsible.tsx
+++ b/packages/core/src/Collapsible/XDSCollapsible.tsx
@@ -28,6 +28,7 @@ import {
} from '../theme/tokens.stylex';
import {useXDSCollapsible} from './useXDSCollapsible';
import {useXDSIcon} from '../Icon/IconRegistry';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
// Trigger button — full width, flex row, no browser button styling
@@ -176,7 +177,7 @@ export const XDSCollapsible = forwardRef<HTMLDivElement, XDSCollapsibleProps>(
const chevronIcon = useXDSIcon('chevronDown');
return (
- <div ref={ref} {...props}>
+ <div ref={ref} className={xdsClassName('collapsible')} {...props}>
<button
type="button"
onClick={toggle}
diff --git a/packages/core/src/DateInput/XDSDateInput.tsx b/packages/core/src/DateInput/XDSDateInput.tsx
index ddee3d25db..4ea1c72e81 100644
--- a/packages/core/src/DateInput/XDSDateInput.tsx
+++ b/packages/core/src/DateInput/XDSDateInput.tsx
@@ -126,6 +126,7 @@ export type {
} from '../Field';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register component styles with ComponentStyles
@@ -477,14 +478,17 @@ export const XDSDateInput = forwardRef<HTMLInputElement, XDSDateInputProps>(
labelTooltip={labelTooltip}>
<div
ref={popover.triggerRef}
- {...stylex.props(
- inputWrapperStyles.base,
- sizeStyles[size],
- isDisabled && inputWrapperStyles.disabled,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- status && inputStatusFocusWithinStyles[status.type],
- wrapperOverride,
+ {...mergeProps(
+ xdsClassName('date-input', {size}),
+ stylex.props(
+ inputWrapperStyles.base,
+ sizeStyles[size],
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ wrapperOverride,
+ ),
)}>
<button
type="button"
diff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsx
index bbde713a3b..7429297d39 100644
--- a/packages/core/src/Dialog/XDSDialog.tsx
+++ b/packages/core/src/Dialog/XDSDialog.tsx
@@ -30,6 +30,7 @@ import {
} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Dialog variant type
@@ -346,19 +347,22 @@ export const XDSDialog = forwardRef<HTMLDialogElement, XDSDialogProps>(
onClick={handleClick}
onCancel={handleCancel}
aria-modal="true"
- {...stylex.props(
- styles.dialog,
- styles.backdrop,
- !isFullscreen && dynamicStyles.sizing(width, maxHeight),
- hasPosition &&
- dynamicStyles.position(
- position?.top,
- position?.right,
- position?.bottom,
- position?.left,
- ),
- isFullscreen && styles.fullscreen,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('dialog', {variant}),
+ stylex.props(
+ styles.dialog,
+ styles.backdrop,
+ !isFullscreen && dynamicStyles.sizing(width, maxHeight),
+ hasPosition &&
+ dynamicStyles.position(
+ position?.top,
+ position?.right,
+ position?.bottom,
+ position?.left,
+ ),
+ isFullscreen && styles.fullscreen,
+ rootOverride,
+ ),
)}
{...props}>
{children}
diff --git a/packages/core/src/Divider/XDSDivider.test.tsx b/packages/core/src/Divider/XDSDivider.test.tsx
index f8425d697a..562e3ffee9 100644
--- a/packages/core/src/Divider/XDSDivider.test.tsx
+++ b/packages/core/src/Divider/XDSDivider.test.tsx
@@ -97,4 +97,18 @@ describe('XDSDivider', () => {
expect(divider).toHaveAttribute('aria-orientation', 'vertical');
expect(screen.getByText('Vertical')).toBeInTheDocument();
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ render(
+ <XDSDivider
+ variant="strong"
+ orientation="vertical"
+ data-testid="divider"
+ />,
+ );
+ const root = screen.getByTestId('divider');
+ expect(root.className).toContain('xds-divider');
+ expect(root.className).toContain('strong');
+ expect(root.className).toContain('vertical');
+ });
});
diff --git a/packages/core/src/Divider/XDSDivider.tsx b/packages/core/src/Divider/XDSDivider.tsx
index 012505a284..de950e66b8 100644
--- a/packages/core/src/Divider/XDSDivider.tsx
+++ b/packages/core/src/Divider/XDSDivider.tsx
@@ -28,6 +28,7 @@ import {
} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register Divider's style surfaces with ComponentStyles
@@ -174,14 +175,17 @@ export const XDSDivider = forwardRef<HTMLElement, XDSDividerProps>(
ref={ref as React.Ref<HTMLDivElement>}
role="separator"
aria-orientation={orientation}
- {...stylex.props(
- isHorizontal ? baseStyles.horizontal : baseStyles.vertical,
- isFullBleed &&
- (isHorizontal
- ? fullBleedStyles.horizontal
- : fullBleedStyles.vertical),
- rootOverride,
- xstyle,
+ {...mergeProps(
+ xdsClassName('divider', {variant, orientation}),
+ stylex.props(
+ isHorizontal ? baseStyles.horizontal : baseStyles.vertical,
+ isFullBleed &&
+ (isHorizontal
+ ? fullBleedStyles.horizontal
+ : fullBleedStyles.vertical),
+ rootOverride,
+ xstyle,
+ ),
)}
{...props}>
<div
diff --git a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
index c4e4127634..a3cdcae8cf 100644
--- a/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
+++ b/packages/core/src/DropdownMenu/XDSDropdownMenuItem.tsx
@@ -17,6 +17,7 @@ import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
import {XDSText} from '../Text';
import {spacingVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
root: {
@@ -90,7 +91,11 @@ export function XDSDropdownMenuItem({
xstyle,
}: XDSDropdownMenuItemProps) {
return (
- <span {...stylex.props(styles.root, xstyle)}>
+ <span
+ {...mergeProps(
+ xdsClassName('dropdown-menu-item'),
+ stylex.props(styles.root, xstyle),
+ )}>
{icon && <XDSIcon icon={icon} size="sm" color="secondary" />}
<span {...stylex.props(styles.content)}>
{typeof label === 'string' ? (
diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsx
index 1ccfa58241..71b291bb07 100644
--- a/packages/core/src/EmptyState/XDSEmptyState.tsx
+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx
@@ -21,6 +21,7 @@ import {
fontWeightVars,
lineHeightVars,
} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
container: {
@@ -143,10 +144,13 @@ export const XDSEmptyState = forwardRef<HTMLDivElement, XDSEmptyStateProps>(
<div
ref={ref}
role="status"
- {...stylex.props(
- styles.container,
- isCompact && styles.containerCompact,
- xstyle,
+ {...mergeProps(
+ xdsClassName('emptystate'),
+ stylex.props(
+ styles.container,
+ isCompact && styles.containerCompact,
+ xstyle,
+ ),
)}
{...props}>
{icon != null && <div aria-hidden="true">{icon}</div>}
diff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsx
index a559119e3d..db592eeb8a 100644
--- a/packages/core/src/Field/XDSField.tsx
+++ b/packages/core/src/Field/XDSField.tsx
@@ -32,6 +32,7 @@ import {
import type {XDSIconType} from '../Icon';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
container: {
@@ -214,7 +215,10 @@ export const XDSField = forwardRef<HTMLDivElement, XDSFieldProps>(
return (
<div
ref={ref}
- {...stylex.props(styles.container, rootOverride)}
+ {...mergeProps(
+ xdsClassName('field'),
+ stylex.props(styles.container, rootOverride),
+ )}
{...props}>
<XDSFieldLabel
label={label}
diff --git a/packages/core/src/Field/XDSFieldLabel.tsx b/packages/core/src/Field/XDSFieldLabel.tsx
index 2798155e35..007ec92689 100644
--- a/packages/core/src/Field/XDSFieldLabel.tsx
+++ b/packages/core/src/Field/XDSFieldLabel.tsx
@@ -11,6 +11,7 @@
import {forwardRef} from 'react';
import * as stylex from '@stylexjs/stylex';
+import {xdsClassName, mergeProps} from '../utils';
import {
colorVars,
@@ -129,11 +130,14 @@ export const XDSFieldLabel = forwardRef<HTMLLabelElement, XDSFieldLabelProps>(
<label
ref={ref}
htmlFor={inputID}
- {...stylex.props(
- styles.label,
- !isDisabled && styles.labelClickable,
- isDisabled && styles.labelDisabled,
- isLabelHidden && styles.labelHidden,
+ {...mergeProps(
+ xdsClassName('field-label'),
+ stylex.props(
+ styles.label,
+ !isDisabled && styles.labelClickable,
+ isDisabled && styles.labelDisabled,
+ isLabelHidden && styles.labelHidden,
+ ),
)}>
{labelIcon && (
<XDSIcon
diff --git a/packages/core/src/Field/XDSFieldStatus.tsx b/packages/core/src/Field/XDSFieldStatus.tsx
index b0d23af9b7..c670bf55b8 100644
--- a/packages/core/src/Field/XDSFieldStatus.tsx
+++ b/packages/core/src/Field/XDSFieldStatus.tsx
@@ -10,6 +10,7 @@
*/
import * as stylex from '@stylexjs/stylex';
+import {xdsClassName, mergeProps} from '../utils';
import {
colorVars,
lineHeightVars,
@@ -106,10 +107,13 @@ export function XDSFieldStatus({
return (
<div
id={id}
- {...stylex.props(
- styles.base,
- variant === 'attached' ? styles.attached : styles.detached,
- colorStyles[type],
+ {...mergeProps(
+ xdsClassName('field-status', {type, variant}),
+ stylex.props(
+ styles.base,
+ variant === 'attached' ? styles.attached : styles.detached,
+ colorStyles[type],
+ ),
)}>
{message}
</div>
diff --git a/packages/core/src/FormLayout/XDSFormLayout.tsx b/packages/core/src/FormLayout/XDSFormLayout.tsx
index bbdac375f3..a37c193ae1 100644
--- a/packages/core/src/FormLayout/XDSFormLayout.tsx
+++ b/packages/core/src/FormLayout/XDSFormLayout.tsx
@@ -21,6 +21,7 @@ import {
XDSFormLayoutContext,
type XDSFormLayoutDirection,
} from './XDSFormLayoutContext';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Responsive breakpoint for horizontal-labels collapse
@@ -126,11 +127,14 @@ export const XDSFormLayout = forwardRef<HTMLDivElement, XDSFormLayoutProps>(
<XDSFormLayoutContext.Provider value={contextValue}>
<div
ref={ref}
- {...stylex.props(
- styles.base,
- direction === 'horizontal' && styles.horizontal,
- direction === 'horizontal-labels' && styles.horizontalLabels,
- xstyle,
+ {...mergeProps(
+ xdsClassName('form-layout', {direction}),
+ stylex.props(
+ styles.base,
+ direction === 'horizontal' && styles.horizontal,
+ direction === 'horizontal-labels' && styles.horizontalLabels,
+ xstyle,
+ ),
)}
{...props}>
{children}
diff --git a/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap b/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap
index 88225c3c88..5600e69531 100644
--- a/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap
+++ b/packages/core/src/FormLayout/__snapshots__/XDSFormLayout.test.tsx.snap
@@ -2,8 +2,7 @@
exports[`XDSFormLayout > matches snapshot for horizontal direction 1`] = `
<div
- class="XDSFormLayout__styles.base x78zum5 x18g69wz XDSFormLayout__styles.horizontal x1q0g3np x1a02dak"
- data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:36; @xds/core:src/FormLayout/XDSFormLayout.tsx:41"
+ class="xds-form-layout horizontal XDSFormLayout__styles.base x78zum5 x18g69wz XDSFormLayout__styles.horizontal x1q0g3np x1a02dak"
data-testid="layout"
>
<input
@@ -17,8 +16,7 @@ exports[`XDSFormLayout > matches snapshot for horizontal direction 1`] = `
exports[`XDSFormLayout > matches snapshot for horizontal-labels direction 1`] = `
<div
- class="XDSFormLayout__styles.base xdt5ytf XDSFormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
- data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:36; @xds/core:src/FormLayout/XDSFormLayout.tsx:45"
+ class="xds-form-layout horizontal-labels XDSFormLayout__styles.base xdt5ytf XDSFormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
data-testid="layout"
>
<label>
@@ -32,8 +30,7 @@ exports[`XDSFormLayout > matches snapshot for horizontal-labels direction 1`] =
exports[`XDSFormLayout > matches snapshot for vertical direction 1`] = `
<div
- class="XDSFormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
- data-style-src="@xds/core:src/FormLayout/XDSFormLayout.tsx:36"
+ class="xds-form-layout vertical XDSFormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
data-testid="layout"
>
<input
diff --git a/packages/core/src/Grid/XDSGrid.tsx b/packages/core/src/Grid/XDSGrid.tsx
index cc68abe845..67db3f3eca 100644
--- a/packages/core/src/Grid/XDSGrid.tsx
+++ b/packages/core/src/Grid/XDSGrid.tsx
@@ -25,6 +25,7 @@ import type {SpacingScale} from '../Layout';
import type {SizeValue} from '../utils/types';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Grid alignment options for align-items and justify-items.
@@ -402,15 +403,18 @@ export const XDSGrid = forwardRef<HTMLElement, XDSGridProps>(function XDSGrid(
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
- {...stylex.props(
- baseStyles.grid,
- gap != null && gapStyles[gap],
- rowGap != null && rowGapStyles[rowGap],
- columnGap != null && columnGapStyles[columnGap],
- align != null && alignStyles[align],
- justify != null && justifyStyles[justify],
- xstyle,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('grid', {columns, gap, align, justify}),
+ stylex.props(
+ baseStyles.grid,
+ gap != null && gapStyles[gap],
+ rowGap != null && rowGapStyles[rowGap],
+ columnGap != null && columnGapStyles[columnGap],
+ align != null && alignStyles[align],
+ justify != null && justifyStyles[justify],
+ xstyle,
+ rootOverride,
+ ),
)}
style={inlineStyle}
{...props}>
diff --git a/packages/core/src/Grid/XDSGridSpan.tsx b/packages/core/src/Grid/XDSGridSpan.tsx
index 7d7d331730..eafb2bbfb7 100644
--- a/packages/core/src/Grid/XDSGridSpan.tsx
+++ b/packages/core/src/Grid/XDSGridSpan.tsx
@@ -13,6 +13,7 @@
import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
+import {xdsClassName, mergeProps} from '../utils';
export interface XDSGridSpanProps extends Omit<
HTMLAttributes<HTMLElement>,
@@ -81,7 +82,10 @@ export const XDSGridSpan = forwardRef<HTMLElement, XDSGridSpanProps>(
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
- {...stylex.props(baseStyles.span, xstyle)}
+ {...mergeProps(
+ xdsClassName('grid-span'),
+ stylex.props(baseStyles.span, xstyle),
+ )}
style={inlineStyle}
{...props}>
{children}
diff --git a/packages/core/src/Icon/XDSIcon.tsx b/packages/core/src/Icon/XDSIcon.tsx
index 433c152ff7..dec56fb8f9 100644
--- a/packages/core/src/Icon/XDSIcon.tsx
+++ b/packages/core/src/Icon/XDSIcon.tsx
@@ -25,6 +25,7 @@ import {colorVars} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {useXDSIcon, type XDSIconName} from './IconRegistry';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
@@ -207,11 +208,14 @@ export const XDSIcon = forwardRef<SVGSVGElement, XDSIconProps>(
<IconComponent
ref={ref}
aria-hidden="true"
- {...stylex.props(
- styles.root,
- colorStyles[color],
- sizeStyles[size],
- rootOverride,
+ {...mergeProps(
+ xdsClassName('icon', {size, color}),
+ stylex.props(
+ styles.root,
+ colorStyles[color],
+ sizeStyles[size],
+ rootOverride,
+ ),
)}
{...props}
/>
@@ -249,7 +253,10 @@ function IconFromRegistry({
return (
<span
- {...stylex.props(styles.span, colorStyles[color], spanSizeStyles[size])}
+ {...mergeProps(
+ xdsClassName('icon', {size, color}),
+ stylex.props(styles.span, colorStyles[color], spanSizeStyles[size]),
+ )}
aria-hidden="true">
{resolvedIcon}
</span>
diff --git a/packages/core/src/Kbd/XDSKbd.test.tsx b/packages/core/src/Kbd/XDSKbd.test.tsx
index 6603903981..586ac5df7b 100644
--- a/packages/core/src/Kbd/XDSKbd.test.tsx
+++ b/packages/core/src/Kbd/XDSKbd.test.tsx
@@ -55,4 +55,10 @@ describe('XDSKbd', () => {
expect(screen.getByText('\u2318')).toBeInTheDocument();
expect(screen.getByText('K')).toBeInTheDocument();
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ const {container} = render(<XDSKbd keys="k" />);
+ const wrapper = container.firstChild as HTMLElement;
+ expect(wrapper.className).toContain('xds-kbd');
+ });
});
diff --git a/packages/core/src/Kbd/XDSKbd.tsx b/packages/core/src/Kbd/XDSKbd.tsx
index d21eb27f53..e2a42fe29e 100644
--- a/packages/core/src/Kbd/XDSKbd.tsx
+++ b/packages/core/src/Kbd/XDSKbd.tsx
@@ -11,6 +11,7 @@
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
+import {xdsClassName, mergeProps} from '../utils';
import {
colorVars,
spacingVars,
@@ -99,7 +100,9 @@ export function XDSKbd({keys, xstyle}: XDSKbdProps) {
const parts = keys.split('+').map(key => key.trim().toLowerCase());
return (
- <span {...stylex.props(styles.wrapper, xstyle)} aria-hidden="true">
+ <span
+ {...mergeProps(xdsClassName('kbd'), stylex.props(styles.wrapper, xstyle))}
+ aria-hidden="true">
{parts.map((key, i) => (
<kbd key={i} {...stylex.props(styles.kbd)}>
{KEY_DISPLAY[key] ?? key.toUpperCase()}
diff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsx
index 366fffaec7..956c49faf7 100644
--- a/packages/core/src/Layout/XDSLayout.tsx
+++ b/packages/core/src/Layout/XDSLayout.tsx
@@ -21,6 +21,7 @@ import {XDSLayoutAreaContext, type LayoutArea} from './XDSLayoutAreaContext';
import {XDSLayoutSlotsContext, type LayoutSlots} from './XDSLayoutSlotsContext';
import {stack} from '../Stack/stack.stylex';
import {stackItem} from '../Stack/stackItem.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Height behavior for the layout.
@@ -188,9 +189,9 @@ export function XDSLayout({
return (
<XDSLayoutSlotsContext.Provider value={slotsValue}>
<div
- {...stylex.props(
- styles.layoutOuter,
- isFill ? styles.fill : styles.auto,
+ {...mergeProps(
+ xdsClassName('layout', {height}),
+ stylex.props(styles.layoutOuter, isFill ? styles.fill : styles.auto),
)}>
<div
{...stylex.props(
diff --git a/packages/core/src/Layout/XDSLayoutContent.tsx b/packages/core/src/Layout/XDSLayoutContent.tsx
index ff3b2cc400..a83eaad562 100644
--- a/packages/core/src/Layout/XDSLayoutContent.tsx
+++ b/packages/core/src/Layout/XDSLayoutContent.tsx
@@ -17,6 +17,7 @@ import {forwardRef, useContext} from 'react';
import * as stylex from '@stylexjs/stylex';
import {spacingVars} from '../theme/tokens.stylex';
import {XDSLayoutSlotsContext} from './XDSLayoutSlotsContext';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
content: {
@@ -148,15 +149,18 @@ export const XDSLayoutContent = forwardRef<HTMLElement, XDSLayoutContentProps>(
ref={ref as React.Ref<HTMLDivElement>}
role={role}
aria-label={label}
- {...stylex.props(
- styles.content,
- // Outer padding on container edges (unless content is full bleed)
- !hasStart && !isFullBleed && styles.noStart,
- !hasEnd && !isFullBleed && styles.noEnd,
- !hasHeader && !isFullBleed && styles.noHeader,
- !hasFooter && !isFullBleed && styles.noFooter,
- isScrollable && styles.scrollable,
- isFullBleed && styles.fullBleed,
+ {...mergeProps(
+ xdsClassName('layout-content'),
+ stylex.props(
+ styles.content,
+ // Outer padding on container edges (unless content is full bleed)
+ !hasStart && !isFullBleed && styles.noStart,
+ !hasEnd && !isFullBleed && styles.noEnd,
+ !hasHeader && !isFullBleed && styles.noHeader,
+ !hasFooter && !isFullBleed && styles.noFooter,
+ isScrollable && styles.scrollable,
+ isFullBleed && styles.fullBleed,
+ ),
)}
{...props}>
{children}
diff --git a/packages/core/src/Layout/XDSLayoutFooter.tsx b/packages/core/src/Layout/XDSLayoutFooter.tsx
index 7991464537..c33b430fb4 100644
--- a/packages/core/src/Layout/XDSLayoutFooter.tsx
+++ b/packages/core/src/Layout/XDSLayoutFooter.tsx
@@ -14,6 +14,7 @@ import type {AriaRole, HTMLAttributes, ReactNode} from 'react';
import {forwardRef} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
footer: {
@@ -128,12 +129,15 @@ export const XDSLayoutFooter = forwardRef<HTMLElement, XDSLayoutFooterProps>(
ref={ref as React.Ref<HTMLDivElement>}
role={role}
aria-label={label}
- {...stylex.props(
- styles.footer,
- dynamicStyles.sizing(height ?? null),
- isFullBleed && styles.fullBleed,
- hasDivider && styles.divider,
- shouldCollapseSpacing && styles.collapseTop,
+ {...mergeProps(
+ xdsClassName('layout-footer'),
+ stylex.props(
+ styles.footer,
+ dynamicStyles.sizing(height ?? null),
+ isFullBleed && styles.fullBleed,
+ hasDivider && styles.divider,
+ shouldCollapseSpacing && styles.collapseTop,
+ ),
)}
{...props}>
{children}
diff --git a/packages/core/src/Layout/XDSLayoutHeader.tsx b/packages/core/src/Layout/XDSLayoutHeader.tsx
index 1c82b317a7..8871af024c 100644
--- a/packages/core/src/Layout/XDSLayoutHeader.tsx
+++ b/packages/core/src/Layout/XDSLayoutHeader.tsx
@@ -14,6 +14,7 @@ import type {AriaRole, HTMLAttributes, ReactNode} from 'react';
import {forwardRef} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
header: {
@@ -128,12 +129,15 @@ export const XDSLayoutHeader = forwardRef<HTMLElement, XDSLayoutHeaderProps>(
ref={ref as React.Ref<HTMLDivElement>}
role={role}
aria-label={label}
- {...stylex.props(
- styles.header,
- dynamicStyles.sizing(height ?? null),
- isFullBleed && styles.fullBleed,
- hasDivider && styles.divider,
- shouldCollapseSpacing && styles.collapseBottom,
+ {...mergeProps(
+ xdsClassName('layout-header'),
+ stylex.props(
+ styles.header,
+ dynamicStyles.sizing(height ?? null),
+ isFullBleed && styles.fullBleed,
+ hasDivider && styles.divider,
+ shouldCollapseSpacing && styles.collapseBottom,
+ ),
)}
{...props}>
{children}
diff --git a/packages/core/src/Layout/XDSLayoutPanel.tsx b/packages/core/src/Layout/XDSLayoutPanel.tsx
index 7906021573..cfd92be609 100644
--- a/packages/core/src/Layout/XDSLayoutPanel.tsx
+++ b/packages/core/src/Layout/XDSLayoutPanel.tsx
@@ -18,6 +18,7 @@ import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {XDSLayoutAreaContext} from './XDSLayoutAreaContext';
import {XDSLayoutSlotsContext} from './XDSLayoutSlotsContext';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
panel: {
@@ -207,18 +208,21 @@ export const XDSLayoutPanel = forwardRef<HTMLElement, XDSLayoutPanelProps>(
ref={ref as React.Ref<HTMLDivElement>}
role={role}
aria-label={label}
- {...stylex.props(
- styles.panel,
- dynamicStyles.sizing(width ?? null),
- // Outer padding on container edges (unless component is full bleed)
- isStartPanel && !isFullBleed && styles.startPanel,
- isEndPanel && !isFullBleed && styles.endPanel,
- !hasHeader && !isFullBleed && styles.noHeader,
- !hasFooter && !isFullBleed && styles.noFooter,
- isScrollable && styles.scrollable,
- isFullBleed && styles.fullBleed,
- hasDivider && dividerStyle,
- shouldCollapseSpacing && collapseStyle,
+ {...mergeProps(
+ xdsClassName('layout-panel'),
+ stylex.props(
+ styles.panel,
+ dynamicStyles.sizing(width ?? null),
+ // Outer padding on container edges (unless component is full bleed)
+ isStartPanel && !isFullBleed && styles.startPanel,
+ isEndPanel && !isFullBleed && styles.endPanel,
+ !hasHeader && !isFullBleed && styles.noHeader,
+ !hasFooter && !isFullBleed && styles.noFooter,
+ isScrollable && styles.scrollable,
+ isFullBleed && styles.fullBleed,
+ hasDivider && dividerStyle,
+ shouldCollapseSpacing && collapseStyle,
+ ),
)}
{...props}>
{children}
diff --git a/packages/core/src/Link/XDSLink.test.tsx b/packages/core/src/Link/XDSLink.test.tsx
index 7d72b05ca1..cfc09b0858 100644
--- a/packages/core/src/Link/XDSLink.test.tsx
+++ b/packages/core/src/Link/XDSLink.test.tsx
@@ -219,4 +219,15 @@ describe('XDSLink', () => {
expect(link).toHaveAttribute('data-custom-link');
expect(link).not.toHaveAttribute('data-another-link');
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ render(
+ <XDSLink label="Themed" href="/test" color="secondary">
+ Themed Link
+ </XDSLink>,
+ );
+ const link = screen.getByRole('link', {name: 'Themed'});
+ expect(link.className).toContain('xds-link');
+ expect(link.className).toContain('secondary');
+ });
});
diff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsx
index 5f8ff12ee0..b77d55ec1c 100644
--- a/packages/core/src/Link/XDSLink.tsx
+++ b/packages/core/src/Link/XDSLink.tsx
@@ -43,6 +43,7 @@ import type {
} from '../theme/types';
import {useXDSLinkComponent} from './useXDSLinkComponent';
import type {XDSLinkComponentType} from './types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Base link styles
@@ -283,13 +284,16 @@ export const XDSLink = forwardRef<HTMLAnchorElement, XDSLinkProps>(
aria-label={label}
aria-disabled={isDisabled || undefined}
tabIndex={isDisabled ? -1 : undefined}
- {...stylex.props(
- styles.base,
- linkColorStyles[color],
- hasUnderline && styles.hasUnderline,
- isStandalone && styles.standalone,
- isDisabled && styles.disabled,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('link', {color}),
+ stylex.props(
+ styles.base,
+ linkColorStyles[color],
+ hasUnderline && styles.hasUnderline,
+ isStandalone && styles.standalone,
+ isDisabled && styles.disabled,
+ rootOverride,
+ ),
)}
{...props}>
<XDSText
diff --git a/packages/core/src/List/XDSList.tsx b/packages/core/src/List/XDSList.tsx
index 318eb878ae..0ba3b52091 100644
--- a/packages/core/src/List/XDSList.tsx
+++ b/packages/core/src/List/XDSList.tsx
@@ -18,6 +18,7 @@ import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {XDSListContext, type XDSListDensity} from './XDSListContext';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -192,11 +193,14 @@ export const XDSList = forwardRef<
data-testid={testId}
aria-labelledby={header != null ? headerId : undefined}
{...(listStyle === 'none' && !isOrdered ? {role: 'list'} : {})}
- {...stylex.props(
- styles.list,
- listStyleTypes[listStyle],
- hasMarkers && styles.listWithMarkers,
- xstyle,
+ {...mergeProps(
+ xdsClassName('list', {density, listStyle}),
+ stylex.props(
+ styles.list,
+ listStyleTypes[listStyle],
+ hasMarkers && styles.listWithMarkers,
+ xstyle,
+ ),
)}>
{renderedChildren}
</Tag>
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
index 4896bfc2c0..9169304253 100644
--- a/packages/core/src/List/XDSListItem.tsx
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -25,6 +25,7 @@ import {
transitionVars,
} from '../theme/tokens.stylex';
import {XDSListContext} from './XDSListContext';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -350,15 +351,18 @@ export const XDSListItem = forwardRef<HTMLLIElement, XDSListItemProps>(
data-testid={testId}
aria-selected={isSelected || undefined}
aria-disabled={isDisabled || undefined}
- {...stylex.props(
- hasMarkers ? styles.itemWithMarker : styles.item,
- densityStyles[density],
- hasDividers ? styles.noRadius : styles.withRadius,
- isInteractive && styles.interactive,
- isInteractive && styles.focusWithinOutline,
- isDisabled && styles.disabled,
- isSelected && styles.selected,
- xstyle,
+ {...mergeProps(
+ xdsClassName('list-item'),
+ stylex.props(
+ hasMarkers ? styles.itemWithMarker : styles.item,
+ densityStyles[density],
+ hasDividers ? styles.noRadius : styles.withRadius,
+ isInteractive && styles.interactive,
+ isInteractive && styles.focusWithinOutline,
+ isDisabled && styles.disabled,
+ isSelected && styles.selected,
+ xstyle,
+ ),
)}
onClick={isInteractive ? handleContainerClick : undefined}>
{hasMarkers ? (
diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsx
index 4a6d93eba6..a7589d95cf 100644
--- a/packages/core/src/MobileNav/XDSMobileNav.tsx
+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx
@@ -38,6 +38,7 @@ import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {XDSButton} from '../Button';
import {XDSIcon} from '../Icon';
import {XDSHeading} from '../Text/XDSHeading';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
@@ -329,11 +330,14 @@ export const XDSMobileNav = forwardRef<HTMLDialogElement, XDSMobileNavProps>(
aria-label={title ?? 'Navigation'}
onClick={handleDialogClick}
onCancel={handleCancel}
- {...stylex.props(
- styles.dialog,
- styles.backdrop,
- isOpen && styles.backdropOpen,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('mobile-nav', {side}),
+ stylex.props(
+ styles.dialog,
+ styles.backdrop,
+ isOpen && styles.backdropOpen,
+ rootOverride,
+ ),
)}>
{/* Drawer panel */}
<div
diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsx
index 7412d8c4a6..231649473c 100644
--- a/packages/core/src/NavIcon/XDSNavIcon.tsx
+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx
@@ -15,6 +15,7 @@
import {forwardRef, type HTMLAttributes, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars, sizeVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* NavIcon styles
@@ -70,7 +71,10 @@ export interface XDSNavIconProps extends Omit<
export const XDSNavIcon = forwardRef<HTMLSpanElement, XDSNavIconProps>(
function XDSNavIcon({icon, ...props}, ref) {
return (
- <span ref={ref} {...stylex.props(styles.base)} {...props}>
+ <span
+ ref={ref}
+ {...mergeProps(xdsClassName('navicon'), stylex.props(styles.base))}
+ {...props}>
{icon}
</span>
);
diff --git a/packages/core/src/NumberInput/XDSNumberInput.tsx b/packages/core/src/NumberInput/XDSNumberInput.tsx
index e69628307f..2fab8caece 100644
--- a/packages/core/src/NumberInput/XDSNumberInput.tsx
+++ b/packages/core/src/NumberInput/XDSNumberInput.tsx
@@ -101,6 +101,7 @@ export type {
} from '../Field';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register component styles with ComponentStyles
@@ -472,15 +473,18 @@ export const XDSNumberInput = forwardRef<HTMLInputElement, XDSNumberInputProps>(
}
labelTooltip={labelTooltip}>
<div
- {...stylex.props(
- inputWrapperStyles.base,
- styles.wrapper,
- sizeStyles[size],
- isDisabled && inputWrapperStyles.disabled,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- status && inputStatusFocusWithinStyles[status.type],
- wrapperOverride,
+ {...mergeProps(
+ xdsClassName('number-input', {size}),
+ stylex.props(
+ inputWrapperStyles.base,
+ styles.wrapper,
+ sizeStyles[size],
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ wrapperOverride,
+ ),
)}>
{startIcon && <XDSIcon icon={startIcon} size="sm" color="primary" />}
<input
diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsx
index a60e4d26a9..9316107ea3 100644
--- a/packages/core/src/Pagination/XDSPagination.tsx
+++ b/packages/core/src/Pagination/XDSPagination.tsx
@@ -33,6 +33,7 @@ import {XDSButton} from '../Button';
import {XDSIcon} from '../Icon';
import {XDSSelector} from '../Selector';
import {XDSText} from '../Text';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register component styles with ComponentStyles
@@ -504,7 +505,10 @@ export const XDSPagination = forwardRef<HTMLElement, XDSPaginationProps>(
ref={ref}
aria-label={label}
data-testid={testId}
- {...stylex.props(styles.root, rootOverride, xstyle)}>
+ {...mergeProps(
+ xdsClassName('pagination', {variant, size}),
+ stylex.props(styles.root, rootOverride, xstyle),
+ )}>
{pageSizeOptions != null && pageSizeOptions.length > 0 && (
<div {...stylex.props(styles.pageSizeSelector)}>
<div {...stylex.props(styles.pageSizeSelectorControl)}>
diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsx
index 8c1309b58e..a1411e0a1f 100644
--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx
+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx
@@ -25,6 +25,7 @@ import {
lineHeightVars,
transitionVars,
} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Progress bar variant type — maps to semantic color tokens.
@@ -263,7 +264,10 @@ export const XDSProgressBar = forwardRef<HTMLDivElement, XDSProgressBarProps>(
return (
<div
ref={ref}
- {...stylex.props(styles.container, xstyle)}
+ {...mergeProps(
+ xdsClassName('progressbar', {variant, size}),
+ stylex.props(styles.container, xstyle),
+ )}
data-testid={dataTestId}>
{/* Label row */}
{!isLabelHidden || showValueLabel ? (
diff --git a/packages/core/src/RadioList/XDSRadioList.tsx b/packages/core/src/RadioList/XDSRadioList.tsx
index 5677a8cf9c..0d21c34008 100644
--- a/packages/core/src/RadioList/XDSRadioList.tsx
+++ b/packages/core/src/RadioList/XDSRadioList.tsx
@@ -21,6 +21,7 @@ import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {spacingVars} from '../theme/tokens.stylex';
import {XDSField} from '../Field/XDSField';
import type {XDSInputStatus} from '../Field/types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Size of the radio controls, matching CheckboxInput sizes.
@@ -225,10 +226,13 @@ export function XDSRadioList({
}
aria-invalid={status?.type === 'error' ? true : undefined}
aria-required={isRequired || undefined}
- {...stylex.props(
- styles.radiogroup,
- orientation === 'vertical' ? styles.vertical : styles.horizontal,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('radio-list', {orientation, size}),
+ stylex.props(
+ styles.radiogroup,
+ orientation === 'vertical' ? styles.vertical : styles.horizontal,
+ rootOverride,
+ ),
)}>
<RadioListContext.Provider value={contextValue}>
{children}
diff --git a/packages/core/src/RadioList/XDSRadioListItem.tsx b/packages/core/src/RadioList/XDSRadioListItem.tsx
index 4c35d602e7..8b9bc6cddf 100644
--- a/packages/core/src/RadioList/XDSRadioListItem.tsx
+++ b/packages/core/src/RadioList/XDSRadioListItem.tsx
@@ -24,6 +24,7 @@ import {
fontWeightVars,
} from '../theme/tokens.stylex';
import {RadioListContext} from './XDSRadioList';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
container: {
@@ -256,9 +257,9 @@ export function XDSRadioListItem({
return (
<div
data-testid={dataTestId}
- {...stylex.props(
- styles.container,
- !isDisabled && stylex.defaultMarker(),
+ {...mergeProps(
+ xdsClassName('radio-list-item'),
+ stylex.props(styles.container, !isDisabled && stylex.defaultMarker()),
)}>
{startContent && (
<div {...stylex.props(styles.startContent)}>{startContent}</div>
diff --git a/packages/core/src/Section/XDSSection.tsx b/packages/core/src/Section/XDSSection.tsx
index 28d0865113..62adbf0825 100644
--- a/packages/core/src/Section/XDSSection.tsx
+++ b/packages/core/src/Section/XDSSection.tsx
@@ -19,6 +19,7 @@ import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {container} from '../Layout/container.stylex';
import type {SizeValue} from '../utils/types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Visual variant for the section.
@@ -225,15 +226,18 @@ export const XDSSection = forwardRef<HTMLDivElement, XDSSectionProps>(
return (
<div
ref={ref}
- {...stylex.props(
- nestedStyles.outer,
- dynamicStyles.sizing(
- width ?? null,
- height ?? null,
- maxWidth ?? null,
- minHeight ?? null,
+ {...mergeProps(
+ xdsClassName('section', {variant}),
+ stylex.props(
+ nestedStyles.outer,
+ dynamicStyles.sizing(
+ width ?? null,
+ height ?? null,
+ maxWidth ?? null,
+ minHeight ?? null,
+ ),
+ containerOverride,
),
- containerOverride,
)}
{...props}>
<div
diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsx
index d039ae796e..409108d38a 100644
--- a/packages/core/src/Selector/XDSSelector.tsx
+++ b/packages/core/src/Selector/XDSSelector.tsx
@@ -55,6 +55,7 @@ import {useCombobox, useSelectedItemOffset} from './hooks';
import {XDSSelectorOption} from './XDSSelectorOption';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
// Trigger button
@@ -622,14 +623,17 @@ export function XDSSelector<T extends XDSSelectorOptionType>({
onClick={onTriggerClick}
onKeyDown={onKeyDown}
data-testid={testId}
- {...stylex.props(
- styles.trigger,
- sizeStyles[size],
- isDisabled && styles.triggerDisabled,
- !selectedItem && styles.triggerPlaceholder,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- triggerOverride,
+ {...mergeProps(
+ xdsClassName('selector', {size}),
+ stylex.props(
+ styles.trigger,
+ sizeStyles[size],
+ isDisabled && styles.triggerDisabled,
+ !selectedItem && styles.triggerPlaceholder,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ triggerOverride,
+ ),
)}>
<span>{selectedItem?.label ?? placeholder}</span>
{isBusy && <XDSSpinner size="sm" />}
diff --git a/packages/core/src/Selector/XDSSelectorOption.tsx b/packages/core/src/Selector/XDSSelectorOption.tsx
index 45e9d20a14..ffc340b807 100644
--- a/packages/core/src/Selector/XDSSelectorOption.tsx
+++ b/packages/core/src/Selector/XDSSelectorOption.tsx
@@ -11,6 +11,7 @@ import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
import {XDSText} from '../Text';
import {spacingVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
root: {
@@ -86,7 +87,11 @@ export function XDSSelectorOption({
xstyle,
}: XDSSelectorOptionProps) {
return (
- <span {...stylex.props(styles.root, xstyle)}>
+ <span
+ {...mergeProps(
+ xdsClassName('selector-option'),
+ stylex.props(styles.root, xstyle),
+ )}>
{icon && <XDSIcon icon={icon} size="sm" color="secondary" />}
<span {...stylex.props(styles.content)}>
{typeof label === 'string' ? (
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index 53294526cc..b1f07d0982 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -27,6 +27,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
@@ -182,7 +183,10 @@ export const XDSSideNav = forwardRef<HTMLElement, XDSSideNavProps>(
role="navigation"
aria-label="Side navigation"
data-testid={testId}
- {...stylex.props(styles.root, rootOverride, xstyle)}
+ {...mergeProps(
+ xdsClassName('side-nav'),
+ stylex.props(styles.root, rootOverride, xstyle),
+ )}
{...props}>
{hasStickyTop && (
<div {...stylex.props(styles.stickyTop)}>
diff --git a/packages/core/src/SideNav/XDSSideNavHeader.tsx b/packages/core/src/SideNav/XDSSideNavHeader.tsx
index 95eb1bf060..971e77430c 100644
--- a/packages/core/src/SideNav/XDSSideNavHeader.tsx
+++ b/packages/core/src/SideNav/XDSSideNavHeader.tsx
@@ -32,6 +32,7 @@ import {
// of lazy loading layer resources.
import {useXDSPopover} from '../Layer/useXDSPopover';
import {XDSLink} from '../Link';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
@@ -353,11 +354,14 @@ export const XDSSideNavHeader = forwardRef<
ref={ref as React.Ref<HTMLAnchorElement>}
href={titleHref}
data-testid={testId}
- {...stylex.props(
- styles.root,
- styles.interactive,
- styles.interactiveInset,
- xstyle,
+ {...mergeProps(
+ xdsClassName('side-nav-header'),
+ stylex.props(
+ styles.root,
+ styles.interactive,
+ styles.interactiveInset,
+ xstyle,
+ ),
)}
{...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)}>
{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
@@ -377,11 +381,14 @@ export const XDSSideNavHeader = forwardRef<
onClick={handleToggle}
data-testid={testId}
{...popover.triggerProps}
- {...stylex.props(
- styles.root,
- styles.interactive,
- styles.interactiveInset,
- xstyle,
+ {...mergeProps(
+ xdsClassName('side-nav-header'),
+ stylex.props(
+ styles.root,
+ styles.interactive,
+ styles.interactiveInset,
+ xstyle,
+ ),
)}>
{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
{renderTextContent()}
@@ -404,7 +411,10 @@ export const XDSSideNavHeader = forwardRef<
<div
ref={setRef}
data-testid={testId}
- {...stylex.props(styles.root, xstyle)}>
+ {...mergeProps(
+ xdsClassName('side-nav-header'),
+ stylex.props(styles.root, xstyle),
+ )}>
{icon &&
(titleHref ? (
<a href={titleHref} {...stylex.props(styles.icon)}>
@@ -439,7 +449,10 @@ export const XDSSideNavHeader = forwardRef<
<div
ref={ref}
data-testid={testId}
- {...stylex.props(styles.root, xstyle)}
+ {...mergeProps(
+ xdsClassName('side-nav-header'),
+ stylex.props(styles.root, xstyle),
+ )}
{...props}>
{icon &&
(titleHref ? (
@@ -496,7 +509,10 @@ export const XDSSideNavHeader = forwardRef<
<div
ref={ref}
data-testid={testId}
- {...stylex.props(styles.root, xstyle)}
+ {...mergeProps(
+ xdsClassName('side-nav-header'),
+ stylex.props(styles.root, xstyle),
+ )}
{...props}>
{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
{renderTextContent()}
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index 8ed41bd24c..0a88bb3ba0 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -29,6 +29,7 @@ import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
@@ -263,7 +264,11 @@ export const XDSSideNavItem = forwardRef<HTMLElement, XDSSideNavItemProps>(
);
return (
- <div {...stylex.props(styles.root)}>
+ <div
+ {...mergeProps(
+ xdsClassName('side-nav-item'),
+ stylex.props(styles.root),
+ )}>
{itemElement}
{hasChildren && (
<div
diff --git a/packages/core/src/SideNav/XDSSideNavSection.tsx b/packages/core/src/SideNav/XDSSideNavSection.tsx
index b2a46d9f7f..e958b4d3fe 100644
--- a/packages/core/src/SideNav/XDSSideNavSection.tsx
+++ b/packages/core/src/SideNav/XDSSideNavSection.tsx
@@ -24,6 +24,7 @@ import {
fontWeightVars,
lineHeightVars,
} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
// =============================================================================
@@ -174,7 +175,10 @@ export function XDSSideNavSection({
role="group"
aria-labelledby={titleId}
data-testid={testId}
- {...stylex.props(styles.root)}>
+ {...mergeProps(
+ xdsClassName('side-nav-section'),
+ stylex.props(styles.root),
+ )}>
<div
style={isHeaderHidden ? visuallyHiddenStyle : undefined}
{...stylex.props(styles.header)}>
diff --git a/packages/core/src/Skeleton/XDSSkeleton.tsx b/packages/core/src/Skeleton/XDSSkeleton.tsx
index e0c8beb178..36a67fdeee 100644
--- a/packages/core/src/Skeleton/XDSSkeleton.tsx
+++ b/packages/core/src/Skeleton/XDSSkeleton.tsx
@@ -17,6 +17,7 @@ import * as stylex from '@stylexjs/stylex';
import {colorVars, radiusVars} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Animation Timing Constants
@@ -195,13 +196,16 @@ export const XDSSkeleton = forwardRef<HTMLDivElement, XDSSkeletonProps>(
<div
ref={ref}
data-testid={testId}
- {...stylex.props(
- styles.root,
- styles.animate,
- radiusStyles[radiusProp],
- dynamicStyles.dimensions(width, height),
- dynamicStyles.animationDelay(index),
- rootOverride,
+ {...mergeProps(
+ xdsClassName('skeleton'),
+ stylex.props(
+ styles.root,
+ styles.animate,
+ radiusStyles[radiusProp],
+ dynamicStyles.dimensions(width, height),
+ dynamicStyles.animationDelay(index),
+ rootOverride,
+ ),
)}
{...props}
/>
diff --git a/packages/core/src/Spinner/XDSSpinner.tsx b/packages/core/src/Spinner/XDSSpinner.tsx
index 4fc930dd9c..ad5eb87121 100644
--- a/packages/core/src/Spinner/XDSSpinner.tsx
+++ b/packages/core/src/Spinner/XDSSpinner.tsx
@@ -18,6 +18,7 @@ import * as stylex from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Constants
@@ -185,7 +186,10 @@ export const XDSSpinner = forwardRef<HTMLSpanElement, XDSSpinnerProps>(
role="status"
aria-label="Loading"
data-testid={testId}
- {...stylex.props(styles.spinner, rootOverride)}
+ {...mergeProps(
+ xdsClassName('spinner', {size}),
+ stylex.props(styles.spinner, rootOverride),
+ )}
style={{width: frameSize, height: frameSize}}>
<canvas ref={canvasRef} {...stylex.props(styles.canvas)} />
</span>
diff --git a/packages/core/src/Stack/XDSStack.tsx b/packages/core/src/Stack/XDSStack.tsx
index fd5e455df9..4ec99fd8db 100644
--- a/packages/core/src/Stack/XDSStack.tsx
+++ b/packages/core/src/Stack/XDSStack.tsx
@@ -28,6 +28,7 @@ import {
type StackWrap,
type SpacingScale,
} from './stack.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Alignment values accepted by XDSStack.
@@ -168,7 +169,10 @@ export const XDSStack = forwardRef<HTMLElement, XDSStackProps>(
element,
{
ref: ref as Ref<Element>,
- ...stylexProps,
+ ...mergeProps(
+ xdsClassName('stack', {direction, gap, wrap}),
+ stylexProps,
+ ),
...props,
},
children,
diff --git a/packages/core/src/Stack/XDSStackItem.tsx b/packages/core/src/Stack/XDSStackItem.tsx
index b6d95c2f8b..5ca5a02b19 100644
--- a/packages/core/src/Stack/XDSStackItem.tsx
+++ b/packages/core/src/Stack/XDSStackItem.tsx
@@ -25,6 +25,7 @@ import {
type StackItemCrossAlignSelf,
type StackItemSize,
} from './stackItem.stylex';
+import {xdsClassName, mergeProps} from '../utils';
export interface XDSStackItemProps extends Omit<
HTMLAttributes<HTMLElement>,
@@ -90,7 +91,7 @@ export const XDSStackItem = forwardRef<HTMLElement, XDSStackItemProps>(
element,
{
ref: ref as Ref<Element>,
- ...stylexProps,
+ ...mergeProps(xdsClassName('stack-item', {size}), stylexProps),
...props,
},
children,
diff --git a/packages/core/src/StatusDot/XDSStatusDot.tsx b/packages/core/src/StatusDot/XDSStatusDot.tsx
index a219e80ae2..a502a869b7 100644
--- a/packages/core/src/StatusDot/XDSStatusDot.tsx
+++ b/packages/core/src/StatusDot/XDSStatusDot.tsx
@@ -15,6 +15,7 @@ import {forwardRef} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Pulse animation keyframes
@@ -142,13 +143,16 @@ export const XDSStatusDot = forwardRef<HTMLSpanElement, XDSStatusDotProps>(
ref={ref}
role="img"
aria-label={label}
- {...stylex.props(
- styles.base,
- sizes[size],
- variants[variant],
- isPulsing && styles.pulsing,
- isPulsing && styles.reducedMotion,
- xstyle,
+ {...mergeProps(
+ xdsClassName('statusdot', {variant, size}),
+ stylex.props(
+ styles.base,
+ sizes[size],
+ variants[variant],
+ isPulsing && styles.pulsing,
+ isPulsing && styles.reducedMotion,
+ xstyle,
+ ),
)}
{...props}
/>
diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsx
index 8124b79ae9..2cada3d027 100644
--- a/packages/core/src/Switch/XDSSwitch.tsx
+++ b/packages/core/src/Switch/XDSSwitch.tsx
@@ -38,6 +38,7 @@ import type {XDSInputStatus} from '../Field/types';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {XDSSpinner} from '../Spinner';
+import {xdsClassName, mergeProps} from '../utils';
// Fixed dimensions: 40px width, 24px height, 16px thumb (off), 20px thumb (on)
const SWITCH_WIDTH = 40;
@@ -349,12 +350,15 @@ export const XDSSwitch = forwardRef<HTMLInputElement, XDSSwitchProps>(
/>
<div
aria-hidden="true"
- {...stylex.props(
- styles.track,
- isOn ? styles.trackOn : styles.trackOff,
- isDisabled && styles.trackDisabled,
- isDisabled && !isOn && styles.trackDisabledOff,
- trackOverride,
+ {...mergeProps(
+ xdsClassName('switch'),
+ stylex.props(
+ styles.track,
+ isOn ? styles.trackOn : styles.trackOff,
+ isDisabled && styles.trackDisabled,
+ isDisabled && !isOn && styles.trackDisabledOff,
+ trackOverride,
+ ),
)}>
<div
{...stylex.props(
diff --git a/packages/core/src/TabList/XDSTab.tsx b/packages/core/src/TabList/XDSTab.tsx
index 329a64a295..cf93e7a50e 100644
--- a/packages/core/src/TabList/XDSTab.tsx
+++ b/packages/core/src/TabList/XDSTab.tsx
@@ -28,6 +28,7 @@ import {useXDSTabListContext} from './XDSTabListContext';
import type {XDSTabListSize} from './XDSTabListContext';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
+import {xdsClassName, mergeProps} from '../utils';
export interface XDSTabProps {
/**
@@ -199,12 +200,15 @@ export function XDSTab({
const sharedProps = {
'aria-current': isSelected ? ('page' as const) : undefined,
- ...stylex.props(
- styles.base,
- sizeStyles[size],
- isSelected && styles.selected,
- isSelected && styles.underlineSelected,
- !isSelected && stylex.defaultMarker(),
+ ...mergeProps(
+ xdsClassName('tab'),
+ stylex.props(
+ styles.base,
+ sizeStyles[size],
+ isSelected && styles.selected,
+ isSelected && styles.underlineSelected,
+ !isSelected && stylex.defaultMarker(),
+ ),
),
};
diff --git a/packages/core/src/TabList/XDSTabList.tsx b/packages/core/src/TabList/XDSTabList.tsx
index e8db9b3be5..9e5f04f336 100644
--- a/packages/core/src/TabList/XDSTabList.tsx
+++ b/packages/core/src/TabList/XDSTabList.tsx
@@ -19,6 +19,7 @@ import {XDSTabListContext} from './XDSTabListContext';
import type {XDSTabListSize} from './XDSTabListContext';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register component styles with ComponentStyles
@@ -105,10 +106,9 @@ export function XDSTabList({
<XDSTabListContext.Provider value={contextValue}>
<nav
aria-label="Tabs"
- {...stylex.props(
- styles.nav,
- hasDivider && styles.divider,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('tab-list', {size}),
+ stylex.props(styles.nav, hasDivider && styles.divider, rootOverride),
)}>
{children}
</nav>
diff --git a/packages/core/src/Table/XDSBaseTable.tsx b/packages/core/src/Table/XDSBaseTable.tsx
index 5b417609cd..9dbed110d5 100644
--- a/packages/core/src/Table/XDSBaseTable.tsx
+++ b/packages/core/src/Table/XDSBaseTable.tsx
@@ -34,6 +34,7 @@ import {generateColumns, defaultCellRenderer} from './columnUtils';
import {XDSTableRow} from './XDSTableRow';
import {XDSTableCell} from './XDSTableCell';
import {XDSTableHeaderCell} from './XDSTableHeaderCell';
+import {xdsClassName, mergeProps} from '../utils';
const styles = stylex.create({
table: {
@@ -249,7 +250,10 @@ function XDSBaseTableInner<T extends Record<string, unknown>>(
<table
ref={ref}
{...tableRenderProps.htmlProps}
- {...stylex.props(...tableRenderProps.styles)}>
+ {...mergeProps(
+ xdsClassName('base-table'),
+ stylex.props(...tableRenderProps.styles),
+ )}>
{/* thead */}
{hasColumns && (
<thead>
diff --git a/packages/core/src/Table/XDSTableCell.tsx b/packages/core/src/Table/XDSTableCell.tsx
index 87024041fe..dacc666206 100644
--- a/packages/core/src/Table/XDSTableCell.tsx
+++ b/packages/core/src/Table/XDSTableCell.tsx
@@ -21,6 +21,7 @@ import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars, textSizeVars} from '../theme/tokens.stylex';
import type {StyleXStyles} from '../theme/types';
import {XDSTableContext} from './XDSTableContext';
+import {xdsClassName, mergeProps} from '../utils';
/** Props for XDSTableCell — thin `<td>` wrapper */
export interface XDSTableCellProps extends Omit<
@@ -91,7 +92,10 @@ export const XDSTableCell = forwardRef<HTMLTableCellElement, XDSTableCellProps>(
if (!ctx) {
return (
- <td ref={ref} {...props} {...stylex.props(xstyle)}>
+ <td
+ ref={ref}
+ {...props}
+ {...mergeProps(xdsClassName('table-cell'), stylex.props(xstyle))}>
{children}
</td>
);
@@ -116,7 +120,13 @@ export const XDSTableCell = forwardRef<HTMLTableCellElement, XDSTableCellProps>(
}
return (
- <td ref={ref} {...props} {...stylex.props(...cellStyles)}>
+ <td
+ ref={ref}
+ {...props}
+ {...mergeProps(
+ xdsClassName('table-cell'),
+ stylex.props(...cellStyles),
+ )}>
{children}
</td>
);
diff --git a/packages/core/src/Table/XDSTableHeaderCell.tsx b/packages/core/src/Table/XDSTableHeaderCell.tsx
index 1fa49e9005..2bd927e042 100644
--- a/packages/core/src/Table/XDSTableHeaderCell.tsx
+++ b/packages/core/src/Table/XDSTableHeaderCell.tsx
@@ -26,6 +26,7 @@ import {
} from '../theme/tokens.stylex';
import type {StyleXStyles} from '../theme/types';
import {XDSTableContext} from './XDSTableContext';
+import {xdsClassName, mergeProps} from '../utils';
/** Props for XDSTableHeaderCell — `<th>` wrapper with context-aware styling */
export interface XDSTableHeaderCellProps extends ThHTMLAttributes<HTMLTableCellElement> {
@@ -108,7 +109,13 @@ export const XDSTableHeaderCell = forwardRef<
if (!ctx) {
return (
- <th ref={ref} {...props} {...stylex.props(xstyle)}>
+ <th
+ ref={ref}
+ {...props}
+ {...mergeProps(
+ xdsClassName('table-header-cell'),
+ stylex.props(xstyle),
+ )}>
{children}
</th>
);
@@ -133,7 +140,13 @@ export const XDSTableHeaderCell = forwardRef<
}
return (
- <th ref={ref} {...props} {...stylex.props(...cellStyles)}>
+ <th
+ ref={ref}
+ {...props}
+ {...mergeProps(
+ xdsClassName('table-header-cell'),
+ stylex.props(...cellStyles),
+ )}>
{children}
</th>
);
diff --git a/packages/core/src/Table/XDSTableRow.tsx b/packages/core/src/Table/XDSTableRow.tsx
index 709f918c46..39ce8eb686 100644
--- a/packages/core/src/Table/XDSTableRow.tsx
+++ b/packages/core/src/Table/XDSTableRow.tsx
@@ -21,6 +21,7 @@ import * as stylex from '@stylexjs/stylex';
import {colorVars, transitionVars} from '../theme/tokens.stylex';
import type {StyleXStyles} from '../theme/types';
import {XDSTableContext} from './XDSTableContext';
+import {xdsClassName, mergeProps} from '../utils';
/** Props for XDSTableRow — thin `<tr>` wrapper */
export interface XDSTableRowProps extends Omit<
@@ -98,7 +99,10 @@ export const XDSTableRow = forwardRef<HTMLTableRowElement, XDSTableRowProps>(
if (!ctx) {
return (
- <tr ref={ref} {...props} {...stylex.props(xstyle)}>
+ <tr
+ ref={ref}
+ {...props}
+ {...mergeProps(xdsClassName('table-row'), stylex.props(xstyle))}>
{children}
</tr>
);
@@ -125,7 +129,10 @@ export const XDSTableRow = forwardRef<HTMLTableRowElement, XDSTableRowProps>(
}
return (
- <tr ref={ref} {...props} {...stylex.props(...rowStyles)}>
+ <tr
+ ref={ref}
+ {...props}
+ {...mergeProps(xdsClassName('table-row'), stylex.props(...rowStyles))}>
{children}
</tr>
);
diff --git a/packages/core/src/Text/XDSHeading.test.tsx b/packages/core/src/Text/XDSHeading.test.tsx
index 28218ce47e..42784a04f3 100644
--- a/packages/core/src/Text/XDSHeading.test.tsx
+++ b/packages/core/src/Text/XDSHeading.test.tsx
@@ -172,4 +172,11 @@ describe('XDSHeading', () => {
expect(element.tagName).toBe('H2');
});
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ render(<XDSHeading level={2}>Themed Heading</XDSHeading>);
+ const element = screen.getByText('Themed Heading');
+ expect(element.className).toContain('xds-heading');
+ expect(element.className).toContain('level-2');
+ });
});
diff --git a/packages/core/src/Text/XDSHeading.tsx b/packages/core/src/Text/XDSHeading.tsx
index 945c3d13b2..75d21d7f08 100644
--- a/packages/core/src/Text/XDSHeading.tsx
+++ b/packages/core/src/Text/XDSHeading.tsx
@@ -44,6 +44,7 @@ import {
} from './text.stylex';
import {useTruncation} from './useTruncation';
import type {LayerPlacement} from '../Layer';
+import {xdsClassName, mergeProps} from '../utils';
const LazyXDSTooltip = lazy(() =>
import('../Layer/XDSTooltip').then(mod => ({default: mod.XDSTooltip})),
@@ -277,25 +278,28 @@ export const XDSHeading = forwardRef<HTMLHeadingElement, XDSHeadingProps>(
<>
<Component
ref={mergedRef}
- {...stylex.props(
- levelStyle,
- colorStyles[color],
- // Display: use truncation styles when maxLines > 0
- maxLines === 1
- ? truncationStyles.singleLine
- : maxLines > 1
- ? truncationStyles.multiLine
- : displayStyles[resolvedDisplay],
- // Word break when truncating
- maxLines > 0 && wordBreakStyles[resolvedWordBreak],
- // Text wrap
- textWrap && textWrapStyles[textWrap],
- // Capsize
- hasCapsize && capsizeStyles.enabled,
- // Decorations
- hasStrikethrough && decorationStyles.strikethrough,
- // User xstyle
- xstyle,
+ {...mergeProps(
+ xdsClassName('heading', {level}),
+ stylex.props(
+ levelStyle,
+ colorStyles[color],
+ // Display: use truncation styles when maxLines > 0
+ maxLines === 1
+ ? truncationStyles.singleLine
+ : maxLines > 1
+ ? truncationStyles.multiLine
+ : displayStyles[resolvedDisplay],
+ // Word break when truncating
+ maxLines > 0 && wordBreakStyles[resolvedWordBreak],
+ // Text wrap
+ textWrap && textWrapStyles[textWrap],
+ // Capsize
+ hasCapsize && capsizeStyles.enabled,
+ // Decorations
+ hasStrikethrough && decorationStyles.strikethrough,
+ // User xstyle
+ xstyle,
+ ),
)}
style={inlineStyle}
title={tooltipEnabled ? truncation.fullText : undefined}
diff --git a/packages/core/src/Text/XDSText.test.tsx b/packages/core/src/Text/XDSText.test.tsx
index 488586b22d..13ffc1a3d3 100644
--- a/packages/core/src/Text/XDSText.test.tsx
+++ b/packages/core/src/Text/XDSText.test.tsx
@@ -182,4 +182,11 @@ describe('XDSText', () => {
expect(screen.getByText('No tooltip')).toBeInTheDocument();
});
});
+
+ it('renders xds-* class names for theme targeting', () => {
+ render(<XDSText type="body">Themed Text</XDSText>);
+ const element = screen.getByText('Themed Text');
+ expect(element.className).toContain('xds-text');
+ expect(element.className).toContain('body');
+ });
});
diff --git a/packages/core/src/Text/XDSText.tsx b/packages/core/src/Text/XDSText.tsx
index 836a2fb368..990a6a006a 100644
--- a/packages/core/src/Text/XDSText.tsx
+++ b/packages/core/src/Text/XDSText.tsx
@@ -48,6 +48,7 @@ import {
} from './text.stylex';
import {useTruncation} from './useTruncation';
import type {LayerPlacement} from '../Layer';
+import {xdsClassName, mergeProps} from '../utils';
const LazyXDSTooltip = lazy(() =>
import('../Layer/XDSTooltip').then(mod => ({default: mod.XDSTooltip})),
@@ -252,27 +253,30 @@ export const XDSText = forwardRef<HTMLElement, XDSTextProps>(function XDSText(
<>
<Component
ref={mergedRef}
- {...stylex.props(
- typeStyle,
- colorStyles[resolvedColor],
- weight && weightStyles[weight],
- // Display: use truncation styles when maxLines > 0
- maxLines === 1
- ? truncationStyles.singleLine
- : maxLines > 1
- ? truncationStyles.multiLine
- : displayStyles[resolvedDisplay],
- // Word break when truncating
- maxLines > 0 && wordBreakStyles[resolvedWordBreak],
- // Text wrap
- textWrap && textWrapStyles[textWrap],
- // Capsize
- hasCapsize && capsizeStyles.enabled,
- // Decorations
- hasStrikethrough && decorationStyles.strikethrough,
- hasTabularNumbers && tabularNumbersStyle.enabled,
- // User xstyle
- xstyle,
+ {...mergeProps(
+ xdsClassName('text', {type}),
+ stylex.props(
+ typeStyle,
+ colorStyles[resolvedColor],
+ weight && weightStyles[weight],
+ // Display: use truncation styles when maxLines > 0
+ maxLines === 1
+ ? truncationStyles.singleLine
+ : maxLines > 1
+ ? truncationStyles.multiLine
+ : displayStyles[resolvedDisplay],
+ // Word break when truncating
+ maxLines > 0 && wordBreakStyles[resolvedWordBreak],
+ // Text wrap
+ textWrap && textWrapStyles[textWrap],
+ // Capsize
+ hasCapsize && capsizeStyles.enabled,
+ // Decorations
+ hasStrikethrough && decorationStyles.strikethrough,
+ hasTabularNumbers && tabularNumbersStyle.enabled,
+ // User xstyle
+ xstyle,
+ ),
)}
style={inlineStyle}
title={tooltipEnabled ? truncation.fullText : undefined}
diff --git a/packages/core/src/TextInput/XDSTextInput.tsx b/packages/core/src/TextInput/XDSTextInput.tsx
index a2aa8471f2..1977daaba2 100644
--- a/packages/core/src/TextInput/XDSTextInput.tsx
+++ b/packages/core/src/TextInput/XDSTextInput.tsx
@@ -89,6 +89,7 @@ export type {
} from '../Field';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Module Augmentation - Register component styles with ComponentStyles
@@ -284,15 +285,18 @@ export const XDSTextInput = forwardRef<HTMLInputElement, XDSTextInputProps>(
}
labelTooltip={labelTooltip}>
<div
- {...stylex.props(
- inputWrapperStyles.base,
- styles.wrapper,
- sizeStyles[size],
- isDisabled && inputWrapperStyles.disabled,
- status && inputStatusBorderStyles[status.type],
- status && inputStatusHoverShadowStyles[status.type],
- status && inputStatusFocusWithinStyles[status.type],
- wrapperOverride,
+ {...mergeProps(
+ xdsClassName('text-input', {size}),
+ stylex.props(
+ inputWrapperStyles.base,
+ styles.wrapper,
+ sizeStyles[size],
+ isDisabled && inputWrapperStyles.disabled,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ status && inputStatusFocusWithinStyles[status.type],
+ wrapperOverride,
+ ),
)}>
{startIcon && <XDSIcon icon={startIcon} size="sm" color="primary" />}
<input
diff --git a/packages/core/src/Token/XDSToken.tsx b/packages/core/src/Token/XDSToken.tsx
index 8aa4b9271e..d2cfa763a7 100644
--- a/packages/core/src/Token/XDSToken.tsx
+++ b/packages/core/src/Token/XDSToken.tsx
@@ -25,6 +25,7 @@ import {
lineHeightVars,
} from '../theme/tokens.stylex';
import {XDSIcon} from '../Icon';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -354,13 +355,16 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
href={href}
aria-disabled={isDisabled || undefined}
{...sharedProps}
- {...stylex.props(
- styles.base,
- sizeStyles[size],
- colorStyles[color],
- styles.interactive,
- isDisabled && styles.disabled,
- xstyle,
+ {...mergeProps(
+ xdsClassName('token', {color}),
+ stylex.props(
+ styles.base,
+ sizeStyles[size],
+ colorStyles[color],
+ styles.interactive,
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
)}>
{content}
</a>
@@ -379,14 +383,17 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
ref={ref as React.Ref<HTMLSpanElement>}
onClick={isDisabled ? undefined : handleContainerClick}
{...sharedProps}
- {...stylex.props(
- styles.base,
- sizeStyles[size],
- colorStyles[color],
- styles.interactive,
- styles.focusWithinOutline,
- isDisabled && styles.disabled,
- xstyle,
+ {...mergeProps(
+ xdsClassName('token', {color}),
+ stylex.props(
+ styles.base,
+ sizeStyles[size],
+ colorStyles[color],
+ styles.interactive,
+ styles.focusWithinOutline,
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
)}>
{icon}
<button
@@ -424,12 +431,15 @@ export const XDSToken = forwardRef<HTMLElement, XDSTokenProps>(
<span
ref={ref as React.Ref<HTMLSpanElement>}
{...sharedProps}
- {...stylex.props(
- styles.base,
- sizeStyles[size],
- colorStyles[color],
- isDisabled && styles.disabled,
- xstyle,
+ {...mergeProps(
+ xdsClassName('token', {color}),
+ stylex.props(
+ styles.base,
+ sizeStyles[size],
+ colorStyles[color],
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
)}>
{content}
</span>
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 8a0dff0354..46dfd1d9b8 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -24,6 +24,7 @@ import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {ThemeContext} from '../theme/ThemeContext';
import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';
import {edgeSignals} from '../Layout/edgeCompensation.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Base TopNav styles
@@ -164,10 +165,13 @@ export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(
ref={ref}
role="navigation"
aria-label={label}
- {...stylex.props(
- styles.base,
- hasCenterContent ? styles.baseGrid : styles.baseFlex,
- rootOverride,
+ {...mergeProps(
+ xdsClassName('top-nav'),
+ stylex.props(
+ styles.base,
+ hasCenterContent ? styles.baseGrid : styles.baseFlex,
+ rootOverride,
+ ),
)}
{...props}>
<div {...stylex.props(styles.leftSection, edgeSignals.start)}>
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index 2d6ae4fcb8..55995678a6 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -26,6 +26,7 @@ import {
} from '../theme/tokens.stylex';
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
+import {xdsClassName, mergeProps} from '../utils';
/**
* NavItem styles with hover/selected states
@@ -163,11 +164,14 @@ export const XDSTopNavItem = forwardRef<HTMLAnchorElement, XDSTopNavItemProps>(
aria-current={isSelected ? 'page' : undefined}
aria-disabled={isDisabled || undefined}
tabIndex={isDisabled ? -1 : undefined}
- {...stylex.props(
- styles.base,
- isSelected && styles.selected,
- isDisabled && styles.disabled,
- isIconOnly && styles.iconOnly,
+ {...mergeProps(
+ xdsClassName('top-nav-item'),
+ stylex.props(
+ styles.base,
+ isSelected && styles.selected,
+ isDisabled && styles.disabled,
+ isIconOnly && styles.iconOnly,
+ ),
)}
{...props}>
{icon}
diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
index 9ec0bf2d48..681ef1ef4f 100644
--- a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
@@ -28,6 +28,7 @@ import {
elevationVars,
} from '../theme/tokens.stylex';
import {useXDSLayer} from '../Layer';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Styles
@@ -480,7 +481,10 @@ export function XDSTopNavMegaMenu({
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
onKeyDown={handleKeyDown}
- {...stylex.props(styles.wrapper)}>
+ {...mergeProps(
+ xdsClassName('top-nav-mega-menu'),
+ stylex.props(styles.wrapper),
+ )}>
<button
type="button"
aria-haspopup="true"
diff --git a/packages/core/src/TopNav/XDSTopNavTitle.tsx b/packages/core/src/TopNav/XDSTopNavTitle.tsx
index aa7d30670b..eb7b96b5d6 100644
--- a/packages/core/src/TopNav/XDSTopNavTitle.tsx
+++ b/packages/core/src/TopNav/XDSTopNavTitle.tsx
@@ -20,6 +20,7 @@ import {
fontWeightVars,
lineHeightVars,
} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
/**
* Title styles
@@ -102,7 +103,10 @@ export const XDSTopNavTitle = forwardRef<HTMLElement, XDSTopNavTitleProps>(
<Element
ref={ref as React.Ref<HTMLAnchorElement & HTMLDivElement>}
href={href}
- {...stylex.props(styles.base, href != null && styles.clickable)}
+ {...mergeProps(
+ xdsClassName('top-nav-title'),
+ stylex.props(styles.base, href != null && styles.clickable),
+ )}
{...props}>
{logo && <span {...stylex.props(styles.logo)}>{logo}</span>}
{title && <span {...stylex.props(styles.titleText)}>{title}</span>}
diff --git a/packages/core/src/Typeahead/XDSTypeaheadItem.tsx b/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
index b9b588e718..e6e65306ef 100644
--- a/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
+++ b/packages/core/src/Typeahead/XDSTypeaheadItem.tsx
@@ -19,6 +19,7 @@ import {
fontWeightVars,
} from '../theme/tokens.stylex';
import type {XDSSearchableItem} from './types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -136,7 +137,11 @@ export function XDSTypeaheadItem<T extends XDSSearchableItem>({
}
return (
- <div {...stylex.props(styles.container, isDisabled && styles.disabled)}>
+ <div
+ {...mergeProps(
+ xdsClassName('typeahead-item'),
+ stylex.props(styles.container, isDisabled && styles.disabled),
+ )}>
{icon}
<div {...stylex.props(styles.content)}>
<span {...stylex.props(styles.label)}>{item.label}</span>
diff --git a/packages/core/src/utils/index.ts b/packages/core/src/utils/index.ts
index 3de5057a0c..d3c617bb0a 100644
--- a/packages/core/src/utils/index.ts
+++ b/packages/core/src/utils/index.ts
@@ -30,3 +30,7 @@ export {
export type {ISOTimeString, ParsedTime} from './timeParser';
export {parseStyleKey} from './parseStyleKey';
+
+export {xdsClassName} from './xdsClassName';
+
+export {mergeProps} from './mergeProps';
diff --git a/packages/core/src/utils/mergeProps.ts b/packages/core/src/utils/mergeProps.ts
new file mode 100644
index 0000000000..d84345f686
--- /dev/null
+++ b/packages/core/src/utils/mergeProps.ts
@@ -0,0 +1,24 @@
+/**
+ * Merge stylex.props result with an xds-* class name.
+ *
+ * stylex.props() returns { className, style }. This merges the xds-*
+ * class name into the className string so both StyleX styles and the
+ * stable theme-targeting class are applied.
+ *
+ * @example
+ * ```tsx
+ * <div {...mergeProps(
+ * xdsClassName('button', { variant }),
+ * stylex.props(styles.base, variants[variant])
+ * )} />
+ * ```
+ */
+export function mergeProps(
+ xdsClass: string,
+ stylexResult: {className?: string; style?: object},
+): {className: string; style?: object} {
+ const merged = stylexResult.className
+ ? `${xdsClass} ${stylexResult.className}`
+ : xdsClass;
+ return {className: merged, style: stylexResult.style};
+}
diff --git a/packages/core/src/utils/parseStyleKey.ts b/packages/core/src/utils/parseStyleKey.ts
index 3cf8dd379c..0df6bddd6c 100644
--- a/packages/core/src/utils/parseStyleKey.ts
+++ b/packages/core/src/utils/parseStyleKey.ts
@@ -4,6 +4,9 @@
* Used by both defineTheme (CSS generation) and components (class name rendering)
* to ensure the same convention is applied consistently.
*
+ * <!-- SYNC: packages/cli/src/commands/build-theme.mjs (parseStyleKey) -->
+ * <!-- SYNC: packages/core/src/utils/xdsClassName.ts -->
+ *
* Uses class names for visual prop values — shorter HTML, easier to inspect.
* The component class (e.g. .xds-button) disambiguates any value overlaps.
*
diff --git a/packages/core/src/utils/xdsClassName.test.ts b/packages/core/src/utils/xdsClassName.test.ts
new file mode 100644
index 0000000000..526a6debb1
--- /dev/null
+++ b/packages/core/src/utils/xdsClassName.test.ts
@@ -0,0 +1,32 @@
+import {describe, it, expect} from 'vitest';
+import {xdsClassName} from './xdsClassName';
+
+describe('xdsClassName', () => {
+ it('returns base class for component', () => {
+ expect(xdsClassName('card')).toBe('xds-card');
+ });
+
+ it('adds variant classes', () => {
+ expect(xdsClassName('button', {variant: 'secondary', size: 'sm'})).toBe(
+ 'xds-button secondary sm',
+ );
+ });
+
+ it('prefixes numeric values with prop name', () => {
+ expect(xdsClassName('heading', {level: 1})).toBe('xds-heading level-1');
+ });
+
+ it('skips null and undefined props', () => {
+ expect(xdsClassName('button', {variant: 'primary', size: undefined})).toBe(
+ 'xds-button primary',
+ );
+ });
+
+ it('works with no props', () => {
+ expect(xdsClassName('divider')).toBe('xds-divider');
+ });
+
+ it('handles string numeric values', () => {
+ expect(xdsClassName('heading', {level: '3'})).toBe('xds-heading level-3');
+ });
+});
diff --git a/packages/core/src/utils/xdsClassName.ts b/packages/core/src/utils/xdsClassName.ts
new file mode 100644
index 0000000000..1a8335ef93
--- /dev/null
+++ b/packages/core/src/utils/xdsClassName.ts
@@ -0,0 +1,50 @@
+/**
+ * Build the xds-* class name string for a component.
+ *
+ * Every XDS component renders a base class (`xds-button`, `xds-card`, etc.)
+ * plus variant classes derived from visual props. These stable class names
+ * enable CSS-based theming via @scope'd selectors in defineTheme.
+ *
+ * <!-- SYNC: packages/cli/src/commands/build-theme.mjs (parseStyleKey + selector generation) -->
+ * <!-- SYNC: packages/core/src/utils/parseStyleKey.ts -->
+ *
+ * Values starting with a digit get prefixed with the prop name since
+ * CSS class names can't start with a number (e.g. level=1 → "level-1").
+ *
+ * @param component - Component name in lowercase (e.g. 'button', 'card')
+ * @param props - Visual prop values to include as variant classes
+ * @returns Class name string (e.g. "xds-button secondary sm")
+ *
+ * @example
+ * ```ts
+ * xdsClassName('button', { variant: 'secondary', size: 'sm' })
+ * // → "xds-button secondary sm"
+ *
+ * xdsClassName('heading', { level: 1 })
+ * // → "xds-heading level-1"
+ *
+ * xdsClassName('card')
+ * // → "xds-card"
+ * ```
+ */
+export function xdsClassName(
+ component: string,
+ props?: Record<string, string | number | undefined | null>,
+): string {
+ const classes = [`xds-${component}`];
+
+ if (props) {
+ for (const [prop, value] of Object.entries(props)) {
+ if (value == null) continue;
+ const strValue = String(value);
+ // CSS classes can't start with a digit — prefix with prop name
+ if (/^\d/.test(strValue)) {
+ classes.push(`${prop}-${strValue}`);
+ } else {
+ classes.push(strValue);
+ }
+ }
+ }
+
+ return classes.join(' ');
+}