An open source design system that's fully customizable and agent ready
TypeScript
feat(Avatar): make fallback background a direct theme target (#4716)
Cindy Zhang5ec028a3bad8
diff --git a/.changeset/avatar-fallback-theme-target.md b/.changeset/avatar-fallback-theme-target.mdnew file mode 100644index 0000000000..6e4e8872c3--- /dev/null+++ b/.changeset/avatar-fallback-theme-target.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] Avatar: the fallback surface (initials and default icon) is now a direct theme target via the stable `astryx-avatar-fallback` class. Theme its background, text color, font weight, and per-size font size through the `avatar-fallback` component key (e.g. `components: { 'avatar-fallback': { base: { backgroundColor: '...' }, 'size:sm': { fontSize: '...' } } }`), replacing the internal `--_avatar-fallback-*` derived vars.++@cixzhangdiff --git a/apps/storybook/stories/Avatar.stories.tsx b/apps/storybook/stories/Avatar.stories.tsxindex 37a18508a4..a9daa706ec 100644--- a/apps/storybook/stories/Avatar.stories.tsx+++ b/apps/storybook/stories/Avatar.stories.tsx@@ -348,10 +348,26 @@ export const StatusWithSizes: Story = {<div {...stylex.props(styles.storyWrapper)}><h4 {...stylex.props(styles.heading)}>Status with Different Sizes</h4><div {...stylex.props(styles.row)}>- <Avatar name="AB" size="md" status={<AvatarStatusDot label="Online" />} />- <Avatar name="CD" size="lg" status={<AvatarStatusDot label="Online" />} />- <Avatar name="EF" size="xl" status={<AvatarStatusDot label="Online" />} />- <Avatar name="GH" size={72} status={<AvatarStatusDot label="Online" />} />+ <Avatar+ name="AB"+ size="md"+ status={<AvatarStatusDot label="Online" />}+ />+ <Avatar+ name="CD"+ size="lg"+ status={<AvatarStatusDot label="Online" />}+ />+ <Avatar+ name="EF"+ size="xl"+ status={<AvatarStatusDot label="Online" />}+ />+ <Avatar+ name="GH"+ size={72}+ status={<AvatarStatusDot label="Online" />}+ /></div></div>),@@ -607,19 +623,24 @@ export const NumericSizes: Story = {),};-// A theme can re-scope the fallback initials' typography per size tier via the-// Avatar-scoped derived vars — a smaller-per-size type scale, regular weight,-// and a muted secondary-text color on an accent wash fill — without forking the-// component. The default row is unchanged (size × 0.4, medium weight, neutral-// fill); only the themed row opts in.+// A theme can re-scope the fallback initials' typography without forking the+// component: weight, text color, the wash background, and the per-size+// font-size scale are all set on the `avatar-fallback` child target (font size+// through its size tiers). The default row is unchanged (size × 0.4, medium+// weight, neutral fill); only the themed row opts in.+//+// The themed colors deliberately use a hued token pair (blue) rather than+// `--color-accent-muted`/`--color-text-secondary`: in the monochrome neutral+// theme those resolve to the same grey as the default fallback, so the demo+// would look unthemed even though the theme rule is applying.const fallbackScaleTheme = defineTheme({name: 'avatar-fallback-scale',components: {- avatar: {+ 'avatar-fallback': {base: {fontWeight: 'var(--font-weight-normal)',- color: 'var(--color-text-secondary)',- backgroundColor: 'var(--color-accent-muted)',+ color: 'var(--color-text-blue)',+ backgroundColor: 'var(--color-background-blue)',},'size:xsm': {fontSize: '8px'},'size:sm': {fontSize: '9px'},@@ -644,7 +665,7 @@ export const ThemedFallbackScale: Story = {</div><h4 {...stylex.props(styles.heading)}>- Themed fallback (per-size scale, regular weight, wash fill)+ Themed fallback (per-size scale, regular weight, blue wash)</h4><Theme theme={fallbackScaleTheme} mode="light"><div {...stylex.props(styles.row)}>@@ -658,3 +679,49 @@ export const ThemedFallbackScale: Story = {</div>),};++// The fallback surface (initials AND the default person icon) is a direct theme+// target via the stable `astryx-avatar-fallback` class. Setting a background on+// the `avatar-fallback` component key paints the fill on the element that+// actually renders it — no per-component override needed. Both fallback kinds+// pick up the same themed background.+//+// `--color-accent` / `--color-on-accent` gives a full-contrast flip against the+// default grey wash in every shipped theme, so the themed row reads as themed+// at a glance (a muted token would land within a shade of the default here).+const fallbackBackgroundTheme = defineTheme({+ name: 'avatar-fallback-background',+ components: {+ 'avatar-fallback': {+ base: {+ backgroundColor: 'var(--color-accent)',+ color: 'var(--color-on-accent)',+ },+ },+ },+});++export const ThemedFallbackBackground: Story = {+ name: 'Themed Fallback Background',+ render: () => (+ <div {...stylex.props(styles.storyWrapper)}>+ <h4 {...stylex.props(styles.heading)}>Default fallback background</h4>+ <div {...stylex.props(styles.row)}>+ <Avatar name="Ada Lovelace" size="lg" />+ <Avatar name="Grace Hopper" size="lg" />+ <Avatar size="lg" />+ </div>++ <h4 {...stylex.props(styles.heading)}>+ Themed fallback background (solid accent on initials and icon)+ </h4>+ <Theme theme={fallbackBackgroundTheme} mode="light">+ <div {...stylex.props(styles.row)}>+ <Avatar name="Ada Lovelace" size="lg" />+ <Avatar name="Grace Hopper" size="lg" />+ <Avatar size="lg" />+ </div>+ </Theme>+ </div>+ ),+};diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjsindex 8ce16949fb..9d0b110330 100644--- a/packages/core/src/Avatar/Avatar.doc.mjs+++ b/packages/core/src/Avatar/Avatar.doc.mjs@@ -29,21 +29,10 @@ export const docs = {theming: {targets: [{className: 'astryx-avatar', visualProps: ['size']},+ {className: 'astryx-avatar-fallback', visualProps: ['size']},{className: 'astryx-avatar-status-dot', visualProps: ['variant']},{className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},],- vars: [- {name: '--_avatar-fallback-font-size', description: 'Initials font size; default is proportional to the avatar size (size × 0.4). Override per size tier (e.g. size:sm) for a custom type scale.', default: 'calc(avatar-size × 0.4)', private: true},- {name: '--_avatar-fallback-font-weight', description: 'Initials font weight', default: 'var(--font-weight-medium)', private: true},- {name: '--_avatar-fallback-color', description: 'Fallback text and default-icon color', default: 'var(--color-text-secondary)', private: true},- {name: '--_avatar-fallback-background', description: 'Fallback wash background fill', default: 'var(--color-neutral)', private: true},- ],- derived: [- {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},- {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},- {property: 'color', vars: ['--_avatar-fallback-color']},- {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},- ],},description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',props: [diff --git a/packages/core/src/Avatar/Avatar.test.tsx b/packages/core/src/Avatar/Avatar.test.tsxindex 1098c40b7a..3989209ccd 100644--- a/packages/core/src/Avatar/Avatar.test.tsx+++ b/packages/core/src/Avatar/Avatar.test.tsx@@ -37,17 +37,32 @@ describe('Avatar', () => {expect(innerImg).toHaveAttribute('alt', '');});- it('renders fallback initials through the themeable font-size var, not a bare px literal', () => {+ it('renders fallback initials at the proportional size via a StyleX class, not an inline property', () => {render(<Avatar name="Ada Lovelace" size="sm" data-testid="a" />);const initials = screen.getByText('AL');- // The seam: the dynamic font size resolves to the Avatar-scoped var (with- // the proportional `size × 0.4` default baked in as the fallback), so a- // theme can re-scope it per size. A regression to a bare px literal would- // break theming.+ // The default proportional size (sm = 24 × 0.4 = 9.6px) is fed to StyleX as+ // a dynamic value: StyleX applies `font-size` through a class and sets only+ // the computed value inline (as a custom property). Because the property+ // lands via a class, a theme's `.astryx-avatar-fallback.<size>` rule in the+ // theme layer overrides it per size tier — no internal var seam needed.const style = initials.getAttribute('style') ?? '';- expect(style).toContain('var(--_avatar-fallback-font-size,');- // Default still reproduces the proportional scale (sm = 24 × 0.4 = 9.6px).- expect(style).toMatch(/var\(--_avatar-fallback-font-size,\s*9\.6\d*px\)/);+ expect(style).toMatch(/9\.6\d*px/);+ // Regression guard: the seam must NOT reintroduce the removed internal var.+ expect(style).not.toContain('--_avatar-fallback-font-size');+ });++ it('marks the fallback surface with the stable theming class (initials and icon)', () => {+ // The background is themed directly on `.astryx-avatar-fallback`, so both+ // the initials and the default-icon fallback must carry the class.+ const {rerender} = render(<Avatar name="Ada Lovelace" />);+ expect(screen.getByText('AL').className).toContain(+ 'astryx-avatar-fallback',+ );++ rerender(<Avatar />);+ const icon = document.querySelector('.astryx-avatar-fallback');+ expect(icon).not.toBeNull();+ expect(icon?.querySelector('svg')).not.toBeNull();});it('retries a new src after a previous src failed to load', () => {diff --git a/packages/core/src/Avatar/Avatar.tsx b/packages/core/src/Avatar/Avatar.tsxindex cd2774ad05..602e79f03d 100644--- a/packages/core/src/Avatar/Avatar.tsx+++ b/packages/core/src/Avatar/Avatar.tsx@@ -112,9 +112,9 @@ const styles = stylex.create({display: 'inline-flex',flexShrink: 0,// The wrapper is not clipped (so the status dot can overflow), so it must be- // rounded itself: a themed fallback background lands on `.astryx-avatar` (the- // class-bearing wrapper) as well as the internal var, and an unrounded- // wrapper would show that fill as square corners behind the circular content.+ // rounded itself: a theme can set a background on the `.astryx-avatar`+ // wrapper, and an unrounded wrapper would show that fill as square corners+ // behind the circular content.borderRadius: radiusVars['--radius-full'],},content: {@@ -136,14 +136,15 @@ const styles = stylex.create({justifyContent: 'center',width: '100%',height: '100%',- // Fallback surface (initials + default icon). Each property reads an- // Avatar-scoped internal var so a theme can re-scope the fallback wash and- // initials weight/color without forking; the defaults reproduce today's- // exact output. See derivedVarRegistry (avatar) + Avatar.doc.mjs theming.- backgroundColor: `var(--_avatar-fallback-background, ${colorVars['--color-neutral']})`,- color: `var(--_avatar-fallback-color, ${colorVars['--color-text-secondary']})`,+ // Fallback surface (initials + default icon). Background, text color,+ // weight, and per-size font size are all themed directly via the stable+ // `.astryx-avatar-fallback` class target (font size through its size+ // variant, `.astryx-avatar-fallback.<size>`), so the defaults here are+ // plain values with no internal-var seam. See Avatar.doc.mjs theming.+ backgroundColor: colorVars['--color-neutral'],+ color: colorVars['--color-text-secondary'],fontFamily: typographyVars['--font-family-body'],- fontWeight: `var(--_avatar-fallback-font-weight, ${fontWeightVars['--font-weight-medium']})`,+ fontWeight: fontWeightVars['--font-weight-medium'],textTransform: 'uppercase',},status: {@@ -205,13 +206,12 @@ const dynamicStyles = stylex.create({width: size,height: size,}),- // Initials font size defaults to the proportional `size × ratio` scale but is- // reachable via the `--_avatar-fallback-font-size` derived var, so a theme can- // set a per-size type scale (e.g. `components.avatar['size:sm']`).+ // Initials font size defaults to the proportional `size × ratio` scale. It's+ // a StyleX dynamic style, so the value lands via a class (not an inline+ // property) — a theme's `.astryx-avatar-fallback.<size>` rule in the theme+ // layer overrides it per size tier, no internal var needed.fontSize: (size: number) => ({- fontSize: `var(--_avatar-fallback-font-size, ${- size * INITIALS_FONT_SIZE_RATIO- }px)`,+ fontSize: `${size * INITIALS_FONT_SIZE_RATIO}px`,}),statusPosition: (size: number) => ({bottom: size * CIRCLE_EDGE_OFFSET_RATIO,@@ -549,15 +549,22 @@ export function Avatar({)}{showInitials && (<div- {...stylex.props(- styles.fallback,- dynamicStyles.fontSize(numericSize),+ {...mergeProps(+ themeProps('avatar-fallback', {size: resolvedSize}),+ stylex.props(+ styles.fallback,+ dynamicStyles.fontSize(numericSize),+ ),)}>{getInitials(name)}</div>)}{showIcon && (- <div {...stylex.props(styles.fallback)}>+ <div+ {...mergeProps(+ themeProps('avatar-fallback', {size: resolvedSize}),+ stylex.props(styles.fallback),+ )}><DefaultIcon size={numericSize} /></div>)}diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.tsindex 61d3a3d992..94b52e14a3 100644--- a/packages/core/src/theme/derivedVarRegistry.test.ts+++ b/packages/core/src/theme/derivedVarRegistry.test.ts@@ -186,7 +186,6 @@ function discoverComponents(): ComponentInfo[] {// ---------------------------------------------------------------------------const DIR_TO_REGISTRY_KEY: Record<string, string> = {- Avatar: 'avatar',Banner: 'banner',Button: 'button',Card: 'card',diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.tsindex 88449e8ee6..3a037c2f4a 100644--- a/packages/core/src/theme/derivedVarRegistry.ts+++ b/packages/core/src/theme/derivedVarRegistry.ts@@ -35,12 +35,6 @@ export interface DerivedVarEntry {* entries share the same property.*/export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {- avatar: [- {property: 'fontSize', vars: ['--_avatar-fallback-font-size']},- {property: 'fontWeight', vars: ['--_avatar-fallback-font-weight']},- {property: 'color', vars: ['--_avatar-fallback-color']},- {property: 'backgroundColor', vars: ['--_avatar-fallback-background']},- ],banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],button: [{property: 'borderRadius', vars: ['--_button-radius']}],card: [diff --git a/packages/core/src/theme/generateThemeRules.test.ts b/packages/core/src/theme/generateThemeRules.test.tsindex df61188b18..d8c4f886b8 100644--- a/packages/core/src/theme/generateThemeRules.test.ts+++ b/packages/core/src/theme/generateThemeRules.test.ts@@ -385,46 +385,46 @@ describe('derived var expansion', () => {expect(rule).toContain('--_button-radius: 8px');});- it('emits internal vars for avatar fallback typography (base)', () => {+ it('emits direct rules for avatar fallback background, color, and weight', () => {const theme = defineTheme({- name: 'test-derived-avatar',+ name: 'test-avatar-fallback',components: {- avatar: {+ 'avatar-fallback': {base: {- fontWeight: 'var(--font-weight-normal)',- color: 'var(--color-text-secondary)',backgroundColor: 'var(--color-accent-muted)',+ color: 'var(--color-text-secondary)',+ fontWeight: 'var(--font-weight-normal)',},},},});const rules = generateThemeRules(theme);- const rule = rules.find(r => r.includes('.astryx-avatar'));+ const rule = rules.find(r => r.includes('.astryx-avatar-fallback'));expect(rule).toBeDefined();- expect(rule).toContain(- '--_avatar-fallback-font-weight: var(--font-weight-normal)',- );- expect(rule).toContain(- '--_avatar-fallback-color: var(--color-text-secondary)',- );- expect(rule).toContain(- '--_avatar-fallback-background: var(--color-accent-muted)',- );+ expect(rule).toContain('background-color: var(--color-accent-muted)');+ expect(rule).toContain('color: var(--color-text-secondary)');+ expect(rule).toContain('font-weight: var(--font-weight-normal)');+ // These are direct class targets now, not internal derived vars.+ expect(rule).not.toContain('--_avatar-fallback-background');+ expect(rule).not.toContain('--_avatar-fallback-color');+ expect(rule).not.toContain('--_avatar-fallback-font-weight');});- it('emits a per-size fallback font-size for avatar (size:sm)', () => {+ it('emits a direct per-size font-size rule for the avatar fallback target', () => {const theme = defineTheme({- name: 'test-derived-avatar-size',+ name: 'test-avatar-fallback-size',components: {- avatar: {+ 'avatar-fallback': {'size:sm': {fontSize: '9px'},},},});const rules = generateThemeRules(theme);- const rule = rules.find(r => r.includes('.astryx-avatar.sm'));+ const rule = rules.find(r => r.includes('.astryx-avatar-fallback.sm'));expect(rule).toBeDefined();- expect(rule).toContain('--_avatar-fallback-font-size: 9px');+ expect(rule).toContain('font-size: 9px');+ // Direct class target now — no internal derived var.+ expect(rule).not.toContain('--_avatar-fallback-font-size');});it('does not emit derived vars for components without registry entries', () => {