@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

package/locales/en.json

@@ -563,6 +563,10 @@
     "defaultMessage": "Apply",
     "description": "Primary button label inside a table's filter panel/popover; commits pending filter values. Imperative verb; pairs with `Reset`."
   },
+  "@astryx.table.rowStatus.columnHeader": {
+    "defaultMessage": "Row status",
+    "description": "Screen-reader-only column header for the narrow status-indicator gutter a Table gains from useTableRowStatus. Sighted users see a blank gutter; assistive tech announces this as the column name."
+  },
   "@astryx.table.selection.selectAllRows": {
     "defaultMessage": "Select all rows",
     "description": "Aria label for the \"select all rows\" checkbox in a Table header."
@@ -747,6 +751,10 @@
     "defaultMessage": "{label} time",
     "description": "Screen-reader-only accessible name for the time-of-day slot in a DateTimeInput. Example: `Start date time`; reorder freely (e.g. \"time of {label}\")."
   },
+  "@astryx.dateTimeInput.timeOptionsLabel": {
+    "defaultMessage": "{label} options",
+    "description": "Screen-reader-only accessible name for the list of preset times that drops down from a DateTimeInput's time slot. `{label}` is the accessible name of the time field itself, already ending in the word for time — example: `Meeting time options`. Plural: the list holds every selectable time."
+  },
   "@astryx.dateRangeInput.placeholder": {
     "defaultMessage": "Select date range",
     "description": "Grey placeholder inside an empty DateRangeInput field. Represents picking a start–end date pair. Imperative verb."
@@ -809,7 +817,15 @@
   },
   "@astryx.table.pagination.label": {
     "defaultMessage": "Table pagination",
-    "description": "Screen-reader-only accessible name for the pagination `<nav>` appended below a data table. Kept separate from `@astryx.pagination.label` so translations may diverge."
+    "description": "Screen-reader-only accessible name for a table's pagination `<nav>` (rendered below and/or above the table per the plugin's position config). Kept separate from `@astryx.pagination.label` so translations may diverge. When position='both', this string is interpolated as the {label} value into `@astryx.table.pagination.labelAbove`/`labelBelow` — keep it compatible with those suffix templates."
+  },
+  "@astryx.table.pagination.labelAbove": {
+    "defaultMessage": "{label} (top)",
+    "description": "Accessible name for the pagination `<nav>` rendered above the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."
+  },
+  "@astryx.table.pagination.labelBelow": {
+    "defaultMessage": "{label} (bottom)",
+    "description": "Accessible name for the pagination `<nav>` rendered below the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."
   },
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "Select a time",
@@ -1059,6 +1075,10 @@
     "defaultMessage": "Expand row",
     "description": "Screen-reader-only label on the row-expand chevron when the row is currently collapsed. Part of a four-way set with `collapseRow`, `expandAllRows`, `collapseAllRows`."
   },
+  "@astryx.tableRowExpansion.columnHeader": {
+    "defaultMessage": "Row expansion",
+    "description": "Screen-reader-only header for the leading column that holds the per-row expand/collapse chevrons. The column shows no visible label."
+  },
   "@astryx.tableRowExpansion.collapseAllRows": {
     "defaultMessage": "Collapse all rows",
     "description": "Screen-reader-only label on the same header button when every row is expanded. Part of the four-way set."
@@ -1067,29 +1087,33 @@
     "defaultMessage": "Expand all rows",
     "description": "Screen-reader-only label on the header expand-all/collapse-all button when at least one row is collapsed (clicking expands every expandable row). Part of the four-way set."
   },
