@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/i18n/getLocaleDirection.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file getLocaleDirection.ts
+ * @input BCP 47 locale tag
+ * @output 'ltr' | 'rtl'
+ * @position Server-safe helper for computing text direction from a locale.
+ *   Callable in React Server Components / Next.js layouts to set <html dir>.
+ *
+ * Uses Intl.Locale.getTextInfo() (CLDR-backed) with a try/catch fallback to
+ * 'ltr'. React 19 baseline covers all target browsers + Node ≥20; the older
+ * accessor form (`.textInfo`) is handled as a fallback for defensive parity.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationProvider.tsx (uses this to derive default)
+ * - /packages/core/src/i18n/useDirection.ts (client-side hook counterpart)
+ * - /packages/core/src/i18n/index.ts (public export)
+ */
+
+export function getLocaleDirection(locale: string): 'ltr' | 'rtl' {
+  try {
+    const loc = new Intl.Locale(locale);
+    // @ts-expect-error — older engines expose accessor form `.textInfo`
+    const info = typeof loc.getTextInfo === 'function' ? loc.getTextInfo() : loc.textInfo;
+    return info?.direction === 'rtl' ? 'rtl' : 'ltr';
+  } catch {
+    return 'ltr';
+  }
+}

package/src/i18n/index.ts

@@ -10,10 +10,14 @@
  * The public API is deliberately small:
  *   - InternationalizationProvider — provider component
  *   - useTranslator               — hook returning a translator function
+ *   - useDirection                — hook returning the ambient text direction
+ *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/index.ts
+ * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts
  */
 
 export {InternationalizationProvider} from './InternationalizationProvider';
@@ -22,6 +26,8 @@ export {InternationalizationContext} from './InternationalizationContext';
 export type {InternationalizationContextValue} from './InternationalizationContext';
 export {useTranslator} from './useTranslator';
 export type {TranslatorFn} from './useTranslator';
+export {useDirection} from './useDirection';
+export {getLocaleDirection} from './getLocaleDirection';
 export type {Translator} from './translator';
 export type {
   Locale,

package/src/i18n/useDirection.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useDirection.ts
+ * @input InternationalizationContext (via use())
+ * @output 'ltr' | 'rtl'
+ * @position Client hook for reading the ambient text direction. Returns 'ltr'
+ *   when called outside a provider (matches the silent-en-fallback pattern of
+ *   useTranslator).
+ *
+ * Use this in components that need to swap directional icons, mirror
+ * behavioral logic (slider math, keyboard nav), or apply direction-specific
+ * styling that CSS logical properties can't express.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/i18n/InternationalizationContext.ts
+ * - /packages/core/src/i18n/getLocaleDirection.ts (server-safe counterpart)
+ * - /packages/core/src/i18n/index.ts
+ */
+
+import {use} from 'react';
+import {InternationalizationContext} from './InternationalizationContext';
+
+export function useDirection(): 'ltr' | 'rtl' {
+  const ctx = use(InternationalizationContext);
+  return ctx.direction;
+}

package/src/i18n/useTranslator.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useTranslator',
   displayName: 'useTranslator',
@@ -31,7 +31,7 @@ export const docs = {
   importPath: '@astryxdesign/core',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Hook returning a translator function bound to the current InternationalizationProvider context. Call with an ICU MessageFormat key and values to get the formatted string for the active locale.',

package/src/index.ts

@@ -168,25 +168,29 @@ export * from './hooks';
 export * from './utils';
 
 // Theme
+export type {TextColorMap} from './Text';
 export * from './theme';
 
 // Internationalization
 export * from './i18n';
 
-// Doc types — for external library authors writing .doc.mjs files
+// Doc types — for external library authors writing .doc.mjs files.
+// @deprecated Import these from `@astryxdesign/cli/authoring` instead. These
+// re-exports are kept for one release cycle and will be removed; `astryx upgrade`
+// repoints them automatically.
 export type {
   ComponentDoc,
   SingleComponentDoc,
   MultiComponentDoc,
-  PropDoc,
+  ComponentPropDoc,
   ComponentEntry,
-  ThemingTarget,
-  ComponentVar,
-  DerivedVar,
-  TranslationDoc,
-  GroupDoc,
+  ComponentThemingTarget,
+  ComponentThemingVar,
+  ComponentThemingDerivedVar,
+  ComponentTranslationDoc,
+  ComponentGroupDoc,
   ReferenceDoc,
   ReferenceSection,
-  ContentBlock,
-  TokenPreviewType,
-} from './docs-types';
+  ReferenceContentBlock,
+  ReferenceTokenPreviewType,
+} from '@astryxdesign/cli/authoring';

package/src/reset.css

@@ -360,32 +360,6 @@
     -webkit-tap-highlight-color: transparent;
   }
 
