An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect, expectTypeOf, vi} from 'vitest';
import type {IconRegistry} from '../Icon/globalIconRegistry';
import type {
DefinedTheme,
DefineThemeInput,
ResolvedDefinedTheme,
} from './defineTheme';
import {
defineTheme,
generateThemeCSS,
generateThemeRules,
isDefinedTheme,
} from './defineTheme';
import {resolveThemeToken} from './tokens';
function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
const {prose, component} = generateThemeCSS(theme);
return [prose, component].filter(Boolean).join('\n\n');
}
describe('defineTheme', () => {
it('creates a theme with name', () => {
const theme = defineTheme({name: 'test'});
expect(theme.name).toBe('test');
});
it('stores only authored token overrides while CSS scopes derived role defaults', () => {
const theme = defineTheme({
name: 'custom',
tokens: {
'--color-text-blue': '#CC0000',
},
});
expect(theme.tokens['--color-text-blue']).toBe('#CC0000');
expect(theme.tokens['--color-text-info']).toBeUndefined();
expect(generateThemeTestCSS(theme)).toContain(
'--color-text-info: var(--color-text-blue);',
);
// Unrelated defaults remain owned by StyleX rather than copied into every
// theme scope.
expect(theme.tokens['--color-background-surface']).toBeUndefined();
});
it('keeps an explicit semantic role above its scoped default', () => {
const theme = defineTheme({
name: 'custom-info',
tokens: {
'--color-text-blue': '#FF0000',
'--color-text-info': '#0066CC',
},
});
expect(theme.tokens['--color-text-info']).toBe('#0066CC');
});
it('does not generate a status alias that would create a token cycle', () => {
const theme = defineTheme({
name: 'parent-role-reference',
tokens: {'--color-text-blue': 'var(--color-text-info)'},
});
const css = generateThemeRules(theme).join('\n');
expect(css).toContain('--color-text-blue: var(--color-text-info);');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
});
it('checks the complete generated alias graph for cycles', () => {
const theme = defineTheme({
name: 'generated-role-cycle',
tokens: {
'--color-text-blue': 'var(--color-text-success)',
'--color-text-green': 'var(--color-text-info)',
},
});
const css = generateThemeRules(theme).join('\n');
// The first alias is safe; the second would close a loop through it.
expect(css).toContain('--color-text-info: var(--color-text-blue);');
expect(css).not.toContain('--color-text-success: var(--color-text-green);');
});
it('includes theme-local references in generated alias cycle checks', () => {
const css = generateThemeRules({
tokens: {'--color-text-blue': 'var(--local-info-loop)'},
localTokens: {'--local-info-loop': 'var(--color-text-info)'},
}).join('\n');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
});
it.each([null, 16, false])(
'stringifies a legacy non-string status source without throwing (%s)',
value => {
const theme = defineTheme({
name: `legacy-status-source-${String(value)}`,
tokens: {'--color-text-blue': value as never},
});
expect(() => generateThemeRules(theme)).not.toThrow();
expect(generateThemeRules(theme).join('\n')).toContain(
`--color-text-blue: ${String(value)};`,
);
},
);
it('preserves JavaScript string coercion for legacy object token values', () => {
const value = {toString: () => '#123456'};
const theme = defineTheme({
name: 'legacy-object-status-source',
tokens: {'--color-text-blue': value as never},
});
expect(generateThemeRules(theme).join('\n')).toContain(
'--color-text-blue: #123456;',
);
});
it.each([
['uppercase VAR()', 'VAR(--color-text-info)', undefined],
['mixed-case var()', 'vAr(--color-text-info)', undefined],
['escaped identifier', 'var(--\\63 olor-text-info)', undefined],
['escaped function name', 'v\\61r(--color-text-info)', undefined],
['escaped leading hyphens', 'var(\\2d\\2d color-text-info)', undefined],
[
'comment-separated identifier',
'var(/*ok*/ --color-text-info)',
undefined,
],
[
'non-ASCII local token',
'var(--品牌)',
{'--品牌': 'var(--color-text-info)'},
],
])(
'recognizes %s while checking generated alias cycles',
(_, accent, localTokens) => {
const css = generateThemeRules({
tokens: {'--color-text-blue': accent},
localTokens,
}).join('\n');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
},
);
it('canonicalizes escaped declaration keys while checking cycles', () => {
const css = generateThemeRules({
tokens: {'--color-text-blue': 'var(--\\62 rand)'},
localTokens: {'--\\62 rand': 'var(--color-text-info)'},
}).join('\n');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
});
it('ignores var() text inside CSS comments', () => {
const css = generateThemeRules({
tokens: {'--color-text-blue': '#123456 /* var(--color-text-info) */'},
}).join('\n');
expect(css).toContain('--color-text-info: var(--color-text-blue);');
});
it.each([
['escaped space', '--x\\ y'],
['escaped backslash', '--x\\\\y'],
])('canonicalizes an %s declaration key exactly once', (_, localToken) => {
const css = generateThemeRules({
tokens: {'--color-text-blue': `var(${localToken})`},
localTokens: {[localToken]: 'var(--color-text-info)'},
}).join('\n');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
});
it.each([
['CRLF-preprocessed escape', 'v\\61\r\nr(--color-text-info)', undefined],
['surrogate escape', 'var(--\\d800)', {'--�': 'var(--color-text-info)'}],
['NUL replacement', 'var(--\0)', {'--�': 'var(--color-text-info)'}],
])('uses browser preprocessing for %s', (_, accent, localTokens) => {
const css = generateThemeRules({
tokens: {'--color-text-blue': accent},
localTokens,
}).join('\n');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
});
it.each(['var (--color-text-info)', 'var/**/(--color-text-info)'])(
'does not treat non-function text as a reference: %s',
accent => {
const css = generateThemeRules({
tokens: {'--color-text-blue': accent},
}).join('\n');
expect(css).toContain('--color-text-info: var(--color-text-blue);');
},
);
it.each([
'var(--color-text-red, #var(--color-text-info))',
'1var(--color-text-info)',
'@var(--color-text-info)',
])(
'does not create references inside non-function CSS tokens: %s',
accent => {
const css = generateThemeRules({
tokens: {
'--color-text-blue': accent,
'--color-text-red': '#123456',
},
}).join('\n');
expect(css).toContain('--color-text-info: var(--color-text-blue);');
},
);
it('does not let unquoted URL contents hide a following var() reference', () => {
const css = generateThemeRules({
tokens: {
'--color-text-blue': 'url(/*) var(--color-text-info) /* */',
},
}).join('\n');
expect(css).not.toContain('--color-text-info: var(--color-text-blue);');
});
it('ignores pre-existing unrelated legacy cycles', () => {
const css = generateThemeRules({
tokens: {
'--color-text-blue': '#123456',
'--color-background-body': 'var(--color-background-surface)',
'--color-background-surface': 'var(--color-background-body)',
},
}).join('\n');
expect(css).toContain('--color-text-info: var(--color-text-blue);');
});
it('handles long runs of adjacent comments without recursion', () => {
const comments = '/**/'.repeat(10_000);
expect(() =>
generateThemeRules({
tokens: {'--color-text-blue': `#123456 ${comments}`},
}),
).not.toThrow();
});
it('handles a very wide reference list without argument spreading', () => {
const references = 'var(--wide-target) '.repeat(200_000);
expect(() =>
generateThemeRules({
tokens: {'--color-text-blue': references},
localTokens: {'--wide-target': '#123456'},
}),
).not.toThrow();
});
it('checks a reconverging token graph in linear time', () => {
const localTokens: Record<string, string> = {};
for (let layer = 0; layer < 26; layer++) {
const next = layer + 1;
const value =
layer === 25
? '#ffffff'
: `var(--layer-${next}-a, var(--layer-${next}-b))`;
localTokens[`--layer-${layer}-a`] = value;
localTokens[`--layer-${layer}-b`] = value;
}
const started = performance.now();
generateThemeRules({
tokens: {'--color-text-blue': 'var(--layer-0-a)'},
localTokens,
});
expect(performance.now() - started).toBeLessThan(1000);
});
it('emits every source-derived status role without counting it as authored', () => {
const theme = defineTheme({
name: 'custom-status-sources',
tokens: {
'--color-text-blue': '#200001',
'--color-text-green': '#200002',
'--color-text-yellow': '#200003',
'--color-text-red': '#200004',
},
});
const css = generateThemeTestCSS(theme);
expect(theme.tokens['--color-text-info']).toBeUndefined();
for (const declaration of [
'--color-text-info: var(--color-text-blue);',
'--color-text-success: var(--color-text-green);',
'--color-text-warning: var(--color-text-yellow);',
'--color-text-error: var(--color-text-red);',
'--color-on-info-muted: var(--color-text-blue);',
'--color-on-success-muted: var(--color-text-green);',
'--color-on-warning-muted: var(--color-text-yellow);',
'--color-on-error-muted: var(--color-text-red);',
]) {
expect(css).toContain(declaration);
}
for (const role of ['icon', 'border']) {
expect(css).toContain(`--color-${role}-info: var(--color-text-info);`);
}
});
it('derives the content on a status fill the theme sets (INV17)', () => {
const theme = defineTheme({
name: 'bright-error',
tokens: {'--color-error': '#FF0000'},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--color-error: #FF0000;');
expect(css).toMatch(
/--color-on-error: light-dark\(#[0-9A-F]{6}, #[0-9A-F]{6}\)/,
);
});
it('converts [light, dark] tuples to light-dark()', () => {
const theme = defineTheme({
name: 'tuple-test',
tokens: {
'--color-accent': ['#0077B6', '#48CAE4'],
},
});
expect(theme.tokens['--color-accent']).toBe('light-dark(#0077B6, #48CAE4)');
expect(theme.tokens['--color-accent']).toBe('light-dark(#0077B6, #48CAE4)');
});
it('passes through string values as-is', () => {
const theme = defineTheme({
name: 'string-test',
tokens: {
'--radius-container': '16px',
},
});
expect(theme.tokens['--radius-container']).toBe('16px');
});
it('mixes tuples and strings', () => {
const theme = defineTheme({
name: 'mixed',
tokens: {
'--color-accent': ['#0077B6', '#48CAE4'],
'--radius-container': '16px',
'--font-family-heading': '"Georgia", serif',
},
});
expect(theme.tokens['--color-accent']).toBe('light-dark(#0077B6, #48CAE4)');
expect(theme.tokens['--radius-container']).toBe('16px');
expect(theme.tokens['--font-family-heading']).toBe('"Georgia", serif');
});
it('accepts unknown token names without warning (types provide guardrails)', () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const theme = defineTheme({
name: 'custom',
tokens: {
// @ts-expect-error testing unknown token
'--color-does-not-exist': '#FF0000',
},
});
// No runtime warning — TypeScript catches typos at compile time
expect(warn).not.toHaveBeenCalled();
// But the token is still set (themes are just CSS custom properties)
expect(theme.tokens['--color-does-not-exist']).toBe('#FF0000');
warn.mockRestore();
});
it.each([
['ocean-theme', '--ac-selection-ink'],
['Theme.Owner', '--'],
['ocean-theme', '--astryx-theme-ocean-theme-color-status-fill-accent'],
])(
'accepts valid local token name %s / %s and preserves its exact bytes',
(themeName, token) => {
const theme = defineTheme({
name: themeName,
localTokens: {[token]: ['#0077b6', '#48cae4']},
components: {
badge: {
'variant:info': {backgroundColor: `var(${token})`},
},
},
});
expect(theme.tokens).not.toHaveProperty(token);
expect(theme.localTokens).toEqual({
[token]: 'light-dark(#0077b6, #48cae4)',
});
expect(theme.__localTokenOwners).toEqual({[token]: themeName});
expect(theme.__localTokenLineage).toEqual([themeName]);
expect(generateThemeTestCSS(theme)).toContain(
`${token}: light-dark(#0077b6, #48cae4);`,
);
},
);
it('rejects a name declared in both tokens and localTokens before CSS and token helpers can disagree', () => {
const token = '--astryx-theme-ocean-theme-color-status-fill-accent';
const legacyTheme = defineTheme({
name: 'ocean-theme',
tokens: {
// @ts-expect-error legacy tokens remain permissive at runtime
[token]: '#0077b6',
},
});
expect(generateThemeTestCSS(legacyTheme)).toContain(`${token}: #0077b6;`);
expect(resolveThemeToken(legacyTheme, token, {mode: 'light'})).toBe(
'#0077b6',
);
expect(() =>
defineTheme({
name: 'ocean-theme',
tokens: {
// @ts-expect-error legacy tokens remain permissive at runtime
[token]: '#0077b6',
},
localTokens: {
[token]: '#48cae4',
},
}),
).toThrow(/both tokens and localTokens/);
expect(() =>
defineTheme({
name: 'ocean-theme',
localTokens: {'--color-accent': '#48cae4'},
}),
).toThrow(/both tokens and localTokens/);
});
it('does not reinterpret unenrolled custom-property references', () => {
const theme = defineTheme({
name: 'legacy',
tokens: {
// @ts-expect-error legacy permissive token input remains unchanged
'--astryx-theme-legacy-color-old': '#123456',
},
components: {
badge: {
base: {color: 'var(--astryx-theme-missing-color-old)'},
},
},
});
expect(theme.tokens['--astryx-theme-legacy-color-old']).toBe('#123456');
expect(theme).not.toHaveProperty('localTokens');
expect(theme).not.toHaveProperty('__localTokenOwners');
expect(theme).not.toHaveProperty('__localTokenLineage');
});
it('rejects an invalid CSS custom-property name', () => {
expect(() =>
defineTheme({
name: 'ocean',
localTokens: {'selection-ink': '#123456'},
}),
).toThrow(/valid CSS custom-property name/);
});
it('treats case-only and unrelated custom-property references as external', () => {
expect(() =>
defineTheme({
name: 'ocean',
localTokens: {'--Selection-Ink': '#123456'},
components: {
button: {
base: {
color: 'var(--selection-ink)',
backgroundColor: 'var(--product-surface)',
},
},
},
}),
).not.toThrow();
});
it.each(['VAR', 'vAr'])(
'rejects cycles between local tokens using %s()',
functionName => {
const escaped = '--\\66 oo';
const other = '--astryx-theme-cycle-color-b';
expect(() =>
defineTheme({
name: 'cycle',
localTokens: {
[escaped]: `${functionName}(${other})`,
[other]: `${functionName}(${escaped})`,
},
}),
).toThrow(/cycle detected/);
},
);
it('includes icons in the theme', () => {
const icons = {close: 'X'} as Partial<IconRegistry>;
const theme = defineTheme({name: 'icons', icons});
expect(theme.icons).toBe(icons);
});
it('reads function icon entries at md in the public icons view', () => {
const info = vi.fn(({size}: {size: string}) => `info-${size}`);
const theme = defineTheme({
name: 'fn-icons',
icons: {info, close: 'X', menu: null},
});
expect(theme.icons).toEqual({info: 'info-md', close: 'X', menu: null});
expect(info).toHaveBeenCalledTimes(1);
expect(info).toHaveBeenCalledWith({size: 'md'});
});
it('works with no tokens', () => {
const theme = defineTheme({name: 'bare'});
expect(Object.keys(theme.tokens)).toHaveLength(0);
});
});
describe('generateThemeCSS', () => {
it('generates CSS with only overrides', () => {
const theme = defineTheme({
name: 'ocean',
tokens: {
'--color-accent': ['#0077B6', '#48CAE4'],
'--radius-container': '16px',
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('@scope');
expect(css).toContain('--color-accent: light-dark(#0077B6, #48CAE4)');
expect(css).toContain('--radius-container: 16px');
// :scope should NOT contain non-overridden tokens
expect(css).not.toContain('--color-background-surface:');
});
it('includes prose rules even with no overrides', () => {
const theme = defineTheme({name: 'empty'});
const css = generateThemeTestCSS(theme);
expect(css).toContain('@scope');
expect(css).toContain(':where(h1, h2, h3, h4, h5, h6)');
expect(css).toContain('font-family: var(--font-family-heading)');
});
it('keeps the data palette out of a theme that never mentions it', () => {
// Canonical defaults come from the public StyleX dataVars group, so a
// theme that never authors data colors has nothing to serialize.
const {component} = generateThemeCSS(defineTheme({name: 'chartless'}));
expect(component).not.toContain('--color-data-');
});
it('puts only the named data token in the theme block, not its siblings', () => {
const theme = defineTheme({
name: 'brand-charts',
tokens: {'--color-data-categorical-blue': '#00A3FF'},
});
const {component} = generateThemeCSS(theme);
expect(component).toContain('--color-data-categorical-blue: #00A3FF;');
// Leaving the siblings out of the theme's own block is what lets a nested
// theme inherit a parent's override instead of shadowing it.
expect(component).not.toContain('--color-data-categorical-orange');
// Defaults reach compiled consumer CSS without entering the theme's own
// tokens, which are what `astryx theme build` reports as overrides.
expect(theme.tokens['--color-data-categorical-orange']).toBeUndefined();
});
it('splits prose into reset layer and components into astryx-theme', () => {
const theme = defineTheme({
name: 'split-test',
components: {
button: {'variant:secondary': {backgroundColor: 'red'}},
},
});
const {prose, component} = generateThemeCSS(theme);
// Prose block should contain element defaults
expect(prose).toContain(':where(p)');
expect(prose).toContain(':where(h1, h2, h3, h4, h5, h6)');
expect(prose).toContain('@scope');
// Prose should NOT contain component overrides
expect(prose).not.toContain('.astryx-button');
// Component block should contain overrides
expect(component).toContain('.astryx-button');
expect(component).toContain('@scope');
// Component should NOT contain prose element rules
expect(component).not.toContain(':where(p)');
});
});
describe('isDefinedTheme', () => {
it('returns true for defineTheme output', () => {
const theme = defineTheme({name: 'test'});
expect(isDefinedTheme(theme)).toBe(true);
});
it('returns false for legacy theme objects', () => {
const legacy = {name: 'old', styles: {}, icons: undefined};
expect(isDefinedTheme(legacy)).toBe(false);
});
it('returns false for null/undefined', () => {
expect(isDefinedTheme(null)).toBe(false);
expect(isDefinedTheme(undefined)).toBe(false);
});
});
describe('component overrides', () => {
it('passes components through to the theme', () => {
const theme = defineTheme({
name: 'styled',
components: {
card: {
base: {borderWidth: '2px', borderColor: 'var(--color-accent)'},
},
button: {
base: {borderRadius: '999px'},
},
},
});
expect(theme.components?.card?.base).toEqual({
borderWidth: '2px',
borderColor: 'var(--color-accent)',
});
expect(theme.components?.button?.base).toEqual({borderRadius: '999px'});
});
});
describe('generateThemeCSS with components', () => {
it('generates scoped CSS for base component overrides', () => {
const theme = defineTheme({
name: 'ocean',
tokens: {
'--color-accent': ['#0077B6', '#48CAE4'],
},
components: {
card: {
base: {borderWidth: '2px', borderColor: 'var(--color-accent)'},
},
button: {
base: {borderRadius: '999px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-card {');
expect(css).toContain('border-width: 2px');
expect(css).toContain('border-color: var(--color-accent)');
expect(css).toContain('.astryx-button {');
expect(css).toContain('border-radius: 999px');
});
it('generates variant selectors from prop:value keys', () => {
const theme = defineTheme({
name: 'test',
components: {
button: {
'variant:secondary': {
backgroundColor: 'rgba(0,0,0,0.06)',
},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-button[data-variant="secondary"]');
expect(css).toContain('background-color: rgba(0,0,0,0.06)');
});
it('generates compound selectors from prop:value+prop:value keys', () => {
const theme = defineTheme({
name: 'test',
components: {
button: {
'variant:destructive+size:sm': {
padding: '2px 6px',
},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain(
'.astryx-button[data-variant="destructive"][data-size="sm"]',
);
expect(css).toContain('padding: 2px 6px');
});
it('converts camelCase to kebab-case', () => {
const theme = defineTheme({
name: 'test',
components: {
heading: {
base: {fontFamily: '"Playfair Display", serif'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('font-family: "Playfair Display", serif');
expect(css).not.toContain('fontFamily');
});
it('combines tokens and components', () => {
const theme = defineTheme({
name: 'combo',
tokens: {'--radius-container': '20px'},
components: {
card: {base: {borderWidth: '1px'}},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('@scope');
expect(css).toContain('--radius-container: 20px');
expect(css).toContain('.astryx-card {');
expect(css).toContain('border-width: 1px');
});
});
describe('typography.scale', () => {
it('generates typography token overrides when typography.scale is provided', () => {
const theme = defineTheme({
name: 'dense',
typography: {scale: {base: 12, ratio: 1.125}},
});
// Semantic tokens are now var() refs; raw token has the computed value
expect(theme.tokens['--text-heading-4-size']).toBe('var(--font-size-base)');
expect(theme.tokens['--font-size-base']).toBe('0.75rem');
expect(theme.tokens['--text-body-size']).toBe('var(--font-size-base)');
});
it('generates 44 tokens (11 raw size + 33 semantic)', () => {
const theme = defineTheme({
name: 'custom',
typography: {scale: {base: 14, ratio: 1.2}},
});
// 12 raw size (--font-size-4xs…--font-size-5xl) + 18 heading + 24 text = 54
const typeScaleKeys = Object.keys(theme.tokens).filter(
k => k.startsWith('--font-size-') || k.startsWith('--text-'),
);
expect(typeScaleKeys).toHaveLength(54);
});
it('explicit tokens override scale-generated values', () => {
const theme = defineTheme({
name: 'override-test',
typography: {scale: {base: 14, ratio: 1.2}},
tokens: {
'--text-heading-1-size': '40px',
},
});
// Explicit token should win over typography.scale
expect(theme.tokens['--text-heading-1-size']).toBe('40px');
// Non-overridden scale token should still be a var() ref
expect(theme.tokens['--text-heading-4-size']).toBe('var(--font-size-base)');
});
it('works without typography.scale (backwards compatible)', () => {
const theme = defineTheme({name: 'no-scale'});
// No type scale tokens should be present
expect(theme.tokens['--text-heading-1-size']).toBeUndefined();
});
it('combines typography.scale with other token overrides', () => {
const theme = defineTheme({
name: 'combo',
typography: {scale: {base: 16, ratio: 1.25}},
tokens: {
'--color-accent': '#CC0000',
},
});
expect(theme.tokens['--color-accent']).toBe('#CC0000');
expect(theme.tokens['--text-heading-4-size']).toBe('var(--font-size-base)');
expect(theme.tokens['--font-size-base']).toBe('1rem');
});
});
describe('typography.scale component auto-generation', () => {
it('auto-generates heading component overrides when typography.scale is provided', () => {
const theme = defineTheme({
name: 'auto',
typography: {scale: {base: 14, ratio: 1.2}},
});
expect(theme.components?.heading?.['level:1']).toBeDefined();
expect(theme.components?.heading?.['level:1']?.fontSize).toBe(
'var(--text-heading-1-size)',
);
});
it('auto-generates text component overrides when typography.scale is provided', () => {
const theme = defineTheme({
name: 'auto',
typography: {scale: {base: 14, ratio: 1.2}},
});
expect(theme.components?.text?.['type:body']).toBeDefined();
expect(theme.components?.text?.['type:body']?.fontSize).toBe(
'var(--text-body-size)',
);
});
it('does not include color in auto-generated rules', () => {
const theme = defineTheme({
name: 'auto',
typography: {scale: {base: 14, ratio: 1.2}},
});
expect(theme.components?.heading?.['level:1']?.color).toBeUndefined();
expect(theme.components?.text?.['type:supporting']?.color).toBeUndefined();
});
it('explicit components deep-merge on top of auto-generated', () => {
const theme = defineTheme({
name: 'custom',
typography: {scale: {base: 14, ratio: 1.2}},
components: {
heading: {
'level:1': {letterSpacing: '-0.02em'},
},
button: {
base: {borderRadius: '999px'},
},
},
});
// Auto-generated heading props still present
expect(theme.components?.heading?.['level:1']?.fontSize).toBe(
'var(--text-heading-1-size)',
);
// Explicit override merged on top
expect(theme.components?.heading?.['level:1']?.letterSpacing).toBe(
'-0.02em',
);
// Non-typography component preserved
expect(theme.components?.button?.base?.borderRadius).toBe('999px');
});
it('does not generate components when typography.scale is absent', () => {
const theme = defineTheme({name: 'bare'});
expect(theme.components).toBeUndefined();
});
it('explicit heading overrides win over auto-generated', () => {
const theme = defineTheme({
name: 'override',
typography: {scale: {base: 14, ratio: 1.2}},
components: {
heading: {
'level:1': {fontFamily: '"Playfair Display", serif'},
},
},
});
// Explicit fontFamily wins
expect(theme.components?.heading?.['level:1']?.fontFamily).toBe(
'"Playfair Display", serif',
);
// Auto-generated fontSize still present
expect(theme.components?.heading?.['level:1']?.fontSize).toBe(
'var(--text-heading-1-size)',
);
});
});
describe('radius', () => {
it('generates radius tokens from radius', () => {
const theme = defineTheme({
name: 'rounded',
radius: {base: 4, multiplier: 1.5},
});
expect(theme.tokens['--radius-inner']).toBe('6px');
expect(theme.tokens['--radius-element']).toBe('12px');
expect(theme.tokens['--radius-container']).toBe('18px');
expect(theme.tokens['--radius-page']).toBe('42px');
expect(theme.tokens['--radius-none']).toBe('0px');
expect(theme.tokens['--radius-full']).toBe('9999px');
});
it('explicit tokens override radius', () => {
const theme = defineTheme({
name: 'custom',
radius: {base: 4, multiplier: 1},
tokens: {'--radius-container': '20px'},
});
expect(theme.tokens['--radius-container']).toBe('20px');
expect(theme.tokens['--radius-element']).toBe('8px'); // from radius
});
it('radius with multiplier 0 produces sharp theme', () => {
const theme = defineTheme({
name: 'sharp',
radius: {base: 4, multiplier: 0},
});
expect(theme.tokens['--radius-inner']).toBe('0px');
expect(theme.tokens['--radius-element']).toBe('0px');
expect(theme.tokens['--radius-container']).toBe('0px');
expect(theme.tokens['--radius-page']).toBe('0px');
expect(theme.tokens['--radius-none']).toBe('0px');
expect(theme.tokens['--radius-full']).toBe('9999px');
});
it('works without radius (backwards compatible)', () => {
const theme = defineTheme({name: 'no-scale'});
expect(theme.tokens['--radius-none']).toBeUndefined();
});
it('combines radius with typography.scale and other tokens', () => {
const theme = defineTheme({
name: 'combo',
typography: {scale: {base: 16, ratio: 1.25}},
radius: {base: 4, multiplier: 1},
tokens: {
'--color-accent': '#CC0000',
},
});
expect(theme.tokens['--color-accent']).toBe('#CC0000');
expect(theme.tokens['--text-heading-4-size']).toBe('var(--font-size-base)');
expect(theme.tokens['--radius-element']).toBe('8px');
});
});
describe('custom status via components', () => {
it('passes custom status through components as status:value keys', () => {
const theme = defineTheme({
name: 'banner-status',
components: {
banner: {
'status:neutral': {
backgroundColor: 'var(--color-background-muted)',
},
},
},
});
expect(theme.components?.banner?.['status:neutral']).toEqual({
backgroundColor: 'var(--color-background-muted)',
});
});
it('generates correct CSS selectors for banner status extensions', () => {
const theme = defineTheme({
name: 'banner-css',
components: {
banner: {
'status:neutral': {
backgroundColor: 'var(--color-background-muted)',
},
},
},
});
const css = generateThemeTestCSS(theme);
// The status axis remains explicit in the generated data-attribute selector.
expect(css).toContain('.astryx-banner[data-status="neutral"]');
expect(css).toContain('background-color: var(--color-background-muted)');
});
it('custom button variant via components', () => {
const theme = defineTheme({
name: 'button-variant',
components: {
button: {
'variant:primary-muted': {
backgroundColor: '#ECF5FF',
},
},
},
});
expect(theme.components?.button?.['variant:primary-muted']).toEqual({
backgroundColor: '#ECF5FF',
});
});
it('generates correct CSS for custom button variant', () => {
const theme = defineTheme({
name: 'button-css',
components: {
button: {
'variant:primary-muted': {
backgroundColor: '#ECF5FF',
},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-button[data-variant="primary-muted"]');
expect(css).toContain('background-color: #ECF5FF');
});
it('combines custom status with base and token overrides', () => {
const theme = defineTheme({
name: 'combo',
tokens: {'--color-accent': '#FF0000'},
components: {
banner: {
'status:neutral': {
backgroundColor: 'var(--color-background-muted)',
color: 'gray',
},
},
button: {base: {borderRadius: '999px'}},
},
});
expect(theme.tokens['--color-accent']).toBe('#FF0000');
expect(theme.components?.banner?.['status:neutral']).toEqual({
backgroundColor: 'var(--color-background-muted)',
color: 'gray',
});
expect(theme.components?.button?.base?.borderRadius).toBe('999px');
});
it('does not have a variants field on the output', () => {
const theme = defineTheme({
name: 'no-variants',
components: {
banner: {
'status:neutral': {backgroundColor: 'gray'},
},
},
});
expect(theme).not.toHaveProperty('variants');
});
});
describe('typography font family derivation', () => {
it('derives font family tokens from typography roles', () => {
const theme = defineTheme({
name: 'family-tokens',
typography: {
body: {family: 'Geist', fallbacks: '-apple-system, sans-serif'},
code: {family: 'Geist Mono', fallbacks: '"SF Mono", monospace'},
},
});
expect(theme.tokens['--font-family-body']).toBe(
'Geist, -apple-system, sans-serif',
);
expect(theme.tokens['--font-family-heading']).toBe(
'Geist, -apple-system, sans-serif',
); // inherited from body
expect(theme.tokens['--font-family-code']).toBe(
'"Geist Mono", "SF Mono", monospace',
);
});
it('heading family overrides body when specified', () => {
const theme = defineTheme({
name: 'heading-override',
typography: {
body: {family: 'Inter', fallbacks: 'sans-serif'},
heading: {family: 'Playfair Display', fallbacks: 'serif'},
},
});
expect(theme.tokens['--font-family-body']).toBe('Inter, sans-serif');
expect(theme.tokens['--font-family-heading']).toBe(
'"Playfair Display", serif',
);
});
it('explicit tokens override typography-derived font tokens', () => {
const theme = defineTheme({
name: 'token-wins',
typography: {
body: {family: 'Geist', fallbacks: 'sans-serif'},
},
tokens: {'--font-family-heading': '"Custom", serif'},
});
// Explicit token wins over typography-derived
expect(theme.tokens['--font-family-heading']).toBe('"Custom", serif');
// Body still comes from typography
expect(theme.tokens['--font-family-body']).toBe('Geist, sans-serif');
});
it('combines typography with scale and tokens', () => {
const theme = defineTheme({
name: 'combo',
typography: {
scale: {base: 14, ratio: 1.2},
body: {
family: 'Figtree',
fallbacks: 'sans-serif',
},
},
});
expect(theme.name).toBe('combo');
expect(theme.tokens['--font-family-body']).toBe('Figtree, sans-serif');
// scale tokens should still be present
expect(theme.tokens['--text-heading-4-size']).toBeDefined();
});
});
describe('typography weight derivation', () => {
it('applies heading weight from typography role', () => {
const theme = defineTheme({
name: 'heading-weight',
typography: {
scale: {base: 14, ratio: 1.2},
heading: {weight: 'bold'},
},
});
// All heading levels should get bold weight
expect(theme.tokens['--text-heading-1-weight']).toBe(
'var(--font-weight-bold)',
);
expect(theme.tokens['--text-heading-4-weight']).toBe(
'var(--font-weight-bold)',
);
});
it('per-level heading weights override default heading weight', () => {
const theme = defineTheme({
name: 'per-level',
typography: {
scale: {base: 14, ratio: 1.2},
heading: {
weight: 'semibold',
weights: {3: 'bold', 4: 'bold'},
},
},
});
expect(theme.tokens['--text-heading-1-weight']).toBe(
'var(--font-weight-semibold)',
);
expect(theme.tokens['--text-heading-3-weight']).toBe(
'var(--font-weight-bold)',
);
expect(theme.tokens['--text-heading-4-weight']).toBe(
'var(--font-weight-bold)',
);
});
it('body weight flows to text body token', () => {
const theme = defineTheme({
name: 'body-weight',
typography: {
scale: {base: 14, ratio: 1.2},
body: {weight: 'medium'},
},
});
expect(theme.tokens['--text-body-weight']).toBe(
'var(--font-weight-medium)',
);
});
it('code weight flows to text code token', () => {
const theme = defineTheme({
name: 'code-weight',
typography: {
scale: {base: 14, ratio: 1.2},
code: {weight: 'medium'},
},
});
expect(theme.tokens['--text-code-weight']).toBe(
'var(--font-weight-medium)',
);
});
it('named weight maps to var reference', () => {
const theme = defineTheme({
name: 'named-weight',
typography: {
scale: {base: 14, ratio: 1.2},
heading: {weight: 'normal'},
},
});
expect(theme.tokens['--text-heading-1-weight']).toBe(
'var(--font-weight-normal)',
);
});
it('raw CSS weight value passes through', () => {
const theme = defineTheme({
name: 'raw-weight',
typography: {
scale: {base: 14, ratio: 1.2},
heading: {weight: '900'},
},
});
expect(theme.tokens['--text-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-indicator': {
base: {
borderColor: '#8F9296',
':hover': {
borderColor: 'color-mix(in srgb, #8F9296, black 20%)',
},
},
},
},
});
const css = generateThemeTestCSS(theme);
// Base rule
expect(css).toContain('.astryx-radio-indicator {');
expect(css).toContain('border-color: #8F9296');
// Pseudo rule — separate selector
expect(css).toContain(
'.astryx-radio-indicator:hover:where(:not(:disabled,[aria-disabled="true"])) {',
);
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-accent)',
},
},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-button[data-variant="primary-muted"] {');
expect(css).toContain('background-color: #ECF5FF');
expect(css).toContain(
'.astryx-button[data-variant="primary-muted"]:hover:where(:not(:disabled,[aria-disabled="true"])) {',
);
expect(css).toContain('background-color: #D6EBFF');
expect(css).toContain(
'.astryx-button[data-variant="primary-muted"]:focus-visible {',
);
expect(css).toContain('outline: 2px solid var(--color-accent)');
});
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 = generateThemeTestCSS(theme);
// Should NOT emit an empty base rule
expect(css).not.toMatch(/\.astryx-switch\s*\{\s*\}/);
// Should emit the pseudo rule
expect(css).toContain(
'.astryx-switch:hover:where(:not(:disabled,[aria-disabled="true"])) {',
);
});
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 = generateThemeTestCSS(theme);
expect(css).toContain('.astryx-card {');
expect(css).toContain('border-width: 2px');
expect(css).toContain('border-color: var(--color-accent)');
// No pseudo rules
expect(css).not.toContain('.astryx-card:');
});
});
describe('container padding mapping', () => {
it('maps uniform padding to shorthand token on card', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {padding: '20px'},
},
},
});
const css = generateThemeTestCSS(theme);
// Should NOT emit raw padding property (only the scoped token)
expect(css).not.toMatch(/[^-]padding: 20px/);
// Should emit component-scoped shorthand token
expect(css).toContain('--astryx-card-padding: 20px');
// Should NOT emit directional tokens (shorthand covers all sides)
expect(css).not.toContain('--astryx-card-padding-inline');
expect(css).not.toContain('--astryx-card-padding-block-start');
});
it('maps asymmetric padding to directional tokens', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {padding: '16px 20px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-inline: 20px');
expect(css).toContain('--astryx-card-padding-block-start: 16px');
expect(css).toContain('--astryx-card-padding-block-end: 16px');
// Should NOT emit shorthand (sides differ)
expect(css).not.toMatch(/--astryx-card-padding:[^-]/);
});
it('maps paddingBlock and paddingInline separately', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {paddingBlock: '24px', paddingInline: '16px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-inline: 16px');
expect(css).toContain('--astryx-card-padding-block-start: 24px');
expect(css).toContain('--astryx-card-padding-block-end: 24px');
});
it('works for section and dialog too', () => {
const theme = defineTheme({
name: 'test',
components: {
section: {
base: {padding: '12px'},
},
dialog: {
base: {padding: '24px 32px'},
},
},
});
const css = generateThemeTestCSS(theme);
// Section — uniform → shorthand
expect(css).toContain('--astryx-section-padding: 12px');
// Dialog — asymmetric → directional
expect(css).toContain('--astryx-dialog-padding-inline: 32px');
expect(css).toContain('--astryx-dialog-padding-block-start: 24px');
});
it('maps bottom-sheet padding to its container tokens', () => {
const theme = defineTheme({
name: 'test',
components: {
'bottom-sheet': {
base: {padding: '24px 20px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-bottom-sheet-padding-inline: 20px');
expect(css).toContain('--astryx-bottom-sheet-padding-block-start: 24px');
expect(css).toContain('--astryx-bottom-sheet-padding-block-end: 24px');
// The panel is the overlay boundary; the value reaches the content box
// through the token, never as padding on the panel itself.
expect(css).not.toMatch(/(^|[\s{;])padding:\s*24px 20px/);
});
it('maps drawer padding to its container tokens', () => {
const theme = defineTheme({
name: 'test',
components: {
drawer: {
base: {padding: '24px 20px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-drawer-padding-inline: 20px');
expect(css).toContain('--astryx-drawer-padding-block-start: 24px');
expect(css).toContain('--astryx-drawer-padding-block-end: 24px');
// The panel is the overlay boundary; the value reaches the content area
// through the token, never as padding on the panel itself.
expect(css).not.toMatch(/(^|[\s{;])padding:\s*24px 20px/);
});
it('does NOT map padding on non-container components', () => {
const theme = defineTheme({
name: 'test',
components: {
button: {
base: {padding: '8px 16px'},
},
},
});
const css = generateThemeTestCSS(theme);
// Button is not a container — padding passes through as-is
expect(css).toContain('padding: 8px 16px');
expect(css).not.toContain('--astryx-button-padding');
});
it('preserves non-padding properties alongside padding mapping', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {
padding: '20px',
'--_card-radius': '16px',
backgroundColor: 'white',
},
},
},
});
const css = generateThemeTestCSS(theme);
// Non-padding props pass through
expect(css).toContain('--_card-radius: 16px');
expect(css).toContain('background-color: white');
// Padding is mapped to component-scoped token
expect(css).toContain('--astryx-card-padding: 20px');
expect(css).not.toMatch(/[^-]padding: 20px/);
});
it('maps 3-value padding shorthand', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {padding: '16px 20px 12px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-block-start: 16px');
expect(css).toContain('--astryx-card-padding-block-end: 12px');
expect(css).toContain('--astryx-card-padding-inline: 20px');
});
it('maps paddingBlock shorthand with two values', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {paddingBlock: '16px 24px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-block-start: 16px');
expect(css).toContain('--astryx-card-padding-block-end: 24px');
});
it('maps paddingInline shorthand with two values', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {paddingInline: '12px 20px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-inline-start: 12px');
expect(css).toContain('--astryx-card-padding-inline-end: 20px');
});
it('maps paddingBlockStart alone', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {paddingBlockStart: '32px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-block-start: 32px');
expect(css).not.toContain('--astryx-card-padding-block-end');
expect(css).not.toContain('--astryx-card-padding-inline');
});
it('maps paddingInlineStart and paddingInlineEnd separately', () => {
const theme = defineTheme({
name: 'test',
components: {
card: {
base: {paddingInlineStart: '8px', paddingInlineEnd: '24px'},
},
},
});
const css = generateThemeTestCSS(theme);
expect(css).toContain('--astryx-card-padding-inline-start: 8px');
expect(css).toContain('--astryx-card-padding-inline-end: 24px');
});
});
describe('defineTheme extends', () => {
it('inherits enrollment, allows exact replacement, and owns new child names', () => {
const inherited = '--astryx-theme-base-theme-color-status-fill';
const childOwned = '--child-surface-raised';
const base = defineTheme({
name: 'base-theme',
localTokens: {[inherited]: '#123456'},
});
const child = defineTheme({
name: 'child-theme',
extends: base,
localTokens: {
[inherited]: '#654321',
[childOwned]: '#abcdef',
},
});
expect(child.localTokens).toEqual({
[inherited]: '#654321',
[childOwned]: '#abcdef',
});
expect(child.__localTokenOwners).toEqual({
[inherited]: 'base-theme',
[childOwned]: 'child-theme',
});
expect(child.__localTokenLineage).toEqual(['base-theme', 'child-theme']);
});
it('inherits enrollment when the child declares no local tokens', () => {
const base = defineTheme({name: 'base-theme', localTokens: {}});
const child = defineTheme({name: 'child-theme', extends: base});
expect(child.localTokens).toEqual({});
expect(child.__localTokenLineage).toEqual(['base-theme', 'child-theme']);
});
it('preserves legacy descendant names when they only inherit enrollment', () => {
const base = defineTheme({
name: 'base-theme',
localTokens: {
'--astryx-theme-base-theme-color-status-fill': '#123456',
},
});
const legacyChild = defineTheme({name: 'Legacy.Theme', extends: base});
const grandchild = defineTheme({name: 'grandchild', extends: legacyChild});
expect(legacyChild.localTokens).toEqual(base.localTokens);
expect(legacyChild.__localTokenLineage).toEqual([
'base-theme',
'Legacy.Theme',
]);
expect(grandchild.localTokens).toEqual(base.localTokens);
expect(grandchild.__localTokenLineage).toEqual([
'base-theme',
'Legacy.Theme',
'grandchild',
]);
});
it('inherits tokens from base theme', () => {
const base = defineTheme({
name: 'base',
tokens: {
'--color-accent': '#0077B6',
'--radius-container': '16px',
},
});
const child = defineTheme({
name: 'child',
extends: base,
});
expect(child.tokens['--color-accent']).toBe('#0077B6');
expect(child.tokens['--radius-container']).toBe('16px');
});
it('inherits motion field by field: a field the child leaves unset keeps the base value (spec:AST-108 FR5)', () => {
const base = defineTheme({
name: 'base',
motion: {
fast: 100,
medium: 200,
slow: 400,
ratio: 0.75,
easing: 'cubic-bezier(0.2, 0, 0, 1)',
},
});
const child = defineTheme({
name: 'child',
extends: base,
motion: {fast: 120, medium: 240, ratio: 0.8},
});
// The fields the child sets regenerate their tokens.
expect(child.tokens['--duration-fast']).toBe('120ms');
expect(child.tokens['--duration-medium-min']).toBe('190ms');
// `slow` and `easing`, left unset, keep the base's tokens: the slow band
// stays at the base's ratio (400 × 0.75), not the child's.
expect(child.tokens['--duration-slow']).toBe('400ms');
expect(child.tokens['--duration-slow-min']).toBe('300ms');
expect(child.tokens['--ease-standard']).toBe('cubic-bezier(0.2, 0, 0, 1)');
});
it('overrides base tokens with explicit tokens', () => {
const base = defineTheme({
name: 'base',
tokens: {
'--color-accent': '#0077B6',
'--radius-container': '16px',
},
});
const child = defineTheme({
name: 'child',
extends: base,
tokens: {'--color-accent': '#FF0000'},
});
expect(child.tokens['--color-accent']).toBe('#FF0000');
expect(child.tokens['--radius-container']).toBe('16px');
});
it('inherits component overrides from base theme', () => {
const base = defineTheme({
name: 'base',
components: {
button: {
base: {fontWeight: '600'},
'variant:secondary': {backgroundColor: 'rgba(0,0,0,0.06)'},
},
},
});
const child = defineTheme({
name: 'child',
extends: base,
});
expect(child.components?.button?.base).toEqual({fontWeight: '600'});
expect(child.components?.button?.['variant:secondary']).toEqual({
backgroundColor: 'rgba(0,0,0,0.06)',
});
});
it('merges component overrides — child wins', () => {
const base = defineTheme({
name: 'base',
components: {
button: {
base: {fontWeight: '600', borderRadius: '4px'},
},
},
});
const child = defineTheme({
name: 'child',
extends: base,
components: {
button: {
base: {fontWeight: '700'},
},
},
});
expect(child.components?.button?.base).toEqual({
fontWeight: '700',
borderRadius: '4px',
});
});
it('merges icons — child overrides base', () => {
const baseIcons = {close: 'X', menu: 'M'} as Partial<IconRegistry>;
const childIcons = {close: 'Y'} as Partial<IconRegistry>;
const base = defineTheme({name: 'base', icons: baseIcons});
const child = defineTheme({
name: 'child',
extends: base,
icons: childIcons,
});
expect(child.icons?.close).toBe('Y');
expect(child.icons?.menu).toBe('M');
});
it('inherits icons when child has none', () => {
const baseIcons = {close: 'X'} as Partial<IconRegistry>;
const base = defineTheme({name: 'base', icons: baseIcons});
const child = defineTheme({name: 'child', extends: base});
expect(child.icons?.close).toBe('X');
});
// spec:AST-087 FR2, FR3, FR18 — one theme-level list; a child that sets it
// replaces the inherited list, one that omits it inherits; entry functions
// receive `variant` typed as the theme's listed names.
describe('iconVariants', () => {
it('keeps the listed names on the defined theme', () => {
const list = ['outline', 'filled'];
const theme = defineTheme({name: 'variants', iconVariants: list});
expect(theme.iconVariants).toEqual(['outline', 'filled']);
list.push('bold');
expect(theme.iconVariants).toEqual(['outline', 'filled']);
});
it('has no list when no theme in the lineage sets one', () => {
const base = defineTheme({name: 'no-variants'});
const child = defineTheme({name: 'no-variants-child', extends: base});
expect(base.iconVariants).toBeUndefined();
expect('iconVariants' in base).toBe(false);
expect(child.iconVariants).toBeUndefined();
});
it('inherits the base list when a child omits it', () => {
const base = defineTheme({
name: 'variants-base',
iconVariants: ['outline', 'filled'],
});
const child = defineTheme({name: 'variants-inherit', extends: base});
expect(child.iconVariants).toEqual(['outline', 'filled']);
});
it('replaces the base list, without merging, when a child sets it', () => {
const base = defineTheme({
name: 'variants-base',
iconVariants: ['outline', 'filled'],
});
const child = defineTheme({
name: 'variants-replace',
extends: base,
iconVariants: ['bold'],
});
const emptied = defineTheme({
name: 'variants-empty',
extends: base,
iconVariants: [],
});
expect(child.iconVariants).toEqual(['bold']);
expect(emptied.iconVariants).toEqual([]);
expect(base.iconVariants).toEqual(['outline', 'filled']);
});
it('types entry functions by the listed names', () => {
const base = defineTheme({
name: 'variants-typed',
iconVariants: ['outline', 'filled'],
icons: {
info: ({size, variant}) => {
expectTypeOf(variant).toEqualTypeOf<
'outline' | 'filled' | undefined
>();
return `${size}-${variant ?? 'normal'}`;
},
close: ({variant}) =>
// @ts-expect-error — 'bold' is not a name this theme lists.
variant === 'bold' ? 'bold-close' : 'close',
},
});
expectTypeOf(base).toEqualTypeOf<
ResolvedDefinedTheme<'outline' | 'filled'>
>();
defineTheme({
name: 'variants-typed-inherit',
extends: base,
icons: {
info: ({variant}) => {
expectTypeOf(variant).toEqualTypeOf<
'outline' | 'filled' | undefined
>();
return null;
},
},
});
defineTheme({
name: 'variants-typed-replace',
extends: base,
iconVariants: ['bold'],
icons: {
info: ({variant}) => {
expectTypeOf(variant).toEqualTypeOf<'bold' | undefined>();
return null;
},
close: ({variant}) =>
// @ts-expect-error — the child replaced the list; 'filled' is gone.
variant === 'filled' ? 'filled-close' : 'close',
},
});
defineTheme({
name: 'variants-typed-none',
icons: {
info: ({variant}) => {
expectTypeOf(variant).toEqualTypeOf<undefined>();
return null;
},
},
});
const plainBase: DefinedTheme = base;
defineTheme({
name: 'variants-typed-plain-base',
extends: plainBase,
icons: {
info: ({variant}) => {
expectTypeOf(variant).toEqualTypeOf<string | undefined>();
return null;
},
},
});
expectTypeOf<DefinedTheme['iconVariants']>().toEqualTypeOf<
ReadonlyArray<string> | undefined
>();
});
it('keeps resolved themes with and without lists assignable to each other', () => {
const shared: DefineThemeInput = {name: 'variants-shared'};
const unlisted = defineTheme({name: 'variants-active'});
// Each annotation is the check: these assignments compiled before
// iconVariants existed and must keep compiling.
const fromShared: typeof unlisted = defineTheme(shared);
const fromListed: typeof unlisted = defineTheme({
name: 'variants-listed-active',
iconVariants: ['outline'],
});
const listed = defineTheme({
name: 'variants-listed',
iconVariants: ['outline', 'filled'],
});
const fromUnlisted: typeof listed = defineTheme({
name: 'variants-unlisted',
});
const resolved: ResolvedDefinedTheme = fromUnlisted;
expect(
[unlisted, fromShared, fromListed, listed, resolved].map(t => t.name),
).toEqual([
'variants-active',
'variants-shared',
'variants-listed-active',
'variants-listed',
'variants-unlisted',
]);
});
it('passes no variant to entry functions', () => {
const info = vi.fn(
({size, variant}: {size: string; variant?: string}) =>
`${size}-${variant ?? 'normal'}`,
);
const theme = defineTheme({
name: 'variants-no-request',
iconVariants: ['outline', 'filled'],
icons: {info},
});
expect(theme.icons?.info).toBe('md-normal');
expect(info).toHaveBeenCalledWith({size: 'md'});
});
});
it('merges function icon entries by key and reads them at md', () => {
const base = defineTheme({
name: 'base',
icons: {close: ({size}) => `base-close-${size}`, menu: 'M'},
});
const child = defineTheme({
name: 'child',
extends: base,
icons: {menu: ({size}) => `child-menu-${size}`},
});
expect(child.icons).toEqual({
close: 'base-close-md',
menu: 'child-menu-md',
});
});
it('uses child name, not base name', () => {
const base = defineTheme({name: 'base'});
const child = defineTheme({name: 'my-brand', extends: base});
expect(child.name).toBe('my-brand');
});
it('inherits font family tokens from base theme', () => {
const base = defineTheme({
name: 'base',
typography: {
body: {
family: 'Geist',
fallbacks: 'sans-serif',
},
scale: {base: 14, ratio: 1.2},
},
});
const child = defineTheme({name: 'child', extends: base});
expect(child.tokens['--font-family-body']).toBe('Geist, sans-serif');
});
it('typography in child overrides base typography tokens', () => {
const base = defineTheme({
name: 'base',
typography: {scale: {base: 14, ratio: 1.2}},
});
const child = defineTheme({
name: 'child',
extends: base,
typography: {scale: {base: 16, ratio: 1.25}},
});
// Child's type scale tokens should differ from base
expect(child.tokens['--font-size-base']).not.toBe(
base.tokens['--font-size-base'],
);
});
it('inherits indicators when the child has none', () => {
const indicator = (() => null) as unknown as NonNullable<
DefinedTheme['indicators']
>['check'];
const base = defineTheme({name: 'base', indicators: {check: indicator}});
const child = defineTheme({name: 'child', extends: base});
expect(child.indicators?.check).toBe(indicator);
});
it('inherits onDark token overrides from base theme', () => {
const base = defineTheme({
name: 'base',
onDark: {tokens: {'--color-border': '#ffffff'}},
});
const child = defineTheme({name: 'child', extends: base});
expect(child.__onDark?.tokens['--color-border']).toBe('#ffffff');
});
it('inherits onLight token overrides from base theme', () => {
const base = defineTheme({
name: 'base',
onLight: {tokens: {'--color-border': '#000000'}},
});
const child = defineTheme({name: 'child', extends: base});
expect(child.__onLight?.tokens['--color-border']).toBe('#000000');
});
it('lets the child override an inherited onDark token', () => {
const base = defineTheme({
name: 'base',
onDark: {tokens: {'--color-border': '#ffffff', '--color-track': '#eee'}},
});
const child = defineTheme({
name: 'child',
extends: base,
onDark: {tokens: {'--color-border': '#cccccc'}},
});
expect(child.__onDark?.tokens['--color-border']).toBe('#cccccc');
expect(child.__onDark?.tokens['--color-track']).toBe('#eee');
});
it('inherits and deep-merges onDark component overrides', () => {
const base = defineTheme({
name: 'base',
onDark: {
components: {
card: {base: {borderColor: '#fff', backgroundColor: '#111'}},
badge: {base: {color: '#fff'}},
},
},
});
const child = defineTheme({
name: 'child',
extends: base,
onDark: {components: {card: {base: {borderColor: '#ccc'}}}},
});
expect(child.__onDark?.components?.card?.base).toEqual({
borderColor: '#ccc',
backgroundColor: '#111',
});
expect(child.__onDark?.components?.badge?.base).toEqual({color: '#fff'});
});
it('inherits __inputTokens so inherited [light, dark] tuples survive', () => {
const base = defineTheme({
name: 'base',
tokens: {'--color-accent': ['#111111', '#eeeeee']},
});
const child = defineTheme({
name: 'child',
extends: base,
tokens: {'--color-border': '#cccccc'},
});
expect(child.__inputTokens?.['--color-accent']).toEqual([
'#111111',
'#eeeeee',
]);
expect(child.__inputTokens?.['--color-border']).toBe('#cccccc');
});
it('__inputTokens from the child win over the base', () => {
const base = defineTheme({
name: 'base',
tokens: {'--color-accent': ['#111111', '#eeeeee']},
});
const child = defineTheme({
name: 'child',
extends: base,
tokens: {'--color-accent': '#ff0000'},
});
expect(child.__inputTokens?.['--color-accent']).toBe('#ff0000');
});
// The failure that motivated these: `extends` resolving to `undefined` (a
// named import that silently missed — see the theme-build resolution tests)
// used to inherit nothing and build a stylesheet that looked fine.
it('throws when extends is present but undefined', () => {
expect(() =>
defineTheme({
name: 'child',
extends: undefined,
tokens: {'--color-accent': '#ff0000'},
}),
).toThrow(/extends/);
});
it('throws when extends is not a theme', () => {
expect(() =>
defineTheme({
name: 'child',
// A module namespace object is the shape a bad import hands over.
extends: {foo: 'bar'} as unknown as DefinedTheme,
}),
).toThrow(/extends/);
});
it('accepts a pre-built theme module as a base', () => {
const built = {
name: 'built-base',
__built: true,
tokens: {'--color-accent': '#111111'},
} as DefinedTheme;
const child = defineTheme({name: 'child', extends: built});
expect(child.tokens['--color-accent']).toBe('#111111');
});
});