@multiplatform.one/forms 7.6.3 → 7.7.0

package/src/fields/Checkbox/Checkbox.spec.tsx

@@ -343,6 +343,30 @@ describe("CheckboxGroup", () => {
     });
   });
 
+  it("E-FLAT: group glyphs stay unwrapped at elevation large; standalone Checkbox still wraps", () => {
+    const result = renderWithProviders(
+      <Preset overrides={{ elevation: "large" }}>
+        <div data-testid="group">
+          <CheckboxGroup label="Group" options={options} defaultValue={["a"]} />
+        </div>
+        <div data-testid="solo">
+          <Checkbox label="Solo" checked />
+        </div>
+      </Preset>,
+    );
+    const groupBox = result.container
+      .querySelector("[data-testid='group']")
+      ?.querySelector("[data-checkbox-box='true']");
+    expect(groupBox).toBeTruthy();
+    expect(groupBox!.parentElement?.getAttribute("role")).toBe("checkbox");
+
+    const soloBox = result.container
+      .querySelector("[data-testid='solo']")
+      ?.querySelector("[data-checkbox-box='true']");
+    expect(soloBox).toBeTruthy();
+    expect(soloBox!.parentElement?.getAttribute("role")).not.toBe("checkbox");
+  });
+
   describe("compound Checkboxes LC-71", () => {
     it("keyboard focus rings the box, never the focus-group item", async () => {
       const spy = vi.spyOn(Theme, "wasKeyboardFocus").mockReturnValue(true);

package/src/fields/Checkbox/Checkbox.tsx

@@ -20,6 +20,7 @@ import {
   useTheme,
 } from "tamagui";
 import { useIsInTableCell } from "../../shared/tableCellContext";
+import { useCheckboxGroupSkipsElevation } from "./checkboxGroupContext";
 import { Skeleton } from "../../Skeleton";
 import { Field, FieldLayout } from "../../fieldLayout";
 import { formCommonColors, formSelectedColors } from "../../shared/colorRamps";
@@ -149,9 +150,14 @@ export function Checkbox({
   const labelFocusStyle = { color: baseLabelColor, ...text.focusKnobProps };
   const labelFocusVisibleStyle = { color: baseLabelColor, ...text.focusVisibleKnobProps };
   const tamaguiTheme = useTheme();
+  // E-FLAT: table cells and CheckboxGroup items ignore elevation. Skip the
+  // shared helper rather than changing it (MPO-96 owns default `small`).
+  const inTableCell = useIsInTableCell();
+  const inCheckboxGroup = useCheckboxGroupSkipsElevation();
+  const skipElevation = inTableCell || inCheckboxGroup;
   const elevationWrapperProps = useMemo(
-    () => getElevationWrapperProps(knobProps, elevation),
-    [knobProps, elevation],
+    () => (skipElevation ? {} : getElevationWrapperProps(knobProps, elevation)),
+    [skipElevation, knobProps, elevation],
   );
   const accentTokenKey = (knobProps.textAccentColor ?? "$color").replace("$", "");
   const indicatorColor = getVariable(
@@ -207,7 +213,6 @@ export function Checkbox({
   // checkbox's own computed size (tamagui scaleSize 0.45), so visual density
   // is unchanged. Cells (chromeless) and plain forms share the treatment —
   // the earlier cell-only split left the plain checkbox at a 20px target.
-  const inTableCell = useIsInTableCell();
   const targetSize = CHECKBOX_TARGET_PX;
   const glyphSize = getCheckboxGlyphSize(resolvedSize as SizeTokens);
   const iconSize = getCheckboxIconSize(glyphSize);

package/src/fields/Checkbox/CheckboxBox.spec.tsx

@@ -0,0 +1,395 @@
+/**
+ * CheckboxBox — the painted glyph and the geometry rules around it (MPO-143).
+ *
+ * Checkbox.spec.tsx already covers the two headline radius helpers through the
+ * package barrel. What had no coverage at all is everything else this module
+ * exports: the WCAG hit-target constant, the three size/border derivations,
+ * the LC-71 "the 44px frame paints nothing" prop bag, the keyboard-modality
+ * focus handlers, and the glyph box itself. Those are the parts that regress
+ * silently — nothing today would notice if the hit target grew a wash or the
+ * glyph started stealing the press.
+ */
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  CHECKBOX_GLYPH_MAX_RADIUS_TOKEN,
+  CHECKBOX_TARGET_PX,
+  CheckboxGlyphBox,
+  checkboxKbFocusHandlers,
+  checkboxTargetFrameProps,
+  clampCheckboxGlyphRadius,
+  getCheckboxBoxBorderWidth,
+  getCheckboxGlyphSize,
+  getCheckboxIconSize,
+  isCircularCheckboxRadius,
+} from "./CheckboxBox";
+
+afterEach(cleanup);
+
+/**
+ * Modality is the ONE thing here that has to be stood in for. The real tracker
+ * (`@multiplatform.one/theme/keyboardFocusRing`) installs global document
+ * listeners lazily and never flips under this test environment - a dispatched
+ * keydown, on the document or on a real element, leaves `wasKeyboardFocus()`
+ * false - so driving it would assert the environment, not the component.
+ * Everything else in the module stays real: only this one function is
+ * replaced, over `importActual`.
+ */
+let keyboardModality = false;
+vi.mock("@multiplatform.one/theme", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@multiplatform.one/theme")>();
+  return { ...actual, wasKeyboardFocus: () => keyboardModality };
+});
+
+function pressKey() {
+  keyboardModality = true;
+}
+function pressPointer() {
+  keyboardModality = false;
+}
+
+afterEach(() => {
+  keyboardModality = false;
+});
+
+function glyph(container: HTMLElement): HTMLElement {
+  const node = container.querySelector("[data-checkbox-box='true']");
+  if (!node) throw new Error("CheckboxGlyphBox did not render");
+  return node as HTMLElement;
+}
+
+/** Tamagui paints through atomic classes, so read both channels. */
+function cssOf(node: HTMLElement, prop: string): string {
+  const inline = node.style.getPropertyValue(prop);
+  if (inline) return inline;
+  return getComputedStyle(node).getPropertyValue(prop) || "";
+}
+
+function classesOf(node: HTMLElement): string {
+  return Array.from(node.classList).join(" ");
+}
+
+describe("CheckboxBox — the target is 44px and the glyph is smaller", () => {
+  it("pins the WCAG 2.5.5 pressable floor at 44px", () => {
+    expect(CHECKBOX_TARGET_PX).toBe(44);
+  });
+
+  it("derives the glyph at 45% of the size token, rounded", () => {
+    // $4 resolves to 44 on the house size scale in this config, so the glyph
+    // is derived, never hardcoded: whatever the token resolves to, the glyph
+    // is round(0.45 x) and strictly smaller than the 44px target.
+    for (const token of ["$2", "$3", "$4", "$5"] as const) {
+      const size = getCheckboxGlyphSize(token);
+      expect(Number.isInteger(size)).toBe(true);
+      expect(size).toBeGreaterThan(0);
+      expect(size).toBeLessThan(CHECKBOX_TARGET_PX);
+    }
+  });
+
+  it("grows the glyph monotonically with the size token", () => {
+    const small = getCheckboxGlyphSize("$2");
+    const large = getCheckboxGlyphSize("$5");
+    expect(large).toBeGreaterThan(small);
+  });
+});
+
+describe("CheckboxBox — the empty box's edge is the shape (DF-06)", () => {
+  it("floors the border at 2px whatever the knob says", () => {
+    expect(getCheckboxBoxBorderWidth(1)).toBe(2);
+    expect(getCheckboxBoxBorderWidth(0)).toBe(2);
+    expect(getCheckboxBoxBorderWidth(undefined)).toBe(2);
+    expect(getCheckboxBoxBorderWidth(Number.NaN)).toBe(2);
+  });
+
+  it("honours a thicker knob instead of clamping it down", () => {
+    expect(getCheckboxBoxBorderWidth(3)).toBe(3);
+    expect(getCheckboxBoxBorderWidth(6)).toBe(6);
+  });
+
+  it("keeps the check mark at 70% of the glyph but never under 10px", () => {
+    expect(getCheckboxIconSize(20)).toBe(14);
+    expect(getCheckboxIconSize(30)).toBe(21);
+    // The floor bites on the small end: 0.7 x 10 = 7 would be unreadable.
+    expect(getCheckboxIconSize(10)).toBe(10);
+    expect(getCheckboxIconSize(4)).toBe(10);
+  });
+});
+
+describe("CheckboxBox — the radius law (DG-RAD-05 / R2)", () => {
+  it("caps every token stop at $2, which is the documented maximum", () => {
+    expect(CHECKBOX_GLYPH_MAX_RADIUS_TOKEN).toBe(2);
+    expect(clampCheckboxGlyphRadius("$1")).toBe("$1");
+    expect(clampCheckboxGlyphRadius("$2")).toBe("$2");
+    for (const token of ["$3", "$4", "$6", "$8", "$10", "$12"]) {
+      expect(clampCheckboxGlyphRadius(token), token).toBe("$2");
+    }
+  });
+
+  it("goes hard-angled for pointy and for $0, and pointy wins over any stop", () => {
+    expect(clampCheckboxGlyphRadius("$0")).toBe(0);
+    expect(clampCheckboxGlyphRadius("$12", { pointy: true })).toBe(0);
+    expect(clampCheckboxGlyphRadius("$1", { pointy: true })).toBe(0);
+    expect(clampCheckboxGlyphRadius(undefined, { pointy: true })).toBe(0);
+    // pointy:false is not pointy — it must not swallow the stop.
+    expect(clampCheckboxGlyphRadius("$1", { pointy: false })).toBe("$1");
+  });
+
+  it("passes a non-token value through untouched", () => {
+    expect(clampCheckboxGlyphRadius("4px")).toBe("4px");
+  });
+
+  it("RULE GAP: an absent token falls back to $4, above the documented $2 cap", () => {
+    // This is the module's own shared clamp fallback (clampRadius(..., "$4")),
+    // and it contradicts the comment three lines above it in CheckboxBox.tsx:
+    // "$4 (9) already paints as a circle on that box". Asserted as OBSERVED
+    // behaviour, deliberately not "fixed" here — which of the two is right is
+    // Clay's call, and it is recorded on MPO-143 rather than guessed at.
+    expect(clampCheckboxGlyphRadius(undefined)).toBe("$4");
+    // The live caller always passes a resolved knob token, so the gap is in
+    // the exported contract, not in what the Checkbox renders today.
+  });
+
+  it("calls a radius circular exactly at half the side, not before", () => {
+    expect(isCircularCheckboxRadius(9, 20)).toBe(false);
+    expect(isCircularCheckboxRadius(10, 20)).toBe(true);
+    expect(isCircularCheckboxRadius(11, 20)).toBe(true);
+    expect(isCircularCheckboxRadius(0, 20)).toBe(false);
+  });
+
+  it("refuses to answer for a zero or negative side", () => {
+    expect(isCircularCheckboxRadius(10, 0)).toBe(false);
+    expect(isCircularCheckboxRadius(10, -20)).toBe(false);
+  });
+
+  it("keeps the capped stop non-circular on a real glyph, which is the point of the cap", () => {
+    // $2 = 5px on the house radius scale, glyph ~20px: 5 < 10, so square.
+    expect(isCircularCheckboxRadius(5, 20)).toBe(false);
+    // $4 = 9px would not be, which is why the cap exists.
+    expect(isCircularCheckboxRadius(9, 18)).toBe(true);
+  });
+});
+
+describe("CheckboxBox — LC-71: the 44px frame paints nothing", () => {
+  it("is a 44px square with no border, no radius and no fill", () => {
+    expect(checkboxTargetFrameProps.width).toBe(CHECKBOX_TARGET_PX);
+    expect(checkboxTargetFrameProps.height).toBe(CHECKBOX_TARGET_PX);
+    expect(checkboxTargetFrameProps.minWidth).toBe(CHECKBOX_TARGET_PX);
+    expect(checkboxTargetFrameProps.minHeight).toBe(CHECKBOX_TARGET_PX);
+    expect(checkboxTargetFrameProps.borderWidth).toBe(0);
+    expect(checkboxTargetFrameProps.borderRadius).toBe(0);
+    expect(checkboxTargetFrameProps.padding).toBe(0);
+    expect(checkboxTargetFrameProps.backgroundColor).toBe("transparent");
+    expect(checkboxTargetFrameProps.outlineWidth).toBe(0);
+  });
+
+  it("keeps every interaction channel transparent, so no wash can wrap the label", () => {
+    for (const state of [
+      "hoverStyle",
+      "pressStyle",
+      "focusStyle",
+      "focusVisibleStyle",
+      "activeStyle",
+    ] as const) {
+      const bag = checkboxTargetFrameProps[state] as Record<string, unknown>;
+      expect(bag.backgroundColor, state).toBe("transparent");
+      expect(bag.borderColor, state).toBe("transparent");
+    }
+    expect(checkboxTargetFrameProps.focusStyle.outlineWidth).toBe(0);
+    expect(checkboxTargetFrameProps.focusVisibleStyle.outlineWidth).toBe(0);
+  });
+});
+
+describe("CheckboxBox — keyboard-modality focus handlers", () => {
+  it("raises kbFocus on a focus that followed a key press", () => {
+    const setKbFocus = vi.fn();
+    const handlers = checkboxKbFocusHandlers(setKbFocus, vi.fn());
+    pressKey();
+    handlers.onFocus({});
+    expect(setKbFocus).toHaveBeenCalledWith(true);
+  });
+
+  it("stays quiet on a focus that followed a pointer press", () => {
+    const setKbFocus = vi.fn();
+    const handlers = checkboxKbFocusHandlers(setKbFocus, vi.fn());
+    pressPointer();
+    handlers.onFocus({});
+    expect(setKbFocus).not.toHaveBeenCalled();
+  });
+
+  it("always clears kbFocus on blur, whatever the modality was", () => {
+    const setKbFocus = vi.fn();
+    const handlers = checkboxKbFocusHandlers(setKbFocus, vi.fn());
+    pressPointer();
+    handlers.onBlur({});
+    expect(setKbFocus).toHaveBeenCalledWith(false);
+  });
+
+  it("tracks hover in and out", () => {
+    const setHovered = vi.fn();
+    const handlers = checkboxKbFocusHandlers(vi.fn(), setHovered);
+    handlers.onHoverIn({});
+    expect(setHovered).toHaveBeenLastCalledWith(true);
+    handlers.onHoverOut({});
+    expect(setHovered).toHaveBeenLastCalledWith(false);
+  });
+
+  it("forwards the caller's own handlers instead of swallowing them", () => {
+    const rest = {
+      onFocus: vi.fn(),
+      onBlur: vi.fn(),
+      onHoverIn: vi.fn(),
+      onHoverOut: vi.fn(),
+    };
+    const handlers = checkboxKbFocusHandlers(vi.fn(), vi.fn(), rest);
+    const event = { id: 1 };
+    handlers.onFocus(event);
+    handlers.onBlur(event);
+    handlers.onHoverIn(event);
+    handlers.onHoverOut(event);
+    expect(rest.onFocus).toHaveBeenCalledWith(event);
+    expect(rest.onBlur).toHaveBeenCalledWith(event);
+    expect(rest.onHoverIn).toHaveBeenCalledWith(event);
+    expect(rest.onHoverOut).toHaveBeenCalledWith(event);
+  });
+
+  it("survives a caller that passes no handlers at all", () => {
+    const handlers = checkboxKbFocusHandlers(vi.fn(), vi.fn());
+    expect(() => {
+      handlers.onFocus({});
+      handlers.onBlur({});
+      handlers.onHoverIn({});
+      handlers.onHoverOut({});
+    }).not.toThrow();
+  });
+});
+
+describe("CheckboxGlyphBox — the painted box", () => {
+  it("marks itself so the boards and the other specs can find it", () => {
+    const { container } = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={20}
+        isMarked={false}
+        kbFocus={false}
+        borderWidth={2}
+        borderRadius={5}
+      />,
+    );
+    expect(glyph(container)).toBeTruthy();
+  });
+
+  it("never takes the press, so the 44px frame keeps the responder", () => {
+    const { container } = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={20}
+        isMarked={false}
+        kbFocus={false}
+        borderWidth={2}
+        borderRadius={5}
+      />,
+    );
+    expect(cssOf(glyph(container), "pointer-events")).toBe("none");
+  });
+
+  it("publishes the focus-ring flag only while kbFocus is true", () => {
+    const off = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={20}
+        isMarked={false}
+        kbFocus={false}
+        borderWidth={2}
+        borderRadius={5}
+      />,
+    );
+    expect(glyph(off.container).getAttribute("data-focus-ring")).toBeNull();
+    cleanup();
+    const on = renderWithProviders(
+      <CheckboxGlyphBox glyphSize={20} isMarked={false} kbFocus borderWidth={2} borderRadius={5} />,
+    );
+    expect(glyph(on.container).getAttribute("data-focus-ring")).toBe("true");
+  });
+
+  it("is an empty box when idle and drops that transparency when marked", () => {
+    const unmarked = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={20}
+        isMarked={false}
+        kbFocus={false}
+        borderWidth={2}
+        borderRadius={5}
+      />,
+    );
+    expect(classesOf(glyph(unmarked.container))).toContain("_bg-transparent");
+    cleanup();
+    const marked = renderWithProviders(
+      <CheckboxGlyphBox glyphSize={20} isMarked kbFocus={false} borderWidth={2} borderRadius={5} />,
+    );
+    // Checked paints the MARK channel (formSelectedColors.mark), so the
+    // transparent fill is gone. The mark token is an accent value the test
+    // config does not resolve, which is exactly why this asserts the absence
+    // of the idle fill rather than a colour literal.
+    expect(classesOf(glyph(marked.container))).not.toContain("_bg-transparent");
+  });
+
+  it("takes the checked border off the boundary ramp entirely, so it is a fill and not a second outline", () => {
+    const { container } = renderWithProviders(
+      <CheckboxGlyphBox glyphSize={20} isMarked kbFocus={false} borderWidth={2} borderRadius={5} />,
+    );
+    const painted = classesOf(glyph(container));
+    expect(painted).not.toContain("_btc-color10");
+    expect(painted).not.toContain("_btc-color11");
+  });
+
+  it("moves the idle border from the boundary tier to the press tier on hover", () => {
+    // formControlColors.boundary = $color10 (DF-06: the edge that carries the
+    // shape, >=3:1), thumb.press = $color11.
+    const idle = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={20}
+        isMarked={false}
+        kbFocus={false}
+        borderWidth={2}
+        borderRadius={5}
+      />,
+    );
+    expect(classesOf(glyph(idle.container))).toContain("_btc-color10");
+    cleanup();
+    const hovered = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={20}
+        isMarked={false}
+        kbFocus={false}
+        hovered
+        borderWidth={2}
+        borderRadius={5}
+      />,
+    );
+    expect(classesOf(glyph(hovered.container))).toContain("_btc-color11");
+  });
+
+  it("takes its geometry from the props rather than a hardcoded box", () => {
+    const { container } = renderWithProviders(
+      <CheckboxGlyphBox
+        glyphSize={26}
+        isMarked={false}
+        kbFocus={false}
+        borderWidth={3}
+        borderRadius={7}
+      />,
+    );
+    const node = glyph(container);
+    expect(cssOf(node, "width")).toBe("26px");
+    expect(cssOf(node, "height")).toBe("26px");
+    expect(cssOf(node, "border-top-width")).toBe("3px");
+    expect(classesOf(node)).toContain("_btlr-7px");
+  });
+
+  it("renders the check mark it is handed", () => {
+    const { container } = renderWithProviders(
+      <CheckboxGlyphBox glyphSize={20} isMarked kbFocus={false} borderWidth={2} borderRadius={5}>
+        <span data-mark>x</span>
+      </CheckboxGlyphBox>,
+    );
+    expect(container.querySelector("[data-mark]")).toBeTruthy();
+  });
+});

package/src/fields/Checkbox/CheckboxCard.spec.tsx

@@ -0,0 +1,197 @@
+/**
+ * CheckboxCard — the SELECTION-CARD anatomy (LC-22) and its two derivations
+ * (MPO-143).
+ *
+ * These five parts are shared by `Checkboxes.Card`, `CheckboxGroup card` and
+ * `RadioGroup card`, so a change here moves three surfaces at once and nothing
+ * checked it. The two rules worth pinning are LC-71's "selected = fill, not an
+ * extra border" and T-HELPER's "the description is one step under the field
+ * size" — both are one-line edits away from silently regressing.
+ */
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  CheckboxCardContent,
+  CheckboxCardDescription,
+  CheckboxCardFrame,
+  CheckboxCardLabel,
+  getCardDescriptionSize,
+  getCheckboxCardLayout,
+} from "./CheckboxCard";
+
+afterEach(cleanup);
+
+/**
+ * The styled parts paint through Tamagui atomic classes, so the class list is
+ * the honest read; `getComputedStyle` only resolves the subset whose CSS this
+ * environment injects.
+ */
+function classesOf(node: Element | null): string {
+  if (!node) throw new Error("expected a rendered node");
+  return Array.from(node.classList).join(" ");
+}
+
+function painted(container: HTMLElement, marker: string): string {
+  return classesOf(container.querySelector(`[class*='${marker}']`));
+}
+
+describe("getCardDescriptionSize — T-HELPER is one step under the field", () => {
+  it("maps each field size onto its helper tier", () => {
+    expect(getCardDescriptionSize("$1")).toBe("$1");
+    expect(getCardDescriptionSize("$2")).toBe("$1");
+    expect(getCardDescriptionSize("$3")).toBe("$2");
+    expect(getCardDescriptionSize("$4")).toBe("$3");
+    expect(getCardDescriptionSize("$5")).toBe("$4");
+    expect(getCardDescriptionSize("$6")).toBe("$5");
+  });
+
+  it("treats $true as the default field size, not as an unknown", () => {
+    expect(getCardDescriptionSize("$true" as never)).toBe("$3");
+    expect(getCardDescriptionSize("$true" as never)).toBe(getCardDescriptionSize("$4"));
+  });
+
+  it("falls back to $2 for no size and for a size off the ladder", () => {
+    expect(getCardDescriptionSize(undefined)).toBe("$2");
+    expect(getCardDescriptionSize("$9" as never)).toBe("$2");
+  });
+
+  it("never returns a helper size at or above its own field size", () => {
+    for (const [field, helper] of [
+      ["$3", "$2"],
+      ["$4", "$3"],
+      ["$5", "$4"],
+      ["$6", "$5"],
+    ] as const) {
+      expect(getCardDescriptionSize(field), field).toBe(helper);
+      expect(Number(String(helper).slice(1))).toBeLessThan(Number(field.slice(1)));
+    }
+  });
+});
+
+describe("getCheckboxCardLayout — compact metrics off the space knob", () => {
+  it("gives each space stop its own padding and gap", () => {
+    expect(getCheckboxCardLayout("none")).toEqual({
+      paddingVertical: "$2.5",
+      paddingHorizontal: "$3",
+      gap: "$2.5",
+    });
+    expect(getCheckboxCardLayout("large")).toEqual({
+      paddingVertical: "$3.5",
+      paddingHorizontal: "$4",
+      gap: "$3.5",
+    });
+  });
+
+  it("makes small and medium deliberately identical", () => {
+    expect(getCheckboxCardLayout("small")).toEqual(getCheckboxCardLayout("medium"));
+  });
+
+  it("falls back to medium for an unknown stop rather than throwing", () => {
+    expect(getCheckboxCardLayout("enormous")).toEqual(getCheckboxCardLayout("medium"));
+    expect(getCheckboxCardLayout("")).toEqual(getCheckboxCardLayout("medium"));
+  });
+
+  it("grows monotonically from none to large", () => {
+    const stops = ["none", "small", "large"].map((s) => getCheckboxCardLayout(s));
+    const num = (token: string) => Number(token.replace("$", ""));
+    expect(num(stops[0].paddingVertical)).toBeLessThanOrEqual(num(stops[1].paddingVertical));
+    expect(num(stops[1].paddingVertical)).toBeLessThan(num(stops[2].paddingVertical));
+  });
+});
+
+describe("CheckboxCardFrame — control leading, whole card interactive", () => {
+  it("lays the control out in a row, top-aligned with the first label line", () => {
+    const { container } = renderWithProviders(<CheckboxCardFrame />);
+    const card = painted(container, "_fd-row");
+    expect(card).toContain("_fd-row");
+    expect(card).toContain("_ai-flex-start");
+  });
+
+  it("reads as pressable across the whole card", () => {
+    const { container } = renderWithProviders(<CheckboxCardFrame />);
+    expect(painted(container, "_fd-row")).toContain("_cur-pointer");
+  });
+
+  it("carries exactly one border at rest, on the $color6 seam", () => {
+    const { container } = renderWithProviders(<CheckboxCardFrame />);
+    const card = painted(container, "_fd-row");
+    expect(card).toContain("_btw-1px");
+    expect(card).toContain("_btc-color6");
+  });
+
+  it("moves the border one step up the ramp on hover, and only on hover", () => {
+    const { container } = renderWithProviders(<CheckboxCardFrame />);
+    const card = painted(container, "_fd-row");
+    expect(card).toContain("_btc-0hover-color7");
+    expect(card).toContain("_btc-color6");
+  });
+
+  it("LC-71: active changes the FILL and leaves the border exactly where it was", () => {
+    const rest = renderWithProviders(<CheckboxCardFrame />);
+    const restCard = painted(rest.container, "_fd-row");
+    expect(restCard).toContain("_bg-color2");
+    cleanup();
+    const active = renderWithProviders(<CheckboxCardFrame active />);
+    const activeCard = painted(active.container, "_fd-row");
+    expect(activeCard).toContain("_bg-color3");
+    expect(activeCard).not.toContain("_bg-color2");
+    // the border is untouched: same width, same colour, no second outline
+    expect(activeCard).toContain("_btw-1px");
+    expect(activeCard).toContain("_btc-color6");
+  });
+
+  it("renders the control and the text column it is given", () => {
+    const { container } = renderWithProviders(
+      <CheckboxCardFrame>
+        <span data-control />
+        <CheckboxCardContent>
+          <CheckboxCardLabel>Ship it</CheckboxCardLabel>
+          <CheckboxCardDescription>Sends the release out</CheckboxCardDescription>
+        </CheckboxCardContent>
+      </CheckboxCardFrame>,
+    );
+    expect(container.querySelector("[data-control]")).toBeTruthy();
+    expect(container.textContent).toContain("Ship it");
+    expect(container.textContent).toContain("Sends the release out");
+  });
+});
+
+describe("CheckboxCardContent — the text column", () => {
+  it("stacks the label over the description and can shrink under a long word", () => {
+    const { container } = renderWithProviders(<CheckboxCardContent />);
+    const column = painted(container, "_miw-0px");
+    expect(column).toContain("_fd-column");
+    expect(column).toContain("_miw-0px");
+    expect(column).toContain("_fg-1");
+  });
+});
+
+describe("CheckboxCardLabel and CheckboxCardDescription", () => {
+  it("makes the label the bold, full-contrast first line", () => {
+    const { container } = renderWithProviders(<CheckboxCardLabel>Label</CheckboxCardLabel>);
+    const label = classesOf(container.querySelector("p"));
+    expect(label).toContain("_fow-600");
+    expect(label).toContain("_lh-20px");
+    expect(label).toContain("_col-color12");
+  });
+
+  it("paints the description one ramp step down, in the muted tier", () => {
+    const label = renderWithProviders(<CheckboxCardLabel>Label</CheckboxCardLabel>);
+    expect(classesOf(label.container.querySelector("p"))).toContain("_col-color12");
+    cleanup();
+    const description = renderWithProviders(
+      <CheckboxCardDescription>Helper</CheckboxCardDescription>,
+    );
+    const muted = classesOf(description.container.querySelector("p"));
+    expect(muted).toContain("_col-color11");
+    expect(muted).not.toContain("_col-color12");
+  });
+
+  it("leaves the description at the normal weight, so only the label is bold", () => {
+    const { container } = renderWithProviders(
+      <CheckboxCardDescription>Helper</CheckboxCardDescription>,
+    );
+    expect(classesOf(container.querySelector("p"))).not.toContain("_fow-600");
+  });
+});