-  /* ===========================================================================
-     Touch Devices
-     =========================================================================== */
-
-  /*
-   * Suppress focus-visible outlines on touch-only devices.
-   *
-   * Focus rings exist to show keyboard users where focus is. On devices
-   * with no hover capability and a coarse pointer (phones, tablets),
-   * there's no keyboard navigation — focus rings are visual noise that
-   * can flash on tap, on dialog open (showModal auto-focus), or on
-   * programmatic focus.
-   *
-   * This targets touch-only devices specifically:
-   * - (hover: none) — no hover capability (not a mouse)
-   * - (pointer: coarse) — imprecise pointer (finger, not stylus)
-   *
-   * Hybrid devices (laptop with touchscreen) are NOT affected because
-   * their primary pointer is fine (trackpad/mouse) and hover is available.
-   */
-  @media (hover: none) and (pointer: coarse) {
-    :where(:focus-visible) {
-      outline: none;
-    }
-  }
-
   /* ===========================================================================
      Color Scheme
      =========================================================================== */

package/src/reset.test.ts

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Tests for reset.css invariants that components rely on.
+ *
+ * reset.css is a plain stylesheet, so these tests assert on its source
+ * text (same approach as the reset.css baseline checks in
+ * theme/onMediaTokens.test.ts and AspectRatio/AspectRatio.test.tsx).
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import {beforeAll, describe, expect, it} from 'vitest';
+
+describe('reset.css accessibility invariants', () => {
+  let ruleBlocks: {selector: string; body: string}[];
+
+  beforeAll(() => {
+    const resetCSS = fs.readFileSync(
+      path.resolve(__dirname, './reset.css'),
+      'utf-8',
+    );
+    // Strip comments, then collect every innermost `selector { body }`
+    // block. `[^{}]` keeps at-rule preludes (@media, @layer) out of the
+    // selector capture, since their own `{` terminates any earlier match.
+    const stripped = resetCSS.replace(/\/\*[\s\S]*?\*\//g, '');
+    ruleBlocks = [...stripped.matchAll(/([^{}]+)\{([^{}]*)\}/g)].map(
+      ([, selector, body]) => ({selector: selector.trim(), body}),
+    );
+  });
+
+  it('parses rule blocks out of reset.css', () => {
+    // Guards the WCAG assertion below against silently passing if the
+    // block parsing ever breaks.
+    expect(ruleBlocks.length).toBeGreaterThan(20);
+    expect(
+      ruleBlocks.some(({body}) => body.includes('box-sizing: border-box')),
+    ).toBe(true);
+  });
+
+  /**
+   * WCAG 2.4.7 (Focus Visible, Level AA): keyboard focus indicators must
+   * not be suppressed. `:focus-visible` only matches keyboard-style focus,
+   * so any `outline: none` on it removes the focus indicator for keyboard
+   * users — and a `@media (hover: none) and (pointer: coarse)` guard does
+   * not exempt keyboard users on coarse-pointer devices (iPad/phone with a
+   * Bluetooth keyboard, switch-control users).
+   */
+  it('does not suppress :focus-visible outlines (WCAG 2.4.7)', () => {
+    const focusVisibleBlocks = ruleBlocks.filter(({selector}) =>
+      selector.includes(':focus-visible'),
+    );
+    for (const {selector, body} of focusVisibleBlocks) {
+      expect
+        .soft(body, `":focus-visible" rule "${selector}" must keep the outline`)
+        .not.toMatch(/outline(?:-style|-width)?\s*:\s*(?:none|0)/);
+    }
+  });
+});

package/src/theme/MediaTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'MediaTheme',
@@ -100,7 +100,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/SyntaxTheme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'SyntaxTheme',
@@ -74,7 +74,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/Theme.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Theme',
@@ -86,7 +86,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:

package/src/theme/defineTheme.ts

@@ -239,9 +239,15 @@ export interface DefineThemeInput {
    * categorical hues, and fixed tokens (on-dark/on-light) use defaults.
    * Explicit `tokens` entries always take precedence.
    *
+   * `accent` is optional — omit it for a neutral-only theme, which keeps
+   * the default accent tokens and only themes the neutrals.
+   *
    * @example
    * ```tsx
    * color: { accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard' }
+   *
+   * // Neutral-only — accent tokens stay at their defaults
+   * color: { neutralStyle: 'warm' }
    * ```
    */
   color?: ColorScaleConfig;

package/src/theme/derivedVarRegistry.test.ts

@@ -186,6 +186,7 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 const DIR_TO_REGISTRY_KEY: Record<string, string> = {
+  Avatar: 'avatar',
   Banner: 'banner',
   Button: 'button',
   Card: 'card',

package/src/theme/derivedVarRegistry.ts

@@ -35,6 +35,12 @@ 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: [

package/src/theme/expandColorScale.test.ts

@@ -4,6 +4,19 @@ import {describe, it, expect} from 'vitest';
 import {expandColorScale} from './expandColorScale';
 import {defineTheme} from './defineTheme';
 import {generateThemeRules} from './generateThemeRules';
+import {resolveThemeTokens} from './tokens';
+import {colorDefaults} from './tokens.stylex';
+
+/** Light-mode half of colorDefaults['--color-accent'] — the hue an accent-less config seeds from. */
+const DEFAULT_ACCENT = '#0064E0';
+const DEFAULT_ACCENT_DARK = '#2694FE';
+
+/** The three tokens that only exist when a seed accent is supplied. */
+const ACCENT_TOKENS = [
+  '--color-accent',
+  '--color-accent-muted',
+  '--color-on-accent',
+] as const;
 
 describe('expandColorScale', () => {
   it('produces all expected token keys', () => {
@@ -86,6 +99,82 @@ describe('expandColorScale', () => {
   });
 });
 
+describe('expandColorScale — neutral-only themes (#2279)', () => {
+  it('accent is optional — a config without one expands', () => {
+    const tokens = expandColorScale({neutralStyle: 'warm'});
+    expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);
+  });
+
+  it('expands an empty config', () => {
+    const tokens = expandColorScale({});
+    expect(tokens['--color-background-surface']).toMatch(/^light-dark\(#/);
+    expect(tokens).not.toHaveProperty('--color-accent');
+  });
+
+  it('omits the accent tokens so they fall through to colorDefaults', () => {
+    const tokens = expandColorScale({neutralStyle: 'warm'});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).not.toHaveProperty(key);
+    }
+    // ...and the reference tokens still point at whatever --color-accent resolves to.
+    expect(tokens['--color-text-accent']).toBe('var(--color-accent)');
+    expect(tokens['--color-icon-accent']).toBe('var(--color-accent)');
+  });
+
+  it('seeds the neutral palettes from the light half of the default accent', () => {
+    // Drift guard: the module's DEFAULT_ACCENT_SEED is private, so pin the
+    // colorDefaults value it is copied from. Re-coloring the default accent
+    // without re-seeding would silently change every neutral-only theme.
+    expect(colorDefaults['--color-accent']).toBe(
+      `light-dark(${DEFAULT_ACCENT}, ${DEFAULT_ACCENT_DARK})`,
+    );
+
+    const neutralOnly = expandColorScale({neutralStyle: 'warm'});
+    const seeded = expandColorScale({
+      accent: DEFAULT_ACCENT,
+      neutralStyle: 'warm',
+    });
+    for (const [key, value] of Object.entries(seeded)) {
+      if ((ACCENT_TOKENS as ReadonlyArray<string>).includes(key)) {
+        continue;
+      }
+      expect(neutralOnly[key], key).toBe(value);
+    }
+  });
+
+  it('honours neutralStyle and contrast without an accent', () => {
+    const warm = expandColorScale({neutralStyle: 'warm'});
+    const cool = expandColorScale({neutralStyle: 'cool'});
+    expect(warm['--color-neutral']).not.toBe(cool['--color-neutral']);
+
+    const high = expandColorScale({contrast: 'high'});
+    const standard = expandColorScale({contrast: 'standard'});
+    expect(high['--color-text-primary']).not.toBe(
+      standard['--color-text-primary'],
+    );
+  });
+
+  it('does not re-color themes that do pass an accent', () => {
+    // Seeding from the default hex derives a DIFFERENT accent than the default
+    // token holds, so "just default the seed" is not behavior-preserving —
+    // omitting the tokens is the only way a neutral-only theme keeps the
+    // default accent.
+    const tokens = expandColorScale({accent: DEFAULT_ACCENT});
+    expect(tokens['--color-accent']).toMatch(/^light-dark\(#/);
+    expect(tokens['--color-accent']).not.toBe(colorDefaults['--color-accent']);
+  });
+
+  it('treats an empty accent as supplied, not absent', () => {
+    // '' is falsy but not nullish. Only an absent accent is neutral-only; a
+    // supplied-but-malformed one keeps its pre-#2279 behavior (the hex parser
+    // falls back to black) rather than silently dropping the accent tokens.
+    const tokens = expandColorScale({accent: ''});
+    for (const key of ACCENT_TOKENS) {
+      expect(tokens).toHaveProperty(key);
+    }
+  });
+});
+
 describe('expandColorScale + defineTheme integration', () => {
   it('explicit token overrides win over generated values', () => {
     const theme = defineTheme({
@@ -110,4 +199,59 @@ describe('expandColorScale + defineTheme integration', () => {
     // The base token itself stays a resolved color pair.
     expect(css).toMatch(/--color-accent: light-dark\(#/);
   });
+
+  it('a neutral-only theme leaves the accent tokens at their defaults (#2279)', () => {
+    const theme = defineTheme({
+      name: 'test-neutral-only',
+      color: {neutralStyle: 'warm'},
+    });
+    for (const key of ACCENT_TOKENS) {
+      expect(theme.tokens).not.toHaveProperty(key);
+    }
+    // Neutrals are still themed.
+    expect(theme.tokens['--color-background-surface']).toMatch(
+      /^light-dark\(#/,
+    );
+
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).not.toContain('--color-accent:');
+    expect(css).not.toContain('--color-on-accent:');
+    expect(css).toContain('--color-background-surface:');
+  });
+
+  it('a neutral-only theme resolves accent tokens to the defaults at runtime (#2279)', () => {
+    // The CSS side falls through by simply not emitting the tokens. The JS side
+    // (useTheme/resolveThemeTokens) has to agree: the omitted tokens come back
+    // from tokenDefaults, and the var() references the theme DOES emit resolve
+    // against them instead of leaking a literal 'var(--color-accent)'.
+    const theme = defineTheme({
+      name: 'test-neutral-only-runtime',
+      color: {neutralStyle: 'warm'},
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    expect(light['--color-accent']).toBe(DEFAULT_ACCENT);
+    expect(light['--color-text-accent']).toBe(DEFAULT_ACCENT);
+    expect(light['--color-icon-accent']).toBe(DEFAULT_ACCENT);
+
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+    expect(dark['--color-accent']).toBe(DEFAULT_ACCENT_DARK);
+    expect(dark['--color-text-accent']).toBe(DEFAULT_ACCENT_DARK);
+  });
+
+  it('an explicit accent token still wins on a neutral-only theme (#2279)', () => {
+    // Neutral scale from HCT + a hand-picked accent: the tokens map is the only
+    // source of --color-accent, so the reference tokens follow it.
+    const theme = defineTheme({
+      name: 'test-neutral-only-explicit-accent',
+      color: {neutralStyle: 'warm'},
+      tokens: {'--color-accent': ['#AA0000', '#FF5555']},
+    });
+    expect(
+      resolveThemeTokens(theme, {mode: 'light'})['--color-text-accent'],
+    ).toBe('#AA0000');
+
+    const css = generateThemeRules(theme).join('\n');
+    expect(css).toContain('--color-text-accent: var(--color-accent);');
+  });
 });

package/src/theme/expandColorScale.ts

@@ -2,7 +2,7 @@
 
 /**
  * @file expandColorScale.ts
- * @input Color scale configuration { accent, neutralStyle?, contrast? }
+ * @input Color scale configuration { accent?, neutralStyle?, contrast? }
  * @output Token overrides for derivable color tokens
  * @position Theme utility; consumed by defineTheme.ts
  *
@@ -11,6 +11,10 @@
  * derive from the accent — status colors, categorical hues, and fixed
  * tokens (on-dark/on-light) fall through to colorDefaults.
  *
+ * `accent` is optional: a neutral-only config still gets the full neutral
+ * ramp (seeded from the default accent's hue) while the accent tokens
+ * themselves fall through to colorDefaults, same as the tokens above.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/defineTheme.ts
  */
@@ -31,11 +35,21 @@ import {hexToHct, tonalPalette, hexWithAlpha} from './hct';
  *
  * // With customization
  * { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }
+ *
+ * // Neutral-only — keeps the default accent, themes the neutrals
+ * { neutralStyle: 'warm' }
  * ```
  */
 export interface ColorScaleConfig {
-  /** Seed accent color as hex (#RRGGBB). Everything derives from this. */
-  accent: string;
+  /**
+   * Seed accent color as hex (#RRGGBB). Everything derives from this.
+   *
+   * Optional. When omitted, the neutral palettes are seeded from the
+   * default accent's hue and the accent tokens (--color-accent,
+   * --color-accent-muted, --color-on-accent) are not generated — they
+   * fall through to colorDefaults.
+   */
+  accent?: string;
 
   /**
    * Neutral tone warmth. Controls how much of the seed's hue bleeds
@@ -69,6 +83,14 @@ const NEUTRAL_VARIANT_CHROMA: Record<string, number> = {
   neutral: 6,
 };
 
+/**
+ * Hue source for accent-less configs — the light half of
+ * colorDefaults['--color-accent'] (a test guards the two against drift).
+ * Only its hue reaches the output: the accent tokens stay ungenerated, so
+ * they keep their colorDefaults values rather than this seed's derivation.
+ */
+const DEFAULT_ACCENT_SEED = '#0064E0';
+
 // =============================================================================
 // Computation
 // =============================================================================
@@ -89,18 +111,23 @@ function accentWithAlpha(alpha: number): string {
  * --color-on-dark/on-light) are NOT generated — they fall through
  * to colorDefaults.
  *
+ * Without an `accent`, the accent tokens join that fall-through set: the
+ * neutrals are seeded from the default accent's hue, and --color-accent,
+ * --color-accent-muted and --color-on-accent keep their colorDefaults values.
+ *
  * @example
  * ```
  * const tokens = expandColorScale({ accent: '#0064E0' });
  * // tokens['--color-accent'] === 'light-dark(#..., #...)'
+ *
+ * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });
+ * // neutralOnly['--color-accent'] === undefined
  * ```
  */
-export function expandColorScale(
-  config: ColorScaleConfig,
-): ColorScaleTokens {
+export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
   const {accent, neutralStyle = 'cool', contrast = 'standard'} = config;
 
-  const seed = hexToHct(accent);
+  const seed = hexToHct(accent ?? DEFAULT_ACCENT_SEED);
   const seedHue = seed.hue;
 
   const primaryChroma = Math.max(seed.chroma, 48);
@@ -119,14 +146,25 @@ export function expandColorScale(
   const textSecondaryDarkTone = isHigh ? 80 : 70;
 
   return {
-    // Core semantic
-    '--color-accent': ld(P[40], P[80]),
-    // Derived accent tokens reference --color-accent instead of baking its
-    // resolved hex, so a scoped override of the base token re-accents the
-    // whole subtree at runtime. --color-on-accent stays baked: it is a
-    // contrast computation against the accent, which CSS cannot express.
-    '--color-accent-muted': ld(accentWithAlpha(0.2), accentWithAlpha(0.25)),
-    '--color-on-accent': ld(P[100], P[20]),
+    // Core semantic — only with a seed accent. Without one these fall through
+    // to colorDefaults, whose --color-accent is NOT what the default seed
+    // derives: defaulting the seed instead of omitting the tokens would
+    // recolor every neutral-only theme. Nullish and not truthy, matching the
+    // seed above, so a supplied-but-malformed accent keeps its old behavior.
+    ...(accent != null
+      ? {
+          '--color-accent': ld(P[40], P[80]),
+          // Derived accent tokens reference --color-accent instead of baking its
+          // resolved hex, so a scoped override of the base token re-accents the
+          // whole subtree at runtime. --color-on-accent stays baked: it is a
+          // contrast computation against the accent, which CSS cannot express.
+          '--color-accent-muted': ld(
+            accentWithAlpha(0.2),
+            accentWithAlpha(0.25),
+          ),
+          '--color-on-accent': ld(P[100], P[20]),
+        }
+      : null),
     '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
     '--color-background-surface': ld(N[99], N[10]),
     '--color-background-body': ld(N[95], N[5]),

package/src/theme/generateThemeRules.test.ts

@@ -385,6 +385,48 @@ describe('derived var expansion', () => {
     expect(rule).toContain('--_button-radius: 8px');
   });
 
+  it('emits internal vars for avatar fallback typography (base)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-avatar',
+      components: {
+        avatar: {
+          base: {
+            fontWeight: 'var(--font-weight-normal)',
+            color: 'var(--color-text-secondary)',
+            backgroundColor: 'var(--color-accent-muted)',
+          },
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-avatar'));
+    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)',
+    );
+  });
+
+  it('emits a per-size fallback font-size for avatar (size:sm)', () => {
+    const theme = defineTheme({
+      name: 'test-derived-avatar-size',
+      components: {
+        avatar: {
+          'size:sm': {fontSize: '9px'},
+        },
+      },
+    });
+    const rules = generateThemeRules(theme);
+    const rule = rules.find(r => r.includes('.astryx-avatar.sm'));
+    expect(rule).toBeDefined();
+    expect(rule).toContain('--_avatar-fallback-font-size: 9px');
+  });
+
   it('does not emit derived vars for components without registry entries', () => {
     const theme = defineTheme({
       name: 'test-no-derived',