@multiplatform.one/theme 7.83.1 → 7.84.0

package/src/theme/hairline.spec.ts

@@ -1,5 +1,11 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { ensureHairlineFallback, hairline, hairlineFallbackCss, hairlineWidth } from "./hairline";
+import {
+  ensureHairlineFallback,
+  hairline,
+  hairlineFallbackCss,
+  hairlineThickness,
+  hairlineWidth,
+} from "./hairline";
 
 describe("hairline (Axiom 15 OPTICS)", () => {
   it("resolves half a CSS pixel on web", () => {
@@ -43,8 +49,46 @@ describe("hairline (Axiom 15 OPTICS)", () => {
     expect(hairlineFallbackCss).toContain("border-inline-end-width: 1px !important");
     // filled-line fallbacks must pin max-height/max-width too (the `line`
     // treatment sets both, so height alone could not win)
-    expect(hairlineFallbackCss).toContain("height: 1px !important; max-height: 1px !important");
-    expect(hairlineFallbackCss).toContain("width: 1px !important; max-width: 1px !important");
+    // and never under one device pixel when zoomed out below 1dppx
+    expect(hairlineFallbackCss).toContain(
+      "height: max(1px, var(--mp-hairline, 1px)) !important; max-height: max(1px, var(--mp-hairline, 1px)) !important",
+    );
+    expect(hairlineFallbackCss).toContain(
+      "width: max(1px, var(--mp-hairline, 1px)) !important; max-width: max(1px, var(--mp-hairline, 1px)) !important",
+    );
+  });
+
+  it("keeps a zoomed-out ratio under 1 at one device pixel, past the 1px floor", () => {
+    for (const ratio of [0.5, 0.67, 0.8, 0.9]) {
+      const thickness = Math.max(1, hairlineThickness(ratio));
+      expect(thickness * ratio, `ratio ${ratio}`).toBeGreaterThanOrEqual(1);
+    }
+  });
+
+  // FZ-8395: a filled box under one device pixel snaps to 0 on alternate rows.
+  it("draws filled lines at least one device pixel at every ratio, never 0", () => {
+    for (const ratio of [1, 1.25, 1.5, 1.75, 1.8, 2, 2.25, 2.5, 2.625, 3, 3.5, 4]) {
+      const devicePx = hairlineThickness(ratio) * ratio;
+      expect(devicePx, `ratio ${ratio}`).toBeGreaterThanOrEqual(1);
+      expect(devicePx, `ratio ${ratio}`).toBeLessThan(1.1);
+      // On Blink's 1/64 px layout grid, so layout cannot round it under.
+      expect(Number.isInteger(hairlineThickness(ratio) * 64), `ratio ${ratio}`).toBe(true);
+    }
+    expect(hairlineThickness(2)).toBe(0.5);
+    expect(hairlineThickness(Number.NaN)).toBe(1);
+  });
+
+  it("sizes the filled treatments from --mp-hairline, above the inline 0.5px", () => {
+    expect(hairlineFallbackCss).toContain(
+      ".mp-hairline-h { height: var(--mp-hairline, 0.5px) !important",
+    );
+    expect(hairlineFallbackCss).toContain(
+      ".mp-hairline-w { width: var(--mp-hairline, 0.5px) !important",
+    );
+    // The low-DPI 1px block comes after, so it still wins there.
+    expect(hairlineFallbackCss.indexOf("@media")).toBeGreaterThan(
+      hairlineFallbackCss.indexOf("var(--mp-hairline"),
+    );
   });
 
   describe("fallback stylesheet mount", () => {
@@ -59,5 +103,18 @@ describe("hairline (Axiom 15 OPTICS)", () => {
       expect(tags).toHaveLength(1);
       expect(tags[0]?.textContent).toBe(hairlineFallbackCss);
     });
+
+    it("points --mp-hairline at one device pixel of the live ratio", () => {
+      const original = window.devicePixelRatio;
+      Object.defineProperty(window, "devicePixelRatio", { configurable: true, value: 1.75 });
+      try {
+        ensureHairlineFallback();
+        expect(document.documentElement.style.getPropertyValue("--mp-hairline")).toBe(
+          `${hairlineThickness(1.75)}px`,
+        );
+      } finally {
+        Object.defineProperty(window, "devicePixelRatio", { configurable: true, value: original });
+      }
+    });
   });
 });

package/src/theme/hairline.ts

@@ -81,21 +81,50 @@ export const hairline = {
 const STYLE_TAG_ID = "mp-hairline-styles";
 
 /**
- * 1px fallback for screens where 0.5px cannot map to a whole device pixel.
+ * FZ-8395: the filled lines' thickness, one device pixel rounded UP to
+ * Blink's 1/64 px layout unit. A filled box under one device pixel tall snaps
+ * to 0 or 1 device pixel depending on where its top lands, so 0.5 CSS px
+ * vanished on alternate rows at ratios between 1.5 and 2 (Windows 150-175%
+ * scaling, browser zoom). Exactly one device pixel or more never rounds to 0.
+ */
+export function hairlineThickness(devicePixelRatio: number): number {
+  const ratio = Number.isFinite(devicePixelRatio) && devicePixelRatio > 0 ? devicePixelRatio : 1;
+  return Math.ceil(64 / ratio) / 64;
+}
+
+/**
+ * The filled `line`, `vline` and `height` treatments read their thickness
+ * from `--mp-hairline` (set from the live ratio below; 0.5px until it is), and
+ * low-DPI screens get a 1px floor for every treatment; a zoomed-out ratio
+ * under 1 keeps the filled ones at one device pixel, past that floor.
  * (`-webkit-max-device-pixel-ratio` covers Safari versions without
  * `resolution` media-query support.) Exported for unit tests.
  */
-export const hairlineFallbackCss = `@media (max-resolution: 1.49dppx), (-webkit-max-device-pixel-ratio: 1.49) {
+export const hairlineFallbackCss = `.mp-hairline-h { height: var(--mp-hairline, 0.5px) !important; max-height: var(--mp-hairline, 0.5px) !important; flex-basis: var(--mp-hairline, 0.5px) !important; }
+.mp-hairline-w { width: var(--mp-hairline, 0.5px) !important; max-width: var(--mp-hairline, 0.5px) !important; flex-basis: var(--mp-hairline, 0.5px) !important; }
+@media (max-resolution: 1.49dppx), (-webkit-max-device-pixel-ratio: 1.49) {
   .mp-hairline-b { border-bottom-width: 1px !important; }
   .mp-hairline-t { border-top-width: 1px !important; }
   .mp-hairline-r { border-right-width: 1px !important; }
   .mp-hairline-l { border-left-width: 1px !important; }
-  .mp-hairline-h { height: 1px !important; max-height: 1px !important; flex-basis: 1px !important; }
-  .mp-hairline-w { width: 1px !important; max-width: 1px !important; flex-basis: 1px !important; }
+  .mp-hairline-h { height: max(1px, var(--mp-hairline, 1px)) !important; max-height: max(1px, var(--mp-hairline, 1px)) !important; flex-basis: max(1px, var(--mp-hairline, 1px)) !important; }
+  .mp-hairline-w { width: max(1px, var(--mp-hairline, 1px)) !important; max-width: max(1px, var(--mp-hairline, 1px)) !important; flex-basis: max(1px, var(--mp-hairline, 1px)) !important; }
   .mp-hairline-ie { border-inline-end-width: 1px !important; }
 }`;
 
-/** Idempotently mount the low-DPI fallback stylesheet (no-op off-DOM). */
+let watchedRatio: MediaQueryList | undefined;
+
+/** Point `--mp-hairline` at one device pixel, and again whenever the ratio changes. */
+function trackDevicePixel(): void {
+  if (typeof window === "undefined") return;
+  const ratio = window.devicePixelRatio || 1;
+  document.documentElement.style.setProperty("--mp-hairline", `${hairlineThickness(ratio)}px`);
+  watchedRatio?.removeEventListener?.("change", trackDevicePixel);
+  watchedRatio = window.matchMedia?.(`(resolution: ${ratio}dppx)`);
+  watchedRatio?.addEventListener?.("change", trackDevicePixel);
+}
+
+/** Idempotently mount the hairline stylesheet (no-op off-DOM). */
 export function ensureHairlineFallback(): void {
   if (typeof document === "undefined") return;
   if (document.getElementById(STYLE_TAG_ID)) return;
@@ -103,6 +132,7 @@ export function ensureHairlineFallback(): void {
   tag.id = STYLE_TAG_ID;
   tag.textContent = hairlineFallbackCss;
   document.head.appendChild(tag);
+  trackDevicePixel();
 }
 
 // The fallback is static CSS (no knob/theme dependency), so mount it as soon

package/src/theme/readableColor.ts

@@ -3,11 +3,13 @@ import { useTheme as useTamaguiTheme, useThemeName } from "tamagui";
 import {
   aaTextContrastRatio,
   contrastRatio,
+  holdHueToFloor,
   holdInkFloor,
   normalizeToHex,
   pickReadableForeground,
   relativeLuminance,
 } from "./colorRules";
+import { isDarkThemeName } from "./controlTiers";
 import { tintHueNames } from "./createThemes";
 
 /**
@@ -314,3 +316,50 @@ export function useAccentTintedSurface(): string | undefined {
   const paper = resolveTokenValue(theme, "color1");
   return useMemo(() => resolveAccentTintedSurface({ solid, paper }), [solid, paper]);
 }
+
+/** LC-172's floor for a hue: the spread between the strongest and weakest sRGB channel. */
+const ACTIVE_TAB_CHROMA_FLOOR = 0.1;
+
+export interface ResolveActiveTabInkInput {
+  /** The theme's identity hue on the page, when it has one. */
+  hue: string | undefined;
+  /** The theme's accent solid (`$accentBackground`). */
+  solid: string | undefined;
+  dark: boolean;
+  surfaces: readonly (string | undefined)[];
+  ink: string;
+}
+
+/**
+ * LC-150: the active tab's ink, one pick for the MPO TabBar and the system
+ * tab bar. A hued theme keeps its identity hue. A theme with no identity hue
+ * but a hued accent solid takes that solid held to AA text contrast on the
+ * page. The house hue-less theme's solid is the neutral inverse, so the tab
+ * takes the primary ink, bold mono, never the grey ramp step.
+ */
+export function resolveActiveTabInk({
+  hue,
+  solid,
+  dark,
+  surfaces,
+  ink,
+}: ResolveActiveTabInkInput): string {
+  if (hue) return hue;
+  const solidHex = solid ? normalizeToHex(solid) : null;
+  if (solidHex && chromaOf(solidHex) >= ACTIVE_TAB_CHROMA_FLOOR) {
+    return holdHueToFloor(solidHex, surfaces, dark, aaTextContrastRatio);
+  }
+  return ink;
+}
+
+/** LC-150: the live theme's active-tab ink (see {@link resolveActiveTabInk}). */
+export function useActiveTabInk(): string {
+  const dark = isDarkThemeName(useThemeName() as string | undefined);
+  const { hue, c1, c2, ink } = useIdentityHue();
+  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
+  const solid = resolveTokenValue(theme, "accentBackground");
+  return useMemo(
+    () => resolveActiveTabInk({ hue, solid, dark, surfaces: [c1, c2], ink }),
+    [hue, solid, dark, c1, c2, ink],
+  );
+}

package/src/theme/resolveKnobs.ts

@@ -656,45 +656,26 @@ export interface ResolveKnobsEnvironment {
   painted?: boolean;
 }
 
-export function resolveKnobs(
-  knobs: Knobs,
-  override?: KnobPropsOverride,
-  scheme: ColorScheme = "light",
-  environment?: ResolveKnobsEnvironment,
-): ResolvedKnobs {
-  const radiusToken = borderRadiusMap[knobs.borderRadius];
-  const nestedRadiusToken = nestedRadiusMap[knobs.borderRadius];
-  const sizeToken = normalizeSizeToken(environment?.sizeToken);
-  const painted = environment?.painted ?? false;
-  const nestedPx = nestedControlPx(sizeToken);
-  const nestedHitSlop = pressTargetHitSlop(nestedPx);
-  const touch = environment?.touch ?? (isTouchable || isWebTouchable);
-  const sizeRecipe = sizeRecipeForToken(sizeToken, { touch });
-  const menuRowRecipe = sizeRecipeForToken(sizeToken, { touch, family: "menuRow" });
-  const tabRecipe = sizeRecipeForToken(sizeToken, { touch, family: "tab" });
-  const scaleTokens = getActiveScaleTokens();
-  const paddingToken = spacingRoles.panelPadding;
-  const fontWeightValue = fontWeightMap[knobs.fontWeight];
-  const bodyFontValue = bodyFontMap[knobs.bodyFont] ?? "$body";
-  const motion = motionFor(knobs.animation);
-
-  const containerRadiusValue = capContainerRadius(knobs.borderRadius);
-
-  // Corner smoothing rides every radius-bearing fragment so consumers need
-  // zero edits (KNOB-TOTALITY, LC-18). Identity guard (Axiom 3 NULL +
-  // R-BINARY/R-PILL): `none` has no arc to smooth, and at `full` the
-  // uncapped token turns control-tier parts into circles/capsules whose
-  // shape is identity — squircle ends would distort them — so the
-  // raw-radius fragments only smooth the arc classes (small/medium/large).
-  // Capped container fragments stay plain arcs at every knob (the Axiom 1
-  // cap = padding px, which superellipse corners under-fill, so the cap
-  // remains a safe over-approximation) and smooth whenever a nonzero arc
-  // exists. featureSurface smooths on the same rule: `none` has no arc.
+// Corner smoothing rides every radius-bearing fragment so consumers need
+// zero edits (KNOB-TOTALITY, LC-18). Identity guard (Axiom 3 NULL +
+// R-BINARY/R-PILL): `none` has no arc to smooth, and at `full` the
+// uncapped token turns control-tier parts into circles/capsules whose
+// shape is identity — squircle ends would distort them — so the
+// raw-radius fragments only smooth the arc classes (small/medium/large).
+// Capped container fragments stay plain arcs at every knob (the Axiom 1
+// cap = padding px, which superellipse corners under-fill, so the cap
+// remains a safe over-approximation) and smooth whenever a nonzero arc
+// exists. featureSurface smooths on the same rule: `none` has no arc.
+function smoothingFor(knobs: Knobs) {
   const smoothing = cornerSmoothingStyle[knobs.cornerSmoothing ?? "round"];
-  const scaleSmoothing =
-    knobs.borderRadius === "none" || knobs.borderRadius === "full" ? undefined : smoothing;
-  const containerSmoothing = knobs.borderRadius === "none" ? undefined : smoothing;
+  const arcless = knobs.borderRadius === "none";
+  return {
+    scaleSmoothing: arcless || knobs.borderRadius === "full" ? undefined : smoothing,
+    containerSmoothing: arcless ? undefined : smoothing,
+  };
+}
 
+function edgeRulesFor(knobs: Knobs) {
   const outlined = knobs.fillStyle === "outlined";
   // LC-86 OUTLINED-HAIRLINE: outlined implies a minimum border. none on an
   // outlined control still draws the enumerated `small` stop. Chromeless
@@ -703,30 +684,22 @@ export function resolveKnobs(
   const borderWidthValue = smallEdge ? borderWidthMap.small : borderWidthMap[knobs.borderWidth];
   const edge = (color: string, width: number) =>
     smallEdge && width >= borderWidthMap.medium ? fainterEdge(color) : color;
-  const elevationToken = elevationMap[knobs.elevation];
-  const overlayElevationToken = overlayElevationMap[knobs.elevation];
-  const overlayPaintProps = elevationPaint(overlayElevationToken);
   const overlayEdgeWidth = Math.max(borderWidthValue, borderWidthMap.small);
   // LC-85's floor is the small stop, so the floored edge takes its colour too.
+  const flooredSmall = smallEdge || knobs.borderWidth === "none";
   const overlayEdge = (color: string) =>
-    (smallEdge || knobs.borderWidth === "none") && overlayEdgeWidth >= borderWidthMap.medium
-      ? fainterEdge(color)
-      : color;
-  const elevationChrome = elevationChromeFor(elevationToken);
-  const textAccentColor = textAccentColorMap[knobs.textAccent] ?? "$color";
-  // One input surface (DF-19 / Axiom 5 ONE SOURCE): Timeline's composer,
-  // RichEditor and form fields agree on what an input surface is.
-  // MPO-19 X6: `$background` not `$color2` so a surface sub-theme can move it.
-  const inputBackground = outlined ? "transparent" : "$background";
+    flooredSmall && overlayEdgeWidth >= borderWidthMap.medium ? fainterEdge(color) : color;
+  return { outlined, smallEdge, borderWidthValue, edge, overlayEdgeWidth, overlayEdge };
+}
 
+const nonEmpty = <T extends object>(obj: T): T | undefined =>
+  Object.keys(obj).length > 0 ? obj : undefined;
+
+function stateRecipesFor(knobs: Knobs) {
   const hover = resolveStateKnobs(knobs.hover);
   const press = resolveStateKnobs(knobs.press);
   const focus = resolveStateKnobs(knobs.focus);
   const focusVisible = resolveStateKnobs(knobs.focusVisible);
-
-  const nonEmpty = <T extends object>(obj: T): T | undefined =>
-    Object.keys(obj).length > 0 ? obj : undefined;
-
   // DG-STATE-01: hover/press always carry on-color state-layer fills.
   // DG-A11Y-01: focus-visible ring is always present and non-removable.
   const control: KnobRecipe<ControlStateProps> = {
@@ -747,6 +720,136 @@ export function resolveKnobs(
     focusKnobProps: nonEmpty(focus.elevation),
     focusVisibleKnobProps: nonEmpty(focusVisible.elevation),
   };
+  return { control, text, elevation };
+}
+
+function boldWeight(knobs: Knobs): { fontWeight?: "700" } {
+  return knobs.fontWeight === "bold" ? { fontWeight: "700" } : {};
+}
+
+/** LC-151 card edge width: none draws none, large its stop, else the small hairline. */
+function cardEdgeWidth(borderWidth: Knobs["borderWidth"]): number {
+  if (borderWidth === "none") return 0;
+  if (borderWidth === "large") return borderWidthMap.large;
+  return borderWidthMap.small;
+}
+
+interface SurfaceFrame {
+  painted: boolean;
+  radius: string | number;
+  smoothing: { className: string } | undefined;
+}
+
+// LC-151: a top-level card is the grouped white step ($background inside
+// the Card template) with a hairline edge and a hair of lift. Under a
+// painted ancestor it is one fill step off its parent, edge and lift off,
+// so a card on a card never stacks a second shadow (WP-c2).
+function cardSurfaceFor(
+  knobs: Knobs,
+  scheme: ColorScheme,
+  frame: SurfaceFrame & { padding: string },
+) {
+  const { painted, radius, padding, smoothing } = frame;
+  if (painted) {
+    return { backgroundColor: paintedCardFill, borderRadius: radius, padding, ...smoothing };
+  }
+  return {
+    backgroundColor: "$background",
+    borderColor:
+      knobs.borderWidth === "large" ? "$borderColor" : edgeColorAt("$borderColor", "small"),
+    borderWidth: cardEdgeWidth(knobs.borderWidth),
+    borderRadius: radius,
+    padding,
+    ...cardLiftFor(cardElevationMap[knobs.elevation], scheme),
+    ...smoothing,
+  };
+}
+
+function elevatedSurfaceFor(
+  scheme: ColorScheme,
+  frame: Omit<SurfaceFrame, "radius"> & {
+    radius: string;
+    edge: string;
+    edgeWidth: number;
+    elevationToken: SizeKey | undefined;
+  },
+) {
+  const { painted, radius, smoothing, edge, edgeWidth, elevationToken } = frame;
+  if (painted) {
+    return {
+      backgroundColor: "$background",
+      borderColor: edge,
+      borderWidth: edgeWidth,
+      borderRadius: radius,
+      elevation: undefined,
+      ...smoothing,
+    };
+  }
+  if (scheme === "dark") {
+    // Dark draws no edge at all: on iOS a transparent border on a sheet
+    // mounted under a light OS painted the light $borderColor, and it lifts
+    // by its lighter fill, as the card lift does: a black shadow on a
+    // near-black page reads as a smudge (FZ-8116).
+    return {
+      backgroundColor: surface2.fill,
+      borderColor: "transparent",
+      borderWidth: 0,
+      borderRadius: radius,
+      elevation: undefined,
+      ...smoothing,
+    };
+  }
+  // Light: an overlay fills the page's own white, so it always keeps at
+  // least the hairline, even on a chromeless preset (FZ-8116).
+  return {
+    backgroundColor: "$background",
+    borderColor: edge,
+    borderWidth: edgeWidth,
+    borderRadius: radius,
+    elevation: platformElevation(elevationToken),
+    ...elevationPaint(elevationToken),
+    ...smoothing,
+  };
+}
+
+export function resolveKnobs(
+  knobs: Knobs,
+  override?: KnobPropsOverride,
+  scheme: ColorScheme = "light",
+  environment?: ResolveKnobsEnvironment,
+): ResolvedKnobs {
+  const radiusToken = borderRadiusMap[knobs.borderRadius];
+  const nestedRadiusToken = nestedRadiusMap[knobs.borderRadius];
+  const sizeToken = normalizeSizeToken(environment?.sizeToken);
+  const painted = environment?.painted ?? false;
+  const nestedPx = nestedControlPx(sizeToken);
+  const nestedHitSlop = pressTargetHitSlop(nestedPx);
+  const touch = environment?.touch ?? (isTouchable || isWebTouchable);
+  const sizeRecipe = sizeRecipeForToken(sizeToken, { touch });
+  const menuRowRecipe = sizeRecipeForToken(sizeToken, { touch, family: "menuRow" });
+  const tabRecipe = sizeRecipeForToken(sizeToken, { touch, family: "tab" });
+  const scaleTokens = getActiveScaleTokens();
+  const paddingToken = spacingRoles.panelPadding;
+  const fontWeightValue = fontWeightMap[knobs.fontWeight];
+  const bodyFontValue = bodyFontMap[knobs.bodyFont] ?? "$body";
+  const motion = motionFor(knobs.animation);
+
+  const containerRadiusValue = capContainerRadius(knobs.borderRadius);
+
+  const { scaleSmoothing, containerSmoothing } = smoothingFor(knobs);
+  const { outlined, smallEdge, borderWidthValue, edge, overlayEdgeWidth, overlayEdge } =
+    edgeRulesFor(knobs);
+  const elevationToken = elevationMap[knobs.elevation];
+  const overlayElevationToken = overlayElevationMap[knobs.elevation];
+  const elevationChrome = elevationChromeFor(elevationToken);
+  const textAccentColor = textAccentColorMap[knobs.textAccent] ?? "$color";
+  // One input surface (DF-19 / Axiom 5 ONE SOURCE): Timeline's composer,
+  // RichEditor and form fields agree on what an input surface is.
+  // MPO-19 X6: `$background` not `$color2` so a surface sub-theme can move it.
+  const inputBackground = outlined ? "transparent" : "$background";
+
+  const { control, text, elevation } = stateRecipesFor(knobs);
+  const bold = boldWeight(knobs);
 
   const nestedRadius = { borderRadius: nestedRadiusToken, ...containerSmoothing };
 
@@ -786,52 +889,20 @@ export function resolveKnobs(
     // the Card template) with a hairline edge and a hair of lift. Under a
     // painted ancestor it is one fill step off its parent, edge and lift off,
     // so a card on a card never stacks a second shadow (WP-c2).
-    cardSurface: painted
-      ? {
-          backgroundColor: paintedCardFill,
-          borderRadius: containerRadiusValue,
-          padding: paddingToken,
-          ...containerSmoothing,
-        }
-      : {
-          backgroundColor: "$background",
-          borderColor:
-            knobs.borderWidth === "large" ? "$borderColor" : edgeColorAt("$borderColor", "small"),
-          borderWidth:
-            knobs.borderWidth === "none"
-              ? 0
-              : knobs.borderWidth === "large"
-                ? borderWidthMap.large
-                : borderWidthMap.small,
-          borderRadius: containerRadiusValue,
-          padding: paddingToken,
-          ...cardLiftFor(cardElevationMap[knobs.elevation], scheme),
-          ...containerSmoothing,
-        },
-    elevatedSurface: painted
-      ? {
-          backgroundColor: "$background",
-          borderColor: overlayEdge("$borderColor"),
-          borderWidth: overlayEdgeWidth,
-          borderRadius: radiusToken,
-          elevation: undefined,
-          ...scaleSmoothing,
-        }
-      : {
-          backgroundColor: scheme === "dark" ? surface2.fill : "$background",
-          // Light: an overlay fills the page's own white, so it always keeps at
-          // least the hairline, even on a chromeless preset (FZ-8116).
-          borderColor: scheme === "dark" ? "transparent" : overlayEdge("$borderColor"),
-          // Dark draws no edge at all: on iOS a transparent border on a sheet
-          // mounted under a light OS painted the light $borderColor (FZ-8116).
-          borderWidth: scheme === "dark" ? 0 : overlayEdgeWidth,
-          borderRadius: radiusToken,
-          elevation: scheme === "dark" ? undefined : platformElevation(overlayElevationToken),
-          // Dark lifts an overlay by its lighter fill, as the card lift does: a
-          // black shadow on a near-black page reads as a smudge (FZ-8116).
-          ...(scheme === "dark" ? undefined : overlayPaintProps),
-          ...scaleSmoothing,
-        },
+    cardSurface: cardSurfaceFor(knobs, scheme, {
+      painted,
+      radius: containerRadiusValue,
+      padding: paddingToken,
+      smoothing: containerSmoothing,
+    }),
+    elevatedSurface: elevatedSurfaceFor(scheme, {
+      painted,
+      radius: radiusToken,
+      smoothing: scaleSmoothing,
+      edge: overlayEdge("$borderColor"),
+      edgeWidth: overlayEdgeWidth,
+      elevationToken: overlayElevationToken,
+    }),
     featureSurface: {
       backgroundColor: "$background",
       borderRadius: featureRadiusMap[knobs.borderRadius],
@@ -854,7 +925,7 @@ export function resolveKnobs(
     label: {
       fontSize: labelFontSizeFor(sizeToken),
       fontFamily: bodyFontValue,
-      ...(knobs.fontWeight === "bold" ? { fontWeight: "700" } : {}),
+      ...bold,
     },
     nestedControl: {
       px: nestedPx,
@@ -896,7 +967,7 @@ export function resolveKnobs(
     },
     heading: {
       fontFamily: headingFontMap[knobs.headingFont],
-      ...(knobs.fontWeight === "bold" ? { fontWeight: "700" } : {}),
+      ...bold,
     },
     pageTitle: resolvePageTitleScale(knobs.pageTitleScale ?? "moderate"),
     textRole: resolveTextRoles(sizeToken, knobs.fontWeight === "bold"),

package/src/theme/scale/activeScale.spec.ts

@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { getActiveScaleTokens, scaleSpaceFractionPx, setActiveScaleTokens } from "./activeScale";
+import { generateScale } from "./generateScale";
+import { defaultScaleInputs } from "./scaleInputs";
+
+const original = getActiveScaleTokens();
+const defaults = generateScale(defaultScaleInputs).tokens;
+const dense = generateScale({ control: 32, type: 13 }).tokens;
+
+afterEach(() => setActiveScaleTokens(original));
+
+describe("scaleSpaceFractionPx (FZ-8018)", () => {
+  it("is plain rounding on the default scale", () => {
+    for (const key of ["$1.5", "$2.5", "$3.5", "$4.5"] as const) {
+      const px = defaults.space[key];
+      expect(scaleSpaceFractionPx(px, 0.25)).toBe(Math.round(px * 0.25));
+    }
+  });
+
+  it("paints an installed space token where the default quarter is one", () => {
+    const quarter = Math.round(defaults.space["$2.5"] * 0.25);
+    expect(new Set(Object.values(defaults.space)).has(quarter)).toBe(true);
+    setActiveScaleTokens(dense);
+    expect(getActiveScaleTokens()).toBe(dense);
+    const inset = scaleSpaceFractionPx(dense.space["$2.5"], 0.25);
+    expect(new Set(Object.values(dense.space)).has(inset)).toBe(true);
+  });
+
+  it("keeps plain rounding for a px that is no installed space value", () => {
+    setActiveScaleTokens(dense);
+    expect(scaleSpaceFractionPx(1001, 0.25)).toBe(250);
+  });
+});

package/src/theme/scale/activeScale.ts

@@ -28,3 +28,22 @@ export function scaleRadiusPx(defaultPx: number): number {
   }
   return defaultPx;
 }
+
+/**
+ * `fraction` of an installed `$space` value, as an inset on that scale. The
+ * default scale rounds the product; when that lands on a default `$space`
+ * token, every scale paints its own value at the same key, so a preset never
+ * draws a px between its tokens. A product that is no default token, or a
+ * `px` that is no installed `$space` value, keeps the plain rounding.
+ */
+export function scaleSpaceFractionPx(px: number, fraction: number): number {
+  const rounded = Math.round(px * fraction);
+  const keys = (Object.keys(activeTokens.space) as (keyof ScaleTokens["space"])[]).filter(
+    (key) => key !== "$true",
+  );
+  const key = keys.find((k) => activeTokens.space[k] === px);
+  if (key === undefined) return rounded;
+  const onDefault = Math.round(defaultTokens.space[key] * fraction);
+  const target = keys.find((k) => defaultTokens.space[k] === onDefault);
+  return target === undefined ? rounded : activeTokens.space[target];
+}

package/src/theme/scale/index.ts

@@ -51,4 +51,9 @@ export type { PublishedScale, ScaleSource } from "./useActiveScale";
 export { ScaleStyles, scaleAttributeValue, scaleStyleSheet } from "./ScaleStyles";
 export type { ScaleStylesProps } from "./ScaleStyles";
 export { scaleAttributeFromCookie, scaleAttributeScript } from "./scaleAttribute";
-export { getActiveScaleTokens, scaleRadiusPx, setActiveScaleTokens } from "./activeScale";
+export {
+  getActiveScaleTokens,
+  scaleRadiusPx,
+  scaleSpaceFractionPx,
+  setActiveScaleTokens,
+} from "./activeScale";