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.tsindex 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 preservedexpect(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.tsindex 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,};}