@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

package/src/RadioList/RadioList.tsx

@@ -29,6 +29,7 @@ import {spacingVars} from '../theme/tokens.stylex';
 import {Field} from '../Field/Field';
 import type {InputStatus} from '../Field/types';
 import {useTooltip} from '../Tooltip';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -218,6 +219,13 @@ export function RadioList({
 
   const groupRef = useRef<HTMLDivElement>(null);
 
+  // The radiogroup exposes the *effective* required state so a form-wide
+  // `defaultOptionality="required"` is announced even when the group carries no
+  // visible indicator. Individual radios keep their native `required` bound to
+  // the explicit `isRequired` (via context), so a layout default never switches
+  // on browser validation for the group.
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+
   // Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled
   // controls swallow pointer events, so the tooltip listeners attach to the
   // radiogroup container and the radios stay perceivable via aria-disabled
@@ -387,7 +395,7 @@ export function RadioList({
             .join(' ') || undefined
         }
         aria-invalid={status?.type === 'error' ? true : undefined}
-        aria-required={isRequired || undefined}
+        aria-required={isEffectivelyRequired || undefined}
         {...mergeProps(
           themeProps('radio-list', {orientation, size}),
           stylex.props(

package/src/Selector/Selector.test.tsx

@@ -26,6 +26,7 @@ import {RadioIndicator} from '../Indicator';
 import {InputGroup, InputGroupText} from '../InputGroup';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {__resetInteractionModalityForTest} from '../utils/interactionModality';
+import {InternationalizationProvider} from '../i18n';
 import {defineTheme} from '../theme/defineTheme';
 import {Theme} from '../theme/Theme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
@@ -1000,60 +1001,118 @@ describe('Selector', () => {
       ).toBeInTheDocument();
     });
 
+    it('does not select the highlighted option on a composing Enter (IME)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <Selector
+          label="Fruit"
+          options={OPTIONS}
+          onChange={onChange}
+          hasSearch
+        />,
+      );
+      await user.click(screen.getByRole('button', {name: 'Fruit'}));
+      const search = screen.getByRole('combobox', h);
+      // Filter to Banana and highlight it so an unguarded Enter would commit a
+      // selection.
+      await user.type(search, 'ban');
+      await user.keyboard('{ArrowDown}');
+      expect(search).toHaveAttribute('aria-activedescendant');
+
+      // The browser fires this composing keydown for the Enter that commits an
+      // IME candidate (isComposing: true, or the legacy keyCode 229) before
+      // compositionend writes the syllable. It must NOT be read as "select the
+      // highlighted option".
+      fireEvent.keyDown(search, {key: 'Enter', isComposing: true});
+      expect(onChange).not.toHaveBeenCalled();
+      fireEvent.keyDown(search, {key: 'Enter', keyCode: 229});
+      expect(onChange).not.toHaveBeenCalled();
+
+      // A real, non-composing Enter still selects the highlighted option.
+      fireEvent.keyDown(search, {key: 'Enter'});
+      expect(onChange).toHaveBeenCalledWith('Banana');
+    });
+
     describe('result announcements', () => {
       it('announces the match count politely while searching', async () => {
         const user = userEvent.setup();
         render(
-          <Selector
-            label="Fruit"
-            options={OPTIONS}
-            value="Apple"
-            onChange={() => {}}
-            hasSearch
-          />,
+          <InternationalizationProvider
+            locale="fr"
+            overrides={{
+              fr: {
+                '@astryx.selector.resultCount':
+                  '{count, number} {count, plural, one {résultat} other {résultats}}',
+              },
+            }}>
+            <Selector
+              label="Fruit"
+              options={OPTIONS}
+              value="Apple"
+              onChange={() => {}}
+              hasSearch
+            />
+          </InternationalizationProvider>,
         );
         await user.click(screen.getByRole('button', {name: 'Fruit'}));
         // "a" matches Apple and Banana.
         await user.type(screen.getByRole('combobox', h), 'a');
         await waitFor(() => {
-          expect(politeRegion()).toHaveTextContent('2 results');
+          // The plural branch of a message no catalog supplies.
+          expect(politeRegion()?.textContent).toBe('2 résultats');
         });
       });
 
       it('announces the singular form when one option matches', async () => {
         const user = userEvent.setup();
         render(
-          <Selector
-            label="Fruit"
-            options={OPTIONS}
-            value="Apple"
-            onChange={() => {}}
-            hasSearch
-          />,
+          <InternationalizationProvider
+            locale="fr"
+            overrides={{
+              fr: {
+                '@astryx.selector.resultCount':
+                  '{count, number} {count, plural, one {résultat} other {résultats}}',
+              },
+            }}>
+            <Selector
+              label="Fruit"
+              options={OPTIONS}
+              value="Apple"
+              onChange={() => {}}
+              hasSearch
+            />
+          </InternationalizationProvider>,
         );
         await user.click(screen.getByRole('button', {name: 'Fruit'}));
-        // "ban" matches only Banana. Anchored so it cannot pass on "1 results".
+        // "ban" matches only Banana. Exact, so "1 résultats" would fail.
         await user.type(screen.getByRole('combobox', h), 'ban');
         await waitFor(() => {
-          expect(politeRegion()).toHaveTextContent(/^1 result$/);
+          expect(politeRegion()?.textContent).toBe('1 résultat');
         });
       });
 
-      it('announces "No results found" when nothing matches', async () => {
+      it('announces the empty-results message when nothing matches', async () => {
         const user = userEvent.setup();
         render(
-          <Selector
-            label="Fruit"
-            options={OPTIONS}
-            value="Apple"
-            onChange={() => {}}
-            hasSearch
-          />,
+          <InternationalizationProvider
+            locale="fr"
+            overrides={{
+              fr: {'@astryx.selector.emptySearchResults': 'Aucun résultat'},
+            }}>
+            <Selector
+              label="Fruit"
+              options={OPTIONS}
+              value="Apple"
+              onChange={() => {}}
+              hasSearch
+            />
+          </InternationalizationProvider>,
         );
         await user.click(screen.getByRole('button', {name: 'Fruit'}));
         await user.type(screen.getByRole('combobox', h), 'xyz');
         await waitFor(() => {
-          expect(politeRegion()).toHaveTextContent('No results found');
+          expect(politeRegion()?.textContent).toBe('Aucun résultat');
         });
       });
 

package/src/Selector/Selector.tsx

@@ -71,8 +71,9 @@ import {
 } from './utils';
 import {useCombobox, useSelectedItemOffset} from './hooks';
 import {useTypeahead} from '../hooks/useTypeahead';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {SelectorOption} from './SelectorOption';
-import {getInputARIA, mergeProps} from '../utils';
+import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -699,6 +700,7 @@ export function Selector<T extends SelectorOptionType>(
     hasClear: hasClearProp,
     ...rest
   } = props as SelectorPropsClearable<T>;
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
   const searchPlaceholder =
     searchPlaceholderFromProps ?? t('@astryx.selector.searchPlaceholder');
@@ -844,11 +846,11 @@ export function Selector<T extends SelectorOptionType>(
       const count = filterOptionsByQuery(selectableItems, nextQuery).length;
       announce(
         count === 0
-          ? 'No results found'
-          : `${count} result${count === 1 ? '' : 's'}`,
+          ? t('@astryx.selector.emptySearchResults')
+          : t('@astryx.selector.resultCount', {count}),
       );
     },
-    [announce, selectableItems],
+    [announce, selectableItems, t],
   );
 
   // Calculate offset to position selected item over trigger. Explicit
@@ -1055,6 +1057,15 @@ export function Selector<T extends SelectorOptionType>(
           }
         }}
         onKeyDown={e => {
+          // An in-progress IME composition uses these same keys (Enter to
+          // commit the candidate, Escape/Arrows to navigate the candidate
+          // window); the composing keydown fires before compositionend, so
+          // without this guard a Korean/Japanese/Chinese user committing a
+          // syllable with Enter would instead select the highlighted option.
+          // See utils/ime.ts.
+          if (isImeKeyEvent(e.nativeEvent)) {
+            return;
+          }
           // Arrow keys navigate options; Enter selects; Escape closes.
           // Home/End are left to the input for caret movement (APG editable
           // combobox); PageUp/PageDown are the sanctioned substitute for
@@ -1336,7 +1347,7 @@ export function Selector<T extends SelectorOptionType>(
           }
           aria-describedby={ariaDescribedBy}
           aria-labelledby={ariaLabelledBy}
-          aria-required={isRequired ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={status?.type === 'error' ? 'true' : undefined}
           aria-busy={isBusy || undefined}
           // With a disabledMessage the trigger keeps focusability via

package/src/StatusDot/StatusDot.doc.mjs

@@ -33,6 +33,12 @@ export const docs = {
       description:
         'Tooltip text shown on hover to explain the status meaning.',
     },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        'Optional icon rendered centered inside the dot, painted in currentColor (the variant\'s ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -84,6 +90,12 @@ export const docsZh = {
         '启用脉冲动画；尊重 prefers-reduced-motion: reduce 设置。',
       default: 'false',
     },
+    {
+      name: 'icon',
+      type: 'ReactNode',
+      description:
+        '可选图标，居中渲染于圆点内，以 currentColor（变体的前景色）着色。为状态提供非颜色标记，请为每个状态使用不同图标。布尔值和空字符串会被忽略，因此 `cond && <Icon />` 是安全的。与 AvatarStatusDot 的契约一致。',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -132,6 +144,7 @@ export const docsDense = {
     label: 'Accessible label via aria-label.',
     isPulsing: 'Pulse animation; respects prefers-reduced-motion: reduce.',
     tooltip: 'Tooltip text on hover to explain status meaning.',
+    icon: 'Optional ReactNode rendered centered in the dot (currentColor ink); a non-color mark for the status, use a different icon per status. Booleans/empty strings ignored (safe for cond && <Icon/>). Same contract as AvatarStatusDot.',
     xstyle: 'StyleX layout styles; must be stylex.create() value.',
   },
 };

package/src/StatusDot/StatusDot.test.tsx

@@ -2,8 +2,16 @@
 
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {StatusDot} from './StatusDot';
 
+/** Renders a StatusDot and returns its root element. */
+function renderDot(props: React.ComponentProps<typeof StatusDot>) {
+  render(<StatusDot {...props} />);
+  return screen.getByRole('img', {name: props.label});
+}
+
 describe('StatusDot', () => {
   it('renders with role="img" and aria-label', () => {
     render(<StatusDot variant="success" label="Online" />);
@@ -27,9 +35,7 @@ describe('StatusDot', () => {
     ] as const;
 
     for (const variant of variants) {
-      const {unmount} = render(
-        <StatusDot variant={variant} label={variant} />,
-      );
+      const {unmount} = render(<StatusDot variant={variant} label={variant} />);
       expect(screen.getByRole('img', {name: variant})).toBeInTheDocument();
       unmount();
     }
@@ -49,11 +55,7 @@ describe('StatusDot', () => {
 
   it('supports data-testid', () => {
     render(
-      <StatusDot
-        variant="success"
-        label="Online"
-        data-testid="status-dot"
-      />,
+      <StatusDot variant="success" label="Online" data-testid="status-dot" />,
     );
     expect(screen.getByTestId('status-dot')).toBeInTheDocument();
   });
@@ -81,4 +83,109 @@ describe('StatusDot', () => {
     const dot = screen.getByRole('img', {name: 'Online'});
     expect(dot).toBeInTheDocument();
   });
+
+  it('renders every variant as a plain childless dot by default (design review #4373)', () => {
+    // The dot is deliberately a colour-only signal by default — no built-in
+    // per-variant glyph. Making the status accessible in context (label,
+    // icon, or an accessible alternative) is the builder's responsibility;
+    // see the usage guidance.
+    const variants = [
+      'success',
+      'warning',
+      'error',
+      'accent',
+      'neutral',
+    ] as const;
+    for (const variant of variants) {
+      const dot = renderDot({variant, label: `plain-${variant}`});
+      expect(dot.childElementCount, variant).toBe(0);
+    }
+  });
+
+  describe('custom icon (parity with AvatarStatusDot)', () => {
+    const ICON_TESTID = 'custom-icon';
+    function Icon() {
+      return <svg data-testid={ICON_TESTID} />;
+    }
+
+    it('renders a provided icon inside the dot', () => {
+      renderDot({variant: 'success', label: 'Verified', icon: <Icon />});
+      expect(screen.getByTestId(ICON_TESTID)).toBeInTheDocument();
+    });
+
+    it('hides the icon wrapper from assistive tech (the label carries the status)', () => {
+      renderDot({variant: 'success', label: 'Verified', icon: <Icon />});
+      const iconEl = screen.getByTestId(ICON_TESTID);
+      expect(iconEl.closest('[aria-hidden="true"]')).not.toBeNull();
+    });
+
+    it.each([false, true, null, undefined, ''])(
+      'ignores %s and keeps the plain dot (safe for `cond && <Icon />`)',
+      value => {
+        const dot = renderDot({
+          variant: 'error',
+          label: 'Offline',
+          icon: value,
+        });
+        expect(dot.childElementCount).toBe(0);
+      },
+    );
+
+    it('keeps the accessible name on the dot when an icon renders', () => {
+      const dot = renderDot({
+        variant: 'success',
+        label: 'Verified',
+        icon: <Icon />,
+      });
+      expect(dot).toHaveAttribute('role', 'img');
+      expect(dot).toHaveAttribute('aria-label', 'Verified');
+    });
+  });
+
+  describe('variant ink (a passed icon paints from currentColor)', () => {
+    it('pairs the warning plate with the dedicated dark on-warning ink', () => {
+      // The regression this guards: a light surface ink on the yellow warning
+      // plate lands near 2:1, while `--color-on-warning` is the fixed dark
+      // ink (~9.6:1). An icon inherits the ink via `currentColor`, so the
+      // pairing is what keeps custom icons legible.
+      const probe = stylex.create({
+        warning: {
+          backgroundColor: colorVars['--color-warning'],
+          color: colorVars['--color-on-warning'],
+        },
+      });
+      const dot = renderDot({variant: 'warning', label: 'Degraded'});
+      const atomicClasses = (stylex.props(probe.warning).className ?? '')
+        .split(' ')
+        // Dev mode prepends a per-file `File__style.key` debug class that
+        // legitimately differs between the probe and the component.
+        .filter(cls => !cls.includes('__'));
+      expect(atomicClasses.length).toBeGreaterThan(0);
+      for (const cls of atomicClasses) {
+        expect(dot.className).toContain(cls);
+      }
+    });
+  });
+
+  describe('accessible name (label reaches AT without hover)', () => {
+    it('exposes the status label as the accessible name for every variant, without a tooltip', () => {
+      const variants = [
+        'success',
+        'warning',
+        'error',
+        'accent',
+        'neutral',
+      ] as const;
+      for (const variant of variants) {
+        const {unmount} = render(
+          <StatusDot variant={variant} label={`Status: ${variant}`} />,
+        );
+        const dot = screen.getByRole('img', {name: `Status: ${variant}`});
+        expect(dot).toHaveAttribute('aria-label', `Status: ${variant}`);
+        // The name must not depend on hover or focus.
+        expect(dot.getAttribute('tabindex')).toBeNull();
+        unmount();
+      }
+    });
+  });
 });

package/src/StatusDot/StatusDot.tsx

@@ -16,11 +16,13 @@
  * - /packages/cli/assets/templates/blocks/components/StatusDot/ (showcase blocks)
  */
 
+import type {ReactNode} from 'react';
+
 import * as stylex from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Tooltip} from '../Tooltip/Tooltip';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 import type {StatusDotVariantMap} from './index';
 
@@ -33,16 +35,21 @@ const pulseKeyframes = stylex.keyframes({
   '100%': {opacity: 1},
 });
 
+/** Fixed dot size in px. A user-supplied icon is drawn into this same field. */
+const DOT_SIZE = 8;
+
 /**
  * Base styles
  */
 const styles = stylex.create({
   base: {
-    display: 'inline-block',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
     borderRadius: '50%',
     flexShrink: 0,
-    width: '8px',
-    height: '8px',
+    width: `${DOT_SIZE}px`,
+    height: `${DOT_SIZE}px`,
   },
   pulsing: {
     animationName: pulseKeyframes,
@@ -55,26 +62,49 @@ const styles = stylex.create({
       animationName: 'none',
     },
   },
+  // A user-supplied icon fills the whole 8px field and paints from
+  // `currentColor` (the variant's ink).
+  icon: {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    lineHeight: 0,
+    width: `${DOT_SIZE}px`,
+    height: `${DOT_SIZE}px`,
+  },
 });
 
 /**
- * Variant styles mapping to theme color tokens
+ * Variant styles mapping to theme color tokens.
+ *
+ * Each variant sets both the plate colour and an ink colour: a user-supplied
+ * `icon` paints from `currentColor`, so plate and ink can never drift out of
+ * contrast (same contract as AvatarStatusDot). The ink is each plate's
+ * dedicated `--color-on-*` pairing (the Badge precedent), not the surface
+ * colour: on-warning is a fixed dark ink, which keeps an icon legible on the
+ * yellow plate (~9.6:1) where a light surface ink lands near 2:1. Neutral has
+ * no `--color-on-*` token; its mid-grey plate takes the surface ink.
  */
 const variants = stylex.create({
   success: {
     backgroundColor: colorVars['--color-success'],
+    color: colorVars['--color-on-success'],
   },
   warning: {
     backgroundColor: colorVars['--color-warning'],
+    color: colorVars['--color-on-warning'],
   },
   error: {
     backgroundColor: colorVars['--color-error'],
+    color: colorVars['--color-on-error'],
   },
   accent: {
     backgroundColor: colorVars['--color-accent'],
+    color: colorVars['--color-on-accent'],
   },
   neutral: {
     backgroundColor: colorVars['--color-icon-secondary'],
+    color: colorVars['--color-background-surface'],
   },
 });
 
@@ -92,7 +122,8 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
    */
   variant: StatusDotVariant;
   /**
-   * Accessible label describing the status. Required for a11y.
+   * Accessible label describing the status. Required for a11y — it is the
+   * dot's `aria-label`, so the status reaches screen readers without hover.
    */
   label: string;
   /**
@@ -106,12 +137,36 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
    * When omitted, no tooltip is rendered.
    */
   tooltip?: string;
+  /**
+   * Optional icon to render centered inside the dot. Accepts any ReactNode
+   * (typically an SVG icon), painted in the dot's `currentColor` ink. Same
+   * contract as `AvatarStatusDot`'s `icon`.
+   *
+   * By default the dot is a colour-only signal; an icon gives the status a
+   * non-colour mark, so use a different icon per status — the same icon on
+   * every variant leaves the statuses distinguishable by colour alone
+   * (WCAG 2.1 SC 1.4.1). Booleans and empty strings are ignored (safe for
+   * `cond && <Icon />`).
+   *
+   * @example
+   * ```
+   * <StatusDot variant="success" label="Verified" icon={<CheckIcon />} />
+   * ```
+   */
+  icon?: ReactNode;
 }
 
 /**
  * A small colored dot indicator for status display (online/offline, severity, etc).
  *
- * Fixed 8px size. Renders as a non-focusable `<span>` with `role="img"` and
+ * Fixed 8px size. By default the dot conveys status by colour only, which is
+ * not accessible in isolation (WCAG 2.1 SC 1.4.1) — treat it as a signal the
+ * surrounding UI must make accessible: use it as a binary present/absent
+ * signal, pair it with a visible label, pass `icon` so the status carries a
+ * non-colour mark, or convey the status accessibly elsewhere. See the usage
+ * guidance in the component docs.
+ *
+ * Renders as a non-focusable `<span>` with `role="img"` and
  * `aria-label` for accessibility. Styles use Astryx theme tokens via StyleX.
  * Wrap your app in `<Theme>` to apply a theme.
  *
@@ -121,6 +176,7 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
  * <StatusDot variant="error" label="Offline" />
  * <StatusDot variant="success" label="Live" isPulsing />
  * <StatusDot variant="success" label="Online" tooltip="Online" />
+ * <StatusDot variant="success" label="Verified" icon={<CheckIcon />} />
  * ```
  */
 export function StatusDot({
@@ -128,12 +184,16 @@ export function StatusDot({
   label,
   isPulsing = false,
   tooltip,
+  icon,
   xstyle,
   className,
   style,
   ref,
   ...props
 }: StatusDotProps) {
+  // Booleans and empty renders don't count (safe for `cond && <Icon />`) —
+  // same contract as AvatarStatusDot.
+  const showsIcon = isRenderable(icon);
   const dot = (
     <span
       ref={ref}
@@ -151,8 +211,13 @@ export function StatusDot({
         className,
         style,
       )}
-      {...props}
-    />
+      {...props}>
+      {showsIcon && (
+        <span aria-hidden="true" {...stylex.props(styles.icon)}>
+          {icon}
+        </span>
+      )}
+    </span>
   );
 
   if (tooltip) {

package/src/Switch/Switch.test.tsx

@@ -262,6 +262,22 @@ describe('Switch', () => {
     expect(screen.getByLabelText('Toggle row')).toBeInTheDocument();
   });
 
+  it('drops the label gap when isLabelHidden so the row is only as wide as the track', () => {
+    const {rerender} = render(
+      <Switch
+        label="Toggle row"
+        isLabelHidden
+        value={false}
+        onChange={() => {}}
+      />,
+    );
+    const row = screen.getByRole('switch').parentElement!.parentElement!;
+    expect(getComputedStyle(row).gap).toMatch(/^0(px)?$/);
+
+    rerender(<Switch label="Toggle row" value={false} onChange={() => {}} />);
+    expect(getComputedStyle(row).gap).not.toMatch(/^0(px)?$/);
+  });
+
   it('keeps description linked via aria-describedby when isLabelHidden', () => {
     render(
       <Switch

package/src/Switch/Switch.tsx

@@ -47,6 +47,7 @@ import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {VisuallyHidden} from '../VisuallyHidden';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 
 const wrapperSizeStyles = stylex.create({
   sm: {
@@ -135,6 +136,12 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
   },
+  // A hidden label is sr-only, so its wrapper is a zero-width flex item — the
+  // row gap would still be painted beside the track, making the field box
+  // wider than the control it contains. Matches CheckboxInput.
+  containerLabelHidden: {
+    gap: 0,
+  },
   containerSpread: {
     justifyContent: 'space-between',
     width: '100%',
@@ -497,6 +504,10 @@ export function Switch({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  // Announce the effective required state (form default included) while the
+  // native `required` stays bound to the explicit `isRequired` so a layout
+  // default never switches on browser validation.
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -553,6 +564,7 @@ export function Switch({
         aria-disabled={showsDisabledMessage ? 'true' : undefined}
         form={showsDisabledMessage ? '' : undefined}
         required={isRequired}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         onChange={e => {
           if (isDisabled || isBusy) {
             return;
@@ -655,6 +667,7 @@ export function Switch({
         }}
         {...stylex.props(
           styles.container,
+          isLabelHidden && styles.containerLabelHidden,
           labelSpacing === 'spread' && styles.containerSpread,
           !isDisabled && switchScope,
         )}>