@multiplatform.one/theme 8.2.2 → 8.4.0

package/src/theme/createThemes.ts

@@ -18,12 +18,14 @@ import {
   plateContrastRatio,
   relativeLuminance,
   switchOffFillAlpha,
+  switchOffGround,
   systemFillHex,
   systemFillLuminance,
 } from "./colorRules";
-import { pickSecondaryInk } from "./defaults/builderOptions";
+import { darkHairlineContrast, pickSecondaryInk } from "./defaults/builderOptions";
 import { themeRampHues } from "./ramps";
-import { withAccentOnSurface, withIdentityInk } from "./accentInk";
+import { pageSurfaces, pickIdentityInk, withAccentOnSurface, withIdentityInk } from "./accentInk";
+import { resolveThemeThroughParents } from "./dedupeInherited";
 import { tintHueNames } from "./tintHues";
 
 export { tintHueNames };
@@ -79,9 +81,63 @@ const lightSurfaceGrouped = {
   backgroundActive: PALETTE_BACKGROUND_OFFSET,
 };
 
+/**
+ * LC-151 in dark (FZ-8400): the page drops to the ramp's darkest step
+ * (`$color1`) and the grouped surfaces climb one step (surface1 `$color4`,
+ * surface2 `$color5`), so a card, list group or field steps off the page by at
+ * least iOS's grouped step (`#1C1C1E` on black, 1.23:1). v5 stock put
+ * surface1 one step over a `$color2` page, `#191919` on `#151515` (1.07:1),
+ * and groups vanished. A Button's surface2 climbs with them so it still sits a
+ * step off the card. Light is untouched, and the ramp stays stock v5.
+ */
+const fillKeys = [
+  "background",
+  "backgroundHover",
+  "backgroundPress",
+  "backgroundFocus",
+  "backgroundActive",
+] as const;
+const edgeKeys = [
+  "borderColor",
+  "borderColorHover",
+  "borderColorFocus",
+  "borderColorPress",
+] as const;
+
+function liftOneStep<T extends Record<string, number>>(template: T) {
+  const lifted: Record<string, number> = { ...template };
+  for (const key of [...fillKeys, ...edgeKeys]) lifted[key] = template[key] + 1;
+  return lifted as T;
+}
+
+/**
+ * Cards, list groups and fields in dark: surface1 lifted, and the LC-05
+ * selection fills re-pointed one step above the card's own `$color4`, so a
+ * selected or pressed row inside an inset group never lands on the group's
+ * fill. On the page they stay `$color4` and `$color5`. Each theme key costs
+ * about 1.4 KB of theme CSS, so there are two.
+ */
+const darkSurfaceGrouped = {
+  ...liftOneStep(v5Templates.dark_surface1),
+  selectFill: PALETTE_BACKGROUND_OFFSET + 4,
+  selectPress: PALETTE_BACKGROUND_OFFSET + 5,
+};
+
+const darkBasePage = {
+  ...v5Templates.dark_base,
+  background: PALETTE_BACKGROUND_OFFSET,
+  backgroundActive: PALETTE_BACKGROUND_OFFSET,
+  backgroundFocus: PALETTE_BACKGROUND_OFFSET + 1,
+  backgroundHover: PALETTE_BACKGROUND_OFFSET + 1,
+  backgroundPress: PALETTE_BACKGROUND_OFFSET + 1,
+};
+
 export const houseTemplates = {
   ...v5Templates,
   light_surface1: lightSurfaceGrouped,
+  dark_base: darkBasePage,
+  dark_surface1: darkSurfaceGrouped,
+  dark_surface2: liftOneStep(v5Templates.dark_surface2),
 };
 
 export const houseComponentThemes = {
@@ -296,7 +352,15 @@ function holdAccentFloor(
     if (!base?.accentBackground || !base.accentColor) continue;
     const paper = luminanceOf(base.color1);
     const ink = luminanceOf(base.color12);
-    const surfaces = [base.color1, base.color2, base.color3, base.color4].map(luminanceOf);
+    // A dark overlay paints `$color5` (LC-85, FZ-8400), and a Toast's accent
+    // action sits on it.
+    const surfaces = [
+      base.color1,
+      base.color2,
+      base.color3,
+      base.color4,
+      ...(scheme === "dark" ? [base.color5] : []),
+    ].map(luminanceOf);
     if (paper === null || ink === null || surfaces.some((lum) => lum === null)) continue;
     const steps = Array.from({ length: 12 }, (_, index) => base[`accent${index + 1}`]);
     const fill = nearestHoldingStep(
@@ -367,12 +431,188 @@ function holdSelectionSurface(
         ...out[name],
         color4: held,
         ...(theme.borderColor === scope.color4 ? { borderColor: held } : null),
+        ...(theme.selectFill === scope.color4 ? { selectFill: held } : null),
       };
     }
   }
   return out;
 }
 
