@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/Timestamp/tooltipEntries.ts

@@ -0,0 +1,210 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tooltipEntries.ts
+ * @input A Date and the consumer's tooltip entry list
+ * @output Pure formatting of one tooltip line per entry, plus the entry types
+ * @position Leaf module; owns which zone each tooltip line names and whether
+ *   it needs a zone abbreviation, then defers to formatInstant to render it
+ *
+ * This module holds only the decisions a tooltip makes that the visible text
+ * does not: resolving `timezoneID` (including the `'local'` alias and the
+ * fallback for an unknown identifier), and deciding which lines need a zone
+ * abbreviation to be told apart. The formatting itself is formatInstant's,
+ * shared with the rendered text, so the two surfaces cannot drift.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Timestamp/Timestamp.tsx
+ * - /packages/core/src/Timestamp/formatInstant.ts
+ * - /packages/core/src/Timestamp/tooltipEntries.test.ts
+ * - /packages/core/src/Timestamp/Timestamp.doc.mjs
+ * - /packages/core/src/Timestamp/index.ts
+ */
+
+import {devWarn} from '../utils/devWarning';
+import {formatInstant} from './formatInstant';
+import type {InstantFormat} from './formatInstant';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Formats available to a tooltip line.
+ *
+ * Every `TimestampFormat` that names a fixed instant, plus `'full'` — the long
+ * absolute style the tooltip has always shown ("February 19, 2026 at 5:00:00 PM
+ * UTC"). `'relative'` and `'auto'` are excluded: a relative phrase ignores any
+ * zone, which would make `timezoneID` silently inert on that line.
+ *
+ * `'full'` lives only in this vocabulary, never in `TimestampFormat` — nothing
+ * asked for it as a visible display format, and keeping it out means new
+ * members added to `TimestampFormat` become valid tooltip formats for free.
+ *
+ * The public spelling of {@link InstantFormat}: consumers reading Timestamp's
+ * props should not have to know the name of its internal formatter.
+ */
+export type TimestampTooltipFormat = InstantFormat;
+
+/** One line of the Timestamp tooltip. */
+export interface TimestampTooltipEntry {
+  /**
+   * IANA time zone identifier, e.g. `'UTC'`, `'America/Los_Angeles'`.
+   * Omit it — or pass `'local'` — for the viewer's own zone.
+   *
+   * Prefer region identifiers. Fixed-offset abbreviations such as `'EST'` are
+   * accepted by the platform but never observe daylight saving, so they read
+   * an hour wrong for half the year — `'America/New_York'` is what people
+   * usually mean by "Eastern".
+   *
+   * An identifier the platform does not recognize falls back to the viewer's
+   * zone with a console warning rather than throwing.
+   */
+  timezoneID?: string;
+  /**
+   * How this line renders the instant.
+   * @default 'full'
+   */
+  format?: TimestampTooltipFormat;
+  /**
+   * Text shown beside the time, e.g. `'Local'`, `'UTC'`, `'Pacific'`.
+   * Supplied already translated; Timestamp never invents or localizes labels.
+   */
+  label?: string;
+}
+
+/** A rendered tooltip line. */
+export interface TimestampTooltipLine {
+  label?: string;
+  value: string;
+}
+
+// =============================================================================
+// Zone resolution
+// =============================================================================
+
+/** Spelling that means "the viewer's own zone" without naming it. */
+const LOCAL_ZONE_ALIAS = 'local';
+
+/**
+ * Zone identifiers already reported as unknown.
+ *
+ * Resolution runs once per entry on every render, so without this a single
+ * typo on a live timestamp would emit the same warning every tick, forever.
+ * One report per bad identifier is enough to act on.
+ */
+const warnedTimezoneIDs = new Set<string>();
+
+/**
+ * Resolves an entry's zone to something safe to hand to `Intl`.
+ *
+ * Returns `undefined` for the viewer's own zone, which is also what `Intl`
+ * treats as "use the host zone" — so the local path never constructs a
+ * formatter with an explicit `timeZone` and cannot drift from today's output.
+ */
+function resolveTimezoneID(timezoneID: string | undefined): string | undefined {
+  if (
+    timezoneID === undefined ||
+    timezoneID.toLowerCase() === LOCAL_ZONE_ALIAS
+  ) {
+    return undefined;
+  }
+
+  // An unrecognized identifier makes every Intl.DateTimeFormat constructor
+  // throw a RangeError. Rendering a timestamp must never take down the tree —
+  // degrade to the viewer's zone and say so, mirroring how an unparseable
+  // `value` is handled in Timestamp.tsx.
+  try {
+    new Intl.DateTimeFormat(undefined, {timeZone: timezoneID});
+  } catch {
+    if (!warnedTimezoneIDs.has(timezoneID)) {
+      warnedTimezoneIDs.add(timezoneID);
+      devWarn(
+        'Timestamp',
+        `unknown time zone ${JSON.stringify(timezoneID)} in tooltipEntries. Falling back to the viewer's time zone.`,
+      );
+    }
+    return undefined;
+  }
+
+  return timezoneID;
+}
+
+/**
+ * A stable key for "which zone did the consumer ask for", used to decide
+ * whether the tooltip needs zone abbreviations to disambiguate its lines.
+ *
+ * Deliberately keyed on the *requested* zone, not on the resolved offset: a
+ * consumer who asks for two zones gets both labelled even when the viewer
+ * happens to be sitting in one of them, so the rendering does not change shape
+ * depending on where the reader is. That also keeps this testable under any
+ * machine timezone.
+ */
+function zoneKey(resolved: string | undefined): string {
+  return resolved === undefined ? LOCAL_ZONE_ALIAS : resolved.toLowerCase();
+}
+
+// =============================================================================
+// Zone marking
+// =============================================================================
+
+/**
+ * Whether a format should carry a zone abbreviation.
+ *
+ * `'full'` always has one (that is the style). `system_*` never does — those
+ * are machine shapes and a trailing "PST" would break anything parsing them,
+ * which is also why `isTimezoneShown` has never applied to them.
+ *
+ * The two human formats that can carry one do so when either the reader has
+ * to tell several lines apart, or the line shows a zone the consumer named
+ * explicitly. That second case matters even for a lone entry: the tooltip is
+ * the `<time>` element's `aria-describedby`, and that element's accessible
+ * name is the absolute time in the *viewer's* zone — so an unmarked foreign
+ * time is announced directly after a local one with nothing to distinguish
+ * them. A line the consumer did not steer stays unmarked, matching how the
+ * visible text reads with `isTimezoneShown` off.
+ */
+function shouldShowZoneName(
+  format: TimestampTooltipFormat,
+  hasMultipleZones: boolean,
+  isNamedZone: boolean,
+): boolean {
+  if (format === 'full') {
+    return true;
+  }
+  if (format === 'date_time' || format === 'time') {
+    return hasMultipleZones || isNamedZone;
+  }
+  return false;
+}
+
+/**
+ * Renders one tooltip line per entry, in the order given.
+ *
+ * Pure: the same `date` and `entries` always produce the same lines for a given
+ * host zone and locale.
+ */
+export function formatTooltipLines(
+  date: Date,
+  entries: ReadonlyArray<TimestampTooltipEntry>,
+): ReadonlyArray<TimestampTooltipLine> {
+  const resolved = entries.map(entry => resolveTimezoneID(entry.timezoneID));
+  const hasMultipleZones = new Set(resolved.map(zoneKey)).size > 1;
+
+  return entries.map((entry, index) => {
+    const format = entry.format ?? 'full';
+    const timeZone = resolved[index];
+
+    return {
+      ...(entry.label === undefined ? {} : {label: entry.label}),
+      value: formatInstant(date, format, {
+        timeZone,
+        isTimezoneShown: shouldShowZoneName(
+          format,
+          hasMultipleZones,
+          timeZone !== undefined,
+        ),
+      }),
+    };
+  });
+}

package/src/Toast/ToastViewport.test.tsx

@@ -3,19 +3,56 @@
 /**
  * @file ToastViewport.test.tsx
  * @input Uses vitest, @testing-library/react, ToastViewport + useToast
- * @output Unit tests for toast keyboard reach and focus management
- * @position Testing; validates ToastViewport.tsx + Toast.tsx focus behavior
+ * @output Unit tests for toast keyboard reach, focus management, and
+ *   screen-reader announcements
+ * @position Testing; validates ToastViewport.tsx + Toast.tsx focus behavior and
+ *   the announce-at-dispatch flow through the singleton live regions
  *
- * SYNC: When ToastViewport.tsx or Toast.tsx focus handling changes, update these tests
+ * SYNC: When ToastViewport.tsx / Toast.tsx focus handling or the toast
+ *   announcement flow changes, update these tests
  */
 
-import {describe, it, expect, vi, beforeAll} from 'vitest';
-import {render, screen, fireEvent, act} from '@testing-library/react';
+import {describe, it, expect, vi, beforeAll, afterEach} from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  act,
+  waitFor,
+  within,
+} from '@testing-library/react';
 import React from 'react';
