@astryxdesign/core 0.1.7 → 0.1.8-canary.0c4d8d7

package/locales/fr-FR.json

@@ -0,0 +1,10 @@
+{
+  "@astryx.pagination.previous": {
+    "defaultMessage": "Aller à la page précédente",
+    "description": "Aria label for the previous-page button."
+  },
+  "@astryx.pagination.next": {
+    "defaultMessage": "Aller à la page suivante",
+    "description": "Aria label for the next-page button."
+  }
+}

package/locales/pseudo.json

@@ -197,6 +197,9 @@
   "@astryx.carousel.scrollRight": {
     "defaultMessage": "⟦Šçřółł říĝĥţ⟧"
   },
+  "@astryx.carousel.slideLabel": {
+    "defaultMessage": "⟦Šłíðé {current, number} óƒ {total, number}⟧"
+  },
   "@astryx.chat.status.sending": {
     "defaultMessage": "⟦Šéñðíñĝ⟧"
   },
@@ -308,6 +311,9 @@
   "@astryx.table.selection.selectRow": {
     "defaultMessage": "⟦Šéłéçţ řóŵ⟧"
   },
+  "@astryx.table.selection.selectRowNamed": {
+    "defaultMessage": "⟦Šéłéçţ {label}⟧"
+  },
   "@astryx.table.sort.ascending": {
     "defaultMessage": "⟦Šóřţ àšçéñðíñĝ⟧"
   },
@@ -317,6 +323,21 @@
   "@astryx.table.sort.clear": {
     "defaultMessage": "⟦Çłéàř šóřţ⟧"
   },
+  "@astryx.table.sort.direction.ascending": {
+    "defaultMessage": "⟦àšçéñðíñĝ⟧"
+  },
+  "@astryx.table.sort.direction.descending": {
+    "defaultMessage": "⟦ðéšçéñðíñĝ⟧"
+  },
+  "@astryx.table.sort.sortBy": {
+    "defaultMessage": "⟦Šóřţ ƀý {label}⟧"
+  },
+  "@astryx.table.sort.sortedBy": {
+    "defaultMessage": "⟦Šóřţ ƀý {label}, šóřţéð {direction}⟧"
+  },
+  "@astryx.table.sort.sortedByWithPriority": {
+    "defaultMessage": "⟦Šóřţ ƀý {label}, šóřţéð {direction}, þříóříţý {rank, number} óƒ {total, number}⟧"
+  },
   "@astryx.toast.dismiss": {
     "defaultMessage": "⟦Ðíšɱíšš ñóţíƒíçàţíóñ⟧"
   },
@@ -494,6 +515,9 @@
   "@astryx.fileInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },
+  "@astryx.fileInput.triggerWithFiles": {
+    "defaultMessage": "⟦{label}, {fileNames}⟧"
+  },
   "@astryx.lightbox.mediaViewer": {
     "defaultMessage": "⟦Ṁéðíà ṽíéŵéř⟧"
   },
