Skip to content

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

TypeScript

feat(theme): sub-element xdsClassName targets + state classes (#763)

Cindy Zhanged45101b073d
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index 9d8cf8f7ba..b7d19a627c 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -66,7 +66,51 @@ export function formatFull(docs) {
if (docs.theming) {
sections.push('## Theming\n');
- sections.push(`Component key: \`${docs.theming.componentKey}\`\n`);
+ const componentKey = docs.name.toLowerCase();
+
+ // Targets table
+ if (docs.theming.targets?.length) {
+ const targetLines = [];
+ targetLines.push('| Class | Variants | States |');
+ targetLines.push('|-------|---------|--------|');
+ for (const t of docs.theming.targets) {
+ const variants = t.visualProps?.length ? t.visualProps.join(', ') : '—';
+ const states = t.states?.length ? t.states.join(', ') : '—';
+ targetLines.push(`| \`${t.className}\` | ${variants} | ${states} |`);
+ }
+ sections.push(targetLines.join('\n') + '\n');
+
+ // Generate defineTheme example with class targeting
+ const exampleLines = ['Override in defineTheme:\n```ts\ncomponents: {'];
+ const rootTarget = docs.theming.targets[0];
+ const rootKey = rootTarget.className.replace('xds-', '');
+ exampleLines.push(` '${rootKey}': {`);
+ exampleLines.push(` base: { /* CSS properties */ },`);
+ if (rootTarget.visualProps?.length) {
+ const firstVariant = rootTarget.visualProps[0];
+ exampleLines.push(` '${firstVariant}:value': { /* variant-specific */ },`);
+ }
+ if (rootTarget.states?.length) {
+ const firstState = rootTarget.states[0];
+ exampleLines.push(` '${firstState}': { /* state-specific */ },`);
+ }
+ exampleLines.push(` },`);
+ // Show sub-element example if there are multiple targets
+ if (docs.theming.targets.length > 1) {
+ const subTarget = docs.theming.targets[1];
+ const subKey = subTarget.className.replace('xds-', '');
+ exampleLines.push(` '${subKey}': {`);
+ exampleLines.push(` base: { /* CSS properties */ },`);
+ if (subTarget.states?.length) {
+ const firstState = subTarget.states[0];
+ exampleLines.push(` '${firstState}': { /* state-specific */ },`);
+ }
+ exampleLines.push(` },`);
+ }
+ exampleLines.push('}\n```\n');
+ sections.push(exampleLines.join('\n'));
+ }
+
if (docs.theming.surfaces?.length) {
const surfaceLines = [];
surfaceLines.push('| Surface | Description |');
@@ -89,12 +133,11 @@ export function formatFull(docs) {
}
sections.push(varLines.join('\n') + '\n');
- // Show override example
+ // Show var override example
const overridableVars = docs.theming.vars.filter(v => !v.derived);
if (overridableVars.length > 0) {
- const componentKey = docs.name.toLowerCase();
const exampleVar = overridableVars[0];
- sections.push('Override in defineTheme:\n```tsx\ncomponents: {\n ' + componentKey + ': {\n base: { \'' + exampleVar.name + '\': \'...\' },\n },\n}\n```\n');
+ sections.push('Override CSS vars in defineTheme:\n```ts\ncomponents: {\n ' + componentKey + ': {\n base: { \'' + exampleVar.name + '\': \'...\' },\n },\n}\n```\n');
}
}
}
@@ -257,6 +300,17 @@ export function formatBrief(docs, componentName, importHint) {
}
}
+ // Theme targets (class names, variants, states)
+ if (docs.theming?.targets?.length) {
+ const targetParts = docs.theming.targets.map(t => {
+ const parts = [t.className];
+ if (t.visualProps?.length) parts.push(`variants: ${t.visualProps.join(', ')}`);
+ if (t.states?.length) parts.push(`states: ${t.states.join(', ')}`);
+ return parts.join(' ');
+ });
+ output.push(` Targets: ${targetParts.join(' | ')}`);
+ }
+
// Other props
if (otherProps.length > 0) {
output.push(` ${otherProps.join(' · ')}`);
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index fa222295b3..f1f03b5d5b 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -118,6 +118,7 @@ export const docs = {
theming: {
targets: [
{className: 'xds-banner', visualProps: ['variant']},
+ {className: 'xds-banner-icon', visualProps: ['status']},
],
vars: [
{name: '--banner-radius', description: 'Border radius (card variant only)', default: 'var(--radius-3)'},
@@ -247,6 +248,7 @@ export const docsZh = {
theming: {
targets: [
{className: 'xds-banner', visualProps: ['variant']},
+ {className: 'xds-banner-icon', visualProps: ['status']},
],
vars: [
{name: '--banner-radius', description: 'Border radius (card variant only)', default: 'var(--radius-3)'},
diff --git a/packages/core/src/Banner/XDSBanner.tsx b/packages/core/src/Banner/XDSBanner.tsx
index c59d68f9c9..8e5219c840 100644
--- a/packages/core/src/Banner/XDSBanner.tsx
+++ b/packages/core/src/Banner/XDSBanner.tsx
@@ -423,7 +423,12 @@ export function XDSBanner({
isSingleLine && styles.headerCentered,
statusStyles[status],
)}>
- <div {...stylex.props(styles.iconWrapper)} aria-hidden="true">
+ <div
+ {...mergeProps(
+ xdsClassName('banner-icon', {status}),
+ stylex.props(styles.iconWrapper),
+ )}
+ aria-hidden="true">
{icon != null ? (
icon
) : (
diff --git a/packages/core/src/Calendar/Calendar.doc.mjs b/packages/core/src/Calendar/Calendar.doc.mjs
index 67f0156aba..0962d92b2a 100644
--- a/packages/core/src/Calendar/Calendar.doc.mjs
+++ b/packages/core/src/Calendar/Calendar.doc.mjs
@@ -119,6 +119,7 @@ export const docs = {
theming: {
targets: [
{className: 'xds-calendar', visualProps: ['mode']},
+ {className: 'xds-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},
],
},
notes: [
@@ -248,6 +249,7 @@ export const docsZh = {
theming: {
targets: [
{className: 'xds-calendar', visualProps: ['mode']},
+ {className: 'xds-calendar-day', states: ['selected', 'today', 'disabled', 'in-range']},
],
},
notes: [
diff --git a/packages/core/src/Calendar/XDSCalendar.tsx b/packages/core/src/Calendar/XDSCalendar.tsx
index 9370ddce18..5a3e026e4f 100644
--- a/packages/core/src/Calendar/XDSCalendar.tsx
+++ b/packages/core/src/Calendar/XDSCalendar.tsx
@@ -812,21 +812,33 @@ function DayCell({
onClick={() => !isDisabled && onDayClick(date)}
onMouseEnter={() => !isDisabled && onDayHover(date)}
onMouseLeave={() => onDayHover(null)}
- {...stylex.props(
- dayCellStyles.day,
- dayCellTheme.day,
- isOutside && dayCellStyles.dayOutside,
- isOutside && dayCellTheme.dayOutside,
- isToday && !isSelected && !isInRange && dayCellStyles.dayToday,
- isToday && !isSelected && !isInRange && dayCellTheme.dayToday,
- isToday && !isSelected && isInRange && dayCellStyles.dayTodayInRange,
- isToday && !isSelected && isInRange && dayCellTheme.dayTodayInRange,
- (isSelected || isRangeStart || isRangeEnd) &&
- dayCellStyles.daySelected,
- (isSelected || isRangeStart || isRangeEnd) &&
- dayCellTheme.daySelected,
- isDisabled && dayCellStyles.dayDisabled,
- isDisabled && dayCellTheme.dayDisabled,
+ {...mergeProps(
+ xdsClassName('calendar-day', {
+ selected:
+ isSelected || isRangeStart || isRangeEnd ? 'selected' : null,
+ today: isToday ? 'today' : null,
+ disabled: isDisabled ? 'disabled' : null,
+ 'in-range': isInRange ? 'in-range' : null,
+ }),
+ stylex.props(
+ dayCellStyles.day,
+ dayCellTheme.day,
+ isOutside && dayCellStyles.dayOutside,
+ isOutside && dayCellTheme.dayOutside,
+ isToday && !isSelected && !isInRange && dayCellStyles.dayToday,
+ isToday && !isSelected && !isInRange && dayCellTheme.dayToday,
+ isToday &&
+ !isSelected &&
+ isInRange &&
+ dayCellStyles.dayTodayInRange,
+ isToday && !isSelected && isInRange && dayCellTheme.dayTodayInRange,
+ (isSelected || isRangeStart || isRangeEnd) &&
+ dayCellStyles.daySelected,
+ (isSelected || isRangeStart || isRangeEnd) &&
+ dayCellTheme.daySelected,
+ isDisabled && dayCellStyles.dayDisabled,
+ isDisabled && dayCellTheme.dayDisabled,
+ ),
)}>
{dayNumber}
</button>
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index 75897cd22f..7f6fb327d4 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -188,7 +188,7 @@ export const docs = {
theming: {
targets: [
{className: 'xds-checkbox-input', visualProps: ['size']},
- {className: 'xds-checkbox'},
+ {className: 'xds-checkbox', states: ['checked', 'disabled']},
],
},
notes: [
@@ -384,7 +384,7 @@ export const docsZh = {
theming: {
targets: [
{className: 'xds-checkbox-input', visualProps: ['size']},
- {className: 'xds-checkbox'},
+ {className: 'xds-checkbox', states: ['checked', 'disabled']},
],
},
notes: [
diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
index 24a1d01aca..7bb21b92c6 100644
--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx
@@ -383,7 +383,10 @@ export function XDSCheckboxInput({
<div
aria-hidden="true"
{...mergeProps(
- xdsClassName('checkbox'),
+ xdsClassName('checkbox', {
+ checked: isCheckedOrIndeterminate ? 'checked' : null,
+ disabled: isDisabled ? 'disabled' : null,
+ }),
stylex.props(
styles.checkbox,
checkboxSizeStyles[size],
@@ -431,8 +434,7 @@ export function XDSCheckboxInput({
)}
</div>
</div>
- <div
- {...stylex.props(styles.labelWrapper)}>
+ <div {...stylex.props(styles.labelWrapper)}>
<XDSFieldLabel
label={label}
inputID={id}
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index 2495f3e8e5..923732c3ac 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -111,6 +111,7 @@ export const docs = {
theming: {
targets: [
{className: 'xds-progressbar', visualProps: ['size', 'variant']},
+ {className: 'xds-progressbar-fill', visualProps: ['variant']},
],
},
accessibility: [
@@ -234,6 +235,7 @@ export const docsZh = {
theming: {
targets: [
{className: 'xds-progressbar', visualProps: ['size', 'variant']},
+ {className: 'xds-progressbar-fill', visualProps: ['variant']},
],
},
accessibility: [
diff --git a/packages/core/src/ProgressBar/XDSProgressBar.tsx b/packages/core/src/ProgressBar/XDSProgressBar.tsx
index 3b36fa7ed6..b892029288 100644
--- a/packages/core/src/ProgressBar/XDSProgressBar.tsx
+++ b/packages/core/src/ProgressBar/XDSProgressBar.tsx
@@ -336,11 +336,17 @@ export function XDSProgressBar({
{...stylex.props(styles.track, sizeStyles[size])}>
{isIndeterminate ? (
<div
- {...stylex.props(styles.indeterminateFill, variantStyles[variant])}
+ {...mergeProps(
+ xdsClassName('progressbar-fill', {variant}),
+ stylex.props(styles.indeterminateFill, variantStyles[variant]),
+ )}
/>
) : (
<div
- {...stylex.props(styles.fill, variantStyles[variant])}
+ {...mergeProps(
+ xdsClassName('progressbar-fill', {variant}),
+ stylex.props(styles.fill, variantStyles[variant]),
+ )}
style={{width: `${percentage}%`}}
/>
)}
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index 6807397afd..4ea22ca511 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -88,6 +88,8 @@ export const docs = {
targets: [
{className: 'xds-radio-list', visualProps: ['orientation', 'size']},
{className: 'xds-radio-list-item'},
+ {className: 'xds-radio', visualProps: ['size'], states: ['checked', 'disabled']},
+ {className: 'xds-radio-dot', visualProps: ['size']},
],
},
notes: [
@@ -340,6 +342,8 @@ export const docsZh = {
targets: [
{className: 'xds-radio-list', visualProps: ['orientation', 'size']},
{className: 'xds-radio-list-item'},
+ {className: 'xds-radio', visualProps: ['size'], states: ['checked', 'disabled']},
+ {className: 'xds-radio-dot', visualProps: ['size']},
],
},
notes: [
diff --git a/packages/core/src/RadioList/XDSRadioListItem.tsx b/packages/core/src/RadioList/XDSRadioListItem.tsx
index 2aa69b32d7..8fb652689c 100644
--- a/packages/core/src/RadioList/XDSRadioListItem.tsx
+++ b/packages/core/src/RadioList/XDSRadioListItem.tsx
@@ -290,15 +290,27 @@ export function XDSRadioListItem({
/>
<div
aria-hidden="true"
- {...stylex.props(
- styles.radio,
- radioSizeStyles[size],
- isChecked ? styles.radioChecked : styles.radioUnchecked,
- isDisabled && styles.radioDisabled,
- isDisabled && !isChecked && styles.radioDisabledUnchecked,
+ {...mergeProps(
+ xdsClassName('radio', {
+ size,
+ checked: isChecked ? 'checked' : null,
+ disabled: isDisabled ? 'disabled' : null,
+ }),
+ stylex.props(
+ styles.radio,
+ radioSizeStyles[size],
+ isChecked ? styles.radioChecked : styles.radioUnchecked,
+ isDisabled && styles.radioDisabled,
+ isDisabled && !isChecked && styles.radioDisabledUnchecked,
+ ),
)}>
{isChecked && (
- <div {...stylex.props(styles.innerDot, dotSizeStyles[size])} />
+ <div
+ {...mergeProps(
+ xdsClassName('radio-dot', {size}),
+ stylex.props(styles.innerDot, dotSizeStyles[size]),
+ )}
+ />
)}
</div>
</div>
diff --git a/packages/core/src/Slider/Slider.doc.mjs b/packages/core/src/Slider/Slider.doc.mjs
index 34bca4e618..f6b13f2e80 100644
--- a/packages/core/src/Slider/Slider.doc.mjs
+++ b/packages/core/src/Slider/Slider.doc.mjs
@@ -221,6 +221,13 @@ export const docs = {
'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.',
},
],
+ theming: {
+ targets: [
+ {className: 'xds-slider', visualProps: ['orientation']},
+ {className: 'xds-slider-track', visualProps: ['orientation']},
+ {className: 'xds-slider-thumb', visualProps: ['orientation']},
+ ],
+ },
accessibility: [
'Uses `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, and `aria-valuetext` on each thumb.',
'The label is always rendered in the DOM for accessibility even when `isLabelHidden` is true.',
@@ -460,6 +467,13 @@ export const docsZh = {
'用于布局自定义的 StyleX 样式(边距、定位、尺寸)。必须是 stylex.create() 的值,而非内联样式对象如 style={{}}。',
},
],
+ theming: {
+ targets: [
+ {className: 'xds-slider', visualProps: ['orientation']},
+ {className: 'xds-slider-track', visualProps: ['orientation']},
+ {className: 'xds-slider-thumb', visualProps: ['orientation']},
+ ],
+ },
accessibility: [
'每个滑块使用 `role="slider"`,配合 `aria-valuenow`、`aria-valuemin`、`aria-valuemax` 和 `aria-valuetext`。',
'即使 `isLabelHidden` 为 true,标签也始终在 DOM 中渲染以确保无障碍可访问性。',
diff --git a/packages/core/src/Slider/XDSSlider.tsx b/packages/core/src/Slider/XDSSlider.tsx
index 1166f2c556..1efced8b1b 100644
--- a/packages/core/src/Slider/XDSSlider.tsx
+++ b/packages/core/src/Slider/XDSSlider.tsx
@@ -34,6 +34,7 @@ import {
import {XDSField} from '../Field/XDSField';
import {XDSTooltip} from '../Tooltip/XDSTooltip';
import type {XDSInputStatus} from '../Field/types';
+import {xdsClassName, mergeProps} from '../utils';
// =============================================================================
// Types
@@ -574,12 +575,15 @@ export function XDSSlider({ref, ...props}: XDSSliderProps) {
aria-describedby={ariaDescribedBy}
style={positionStyle}
onKeyDown={e => handleKeyDown(thumbIndex, e)}
- {...stylex.props(
- styles.thumb,
- isHorizontal ? styles.thumbHorizontal : styles.thumbVertical,
- !isDisabled && styles.thumbHover,
- !isDisabled && styles.thumbFocusWithin,
- isDisabled && styles.thumbDisabled,
+ {...mergeProps(
+ xdsClassName('slider-thumb', {orientation}),
+ stylex.props(
+ styles.thumb,
+ isHorizontal ? styles.thumbHorizontal : styles.thumbVertical,
+ !isDisabled && styles.thumbHover,
+ !isDisabled && styles.thumbFocusWithin,
+ isDisabled && styles.thumbDisabled,
+ ),
)}
/>
);
@@ -652,7 +656,11 @@ export function XDSSlider({ref, ...props}: XDSSliderProps) {
xstyle={xstyle}
className={className}
style={style}>
- <div {...stylex.props(styles.sliderRow)}>
+ <div
+ {...mergeProps(
+ xdsClassName('slider', {orientation}),
+ stylex.props(styles.sliderRow),
+ )}>
<div
ref={node => {
// Merge refs
@@ -678,9 +686,12 @@ export function XDSSlider({ref, ...props}: XDSSliderProps) {
)}>
{/* Background track */}
<div
- {...stylex.props(
- styles.track,
- isHorizontal ? styles.trackHorizontal : styles.trackVertical,
+ {...mergeProps(
+ xdsClassName('slider-track', {orientation}),
+ stylex.props(
+ styles.track,
+ isHorizontal ? styles.trackHorizontal : styles.trackVertical,
+ ),
)}
/>
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index 0a07d91814..35c6a16283 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -188,7 +188,8 @@ export const docs = {
],
theming: {
targets: [
- {className: 'xds-switch'},
+ {className: 'xds-switch', states: ['checked', 'disabled']},
+ {className: 'xds-switch-thumb', states: ['checked']},
{className: 'xds-switch-field', visualProps: ['labelPosition', 'labelSpacing']},
],
},
@@ -400,7 +401,8 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'xds-switch'},
+ {className: 'xds-switch', states: ['checked', 'disabled']},
+ {className: 'xds-switch-thumb', states: ['checked']},
{className: 'xds-switch-field', visualProps: ['labelPosition', 'labelSpacing']},
],
},
diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsx
index 27cc4a3744..596cad0a15 100644
--- a/packages/core/src/Switch/XDSSwitch.tsx
+++ b/packages/core/src/Switch/XDSSwitch.tsx
@@ -351,7 +351,10 @@ export function XDSSwitch({
<div
aria-hidden="true"
{...mergeProps(
- xdsClassName('switch'),
+ xdsClassName('switch', {
+ checked: isOn ? 'checked' : null,
+ disabled: isDisabled ? 'disabled' : null,
+ }),
stylex.props(
styles.track,
isOn ? styles.trackOn : styles.trackOff,
@@ -361,9 +364,9 @@ export function XDSSwitch({
),
)}>
<div
- {...stylex.props(
- styles.thumb,
- isOn ? styles.thumbOn : styles.thumbOff,
+ {...mergeProps(
+ xdsClassName('switch-thumb', {checked: isOn ? 'checked' : null}),
+ stylex.props(styles.thumb, isOn ? styles.thumbOn : styles.thumbOff),
)}>
{isBusy && <XDSSpinner size="sm" />}
</div>
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index 1b9f9e4df5..da927b9820 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -91,6 +91,12 @@ export interface ThemingTarget {
* Themes can target specific variants via `.xds-button.secondary`.
* Omit if the component has no visual props (class name only). */
visualProps?: string[];
+ /** State class names that appear on this element based on component state.
+ * Unlike visualProps (driven by props), these reflect runtime state
+ * (checked, selected, today, on, expanded, etc.).
+ * Themes target them the same way as variants: `.xds-radio.checked { ... }`
+ * Omit if the element has no state-driven classes. */
+ states?: string[];
}
/**