+  "@astryx.stepper.label": {
+    "defaultMessage": "Progress",
+    "description": "Screen-reader-only fallback name for the Stepper's ordered list of steps, describing the sequence as a whole (e.g. `Progress`). Used as the aria-label when the consumer does not pass a `label`. Singular per ARIA convention."
+  },
   "@astryx.step.goToStep": {
     "defaultMessage": "Go to step {stepNumber, number}: {label}",
-    "description": "Accessible name for a clickable step in the lab Stepper. {stepNumber} is the 1-based position, {label} is the step's visible label."
+    "description": "Accessible name for a clickable step in the Stepper. {stepNumber} is the 1-based position, {label} is the step's visible label."
   },
   "@astryx.step.goToStepWithStatus": {
     "defaultMessage": "Go to step {stepNumber, number}: {label}, {status}",
-    "description": "Accessible name for a clickable lab Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."
+    "description": "Accessible name for a clickable Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."
   },
   "@astryx.step.optional": {
     "defaultMessage": "Optional",
-    "description": "Visible indicator appended after a lab Stepper step's label when the step is optional (isOptional). Very short; appears inline after the label text."
+    "description": "Visible indicator appended after a Stepper step's label when the step is optional (isOptional). Very short; appears inline after the label text."
   },
   "@astryx.step.status.completed": {
     "defaultMessage": "completed",
-    "description": "Screen-reader-only status word rendered next to a lab Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."
+    "description": "Screen-reader-only status word rendered next to a Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."
   },
   "@astryx.step.status.warning": {
     "defaultMessage": "warning",
-    "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=warning. Lowercase noun/adjective; read mid-sentence after the step label."
+    "description": "Screen-reader-only status word rendered next to a Stepper step label when status=warning. Lowercase noun/adjective; read mid-sentence after the step label."
   },
   "@astryx.step.status.error": {
     "defaultMessage": "error",
-    "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=error. Lowercase noun; read mid-sentence after the step label."
+    "description": "Screen-reader-only status word rendered next to a Stepper step label when status=error. Lowercase noun; read mid-sentence after the step label."
   },
   "@astryx.tableTree.collapseRow": {
     "defaultMessage": "Collapse row",

package/locales/pseudo.json

@@ -422,6 +422,9 @@
   "@astryx.table.filter.apply": {
     "defaultMessage": "⟦Àþþłý⟧"
   },
+  "@astryx.table.rowStatus.columnHeader": {
+    "defaultMessage": "⟦Řóŵ šţàţúš⟧"
+  },
   "@astryx.table.selection.selectAllRows": {
     "defaultMessage": "⟦Šéłéçţ àłł řóŵš⟧"
   },
@@ -560,6 +563,9 @@
   "@astryx.dateTimeInput.timeSuffix": {
     "defaultMessage": "⟦{label} ţíɱé⟧"
   },
+  "@astryx.dateTimeInput.timeOptionsLabel": {
+    "defaultMessage": "⟦{label} óþţíóñš⟧"
+  },
   "@astryx.dateRangeInput.placeholder": {
     "defaultMessage": "⟦Šéłéçţ ðàţé řàñĝé⟧"
   },
@@ -608,6 +614,12 @@
   "@astryx.table.pagination.label": {
     "defaultMessage": "⟦Ţàƀłé þàĝíñàţíóñ⟧"
   },
+  "@astryx.table.pagination.labelAbove": {
+    "defaultMessage": "⟦{label} (ţóþ)⟧"
+  },
+  "@astryx.table.pagination.labelBelow": {
+    "defaultMessage": "⟦{label} (ƀóţţóɱ)⟧"
+  },
   "@astryx.timeInput.placeholder": {
     "defaultMessage": "⟦Šéłéçţ à ţíɱé⟧"
   },
@@ -794,12 +806,18 @@
   "@astryx.tableRowExpansion.expandRow": {
     "defaultMessage": "⟦Éẋþàñð řóŵ⟧"
   },
+  "@astryx.tableRowExpansion.columnHeader": {
+    "defaultMessage": "⟦Řóŵ éẋþàñšíóñ⟧"
+  },
   "@astryx.tableRowExpansion.collapseAllRows": {
     "defaultMessage": "⟦Çółłàþšé àłł řóŵš⟧"
   },
   "@astryx.tableRowExpansion.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.stepper.label": {
+    "defaultMessage": "⟦Þřóĝřéšš⟧"
+  },
   "@astryx.step.goToStep": {
     "defaultMessage": "⟦Ĝó ţó šţéþ {stepNumber, number}: {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.4.6",
+  "version": "0.4.7-canary.019ae5a",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -489,6 +489,11 @@
       "types": "./dist/StatusDot/index.d.ts",
       "default": "./dist/StatusDot/index.js"
     },
+    "./Stepper": {
+      "source": "./src/Stepper/index.ts",
+      "types": "./dist/Stepper/index.d.ts",
+      "default": "./dist/Stepper/index.js"
+    },
     "./Switch": {
       "source": "./src/Switch/index.ts",
       "types": "./dist/Switch/index.d.ts",
@@ -656,6 +661,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/cli": "0.4.7-canary.019ae5a",
     "@babel/cli": "^8.0.4",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^8.0.1",
@@ -664,8 +670,7 @@
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "rimraf": "^6.0.1",
-    "@astryxdesign/cli": "0.4.6"
+    "rimraf": "^6.0.1"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AppShell/AppShell.tsx

@@ -50,7 +50,7 @@ import {AppShellMobileContext} from './AppShellMobileContext';
 import type {AppShellMobileContextValue} from './AppShellMobileContext';
 import type {SpacingStep} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps, mergeRefs, isRenderable} from '../utils';
+import {mergeProps, isRenderable} from '../utils';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {observeResize, unobserveResize} from '../utils/sharedResizeObserver';
@@ -58,6 +58,7 @@ import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {AppShellVariantMap} from './index';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const HasActivity = typeof React.Activity !== 'undefined';
 const ActivityWrapper = HasActivity
   ? ({
@@ -792,7 +793,7 @@ export function AppShell({
     <AppShellMobileContext value={mobileContextValue}>
       <div
         {...rest}
-        ref={mergeRefs(ref, shellRef)}
+        ref={useMergedRefs(ref, shellRef)}
         data-testid={dataTestId}
         {...mergeProps(
           themeProps('app-shell', {variant}),

package/src/AspectRatio/AspectRatio.doc.mjs

@@ -16,6 +16,7 @@ export const docs = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -30,7 +31,7 @@ export const docs = {
     {
       name: 'ratio',
       type: 'number',
-      description: 'Aspect ratio as width/height (e.g. 16/9, 1).',
+      description: 'Aspect ratio as width/height (e.g. 16/9, 1). Emitted as a class-level declaration (never inline), so `xstyle` rules or unlayered consumer CSS can override it responsively.',
       required: true,
     },
     {
@@ -83,6 +84,7 @@ export const docsZh = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -94,7 +96,7 @@ export const docsZh = {
     ],
   },
   props: [
-    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。', required: true},
+    {name: 'ratio', type: 'number', description: '宽高比，以宽/高表示（例如 16/9、1）。以类级声明输出（非内联样式），可通过 `xstyle` 规则或未分层的（unlayered）消费者 CSS 做响应式覆盖。', required: true},
     {
       name: 'shape',
       type: "'rectangle' | 'ellipse'",
@@ -133,6 +135,7 @@ export const docsDense = {
       {guidance: true, description: 'Use `fit="cover"` for images and video so the component sizes the child; the child should not repeat `width`/`height`/`objectFit` styles.'},
       {guidance: true, description: 'Pass one child. With `fit` set, every direct child is stretched to fill the box, so put an overlay or caption inside a single wrapper child rather than passing it as a second child.'},
       {guidance: true, description: 'Describe media children with `alt`, or `alt=""` when the image is decorative. AspectRatio adds no role and no accessible name of its own, so the child carries the whole accessible description.'},
+      {guidance: true, description: 'For a breakpoint-dependent ratio, override the ratio responsively: pass an `aspectRatio` rule via `xstyle` (StyleX), or override `aspect-ratio` from your own unlayered CSS under a `@media`/`@container` rule — component styles live in the `astryx-base` cascade layer, so unlayered consumer CSS wins. Give an `xstyle` rule a `default` branch alongside the conditional one (`{default: 3, \'@container ...\': \'3 / 2\'}`) — with only the conditional branch the ratio is unset outside the query and the box collapses.'},
       {guidance: false, description: 'Use for general layout containers; use standard layout components instead.'},
       {guidance: false, description: 'Nest AspectRatio containers; one level is sufficient.'},
       {guidance: false, description: 'Constrain the height on its own. The width comes from the container, so a `height` or `maxHeight` by itself clamps the box off ratio; pair it with `width: "auto"` to size from the height instead.'},
@@ -144,7 +147,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    ratio: 'width/height ratio (e.g. 16/9, 1)',
+    ratio: 'width/height ratio (e.g. 16/9, 1); class-level declaration (never inline) so xstyle/unlayered-CSS @container overrides win',
     shape: "container shape: 'rectangle' (default) | 'ellipse' (circle at ratio 1)",
     fit: "child layout: 'cover' fill+crop | 'contain' fill+letterbox | 'center' natural size; omitted = child styles itself",
     children: 'content positioned absolutely to fill container',

package/src/AspectRatio/AspectRatio.test.tsx

@@ -13,6 +13,20 @@ import {describe, it, expect, vi, beforeAll} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {AspectRatio} from './AspectRatio';
 
+/**
+ * The ratio compiles to a class-level `aspect-ratio: var(--x-aspectRatio)`
+ * declaration with the value carried by a CSS variable (so xstyle/@media
+ * and unlayered consumer CSS overrides can win). `--x-aspectRatio` is the
+ * debug-mode variable name emitted for the `aspectRatio` property.
+ */
+function ratioVar(el: HTMLElement): string {
+  return el.style.getPropertyValue('--x-aspectRatio');
+}
+
+function ratioValue(ratio: number): string {
+  return String(ratio);
+}
+
 describe('AspectRatio', () => {
   it('renders with correct aspect ratio', () => {
     render(
@@ -22,7 +36,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     expect(element).toBeInTheDocument();
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
   });
 
   it('children fill the container', () => {
@@ -47,7 +61,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 4:3 ratio', () => {
@@ -58,7 +72,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders with 1:1 square ratio', () => {
@@ -68,7 +82,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
   });
 
   it('renders with 21:9 ultrawide ratio', () => {
@@ -79,7 +93,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe(String(ratio));
+    expect(ratioVar(element)).toBe(ratioValue(ratio));
   });
 
   it('renders an ellipse that respects the ratio (circle at 1:1)', () => {
@@ -89,7 +103,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('ellipse');
   });
 
@@ -101,7 +115,7 @@ describe('AspectRatio', () => {
     );
     const element = screen.getByTestId('aspect-ratio');
     // Ratio is preserved — the ellipse does not force 1:1.
-    expect(element.style.aspectRatio).toBe(String(16 / 9));
+    expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     expect(element.className).toContain('ellipse');
   });
 
@@ -112,7 +126,7 @@ describe('AspectRatio', () => {
       </AspectRatio>,
     );
     const element = screen.getByTestId('aspect-ratio');
-    expect(element.style.aspectRatio).toBe('1');
+    expect(ratioVar(element)).toBe(ratioValue(1));
     expect(element.className).toContain('rectangle');
     // No ellipse border-radius when shape is the default rectangle
     expect(element.style.borderRadius).toBe('');
@@ -177,6 +191,38 @@ describe('AspectRatio', () => {
     expect(video).toBeInTheDocument();
   });
 
+  describe('responsive ratio', () => {
+    it('emits the ratio as a class-level declaration, not an inline style', () => {
+      render(
+        <AspectRatio ratio={3 / 1} data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // No inline aspect-ratio — the declaration lives in a class reading a
+      // CSS variable, so @media/@container rules (via xstyle, or via
+      // unlayered consumer CSS beating the astryx-base layer) can override
+      // it.
+      expect(element.style.aspectRatio).toBe('');
+      expect(ratioVar(element)).toBe(ratioValue(3 / 1));
+    });
+
+    it('lets a consumer inline style win over the class-level ratio', () => {
+      render(
+        <AspectRatio
+          ratio={3 / 1}
+          style={{aspectRatio: '3 / 2'}}
+          data-testid="aspect-ratio">
+          <div>Hero</div>
+        </AspectRatio>,
+      );
+      const element = screen.getByTestId('aspect-ratio');
+      // The consumer's style prop passes through untouched (it is no longer
+      // merged with a component-owned inline aspect-ratio).
+      expect(element.style.aspectRatio).toBe('3 / 2');
+    });
+  });
+
   describe('fit', () => {
     it('marks the child\'s direct parent with data-astryx-aspect-ratio-override for fit="cover"', () => {
       render(
@@ -277,7 +323,7 @@ describe('AspectRatio', () => {
   });
 
   describe('style merging', () => {
-    it('keeps the consumer style and applies the ratio over it', () => {
+    it('keeps the consumer style and lets an inline ratio win', () => {
       render(
         <AspectRatio
           ratio={16 / 9}
@@ -288,7 +334,8 @@ describe('AspectRatio', () => {
       );
       const element = screen.getByTestId('aspect-ratio');
       expect(element.style.opacity).toBe('0.5');
-      expect(element.style.aspectRatio).toBe(String(16 / 9));
+      expect(element.style.aspectRatio).toBe('3 / 1');
+      expect(ratioVar(element)).toBe(ratioValue(16 / 9));
     });
 
     it('keeps a consumer className beside the theme target', () => {

package/src/AspectRatio/AspectRatio.tsx

@@ -43,6 +43,25 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
   ref?: React.Ref<HTMLDivElement>;
   /**
    * The aspect ratio as width/height (e.g., 16/9 = 1.777..., 4/3 = 1.333..., 1 for square).
+   *
+   * The ratio is emitted as a class-level declaration — never an inline
+   * style — so it can be made responsive:
+   * - StyleX consumers pass an `aspect-ratio` rule via `xstyle`, including
+   *   under `@media`/`@container` conditions.
+   * - Plain-CSS/Tailwind consumers override `aspect-ratio` from their own
+   *   (unlayered) rules: the compiled component styles live in the
+   *   `astryx-base` cascade layer, and unlayered CSS wins over layered
+   *   rules regardless of specificity.
+   *
+   * @example
+   * ```
+   * // 3:1 hero that becomes 3:2 when its container stacks
+   * <AspectRatio ratio={3 / 1} className="gallery-hero">…</AspectRatio>
+   *
+   * // CSS: @container gallery (max-width: 720px) {
+   * //   .gallery-hero { aspect-ratio: 3 / 2; }
+   * // }
+   * ```
    */
   ratio: number;
 
@@ -132,6 +151,20 @@ const styles = stylex.create({
   },
 });
 
+// The ratio compiles to a CSS variable + a class-level declaration
+// (aspect-ratio: var(--x)) instead of a raw inline style, so consumer
+// overrides — `xstyle` rules, including ones inside @media/@container
+// queries — can still win. A raw inline `aspect-ratio` would beat any class
+// (same rationale as Grid's dynamic track values). Non-StyleX consumers
+// don't need a dedicated hook: the compiled declaration sits in the
+// `astryx-base` cascade layer, so any unlayered consumer rule wins
+// regardless of specificity.
+const dynamicStyles = stylex.create({
+  ratio: (ratio: number) => ({
+    aspectRatio: ratio,
+  }),
+});
+
 /**
  * AspectRatio component for maintaining a specific aspect ratio for its children.
  *
@@ -147,6 +180,11 @@ const styles = stylex.create({
  * `ratio={1}` or an oval at other ratios. Both shapes respect the provided
  * `ratio`.
  *
+ * The ratio is a class-level declaration (not an inline style), so it can be
+ * overridden responsively — via `xstyle` for StyleX consumers, or with a
+ * plain unlayered `aspect-ratio` rule for plain-CSS consumers (component
+ * styles live in the `astryx-base` cascade layer, which unlayered CSS beats).
+ *
  * Sizing: the box takes its width from its container and derives its height
  * from the ratio, so it needs an ancestor with a definite width. Two
  * consequences are worth knowing. Constraining only the height (`height` or
@@ -188,11 +226,12 @@ export function AspectRatio({
         themeProps('aspect-ratio', {shape}),
         stylex.props(
           styles.container,
+          dynamicStyles.ratio(ratio),
           shape === 'ellipse' && styles.ellipse,
           xstyle,
         ),
         className,
-        {...style, aspectRatio: ratio},
+        style,
       )}
       {...props}>
       {/* The marker attribute carries the fit value so the reset.css child

package/src/Avatar/Avatar.doc.mjs

@@ -148,7 +148,8 @@ export const docsDense = {
       {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: true, description: 'When wrapping Avatar in your own Tooltip or HoverCard, set tooltip={false} so the built-in name tooltip does not overlap yours.'},
-      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development. A status label is not a name.'},
+      {guidance: true, description: 'Interactive avatars (href/onClick) need name or alt; without one they warn in development.'},
+      {guidance: false, description: 'Rely on a status label to name an interactive avatar. "Online" says nothing about where the link goes.'},
       {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.'},
     ],

package/src/Avatar/Avatar.test.tsx

@@ -569,6 +569,23 @@ describe('Avatar', () => {
       render(<Avatar name="Ada Lovelace" ref={ref} data-testid="a" />);
       expect(ref.current).toBe(screen.getByTestId('a'));
     });
+
+    it('keeps its merged ref attached across unrelated rerenders', () => {
+      const ref = vi.fn();
+      const {rerender} = render(
+        <Avatar name="Ada Lovelace" size="sm" tooltip={false} ref={ref} />,
+      );
+      const avatar = screen.getByRole('img', {name: 'Ada Lovelace'});
+      expect(ref).toHaveBeenLastCalledWith(avatar);
+      ref.mockClear();
+
+      rerender(
+        <Avatar name="Ada Lovelace" size="lg" tooltip={false} ref={ref} />,
+      );
+
+      expect(ref).not.toHaveBeenCalled();
+      expect(screen.getByRole('img', {name: 'Ada Lovelace'})).toBe(avatar);
+    });
   });
 });
 

package/src/Avatar/Avatar.tsx

@@ -19,7 +19,14 @@
  * Last synced props: alt, fallbackSrc, name, size, src, status, href, as, target, rel, onClick
  */
 
-import {isValidElement, useMemo, useRef, useState, type ReactNode} from 'react';
+import {
+  isValidElement,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
 import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -34,7 +41,8 @@ import {
   type AvatarStatusLabelTarget,
 } from './AvatarStatusLabelContext';
 import {useAvatarGroup} from '../AvatarGroup/AvatarGroupContext';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {themeProps} from '../utils/themeProps';
 import {firstCharacter} from '../utils/characters';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
@@ -608,47 +616,62 @@ export function Avatar({
     label: undefined,
     update: null,
   });
-  // A fresh callback ref every render, so React reattaches it on every commit
-  // and the name is recomposed after React has written this render's props.
+  const {
+    'aria-hidden': consumerAriaHidden,
+    'aria-label': consumerAriaLabel,
+    role: consumerRole,
+  } = props;
+  // Recompose the name after React has written any relevant prop changes.
   // `update` covers the other direction: a label that changes while the avatar
   // itself does not re-render.
-  const nameRef = (element: HTMLElement | null) => {
-    if (element == null) {
-      return;
-    }
-    const target = statusLabelRef.current;
-    target.update = () => {
-      const composed = composeAccessibleName(
-        t,
-        nameLabel,
-        meaningful(target.label) ?? getStatusLabel(status),
-      );
-      // A consumer's own ARIA wins here exactly as it does in render, where
-      // the derived props spread before `{...props}`.
-      if (props['aria-label'] == null) {
-        setAttributeOrRemove(element, 'aria-label', composed);
+  const nameRef = useCallback(
+    (element: HTMLElement | null) => {
+      if (element == null) {
+        return;
       }
-      // An `<a>`/`<button>` root carries its own role and must not be hidden,
-      // so only the name transfers there.
-      if (!isInteractive) {
-        if (props.role == null) {
-          element.setAttribute('role', composed ? 'img' : 'presentation');
+      const target = statusLabelRef.current;
+      target.update = () => {
+        const composed = composeAccessibleName(
+          t,
+          nameLabel,
+          meaningful(target.label) ?? getStatusLabel(status),
+        );
+        // A consumer's own ARIA wins here exactly as it does in render, where
+        // the derived props spread before `{...props}`.
+        if (consumerAriaLabel == null) {
+          setAttributeOrRemove(element, 'aria-label', composed);
         }
-        if (props['aria-hidden'] == null) {
-          setAttributeOrRemove(
-            element,
-            'aria-hidden',
-            composed ? undefined : 'true',
-          );
+        // An `<a>`/`<button>` root carries its own role and must not be hidden,
+        // so only the name transfers there.
+        if (!isInteractive) {
+          if (consumerRole == null) {
+            element.setAttribute('role', composed ? 'img' : 'presentation');
+          }
+          if (consumerAriaHidden == null) {
+            setAttributeOrRemove(
+              element,
+              'aria-hidden',
+              composed ? undefined : 'true',
+            );
+          }
         }
-      }
-    };
-    target.update();
-    return () => {
-      target.update = null;
-    };
-  };
-  const rootRef = mergeRefs(
+      };
+      target.update();
+      return () => {
+        target.update = null;
+      };
+    },
+    [
+      consumerAriaHidden,
+      consumerAriaLabel,
+      consumerRole,
+      isInteractive,
+      nameLabel,
+      status,
+      t,
+    ],
+  );
+  const rootRef = useMergedRefs(
     ref,
     showTooltip ? tooltipHook.ref : undefined,
     nameRef,