Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/apps/storybook/stories/Avatar.stories.tsx b/apps/storybook/stories/Avatar.stories.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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', () => {