@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/AppShell/AppShell.tsx

@@ -17,7 +17,7 @@ import React from 'react';
  * - /packages/core/src/AppShell/index.ts
  * - /packages/core/src/AppShell/AppShell.test.tsx
  * - /apps/storybook/stories/AppShell.stories.tsx
- * - /packages/cli/templates/blocks/components/AppShell/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AppShell/ (showcase blocks)
  */
 
 import {
@@ -55,6 +55,7 @@ import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
+import type {AppShellVariantMap} from './index';
 
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
@@ -101,25 +102,6 @@ export type AppShellBreakpoint = 'sm' | 'md' | 'lg' | 'none';
  * - `elevated`: Wash nav background with elevated surface content + border radius
  * @default 'elevated'
  */
-/**
- * Extensible variant map for AppShell.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/AppShell' {
- *   interface AppShellVariantMap {
- *     'glass': true;
- *   }
- * }
- * ```
- */
-export interface AppShellVariantMap {
-  wash: true;
-  surface: true;
-  section: true;
-  elevated: true;
-}
 
 /**
  * Navigation background style. Extensible via module augmentation of AppShellVariantMap.
@@ -359,6 +341,15 @@ const styles = stylex.create({
     fontWeight: fontWeightVars['--font-weight-semibold'],
     fontSize: typeScaleVars['--text-body-size'],
   },
+  // Programmatic focus target for the skip link. The main container is only
+  // focusable via tabIndex={-1} (never tabbable), so a focus ring around the
+  // entire content area would be noise rather than guidance — suppress it.
+  mainFocusTarget: {
+    outline: {
+      default: null,
+      ':focus': 'none',
+    },
+  },
 
   elevatedBackdrop: {
     position: 'absolute',
@@ -531,6 +522,13 @@ export function AppShell({
     [mobileNavIsControlled, mobileNavConfig],
   );
 
+  // Move focus to the main content container when the skip link is activated.
+  // Hash navigation alone doesn't reliably move focus in every browser, so
+  // focus the target explicitly (it's focusable via tabIndex={-1}).
+  const handleSkipLinkClick = useCallback(() => {
+    document.getElementById(MAIN_CONTENT_ID)?.focus();
+  }, []);
+
   const isFill = height === 'fill';
   const isAuto = height === 'auto';
 
@@ -675,6 +673,9 @@ export function AppShell({
     headerInner != null ? (
       <div
         ref={headerRef}
+        // Top-level banner landmark for the header region (topNav + banner).
+        // Safe here: the wrapper is never nested inside main/nav/other landmarks.
+        role="banner"
         {...mergeProps(
           themeProps('app-shell-header', {variant}),
           stylex.props(navAreaStyle, isAuto && styles.headerSticky),
@@ -723,8 +724,11 @@ export function AppShell({
       padding={contentPadding ?? 0}
       role="main"
       id={MAIN_CONTENT_ID}
+      // Focusable skip-link target (WCAG 2.4.1) — without tabIndex, several
+      // browsers won't move focus to the div when the skip link is activated.
+      tabIndex={-1}
       isScrollable={isFill}
-      xstyle={contentAreaStyle}>
+      xstyle={[contentAreaStyle, styles.mainFocusTarget]}>
       {children}
     </LayoutContent>
   );
@@ -800,9 +804,10 @@ export function AppShell({
         {/* Skip-to-content link */}
         <a
           href={`#${MAIN_CONTENT_ID}`}
+          onClick={handleSkipLinkClick}
           {...stylex.props(styles.skipLink)}
           data-testid="skip-to-content">
-          Skip to content
+          {t('@astryx.appShell.skipToContent')}
         </a>
 
         <Layout

package/src/AppShell/index.ts

@@ -11,12 +11,31 @@
  * SYNC: When modified, update this header and /packages/core/src/AppShell/AppShell.doc.mjs
  */
 
