@multiplatform.one/theme 6.0.4 → 6.3.0

package/src/theme/devtools/knobIcons.tsx

@@ -28,6 +28,19 @@ export function sizeIcon(value: string, color: string): ReactNode {
   return <div style={{ width: 4, height: height, background: color, borderRadius: 1 }} />;
 }
 
+export function densityIcon(value: string, color: string): ReactNode {
+  // Comfortable = taller stack; compact = compressed stack.
+  const gap = value === "compact" ? 1 : 2;
+  const barH = value === "compact" ? 3 : 4;
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap, width: 14 }}>
+      <div style={{ height: barH, background: color, borderRadius: 1 }} />
+      <div style={{ height: barH, background: color, borderRadius: 1 }} />
+      <div style={{ height: barH, background: color, borderRadius: 1 }} />
+    </div>
+  );
+}
+
 export function borderRadiusIcon(value: string, color: string): ReactNode {
   const radius =
     ({ none: 0, small: 2, medium: 4, large: 7, full: 10 } as Record<string, number>)[value] ?? 0;
@@ -36,6 +49,26 @@ export function borderRadiusIcon(value: string, color: string): ReactNode {
   );
 }
 
+export function cornerSmoothingIcon(value: string, color: string): ReactNode {
+  // Same nominal corner size, different curvature: circular-arc rounded
+  // rect for `round`, continuous-curvature superellipse for `smooth`.
+  const smooth = value === "smooth";
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" role="img" aria-label={value}>
+      <title>{value}</title>
+      {smooth ? (
+        <path
+          d="M7 1 C2.8 1 1 2.8 1 7 C1 11.2 2.8 13 7 13 C11.2 13 13 11.2 13 7 C13 2.8 11.2 1 7 1 Z"
+          stroke={color}
+          strokeWidth="1.5"
+        />
+      ) : (
+        <rect x="1" y="1" width="12" height="12" rx="4" stroke={color} strokeWidth="1.5" />
+      )}
+    </svg>
+  );
+}
+
 export function borderWidthIcon(value: string, color: string): ReactNode {
   if (value === "none") {
     return (
@@ -215,3 +248,111 @@ export function modeIcon(value: "system" | "light" | "dark", color: string): Rea
   }
   return <div style={{ ...base, background: color }} />;
 }
+
+/** Compact text glyph used by house-decision knobs in the panel. */
+function glyph(label: string, color: string, size = 9): ReactNode {
+  return (
+    <span
+      style={{
+        fontSize: size,
+        fontWeight: 600,
+        color,
+        fontFamily: "system-ui, sans-serif",
+        lineHeight: 1,
+        letterSpacing: "-0.02em",
+      }}
+    >
+      {label}
+    </span>
+  );
+}
+
+export function fieldLabelPlacementIcon(value: string, color: string): ReactNode {
+  if (value === "side") return glyph("⊟", color, 12);
+  if (value === "floating") return glyph("⬚", color, 12);
+  return glyph("⊞", color, 12); // top
+}
+
+export function requiredMarkingIcon(value: string, color: string): ReactNode {
+  if (value === "asterisk") return glyph("*", color, 14);
+  if (value === "optional") return glyph("opt", color, 8);
+  return glyph("min", color, 8); // minority
+}
+
+export function tableZebraIcon(value: string, color: string): ReactNode {
+  const on = value === "on";
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 1, width: 14 }}>
+      <div style={{ height: 3, background: color, borderRadius: 1, opacity: on ? 1 : 0.35 }} />
+      <div style={{ height: 3, background: color, borderRadius: 1, opacity: on ? 0.35 : 0.35 }} />
+      <div style={{ height: 3, background: color, borderRadius: 1, opacity: on ? 1 : 0.35 }} />
+    </div>
+  );
+}
+
+export function bulkBarPlacementIcon(value: string, color: string): ReactNode {
+  const top = value !== "bottom";
+  return (
+    <div
+      style={{
+        width: 14,
+        height: 14,
+        border: `1px solid ${color}`,
+        borderRadius: 2,
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: top ? "flex-start" : "flex-end",
+        padding: 1,
+      }}
+    >
+      <div style={{ height: 3, background: color, borderRadius: 1 }} />
+    </div>
+  );
+}
+
+export function selectAllScopeIcon(value: string, color: string): ReactNode {
+  const filtered = value === "filtered";
+  // Three rows; page scope highlights only the top rows (current page),
+  // filtered scope highlights all rows (all matching).
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 1, width: 14 }}>
+      <div style={{ height: 3, background: color, borderRadius: 1 }} />
+      <div style={{ height: 3, background: color, borderRadius: 1 }} />
+      <div style={{ height: 3, background: color, borderRadius: 1, opacity: filtered ? 1 : 0.3 }} />
+    </div>
+  );
+}
+
+export function timestampStyleIcon(value: string, color: string): ReactNode {
+  return glyph(value === "relative" ? "~t" : "12:00", color, value === "relative" ? 10 : 7);
+}
+
+export function disabledStyleIcon(value: string, color: string): ReactNode {
+  if (value === "dimWhole") {
+    return (
+      <div style={{ width: 14, height: 14, background: color, borderRadius: 2, opacity: 0.35 }} />
+    );
+  }
+  // keepLabel — solid label bar over a dimmed body
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 2, width: 14 }}>
+      <div style={{ height: 3, background: color, borderRadius: 1 }} />
+      <div style={{ height: 7, background: color, borderRadius: 1, opacity: 0.3 }} />
+    </div>
+  );
+}
+
+export function formAutofocusIcon(value: string, color: string): ReactNode {
+  return (
+    <div
+      style={{
+        width: 14,
+        height: 14,
+        border: `1.5px solid ${color}`,
+        borderRadius: 2,
+        boxShadow: value === "on" ? `0 0 0 2px ${color}` : undefined,
+        opacity: value === "on" ? 1 : 0.45,
+      }}
+    />
+  );
+}

