@multiplatform.one/theme 7.69.2 → 7.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.69.2",
+  "version": "7.71.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -72,8 +72,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@multiplatform.one/platform": "^7.69.2",
-    "@multiplatform.one/store": "^7.69.2",
+    "@multiplatform.one/platform": "^7.71.0",
+    "@multiplatform.one/store": "^7.71.0",
     "@tamagui/animations-react-native": "2.7.6",
     "@tamagui/colors": "2.7.6",
     "@tamagui/config": "2.7.6",
@@ -89,8 +89,8 @@
   },
   "devDependencies": {
     "@expo/prebuild-config": "55.0.18",
-    "@multiplatform.one/config": "7.69.2",
-    "@multiplatform.one/test-utils": "7.69.2",
+    "@multiplatform.one/config": "7.71.0",
+    "@multiplatform.one/test-utils": "7.71.0",
     "@tamagui/animations-css": "2.7.6",
     "@tamagui/animations-reanimated": "2.7.6",
     "@tamagui/font-inter": "2.7.6",

package/src/audit/constraintAudit.ts

@@ -211,6 +211,7 @@ const VALID_FONT_WEIGHT = new Set(Object.values(FONT_WEIGHT_KNOB));
 const FONT_FAMILY_KNOB: Record<string, string> = {
   inter: "sans-serif ($body/$heading)",
   georgia: "serif",
+  "ibm plex mono": "mono",
   "ui-monospace": "mono",
   monospace: "mono",
   "roboto slab": "slab",
@@ -429,6 +430,7 @@ export function runConstraintAudit(rootSelector?: string): AuditReport {
   const _FONT_FAMILY_KNOB: Record<string, string> = {
     inter: "sans-serif ($body/$heading)",
     georgia: "serif",
+    "ibm plex mono": "mono",
     "ui-monospace": "mono",
     monospace: "mono",
     "roboto slab": "slab",

package/src/expo.spec.ts

@@ -65,8 +65,8 @@ describe("Expo theme colors", () => {
 
   it("rejects an unknown preset or missing scheme instead of baking in a fallback", () => {
     expect(() => createExpoThemeColors({ preset: "typo" })).toThrow(/preset.*typo/i);
-    expect(() => createExpoThemeColors({ themes: { light: { background: "#fff" } } })).toThrow(
-      /dark.*background/i,
+    expect(() => createExpoThemeColors({ themes: { light_blue: { background: "#fff" } } })).toThrow(
+      /dark_blue.*background/i,
     );
   });
 
@@ -75,9 +75,9 @@ describe("Expo theme colors", () => {
     (background) => {
       expect(() =>
         createExpoThemeColors({
-          themes: { light: { background }, dark: { background: "#000" } },
+          themes: { light_blue: { background }, dark_blue: { background: "#000" } },
         }),
-      ).toThrow(/light.*background/i);
+      ).toThrow(/light_blue.*background/i);
     },
   );
 });

package/src/expo.ts

@@ -3,7 +3,15 @@ import { createThemesBuilder } from "./theme/createThemes";
 import { defaultAccentTheme } from "./theme/defaults/accent";
 import { defaultBaseTheme } from "./theme/defaults/base";
 import { defaultBuilderOptions } from "./theme/defaults/builderOptions";
-import { boldPreset, defaultPreset, densePreset, heroPreset, roomyPreset } from "./theme/presets";
+import {
+  boldPreset,
+  consolePreset,
+  defaultPreset,
+  densePreset,
+  heroPreset,
+  roomyPreset,
+  storefrontPreset,
+} from "./theme/presets";
 
 export { createThemesBuilder, defaultBaseTheme, defaultAccentTheme, defaultBuilderOptions };
 
@@ -20,6 +28,8 @@ const builtinPresets = {
   dense: densePreset,
   hero: heroPreset,
   roomy: roomyPreset,
+  console: consolePreset,
+  storefront: storefrontPreset,
 };
 
 export function createExpoThemeColors({

package/src/theme/colorRules.ts

@@ -72,6 +72,93 @@ export function contrastRatio(l1: number, l2: number): number {
   return (lighter + 0.05) / (darker + 0.05);
 }
 
+function apcaY(hex: string): number {
+  const [r, g, b] = [1, 3, 5].map((offset) => parseChannel(hex, offset));
+  const y = 0.2126729 * r ** 2.4 + 0.7151522 * g ** 2.4 + 0.072175 * b ** 2.4;
+  return y < 0.022 ? y + (0.022 - y) ** 1.414 : y;
+}
+
+/**
+ * APCA lightness contrast (SAPC 0.0.98G-4g) of `text` on `background`, as
+ * signed Lc: positive for dark text on a light fill, negative for light on
+ * dark. Callers compare the magnitude.
+ */
+export function apcaContrast(text: string, background: string): number {
+  const textHex = normalizeToHex(text);
+  const backgroundHex = normalizeToHex(background);
+  if (!textHex || !backgroundHex) return 0;
+  const yText = apcaY(textHex);
+  const yBackground = apcaY(backgroundHex);
+  if (Math.abs(yBackground - yText) < 0.0005) return 0;
+  if (yBackground > yText) {
+    const sapc = (yBackground ** 0.56 - yText ** 0.57) * 1.14;
+    return sapc < 0.1 ? 0 : (sapc - 0.027) * 100;
+  }
+  const sapc = (yBackground ** 0.65 - yText ** 0.62) * 1.14;
+  return sapc > -0.1 ? 0 : (sapc + 0.027) * 100;
+}
+
+/** APCA |Lc| a label on a filled control must reach (LC-172). */
+export const fillLabelLc = 60;
+
+/**
+ * LC-172 / Apple HIG: the off Switch track is a system fill, rgb(120,120,128)
+ * laid over the ground at 0.16 alpha on a light ground and 0.32 on a dark one
+ * (what UISwitch paints). A ramp step may land anywhere from tertiary to
+ * systemFill on either side of that, the band below.
+ */
+export const switchOffFillAlpha = { light: 0.16, dark: 0.32 } as const;
+export const switchOffFillBand = { light: [0.08, 0.24], dark: [0.18, 0.4] } as const;
+
+/** A ground is light when its relative luminance is past the midpoint. */
+export function isLightGround(ground: string): boolean {
+  const hex = normalizeToHex(ground);
+  return hex !== null && relativeLuminance(hex) > 0.5;
+}
+
+/** HIG's system fill at `alpha` composited over `ground`, as an opaque hex colour. */
+export function systemFillHex(ground: string, alpha: number): string | null {
+  const hex = normalizeToHex(ground);
+  if (!hex) return null;
+  const mixed = [120, 120, 128]
+    .map((fill, index) => {
+      const under = Number.parseInt(hex.slice(1 + index * 2, 3 + index * 2), 16);
+      return Math.round(fill * alpha + under * (1 - alpha))
+        .toString(16)
+        .padStart(2, "0");
+    })
+    .join("");
+  return `#${mixed}`;
+}
+
+/** HIG's system fill at `alpha` composited over `ground`, as relative luminance. */
+export function systemFillLuminance(ground: string, alpha: number): number | null {
+  const hex = systemFillHex(ground, alpha);
+  return hex ? relativeLuminance(hex) : null;
+}
+
+/**
+ * FZ-7944: a control's plate stays this far off the raised ground an overlay
+ * paints ($color4 in dark), so it never dissolves into a sheet or card.
+ */
+export const plateContrastRatio = 1.1;
+
+/**
+ * Whether `track` sits in the HIG system-fill band over `ground`: never
+ * darker than systemFill on a light ground (a dark off track reads as on),
+ * and on a dark ground lifted off it without passing systemFill.
+ */
+export function inSwitchOffBand(track: string, ground: string): boolean {
+  const hex = normalizeToHex(track);
+  if (!hex) return false;
+  const [low, high] = switchOffFillBand[isLightGround(ground) ? "light" : "dark"];
+  const a = systemFillLuminance(ground, low);
+  const b = systemFillLuminance(ground, high);
+  if (a === null || b === null) return false;
+  const lum = relativeLuminance(hex);
+  return lum >= Math.min(a, b) && lum <= Math.max(a, b);
+}
+
 export const minContrastRatio = 3;
 
 /** WCAG AA contrast floor for normal-size body/label text. */

package/src/theme/createDefaultThemeConfig.spec.ts

@@ -37,6 +37,7 @@ import { boldPreset, densePreset, heroPreset, roomyPreset } from "./presets";
 import { createThemesBuilder, type GetThemeProps } from "./createThemes";
 import { defaultBaseTheme, defaultAccentTheme } from "./defaults";
 import { setSizeRecipeInputs } from "./sizeRecipes";
+import { resolveThemeThroughParents } from "./dedupeInherited";
 
 // Mirrors the shc app theme config: a consumer getTheme written against the
 // FULL base ramp (theme.colorN) with no outlineColor of its own. Inside
@@ -398,8 +399,9 @@ describe("the v5 theme matrix", () => {
     for (const scheme of ["light", "dark"] as const) {
       expect(themes[`${scheme}_gray`].color3).toBe(stockThemes[`${scheme}_gray`].color3);
       for (const suffix of ["active", "alt1", "alt2"]) {
-        const child = themes[`${scheme}_gray_${suffix}`];
-        expect(child).toBeDefined();
+        expect(themes[`${scheme}_gray_${suffix}`]).toBeDefined();
+        // The shipped record is deduped (LC-160); a child reads through its parents.
+        const child = resolveThemeThroughParents(themes, `${scheme}_gray_${suffix}`);
         for (const key of ["color", "background", "borderColor"]) {
           expect(child[key]).toMatch(/, 1\)$/);
         }
@@ -448,10 +450,12 @@ describe("the v5 theme matrix", () => {
 
   // FZ-7715 added one accent solid per hue and scheme (16 themes) so
   // `theme="accent"` follows a picked colour; the budget moved 260 -> 280 KB.
-  it("ships 478 themes and the heading-scope category fonts in under 282 KB of CSS (the v4 matrix and stock spread shipped 913 KB)", async () => {
+  // FZ-7970 (LC-160) dedupes values another rule already puts on the element:
+  // 280,833 -> 263,241 bytes, and the budget ratchets down to 264 KB.
+  it("ships 478 themes and the heading-scope category fonts in under 264 KB of CSS (the v4 matrix and stock spread shipped 913 KB)", async () => {
     const { createTamagui: build } = await vi.importActual<typeof import("tamagui")>("tamagui");
     const css = build(config.tamagui).getCSS();
     expect(Object.keys(themes)).toHaveLength(478);
-    expect(Buffer.byteLength(css, "utf8")).toBeLessThan(282_000);
+    expect(Buffer.byteLength(css, "utf8")).toBeLessThan(264_000);
   });
 });

package/src/theme/createDefaultThemeConfig.ts

@@ -22,6 +22,7 @@ import { type ThemeConfig, createThemeConfig } from "./shared";
 import { assertResolvableThemeValues } from "./themeValue";
 import { getGeneratedSizeRecipes, getSizeRecipeInputs, setSizeRecipeInputs } from "./sizeRecipes";
 import { type ThemeSubset, subsetThemes } from "./subsetThemes";
+import { dedupeInheritedThemeValues } from "./dedupeInherited";
 
 /**
  * The Tamagui era this theme config resolves against (MPO-19 X13; rendered
@@ -57,8 +58,12 @@ export interface CreateDefaultThemeConfigOptions {
   builderOptions?: CreateThemesBuilderOptions;
   /** Override tamagui settings */
   settings?: Partial<NonNullable<CreateTamaguiProps["settings"]>>;
-  /** Override any top-level tamagui config property */
-  tamagui?: Partial<CreateTamaguiProps>;
+  /**
+   * Override any top-level tamagui config property except `themes` (LC-160:
+   * an app adds tokens through `builderOptions`, `additionalThemes` and
+   * presets, never prebuilt themes).
+   */
+  tamagui?: Partial<Omit<CreateTamaguiProps, "themes">>;
   /** Named theme presets for the preset system */
   presets?: Record<string, Preset>;
   /** Default preset name to use when no `mp.preset` cookie is set */
@@ -111,6 +116,23 @@ function composeGetTheme(
   };
 }
 
+/**
+ * LC-160 ONE-THEME-ENGINE. Every theme an app paints comes out of this
+ * builder, so the holds (accent floor, selected state, named ink, hairline)
+ * reach it. A prebuilt `tamagui.themes` skips all of them, which is how the
+ * SHC console drifted onto its own matrix.
+ */
+export function assertNoPrebuiltThemes(options: CreateDefaultThemeConfigOptions): void {
+  const tamagui = options.tamagui as { themes?: unknown } | undefined;
+  if (tamagui && "themes" in tamagui && tamagui.themes !== undefined) {
+    throw new Error(
+      "createDefaultThemeConfig: `tamagui.themes` is not accepted (LC-160 ONE-THEME-ENGINE). " +
+        "Add tokens through `builderOptions.getTheme`, palettes through `additionalThemes`, " +
+        "looks through `presets`, and narrow the matrix with `subset`.",
+    );
+  }
+}
+
 /**
  * Builds Tamagui's v5 grey ramp, inverted-base accent and colour themes,
  * with the house accessibility floors. Fonts include Inter heading/body
@@ -124,6 +146,7 @@ function composeGetTheme(
 export function createDefaultThemeConfig(
   options: CreateDefaultThemeConfigOptions = {},
 ): ThemeConfig {
+  assertNoPrebuiltThemes(options);
   setSizeRecipeInputs(options.recipeInputs ?? {});
   const scale = generateScale(defaultScaleInputs);
   const base = options.base ?? defaultBaseTheme;
@@ -146,7 +169,8 @@ export function createDefaultThemeConfig(
   // theming. This optimization breaks builds served outside Tamagui's SSR
   // pipeline (e.g. the Frappe SPA) where runtime JS themes are required.
   // Always keep themes to ensure TamaguiProvider has valid theme data.
-  const themes = options.subset ? subsetThemes(builtThemes, options.subset) : builtThemes;
+  const reachable = options.subset ? subsetThemes(builtThemes, options.subset) : builtThemes;
+  const themes = dedupeInheritedThemeValues(reachable);
   const fonts = withDerivedHeadingCategories({
     ...defaultConfig.fonts,
     ...defaultFonts,

package/src/theme/createThemes.ts

@@ -6,12 +6,20 @@ import {
 import { defaultChildrenThemes, v5Templates } from "@tamagui/themes/v5";
 import {
   aaTextContrastRatio,
+  apcaContrast,
   contrastRatio,
+  fillLabelLc,
   holdInkFloor,
+  inSwitchOffBand,
+  isLightGround,
   minContrastRatio,
   normalizeToHex,
   pickReadableForeground,
+  plateContrastRatio,
   relativeLuminance,
+  switchOffFillAlpha,
+  systemFillHex,
+  systemFillLuminance,
 } from "./colorRules";
 import { pickSecondaryInk } from "./defaults/builderOptions";
 import { themeRampHues } from "./ramps";
@@ -350,6 +358,54 @@ function holdAccentFloor(
   return out;
 }
 
+/**
+ * LC-05 ONE-EMPHASIS. A selected list or sidebar row paints the scope's
+ * `$color4`, and it must separate from the page it sits on. Radix's light
+ * blue, green, purple and yellow step 4 measure 1.10 to 1.14:1 on their own
+ * step 2 page, under LC-05's 1.15 floor, so the house blue preset's selected
+ * row did not read as selected. Walk each scope's step 4 toward step 5, then
+ * step 6, in twentieths until it clears the floor, and repaint every child
+ * theme that carries the same step 4. A scope that already holds stays.
+ * A `$borderColor` on that step moves with it, or it falls off the ramp and
+ * LC-148's hairline is no longer one step fainter (hairlineToken.spec).
+ */
+const selectionSurfaceContrastRatio = 1.16;
+const selectionSurfaceScope = /^(light|dark)(_[a-z]+)?$/;
+
+function holdSelectionSurface(
+  themes: Record<string, Record<string, string>>,
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = { ...themes };
+  for (const [scopeName, scope] of Object.entries(themes)) {
+    if (!selectionSurfaceScope.test(scopeName) || /_(accent|active)$/.test(scopeName)) continue;
+    const page = luminanceOf(scope.background);
+    const [surface, next, last] = [scope.color4, scope.color5, scope.color6].map((color) =>
+      color ? normalizeToHex(color) : null,
+    );
+    if (page === null || !surface || !next || !last) continue;
+    if (contrastRatio(relativeLuminance(surface), page) >= selectionSurfaceContrastRatio) continue;
+    const candidates = [
+      ...Array.from({ length: 20 }, (_, index) => mixHex(surface, next, (index + 1) / 20)),
+      ...Array.from({ length: 20 }, (_, index) => mixHex(next, last, (index + 1) / 20)),
+    ];
+    const held = candidates.find(
+      (candidate) =>
+        contrastRatio(relativeLuminance(candidate), page) >= selectionSurfaceContrastRatio,
+    );
+    if (!held) continue;
+    for (const [name, theme] of Object.entries(themes)) {
+      if (name !== scopeName && !name.startsWith(`${scopeName}_`)) continue;
+      if (theme.color4 !== scope.color4) continue;
+      out[name] = {
+        ...out[name],
+        color4: held,
+        ...(theme.borderColor === scope.color4 ? { borderColor: held } : null),
+      };
+    }
+  }
+  return out;
+}
+
 /**
  * LC-131 SELECTED-STATE. A selected choice part paints a soft accent tint with
  * accent ink. The tint is the accent step nearest the scheme's neutral
@@ -432,18 +488,40 @@ function selectedPaint(
 }
 
 /**
- * FZ-7158 WP-b2 / DF-06. The off Switch track is the first grey step that
- * holds 3:1 under the white thumb and 1.5:1 from the accent on track, and
- * 3:1 on the page and surface1 when a step can hold all four. Dark's accent
- * fill sits between gray9 and gray10, so dark falls back to gray7 and the
- * thumb carries the page contrast. Hover is one step toward the page, press
- * one step away. Runs after holdAccentFloor, which settles the on track.
- * Only the scheme roots carry the keys and every child inherits them: one
- * copy per theme overruns the CSS budget in createDefaultThemeConfig.spec.ts.
+ * LC-172 FILL-CONTRAST / Apple HIG. The off Switch track is a light system
+ * fill, never a dark grey that reads as on beside the accent on track: the
+ * grey ramp step nearest HIG's rgba(120,120,128) over the page, 0.16 alpha in
+ * light and 0.32 in dark, inside the system-fill band (`inSwitchOffBand`).
+ * Among in-band steps the nearest that stays 1.5:1 apart from the on track
+ * wins. In dark a Switch also sits on raised cells, sheets and cards
+ * ($color4), where FZ-7944 holds its plate 1.1:1 off that ground; no grey
+ * step clears it on every hue's raised ground, so dark also weighs HIG's
+ * system fill composited over the raised ground, as UISwitch paints it on a
+ * grouped cell. The white thumb carries its own edge with `thumbShadow`, as UISwitch's
+ * does. Hover is one step toward the page, press one step away. Runs after
+ * holdAccentFloor, which settles the on track. Only the scheme roots carry the
+ * keys and every child inherits them: one copy per theme overruns the CSS
+ * budget in createDefaultThemeConfig.spec.ts.
  */
-const switchOffSteps = [10, 9, 8, 7, 6, 5] as const;
 const switchStateContrastRatio = 1.5;
 
+const switchRaisedAlphas = [0.16, 0.2, 0.24, 0.28, 0.32, 0.36, 0.4];
+const switchRaisedAlphaStep = 0.04;
+
+/** Dark's raised ground under a Switch: `$color4`, the elevated surface knob (FZ-7944). */
+function raisedGrounds(
+  themes: Record<string, Record<string, string>>,
+  scheme: "light" | "dark",
+): string[] {
+  if (scheme === "light") return [];
+  const hues = Object.entries(themes)
+    .filter(([name]) => new RegExp(`^${scheme}_[a-z]+$`).test(name))
+    .filter(([name]) => !/_(accent|active)$/.test(name));
+  return [themes[scheme]?.color4, ...hues.map(([, theme]) => theme.color4)].filter(
+    (color): color is string => typeof color === "string",
+  );
+}
+
 function holdSwitchTrack(
   themes: Record<string, Record<string, string>>,
 ): Record<string, Record<string, string>> {
@@ -451,42 +529,81 @@ function holdSwitchTrack(
   for (const scheme of ["light", "dark"] as const) {
     const base = themes[scheme];
     if (!base) continue;
-    const paint = switchTrackPaint(base, base.accentBackground, [base.background, base.color3]);
+    const paint = switchTrackPaint(
+      base,
+      base.accentBackground,
+      base.background,
+      raisedGrounds(themes, scheme),
+    );
     if (paint) out[scheme] = { ...base, ...paint };
   }
   return out;
 }
 
+interface SwitchTrackCandidate {
+  color: string;
+  lum: number;
+  hover: string;
+  press: string;
+}
+
 /**
- * The off track for one on-fill: the first grey step in `steps` that holds
- * under the thumb and apart from `onFill`, on the page too when one can.
- * Hover is one step toward the page and press one away, clamped to the ramp.
+ * The off track for one on-fill over `ground`: the in-band candidate nearest
+ * HIG's system fill that holds 1.5:1 from `onFill`, else the nearest in-band
+ * one, else the nearest grey step outright when the ramp skips the band.
+ * Candidates are the grey steps and, over `raised[0]`, the system fill at each
+ * alpha; with `raised` grounds every in-band candidate must also hold the
+ * plate floor on each of them.
  */
 function switchTrackPaint(
   base: Record<string, string>,
   onFill: string | undefined,
-  pageSurfaces: (string | undefined)[],
-  steps: readonly number[] = switchOffSteps,
+  ground: string | undefined,
+  raised: string[] = [],
 ): Record<string, string> | undefined {
-  const thumb = luminanceOf(base.switchThumb ?? "#ffffff");
   const on = luminanceOf(onFill);
-  const surfaces = pageSurfaces.map(luminanceOf);
-  if (thumb === null || on === null || surfaces.some((lum) => lum === null)) return undefined;
-  const holds = (step: number, onPage: boolean) => {
-    const lum = luminanceOf(base[`gray${step}`]);
-    return (
-      lum !== null &&
-      contrastRatio(lum, thumb) >= minContrastRatio &&
-      contrastRatio(lum, on) >= switchStateContrastRatio &&
-      (!onPage || surfaces.every((surface) => contrastRatio(lum, surface!) >= minContrastRatio))
-    );
-  };
-  const off = steps.find((step) => holds(step, true)) ?? steps.find((step) => holds(step, false));
-  if (off === undefined) return undefined;
+  if (!ground || on === null) return undefined;
+  const alpha = switchOffFillAlpha[isLightGround(ground) ? "light" : "dark"];
+  const target = systemFillLuminance(ground, alpha);
+  if (target === null) return undefined;
+  const raisedLums = raised
+    .map((color) => luminanceOf(color))
+    .filter((lum): lum is number => lum !== null);
+  const greys: SwitchTrackCandidate[] = Array.from({ length: 12 }, (_, index) => index + 1)
+    .map((step) => ({
+      color: base[`gray${step}`],
+      lum: luminanceOf(base[`gray${step}`]),
+      hover: base[`gray${Math.max(step - 1, 1)}`],
+      press: base[`gray${Math.min(step + 1, 12)}`],
+    }))
+    .filter((entry): entry is SwitchTrackCandidate => entry.lum !== null);
+  const fills: SwitchTrackCandidate[] = raised[0]
+    ? switchRaisedAlphas.flatMap((fillAlpha) => {
+        const color = systemFillHex(raised[0], fillAlpha);
+        const hover = systemFillHex(raised[0], fillAlpha - switchRaisedAlphaStep);
+        const press = systemFillHex(raised[0], fillAlpha + switchRaisedAlphaStep);
+        const lum = luminanceOf(color ?? undefined);
+        return color && hover && press && lum !== null ? [{ color, lum, hover, press }] : [];
+      })
+    : [];
+  const byTarget = (a: SwitchTrackCandidate, b: SwitchTrackCandidate) =>
+    Math.abs(a.lum - target) - Math.abs(b.lum - target);
+  const steps = [...greys].sort(byTarget);
+  const inBand = [...greys, ...fills]
+    .filter((entry) => inSwitchOffBand(entry.color, ground))
+    .filter((entry) =>
+      raisedLums.every((lum) => contrastRatio(entry.lum, lum) >= plateContrastRatio),
+    )
+    .sort(byTarget);
+  const pick =
+    inBand.find((entry) => contrastRatio(entry.lum, on) >= switchStateContrastRatio) ??
+    inBand[0] ??
+    steps[0];
+  if (!pick) return undefined;
   return {
-    switchTrackOff: base[`gray${off}`],
-    switchTrackOffHover: base[`gray${off - 1}`],
-    switchTrackOffPress: base[`gray${Math.min(off + 1, 12)}`],
+    switchTrackOff: pick.color,
+    switchTrackOffHover: pick.hover,
+    switchTrackOffPress: pick.press,
   };
 }
 
@@ -595,6 +712,49 @@ function walkToHoldingInk(
   return null;
 }
 
+/**
+ * LC-172 FILL-CONTRAST. The step of a hue's ramp its accent solid fills with,
+ * and the label on it: the step nearest in luminance to `preferred` where a
+ * label clears both WCAG AA 4.5 and APCA Lc 60, held 3:1 on the page. `labels`
+ * runs lightest first, so a step both labels clear takes the white one.
+ * WCAG alone put a near-black label on the step-9 blue, red, green, orange and
+ * pink (APCA Lc 37-48): the "grey box with black letters" Clay rated down.
+ */
+function holdFillLabel(
+  preferred: string,
+  steps: (string | undefined)[],
+  labels: string[],
+  paper: number,
+): { fill: string; label: string } | undefined {
+  const preferredLum = luminanceOf(preferred);
+  if (preferredLum === null) return undefined;
+  const labelOn = (step: string) =>
+    labels.find((label) => {
+      const lum = luminanceOf(label);
+      const stepLum = luminanceOf(step);
+      return (
+        lum !== null &&
+        stepLum !== null &&
+        contrastRatio(lum, stepLum) >= aaTextContrastRatio &&
+        Math.abs(apcaContrast(label, step)) >= fillLabelLc
+      );
+    });
+  let best: { fill: string; label: string } | undefined;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const step of [preferred, ...steps]) {
+    const lum = luminanceOf(step);
+    if (step === undefined || lum === null || contrastRatio(lum, paper) < minContrastRatio)
+      continue;
+    const label = labelOn(step);
+    const distance = Math.abs(lum - preferredLum);
+    if (label && distance < bestDistance) {
+      bestDistance = distance;
+      best = { fill: step, label };
+    }
+  }
+  return best;
+}
+
 /**
  * FZ-7715. A colour theme is the accent. The house accent is the neutral
  * inverse, and the hue sub-themes (light_green, dark_pink, ...) inherited it,
@@ -620,46 +780,49 @@ function holdColorThemeAccent(
       const ink = luminanceOf(scope.color12);
       const surfaces = [scope.color1, scope.color2, scope.color3, scope.color4].map(luminanceOf);
       if (paper === null || ink === null || surfaces.some((lum) => lum === null)) continue;
-      const fill = nearestHoldingStep(
-        ramp[8],
-        ramp.slice(0, 11),
-        (lum) =>
-          Math.max(contrastRatio(lum, paper), contrastRatio(lum, ink)) >= aaTextContrastRatio &&
-          contrastRatio(lum, paper) >= minContrastRatio,
+      const labels = [scope.color1, scope.color12].sort(
+        (a, b) => (luminanceOf(b) as number) - (luminanceOf(a) as number),
       );
+      const solid = holdFillLabel(ramp[8], ramp.slice(0, 11), labels, paper);
       const holdsInk = (lum: number) =>
         surfaces.every((surface) => contrastRatio(lum, surface as number) >= aaTextContrastRatio);
+      const fill =
+        solid?.fill ??
+        nearestHoldingStep(
+          ramp[8],
+          ramp.slice(0, 11),
+          (lum) =>
+            Math.max(contrastRatio(lum, paper), contrastRatio(lum, ink)) >= aaTextContrastRatio &&
+            contrastRatio(lum, paper) >= minContrastRatio,
+        );
       const accentInk =
         walkToHoldingInk(ramp[10], ramp[11], holdsInk) ??
         nearestHoldingStep(ramp[10], ramp, holdsInk);
       const fillStep = ramp.indexOf(fill);
       const fillHover = ramp[Math.min(fillStep + 1, ramp.length - 1)];
-      const onFill = holdInkFloor(fill, pickReadableForeground(fill, scope.color1, scope.color12));
+      const onFill =
+        solid?.label ??
+        holdInkFloor(fill, pickReadableForeground(fill, scope.color1, scope.color12));
       const accent: Record<string, string> = {
         accentBackground: fill,
         accentColor: accentInk,
         ...selectedPaint(scope, ramp, accentInk),
       };
-      // A hue fill can sit on the root's off grey (light pink on gray10): walk
-      // outward from the root's step to the nearest one that holds again.
-      const rootOff = Number(
-        Object.keys(base)
-          .find((key) => /^gray\d+$/.test(key) && base[key] === base.switchTrackOff)
-          ?.slice(4),
-      );
+      // A hue fill can sit on the root's off grey: repaint inside the band.
       const rootOn = luminanceOf(base.switchTrackOff);
       const fillLum = luminanceOf(fill);
       const rootHolds =
-        rootOn !== null &&
-        fillLum !== null &&
+        rootOn === null ||
+        fillLum === null ||
         contrastRatio(rootOn, fillLum) >= switchStateContrastRatio;
-      const outward = Array.from({ length: 10 }, (_, index) => index + 3).sort(
-        (a, b) => Math.abs(a - rootOff) - Math.abs(b - rootOff) || b - a,
-      );
-      const track =
-        rootHolds || Number.isNaN(rootOff)
-          ? undefined
-          : switchTrackPaint(base, fill, [scope.background, scope.color3], outward);
+      const track = rootHolds
+        ? undefined
+        : switchTrackPaint(
+            base,
+            fill,
+            scope.background,
+            isLightGround(scope.background) ? [] : [scope.color4],
+          );
       for (const [name, theme] of Object.entries(themes)) {
         if (name === scopeName) {
           out[name] = { ...theme, ...accent, ...track };
@@ -855,7 +1018,9 @@ export function createThemesBuilder(
         holdSyntaxFloor(
           holdNamedInkFloor(
             holdSelectedState(
-              holdAccentFloor(neutralizeSemanticEntryText(neutralizeTintText(initialTheme))),
+              holdAccentFloor(
+                holdSelectionSurface(neutralizeSemanticEntryText(neutralizeTintText(initialTheme))),
+              ),
             ),
           ),
         ),