Skip to content

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

TypeScript

feat(theme): pseudo-class selectors in defineTheme component overrides (#811)

Cindy Zhangdb98e6bceebc
diff --git a/packages/cli/src/commands/build-theme.mjs b/packages/cli/src/commands/build-theme.mjs
index f7ac192a90..c69f86dc1e 100644
--- a/packages/cli/src/commands/build-theme.mjs
+++ b/packages/cli/src/commands/build-theme.mjs
@@ -182,23 +182,52 @@ function generateCSS(themeDef, {prose = true} = {}) {
const entries = Object.entries(styles);
if (entries.length > 0) {
const suffix = parseStyleKey(key);
- const declarations = entries
- .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
- .join('\n');
+
+ // Separate regular properties from pseudo-class overrides
+ const props = [];
+ const pseudos = [];
+
+ for (const [prop, value] of entries) {
+ if (prop.startsWith(':') && typeof value === 'object') {
+ pseudos.push([prop, value]);
+ } else {
+ props.push([prop, value]);
+ }
+ }
// Build selector — co-select HTML elements for prose-related components
const xdsSelector = `.xds-${component}${suffix}`;
- let selector = ` ${xdsSelector}`;
+ let baseSelector = ` ${xdsSelector}`;
if (prose) {
const htmlElements = PROSE_COMPONENT_MAP[component]?.[key];
if (htmlElements) {
const htmlSelector = htmlElements.map(el => ` ${el}`).join(',\n');
- selector = ` ${xdsSelector},\n${htmlSelector}`;
+ baseSelector = ` ${xdsSelector},\n${htmlSelector}`;
}
}
- parts.push(`${selector} {\n${declarations}\n }`);
+ // Emit base rule
+ if (props.length > 0) {
+ const declarations = props
+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
+ .join('\n');
+ parts.push(`${baseSelector} {\n${declarations}\n }`);
+ }
+
+ // Emit pseudo-class rules
+ for (const [pseudo, pseudoStyles] of pseudos) {
+ const pseudoEntries = Object.entries(pseudoStyles);
+ if (pseudoEntries.length > 0) {
+ const declarations = pseudoEntries
+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
+ .join('\n');
+ // Pseudo-class rules only on xds selector, not prose co-selection
+ parts.push(
+ ` ${xdsSelector}${pseudo} {\n${declarations}\n }`,
+ );
+ }
+ }
}
}
}
diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.ts
index 0476a4e241..9f6d553697 100644
--- a/packages/core/src/theme/defineTheme.test.ts
+++ b/packages/core/src/theme/defineTheme.test.ts
@@ -747,3 +747,96 @@ describe('typography weight derivation', () => {
expect(theme.tokens['--heading-1-weight']).toBe('900');
});
});
+
+describe('pseudo-class overrides in components', () => {
+ it('generates pseudo-class rules from nested objects', () => {
+ const theme = defineTheme({
+ name: 'pseudo',
+ components: {
+ radio: {
+ base: {
+ borderColor: '#8F9296',
+ ':hover': {
+ borderColor: 'color-mix(in srgb, #8F9296, black 20%)',
+ },
+ },
+ },
+ },
+ });
+ const css = generateThemeCSS(theme);
+ // Base rule
+ expect(css).toContain('.xds-radio {');
+ expect(css).toContain('border-color: #8F9296');
+ // Pseudo rule — separate selector
+ expect(css).toContain('.xds-radio:hover {');
+ expect(css).toContain(
+ 'border-color: color-mix(in srgb, #8F9296, black 20%)',
+ );
+ });
+
+ it('generates pseudo-class rules on variant selectors', () => {
+ const theme = defineTheme({
+ name: 'pseudo-variant',
+ components: {
+ button: {
+ 'variant:primary-muted': {
+ backgroundColor: '#ECF5FF',
+ ':hover': {
+ backgroundColor: '#D6EBFF',
+ },
+ ':focus-visible': {
+ outline: '2px solid var(--color-ring-focus)',
+ },
+ },
+ },
+ },
+ });
+ const css = generateThemeCSS(theme);
+ expect(css).toContain('.xds-button.primary-muted {');
+ expect(css).toContain('background-color: #ECF5FF');
+ expect(css).toContain('.xds-button.primary-muted:hover {');
+ expect(css).toContain('background-color: #D6EBFF');
+ expect(css).toContain('.xds-button.primary-muted:focus-visible {');
+ expect(css).toContain('outline: 2px solid var(--color-ring-focus)');
+ });
+
+ it('handles pseudo-only overrides (no base properties)', () => {
+ const theme = defineTheme({
+ name: 'pseudo-only',
+ components: {
+ switch: {
+ base: {
+ ':hover': {
+ backgroundColor: 'color-mix(in srgb, #8F9296, black 5%)',
+ },
+ },
+ },
+ },
+ });
+ const css = generateThemeCSS(theme);
+ // Should NOT emit an empty base rule
+ expect(css).not.toMatch(/\.xds-switch\s*\{\s*\}/);
+ // Should emit the pseudo rule
+ expect(css).toContain('.xds-switch:hover {');
+ });
+
+ it('keeps non-pseudo string values as regular properties', () => {
+ const theme = defineTheme({
+ name: 'mixed',
+ components: {
+ card: {
+ base: {
+ borderWidth: '2px',
+ borderColor: 'var(--color-accent)',
+ },
+ },
+ },
+ });
+ const css = generateThemeCSS(theme);
+ expect(css).toContain('.xds-card {');
+ expect(css).toContain('border-width: 2px');
+ expect(css).toContain('border-color: var(--color-accent)');
+ // No pseudo rules
+ expect(css).not.toContain('.xds-card:');
+ });
+});
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index f49c33363c..ad880ff6c8 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -94,9 +94,24 @@ export type XDSTokenValue = string | [light: string, dark: string];
/**
* CSS property values for a style rule.
- * Keys are camelCase CSS properties, values are CSS strings.
+ *
+ * Keys are camelCase CSS properties with string values, OR pseudo-class
+ * selectors (starting with `:`) mapping to nested property objects.
+ *
+ * Pseudo-class keys generate separate CSS rules with the pseudo appended
+ * to the component selector. Supported pseudo-classes include `:hover`,
+ * `:focus-visible`, `:active`, `:checked`, `:disabled`, etc.
+ *
+ * @example
+ * ```ts
+ * {
+ * borderColor: '#8F9296',
+ * ':hover': { borderColor: 'color-mix(in srgb, #8F9296, black 20%)' },
+ * ':focus-visible': { outline: '2px solid var(--color-ring-focus)' },
+ * }
+ * ```
*/
-export type XDSStyleOverrides = Record<string, string>;
+export type XDSStyleOverrides = Record<string, string | Record<string, string>>;
/**
* Component style overrides.
@@ -109,6 +124,9 @@ export type XDSStyleOverrides = Record<string, string>;
*
* The `base` key is optional — omit it to only override specific variants.
*
+ * Style values can include pseudo-class keys (`:hover`, `:focus-visible`, etc.)
+ * to override interaction states without CSS custom property escape hatches.
+ *
* @example
* ```tsx
* components: {
@@ -120,6 +138,12 @@ export type XDSStyleOverrides = Record<string, string>;
* badge: {
* 'variant:ghost': { border: '1px solid var(--color-border)' },
* },
+ * radio: {
+ * base: {
+ * borderColor: '#8F9296',
+ * ':hover': { borderColor: 'color-mix(in srgb, #8F9296, black 20%)' },
+ * },
+ * },
* }
* ```
*/
@@ -591,15 +615,46 @@ export function generateThemeRules(theme: XDSDefinedTheme): string[] {
if (theme.components) {
for (const [component, rules] of Object.entries(theme.components)) {
for (const [key, styles] of Object.entries(
- rules as Record<string, Record<string, string>>,
+ rules as Record<
+ string,
+ Record<string, string | Record<string, string>>
+ >,
)) {
const entries = Object.entries(styles);
if (entries.length > 0) {
const suffix = parseStyleKey(key);
- const declarations = entries
- .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
- .join('\n');
- parts.push(` .xds-${component}${suffix} {\n${declarations}\n }`);
+ const baseSelector = `.xds-${component}${suffix}`;
+
+ // Separate regular properties from pseudo-class overrides
+ const props: [string, string][] = [];
+ const pseudos: [string, Record<string, string>][] = [];
+
+ for (const [prop, value] of entries) {
+ if (prop.startsWith(':') && typeof value === 'object') {
+ pseudos.push([prop, value as Record<string, string>]);
+ } else {
+ props.push([prop, value as string]);
+ }
+ }
+
+ // Emit base rule
+ if (props.length > 0) {
+ const declarations = props
+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
+ .join('\n');
+ parts.push(` ${baseSelector} {\n${declarations}\n }`);
+ }
+
+ // Emit pseudo-class rules
+ for (const [pseudo, pseudoStyles] of pseudos) {
+ const pseudoEntries = Object.entries(pseudoStyles);
+ if (pseudoEntries.length > 0) {
+ const declarations = pseudoEntries
+ .map(([prop, value]) => ` ${toKebabCase(prop)}: ${value};`)
+ .join('\n');
+ parts.push(` ${baseSelector}${pseudo} {\n${declarations}\n }`);
+ }
+ }
}
}
}