package/src/theme/devtools/vizConstants.ts

@@ -1,4 +1,4 @@
-export function luminance(rgb: string): number {
+function luminance(rgb: string): number {
   const canvas = typeof document !== "undefined" ? document.createElement("canvas") : null;
   if (!canvas) return 0.5;
   const context = canvas.getContext("2d");

package/src/theme/focusState.spec.ts

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { __resetDevWarnSeen, warnOutlineNone, warnPositiveTabIndex } from "../devWarn";
+import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+import { createThemesBuilder } from "./createThemes";
+import { defaultAccentTheme } from "./defaults/accent";
+import { defaultBaseTheme } from "./defaults/base";
+import { defaultBuilderOptions } from "./defaults/builderOptions";
+import {
+  ensureFocusVisibleRing,
+  focusRingColorMeetsContrast,
+  FOCUS_RING_MIN_CONTRAST,
+  FOCUS_RING_MIN_WIDTH,
+  FOCUS_VISIBLE_RING,
+  STATE_LAYER_HOVER,
+  STATE_LAYER_PRESS,
+  withDefaultStateLayer,
+} from "./focusState";
+import { defaultKnobs } from "./knobs";
+import { resolveKnobs } from "./resolveKnobs";
+
+describe("focusState tokens (DG-A11Y-01 / DG-STATE-01 / W12)", () => {
+  it("FOCUS_VISIBLE_RING meets ≥2px solid outline contract", () => {
+    expect(FOCUS_VISIBLE_RING.outlineWidth).toBeGreaterThanOrEqual(FOCUS_RING_MIN_WIDTH);
+    expect(FOCUS_VISIBLE_RING.outlineStyle).toBe("solid");
+    expect(FOCUS_VISIBLE_RING.outlineColor).toBe("$outlineColor");
+    expect(FOCUS_RING_MIN_CONTRAST).toBeGreaterThanOrEqual(3);
+  });
+
+  it("ensureFocusVisibleRing always emits a ≥2px solid ring", () => {
+    expect(ensureFocusVisibleRing()).toMatchObject(FOCUS_VISIBLE_RING);
+    expect(ensureFocusVisibleRing({})).toMatchObject(FOCUS_VISIBLE_RING);
+  });
+
+  it("ensureFocusVisibleRing clamps outlineWidth < 2 and rejects outline:none", () => {
+    const clamped = ensureFocusVisibleRing({
+      outlineWidth: 0,
+      outlineStyle: "none",
+      outlineColor: "transparent",
+      borderWidth: 1,
+    });
+    expect(clamped.outlineWidth).toBe(FOCUS_RING_MIN_WIDTH);
+    expect(clamped.outlineStyle).toBe("solid");
+    expect(clamped.outlineColor).toBe("$outlineColor");
+    expect(clamped.borderWidth).toBe(1);
+  });
+
+  it("ensureFocusVisibleRing allows thicker rings and preserves extras", () => {
+    const thick = ensureFocusVisibleRing({
+      outlineWidth: 4,
+      borderColor: "$borderColorFocus",
+    } as { outlineWidth: number; borderColor: string });
+    expect(thick.outlineWidth).toBe(4);
+    expect(thick.borderColor).toBe("$borderColorFocus");
+  });
+
+  it("ensureFocusVisibleRing reverts alpha-carrying ring colors (DF-03)", () => {
+    // The stock Tamagui ring (20%-alpha ink) can't guarantee ≥3:1.
+    for (const outlineColor of ["rgba(36, 34, 38, 0.2)", "hsla(270, 6%, 14%, 0.2)", "#2422260a"]) {
+      expect(
+        ensureFocusVisibleRing({ outlineColor } as { outlineColor: string }).outlineColor,
+      ).toBe(FOCUS_VISIBLE_RING.outlineColor);
+    }
+    // A solid override is respected.
+    expect(
+      ensureFocusVisibleRing({ outlineColor: "#5b5563" } as { outlineColor: string }).outlineColor,
+    ).toBe("#5b5563");
+  });
+
+  it("focusRingColorMeetsContrast enforces the ≥3:1 color floor", () => {
+    expect(focusRingColorMeetsContrast("#767085", "#ffffff")).toBe(true);
+    expect(focusRingColorMeetsContrast("#e6e4e7", "#ffffff")).toBe(false);
+    // Alpha colors can't be reduced to a single hue → treated as failing.
+    expect(focusRingColorMeetsContrast("rgba(36,34,38,0.2)", "#ffffff")).toBe(false);
+  });
+
+  it("withDefaultStateLayer fills background when unset; knob wins when set", () => {
+    expect(withDefaultStateLayer({}, STATE_LAYER_HOVER)).toEqual(STATE_LAYER_HOVER);
+    expect(withDefaultStateLayer({ borderWidth: 2 }, STATE_LAYER_PRESS)).toEqual({
+      backgroundColor: "$backgroundPress",
+      borderWidth: 2,
+    });
+    expect(withDefaultStateLayer({ backgroundColor: "transparent" }, STATE_LAYER_HOVER)).toEqual({
+      backgroundColor: "transparent",
+    });
+  });
+});
+
+describe("$outlineColor token contrast (DF-03 / DG-A11Y-01)", () => {
+  const themes = createThemesBuilder(
+    defaultBaseTheme,
+    defaultAccentTheme,
+    defaultBuilderOptions,
+  ).themes() as Record<string, Record<string, string>>;
+
+  for (const scheme of ["light", "dark"] as const) {
+    it(`${scheme} $outlineColor clears ≥3:1 against color1 and color2`, () => {
+      const theme = themes[scheme];
+      expect(theme).toBeTruthy();
+      const ring = normalizeToHex(theme.outlineColor);
+      const bg1 = normalizeToHex(theme.color1);
+      const bg2 = normalizeToHex(theme.color2);
+      expect(ring).toBeTruthy();
+      expect(bg1).toBeTruthy();
+      expect(bg2).toBeTruthy();
+      const c1 = contrastRatio(relativeLuminance(ring!), relativeLuminance(bg1!));
+      const c2 = contrastRatio(relativeLuminance(ring!), relativeLuminance(bg2!));
+      expect(Math.min(c1, c2)).toBeGreaterThanOrEqual(FOCUS_RING_MIN_CONTRAST);
+    });
+  }
+});
+
+describe("resolveKnobs control recipes (W12)", () => {
+  it("always emits hover/press state layers and focus-visible ring", () => {
+    const { control } = resolveKnobs(defaultKnobs);
+    expect(control.hoverKnobProps).toEqual(STATE_LAYER_HOVER);
+    expect(control.pressKnobProps).toEqual(STATE_LAYER_PRESS);
+    expect(control.focusVisibleKnobProps).toMatchObject(FOCUS_VISIBLE_RING);
+    expect(control.focusVisibleKnobProps?.outlineWidth).toBeGreaterThanOrEqual(2);
+  });
+
+  it("merges knob overrides without removing the focus-visible ring", () => {
+    const { control } = resolveKnobs({
+      ...defaultKnobs,
+      focusVisible: { borderWidth: "large", borderRadius: "full" },
+      hover: { borderWidth: "large" },
+      press: { fillStyle: "outlined" },
+    });
+    expect(control.focusVisibleKnobProps).toMatchObject({
+      ...FOCUS_VISIBLE_RING,
+      borderWidth: 2,
+      borderRadius: "$12",
+    });
+    expect(control.hoverKnobProps).toMatchObject({
+      backgroundColor: "$backgroundHover",
+      borderWidth: 2,
+    });
+    expect(control.pressKnobProps?.backgroundColor).toBe("transparent");
+  });
+});
+
+describe("theme DEV warn (outline-none / positive-tabindex)", () => {
+  afterEach(() => {
+    __resetDevWarnSeen();
+    vi.restoreAllMocks();
+  });
+
+  it("warnOutlineNone fires once for outline:none / width 0", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    warnOutlineNone({ outlineStyle: "none" }, { component: "Test" });
+    warnOutlineNone({ outlineStyle: "none" }, { component: "Test" });
+    warnOutlineNone({ outlineWidth: 0 }, { component: "Other" });
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("outline-none"));
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it("warnOutlineNone ignores healthy focus rings", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    warnOutlineNone(FOCUS_VISIBLE_RING, { component: "Test" });
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("warnPositiveTabIndex fires for tabIndex > 0 only", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    warnPositiveTabIndex({ value: 0, component: "Test" });
+    warnPositiveTabIndex({ value: -1, component: "Test" });
+    warnPositiveTabIndex({ value: undefined, component: "Test" });
+    expect(spy).not.toHaveBeenCalled();
+    warnPositiveTabIndex({ value: 2, component: "Test" });
+    warnPositiveTabIndex({ value: 2, component: "Test" });
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("positive-tabindex"));
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("value=2"));
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/theme/focusState.ts

@@ -0,0 +1,112 @@
+import { contrastRatio, normalizeToHex, relativeLuminance } from "./colorRules";
+import type { ControlStateProps } from "./recipes";
+
+/**
+ * DG-A11Y-01 — keyboard focus-visible ring.
+ * Width ≥2px; color is the theme `$outlineColor` token (scheme-aware, ≥3:1
+ * against adjacent surface in both light and dark).
+ */
+export const FOCUS_RING_MIN_WIDTH = 2;
+export const FOCUS_RING_MIN_CONTRAST = 3;
+
+/**
+ * True when a CSS color carries alpha < 1 (rgba/hsla/#rrggbbaa). Such a ring
+ * cannot guarantee the ≥3:1 floor — its effective contrast depends on the
+ * backdrop it composites over (this is exactly how the stock Tamagui ring,
+ * `rgba(ink, 0.2)`, dropped to 1.36:1). The guard reverts these to the solid
+ * `$outlineColor` token.
+ */
+function ringColorCarriesAlpha(color: string): boolean {
+  const s = color.trim().toLowerCase();
+  const fn = s.match(/^(?:rgba|hsla)\([^)]*[,/]\s*([\d.]+%?)\s*\)$/);
+  if (fn) {
+    const raw = fn[1];
+    const a = raw.endsWith("%") ? Number.parseFloat(raw) / 100 : Number.parseFloat(raw);
+    return Number.isFinite(a) && a < 0.999;
+  }
+  if (/^#[0-9a-f]{8}$/.test(s)) {
+    return Number.parseInt(s.slice(7, 9), 16) / 255 < 0.999;
+  }
+  return false;
+}
+
+/**
+ * VERIFY helper (DG-A11Y-01 / Axiom 12): does a *resolved* ring color clear
+ * the ≥3:1 contrast floor against a given surface? Both args are CSS color
+ * strings (hex/hsl/named). Returns false when either can't be parsed (e.g. an
+ * alpha-blended color that can't be reduced to a single hue) so callers treat
+ * unresolved rings as failing.
+ */
+export function focusRingColorMeetsContrast(ringColor: string, surfaceColor: string): boolean {
+  const ring = normalizeToHex(ringColor);
+  const surface = normalizeToHex(surfaceColor);
+  if (!ring || !surface) return false;
+  return (
+    contrastRatio(relativeLuminance(ring), relativeLuminance(surface)) >= FOCUS_RING_MIN_CONTRAST
+  );
+}
+
+export const FOCUS_VISIBLE_RING = {
+  outlineWidth: FOCUS_RING_MIN_WIDTH,
+  outlineStyle: "solid" as const,
+  outlineColor: "$outlineColor",
+  outlineOffset: 2,
+} satisfies ControlStateProps;
+
+/**
+ * DG-STATE-01 — Material-style state layers as theme tokens.
+ * Ramp lives in `defaults/builderOptions` (hover/press background steps);
+ * recipes overlay those tokens rather than inventing a second channel.
+ */
+export const STATE_LAYER_HOVER = {
+  backgroundColor: "$backgroundHover",
+} satisfies ControlStateProps;
+
+export const STATE_LAYER_PRESS = {
+  backgroundColor: "$backgroundPress",
+} satisfies ControlStateProps;
+
+/**
+ * Merge + clamp so variants/knobs cannot remove the focus-visible ring.
+ * Transparent / none / sub-2px outlines are restored to the baseline token.
+ * Extra style keys (e.g. `borderColor`) are preserved for consumer merges.
+ */
+export function ensureFocusVisibleRing<T extends ControlStateProps>(
+  override?: (T & ControlStateProps) | null,
+): T & ControlStateProps {
+  const merged = {
+    ...FOCUS_VISIBLE_RING,
+    ...override,
+  } as T & ControlStateProps;
+  const width =
+    typeof merged.outlineWidth === "number" ? merged.outlineWidth : FOCUS_RING_MIN_WIDTH;
+  merged.outlineWidth = Math.max(width, FOCUS_RING_MIN_WIDTH);
+  if (merged.outlineStyle !== "solid") {
+    merged.outlineStyle = "solid";
+  }
+  if (
+    !merged.outlineColor ||
+    merged.outlineColor === "transparent" ||
+    merged.outlineColor === "none" ||
+    // Enforce COLOR, not just shape: an alpha-carrying ring can't guarantee
+    // ≥3:1 (its contrast depends on the backdrop), so restore the solid token.
+    (typeof merged.outlineColor === "string" && ringColorCarriesAlpha(merged.outlineColor))
+  ) {
+    merged.outlineColor = FOCUS_VISIBLE_RING.outlineColor;
+  }
+  if (typeof merged.outlineOffset !== "number") {
+    merged.outlineOffset = FOCUS_VISIBLE_RING.outlineOffset;
+  }
+  return merged;
+}
+
+/** Apply default hover/press state-layer fill when knobs left background unset. */
+export function withDefaultStateLayer(
+  control: ControlStateProps,
+  layer: ControlStateProps,
+): ControlStateProps {
+  if (control.backgroundColor !== undefined) {
+    return control;
+  }
+  return { ...layer, ...control };
+}

package/src/theme/fontKnobStyles.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import type { FontScopeTables } from "./FontKnobStyles";
+import { buildFontKnobCss, fontCategoryMetrics } from "./FontKnobStyles";
+import type { FontCategory } from "./knobs";
+
+const FAMILIES: Partial<Record<FontCategory, string>> = {
+  slab: "'Roboto Slab', 'Rockwell', 'Courier New', serif",
+  mono: "monospace",
+  blackletter: "'UnifrakturCook', 'Fraktur', serif",
+};
+
+const resolveFamily = (category: FontCategory) => FAMILIES[category];
+const noTables = () => undefined;
+
+// Inter-shaped tables: display sizes tight (~1.16), small sizes loose, and
+// negative display tracking — the exact shape the floors exist to correct.
+const TABLES: Record<"heading" | "body", FontScopeTables> = {
+  heading: {
+    size: { 7: 28, 10: 64 },
+    lineHeight: { 7: 38, 10: 74 },
+    letterSpacing: { 7: 0, 10: -3 },
+  },
+  body: {
+    size: { 4: 14, 10: 46 },
+    lineHeight: { 4: 24, 10: 56 },
+    // positive caption tracking (tracking-by-size curve) + negative display
+    letterSpacing: { 1: 0.05, 10: -3 },
+  },
+};
+const resolveTables = (scope: "heading" | "body") => TABLES[scope];
+
+describe("buildFontKnobCss", () => {
+  it("emits only zero-specificity default leading when both knobs are at the sans-serif default (LC-11)", () => {
+    const css = buildFontKnobCss("sans-serif", "sans-serif", resolveFamily, noTables);
+    expect(css).toContain(":where(:root .font_heading) { line-height: 1.25; }");
+    expect(css).toContain(":where(:root .font_body) { line-height: 1.5; }");
+    expect(css).not.toContain("--f-family");
+  });
+
+  it("overrides the heading font scope for a non-default headingFont", () => {
+    const css = buildFontKnobCss("slab", "sans-serif", resolveFamily, noTables);
+    expect(css).toContain(
+      ":root .font_heading { --f-family: 'Roboto Slab', 'Rockwell', 'Courier New', serif !important; }",
+    );
+  });
+
+  it("overrides the body font scope for a non-default bodyFont", () => {
+    const css = buildFontKnobCss("sans-serif", "mono", resolveFamily, noTables);
+    expect(css).toContain(":root .font_body { --f-family: monospace !important; }");
+  });
+
+  it("overrides both scopes independently", () => {
+    const css = buildFontKnobCss("blackletter", "mono", resolveFamily, noTables);
+    expect(css).toContain("--f-family: 'UnifrakturCook', 'Fraktur', serif !important");
+    expect(css).toContain(":root .font_body { --f-family: monospace !important");
+  });
+
+  it("skips the family override for unregistered fonts but keeps the category's default leading", () => {
+    const css = buildFontKnobCss("cursive", "cursive", resolveFamily, noTables);
+    expect(css).not.toContain("--f-family");
+    // cursive heading floor 1.3 beats the 1.25 minimum; body max(1.5, 1.5)
+    expect(css).toContain(":where(:root .font_heading) { line-height: 1.3; }");
+    expect(css).toContain(":where(:root .font_body) { line-height: 1.5; }");
+  });
+
+  it("lifts heading lineHeight to the category floor only where base leading is tighter", () => {
+    // mono heading floor 1.25: $10 base 74/64 = 1.16 -> 80px; $7 base 38/28 = 1.36 -> untouched
+    const css = buildFontKnobCss("mono", "sans-serif", resolveFamily, resolveTables);
+    expect(css).toContain("--f-lineHeight-10: 80px !important");
+    expect(css).not.toContain("--f-lineHeight-7");
+  });
+
+  it("lifts body lineHeight to the body floor for large sizes", () => {
+    // mono body floor 1.45: $10 base 56/46 = 1.22 -> 67px; $4 base 24/14 = 1.71 -> untouched
+    const css = buildFontKnobCss("sans-serif", "mono", resolveFamily, resolveTables);
+    expect(css).toContain("--f-lineHeight-10: 67px !important");
+    expect(css).not.toContain("--f-lineHeight-4");
+  });
+
+  it("zeroes all non-zero tracking for neutral-tracking categories only (LC-11)", () => {
+    const mono = buildFontKnobCss("mono", "sans-serif", resolveFamily, resolveTables);
+    expect(mono).toContain("--f-letterSpacing-10: 0px !important");
+    expect(mono).not.toContain("--f-letterSpacing-7"); // base 0 stays
+    // positive caption tracking is also Inter-specific: neutral zeroes it too
+    const monoBody = buildFontKnobCss("sans-serif", "mono", resolveFamily, resolveTables);
+    expect(monoBody).toContain("--f-letterSpacing-1: 0px !important");
+    expect(monoBody).toContain("--f-letterSpacing-10: 0px !important");
+    const slab = buildFontKnobCss("slab", "sans-serif", resolveFamily, resolveTables);
+    expect(slab).not.toContain("--f-letterSpacing"); // "inherit" tracking
+  });
+
+  it("keeps every category's heading floor at or above 1.15 and body at or above 1.4", () => {
+    for (const metrics of Object.values(fontCategoryMetrics)) {
+      expect(metrics.heading).toBeGreaterThanOrEqual(1.15);
+      expect(metrics.body).toBeGreaterThanOrEqual(1.4);
+    }
+  });
+});

package/src/theme/hairline.native.ts

@@ -0,0 +1,43 @@
+/**
+ * OPTICS hairline (Axiom 15) — native twin of `hairline.ts`.
+ *
+ * React Native's StyleSheet.hairlineWidth already resolves to one device
+ * pixel for the current screen density (e.g. 1/3 on 3x, 1/2 on 2x), so no
+ * fallback plumbing is needed; `className` entries are omitted (web-only).
+ */
+import { StyleSheet } from "react-native";
+
+/** Divider line width: one device pixel for the current screen density. */
+export const hairlineWidth: number = StyleSheet.hairlineWidth;
+
+/** Spreadable divider treatments — see `hairline.ts` for usage. */
+export const hairline = {
+  /** Standalone horizontal rule as a filled hairline-height line. */
+  line: {
+    height: hairlineWidth,
+    maxHeight: hairlineWidth,
+    flexBasis: hairlineWidth,
+    borderBottomWidth: 0,
+    backgroundColor: "$borderColor",
+  },
+  /** Standalone vertical rule as a filled hairline-width line. */
+  vline: {
+    width: hairlineWidth,
+    maxWidth: hairlineWidth,
+    flexBasis: hairlineWidth,
+    borderRightWidth: 0,
+    backgroundColor: "$borderColor",
+  },
+  /** Already-filled 1px line elements (e.g. menu separator views). */
+  height: { height: hairlineWidth },
+  bottom: { borderBottomWidth: hairlineWidth },
+  top: { borderTopWidth: hairlineWidth },
+  right: { borderRightWidth: hairlineWidth },
+  left: { borderLeftWidth: hairlineWidth },
+} as const;
+
+/** Web-only fallback stylesheet — no-op on native. */
+export const hairlineFallbackCss = "";
+
+/** Web-only fallback mount — no-op on native. */
+export function ensureHairlineFallback(): void {}

package/src/theme/hairline.spec.ts

@@ -0,0 +1,63 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { ensureHairlineFallback, hairline, hairlineFallbackCss, hairlineWidth } from "./hairline";
+
+describe("hairline (Axiom 15 OPTICS)", () => {
+  it("resolves half a CSS pixel on web", () => {
+    expect(hairlineWidth).toBe(0.5);
+  });
+
+  it("renders standalone rules as filled fractional-size lines (Blink floors sub-1px borders)", () => {
+    expect(hairline.line).toEqual({
+      height: 0.5,
+      maxHeight: 0.5,
+      flexBasis: 0.5,
+      borderBottomWidth: 0,
+      backgroundColor: "$borderColor",
+      className: "mp-hairline-h",
+    });
+    expect(hairline.vline).toEqual({
+      width: 0.5,
+      maxWidth: 0.5,
+      flexBasis: 0.5,
+      borderRightWidth: 0,
+      backgroundColor: "$borderColor",
+      className: "mp-hairline-w",
+    });
+    expect(hairline.height).toEqual({ height: 0.5, className: "mp-hairline-h" });
+  });
+
+  it("pairs each edge treatment with its low-DPI fallback class", () => {
+    expect(hairline.bottom).toEqual({ borderBottomWidth: 0.5, className: "mp-hairline-b" });
+    expect(hairline.top).toEqual({ borderTopWidth: 0.5, className: "mp-hairline-t" });
+    expect(hairline.right).toEqual({ borderRightWidth: 0.5, className: "mp-hairline-r" });
+    expect(hairline.left).toEqual({ borderLeftWidth: 0.5, className: "mp-hairline-l" });
+  });
+
+  it("falls back to 1px through a resolution media query on low-DPI screens", () => {
+    expect(hairlineFallbackCss).toMatch(/@media \(max-resolution: 1\.49dppx\)/);
+    // every fallback class resolves a full CSS pixel
+    for (const cls of ["b", "t", "r", "l", "h", "w", "ie"]) {
+      expect(hairlineFallbackCss).toContain(`.mp-hairline-${cls}`);
+    }
+    expect(hairlineFallbackCss).toContain("border-bottom-width: 1px !important");
+    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");
+  });
+
+  describe("fallback stylesheet mount", () => {
+    beforeEach(() => {
+      document.getElementById("mp-hairline-styles")?.remove();
+    });
+
+    it("mounts the fallback stylesheet once (idempotent)", () => {
+      ensureHairlineFallback();
+      ensureHairlineFallback();
+      const tags = document.querySelectorAll("#mp-hairline-styles");
+      expect(tags).toHaveLength(1);
+      expect(tags[0]?.textContent).toBe(hairlineFallbackCss);
+    });
+  });
+});