+/**
+ * LC-148 in dark (FZ-9281): a dark scope's hairline is the first ramp step
+ * that clears `darkHairlineContrast` against its page and its grouped surface
+ * (`$color4`), and its medium edge is the next step up. One step toward the
+ * page put the hairline under the card's own fill, and the medium edge on the
+ * card's fill, so both vanished. The picks are measured per scope, so a ramp
+ * change moves them with it. Edge states keep their offsets from the medium
+ * edge. Light keeps v5's edges.
+ */
+function holdDarkEdges(
+  themes: Record<string, Record<string, string>>,
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = { ...themes };
+  const scopes = Object.keys(themes).filter((name) => /^dark(_[a-z]+)?$/.test(name));
+  const ownerOf = (name: string) =>
+    scopes
+      .filter((scope) => name === scope || name.startsWith(`${scope}_`))
+      .reduce((longest, scope) => (scope.length > longest.length ? scope : longest), "");
+  for (const scopeName of scopes) {
+    if (/_(accent|active)$/.test(scopeName)) continue;
+    const scope = themes[scopeName]!;
+    const ramp = Array.from({ length: 12 }, (_, index) => scope[`color${index + 1}`]);
+    const grounds = [scope.background, scope.color4].map((color) => luminanceOf(color));
+    if (grounds.some((ground) => ground === null)) continue;
+    const brightest = Math.max(...(grounds as number[]));
+    const clears = (color: string | undefined) => {
+      const luminance = luminanceOf(color);
+      return (
+        luminance !== null &&
+        luminance > brightest &&
+        (grounds as number[]).every(
+          (ground) => contrastRatio(luminance, ground) >= darkHairlineContrast,
+        )
+      );
+    };
+    const hairline = ramp.findIndex((color, index) => index < 11 && clears(color));
+    if (hairline < 0) continue;
+    const medium = hairline + 1;
+    for (const [name, theme] of Object.entries(themes)) {
+      if (ownerOf(name) !== scopeName) continue;
+      const surface = name === scopeName || theme.background === scope.color4;
+      const step = ramp.indexOf(theme.borderColor);
+      const shift = surface && step >= 0 ? medium - step : 0;
+      const moved: Record<string, string> = {};
+      if ("borderColorHairline" in theme || name === scopeName)
+        moved.borderColorHairline = ramp[hairline]!;
+      if (shift > 0) {
+        for (const key of [
+          "borderColor",
+          "borderColorHover",
+          "borderColorFocus",
+          "borderColorPress",
+        ]) {
+          const at = ramp.indexOf(theme[key]);
+          if (at >= 0) moved[key] = ramp[Math.min(11, at + shift)]!;
+        }
+      }
+      out[name] = { ...out[name], ...moved };
+    }
+  }
+  return out;
+}
+
+/**
+ * LC-299 CONTROL-EDGE (FZ-9358, WCAG 1.4.11): a field's edge
+ * (`$borderColorField`) is the first neutral step at 3:1 on the page and on
+ * the field's own fill, and its hover never drops under it.
+ * `$borderColorControl` is the same pick on the page alone, for the segmented
+ * frame and the light off Switch track. Dark's off track stays edgeless: its
+ * white thumb already clears 3:1. A semantic intent's field edge is the first
+ * step of its own ramp at 3:1 on every page and on its fill, so error stays red.
+ * Picks sit on the scheme roots and a scope overrides only where its own
+ * differs: one copy per component sub-theme overruns the CSS budget.
+ */
+function holdControlEdges(
+  themes: Record<string, Record<string, string>>,
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = { ...themes };
+  const firstClearing = (neutral: string[], grounds: (string | undefined)[]) => {
+    const lums = grounds.map((ground) => luminanceOf(ground));
+    if (lums.some((lum) => lum === null)) return -1;
+    const darkest = Math.min(...(lums as number[]));
+    const brightest = Math.max(...(lums as number[]));
+    const light = isLightGround(grounds[0]!);
+    return neutral.findIndex((color) => {
+      const lum = luminanceOf(color);
+      return (
+        lum !== null &&
+        (light ? lum < darkest : lum > brightest) &&
+        (lums as number[]).every((ground) => contrastRatio(lum, ground) >= minContrastRatio)
+      );
+    });
+  };
+  const resolved = (name: string, key: string): string | undefined => {
+    for (let at = name; at; at = at.slice(0, Math.max(0, at.lastIndexOf("_")))) {
+      const value = (out[at] ?? themes[at])?.[key];
+      if (value !== undefined) return value;
+      if (!at.includes("_")) break;
+    }
+    return undefined;
+  };
+  for (const scheme of ["light", "dark"] as const) {
+    const root = themes[scheme];
+    if (!root) continue;
+    const neutral = Array.from({ length: 12 }, (_, index) => root[`color${index + 1}`]!);
+    const fieldEdges = (scopeName: string) => {
+      const scope = themes[scopeName]!;
+      const field = `${scopeName}_Input`;
+      const edge = firstClearing(neutral, [scope.background, resolved(field, "background")]);
+      if (edge < 0) return undefined;
+      const ramp = Array.from({ length: 12 }, (_, index) => scope[`color${index + 1}`]);
+      const stepOf = (color: string | undefined) => {
+        const lum = luminanceOf(color);
+        if (lum === null) return -1;
+        return ramp.reduce(
+          (best, step, index) =>
+            Math.abs((luminanceOf(step) ?? 2) - lum) <
+            Math.abs((luminanceOf(ramp[best]) ?? 2) - lum)
+              ? index
+              : best,
+          0,
+        );
+      };
+      const rest = stepOf(resolved(field, "borderColor"));
+      const hover = stepOf(resolved(field, "borderColorHover"));
+      return {
+        borderColorField: neutral[edge]!,
+        borderColorFieldHover: neutral[Math.min(11, Math.max(edge, edge + hover - rest))]!,
+      };
+    };
+    const rootFields = fieldEdges(scheme);
+    const rootControl = firstClearing(neutral, [root.background]);
+    if (!rootFields || rootControl < 0) continue;
+    out[scheme] = {
+      ...out[scheme],
+      ...rootFields,
+      borderColorControl: neutral[rootControl]!,
+      switchTrackOffBorder: scheme === "light" ? neutral[rootControl]! : root.switchTrackOff!,
+    };
+    const scopes = Object.keys(themes).filter(
+      (name) => new RegExp(`^${scheme}_[a-z]+$`).test(name) && !/_(accent|active)$/.test(name),
+    );
+    const pages = [
+      root.background,
+      ...scopes
+        .filter((name) => !semanticIntentNames.has(name.slice(scheme.length + 1)))
+        .map((name) => themes[name]!.background),
+    ];
+    for (const scopeName of scopes) {
+      const scope = themes[scopeName]!;
+      const patch: Record<string, string> = {};
+      if (scheme === "dark" && "switchTrackOff" in scope)
+        patch.switchTrackOffBorder = scope.switchTrackOff!;
+      if (semanticIntentNames.has(scopeName.slice(scheme.length + 1))) {
+        const field = `${scopeName}_Input`;
+        const ramp = Array.from({ length: 12 }, (_, index) => scope[`color${index + 1}`]!);
+        const edge = firstClearing(ramp, [...pages, resolved(field, "background")]);
+        patch.borderColorField = edge < 0 ? resolved(field, "borderColor")! : ramp[edge]!;
+        patch.borderColorFieldHover =
+          edge < 0 ? resolved(field, "borderColorHover")! : ramp[Math.min(11, edge + 1)]!;
+      } else {
+        const fields = fieldEdges(scopeName);
+        if (fields) {
+          for (const [key, value] of Object.entries(fields))
+            if (value !== rootFields[key as keyof typeof rootFields]) patch[key] = value;
+        }
+        const control = firstClearing(neutral, [scope.background]);
+        if (control >= 0 && control !== rootControl) patch.borderColorControl = neutral[control]!;
+      }
+      if (Object.keys(patch).length > 0) out[scopeName] = { ...out[scopeName], ...patch };
+    }
+  }
+  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
@@ -475,7 +715,10 @@ 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). */
+/**
+ * Dark's raised grounds under a Switch: the `$color4` card or field it sits in
+ * and the `$color5` overlay (LC-151 and LC-85, FZ-8400; FZ-7944's plate floor).
+ */
 function raisedGrounds(
   themes: Record<string, Record<string, string>>,
   scheme: "light" | "dark",
@@ -484,9 +727,9 @@ function raisedGrounds(
   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",
-  );
+  return [themes[scheme], ...hues.map(([, theme]) => theme)]
+    .flatMap((theme) => [theme?.color4, theme?.color5])
+    .filter((color): color is string => typeof color === "string");
 }
 
 function holdSwitchTrack(
@@ -496,13 +739,36 @@ function holdSwitchTrack(
   for (const scheme of ["light", "dark"] as const) {
     const base = themes[scheme];
     if (!base) continue;
+    // A dark switch sits on the `$color4` card or field (LC-151, FZ-8400), as
+    // UISwitch does on a grouped cell, so its band is measured there.
     const paint = switchTrackPaint(
       base,
       base.accentBackground,
-      base.background,
+      switchOffGround(base),
       raisedGrounds(themes, scheme),
     );
     if (paint) out[scheme] = { ...base, ...paint };
+    if (scheme !== "dark" || !paint) continue;
+    // A semantic intent's card is its own hue's `$color4`: repaint where the
+    // root's off track leaves the band or the plate floor there.
+    for (const intent of semanticIntentNames) {
+      const scope = themes[`${scheme}_${intent}`];
+      const off = luminanceOf(paint.switchTrackOff);
+      if (!scope?.color4 || !scope.color5 || off === null) continue;
+      const holds =
+        inSwitchOffBand(paint.switchTrackOff, scope.color4) &&
+        [scope.color4, scope.color5].every(
+          (ground) => contrastRatio(off, luminanceOf(ground) ?? off) >= plateContrastRatio,
+        );
+      if (holds) continue;
+      const track = switchTrackPaint(
+        base,
+        scope.accentBackground ?? base.accentBackground,
+        scope.color4,
+        [base.color4, scope.color4, scope.color5],
+      );
+      if (track) out[`${scheme}_${intent}`] = { ...scope, ...track };
+    }
   }
   return out;
 }
@@ -766,7 +1032,13 @@ function holdColorThemeAccent(
       if (!scope || ramp.some((step) => !step)) continue;
       const paper = luminanceOf(scope.color1);
       const ink = luminanceOf(scope.color12);
-      const surfaces = [scope.color1, scope.color2, scope.color3, scope.color4].map(luminanceOf);
+      const surfaces = [
+        scope.color1,
+        scope.color2,
+        scope.color3,
+        scope.color4,
+        ...(scheme === "dark" ? [scope.color5] : []),
+      ].map(luminanceOf);
       if (paper === null || ink === null || surfaces.some((lum) => lum === null)) continue;
       const labels = [scope.color1, scope.color12].sort(
         (a, b) => (luminanceOf(b) as number) - (luminanceOf(a) as number),
@@ -798,17 +1070,22 @@ function holdColorThemeAccent(
       // 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 switchGround = switchOffGround(scope) ?? scope.background;
       const rootHolds =
         rootOn === null ||
         fillLum === null ||
-        contrastRatio(rootOn, fillLum) >= switchStateContrastRatio;
+        (contrastRatio(rootOn, fillLum) >= switchStateContrastRatio &&
+          inSwitchOffBand(base.switchTrackOff, switchGround) &&
+          (isLightGround(scope.background) ? [] : [scope.color4, scope.color5]).every(
+            (ground) => contrastRatio(rootOn, luminanceOf(ground) ?? rootOn) >= plateContrastRatio,
+          ));
       const track = rootHolds
         ? undefined
         : switchTrackPaint(
             base,
             fill,
-            scope.background,
-            isLightGround(scope.background) ? [] : [scope.color4],
+            switchGround,
+            isLightGround(scope.background) ? [] : [base.color4, scope.color4, scope.color5],
           );
       for (const [name, theme] of Object.entries(themes)) {
         if (name === scopeName) {
@@ -943,6 +1220,41 @@ function holdHouseAccent(
   return out;
 }
 
+/**
+ * FZ-10073 with FZ-8400's dark overlay. The house root's identity ink is the
+ * blue colour theme's. Judged on the neutral page alone, dark house picked
+ * blue10 #3b9eff, which fails AA on blue's own `$color5` overlay, where blue
+ * picks blue11 #70b8ff. A house theme (the scheme root, its components and
+ * the intents that followed it) takes blue's ink when that ink also holds AA
+ * on its own page surfaces, so the bar glyph is one blue in either scope.
+ */
+function holdHouseIdentityInk(
+  themes: Record<string, Record<string, string>>,
+): Record<string, Record<string, string>> {
+  const out: Record<string, Record<string, string>> = { ...themes };
+  for (const scheme of ["light", "dark"] as const) {
+    const base = themes[scheme];
+    const blueInk = themes[`${scheme}_blue`]?.identityInk;
+    if (!base?.identityInk || !blueInk || base.identityInk === blueInk) continue;
+    const held = Array.from({ length: 12 }, (_, index) => index + 1).every(
+      (step) =>
+        base[`accent${step}`] !== undefined && base[`accent${step}`] === base[`blue${step}`],
+    );
+    if (!held) continue;
+    for (const [name, theme] of Object.entries(themes)) {
+      if (name !== scheme && !name.startsWith(`${scheme}_`)) continue;
+      const scope = name.split("_")[1];
+      if (scope === "accent" || (childrenHues as readonly string[]).includes(scope)) continue;
+      if (theme.identityInk !== base.identityInk) continue;
+      const values = resolveThemeThroughParents(themes, name);
+      if (pickIdentityInk([blueInk], pageSurfaces(name, values)) === blueInk) {
+        out[name] = { ...theme, identityInk: blueInk };
+      }
+    }
+  }
+  return out;
+}
+
 const defaultLightShadows: Shadows = {
   shadow1: "rgba(0,0,0,0.04)",
   shadow2: "rgba(0,0,0,0.08)",
@@ -1021,6 +1333,27 @@ function isChromatic(color: string | undefined): boolean {
   return Math.max(...channels) - Math.min(...channels) >= 24;
 }
 
+/**
+ * Theme keys that only the post-passes in {@link createThemesBuilder} write
+ * (the hold* passes, withAccentOnSurface, withIdentityInk). The `$token` lint
+ * in public/config/lint.mjs reads this list, since it cannot run the passes,
+ * and themeKeyRegistry.spec fails when a pass adds a key missing here.
+ */
+export const postPassThemeKeys = [
+  "accentOnSurface",
+  "borderColorControl",
+  "borderColorField",
+  "borderColorFieldHover",
+  "borderColorHairline",
+  "identityInk",
+  "selectedBackground",
+  "selectedColor",
+  "switchTrackOff",
+  "switchTrackOffBorder",
+  "switchTrackOffHover",
+  "switchTrackOffPress",
+] as const;
+
 export function createThemesBuilder(
   baseTheme: BaseThemeBuilderDefinition,
   accentTheme: ThemeBuilderDefinition,
@@ -1090,18 +1423,24 @@ export function createThemesBuilder(
   const initialTheme = tamaguiCreateThemes(
     createThemesProps as Parameters<typeof tamaguiCreateThemes>[0],
   );
-  const themes = withIdentityInk(
-    withAccentOnSurface(
-      holdFocusRingAccent(
-        holdHouseAccent(
-          holdColorThemeAccent(
-            holdSwitchTrack(
-              holdSyntaxFloor(
-                holdNamedInkFloor(
-                  holdSelectedState(
-                    holdAccentFloor(
-                      holdSelectionSurface(
-                        neutralizeSemanticEntryText(neutralizeTintText(initialTheme)),
+  const themes = holdHouseIdentityInk(
+    withIdentityInk(
+      withAccentOnSurface(
+        holdFocusRingAccent(
+          holdControlEdges(
+            holdHouseAccent(
+              holdColorThemeAccent(
+                holdSwitchTrack(
+                  holdSyntaxFloor(
+                    holdNamedInkFloor(
+                      holdSelectedState(
+                        holdAccentFloor(
+                          holdDarkEdges(
+                            holdSelectionSurface(
+                              neutralizeSemanticEntryText(neutralizeTintText(initialTheme)),
+                            ),
+                          ),
+                        ),
                       ),
                     ),
                   ),

package/src/theme/defaults/builderOptions.ts

@@ -1,5 +1,11 @@
 import type { CreateThemesBuilderOptions, GetThemeProps } from "../createThemes";
-import { contrastRatio, minContrastRatio, normalizeToHex, relativeLuminance } from "../colorRules";
+import {
+  contrastRatio,
+  isLightGround,
+  minContrastRatio,
+  normalizeToHex,
+  relativeLuminance,
+} from "../colorRules";
 
 /**
  * DG-A11Y-01 / DF-03. The external focus ring must clear 3:1 against both page
@@ -62,6 +68,14 @@ function pickBoundaryColor(theme: Record<string, string>): string {
   return best;
 }
 
+/**
+ * LC-148 HAIRLINE-TOKEN in dark (FZ-9281): the least contrast a dark hairline
+ * holds against the page and against the grouped surface it divides. iOS's
+ * dark `opaqueSeparator` #38383A over `secondarySystemGroupedBackground`
+ * #1C1C1E measures 1.454:1. The medium edge sits one ramp step above it.
+ */
+export const darkHairlineContrast = 1.454;
+
 /**
  * LC-148 HAIRLINE-TOKEN: `$borderColor` one ramp step toward the page. Where
  * the `small` border stop can't draw finer than 1px (web), the resolver paints
@@ -84,7 +98,8 @@ function pickHairlineBorderColor(
  * and the pick is the most muted ramp step that clears it. The stock v5 ramp
  * is not symmetric: light $color11 is 14% lightness, two points off the
  * primary ink, so one fixed step cannot read as secondary in both schemes.
- * On the default ramp this lands on $color9 in light and $color10 in dark.
+ * On the default ramp this lands on $color9 in light and $color11 in dark,
+ * where cards sit on $color4 (FZ-8400).
  */
 export const secondaryInkContrast = 7;
 
@@ -97,9 +112,10 @@ export function pickSecondaryInk(
   ramp: Record<string, string> = theme,
 ): string {
   const fallback = ramp.color11 ?? ramp.color12 ?? "transparent";
-  const surfaces = [theme.background, theme.color1, theme.color2, theme.color3].map((raw) =>
-    normalizeToHex(raw ?? ""),
-  );
+  const tiers = [theme.background, theme.color1, theme.color2, theme.color3];
+  // Dark cards and fields sit on `$color4` (FZ-8400).
+  if (theme.background && !isLightGround(theme.background)) tiers.push(theme.color4);
+  const surfaces = tiers.map((raw) => normalizeToHex(raw ?? ""));
   if (surfaces.some((hex) => !hex)) return fallback;
   const luminances = surfaces.map((hex) => relativeLuminance(hex!));
   for (const key of [8, 9, 10, 11]) {
@@ -125,11 +141,12 @@ function getBaseTheme(theme: Record<string, string>) {
     textMuted: pickSecondaryInk(theme),
     textSubtle: theme.color10,
     borderStrong: theme.color7,
-    borderStrongHover: theme.color8,
-    borderStrongPress: theme.color6,
     surfaceStrong: theme.color7,
     surfaceMuted: theme.color10,
-    surfacePressStrong: theme.color6,
+    // LC-05 selection fills (componentColors, formSelectionColors). A dark
+    // card re-points them one step above its own fill (createThemes).
+    selectFill: theme.color4,
+    selectPress: theme.color5,
   };
 }
 

package/src/theme/defaults/secondaryInk.spec.ts

@@ -14,17 +14,22 @@ const built = createThemesBuilder(
 ).themes() as Themes;
 
 const luminance = (raw: string) => relativeLuminance(normalizeToHex(raw)!);
+// A dark card is `$color4` (LC-151, FZ-8400), so dark checks that tier too.
 const minContrast = (theme: Record<string, string>, ink: string) =>
   Math.min(
-    ...[theme.background!, theme.color1!, theme.color2!, theme.color3!].map((surface) =>
-      contrastRatio(luminance(ink), luminance(surface)),
-    ),
+    ...[
+      theme.background!,
+      theme.color1!,
+      theme.color2!,
+      theme.color3!,
+      ...(luminance(theme.background!) < 0.18 ? [theme.color4!] : []),
+    ].map((surface) => contrastRatio(luminance(ink), luminance(surface))),
   );
 
 describe("LC-152 secondary ink", () => {
-  it("lands on $color9 in light and $color10 in dark on the default ramp", () => {
+  it("lands on $color9 in light and $color11 in dark on the default ramp", () => {
     expect(built.light!.textMuted).toBe(built.light!.color9);
-    expect(built.dark!.textMuted).toBe(built.dark!.color10);
+    expect(built.dark!.textMuted).toBe(built.dark!.color11);
   });
 
   it("clears 7:1 on the page and every card tier in both schemes", () => {

package/src/theme/fillContrast.spec.ts

@@ -22,6 +22,7 @@ import {
   contrastRatio,
   fillLabelLc,
   inSwitchOffBand,
+  switchOffGround,
   normalizeToHex,
   relativeLuminance,
 } from "./colorRules";
@@ -133,9 +134,14 @@ describe("LC-172 the engine keeps every off toggle in the HIG band, a preset's o
   });
 
   for (const name of scopes) {
-    it(`${name}: the off track sits in the system-fill band over the page`, () => {
+    it(`${name}: the off track sits in the system-fill band over its ground (the dark card)`, () => {
       const off = String(resolved[name].switchTrackOff);
-      const ground = String(resolved[name].background);
+      const ground = String(
+        switchOffGround({
+          background: String(resolved[name].background),
+          color4: String(resolved[name].color4),
+        }),
+      );
       expect(inSwitchOffBand(off, ground), `${off} on ${ground}`).toBe(true);
     });
   }

package/src/theme/fillContrast.ts

@@ -1,5 +1,11 @@
 import { accentIdentityCandidates, resolveChartPalette } from "./chartPalette";
-import { apcaContrast, fillLabelLc, inSwitchOffBand, normalizeToHex } from "./colorRules";
+import {
+  apcaContrast,
+  fillLabelLc,
+  inSwitchOffBand,
+  normalizeToHex,
+  switchOffGround,
+} from "./colorRules";
 import { tintHueNames } from "./createThemes";
 
 export { apcaContrast };
@@ -129,7 +135,9 @@ export function auditPresetFills(
       }
     }
     const off = text(scope.switchTrackOff);
-    const ground = text(scope.background);
+    const ground = text(
+      switchOffGround({ background: text(scope.background), color4: text(scope.color4) }),
+    );
     if (!off || !ground || !inSwitchOffBand(off, ground)) {
       findings.push({
         preset,

package/src/theme/houseGround.spec.ts

@@ -23,7 +23,7 @@ const housePresets = {
   storefront: storefrontPreset,
 };
 
-const page = { light: "#f7f7f7", dark: "#141414" } as const;
+const page = { light: "#f7f7f7", dark: "#0a0a0a" } as const;
 
 const groundKeys = [
   "background",

package/src/theme/index.ts

@@ -25,6 +25,7 @@ export * from "./intents";
 export * from "./knobs";
 export * from "./layoutTokens";
 export * from "./pageGutter";
+export * from "./tokenNumber";
 export * from "./Preset";
 export type { Preset as PresetDefinition, IntentOverride } from "./preset.types";
 export * from "./PresetContext";

package/src/theme/nativeSchemePreference.ts

@@ -50,9 +50,10 @@ export function useSchemePreference(): SchemePreference {
     getNativeScheme();
     Appearance.setColorScheme(setting === "system" ? "unspecified" : setting);
   }, [setting]);
+  const resolved = setting === "system" ? os : setting;
   return {
     setting: hydrated ? setting : "system",
-    value: !hydrated ? "light" : setting === "system" ? os : setting,
+    value: hydrated ? resolved : "light",
     set: setStoredScheme,
   };
 }

package/src/theme/nativeTheme.tsx

@@ -47,7 +47,7 @@ export function ThemeProvider<T extends CreateTamaguiProps>({
   config,
   systemTheme,
   ...tamaguiProps
-}: ThemeProviderProps<T>) {
+}: Readonly<ThemeProviderProps<T>>) {
   const scheme = useSchemePreference();
   const activeTheme = systemTheme ?? scheme.value;
   const ancestor = useContext(PresetContext);