@multiplatform.one/forms 7.7.6 → 7.10.0

package/src/FloatingPanel/nestedAction.spec.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { isNestedPanelAction } from "./nestedAction";
+
+describe("independent actions inside panel triggers", () => {
+  it("recognizes an SVG descendant of a marked action", () => {
+    const wrapper = document.createElement("div");
+    wrapper.innerHTML = '<button data-floating-panel-action="true"><svg><path /></svg></button>';
+    expect(
+      isNestedPanelAction({
+        nativeEvent: { target: wrapper.querySelector("path") },
+        currentTarget: wrapper,
+      }),
+    ).toBe(true);
+  });
+
+  it("does not let a marker above the wrapper suppress an ordinary opener", () => {
+    const outer = document.createElement("div");
+    outer.setAttribute("data-floating-panel-action", "true");
+    outer.innerHTML = "<div><button>Open</button></div>";
+    expect(
+      isNestedPanelAction({
+        target: outer.querySelector("button"),
+        currentTarget: outer.firstElementChild,
+      }),
+    ).toBe(false);
+  });
+
+  it("keeps unmarked buttons and non-DOM events as ordinary trigger presses", () => {
+    const wrapper = document.createElement("div");
+    wrapper.innerHTML = "<button>Open</button>";
+    expect(isNestedPanelAction({ target: wrapper.firstElementChild, currentTarget: wrapper })).toBe(
+      false,
+    );
+    expect(isNestedPanelAction({})).toBe(false);
+  });
+});

package/src/FloatingPanel/nestedAction.ts

@@ -0,0 +1,15 @@
+export const floatingPanelActionProps = { "data-floating-panel-action": "true" } as const;
+
+export interface PanelActionEvent {
+  target?: unknown;
+  currentTarget?: unknown;
+  nativeEvent?: { target?: unknown };
+}
+
+/** Marked actions inside a trigger keep their own press and keyboard behavior. */
+export function isNestedPanelAction(event: PanelActionEvent): boolean {
+  const target = (event.nativeEvent?.target ?? event.target) as Element | null;
+  const wrapper = event.currentTarget as Element | null;
+  const action = target?.closest?.('[data-floating-panel-action="true"]');
+  return !!action && !!wrapper?.contains?.(action);
+}

package/src/FloatingPanel/panelWidthContract.spec.ts

@@ -1,6 +1,5 @@
 /**
- * MPO-38 AC: no FloatingPanel consumer renders a panel narrower than its
- * trigger.
+ * Text listboxes match the field width; intrinsic editors size to their content.
  *
  * The runtime half is covered in `useFloatingPanel.spec.tsx`. This is the
  * source half, and it exists because the defect it guards is invisible at
@@ -8,11 +7,9 @@
  * DatePicker measured 262px of calendar under a 289px trigger purely because
  * the call site said `fitContent`.
  *
- * A FIELD-shaped trigger (a control the user reads a value out of) takes
- * `at-least-trigger`. A BUTTON-shaped trigger — an icon, a toolbar chip —
- * legitimately keeps `fit-content`, because matching a 32px button would be
- * absurd; those are listed explicitly so the exemption is a decision rather
- * than an oversight.
+ * Calendar grids take fit-content (MPO-262): a full-width field wrapper is
+ * unrelated to seven day columns and must not create a mostly empty popup.
+ * Text listboxes retain at-least-trigger; icon/button launchers may also hug.
  */
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -22,13 +19,9 @@ import { describe, expect, it } from "vitest";
 const fieldsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "fields");
 
 /** Pickers whose trigger is a form FIELD: the panel may never be narrower. */