@@ -542,6 +566,12 @@
   "@astryx.tableRowExpansion.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.tableTree.collapseRow": {
+    "defaultMessage": "⟦Çółłàþšé řóŵ⟧"
+  },
+  "@astryx.tableTree.expandRow": {
+    "defaultMessage": "⟦Éẋþàñð řóŵ⟧"
+  },
   "@astryx.textInput.clearLabel": {
     "defaultMessage": "⟦Çłéàř {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.1.7",
+  "version": "0.1.8-canary.0c4d8d7",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -636,6 +636,7 @@
   "files": [
     "dist",
     "src",
+    "scripts/postinstall.mjs",
     "locales",
     "docs.mjs",
     "groups.doc.mjs",
@@ -662,6 +663,7 @@
     "intl-messageformat": "^11.2.9"
   },
   "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
     "build": "rimraf dist && pnpm build:i18n && pnpm build:esm && tsc --project tsconfig.build.json && pnpm build:css && pnpm build:umd && node ../../scripts/check-no-dev-jsx.mjs",
     "build:i18n": "node scripts/build-pseudo-locale.mjs",
     "build:esm": "babel src --out-dir dist --extensions .ts,.tsx --out-file-extension .js --ignore \"**/*.test.ts,**/*.test.tsx,**/__tests__/**,**/*.perf.test.*,**/*.doc.mjs,**/*.d.ts,**/*.css,**/*.css.d.ts\" --config-file ./babel.config.json",

package/scripts/postinstall.mjs

@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file @astryxdesign/core postinstall — nudge to run `npx @astryxdesign/cli init`.
+ *
+ * Enforcement layer 1 of making `astryx init` foolproof: when the design system
+ * is installed and the project hasn't run init yet, print a one-line next-step
+ * so agents/humans discover it (this is the most common fresh-install entry).
+ *
+ * Self-contained: core is a separate package and cannot import the CLI, so the
+ * agent-doc locations + marker below intentionally DUPLICATE the CLI's agent-doc
+ * discovery in packages/cli/src/commands/agent-docs.mjs — keep them aligned with
+ * that file. The .hermes.md / HERMES.md entries are an intentional superset (the
+ * CLI writes those via `--agent hermes`). Non-interactive, never fails the
+ * install, and quiet in the monorepo build, during npx's fetch, and once set up.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+
+const HERE = fileURLToPath(import.meta.url);
+
+// Duplicates the CLI's agent-doc locations + markers — keep aligned with
+// packages/cli/src/commands/agent-docs.mjs. Hermes files are an intentional superset.
+const AGENT_DOC_PATHS = [
+  'AGENTS.md',
+  'CLAUDE.md',
+  '.claude/CLAUDE.md',
+  '.cursorrules',
+  '.hermes.md',
+  'HERMES.md',
+];
+const MARKERS = ['<!-- ASTRYX:START -->', '<!-- XDS:START -->'];
+
+/**
+ * True when the project already has the Astryx agent prompt installed (an Astryx
+ * marker is present in any agent-doc file) — the same check the CLI performs.
+ * @param {string} root @returns {boolean}
+ */
+export function isAstryxInitialized(root) {
+  for (const rel of AGENT_DOC_PATHS) {
+    try {
+      const content = fs.readFileSync(path.join(root, rel), 'utf-8');
+      if (MARKERS.some(m => content.includes(m))) return true;
+    } catch {
+      // Unreadable/missing — keep checking the others.
+    }
+  }
+  return false;
+}
+
+/**
+ * Pure decision: should the postinstall print the setup nudge? Unit-testable
+ * without an actual npm install.
+ * @returns {boolean}
+ */
+export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {
+  if (!scriptPath || !scriptPath.includes('node_modules')) return false; // monorepo/source build
+  if (scriptPath.includes('_npx') || npmCommand === 'exec') return false; // npx transient
+  if (isSetUp) return false; // already set up — stay quiet
+  return true;
+}
+
+function main() {
+  const root = process.env.INIT_CWD || process.cwd();
+  if (
+    shouldNudge({
+      scriptPath: HERE,
+      npmCommand: process.env.npm_command,
+      isSetUp: isAstryxInitialized(root),
+    })
+  ) {
+    // Scoped package form (`@astryxdesign/cli`) — always resolves to us, even
+    // before the CLI is installed. Bare `npx astryx` would fetch an unrelated
+    // look-alike package (see PR #4151). After that lands, switch this to its
+    // getCliInvocation() single source of truth.
+    process.stdout.write(
+      '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n',
+    );
+  }
+}
+
+// Run only when executed directly (`node scripts/postinstall.mjs`), never when
+// imported by tests.
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  try {
+    main();
+  } catch {
+    // never break an install
+  }
+  process.exit(0);
+}

package/src/AppShell/AppShell.tsx

