Skip to content

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

TypeScript

feat(theme): variants carry their own styles (#803)

Cindy Zhangd229a2150749
diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.ts
index 60566a64e7..5ee89f4c41 100644
--- a/packages/core/src/theme/defineTheme.test.ts
+++ b/packages/core/src/theme/defineTheme.test.ts
@@ -434,12 +434,25 @@ describe('radiusScale', () => {
});
describe('variants', () => {
- it('passes through variants from input to output', () => {
+ it('extracts variant names from styled variant objects', () => {
const theme = defineTheme({
name: 'custom',
variants: {
- button: ['primary-muted', 'primary-outline'],
- badge: ['info-subtle'],
+ button: {
+ 'primary-muted': {
+ backgroundColor: 'var(--color-accent-muted)',
+ color: 'var(--color-accent)',
+ },
+ 'primary-outline': {
+ borderWidth: '2px',
+ borderStyle: 'solid',
+ },
+ },
+ badge: {
+ 'info-subtle': {
+ backgroundColor: 'var(--color-info-muted)',
+ },
+ },
},
});
expect(theme.variants).toEqual({
@@ -448,20 +461,87 @@ describe('variants', () => {
});
});
+ it('merges variant styles into components as variant: keys', () => {
+ const theme = defineTheme({
+ name: 'styled-variants',
+ variants: {
+ button: {
+ 'primary-muted': {
+ backgroundColor: 'var(--color-accent-muted)',
+ color: 'var(--color-accent)',
+ },
+ },
+ },
+ });
+ expect(theme.components?.button?.['variant:primary-muted']).toEqual({
+ backgroundColor: 'var(--color-accent-muted)',
+ color: 'var(--color-accent)',
+ });
+ });
+
+ it('handles empty style objects (register-only variants)', () => {
+ const theme = defineTheme({
+ name: 'register-only',
+ variants: {
+ button: {
+ 'primary-muted': {},
+ },
+ },
+ });
+ expect(theme.variants).toEqual({button: ['primary-muted']});
+ // Empty styles should not create a component entry
+ expect(theme.components?.button?.['variant:primary-muted']).toBeUndefined();
+ });
+
it('returns undefined variants when not provided', () => {
const theme = defineTheme({name: 'bare'});
expect(theme.variants).toBeUndefined();
});
- it('combines variants with tokens and components', () => {
+ it('combines variants with tokens and explicit components', () => {
const theme = defineTheme({
name: 'combo',
tokens: {'--color-accent': '#FF0000'},
components: {button: {base: {borderRadius: '999px'}}},
- variants: {button: ['primary-muted']},
+ variants: {
+ button: {
+ 'primary-muted': {
+ backgroundColor: 'var(--color-accent-muted)',
+ },
+ },
+ },
});
expect(theme.tokens['--color-accent']).toBe('#FF0000');
+ // Explicit component styles preserved
expect(theme.components?.button?.base?.borderRadius).toBe('999px');
+ // Variant styles merged in
+ expect(theme.components?.button?.['variant:primary-muted']).toEqual({
+ backgroundColor: 'var(--color-accent-muted)',
+ });
expect(theme.variants).toEqual({button: ['primary-muted']});
});
+
+ it('explicit components override variant styles on collision', () => {
+ const theme = defineTheme({
+ name: 'override',
+ components: {
+ button: {
+ 'variant:primary-muted': {backgroundColor: 'red'},
+ },
+ },
+ variants: {
+ button: {
+ 'primary-muted': {backgroundColor: 'blue', color: 'white'},
+ },
+ },
+ });
+ // Explicit component override wins for backgroundColor
+ expect(
+ theme.components?.button?.['variant:primary-muted']?.backgroundColor,
+ ).toBe('red');
+ // Variant-only property still present
+ expect(theme.components?.button?.['variant:primary-muted']?.color).toBe(
+ 'white',
+ );
+ });
});
diff --git a/packages/core/src/theme/defineTheme.ts b/packages/core/src/theme/defineTheme.ts
index befa4d5cdc..eb3d817ab7 100644
--- a/packages/core/src/theme/defineTheme.ts
+++ b/packages/core/src/theme/defineTheme.ts
@@ -216,22 +216,43 @@ export interface XDSDefineThemeInput {
/** Icon registry — maps semantic icon names to React nodes */
icons?: Partial<XDSIconRegistry>;
/**
- * Custom variants added by this theme. Keyed by component name (lowercase),
- * value is an array of variant strings.
+ * Custom variants added by this theme — declaration and styles together.
+ * Keyed by component name (lowercase), then variant name → style object.
*
- * These variants are available at runtime (CSS + class names work correctly)
+ * Use this for NEW variants the theme introduces. To override styles on
+ * existing built-in variants (e.g. `variant:secondary`), use `components`.
+ *
+ * An empty object `{}` registers the variant name without adding styles.
+ *
+ * Variant names are available at runtime (CSS + class names work correctly)
* but don't provide autocomplete until `xds theme build` generates the
* TypeScript module augmentation file.
*
* @example
* ```tsx
* variants: {
- * button: ['primary-muted', 'primary-outline'],
- * badge: ['info-subtle'],
+ * button: {
+ * 'primary-muted': {
+ * backgroundColor: 'var(--color-accent-muted)',
+ * color: 'var(--color-accent)',
+ * },
+ * 'primary-outline': {
+ * borderWidth: '2px',
+ * borderStyle: 'solid',
+ * borderColor: 'var(--color-accent)',
+ * backgroundColor: 'transparent',
+ * },
+ * },
+ * badge: {
+ * 'info-subtle': {
+ * backgroundColor: 'var(--color-info-muted)',
+ * color: 'var(--color-info)',
+ * },
+ * },
* }
* ```
*/
- variants?: Record<string, string[]>;
+ variants?: Record<string, Record<string, Record<string, string>>>;
}
/** A defined theme — ready to pass to <XDSTheme> */
@@ -378,12 +399,39 @@ export function defineTheme(input: XDSDefineThemeInput): XDSDefinedTheme {
components = deepMergeComponents(generated, input.components);
}
+ // 4. Process variants: extract names for type augmentation + merge styles into components
+ let variantNames: Record<string, string[]> | undefined;
+ if (input.variants) {
+ variantNames = {};
+ const variantComponents: XDSComponentStyleMap = {};
+ for (const [component, variantMap] of Object.entries(input.variants)) {
+ const names: string[] = [];
+ for (const [variantName, styles] of Object.entries(variantMap)) {
+ names.push(variantName);
+ // Merge non-empty variant styles into components as `variant:name`
+ if (styles && Object.keys(styles).length > 0) {
+ if (!variantComponents[component]) {
+ variantComponents[component] = {};
+ }
+ variantComponents[component][`variant:${variantName}`] = styles;
+ }
+ }
+ if (names.length > 0) {
+ variantNames[component] = names;
+ }
+ }
+ // Merge variant-derived component styles (lowest) with explicit components (highest)
+ if (Object.keys(variantComponents).length > 0) {
+ components = deepMergeComponents(variantComponents, components);
+ }
+ }
+
return {
name: input.name,
tokens,
components,
icons: input.icons,
- variants: input.variants,
+ variants: variantNames,
};
}