+/**
+ * Extensible variant map for AppShell.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/AppShell' {
+ *   interface AppShellVariantMap {
+ *     'glass': true;
+ *   }
+ * }
+ * ```
+ */
+export interface AppShellVariantMap {
+  wash: true;
+  surface: true;
+  section: true;
+  elevated: true;
+}
+
 export {AppShell} from './AppShell';
 export type {
   AppShellProps,
   AppShellBreakpoint,
   AppShellVariant,
-  AppShellVariantMap,
   MobileNavConfig,
 } from './AppShell';
 export {

package/src/AppShell/useAppShellMobile.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: 'useAppShellMobile',
   displayName: 'useAppShellMobile',
@@ -109,7 +109,7 @@ export const docs = {
   importPath: '@astryxdesign/core/AppShell',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
     'Reads/controls AppShell mobile nav context. Use for custom triggers, closing drawer after route changes, or syncing AppShell-adjacent mobile UI to the same breakpoint as mobile nav.',

package/src/AspectRatio/AspectRatio.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: 'AspectRatio',
@@ -62,7 +62,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'AspectRatio',
   displayName: 'Aspect Ratio',
@@ -105,7 +105,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'maintains specific aspect ratio for children',
   usage: {

package/src/AspectRatio/AspectRatio.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
  * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
  * - /apps/storybook/stories/AspectRatio.stories.tsx
- * - /packages/cli/templates/blocks/components/AspectRatio/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/AspectRatio/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/Avatar/Avatar.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: 'Avatar',
@@ -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: [
@@ -104,7 +93,7 @@ export const docs = {
       name: 'as',
       type: 'ElementType',
       description:
-        'Custom link component used when `href` is set (e.g. Next.js `Link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
+        'Custom link component used when `href` is set (e.g. `next/link`). Overrides the provider-level LinkProvider default. Only applies with `href`.',
     },
     {
       name: 'target',
@@ -128,7 +117,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -142,7 +131,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'person/team avatar w/ photo → initials → icon fallback chain',
   usage: {

package/src/Avatar/Avatar.test.tsx

@@ -37,17 +37,42 @@ 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('does not split an emoji surrogate pair when generating initials', () => {
+    render(<Avatar name="😀 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('😀A');
+  });
+
+  it('preserves a complete grapheme when generating initials', () => {
+    render(<Avatar name="🇬🇧 Ada" data-testid="avatar" />);
+    expect(screen.getByTestId('avatar')).toHaveTextContent('🇬🇧A');
   });
 
   it('retries a new src after a previous src failed to load', () => {

package/src/Avatar/Avatar.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/Avatar/Avatar.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Avatar/index.ts (exports if types change)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Avatar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  *
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
@@ -31,6 +31,7 @@ import {AvatarSizeContext} from './AvatarSizeContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
 import {mergeProps, mergeRefs} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useTooltip} from '../Tooltip/useTooltip';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
@@ -112,9 +113,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 +137,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: {
@@ -152,16 +154,6 @@ const styles = stylex.create({
   // Visible focus ring for the name-tooltip tab stop, matching the repo-wide
   // focus-visible outline treatment (see Timestamp, Token, Thumbnail). Only
   // applied when a tooltip is active so keyboard users can reveal it.
-  focusable: {
-    outline: {
-      default: null,
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':focus-visible': '2px',
-    },
-  },
   // Reset the intrinsic styling of the interactive element (<a>/<button>) so it
   // is a transparent, correctly-sized wrapper around the avatar visuals. The
   // element carries the focus-visible accent ring for keyboard users.
@@ -178,22 +170,6 @@ const styles = stylex.create({
     cursor: 'pointer',
     // Match the avatar's circular shape so the focus ring hugs it.
     borderRadius: radiusVars['--radius-full'],
-    outlineWidth: {
-      default: 0,
-      ':focus-visible': 2,
-    },
-    outlineStyle: {
-      default: 'none',
-      ':focus-visible': 'solid',
-    },
-    outlineColor: {
-      default: null,
-      ':focus-visible': colorVars['--color-accent'],
-    },
-    outlineOffset: {
-      default: 0,
-      ':focus-visible': 2,
-    },
   },
 });
 
@@ -205,18 +181,22 @@ 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,
-    right: size * CIRCLE_EDGE_OFFSET_RATIO,
-    transform: 'translate(50%, 50%)',
+    insetInlineEnd: size * CIRCLE_EDGE_OFFSET_RATIO,
+    // `insetInlineEnd` anchors to the right edge in LTR / left in RTL, so the
+    // outward push must mirror too: +X in LTR, −X in RTL (Y is unaffected).
+    transform: {
+      default: 'translate(50%, 50%)',
+      ':is([dir="rtl"] *)': 'translate(-50%, 50%)',
+    },
   }),
 });
 
@@ -332,6 +312,25 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
   onClick?: React.MouseEventHandler<HTMLElement>;
 }
 
+/**
+ * Reuse a single segmenter when the runtime supports Intl.Segmenter.
+ */
+const graphemeSegmenter =
+  typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, {granularity: 'grapheme'})
+    : null;
+
+/**
+ * Return the first user-perceived character, with a code-point fallback.
+ */
+function firstGrapheme(word: string): string {
+  if (graphemeSegmenter) {
+    return [...graphemeSegmenter.segment(word)][0]?.segment ?? '';
+  }
+
+  return [...word][0] ?? '';
+}
+
 /**
  * Generates initials from a name string.
  * Takes the first letter of the first two words.
@@ -347,9 +346,11 @@ function getInitials(name: string): string {
     return '';
   }
   if (words.length === 1) {
-    return words[0].charAt(0).toUpperCase();
+    return firstGrapheme(words[0]).toUpperCase();
   }
-  return (words[0].charAt(0) + words[words.length - 1].charAt(0)).toUpperCase();
+  return (
+    firstGrapheme(words[0]) + firstGrapheme(words[words.length - 1])
+  ).toUpperCase();
 }
 
 /**
@@ -544,15 +545,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>
         )}
@@ -575,10 +583,9 @@ export function Avatar({
   // `<a>`/`<button>` and the static `<div>` carry the exact same box.
   const rootStylexProps = mergeProps(
     themeProps('avatar', {size: resolvedSize}),
-    stylex.props(
+    focusOutlineProps.focusVisible(
       styles.wrapper,
       isInteractive && styles.interactive,
-      !isInteractive && showTooltip && !avatarGroup && styles.focusable,
       avatarGroup && groupStyles.ring,
       avatarGroup && groupStyles.overlap,
       avatarGroup && groupDynamicStyles.overlap(-avatarGroup.overlap),

package/src/Avatar/AvatarStatusDot.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: 'AvatarStatusDot',

package/src/Avatar/AvatarStatusDot.tsx

@@ -12,7 +12,7 @@
  * - /packages/core/src/Avatar/Avatar.doc.mjs (features, files table)
  * - /packages/core/src/Avatar/index.ts (exports)
  * - /apps/storybook/stories/Avatar.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Avatar/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Avatar/ (showcase blocks)
  */
 
 import React, {use, type ReactNode} from 'react';
@@ -22,6 +22,7 @@ import {colorVars, radiusVars} from '../theme/tokens.stylex';
 import {AvatarSizeContext} from './AvatarSizeContext';
 import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import type {AvatarStatusDotVariantMap} from './index';
 
 /**
  * Discrete size tier of the status dot, derived from the avatar size.
@@ -65,32 +66,6 @@ function resolveStatusDotSize(avatarSize: number): {
   return {dotSize: 32, borderWidth: 4, iconSize: 18, tier: 'large'};
 }
 
-/**
- * Extensible variant map for AvatarStatusDot.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Avatar' {
- *   interface AvatarStatusDotVariantMap {
- *     'away': true;
- *   }
- * }
- * ```
- *
- * Custom variants render no background fill, no ink colour, and no built-in
- * shape glyph — the theme must supply the fill and, if it passes an `icon`,
- * a `color` for it to paint with. It should also supply a non-colour mark
- * so the status is not distinguishable by colour alone (a WCAG 1.4.1
- * failure): pass `icon`, or theme a glyph onto the dot via
- * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
- */
-export interface AvatarStatusDotVariantMap {
-  success: true;
-  neutral: true;
-  error: true;
-}
-
 /**
  * AvatarStatusDot variant type. Extensible via module augmentation of AvatarStatusDotVariantMap.
  */

package/src/Avatar/index.ts

@@ -11,11 +11,36 @@
  * SYNC: When modified, update this header and /packages/core/src/Avatar/Avatar.doc.mjs
  */
 
+/**
+ * Extensible variant map for AvatarStatusDot.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Avatar' {
+ *   interface AvatarStatusDotVariantMap {
+ *     'away': true;
+ *   }
+ * }
+ * ```
+ *
+ * Custom variants render no background fill, no ink colour, and no built-in
+ * shape glyph — the theme must supply the fill and, if it passes an `icon`,
+ * a `color` for it to paint with. It should also supply a non-colour mark
+ * so the status is not distinguishable by colour alone (a WCAG 1.4.1
+ * failure): pass `icon`, or theme a glyph onto the dot via
+ * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
+ */
+export interface AvatarStatusDotVariantMap {
+  success: true;
+  neutral: true;
+  error: true;
+}
+
 export {Avatar, resolveSize} from './Avatar';
 export type {AvatarProps, AvatarSize} from './Avatar';
 export {AvatarStatusDot} from './AvatarStatusDot';
 export type {
   AvatarStatusDotProps,
   AvatarStatusDotVariant,
-  AvatarStatusDotVariantMap,
 } from './AvatarStatusDot';

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -1,5 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'AvatarGroup',
@@ -71,7 +71,7 @@ export const docs = {
   ],
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -85,7 +85,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'compositional overlapping avatar row w/ +N overflow or custom slot',
   usage: {

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -5,6 +5,7 @@ import userEvent from '@testing-library/user-event';
 import {AvatarGroup} from './AvatarGroup';
 import {AvatarGroupOverflow} from './AvatarGroupOverflow';
 import {Avatar, AvatarStatusDot} from '../Avatar';
+import {InternationalizationProvider} from '../i18n';
 
 describe('AvatarGroup', () => {
   it('renders all avatar children', () => {
@@ -238,7 +239,26 @@ describe('AvatarGroupOverflow — hardening', () => {
     );
 
     expect(screen.getByText('+4912')).toBeInTheDocument();
-    expect(screen.getByLabelText('4912 more')).toBeInTheDocument();
+    // The aria-label routes through the catalog's `{count, number}` ICU
+    // argument, so the en locale adds a grouping separator.
+    expect(screen.getByLabelText('4,912 more')).toBeInTheDocument();
+  });
+
+  it('localizes the overflow label through the i18n catalog', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {'@astryx.avatarGroup.overflow': '{count, number} de plus'},
+        }}>
+        <AvatarGroup>
+          <Avatar name="Alice" />
+          <AvatarGroupOverflow count={3} />
+        </AvatarGroup>
+      </InternationalizationProvider>,
+    );
+
+    expect(screen.getByLabelText('3 de plus')).toBeInTheDocument();
   });
 });