-const fieldShapedPickers = [
-  "DatePicker/parts.tsx",
-  "DatePicker/DatetimePicker.catalog.tsx",
-  "TimePicker/catalog.tsx",
-  "ColorPicker/parts.tsx",
-  "Icon/index.tsx",
-];
+const fieldShapedPickers = ["TimePicker/catalog.tsx", "ColorPicker/parts.tsx", "Icon/index.tsx"];
+
+const intrinsicGridPickers = ["DatePicker/parts.tsx", "DatePicker/DatetimePicker.catalog.tsx"];
 
 /** Panels opened from an icon/button trigger, where fit-content is correct. */
 const buttonShapedPickers = ["Geolocation/index.tsx"];
@@ -37,7 +30,11 @@ function read(relative: string): string {
   return readFileSync(resolve(fieldsDir, relative), "utf8");
 }
 
-describe("FloatingPanel width contract (MPO-38)", () => {
+describe("FloatingPanel width contract (MPO-38, MPO-262)", () => {
+  it.each(intrinsicGridPickers)("%s hugs its calendar grid", (relative) => {
+    expect(read(relative)).toContain('widthMode="fit-content"');
+  });
+
   it.each(fieldShapedPickers)("%s declares at-least-trigger", (relative) => {
     const source = read(relative);
     expect(source).toContain('widthMode="at-least-trigger"');

package/src/FormGrid.stories.tsx

@@ -1,9 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Input as TamaguiInput, Paragraph, YStack } from "tamagui";
+import { Paragraph, YStack } from "tamagui";
 import { FieldGroup } from "./FieldGroup";
 import { FormGrid } from "./FormGrid";
 import { FormSection, FormSectionStack } from "./FormSection";
-import { FieldLayout } from "./fieldLayout";
+import { Input } from "./fields/Input";
 
 const meta: Meta<typeof FormGrid> = {
   title: "Forms/FormGrid",
@@ -24,11 +24,7 @@ export default meta;
 type Story = StoryObj<typeof FormGrid>;
 
 function GridField({ id, label }: { id: string; label: string }) {
-  return (
-    <FieldLayout id={id} label={label}>
-      <TamaguiInput id={id} placeholder={label} />
-    </FieldLayout>
-  );
+  return <Input id={id} label={label} placeholder={label} />;
 }
 
 export const Basic: Story = {
@@ -99,13 +95,11 @@ export const LongErrors: Story = {
   render: () => (
     <YStack maxWidth={640}>
       <FormGrid columns={2}>
-        <FieldLayout
+        <Input
           id="fge-a"
           label="With long error"
           error="This validation message is extremely long and should wrap inside its own grid cell without breaking the neighbouring column alignment or overflowing the grid container"
-        >
-          <TamaguiInput id="fge-a" />
-        </FieldLayout>
+        />
         <GridField id="fge-b" label="Neighbour" />
       </FormGrid>
     </YStack>

package/src/FormsIntegration.stories.tsx

@@ -212,9 +212,7 @@ export const multiStepRegistration: Story = {
         />
 
         <FormActions>
-          <Button variant="outlined" onPress={() => setStep("personal")}>
-            Back
-          </Button>
+          <Button onPress={() => setStep("personal")}>Back</Button>
           <Button onPress={() => setStep("verification")}>Next: Verification</Button>
         </FormActions>
       </FormSection>
@@ -240,9 +238,7 @@ export const multiStepRegistration: Story = {
         />
 
         <FormActions>
-          <Button variant="outlined" onPress={() => setStep("contact")}>
-            Back
-          </Button>
+          <Button onPress={() => setStep("contact")}>Back</Button>
           <form.Subscribe selector={(state) => [state.canSubmit, state.isSubmitting]}>
             {([canSubmit, isSubmitting]) => (
               <Button action="submit" disabled={!canSubmit || isSubmitting}>

package/src/InputParts/InputButton.spec.tsx

@@ -40,6 +40,22 @@ describe("Input.Button", () => {
     expect(btn.contains(ring)).toBe(true);
   });
 
+  it("a bare string child is a LABEL, not an icon type to createElement", () => {
+    const result = renderWithProviders(
+      <Input size="$4">
+        <Input.Box size="$4">
+          <Input.Button size="$4" aria-label="cap">
+            Scan
+          </Input.Button>
+        </Input.Box>
+      </Input>,
+    );
+    const btn = result.container.querySelector("[aria-label='cap']") as HTMLElement;
+    expect(btn).not.toBeNull();
+    expect(btn.textContent).toContain("Scan");
+    expect(result.container.querySelector("scan")).toBeNull();
+  });
+
   it("end-cap square is generated from the size recipe at every token", () => {
     for (const token of SIZE_RECIPE_TOKENS) {
       if (token === "$true") continue;

package/src/InputParts/index.tsx

@@ -1,6 +1,6 @@
 import { getFontSized } from "@tamagui/get-font-sized";
 import type { SizeVariantSpreadFunction } from "@tamagui/web";
-import { useEffect, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useState, type ReactNode } from "react";
 import type { ComponentProps, Ref, RefObject } from "react";
 import { Pressable as RNPressable } from "react-native";
 import type {
@@ -1035,6 +1035,33 @@ const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonPr
     size: knobProps.controlIcon.width,
     color: paint as never,
   });
+  // A string/number child is a LABEL, not an icon. `getThemedIcon` treats an
+  // un-elemented child as a component TYPE and `createElement`s it, so "Scan"
+  // becomes an invented `<scan>` element that paints nothing (MPO-208); a bare
+  // string under the glyphRing View is the same category error on native.
+  const textChild =
+    typeof children === "string" || typeof children === "number" ? (
+      <Text
+        {...knobProps.controlType}
+        fontFamily={knobProps.body.fontFamily}
+        fontWeight={knobProps.body.fontWeight}
+        color={paint as never}
+        numberOfLines={1}
+        userSelect="none"
+      >
+        {children}
+      </Text>
+    ) : null;
+  const decorativeRef = useCallback(
+    (node: TamaguiElement | null) => {
+      // Tamagui 2.7.6 Button stamps tabIndex=0 after consumer props.
+      // Correct the host at hydration; decorative caps share the field stop.
+      if (isWeb && node && "tabIndex" in node) node.tabIndex = tabIndexProp ?? -1;
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    },
+    [ref, tabIndexProp],
+  );
 
   if (glyphRing) {
     // A real tab stop must square off the token it was HANDED, not the
@@ -1068,7 +1095,7 @@ const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonPr
           alignItems="center"
           justifyContent="center"
         >
-          {children}
+          {textChild ?? children}
         </View>
       </InputGlyphButton>
     );
@@ -1077,7 +1104,7 @@ const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonPr
   const square = knobProps.control.height;
   return (
     <InputButton
-      ref={ref}
+      ref={decorativeRef}
       size={size}
       height={square}
       width={square}
@@ -1091,7 +1118,7 @@ const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonPr
       data-end-cap={square}
       {...props}
     >
-      {getThemedIcon(children)}
+      {textChild ?? getThemedIcon(children)}
     </InputButton>
   );
 });
@@ -1166,9 +1193,8 @@ export const InputContainerFrame = styled(View, {
 
   variants: {
     size: {
-      "...size": (val, { tokens }) => ({
-        gap: (tokens.space[val] as any)?.val * 0.3,
-      }),
+      // Size is shared with the child parts; layout spacing belongs to space.
+      "...size": () => ({}),
     },
     color: {
       "...color": () => ({}),
@@ -1194,6 +1220,7 @@ const InputContainerImpl = InputContainerFrame.styleable((props, forwardedRef) =
       ref={forwardedRef}
       size={knobProps.sizeToken}
       {...knobProps.body}
+      {...knobProps.gap}
       // LC-06/LC-10 (UX-P12): inside a table cell the field root must adopt
       // the cell width — the raw web <input> carries an intrinsic width that
       // otherwise floors the whole column at ~200px and lays out past the

package/src/InputParts/layoutGap.spec.tsx

@@ -0,0 +1,43 @@
+import { createRef } from "react";
+import { Preset } from "@multiplatform.one/theme";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { afterEach, expect, it } from "vitest";
+import { Input } from "./index";
+
+afterEach(cleanup);
+
+function measure(size: "small" | "medium", space: "small" | "large", gap?: number) {
+  const ref = createRef<HTMLElement>();
+  const { getByTestId } = renderWithProviders(
+    <Preset overrides={{ size, space }}>
+      <Input testID="root" ref={ref as never} {...(gap === undefined ? {} : { gap })}>
+        <Input.Label>Location</Input.Label>
+        <Input.Box>
+          <Input.Area placeholder="Location" />
+        </Input.Box>
+      </Input>
+    </Preset>,
+  );
+  const root = getByTestId("root");
+  expect(ref.current).toBe(root);
+  // Happy DOM leaves token-backed CSS gaps unresolved; browser coverage reads
+  // the actual pixels. Keep this test checking the rendered gap owner.
+  const value =
+    getComputedStyle(root).gap || [...root.classList].find((name) => name.startsWith("_gap-"));
+  expect(value).toBeTruthy();
+  cleanup();
+  return value;
+}
+
+it("lets space change the multi-slot layout gap at a fixed control size", () => {
+  expect(measure("medium", "small")).not.toBe(measure("medium", "large"));
+});
+
+it("keeps the layout gap stable when only control size changes", () => {
+  expect(measure("small", "small")).toBe(measure("medium", "small"));
+});
+
+it("preserves the consumer gap eject and forwarded root ref", () => {
+  expect(measure("medium", "large", 11)).toBe("11px");
+});

package/src/Wheel/Wheel.spec.tsx

@@ -7,6 +7,22 @@ import { Wheel } from "./index";
 afterEach(cleanup);
 
 describe("Wheel contrast contract", () => {
+  it("uses the selected-text weight and keeps rounding on the selection band", () => {
+    renderWithProviders(
+      <Preset overrides={{ borderRadius: "full" }}>
+        <Wheel items={[1, 2, 3, 4, 5]} value={3} visibleItems={5} />
+      </Preset>,
+    );
+    const wheel = screen.getByTestId("wheel");
+    const selected = wheel.querySelector('[data-selected="true"]')?.firstElementChild;
+    expect(selected).toBeTruthy();
+    expect(["700", "bold"]).toContain(getComputedStyle(selected as Element).fontWeight);
+    expect(["", "0px"]).toContain(getComputedStyle(wheel).borderTopLeftRadius);
+    expect(getComputedStyle(screen.getByTestId("wheel-selection")).borderStartStartRadius).not.toBe(
+      "0px",
+    );
+  });
+
   it("keeps inactive item text on the AA $color11 ramp (not opacity-dimmed)", () => {
     renderWithProviders(
       <Wheel items={[1, 2, 3, 4, 5]} value={3} onChange={() => {}} visibleItems={5} />,

package/src/Wheel/index.tsx

@@ -112,7 +112,7 @@ function ensureWheelFocusStyles() {
   const style = document.createElement("style");
   style.id = WHEEL_FOCUS_STYLE_ID;
   style.textContent =
-    ".mp1-wheel-wrapper:focus-visible { outline: 2px solid var(--outlineColor, rgba(0,0,0,0.5)); outline-offset: -2px; }";
+    ".mp1-wheel-wrapper:focus-visible { outline: 2px solid var(--outlineColor, var(--c-outlineColor, CanvasText)); outline-offset: -2px; }";
   document.head.appendChild(style);
 }
 
@@ -847,7 +847,7 @@ export function Wheel<T = string | number>({
       <Text
         {...knobProps.body}
         fontSize={size}
-        fontWeight={isSelected && !disabled ? "600" : "400"}
+        fontWeight={isSelected && !disabled ? "bold" : knobProps.textWeight.fontWeight}
         color={itemColor(isSelected)}
         numberOfLines={1}
         ellipsizeMode="tail"
@@ -865,7 +865,7 @@ export function Wheel<T = string | number>({
       width={flex ? "100%" : columnWidth}
       minWidth={flex ? 0 : columnWidth}
       flex={flex}
-      {...knobProps.containerRadius}
+      borderRadius={0}
       data-testid="wheel"
       data-disabled={disabled ? true : undefined}
       aria-disabled={disabled || undefined}

package/src/fieldFamilyStories.radius.spec.tsx

@@ -0,0 +1,118 @@
+/**
+ * The four form LAYOUT stories must mount house field chrome, not a raw
+ * tamagui primitive.
+ *
+ * FieldLayout, FieldGroup, Fieldset and FormGrid paint no radius of their own —
+ * they are stacks, a grid and a legend. Whatever radius a probe reads off one
+ * of their stories belongs to the CONTROL the story chose to mount. A raw
+ * `Input` from "tamagui" consumes no knobs, so it pins one radius at every
+ * stop and the axis reads dead against a component that never had a say.
+ *
+ * The measurement here is therefore the STORY's, not the component's: walk the
+ * borderRadius knob and assert the control inside each story tracks it.
+ *
+ * Under jsdom the providers inject no CSS and the radius atom keeps its token
+ * reference (`_btlr-t-radius-4`) rather than resolving to `9px`, so this file
+ * gates the token ladder. The pixel ladder (0/5/9/16/50) and the dark scheme
+ * are measured for real by scripts/knob-axis-probe.mjs against a browser.
+ */
+
+import { cleanup } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset, type BorderRadius } from "@multiplatform.one/theme";
+import type { ReactElement } from "react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import * as fieldGroupStories from "./FieldGroup.stories";
+import * as fieldLayoutStories from "./FieldLayout.stories";
+import * as fieldsetStories from "./Fieldset.stories";
+import * as formGridStories from "./FormGrid.stories";
+
+afterEach(cleanup);
+
+/** Knob stop -> radius token index, the `$N` the resolver hands the frame. */
+const ladder: Record<BorderRadius, string> = {
+  none: "0",
+  small: "2",
+  medium: "4",
+  large: "6",
+  full: "12",
+};
+const stops = Object.keys(ladder) as BorderRadius[];
+
+type StoryLike = { render?: (args: Record<string, unknown>) => ReactElement };
+
+/** Every radius token present in the subtree, deduped — the probe's reading. */
+function radiusTokens(container: HTMLElement): string[] {
+  const found = new Set<string>();
+  for (const el of container.querySelectorAll<HTMLElement>("*")) {
+    for (const cls of String(el.className || "").split(/\s+/)) {
+      const match = /^_btlr-t-radius-(\d+)$/.exec(cls);
+      if (match) found.add(match[1]);
+    }
+  }
+  return [...found].sort();
+}
+
+function mountAt(story: StoryLike, meta: { args?: unknown }, stop: BorderRadius) {
+  if (!story.render) throw new Error("story has no render");
+  return renderWithProviders(
+    <Preset overrides={{ borderRadius: stop, elevation: "none" }}>
+      {story.render({ ...((meta.args ?? {}) as Record<string, unknown>) })}
+    </Preset>,
+  );
+}
+
+const family = [
+  {
+    name: "Forms/FieldLayout",
+    story: fieldLayoutStories.Basic as StoryLike,
+    meta: fieldLayoutStories.default,
+  },
+  {
+    name: "Forms/FieldGroup",
+    story: fieldGroupStories.Basic as StoryLike,
+    meta: fieldGroupStories.default,
+  },
+  {
+    name: "Forms/Fieldset",
+    story: fieldsetStories.Default as StoryLike,
+    meta: fieldsetStories.default,
+  },
+  {
+    name: "Forms/FormGrid",
+    story: formGridStories.Basic as StoryLike,
+    meta: formGridStories.default,
+  },
+];
+
+describe("form layout stories mount knob-consuming field chrome", () => {
+  for (const { name, story, meta } of family) {
+    describe(name, () => {
+      // A story that fails to render measures flat on every axis, which reads
+      // exactly like a dead knob. Prove there is a control before believing
+      // anything measured off it.
+      it("renders a text control at all", () => {
+        const { container } = mountAt(story, meta as { args?: unknown }, "medium");
+        expect(container.querySelectorAll("input").length).toBeGreaterThan(0);
+      });
+
+      for (const stop of stops) {
+        it(`takes radius token $${ladder[stop]} at borderRadius:${stop}`, () => {
+          const { container } = mountAt(story, meta as { args?: unknown }, stop);
+          expect(radiusTokens(container)).toContain(ladder[stop]);
+        });
+      }
+
+      it("moves across all five stops instead of pinning one radius", () => {
+        const signatures = stops.map((stop) => {
+          const result = mountAt(story, meta as { args?: unknown }, stop);
+          const tokens = JSON.stringify(radiusTokens(result.container));
+          cleanup();
+          return tokens;
+        });
+        expect(new Set(signatures).size).toBe(stops.length);
+      });
+    });
+  }
+});

package/src/fieldLayout.spec.tsx

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Preset } from "@multiplatform.one/theme";
 import { Input as TamaguiInput } from "tamagui";
-import { FieldLayout } from "./fieldLayout";
+import { FieldLayout, useFieldDescribedBy } from "./fieldLayout";
 import { __resetDevWarnSeen } from "./shared/devWarn";
 
 function classIncludes(container: HTMLElement, fragment: string): boolean {
@@ -188,6 +188,47 @@ describe("FieldLayout error precedence (Axiom 5 eject-last)", () => {
   });
 });
 
+describe("FieldLayout message-before-control anatomy", () => {
+  function Control() {
+    return <input id="ordered" aria-describedby={useFieldDescribedBy()} />;
+  }
+
+  for (const mode of ["top", "side", "compact"] as const) {
+    it(`${mode}: helper and replacement error precede the control and describe only the rendered slot`, () => {
+      const renderField = (error?: string) => (
+        <Preset overrides={{ fieldLabelPlacement: mode === "side" ? "side" : "top" }}>
+          <FieldLayout
+            id="ordered"
+            label="Email"
+            compactSpacing={mode === "compact"}
+            helperText="Use your work address"
+            error={error}
+          >
+            <Control />
+          </FieldLayout>
+        </Preset>
+      );
+      const result = renderWithProviders(renderField());
+      const assertSlot = (id: string, text: string) => {
+        const input = result.container.querySelector("input")!;
+        const message = result.container.querySelector(`#${id}`)!;
+        expect(message.textContent).toBe(text);
+        expect(
+          message.compareDocumentPosition(input) & Node.DOCUMENT_POSITION_FOLLOWING,
+        ).toBeTruthy();
+        expect(input.getAttribute("aria-describedby")).toBe(id);
+        expect(
+          result.container.querySelectorAll("[id$='-description'], [id$='-error']"),
+        ).toHaveLength(1);
+      };
+      assertSlot("ordered-description", "Use your work address");
+      result.rerender(renderField("Enter an email address"));
+      assertSlot("ordered-error", "Enter an email address");
+      expect(result.container.textContent).not.toContain("Use your work address");
+    });
+  }
+});
+
 describe("FieldLayout banned-error-word DEV warn", () => {
   let warnSpy: ReturnType<typeof vi.spyOn>;
 

package/src/fieldLayout.tsx

@@ -218,13 +218,13 @@ export function FieldLayout({
     ...(width !== undefined ? { width } : {}),
   };
 
-  const describedBy =
-    [
-      helperText && id ? `${id}-description` : undefined,
-      errorMessage && id ? `${id}-error` : undefined,
-    ]
-      .filter(Boolean)
-      .join(" ") || undefined;
+  const describedBy = id
+    ? errorMessage
+      ? `${id}-error`
+      : helperText
+        ? `${id}-description`
+        : undefined
+    : undefined;
 
   const a11yLabel = typeof label === "string" ? `${label}${requiredSuffix}` : ariaLabel;
   const a11yDescription = errorMessage ?? helperText;
@@ -293,9 +293,9 @@ export function FieldLayout({
 
   const controlColumn = (
     <YStack flex={sideLabel ? 1 : undefined} {...gapProps}>
-      {children}
       {helperNode}
       {errorNode}
+      {children}
     </YStack>
   );
 
@@ -330,9 +330,9 @@ export function FieldLayout({
           ) : (
             <>
               {labelNode}
-              {children}
               {helperNode}
               {errorNode}
+              {children}
             </>
           )}
         </YStack>

package/src/fields/Barcode/Barcode.spec.tsx

@@ -102,6 +102,8 @@ describe("Barcode", () => {
       const button = result.container.querySelector("[aria-label='Scan barcode']");
       expect(button).not.toBeNull();
       expect(button?.textContent).toContain("Scan");
+      expect(button?.querySelector("scan")).toBeNull();
+      expect(result.container.querySelector("scan")).toBeNull();
     });
 
     it("renders readOnly — hides scan button", () => {

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

@@ -11,6 +11,8 @@
 import { cleanup } from "@testing-library/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { afterEach, describe, expect, it } from "vitest";
+import { createRef } from "react";
+import { FieldLayout } from "../../fieldLayout";
 import { CheckboxFieldFrame } from "./CheckboxFieldFrame";
 
 afterEach(cleanup);
@@ -31,6 +33,22 @@ function frame(container: HTMLElement): HTMLElement {
 }
 
 describe("CheckboxFieldFrame", () => {
+  it("links the rendered field message, forwards its ref, and preserves an explicit description", () => {
+    const ref = createRef<any>();
+    const fixture = (override?: { "aria-describedby": string | undefined }) => (
+      <FieldLayout id="consent" helperText="Read the terms" error="Accept the terms">
+        <CheckboxFieldFrame id="consent" checked={false} ref={ref} {...override} />
+      </FieldLayout>
+    );
+    const result = renderWithProviders(fixture());
+    expect(frame(result.container).getAttribute("aria-describedby")).toBe("consent-error");
+    expect(ref.current).toBe(frame(result.container));
+    result.rerender(fixture({ "aria-describedby": "consumer-description" }));
+    expect(frame(result.container).getAttribute("aria-describedby")).toBe("consumer-description");
+    result.rerender(fixture({ "aria-describedby": undefined }));
+    expect(frame(result.container).getAttribute("aria-describedby")).toBeNull();
+  });
+
   it("still renders a real role=checkbox, so the styling never costs the semantics", () => {
     const { container } = renderWithProviders(<CheckboxFieldFrame checked={false} />);
     expect(frame(container)).toBeTruthy();

package/src/fields/Checkbox/CheckboxFieldFrame.tsx

@@ -1,7 +1,8 @@
 import { Checkbox as TamaguiCheckbox, styled } from "tamagui";
+import { useFieldDescribedBy } from "../../fieldLayout";
 
 /** Hit-target frame. The painted box is CheckboxGlyphBox (LC-71). */
-export const CheckboxFieldFrame = styled(TamaguiCheckbox, {
+const CheckboxFieldFrameBase = styled(TamaguiCheckbox, {
   backgroundColor: "transparent",
   borderColor: "transparent",
   borderWidth: 0,
@@ -21,3 +22,7 @@ export const CheckboxFieldFrame = styled(TamaguiCheckbox, {
   },
   activeStyle: { backgroundColor: "transparent", borderColor: "transparent" },
 });
+
+export const CheckboxFieldFrame = CheckboxFieldFrameBase.styleable((props, ref) => (
+  <CheckboxFieldFrameBase aria-describedby={useFieldDescribedBy()} {...props} ref={ref} />
+));