@multiplatform.one/theme 6.1.0 → 6.3.0

package/src/theme/resolveKnobs.spec.ts

@@ -1,8 +1,25 @@
-import { describe, expect, it } from "vitest";
-import { defaultKnobs, emptyStateKnobs, Space, Size } from "./knobs";
+import { describe, expect, it, vi } from "vitest";
+import {
+  defaultKnobs,
+  emptyStateKnobs,
+  Space,
+  Size,
+  Density,
+  CornerSmoothing,
+  FieldLabelPlacement,
+  RequiredMarking,
+  TableZebra,
+  BulkBarPlacement,
+  SelectAllScope,
+  TimestampStyle,
+  DisabledStyle,
+  FormAutofocus,
+} from "./knobs";
 import type { Knobs } from "./knobs";
 import type { KnobProps } from "./recipes";
-import { resolveKnobs } from "./resolveKnobs";
+import { cornerSmoothClassName } from "./cornerSmoothing";
+import { defaultPreset, boldPreset } from "./presets";
+import { applyDensity, capContainerRadius, resolveKnobs } from "./resolveKnobs";
 import {
   normalizeToHex,
   relativeLuminance,
@@ -18,8 +35,12 @@ function knobsWith(overrides: Partial<Knobs>): Knobs {
 const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "borderRadius",
   "borderRadiusOuter",
+  "containerRadius",
   "elevation",
   "surface",
+  "cardSurface",
+  "elevatedSurface",
+  "featureSurface",
   "inputSurface",
   "panelPadding",
   "gap",
@@ -36,6 +57,15 @@ const expectedKnobPropKeys: (keyof KnobProps)[] = [
   "inputBackground",
   "space",
   "size",
+  "density",
+  "fieldLabelPlacement",
+  "requiredMarking",
+  "tableZebra",
+  "bulkBarPlacement",
+  "selectAllScope",
+  "timestampStyle",
+  "disabledStyle",
+  "formAutofocus",
 ];
 
 // ── colorRules unit tests ────────────────────────────────────
@@ -190,6 +220,33 @@ describe("resolveKnobs", () => {
     });
   });
 
