feat(Avatar): make fallback initials typography theme-reachable via derived vars

[Lee-Dongwook]

Issue

#4256

Summary

Avatar's fallback initials rendered at an inline size × 0.4 px value with a
hardcoded weight and color. Because that font size resolves to a literal px
value inline, no theme token could reach it — a consumer needing a different
fallback type scale (or weight/color/fill) had to abandon Avatar and hand-compose
their own.

This routes the fallback typography through the design system's existing
component-scoped derived-var mechanism (the same one Button uses for
--_button-radius), so a theme can re-scope the fallback per size tier.
Default rendering is byte-for-byte unchanged.

Motivation

An adjacent internal library renders Avatar fallback initials at a per-size type
scale (smaller avatars → proportionally smaller initials, regular weight, a muted
secondary-text color on a wash fill). Matching that by theming Astryx's Avatar was
impossible today, specifically because of the inline dynamic font size. The only
workaround was forking the component — which defeats the point of a themeable
design system.

Approach

Introduce four Avatar-scoped internal vars on the fallback surface, each read with
a default that reproduces today's exact output:

Internal var	CSS property	Default (unchanged)	Applies to
--_avatar-fallback-font-size	fontSize	size × 0.4px (per-size)	initials
--_avatar-fallback-font-weight	fontWeight	--font-weight-medium	initials
--_avatar-fallback-color	color	--color-text-secondary	initials + icon
--_avatar-fallback-background	backgroundColor	--color-neutral	initials + icon

Registered in derivedVarRegistry and documented in Avatar.doc.mjs
(theming.vars / theming.derived), matching the existing Button/Card
convention. No new global tokens; nothing added to tokens.stylex.ts.

Consumers can now theme the fallback without forking:

defineTheme({
  name: 'brand',
  components: {
    avatar: {
      base:      { fontWeight: 'var(--font-weight-normal)',
                   color: 'var(--color-text-secondary)',
                   backgroundColor: 'var(--color-accent-muted)' },
      'size:sm': { fontSize: '9px'  },
      'size:md': { fontSize: '13px' },
      'size:xl': { fontSize: '40px' },
    },
  },
})

Non-breaking

Every var defaults to the current value, so unthemed Avatars are unchanged. A new
Avatar.test.tsx case asserts the initials still render at size × 0.4 (sm =
9.6px) — via the seam — so a regression back to a bare literal fails loudly.

Scope / non-goals

The status-dot corner offsets use the same inline-dynamic pattern but are
out of scope — they're structural geometry, not a themeable design choice, and
weren't the reported gap.

Test plan

• Avatar.test.tsx — 7/7 pass, incl. new seam assertion
• generateThemeRules.test.ts — new cases prove components.avatar emits the
  internal vars for base and a per-size (size:sm) key
• derivedVarRegistry.test.ts — registry ↔ doc consistency (added
  Avatar: 'avatar' mapping)
• core theme suite 533/533 pass; typecheck + eslint clean
• Storybook: new Themed Fallback Type Scale story (default vs themed)

ScreenShot

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 24, 2026 12:59pm