+import {type AnnounceFn, __resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {ToastViewport} from './ToastViewport';
 import {useToast} from './useToast';
 import type {ToastOptions} from './types';
 
+// Spy on the announcement sink so tests can prove a toast is announced exactly
+// once. The mock wraps the real useAnnounce, so the singleton live regions are
+// still populated (the region-content assertions below depend on it) while
+// every call is also recorded on announceSpy.
+const {announceSpy} = vi.hoisted(() => ({announceSpy: vi.fn()}));
+vi.mock('../hooks/useAnnounce', async importActual => {
+  const actual = await importActual<{
+    useAnnounce: () => AnnounceFn;
+    __resetLiveRegionsForTest: () => void;
+  }>();
+  const {useCallback} = await import('react');
+  return {
+    ...actual,
+    useAnnounce: (): AnnounceFn => {
+      const realAnnounce = actual.useAnnounce();
+      return useCallback<AnnounceFn>(
+        (message, politeness) => {
+          announceSpy(message, politeness);
+          realAnnounce(message, politeness);
+        },
+        [realAnnounce],
+      );
+    },
+  };
+});
+
 // Popover API is not implemented in jsdom.
 beforeAll(() => {
   if (typeof HTMLElement.prototype.showPopover === 'undefined') {
@@ -24,6 +61,13 @@ beforeAll(() => {
   }
 });
 
+// Toast text is mirrored into the singleton live regions, which outlive each
+// render — reset them so text from one test never leaks into the next.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+  announceSpy.mockClear();
+});
+
 // Module-level constant default props (avoids unstable-default-props lint).
 const EMPTY_OPTIONS: ToastOptions = {body: 'placeholder'};
 
@@ -169,7 +213,10 @@ describe('Toast blur timer pause', () => {
       act(() => {
         fireEvent.click(screen.getByText('Trigger Auto'));
       });
-      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+      // Scope to the viewport: the toast text is also mirrored into the
+      // singleton live region, which lives outside the notifications region.
+      const viewport = screen.getByRole('region', {name: 'Notifications'});
+      expect(within(viewport).getByText('Auto toast')).toBeInTheDocument();
 
       // Window loses focus — timer should pause.
       act(() => {
@@ -179,7 +226,7 @@ describe('Toast blur timer pause', () => {
         vi.advanceTimersByTime(5000);
       });
       // Still present because the timer was paused while blurred.
-      expect(screen.getByText('Auto toast')).toBeInTheDocument();
+      expect(within(viewport).getByText('Auto toast')).toBeInTheDocument();
 
       // Window regains focus — timer resumes and the toast dismisses.
       act(() => {
@@ -196,7 +243,9 @@ describe('Toast blur timer pause', () => {
           completeExit(toastId);
         });
       }
-      expect(screen.queryByText('Auto toast')).not.toBeInTheDocument();
+      expect(
+        within(viewport).queryByText('Auto toast'),
+      ).not.toBeInTheDocument();
     } finally {
       vi.useRealTimers();
     }
@@ -213,6 +262,167 @@ describe('ToastViewport region ARIA', () => {
   });
 });
 
+describe('toast announcements via singleton live regions', () => {
+  function politeRegion(): HTMLElement | null {
+    return document.querySelector('[data-astryx-live-region="polite"]');
+  }
+  function assertiveRegion(): HTMLElement | null {
+    return document.querySelector('[data-astryx-live-region="assertive"]');
+  }
+
+  const RICH_INFO: ToastOptions = {
+    body: (
+      <>
+        <strong>Update ready</strong>
+        <div>Restart to apply</div>
+      </>
+    ),
+  };
+  const ERROR_TOAST: ToastOptions = {body: 'Upload failed', type: 'error'};
+  const SAVING_V1: ToastOptions = {uniqueID: 'save', body: 'Saving changes'};
+  const SAVING_V2: ToastOptions = {uniqueID: 'save', body: 'Changes saved'};
+  const IGNORE_KEPT: ToastOptions = {
+    uniqueID: 'dup',
+    collisionBehavior: 'ignore',
+    body: 'Kept',
+  };
+  const IGNORE_DROPPED: ToastOptions = {
+    uniqueID: 'dup',
+    collisionBehavior: 'ignore',
+    body: 'Dropped',
+  };
+
+  it('announces an info toast politely with its flattened text content', async () => {
+    renderViewport(<ShowToastButton options={RICH_INFO} triggerLabel="Show" />);
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    // Announced synchronously at dispatch, exactly once.
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenCalledWith(
+      'Update ready Restart to apply',
+      'polite',
+    );
+    // The flattened text reaches the polite singleton region (the sink).
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Update ready Restart to apply');
+    });
+    // Status toasts never touch the assertive region.
+    expect(assertiveRegion()).toHaveTextContent('');
+  });
+
+  it('announces an error toast assertively', async () => {
+    renderViewport(
+      <ShowToastButton options={ERROR_TOAST} triggerLabel="Show" />,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenCalledWith('Upload failed', 'assertive');
+    await waitFor(() => {
+      expect(assertiveRegion()).toHaveTextContent('Upload failed');
+    });
+    expect(politeRegion()).toHaveTextContent('');
+  });
+
+  it('announces exactly once at dispatch, even under StrictMode', () => {
+    render(
+      <React.StrictMode>
+        <ToastViewport isTopLayer={false}>
+          <ShowToastButton options={INFO_A} triggerLabel="Show" />
+        </ToastViewport>
+      </React.StrictMode>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show'));
+    });
+    // The announcement lives in the imperative dispatch path (addToast), not a
+    // render effect, so StrictMode's double render and double-invoked state
+    // updater cannot announce the same toast twice.
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenCalledWith('Toast A', 'polite');
+  });
+
+  it('re-announces a uniqueID toast when its content is overwritten', async () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={SAVING_V1} triggerLabel="Show v1" />
+        <ShowToastButton options={SAVING_V2} triggerLabel="Show v2" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show v1'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenLastCalledWith('Saving changes', 'polite');
+    // Overwriting via uniqueID replaces the toast in place — the new content is
+    // a fresh dispatch and must be announced again.
+    act(() => {
+      fireEvent.click(screen.getByText('Show v2'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(2);
+    expect(announceSpy).toHaveBeenLastCalledWith('Changes saved', 'polite');
+    await waitFor(() => {
+      expect(politeRegion()).toHaveTextContent('Changes saved');
+    });
+    // Still a single toast on screen — overwritten in place, not stacked.
+    const viewport = screen.getByRole('region', {name: 'Notifications'});
+    expect(
+      within(viewport).queryAllByText(/Saving changes|Changes saved/),
+    ).toHaveLength(1);
+  });
+
+  it('does not re-announce an unchanged toast when an unrelated render occurs', () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={INFO_A} triggerLabel="Show A" />
+        <ShowToastButton options={ERROR_TOAST} triggerLabel="Show B" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show A'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    // A second toast arriving re-renders the viewport with a new toast list.
+    // Toast A is not re-dispatched, so it must not be announced again — only
+    // the newly dispatched toast produces a call.
+    act(() => {
+      fireEvent.click(screen.getByText('Show B'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(2);
+    expect(announceSpy).toHaveBeenNthCalledWith(1, 'Toast A', 'polite');
+    expect(announceSpy).toHaveBeenNthCalledWith(
+      2,
+      'Upload failed',
+      'assertive',
+    );
+  });
+
+  it('does not announce a toast whose uniqueID collision is ignored', () => {
+    renderViewport(
+      <>
+        <ShowToastButton options={IGNORE_KEPT} triggerLabel="Show 1" />
+        <ShowToastButton options={IGNORE_DROPPED} triggerLabel="Show 2" />
+      </>,
+    );
+    act(() => {
+      fireEvent.click(screen.getByText('Show 1'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    expect(announceSpy).toHaveBeenLastCalledWith('Kept', 'polite');
+    // The colliding toast is suppressed (collisionBehavior: 'ignore'), so it is
+    // neither shown nor announced.
+    act(() => {
+      fireEvent.click(screen.getByText('Show 2'));
+    });
+    expect(announceSpy).toHaveBeenCalledTimes(1);
+    const viewport = screen.getByRole('region', {name: 'Notifications'});
+    expect(within(viewport).getByText('Kept')).toBeInTheDocument();
+    expect(within(viewport).queryByText('Dropped')).not.toBeInTheDocument();
+  });
+});
+
 describe('toast timer lifecycle (#3589)', () => {
   it('fires onHide exactly once when dismissed twice during the exit window', () => {
     const onHide = vi.fn();

package/src/Toast/ToastViewport.tsx

@@ -3,6 +3,7 @@
 'use client';
 
 import {
+  isValidElement,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -10,10 +11,12 @@ import {
   useRef,
   useState,
 } from 'react';
+import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {Toast} from './Toast';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import type {ToastEntry, ToastPosition, ToastDismissReason} from './types';
@@ -76,6 +79,29 @@ const styles = stylex.create({
   },
 });
 
+// Flatten a toast's rendered content (title, description, etc.) to the plain
+// text that should be spoken by a screen reader. Only text is announced —
+// interactive endContent is deliberately excluded (it is reachable via F6).
+function getNodeText(node: ReactNode): string {
+  if (node == null || typeof node === 'boolean') {
+    return '';
+  }
+  if (typeof node === 'string') {
+    return node;
+  }
+  if (typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(getNodeText).filter(Boolean).join(' ');
+  }
+  if (isValidElement(node)) {
+    const {children} = node.props as {children?: ReactNode};
+    return getNodeText(children);
+  }
+  return '';
+}
+
 export interface ToastViewportProps {
   position?: ToastPosition;
   maxVisible?: number;
@@ -159,21 +185,54 @@ export function ToastViewport({
     [],
   );
 
-  const addToast = useCallback((entry: ToastEntry) => {
-    setToasts(prev => {
+  // Announce toasts through the persistent singleton live regions. Each
+  // <Toast> also renders its own role="status"/"alert" region, but that region
+  // is "born with content" — mounted together with its text — which many
+  // screen readers do not announce (see useAnnounce.ts); the singleton regions
+  // are mounted empty and only mutated afterwards, so they are what actually
+  // guarantees the announcement (the per-toast markup is kept for browse-mode
+  // discoverability). The announcement happens in addToast — the imperative
+  // dispatch path invoked once per useToast() call from an event handler,
+  // never from render — so each toast is announced exactly once by
+  // construction, independent of the React render lifecycle (StrictMode
+  // double-render/double-effect, viewport remounts, and unrelated list
+  // re-renders never re-announce). It is client-only (addToast never runs
+  // during SSR), so it is SSR-safe.
+  const announce = useAnnounce();
+
+  const addToast = useCallback(
+    (entry: ToastEntry) => {
       const {uniqueID, collisionBehavior = 'overwrite'} = entry.options;
-      if (uniqueID) {
-        const existing = prev.find(t => t.options.uniqueID === uniqueID);
-        if (existing) {
-          if (collisionBehavior === 'ignore') {
-            return prev;
+      // Resolve an ignored collision synchronously against the committed list
+      // so a suppressed toast is neither shown nor announced. The remaining
+      // announce + setToasts run outside the setToasts updater, which React may
+      // invoke more than once — keeping the announcement exactly-once.
+      if (
+        uniqueID &&
+        collisionBehavior === 'ignore' &&
+        toastsRef.current.some(t => t.options.uniqueID === uniqueID)
+      ) {
+        return;
+      }
+      const text = getNodeText(entry.options.body);
+      if (text) {
+        // Error toasts map to the assertive region (role="alert"); everything
+        // else to the polite region (role="status") — mirrors Toast.tsx.
+        announce(text, entry.options.type === 'error' ? 'assertive' : 'polite');
+      }
+      setToasts(prev => {
+        if (uniqueID) {
+          const existing = prev.find(t => t.options.uniqueID === uniqueID);
+          if (existing) {
+            // An ignored collision already returned above; overwrite in place.
+            return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
           }
-          return prev.map(t => (t.options.uniqueID === uniqueID ? entry : t));
         }
-      }
-      return [...prev, entry];
-    });
-  }, []);
+        return [...prev, entry];
+      });
+    },
+    [announce],
+  );
 
   const removeToast = useCallback((id: string, reason: ToastDismissReason) => {
     // An exiting toast stays in toastsRef until its exit transition ends, so

package/src/ToggleButton/ToggleButton.test.tsx

@@ -14,6 +14,10 @@ import userEvent from '@testing-library/user-event';
 import {useState, type MouseEvent} from 'react';
 import {ToggleButton} from './ToggleButton';
 import {ToggleButtonGroup} from './ToggleButtonGroup';
+import {
+  getAllInjectedCss,
+  getForcedColorsRules,
+} from '../__tests__/forcedColors';
 
 // =============================================================================
 // ToggleButton — Standalone
@@ -517,3 +521,23 @@ describe('ToggleButtonGroup (multiple)', () => {
     );
   });
 });
+
+// jsdom cannot emulate forced-colors rendering, so these assert that the
+// compiled output includes the forced-colors rules; visual behavior needs
+// manual verification under Windows High Contrast.
+describe('forced colors (WCAG 1.4.11)', () => {
+  it('compiles forced-colors overrides so the pressed state survives Windows High Contrast', () => {
+    render(<ToggleButton label="Bold" isPressed onPressedChange={() => {}} />);
+    const css = getForcedColorsRules();
+    // The painted pressed overlay is stripped; Highlight/HighlightText marks
+    // the pressed toggle (critical for icon-only toggles, which otherwise
+    // lose all pressed indication).
+    expect(css).toContain('background-color: highlight;');
+    expect(css).toContain('color: highlighttext;');
+    // ToggleButton renders a <button>; without opting out of UA remapping it
+    // keeps the native ButtonFace surface and ignores the Highlight fill,
+    // leaving HighlightText text on a white surface. forced-color-adjust: none
+    // makes both render as authored.
+    expect(getAllInjectedCss()).toContain('forced-color-adjust: none;');
+  });
+});

package/src/ToggleButton/ToggleButton.tsx

@@ -40,7 +40,25 @@ import {themeProps} from '../utils/themeProps';
  */
 const pressedStyles = stylex.create({
   background: {
-    backgroundColor: colorVars['--color-overlay-pressed'],
+    // forced-color-adjust must be `none` here: ToggleButton renders a <button>,
+    // and the UA keeps native form-control colors (ButtonFace surface) for it
+    // under forced colors, ignoring the authored Highlight fill — the label kept
+    // its HighlightText color, giving white text on a white surface. Opting the
+    // pressed button out of UA remapping makes both the Highlight surface and
+    // the HighlightText label render as authored, restoring figure-ground.
+    forcedColorAdjust: 'none',
+    backgroundColor: {
+      default: colorVars['--color-overlay-pressed'],
+      // Forced colors (Windows High Contrast) strips the painted pressed
+      // overlay, which would leave icon-only toggles with no pressed
+      // indication at all. Highlight/HighlightText is the platform convention
+      // for a selected/pressed control (WCAG 1.4.11).
+      '@media (forced-colors: active)': 'Highlight',
+    },
+    color: {
+      default: null,
+      '@media (forced-colors: active)': 'HighlightText',
+    },
   },
 });