+  // ── elevation on NATIVE (SB-N-04) ──────────────────────────
+  // Android's RCTView `elevation` prop is a Double; a token string reaching a
+  // plain RN View kills the ReactHost. Native must emit the numeric
+  // tokens.size values Tamagui would resolve those tokens to.
+
+  describe("elevation knob (native)", () => {
+    it("emits RN-safe numbers, never token strings", async () => {
+      vi.resetModules();
+      vi.doMock("@multiplatform.one/platform", () => ({ isWeb: false }));
+      const { resolveKnobs: resolveNative } = await import("./resolveKnobs");
+      try {
+        expect(resolveNative(knobsWith({ elevation: "none" })).knobProps.elevation).toBeUndefined();
+        const small = resolveNative(
+          knobsWith({ elevation: "small", hover: { elevation: "medium" } }),
+        );
+        expect(small.knobProps.elevation).toBe(20);
+        expect(small.knobProps.elevatedSurface.elevation).toBe(20);
+        expect(small.elevation.hoverKnobProps?.elevation).toBe(28);
+        expect(resolveNative(knobsWith({ elevation: "medium" })).knobProps.elevation).toBe(28);
+        expect(resolveNative(knobsWith({ elevation: "large" })).knobProps.elevation).toBe(44);
+      } finally {
+        vi.doUnmock("@multiplatform.one/platform");
+        vi.resetModules();
+      }
+    });
+  });
+
   // ── interaction state overrides ──────────────────────────────
 
   describe("interaction state overrides", () => {
@@ -213,12 +270,16 @@ describe("resolveKnobs", () => {
       expect(control.hoverKnobProps?.borderRadius).toBe("$12");
     });
 
-    it("empty state overrides produce undefined", () => {
+    it("empty state knobs still emit default hover/press layers + focus ring (W12)", () => {
       const { control } = resolveKnobs(defaultKnobs);
-      expect(control.hoverKnobProps).toBeUndefined();
-      expect(control.pressKnobProps).toBeUndefined();
+      expect(control.hoverKnobProps).toEqual({ backgroundColor: "$backgroundHover" });
+      expect(control.pressKnobProps).toEqual({ backgroundColor: "$backgroundPress" });
       expect(control.focusKnobProps).toBeUndefined();
-      expect(control.focusVisibleKnobProps).toBeUndefined();
+      expect(control.focusVisibleKnobProps).toMatchObject({
+        outlineWidth: 2,
+        outlineStyle: "solid",
+        outlineColor: "$outlineColor",
+      });
     });
 
     it("focus.elevation maps to elevation.focusKnobProps.elevation", () => {
@@ -240,9 +301,9 @@ describe("resolveKnobs", () => {
       expect(knobProps.panelPadding.padding).toBe("$3");
     });
 
-    it('maps gap "large" → "$4"', () => {
+    it('maps gap "large" → "$5"', () => {
       const { knobProps } = resolveKnobs(knobsWith({ space: "large" }));
-      expect(knobProps.gap.gap).toBe("$4");
+      expect(knobProps.gap.gap).toBe("$5");
     });
 
     it("passes space value through to knobProps", () => {
@@ -262,10 +323,10 @@ describe("resolveKnobs", () => {
       expect(knobProps.panelPadding.padding).toBe("$3");
     });
 
-    // T2.1c — space "large" still maps gapLg → "$5" regardless of size
-    it('space "large" maps gapLg → "$5" regardless of size', () => {
+    // T2.1c — space "large" still maps gapLg → "$6" regardless of size
+    it('space "large" maps gapLg → "$6" regardless of size', () => {
       const { knobProps } = resolveKnobs(knobsWith({ space: "large", size: "small" }));
-      expect(knobProps.gapLg.gap).toBe("$5");
+      expect(knobProps.gapLg.gap).toBe("$6");
     });
   });
 
@@ -314,9 +375,256 @@ describe("resolveKnobs", () => {
     it("default knobs (size+space both medium) produce consistent output", () => {
       const resolved = resolveKnobs(defaultKnobs);
       expect(resolved.knobProps.sizeToken).toBe("$4");
-      expect(resolved.knobProps.gap.gap).toBe("$3");
+      expect(resolved.knobProps.gap.gap).toBe("$4");
       expect(resolved.knobProps.panelPadding.padding).toBe("$4");
-      expect(resolved.knobProps.gapLg.gap).toBe("$4");
+      expect(resolved.knobProps.gapLg.gap).toBe("$5");
+    });
+  });
+
+  // ── surface tiers ─────────────────────────────────────────
+
+  describe("surface tier recipes", () => {
+    it("cardSurface = bg + radius + panelPadding, no border/shadow", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      expect(knobProps.cardSurface).toEqual({
+        backgroundColor: "$color1",
+        borderRadius: "$4",
+        padding: "$4",
+      });
+      expect(knobProps.cardSurface).not.toHaveProperty("borderWidth");
+      expect(knobProps.cardSurface).not.toHaveProperty("elevation");
+    });
+
+    it("cardSurface tracks borderRadius and space knobs (cap bites: large radius 16px > small padding 13px)", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "large", space: "small" }));
+      expect(knobProps.cardSurface.borderRadius).toBe(13);
+      expect(knobProps.cardSurface.padding).toBe("$3");
+    });
+
+    it("cardSurface keeps the radius token while it fits the padding", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "large", space: "medium" }));
+      expect(knobProps.cardSurface.borderRadius).toBe("$6");
+    });
+
+    it("elevatedSurface = surface + radius + elevation", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      expect(knobProps.elevatedSurface).toEqual({
+        ...knobProps.surface,
+        borderRadius: knobProps.borderRadius.borderRadius,
+        elevation: knobProps.elevation,
+      });
+    });
+
+    it("featureSurface uses big radius, $6 padding, and an ultra-soft shadow", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      expect(knobProps.featureSurface.borderRadius).toBe("$10");
+      expect(knobProps.featureSurface.padding).toBe("$6");
+      expect(knobProps.featureSurface.shadowOffset).toEqual({ width: 0, height: 9 });
+      expect(knobProps.featureSurface.shadowRadius).toBe(12);
+      expect(knobProps.featureSurface).not.toHaveProperty("borderWidth");
+    });
+  });
+
+  // ── container radius cap (Axiom 1 CLIP) ──────────────────
+
+  describe("containerRadius (Axiom 1 child-clip cap)", () => {
+    it("default knobs are untouched (radius $4 = 9px fits medium padding 18px)", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      expect(knobProps.containerRadius).toEqual({ borderRadius: "$4" });
+      expect(knobProps.cardSurface.borderRadius).toBe("$4");
+    });
+
+    it("caps full radius at the padding px for every space", () => {
+      expect(
+        resolveKnobs(knobsWith({ borderRadius: "full", space: "small" })).knobProps.containerRadius
+          .borderRadius,
+      ).toBe(13);
+      expect(
+        resolveKnobs(knobsWith({ borderRadius: "full", space: "medium" })).knobProps.containerRadius
+          .borderRadius,
+      ).toBe(18);
+      expect(
+        resolveKnobs(knobsWith({ borderRadius: "full", space: "large" })).knobProps.containerRadius
+          .borderRadius,
+      ).toBe(32);
+    });
+
+    it("only bites at large/full: none/small/medium keep their token at every space", () => {
+      for (const space of Object.values(Space)) {
+        for (const [radius, token] of [
+          ["none", "$0"],
+          ["small", "$2"],
+          ["medium", "$4"],
+        ] as const) {
+          const { knobProps } = resolveKnobs(knobsWith({ borderRadius: radius, space }));
+          expect(knobProps.containerRadius.borderRadius).toBe(token);
+        }
+      }
+    });
+
+    it("large radius caps only under small space (16px > 13px)", () => {
+      expect(
+        resolveKnobs(knobsWith({ borderRadius: "large", space: "small" })).knobProps.containerRadius
+          .borderRadius,
+      ).toBe(13);
+      expect(
+        resolveKnobs(knobsWith({ borderRadius: "large", space: "medium" })).knobProps
+          .containerRadius.borderRadius,
+      ).toBe("$6");
+      expect(
+        resolveKnobs(knobsWith({ borderRadius: "large", space: "large" })).knobProps.containerRadius
+          .borderRadius,
+      ).toBe("$6");
+    });
+
+    it("mirrored px values agree with the live @tamagui/themes tokens (drift guard)", async () => {
+      const { tokens } = await import("@tamagui/themes");
+      const radiusTokenByKnob = {
+        none: "$0",
+        small: "$2",
+        medium: "$4",
+        large: "$6",
+        full: "$12",
+      } as const;
+      const paddingTokenByKnob = { small: "$3", medium: "$4", large: "$6" } as const;
+      for (const [radiusKnob, radiusToken] of Object.entries(radiusTokenByKnob)) {
+        for (const [spaceKnob, paddingToken] of Object.entries(paddingTokenByKnob)) {
+          const radiusPx = (tokens.radius as any)[radiusToken.slice(1)].val as number;
+          const paddingPx = (tokens.space as any)[paddingToken.slice(1)].val as number;
+          const expected = radiusPx > paddingPx ? paddingPx : radiusToken;
+          expect(
+            capContainerRadius(radiusKnob as Knobs["borderRadius"], spaceKnob as Knobs["space"]),
+            `radius=${radiusKnob} space=${spaceKnob}`,
+          ).toBe(expected);
+        }
+      }
+    });
+  });
+
+  // ── cornerSmoothing (Axiom 15 OPTICS) ─────────────────────
+
+  describe("cornerSmoothing knob", () => {
+    const radiusFragments = [
+      "borderRadius",
+      "borderRadiusOuter",
+      "containerRadius",
+      "cardSurface",
+      "elevatedSurface",
+      "featureSurface",
+    ] as const;
+
+    it('defaults to "round" and emits no class on any fragment', () => {
+      expect(defaultKnobs.cornerSmoothing).toBe(CornerSmoothing.Round);
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      for (const fragment of radiusFragments) {
+        expect(knobProps[fragment], fragment).not.toHaveProperty("className");
+      }
+    });
+
+    it('treats an absent knob as "round" (optional key, older presets)', () => {
+      const { cornerSmoothing: _omit, ...withoutKnob } = defaultKnobs;
+      const { knobProps } = resolveKnobs(withoutKnob as Knobs);
+      for (const fragment of radiusFragments) {
+        expect(knobProps[fragment], fragment).not.toHaveProperty("className");
+      }
+    });
+
+    it("smooth × arc classes (small/medium/large): every radius-bearing fragment carries the class", () => {
+      for (const radius of ["small", "medium", "large"] as const) {
+        const { knobProps } = resolveKnobs(
+          knobsWith({ cornerSmoothing: "smooth", borderRadius: radius }),
+        );
+        for (const fragment of radiusFragments) {
+          expect(knobProps[fragment].className, `${radius}/${fragment}`).toBe(
+            cornerSmoothClassName,
+          );
+        }
+      }
+    });
+
+    it("smooth × none: nothing to smooth except the fixed-radius featureSurface", () => {
+      const { knobProps } = resolveKnobs(
+        knobsWith({ cornerSmoothing: "smooth", borderRadius: "none" }),
+      );
+      // $0 corners have no arc — square world stays square (Axiom 3 NULL).
+      expect(knobProps.borderRadius).not.toHaveProperty("className");
+      expect(knobProps.borderRadiusOuter).not.toHaveProperty("className");
+      expect(knobProps.containerRadius).not.toHaveProperty("className");
+      expect(knobProps.cardSurface).not.toHaveProperty("className");
+      expect(knobProps.elevatedSurface).not.toHaveProperty("className");
+      // featureSurface's radius is fixed ($10, knob-independent) — its arc
+      // exists at every knob value, so it smooths.
+      expect(knobProps.featureSurface.className).toBe(cornerSmoothClassName);
+    });
+
+    it("smooth × full: pill/circle identity fragments ignore smoothing (R-BINARY/R-PILL)", () => {
+      const { knobProps } = resolveKnobs(
+        knobsWith({ cornerSmoothing: "smooth", borderRadius: "full" }),
+      );
+      // Uncapped $12 turns control-tier parts into capsules/circles —
+      // identity shapes that squircle ends would distort.
+      expect(knobProps.borderRadius).not.toHaveProperty("className");
+      expect(knobProps.elevatedSurface).not.toHaveProperty("className");
+      // Capped/outer fragments stay plain arcs (cap = padding px, outer ≤ $5)
+      // and keep smoothing.
+      expect(knobProps.borderRadiusOuter.className).toBe(cornerSmoothClassName);
+      expect(knobProps.containerRadius.className).toBe(cornerSmoothClassName);
+      expect(knobProps.cardSurface.className).toBe(cornerSmoothClassName);
+      expect(knobProps.featureSurface.className).toBe(cornerSmoothClassName);
+    });
+
+    it("smooth keeps the Axiom 1 container cap (clamped radii keep their caps)", () => {
+      const smooth = resolveKnobs(
+        knobsWith({ cornerSmoothing: "smooth", borderRadius: "full", space: "small" }),
+      );
+      const round = resolveKnobs(knobsWith({ borderRadius: "full", space: "small" }));
+      expect(smooth.knobProps.containerRadius.borderRadius).toBe(13);
+      expect(round.knobProps.containerRadius.borderRadius).toBe(13);
+      expect(smooth.knobProps.cardSurface.borderRadius).toBe(13);
+      expect(smooth.knobProps.containerRadius.className).toBe(cornerSmoothClassName);
+    });
+
+    it("smooth changes nothing but the class (radius/border/padding identical to round)", () => {
+      const round = resolveKnobs(knobsWith({ cornerSmoothing: "round" }));
+      const smooth = resolveKnobs(knobsWith({ cornerSmoothing: "smooth" }));
+      for (const fragment of radiusFragments) {
+        const { className: _cls, ...smoothRest } = smooth.knobProps[fragment];
+        expect(smoothRest, fragment).toEqual(round.knobProps[fragment]);
+      }
+    });
+
+    it("never leaks onto non-radius fragments", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ cornerSmoothing: "smooth" }));
+      expect(knobProps.surface).not.toHaveProperty("className");
+      expect(knobProps.inputSurface).not.toHaveProperty("className");
+      expect(knobProps.panelPadding).not.toHaveProperty("className");
+      expect(knobProps.gap).not.toHaveProperty("className");
+    });
+
+    it("shipped presets pin the house default (round)", () => {
+      expect(defaultPreset.knobs.cornerSmoothing).toBe("round");
+      expect(boldPreset.knobs.cornerSmoothing).toBe("round");
+    });
+
+    // Native resolves to `round` for now (SquircleView adoption is phase 2) —
+    // no className may reach RN views regardless of the knob.
+    it("native emits no class for either value", async () => {
+      vi.resetModules();
+      vi.doMock("@multiplatform.one/platform", () => ({ isWeb: false }));
+      const { resolveKnobs: resolveNative } = await import("./resolveKnobs");
+      try {
+        for (const cornerSmoothing of ["round", "smooth"] as const) {
+          const { knobProps } = resolveNative(knobsWith({ cornerSmoothing }));
+          for (const fragment of radiusFragments) {
+            expect(knobProps[fragment], `${cornerSmoothing}/${fragment}`).not.toHaveProperty(
+              "className",
+            );
+          }
+        }
+      } finally {
+        vi.doUnmock("@multiplatform.one/platform");
+        vi.resetModules();
+      }
     });
   });
 