@@ -24,6 +24,7 @@ import {
   isValidElement,
   useCallback,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -600,10 +601,14 @@ export function AppShell({
   // =========================================================================
   // Mobile context — shared with MobileNavToggle and future TopNav mobile
   // =========================================================================
+  // Stable id shared by the drawer (applied as its `id`) and the toggle
+  // (referenced via `aria-controls`) so screen readers know what it controls.
+  const mobileNavId = useId();
   const mobileContextValue = useMemo<AppShellMobileContextValue>(
     () => ({
       isMobile: isBelowBreakpoint,
       isMobileNavOpen,
+      mobileNavId,
       toggleMobileNav: () =>
         mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
       openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
@@ -614,6 +619,7 @@ export function AppShell({
     [
       isBelowBreakpoint,
       isMobileNavOpen,
+      mobileNavId,
       setMobileNavOpen,
       mobileNavEnabled,
       mobileNavHasToggle,

package/src/AppShell/AppShellMobileContext.tsx

@@ -20,6 +20,14 @@ export interface AppShellMobileContextValue {
   isMobile: boolean;
   /** Whether the mobile nav drawer is currently open */
   isMobileNavOpen: boolean;
+  /**
+   * DOM id of the mobile nav drawer. `AppShell` sets this so the toggle can
+   * point its `aria-controls` at the drawer and the drawer can apply it as its
+   * `id`. Optional: callers that construct this context by hand may omit it, in
+   * which case `MobileNav` falls back to a locally generated id and the toggle
+   * simply drops `aria-controls`.
+   */
+  mobileNavId?: string;
   /** Toggle the mobile nav drawer open/closed */
   toggleMobileNav: () => void;
   /** Open the mobile nav drawer */

package/src/AppShell/useAppShellMobile.doc.mjs

@@ -31,6 +31,12 @@ export const docs = {
       description:
         'Whether the AppShell-managed mobile navigation drawer is open.',
     },
+    {
+      name: 'mobileNavId',
+      type: 'string | undefined',
+      description:
+        'DOM id of the mobile navigation drawer, set by AppShell. Point aria-controls of a custom toggle at this so screen-reader users know which element the toggle expands. Undefined outside an AppShell that manages the drawer.',
+    },
     {
       name: 'toggleMobileNav',
       type: '() => void',
@@ -111,6 +117,8 @@ export const docsDense = {
     isMobile:
       'viewport below AppShell mobile nav breakpoint? Use to sync AppShell-adjacent mobile UI',
     isMobileNavOpen: 'AppShell-managed mobile nav drawer open?',
+    mobileNavId:
+      'DOM id of the drawer; point custom toggle aria-controls at it',
     toggleMobileNav: 'toggle drawer; no-op when mobile nav disabled',
     openMobileNav: 'open drawer; no-op when mobile nav disabled',
     closeMobileNav: 'close drawer',

package/src/Avatar/Avatar.doc.mjs

@@ -13,7 +13,7 @@ export const docs = {
       'Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.',
     bestPractices: [
       {guidance: true, description: 'Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents.'},
-      {guidance: true, description: 'Pick a size that matches the context: tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers.'},
+      {guidance: true, description: 'Pick a size that matches the context: xsm or sm for inline mentions, md or lg for lists and cards, xl for profile headers.'},
       {guidance: true, description: 'Add a status dot when knowing someone\'s availability matters, like in chat or team views.'},
       {guidance: false, description: 'Use Avatar for logos, product images, or anything that isn\'t a person or team. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular to stay consistent across the system.'},
@@ -55,9 +55,9 @@ export const docs = {
     },
     {
       name: 'size',
-      type: "'tiny' | 'xsmall' | 'small' | 'medium' | 'large' | number",
-      description: "Avatar size. Use a named size ('tiny', 'xsmall', 'small', 'medium', 'large') or a numeric pixel value. Note: short names like 'sm', 'md', 'lg' are NOT valid; use the full words.",
-      default: "'small'",
+      type: "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | number",
+      description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs.",
+      default: "'md'",
     },
     {
       name: 'status',
@@ -100,7 +100,7 @@ export const docsDense = {
       'Avatar represents a person or team with a profile photo, initials, or a default icon. Falls back automatically. Use in comment headers, contact lists, chat, user cards.',
     bestPractices: [
       {guidance: true, description: 'Always pass a name for initials fallback and screen reader alt text.'},
-      {guidance: true, description: 'Match size to context: tiny/xsmall inline, small/medium in lists, large for profiles.'},
+      {guidance: true, description: 'Match size to context: xsm/sm inline, md/lg in lists, xl for profiles.'},
       {guidance: true, description: 'Add a status dot in chat or team views where availability matters.'},
       {guidance: false, description: 'Use for logos or product images. Use an image or icon instead.'},
       {guidance: false, description: 'Force a square or custom shape. Avatars are always circular.'},
@@ -111,7 +111,7 @@ export const docsDense = {
     fallbackSrc: 'fallback image when primary fails',
     name: 'user name for initials and alt text',
     alt: 'alt text; falls back to name',
-    size: "avatar size. Named ('tiny', 'xsmall', 'small', 'medium', 'large') or numeric px. Short names 'sm'/'md'/'lg' are NOT valid; use full words.",
+    size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px.",
     status: 'corner content for status indicators',
   },
   components: [

package/src/Avatar/Avatar.tsx

@@ -55,9 +55,13 @@ const CIRCLE_EDGE_OFFSET_RATIO = (1 - 1 / Math.SQRT2) / 2;
 const INITIALS_FONT_SIZE_RATIO = 0.4;
 
 /**
- * Named size options
+ * Named size options.
+ *
+ * Avatar uses the same abbreviated scale as Icon (`xsm`/`sm`/`md`/`lg`/`xl`),
+ * but the values are larger because avatars align with media rather than
+ * glyphs. The tiers match EPS's avatar sizes.
  */
-type AvatarNamedSize = 'tiny' | 'xsmall' | 'small' | 'medium' | 'large';
+type AvatarNamedSize = 'xsm' | 'sm' | 'md' | 'lg' | 'xl';
 
 /**
  * Numeric size options (in pixels)
@@ -78,15 +82,15 @@ export function resolveSize(size: AvatarSize): number {
     return size;
   }
   switch (size) {
-    case 'tiny':
+    case 'xsm':
       return 20;
-    case 'xsmall':
+    case 'sm':
       return 24;
-    case 'small':
+    case 'md':
       return 36;
-    case 'medium':
+    case 'lg':
       return 48;
-    case 'large':
+    case 'xl':
       return 128;
   }
 }
@@ -198,8 +202,9 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
    */
   name?: string;
   /**
-   * The size of the avatar.
-   * @default 'small'
+   * The size of the avatar. A named size (`xsm` 20px, `sm` 24px, `md` 36px,
+   * `lg` 48px, `xl` 128px) or a specific pixel value.
+   * @default 'md'
    */
   size?: AvatarSize;
   /**
@@ -258,7 +263,7 @@ function DefaultIcon({size}: {size: number}) {
  * @example
  * ```
  * <Avatar src="/user.jpg" name="John Doe" />
- * <Avatar name="Jane Smith" size="large" />
+ * <Avatar name="Jane Smith" size="xl" />
  * <Avatar src="/user.jpg" status={<OnlineIndicator />} />
  * ```
  */
@@ -267,7 +272,7 @@ export function Avatar({
   'data-testid': testId,
   fallbackSrc,
   name,
-  size = 'small',
+  size = 'md',
   src,
   status,
   xstyle,

package/src/Avatar/AvatarSizeContext.ts

@@ -18,7 +18,7 @@ import {createContext} from 'react';
  * Context that provides the resolved numeric avatar size (in pixels)
  * to child components like AvatarStatusDot.
  *
- * Default value of 36 matches the default 'small' avatar size.
+ * Default value of 36 matches the default 'md' avatar size.
  */
 export const AvatarSizeContext = createContext<number>(36);
 AvatarSizeContext.displayName = 'AvatarSizeContext';

package/src/Avatar/AvatarStatusDot.tsx

@@ -168,12 +168,12 @@ const variantStyleMap: Partial<
  * ```
  * <Avatar
  *   name="John Doe"
- *   size="medium"
+ *   size="lg"
  *   status={<AvatarStatusDot variant="success" label="Online" />}
  * />
  * <Avatar
  *   name="Jane Smith"
- *   size="large"
+ *   size="xl"
  *   status={<AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />}
  * />
  * ```

package/src/AvatarGroup/AvatarGroup.doc.mjs

@@ -47,7 +47,7 @@ export const docs = {
       name: 'size',
       type: 'AvatarSize',
       description: 'Size applied to all avatars via context.',
-      default: "'small'",
+      default: "'md'",
     },
     {
       name: 'ref',

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -56,14 +56,14 @@ describe('AvatarGroup', () => {
 
   it('applies size class to the group', () => {
     render(
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         <Avatar name="Alice" />
       </AvatarGroup>,
     );
 
     const group = screen.getByRole('group');
     expect(group.className).toContain('astryx-avatar-group');
-    expect(group.className).toContain('medium');
+    expect(group.className).toContain('lg');
   });
 
   it('renders empty group when no children', () => {
@@ -134,7 +134,7 @@ describe('AvatarGroupOverflow', () => {
     const visibleCount = 3;
 
     render(
-      <AvatarGroup size="medium">
+      <AvatarGroup size="lg">
         {users.slice(0, visibleCount).map(name => (
           <Avatar key={name} name={name} />
         ))}
@@ -211,4 +211,18 @@ describe('AvatarGroupOverflow — hardening', () => {
 
     expect(screen.getByText('+999')).toBeInTheDocument();
   });
+
+  it('renders the full "+N" text for wide multi-digit counts', () => {
+    // The indicator grows into a pill for long counts, so the entire number
+    // must remain present (nothing clipped away in the DOM).
+    render(
+      <AvatarGroup>
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={4912} />
+      </AvatarGroup>,
+    );
+
+    expect(screen.getByText('+4912')).toBeInTheDocument();
+    expect(screen.getByLabelText('4912 more')).toBeInTheDocument();
+  });
 });

package/src/AvatarGroup/AvatarGroup.tsx

@@ -39,7 +39,7 @@ export interface AvatarGroupProps extends BaseProps<HTMLDivElement> {
   children: ReactNode;
   /**
    * Size applied to all avatars via context.
-   * @default 'small'
+   * @default 'md'
    */
   size?: AvatarSize;
   /**
@@ -65,7 +65,7 @@ const styles = stylex.create({
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}
@@ -75,7 +75,7 @@ const styles = stylex.create({
  */
 export function AvatarGroup({
   children,
-  size = 'small',
+  size = 'md',
   'data-testid': testId,
   'aria-label': ariaLabelFromProps,
   xstyle,

package/src/AvatarGroup/AvatarGroupOverflow.doc.mjs

@@ -51,7 +51,7 @@ export const docs = {
       'AvatarGroupOverflow appears at the end of an AvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.',
     bestPractices: [
       {guidance: true, description: 'Pass the real hidden count to `count` so the accessible label matches the visible indicator.'},
-      {guidance: true, description: 'Use short custom text such as `+12` or `99+`; the indicator is sized like an avatar.'},
+      {guidance: true, description: 'Use short custom text such as `+12` or `99+`. The indicator is circular for short counts and grows into a pill for wider counts so the number always fits.'},
       {guidance: true, description: 'Provide `onClick` when the overflow opens a member list, popover, or detail view.'},
       {guidance: false, description: 'Do not use long labels inside the indicator; place longer participant details next to the group instead.'},
     ],
@@ -64,7 +64,7 @@ export const docs = {
     {
       label: 'Default overflow count',
       code: `
-<AvatarGroup size="medium">
+<AvatarGroup size="lg">
   {users.slice(0, 3).map(user => (
     <Avatar key={user.id} src={user.src} name={user.name} />
   ))}
@@ -75,7 +75,7 @@ export const docs = {
     {
       label: 'Custom count text',
       code: `
-<AvatarGroup size="medium">
+<AvatarGroup size="lg">
   {users.slice(0, 3).map(user => (
     <Avatar key={user.id} src={user.src} name={user.name} />
   ))}
@@ -104,7 +104,7 @@ export const docsZh = {
       'AvatarGroupOverflow 显示在 AvatarGroup 末尾，用来汇总未单独展示的成员。适用于只展示少量头像但仍需要显示隐藏数量的场景。',
     bestPractices: [
       {guidance: true, description: '向 `count` 传入真实隐藏数量，确保无障碍标签与可见指示器一致。'},
-      {guidance: true, description: '使用 `+12` 或 `99+` 等短文本；指示器尺寸与头像相同。'},
+      {guidance: true, description: '使用 `+12` 或 `99+` 等短文本；指示器在计数较短时为圆形，计数较宽时会拉伸为胶囊形，确保数字始终完整显示。'},
       {guidance: true, description: '当溢出项会打开成员列表、弹出层或详情视图时提供 `onClick`。'},
       {guidance: false, description: '不要在指示器内使用长标签；更长的参与者详情应放在头像组旁边。'},
     ],

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -20,6 +20,7 @@ import {
   typographyVars,
   fontWeightVars,
   radiusVars,
+  spacingVars,
 } from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {useAvatarGroup} from './AvatarGroupContext';
@@ -67,13 +68,21 @@ const styles = stylex.create({
     borderWidth: BORDER_WIDTH,
     borderStyle: 'solid',
     borderColor: colorVars['--color-background-surface'],
-    boxSizing: 'content-box',
+    // border-box so the border and inline padding are included in the box
+    // size: a short "+N" stays a circle at exactly the avatar size, while
+    // longer content pushes past the min width and grows into a pill.
+    boxSizing: 'border-box',
+    // Horizontal breathing room so multi-digit "+N" counts don't crowd the
+    // edges once the indicator grows into a pill.
+    paddingInline: spacingVars['--spacing-2'],
     // Neutral tint layer (preserves opaque base underneath)
     backgroundImage: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
   },
   button: {
     cursor: 'pointer',
-    padding: 0,
+    // Reset the UA button's block padding only; the inline padding from `base`
+    // provides the pill's breathing room and must be preserved.
+    paddingBlock: 0,
     // Interactive overlay states layered on top via backgroundImage
     backgroundImage: {
       default: `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`,
@@ -99,8 +108,15 @@ const styles = stylex.create({
 
 const dynamicStyles = stylex.create({
   size: (s: number) => ({
-    width: s,
-    height: s,
+    // Pin height to the avatar's rendered size and enforce the same value as a
+    // *minimum* width, so short counts (`+5`) render a perfect circle. With
+    // border-box, the inline padding lives inside this size; longer content
+    // (`+4912`) pushes past the min width and grows into a stadium/pill.
+    // The border is added to the declared size (like the avatars' ring, which
+    // uses content-box + a 2px border) to keep the indicator the same overall
+    // size as its sibling avatars.
+    minWidth: s + BORDER_WIDTH * 2,
+    height: s + BORDER_WIDTH * 2,
   }),
   fontSize: (s: number) => ({
     fontSize: s * OVERFLOW_FONT_RATIO,
@@ -116,7 +132,7 @@ const dynamicStyles = stylex.create({
  *
  * @example
  * ```
- * <AvatarGroup size="medium">
+ * <AvatarGroup size="lg">
  *   {users.slice(0, 3).map(u => (
  *     <Avatar key={u.id} src={u.src} name={u.name} />
  *   ))}

package/src/Banner/Banner.doc.mjs

@@ -81,6 +81,13 @@ export const docs = {
         'Container type: card has border-radius; section is full-width with no border-radius for page-level use.',
       default: "'card'",
     },
+    {
+      name: 'elevation',
+      type: "'none' | 'low' | 'med' | 'high'",
+      description:
+        'Resting shadow depth. Use for a floating banner that hovers above content; `none` is the default inline banner. A `card`-container banner rounds its shadow to match.',
+      default: "'none'",
+    },
     {
       name: 'children',
       type: 'ReactNode',
@@ -157,6 +164,7 @@ export const docsZh = {
     {name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用；无论是否提供此回调，横幅都会自动隐藏。'},
     {name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容，通常是按钮或链接。'},
     {name: 'container', type: "'card' | 'section'", description: '视觉变体：card 带圆角；section 无圆角全宽，适用于页面级场景。', default: "'card'"},
+    {name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅；none 为默认内联横幅。', default: "'none'"},
     {name: 'children', type: 'ReactNode', description: '渲染在彩色头部下方卡片背景区域的内容。'},
     {name: 'defaultIsExpanded', type: 'boolean', description: '内容区域（children）是否初始展开。仅在提供 children 时相关。', default: 'false'},
     {
@@ -230,6 +238,7 @@ export const docsDense = {
     onDismiss: 'dismiss callback; banner self-hides regardless',
     endContent: 'end-aligned action in header, typically button/link',
     container: 'card=border-radius; section=full-width no radius for page-level',
+    elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
     children: 'content in card-bg area below colored header',
     xstyle: 'StyleX layout customization via stylex.create()',
   },

package/src/Banner/Banner.test.tsx

@@ -368,4 +368,34 @@ describe('Banner', () => {
     );
     expect(screen.getByTestId('custom-chevron')).toBeInTheDocument();
   });
+
+  describe('elevation', () => {
+    it('renders a distinct root class for each elevation level', () => {
+      const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
+        const {container} = render(
+          <Banner status="info" title="Heads up" elevation={elevation} />,
+        );
+        return container.firstElementChild!.className;
+      };
+      const classes = new Set([
+        classFor('none'),
+        classFor('low'),
+        classFor('med'),
+        classFor('high'),
+      ]);
+      expect(classes.size).toBe(4);
+    });
+
+    it('defaults to flat (elevation none)', () => {
+      const {container: def} = render(
+        <Banner status="info" title="Heads up" />,
+      );
+      const {container: none} = render(
+        <Banner status="info" title="Heads up" elevation="none" />,
+      );
+      expect(def.firstElementChild!.className).toBe(
+        none.firstElementChild!.className,
+      );
+    });
+  });
 });