@12-apps/ui 6.26.0 → 6.27.0

package/src/components/form/Switch/Switch.look.native.ts

@@ -6,6 +6,7 @@ import {
   IOS_THUMB_SHADOW,
   MUI_SHADOWS,
   NEUTRAL_CONTRAST,
+  RESTING_THUMB,
   NEUTRAL_FALLBACK,
   NEUTRAL_GREY,
   SWITCH_BLACK,
@@ -23,6 +24,7 @@ import {
   type SwitchLook,
 } from './Switch.metrics';
 import { alpha } from '../../../tokens/color';
+import { inkOver } from '../../../tokens/theme';
 import type { UiTheme } from '../../../tokens/theme';
 import type { ColorValue } from '../../../tokens/vocabulary';
 
@@ -111,6 +113,31 @@ export function trackStyle(
   return base;
 }
 
+/**
+ * The ink on the CHECKED track — the thumb, and the `on` wording (FUT-1924).
+ *
+ * Both halves of the component had a stated `#fff` here, and the checked track
+ * is the one surface a tenant chooses: a pale brand got a white knob on a pale
+ * bar, which reads as OFF while it is on.
+ *
+ * **The fills are THIS renderer's, not the web's, and they differ.** The web
+ * paints a real three-stop gradient and hands `checkedInk` all three
+ * (`Switch.styles.ts`); React Native has no gradient without a dependency, so
+ * `trackStyle` shows `gradientFirstStop` — `palette.light`, FLAT — and
+ * `NATIVE-NOTES.md` records that as a known divergence. Passing the web's set
+ * here would judge the ink against two fills native never draws, and the two
+ * renderers then disagree on the same palette: measured on `#00897b`, the web
+ * answers white and this answered dark ink, because `main` and `dark` were in
+ * the list and only `light` is on screen.
+ *
+ * So the gradient case is ONE fill, which is the one it paints.
+ */
+export function checkedInk(paint: SwitchPaint, palette: SwitchPalette): string {
+  const fills = [paint.gradient ? palette.light || palette.main : palette.main];
+
+  return inkOver(fills, palette.contrastText || NEUTRAL_CONTRAST);
+}
+
 /** The web's two gradients, at the stop a flat fill can show. */
 function gradientFirstStop(palette: SwitchPalette, checked: boolean): string {
   if (checked) return palette.light || palette.main;
@@ -125,10 +152,26 @@ const disabledTrackOpacity = (state: SwitchState): number => {
 /** React Native has no `StyleSheet.absoluteFillObject` constant worth importing for four keys. */
 const StyleSheetAbsoluteFill = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 } as const;
 
-/** The knob: white, round for iOS and the default, squarer for Android and Material. */
+/** Disabled greys out; checked takes the track's ink; resting stays white. */
+function thumbFill(
+  paint: SwitchPaint,
+  palette: SwitchPalette,
+  state: SwitchState,
+  theme: UiTheme,
+): string {
+  if (state.disabled) return theme.palette.grey[DISABLED.thumbGrey] ?? RESTING_THUMB;
+  return state.checked ? checkedInk(paint, palette) : RESTING_THUMB;
+}
+
+/**
+ * The knob: round for iOS and the default, squarer for Android and Material.
+ * White while resting, the checked track's own ink once on — see
+ * {@link RESTING_THUMB} and {@link checkedInk}.
+ */
 export function thumbStyle(
   theme: UiTheme,
   paint: SwitchPaint,
+  palette: SwitchPalette,
   geometry: SwitchGeometry,
   look: SwitchLook,
   state: SwitchState,
@@ -138,7 +181,7 @@ export function thumbStyle(
     width: geometry.thumbSize,
     height: geometry.thumbSize,
     borderRadius: thumbRadius(look, geometry.thumbSize),
-    backgroundColor: state.disabled ? theme.palette.grey[DISABLED.thumbGrey] : '#fff',
+    backgroundColor: thumbFill(paint, palette, state, theme),
     boxShadow: look === 'ios' ? IOS_THUMB_SHADOW : (MUI_SHADOWS[THUMB_ELEVATION[look]] ?? 'none'),
     alignItems: 'center',
     justifyContent: 'center',

package/src/components/form/Switch/Switch.md

@@ -273,15 +273,28 @@ import Close from '@mui/icons-material/Close';
 
 ## Accessibility
 
-The Switch component follows WCAG 2.1 AA guidelines:
-
-- **Keyboard Navigation**: Supports Tab and Space key activation
-- **Focus Management**: Clear focus indicators with visible outline
-- **ARIA Attributes**: Supports aria-label, aria-describedby, role="switch"
-- **Screen Reader**: Properly announces switch state (on/off)
-- **Disabled State**: Communicates disabled state to assistive technologies
-- **Error State**: Associates error messages with the switch
-- **Helper Text**: Properly linked via aria-describedby
+- **The label names the control.** `label` renders a real `<label for>` pointing
+  at the input, so the switch announces by its visible words and clicking those
+  words toggles it. Pass `aria-label` only where there is no visible label —
+  with one, it would override the text on screen.
+- **The id is minted for you.** An explicit `id` (or `inputProps.id`) wins;
+  otherwise each instance gets its own from `useId`. Do not derive one from a
+  test id: two call sites sharing a test id would share a `for`, and the second
+  label would toggle the first control.
+- **`description` and `helperText` are described, not named.** Both are linked
+  by `aria-describedby` and stay out of the accessible name — a two-line
+  explanation read as the control's NAME is worse than no description at all. A
+  caller's own `aria-describedby` is kept alongside them, not replaced.
+- **Keyboard:** `Tab` to reach it, `Space` to toggle, with a visible focus ring.
+- **It announces as a checkbox, not as a switch.** MUI's `SwitchBase` renders an
+  `<input type="checkbox">` and this component does not override the role.
+  Earlier revisions of this document claimed `role="switch"`; that was never
+  true. Announcing as a checkbox is correct and understood — do not "fix" it by
+  hand-setting the role without also handling `aria-checked`.
+- **The tap target is the LABEL.** `SWITCH_SIZES.xl`, the largest, is 34px tall
+  against the 40px floor, so no `size` clears it. The label carries the floor
+  instead (`TAP_TARGET_MIN`), which is why an unlabelled `Switch` at a phone
+  width still wants a target around it drawn by the caller.
 
 ### Keyboard Shortcuts
 
@@ -373,6 +386,18 @@ The Switch component follows WCAG 2.1 AA guidelines:
 />
 ```
 
+## Ink on the track
+
+The thumb, the `on` wording of the `label` variant and the on-icon all take
+their colour from the palette, NOT from a stated white. The checked track is
+`palette.main` — the one surface a white-labelled host picks — so a pale brand
+gets dark ink and reads as ON, where a white knob on a pale bar reads as OFF.
+Under `gradient` the whole bar (`light → main → dark`) is considered, not just
+the colour in the middle of it.
+
+The RESTING thumb stays white by design: that track is `action.disabled` washed
+over the page, which no tenant chooses.
+
 ## Theming
 
 The Switch component integrates with MUI's theme system:

package/src/components/form/Switch/Switch.metrics.ts

@@ -168,6 +168,15 @@ export const SWITCH_HELPER = { fontSize: 12, lineHeight: 1.66, marginTopUnits: 1
 /** The label row: 16px from the control beside it, 8px above or below it. */
 export const LABEL_GAP_UNITS = { beside: 2, stacked: 1 } as const;
 
+/**
+ * The minimum height of a touch target, in px (FUT-1905).
+ *
+ * No entry in {@link SWITCH_SIZES} reaches it — `xl`, the largest, is 34px tall
+ * and `md` is 26 — so a consumer cannot buy a legal target by passing a bigger
+ * `size`. The label is what clears it: see `SwitchLabel` in `Switch.parts.tsx`.
+ */
+export const TAP_TARGET_MIN = 40;
+
 /**
  * `neutral`'s three greys, and the literals the web falls back to for a theme
  * whose grey ramp omits a step. Same three steps `Button` draws its neutral
@@ -177,6 +186,18 @@ export const NEUTRAL_GREY = { main: 700, dark: 800, light: 500 } as const;
 export const NEUTRAL_FALLBACK = { main: '#616161', dark: '#424242', light: '#9e9e9e' } as const;
 export const NEUTRAL_CONTRAST = '#fff';
 
+/**
+ * The RESTING thumb — the knob while the switch is off (FUT-1924).
+ *
+ * It stays white, and the reason is worth stating because the checked thumb no
+ * longer is: the resting track is `theme.palette.action.disabled` washed over
+ * the page, which no tenant picks, and a white knob on it is the conventional
+ * look in both modes. The CHECKED track is `palette.main`, a colour the tenant
+ * does pick, and that is where a stated white was a defect. See `checkedInk`
+ * in `Switch.styles.ts` and its native twin.
+ */
+export const RESTING_THUMB = '#fff';
+
 /** Hover: the thumb lifts a shade and takes a halo of the hue. */
 export const SWITCH_HOVER = { thumbScale: 1.05, elevation: 4, blur: 12, alpha: 0.2 } as const;
 

package/src/components/form/Switch/Switch.native.tsx

@@ -17,6 +17,7 @@ import {
   descriptionTextStyle,
   helperTextStyle,
   labelTextStyle,
+  checkedInk,
   switchPalette,
   thumbStyle,
   trackStyle,
@@ -45,9 +46,6 @@ import type { UiTheme } from '../../../tokens/theme';
 
 const nativeDriver = Platform.OS !== 'web';
 
-/** The web writes the `on` wording in white, whatever the hue behind it. */
-const TRACK_LABEL_ON_INK = '#fff';
-
 /** A 0→1 value that follows `on`, over MUI's 300ms curve unless animation is off. */
 function useProgress(on: boolean, animated: boolean): Animated.Value {
   const progress = React.useRef(new Animated.Value(on ? 1 : 0)).current;
@@ -167,7 +165,16 @@ interface ControlProps {
   testID: string;
 }
 
-/** The track, the thumb, and everything overlaid on them. */
+/**
+ * The track, the thumb, and everything overlaid on them.
+ *
+ * The control carries its own NAME (FUT-1905). React Native has no `<label
+ * for>` to wire the words beside it with, so the name has to be stated on the
+ * pressable itself or the control announces as "checkbox, checked" and nothing
+ * else — which is the defect the web half of this ticket fixed, still live
+ * here. A caller's own `aria-label` wins, because a caller that wrote one meant
+ * it to differ from the visible words.
+ */
 function SwitchControl({ props, theme, checked, inactive, onToggle, rest, testID }: ControlProps): React.JSX.Element {
   const { variant, color, size, animated, loading, onIcon, offIcon, onText, offText } = props;
   const geometry: SwitchGeometry = geometryOf(size, props.trackWidth, props.trackHeight);
@@ -184,6 +191,7 @@ function SwitchControl({ props, theme, checked, inactive, onToggle, rest, testID
     <Pressable
       testID={testID}
       role="checkbox"
+      aria-label={(rest['aria-label'] as string | undefined) ?? props.label}
       aria-checked={checked}
       aria-disabled={inactive}
       disabled={inactive}
@@ -196,7 +204,12 @@ function SwitchControl({ props, theme, checked, inactive, onToggle, rest, testID
     >
       <View style={trackStyle(theme, paint, palette, geometry, look, state)} />
       {showsTrackLabels(variant, onText, offText) ? (
-        <TrackLabels theme={theme} onText={onText} offText={offText} contrastText={TRACK_LABEL_ON_INK} />
+        <TrackLabels
+          theme={theme}
+          onText={onText}
+          offText={offText}
+          contrastText={checkedInk(paint, palette)}
+        />
       ) : null}
       {onIcon == null ? null : (
         <SwitchIcon icon={onIcon} shown={checked} animated={animated} size={iconSize} side="on" width={geometry.width} />
@@ -206,7 +219,7 @@ function SwitchControl({ props, theme, checked, inactive, onToggle, rest, testID
       )}
       <Animated.View
         style={[
-          thumbStyle(theme, paint, geometry, look, state),
+          thumbStyle(theme, paint, palette, geometry, look, state),
           { top: geometry.padding, left: restX, opacity: pulse.opacity },
           {
             transform: [

package/src/components/form/Switch/Switch.parts.tsx

@@ -2,11 +2,11 @@ import Box from '@mui/material/Box/index.js';
 import FormHelperText from '@mui/material/FormHelperText/index.js';
 import MuiSwitch from '@mui/material/Switch/index.js';
 import Typography from '@mui/material/Typography/index.js';
-import { styled } from '@mui/material/styles/index.js';
+import { styled, useTheme } from '@mui/material/styles/index.js';
 import React from 'react';
 
-import { LABEL_GAP_UNITS, SWITCH_ICON_SIZES } from './Switch.metrics';
-import { switchSx } from './Switch.styles';
+import { LABEL_GAP_UNITS, SWITCH_ICON_SIZES, TAP_TARGET_MIN } from './Switch.metrics';
+import { onTrackInk, switchSx } from './Switch.styles';
 import type { SwitchFlags } from './Switch.styles';
 import type { SwitchProps } from './Switch.types';
 import type { SizeValue } from '../../../tokens/vocabulary';
@@ -54,7 +54,7 @@ const StyledLabelContainer = styled(Box, {
  * A plain wrapper over the styled row. Exporting the styled component itself
  * needs a @mui/system reference tsc calls unportable (TS2742).
  */
-export const LabelContainer: React.FC<{
+const LabelContainer: React.FC<{
   labelPosition?: string;
   error?: boolean;
   children: React.ReactNode;
@@ -71,6 +71,8 @@ export interface SwitchIconProps {
   animated: boolean;
   size: string;
   side: 'on' | 'off';
+  /** The ink for the ON icon, which sits on the brand-filled track (FUT-1924). */
+  onInk: string;
 }
 
 /**
@@ -78,7 +80,14 @@ export interface SwitchIconProps {
  * edge when checked and the off icon to the right when unchecked; they are
  * mirror images, so they share this component rather than being written twice.
  */
-export const SwitchIcon: React.FC<SwitchIconProps> = ({ icon, shown, animated, size, side }) => {
+export const SwitchIcon: React.FC<SwitchIconProps> = ({
+  icon,
+  shown,
+  animated,
+  size,
+  side,
+  onInk,
+}) => {
   const isOn = side === 'on';
   const translate = isOn ? 'translate(-50%, -50%)' : 'translate(50%, -50%)';
 
@@ -93,7 +102,7 @@ export const SwitchIcon: React.FC<SwitchIconProps> = ({ icon, shown, animated, s
         transform: `${translate} scale(${shown && animated ? 1 : 0.8})`,
         pointerEvents: 'none',
         zIndex: 2,
-        color: isOn ? '#fff' : 'text.secondary',
+        color: isOn ? onInk : 'text.secondary',
         fontSize: SWITCH_ICON_SIZES[size as SizeValue] ?? SWITCH_ICON_SIZES.md,
       }}
     >
@@ -111,6 +120,12 @@ export interface SwitchControlProps extends SwitchFlags {
   size: string;
   dataTestId?: string;
   switchRef?: React.Ref<HTMLButtonElement>;
+  /** The id the label points at — always set, so the input always has one. */
+  inputId: string;
+  /** The caller's own `inputProps`, merged rather than spread over (FUT-1905). */
+  inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
+  /** The description's id, appended to whatever the caller described it by. */
+  describedBy?: string;
   rest: Record<string, unknown>;
 }
 
@@ -124,13 +139,15 @@ export const SwitchControl: React.FC<SwitchControlProps> = ({
   size,
   dataTestId,
   switchRef,
+  inputId,
+  inputProps,
+  describedBy,
   rest,
   ...flags
 }) => {
-  const props = rest as Record<string, unknown> & {
-    disabled?: boolean;
-    inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
-  };
+  const props = rest as Record<string, unknown> & { disabled?: boolean };
+  const theme = useTheme();
+  const onInk = onTrackInk(theme, flags);
 
   return (
     <Box sx={{ position: 'relative', display: 'inline-flex' }}>
@@ -140,15 +157,31 @@ export const SwitchControl: React.FC<SwitchControlProps> = ({
         checked={checked}
         onChange={onChange}
         disabled={Boolean(flags.loading) || props.disabled}
+        {...props}
+        /*
+          AFTER `props`, not before it (FUT-1905). `inputProps` used to be
+          written first and `{...props}` spread over it, so a caller passing
+          `inputProps` of its own silently replaced the whole object — losing
+          the `data-testid` every spec finds this control by, and the `id` the
+          label points at.
+
+          The order inside is the contract. Everything the component DEFAULTS
+          goes first, so a caller's own key still wins — that is what it could
+          do before, and a fix for a clobber must not become a clobber the
+          other way. Only the two the component OWNS come last: the `id`, which
+          already resolved the caller's spelling of it (`switchIds`), and
+          `aria-describedby`, which by then already CONTAINS whatever the
+          caller passed, in either spelling.
+        */
         inputProps={
           {
             'aria-label': props['aria-label'],
-            'aria-describedby': props['aria-describedby'],
-            ...props.inputProps,
             'data-testid': dataTestId || 'switch',
+            ...inputProps,
+            id: inputId,
+            'aria-describedby': describedBy,
           } as React.InputHTMLAttributes<HTMLInputElement>
         }
-        {...props}
       />
 
       {onIcon && (
@@ -158,6 +191,7 @@ export const SwitchControl: React.FC<SwitchControlProps> = ({
           animated={animated}
           size={size}
           side="on"
+          onInk={onInk}
         />
       )}
       {offIcon && (
@@ -167,19 +201,30 @@ export const SwitchControl: React.FC<SwitchControlProps> = ({
           animated={animated}
           size={size}
           side="off"
+          onInk={onInk}
         />
       )}
     </Box>
   );
 };
 
+/**
+ * The helper line, which is where a validation message lands — so it is
+ * `aria-describedby`'d like the description (FUT-1905).
+ *
+ * It carried no `id` and nothing pointed at it, which means an `error` state
+ * announced as "checkbox, checked" and nothing else: the one sentence saying
+ * WHY was on screen and outside the accessibility tree.
+ */
 export const SwitchHelper: React.FC<{
   helperText?: React.ReactNode;
   error?: boolean;
   dataTestId?: string;
-}> = ({ helperText, error, dataTestId }) =>
+  id?: string;
+}> = ({ helperText, error, dataTestId, id }) =>
   helperText ? (
     <FormHelperText
+      id={id}
       error={error}
       sx={{ mt: 1 }}
       data-testid={dataTestId ? `${dataTestId}-helper` : 'switch-helper'}
@@ -188,23 +233,62 @@ export const SwitchHelper: React.FC<{
     </FormHelperText>
   ) : null;
 
-export const SwitchLabel: React.FC<{
+/**
+ * The label, WIRED to the input it names (FUT-1905).
+ *
+ * It used to be a `<p>` rendered as the control's sibling, with no `for`, no
+ * `id` on the input and no `aria-labelledby` — so a labelled `Switch` announced
+ * as "checkbox, checked" with no name, and clicking the words did nothing. Every
+ * `Switch` in a consumer app was affected, not one call site, and the workaround
+ * each had to write was a hand-typed `aria-label` duplicating the text already
+ * on screen.
+ *
+ * A real `<label for>` fixes the name and the pointer in the same stroke, and it
+ * is also the answer to the TAP TARGET: no size in `SWITCH_SIZES` clears the
+ * 40px floor (`xl` is 34px tall), so the control cannot be made big enough by
+ * passing a bigger `size` — instead the label becomes the target, which is how
+ * this is normally solved. Hence `display: flex` and `TAP_TARGET_MIN`: the
+ * label fills its half of the row and is never shorter than the floor.
+ *
+ * The DESCRIPTION stays outside the label and is pointed at by
+ * `aria-describedby` instead: inside it, a two-line explanation would be read
+ * out as part of the control's name.
+ */
+const SwitchLabel: React.FC<{
   label: React.ReactNode;
   description?: React.ReactNode;
   error?: boolean;
   dataTestId?: string;
-}> = ({ label, description, error, dataTestId }) => (
-  <Box sx={{ flex: 1 }}>
+  /** The input's id. Omitted only where there is no input to point at. */
+  htmlFor?: string;
+  descriptionId?: string;
+  disabled?: boolean;
+}> = ({ label, description, error, dataTestId, htmlFor, descriptionId, disabled }) => (
+  <Box sx={{ flex: 1, minWidth: 0 }}>
     <Typography
+      component="label"
+      htmlFor={htmlFor}
       variant="body2"
       fontWeight={500}
       color={error ? 'error.main' : 'text.primary'}
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        // The floor applies to the row the label shares with the control. A
+        // description already makes the row taller than 40px, so forcing it
+        // there would only add blank space.
+        ...(description ? {} : { minHeight: TAP_TARGET_MIN }),
+        // A disabled control's label toggles nothing, so it must not wear the
+        // cursor that says it does.
+        ...(htmlFor && !disabled ? { cursor: 'pointer' } : {}),
+      }}
       data-testid={dataTestId ? `${dataTestId}-label` : 'switch-label'}
     >
       {label}
     </Typography>
     {description && (
       <Typography
+        id={descriptionId}
         variant="caption"
         color={error ? 'error.main' : 'text.secondary'}
         sx={{ display: 'block', mt: 0.5 }}
@@ -214,3 +298,52 @@ export const SwitchLabel: React.FC<{
     )}
   </Box>
 );
+
+/**
+ * The control and its label in one row, or the control alone.
+ *
+ * Lives here rather than inline in `Switch.tsx` because the two branches only
+ * differ in what surrounds the control — and the component that assembles them
+ * was long enough that the wiring got hard to see between them.
+ */
+export const SwitchRow: React.FC<{
+  label?: React.ReactNode;
+  description?: React.ReactNode;
+  labelPosition?: string;
+  error?: boolean;
+  dataTestId?: string;
+  htmlFor: string;
+  descriptionId?: string;
+  disabled?: boolean;
+  control: React.ReactNode;
+}> = ({
+  label,
+  description,
+  labelPosition,
+  error,
+  dataTestId,
+  htmlFor,
+  descriptionId,
+  disabled,
+  control,
+}) => {
+  if (!label) return <>{control}</>;
+
+  return (
+    <LabelContainer labelPosition={labelPosition} error={error}>
+      {labelPosition === 'start' && control}
+
+      <SwitchLabel
+        label={label}
+        description={description}
+        error={error}
+        dataTestId={dataTestId}
+        htmlFor={htmlFor}
+        descriptionId={descriptionId}
+        disabled={disabled}
+      />
+
+      {labelPosition !== 'start' && control}
+    </LabelContainer>
+  );
+};

package/src/components/form/Switch/Switch.styles.ts

@@ -26,6 +26,7 @@ import {
   SWITCH_RIPPLE,
   SWITCH_SPINNER,
   SWITCH_TRANSITION,
+  RESTING_THUMB,
   THUMB_ELEVATION,
   THUMB_RADIUS,
   TRACK_LABEL,
@@ -41,7 +42,7 @@ import {
 } from './Switch.metrics';
 import type { SwitchVariant } from './Switch.base';
 
-import { px } from '../../../tokens/theme';
+import { inkOver, px } from '../../../tokens/theme';
 import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
 
 // Every number below comes from `./Switch.metrics`, which the native renderer
@@ -125,6 +126,32 @@ const rippleOverlay = (palette: ColorPalette): CSSObject => ({
   pointerEvents: 'none',
 });
 
+/**
+ * The ink on the CHECKED track — the thumb, the `on` wording and any on-icon
+ * (FUT-1924).
+ *
+ * All three stated `#fff`, and the checked track is `palette.main`: the one
+ * surface in this component the TENANT picks. A store with a pale brand got a
+ * white thumb on a pale green bar, which does not read as a knob at all — the
+ * switch looks OFF while it is on, so this is a state a user misreads rather
+ * than a colour they dislike.
+ *
+ * The `gradient` flag paints the track `light → main → dark`, so the fills the
+ * thumb travels over are handed over together and {@link inkOver} takes the
+ * worst of them.
+ *
+ * The RESTING track is not here on purpose: it is `theme.palette.action.disabled`
+ * washed over the page, which no tenant chooses, and a white thumb on it is the
+ * conventional look in both modes.
+ */
+const checkedInk = (flags: SwitchFlags, palette: ColorPalette): string => {
+  const fills = flags.gradient
+    ? [palette.light || palette.main, palette.main, palette.dark || palette.main]
+    : [palette.main];
+
+  return inkOver(fills, palette.contrastText || NEUTRAL_CONTRAST);
+};
+
 /** The checked track: the filled bar behind the thumb once the switch is on. */
 const checkedTrack = (flags: SwitchFlags, palette: ColorPalette): CSSObject => ({
   backgroundColor: palette.main,
@@ -170,9 +197,12 @@ const switchBaseSx = (
       // The thumb travels the track minus its own width and both paddings; the
       // iOS look insets differently, so it gets its own distance.
       transform: `translateX(${width - thumbSize - padding * 2}px)`,
-      color: '#fff',
+      color: checkedInk(flags, palette),
       '& .MuiSwitch-thumb': {
         animation: flags.loading ? 'none' : `${bounceAnimation} ${seconds(SWITCH_TRANSITION.ms)} ease-out`,
+        // `glass` draws its own translucent thumb and means to show the track
+        // through it, so it keeps the fill it chose.
+        ...(flags.glass ? {} : { backgroundColor: checkedInk(flags, palette) }),
       },
       '& + .MuiSwitch-track': checkedTrack(flags, palette),
       '&.Mui-disabled + .MuiSwitch-track': { opacity: DISABLED.checkedTrackOpacity },
@@ -197,7 +227,9 @@ const thumbSx = (
   width: thumbSize,
   height: thumbSize,
   borderRadius: THUMB_RADIUS[look](thumbSize),
-  backgroundColor: '#fff',
+  // `.Mui-checked` above replaces this for the brand-filled track; see
+  // {@link RESTING_THUMB} for why the resting one stays white.
+  backgroundColor: RESTING_THUMB,
   boxShadow: thumbShadow(theme, look),
   transition: `all ${seconds(SWITCH_TRANSITION.ms)} ${SWITCH_TRANSITION.easing}`,
   position: 'relative',
@@ -239,7 +271,13 @@ const thumbSx = (
 });
 
 /** The on/off wording the `label` variant prints inside the track. */
-const trackLabels = (theme: Theme, onText?: string, offText?: string): CSSObject => ({
+const trackLabels = (
+  theme: Theme,
+  flags: SwitchFlags,
+  palette: ColorPalette,
+  onText?: string,
+  offText?: string,
+): CSSObject => ({
   display: 'flex',
   alignItems: 'center',
   justifyContent: 'space-between',
@@ -258,7 +296,13 @@ const trackLabels = (theme: Theme, onText?: string, offText?: string): CSSObject
     zIndex: 1,
   },
   ...(onText && {
-    '&::before': { content: `"${onText}"`, left: theme.spacing(TRACK_LABEL.insetUnits), color: '#fff' },
+    '&::before': {
+      content: `"${onText}"`,
+      left: theme.spacing(TRACK_LABEL.insetUnits),
+      // The `on` word sits at the end the thumb travels TO, which is the
+      // filled half of the track once checked.
+      color: checkedInk(flags, palette),
+    },
   }),
   ...(offText && {
     '&::after': {
@@ -297,10 +341,19 @@ const trackSx = (
       !glass && {
         background: `linear-gradient(${SWITCH_GRADIENT.resting.angleDeg}deg, ${alpha(palette.light || palette.main, SWITCH_GRADIENT.resting.lightAlpha)}, ${alpha(palette.main, SWITCH_GRADIENT.resting.mainAlpha)})`,
       }),
-    ...(showsTrackLabels(customVariant, onText, offText) && trackLabels(theme, onText, offText)),
+    ...(showsTrackLabels(customVariant, onText, offText) &&
+      trackLabels(theme, flags, palette, onText, offText)),
   };
 };
 
+/**
+ * The same checked-track ink, for the two ICONS the control overlays on the
+ * track — which are drawn as components rather than styles, so they cannot
+ * reach {@link checkedInk} directly.
+ */
+export const onTrackInk = (theme: Theme, flags: SwitchFlags): string =>
+  checkedInk(flags, getColorFromTheme(theme, flags.customColor ?? 'primary'));
+
 export const switchSx = (theme: Theme, flags: SwitchFlags): CSSObject => {
   const palette = getColorFromTheme(theme, flags.customColor ?? 'primary');
   const geometry = geometryOf(flags.customSize, flags.trackWidth, flags.trackHeight);