@@ -457,7 +765,7 @@ describe("resolveKnobs", () => {
       const overridden = resolveKnobs(defaultKnobs, () => ({
         elevation: "$4",
       }));
-      expect(baseline.knobProps.elevation).toBeUndefined();
+      expect(baseline.knobProps.elevation).toBe("$1");
       expect(overridden.knobProps.elevation).toBe("$4");
     });
 
@@ -485,8 +793,8 @@ describe("resolveKnobs", () => {
 
     const gapMap: Record<string, string> = {
       small: "$2",
-      medium: "$3",
-      large: "$4",
+      medium: "$4",
+      large: "$5",
     };
 
     const panelPaddingMap: Record<string, string> = {
@@ -497,8 +805,8 @@ describe("resolveKnobs", () => {
 
     const gapLgMap: Record<string, string> = {
       small: "$3",
-      medium: "$4",
-      large: "$5",
+      medium: "$5",
+      large: "$6",
     };
 
     // T4.1a — every Size enum value produces a valid sizeToken
@@ -554,11 +862,11 @@ describe("resolveKnobs", () => {
       expect(defaultKnobs.space).toBe("medium");
     });
 
-    // T4.1i — emptyStateKnobs is still valid
+    // T4.1i — emptyStateKnobs is still valid (W12: default hover layer remains)
     it("emptyStateKnobs is still valid (no required size field breaks it)", () => {
       const knobs = knobsWith({ hover: emptyStateKnobs });
       const { control } = resolveKnobs(knobs);
-      expect(control.hoverKnobProps).toBeUndefined();
+      expect(control.hoverKnobProps).toEqual({ backgroundColor: "$backgroundHover" });
     });
 
     // T4.1j — size "large" does not change borderRadius
@@ -569,3 +877,234 @@ describe("resolveKnobs", () => {
     });
   });
 });
+
+// ── Density (DG-DEN-01 / W8) ─────────────────────────────────
+
+describe("applyDensity", () => {
+  it('defaultKnobs.density is "comfortable"', () => {
+    expect(defaultKnobs.density).toBe(Density.Comfortable);
+  });
+
+  it("comfortable density leaves size and space unchanged", () => {
+    const knobs = knobsWith({ size: "large", space: "large", density: "comfortable" });
+    const applied = applyDensity(knobs);
+    expect(applied.size).toBe("large");
+    expect(applied.space).toBe("large");
+    expect(applied.density).toBe("comfortable");
+  });
+
+  it("compact density steps size and space down one level", () => {
+    expect(
+      applyDensity(knobsWith({ size: "large", space: "large", density: "compact" })),
+    ).toMatchObject({ size: "medium", space: "medium", density: "compact" });
+    expect(
+      applyDensity(knobsWith({ size: "medium", space: "medium", density: "compact" })),
+    ).toMatchObject({ size: "small", space: "small", density: "compact" });
+    expect(
+      applyDensity(knobsWith({ size: "small", space: "small", density: "compact" })),
+    ).toMatchObject({ size: "small", space: "small", density: "compact" });
+  });
+
+  it("compact:true override wins over comfortable density knob", () => {
+    const applied = applyDensity(
+      knobsWith({ size: "medium", space: "medium", density: "comfortable" }),
+      true,
+    );
+    expect(applied).toMatchObject({ size: "small", space: "small", density: "compact" });
+  });
+
+  it("compact:false override wins over compact density knob", () => {
+    const applied = applyDensity(
+      knobsWith({ size: "medium", space: "medium", density: "compact" }),
+      false,
+    );
+    expect(applied).toMatchObject({ size: "medium", space: "medium", density: "comfortable" });
+  });
+
+  it("resolveKnobs exposes density on knobProps", () => {
+    expect(resolveKnobs(defaultKnobs).knobProps.density).toBe("comfortable");
+    expect(resolveKnobs(knobsWith({ density: "compact" })).knobProps.density).toBe("compact");
+  });
+
+  it("compact density produces smaller sizeToken and gap than comfortable", () => {
+    const comfortable = resolveKnobs(applyDensity(knobsWith({ size: "medium", space: "medium" })));
+    const compact = resolveKnobs(
+      applyDensity(knobsWith({ size: "medium", space: "medium", density: "compact" })),
+    );
+    expect(comfortable.knobProps.sizeToken).toBe("$4");
+    expect(compact.knobProps.sizeToken).toBe("$3");
+    expect(comfortable.knobProps.gap).toEqual({ gap: "$4" });
+    expect(compact.knobProps.gap).toEqual({ gap: "$2" });
+  });
+
+  it("compact density preserves house-decision knobs", () => {
+    const knobs = knobsWith({
+      density: "compact",
+      fieldLabelPlacement: "side",
+      requiredMarking: "asterisk",
+      tableZebra: "on",
+      bulkBarPlacement: "bottom",
+      selectAllScope: "filtered",
+      timestampStyle: "relative",
+      disabledStyle: "dimWhole",
+      formAutofocus: "on",
+    });
+    const applied = applyDensity(knobs);
+    expect(applied).toMatchObject({
+      density: "compact",
+      fieldLabelPlacement: "side",
+      requiredMarking: "asterisk",
+      tableZebra: "on",
+      bulkBarPlacement: "bottom",
+      selectAllScope: "filtered",
+      timestampStyle: "relative",
+      disabledStyle: "dimWhole",
+      formAutofocus: "on",
+    });
+  });
+});
+
+// ── House decisions (design-guidelines.md) ────────────────────
+
+describe("house decision knobs", () => {
+  it("defaultKnobs use recommended house defaults", () => {
+    expect(defaultKnobs.fieldLabelPlacement).toBe(FieldLabelPlacement.Top);
+    expect(defaultKnobs.requiredMarking).toBe(RequiredMarking.Minority);
+    expect(defaultKnobs.tableZebra).toBe(TableZebra.Off);
+    expect(defaultKnobs.bulkBarPlacement).toBe(BulkBarPlacement.Top);
+    expect(defaultKnobs.selectAllScope).toBe(SelectAllScope.Page);
+    expect(defaultKnobs.timestampStyle).toBe(TimestampStyle.Absolute);
+    expect(defaultKnobs.disabledStyle).toBe(DisabledStyle.KeepLabel);
+    expect(defaultKnobs.formAutofocus).toBe(FormAutofocus.Off);
+  });
+
+  it("resolveKnobs exposes house knobs on knobProps (pass-through)", () => {
+    const { knobProps } = resolveKnobs(defaultKnobs);
+    expect(knobProps.fieldLabelPlacement).toBe("top");
+    expect(knobProps.requiredMarking).toBe("minority");
+    expect(knobProps.tableZebra).toBe("off");
+    expect(knobProps.bulkBarPlacement).toBe("top");
+    expect(knobProps.selectAllScope).toBe("page");
+    expect(knobProps.timestampStyle).toBe("absolute");
+    expect(knobProps.disabledStyle).toBe("keepLabel");
+    expect(knobProps.formAutofocus).toBe("off");
+  });
+
+  it("resolveKnobs reflects house knob overrides", () => {
+    const { knobProps } = resolveKnobs(
+      knobsWith({
+        fieldLabelPlacement: "floating",
+        requiredMarking: "optional",
+        tableZebra: "on",
+        bulkBarPlacement: "bottom",
+        selectAllScope: "filtered",
+        timestampStyle: "relative",
+        disabledStyle: "dimWhole",
+        formAutofocus: "on",
+      }),
+    );
+    expect(knobProps.fieldLabelPlacement).toBe("floating");
+    expect(knobProps.requiredMarking).toBe("optional");
+    expect(knobProps.tableZebra).toBe("on");
+    expect(knobProps.bulkBarPlacement).toBe("bottom");
+    expect(knobProps.selectAllScope).toBe("filtered");
+    expect(knobProps.timestampStyle).toBe("relative");
+    expect(knobProps.disabledStyle).toBe("dimWhole");
+    expect(knobProps.formAutofocus).toBe("on");
+  });
+
+  it("house knobs do not alter structural token resolution", () => {
+    const baseline = resolveKnobs(defaultKnobs);
+    const housey = resolveKnobs(
+      knobsWith({
+        fieldLabelPlacement: "side",
+        tableZebra: "on",
+        formAutofocus: "on",
+      }),
+    );
+    expect(housey.knobProps.sizeToken).toBe(baseline.knobProps.sizeToken);
+    expect(housey.knobProps.gap).toEqual(baseline.knobProps.gap);
+    expect(housey.knobProps.borderRadius).toEqual(baseline.knobProps.borderRadius);
+    expect(housey.knobProps.density).toBe(baseline.knobProps.density);
+  });
+});
+
+// ── Disabled treatment recipe (LC-40 DISABLED-VISIBLE) ────────
+
+describe("disabledState recipe (LC-40)", () => {
+  it("keepLabel (default) resolves a VISIBLE chrome treatment — not a no-op", () => {
+    const { disabledState } = resolveKnobs(defaultKnobs);
+    expect(disabledState.style).toBe("keepLabel");
+    // Text-bearing chrome: fill/border wash to muted ramp steps, no opacity
+    // (inner text keeps its own alpha so it can hold >= AA).
+    expect(disabledState.surfaceKnobProps).toEqual({
+      backgroundColor: "$color3",
+      borderColor: "$color6",
+      cursor: "not-allowed",
+    });
+    expect(disabledState.surfaceKnobProps).not.toHaveProperty("opacity");
+    // Selected-while-disabled tier: one wash step stronger than the plain
+    // wash so the chosen segment stays visibly chosen (Axiom 6).
+    expect(disabledState.selectedSurfaceKnobProps).toEqual({
+      backgroundColor: "$color5",
+      borderColor: "$color8",
+      cursor: "not-allowed",
+    });
+    // Text-free chrome: opacity dim.
+    expect(disabledState.chromeKnobProps).toEqual({ opacity: 0.5, cursor: "not-allowed" });
+    // Inner text re-anchors to the documented lowest AA step ($color11).
+    expect(disabledState.textKnobProps).toEqual({ color: "$color11" });
+    // keepLabel never dims the assembly (label/helper stay fully readable).
+    expect(disabledState.assemblyKnobProps).toEqual({});
+  });
+
+  it("dimWhole dims the assembly once — control fragments carry only the affordance", () => {
+    const { disabledState } = resolveKnobs(knobsWith({ disabledStyle: "dimWhole" }));
+    expect(disabledState.style).toBe("dimWhole");
+    expect(disabledState.assemblyKnobProps).toEqual({ opacity: 0.5 });
+    // No chrome-level opacity: the assembly owner applies the single dim.
+    expect(disabledState.surfaceKnobProps).toEqual({ cursor: "not-allowed" });
+    expect(disabledState.chromeKnobProps).toEqual({ cursor: "not-allowed" });
+    expect(disabledState.textKnobProps).toEqual({});
+    // Exception: the selected tier still washes — consumers drop the live
+    // active fill when disabled, so the assembly dim alone cannot show
+    // which option is chosen.
+    expect(disabledState.selectedSurfaceKnobProps).toEqual({
+      backgroundColor: "$color5",
+      borderColor: "$color8",
+      cursor: "not-allowed",
+    });
+  });
+
+  it("both values expose complete fragments for every anatomy slot", () => {
+    for (const disabledStyle of ["keepLabel", "dimWhole"] as const) {
+      const { disabledState } = resolveKnobs(knobsWith({ disabledStyle }));
+      expect(disabledState).toHaveProperty("surfaceKnobProps");
+      expect(disabledState).toHaveProperty("selectedSurfaceKnobProps");
+      expect(disabledState).toHaveProperty("chromeKnobProps");
+      expect(disabledState).toHaveProperty("textKnobProps");
+      expect(disabledState).toHaveProperty("assemblyKnobProps");
+      // The not-allowed affordance rides the control chrome under both values.
+      expect(disabledState.surfaceKnobProps.cursor).toBe("not-allowed");
+      expect(disabledState.selectedSurfaceKnobProps.cursor).toBe("not-allowed");
+      expect(disabledState.chromeKnobProps.cursor).toBe("not-allowed");
+      // Selected tier is visibly distinct from the plain wash in both models.
+      expect(disabledState.selectedSurfaceKnobProps.backgroundColor).not.toBe(
+        disabledState.surfaceKnobProps.backgroundColor,
+      );
+    }
+  });
+
+  it("disabled tiers are theme-relative ramp steps (no hex, works under intents)", () => {
+    const { disabledState } = resolveKnobs(defaultKnobs);
+    for (const value of [
+      disabledState.surfaceKnobProps.backgroundColor,
+      disabledState.surfaceKnobProps.borderColor,
+      disabledState.selectedSurfaceKnobProps.backgroundColor,
+      disabledState.selectedSurfaceKnobProps.borderColor,
+      disabledState.textKnobProps.color,
+    ]) {
+      expect(value).toMatch(/^\$color\d+$/);
+    }
+  });
+});