@recursica/adapter-mui-v7 1.3.2 → 1.3.4

package/dist/index.d.ts

@@ -985,18 +985,23 @@ export declare const Panel: PanelComponent;
  * </Panel>
  * ```
  *
+ * Always non-modal, with no props to change it: the page behind stays usable
+ * (no overlay, focus trap, scroll lock, `aria-modal` or `aria-hidden` on the
+ * rest of the page), focus returns to the opener on close, Escape always
+ * closes, and outside clicks never do. Implemented with MUI's `persistent`
+ * Drawer variant (no Modal) plus an Escape listener and focus restoration.
+ *
  * Mui Drawer sub-components available via dot-notation:
  * - `Panel.Header` — Top section with title and close button
  * - `Panel.Title` — Title text within the header
  * - `Panel.CloseButton` — Close button within the header
  * - `Panel.Body` — Scrollable body content area
  * - `Panel.Content` — Outer content container
- * - `Panel.Overlay` — Background overlay
  * - `Panel.Root` — Root element for advanced composition
  * - `Panel.Stack` — Stacked drawer context
  */
 declare const PanelBase: {
-    ({ overStyled, placement, keepMounted, wrapHeaderText, opened, title, withOverlay, withCloseButton, onClose, children, ...rest }: PanelProps): JSX.Element;
+    ({ overStyled, placement, keepMounted, wrapHeaderText, opened, title, withCloseButton, onClose, children, ...rest }: PanelProps): JSX.Element;
     displayName: string;
 };
 
@@ -1208,11 +1213,9 @@ export declare interface RecursicaNumberInputProps extends Omit<InputBaseProps,
 /**
  * Recursica Panel root props. Extends Mui Drawer.
  */
-export declare interface RecursicaPanelProps extends Omit<DrawerProps, "classes" | "position" | "style" | "anchor" | "open" | "title">, RecursicaPanelProps_2 {
+export declare interface RecursicaPanelProps extends Omit<DrawerProps, "classes" | "position" | "style" | "anchor" | "open" | "title" | "variant" | "hideBackdrop" | "ModalProps" | "BackdropComponent" | "BackdropProps" | "disableEscapeKeyDown" | "disableScrollLock" | "disableEnforceFocus" | "disableAutoFocus" | "disableRestoreFocus">, RecursicaPanelProps_2 {
     /** Panel header title label. */
     title?: ReactNode;
-    /** Whether to display a background overlay. Default true. */
-    withOverlay?: boolean;
     /** Whether to display the close button in the header. Default true. */
     withCloseButton?: boolean;
 }

package/docs/PHILOSOPHY.md

@@ -4,6 +4,10 @@ Recursica's component architecture isn't just a wrapper; it's a strict enforcing
 
 This document serves as the governing framework for why the `adapter-mui-v7` components are built the way they are.
 
+## Why an Adapter?
+
+Most companies already have an existing component library or use an existing UI kit, and switching to a different kit means painful refactoring. Rather than replace MUI, this adapter adapts to its API surface while enforcing the behaviors and styling Recursica defines for a consistent UX. You don't ship two separate UI kits, and you can migrate to Recursica systematically, over time.
+
 ## 1. Strict Separation of Props (The Unified Recursica Prop Layer)
 
 Recursica has a **single universal API surface** internally regardless of whether we use MUI or another underlying UI library.

package/package.json

@@ -12,7 +12,7 @@
     "type": "git",
     "url": "git+https://github.com/borderux/recursica-adapter-mui-v7.git"
   },
-  "version": "1.3.2",
+  "version": "1.3.4",
   "publishConfig": {
     "access": "public"
   },
@@ -31,18 +31,14 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.stories.tsx",
     "CHANGELOG.md",
-    ".storybook/commonArgTypes.ts",
     "llms.txt",
     "USAGE.md",
     "ARCHITECTURE.md",
     "SETUP.md",
     "OVERSTYLING.md",
-    "docs/PHILOSOPHY.md",
-    "recursica_variables_scoped.css",
-    "recursica_brand.json",
-    "recursica_tokens.json",
-    "recursica_ui-kit.json"
+    "docs/PHILOSOPHY.md"
   ],
   "keywords": [
     "react",
@@ -85,7 +81,7 @@
     "@playwright/test": "^1.62.1",
     "@recursica/adapter-tester": "^5.3.1",
     "@recursica/recursica-postcss-vars": "^1.5.0",
-    "@recursica/storybook-template": "^0.7.15",
+    "@recursica/storybook-template": "^0.7.16",
     "@recursica/token-analyzer": "^1.8.0",
     "@storybook/addon-a11y": "^10.3.3",
     "@storybook/addon-docs": "^10.3.3",

package/src/components/Checkbox/CHECKBOX_IMPLEMENTATION_NOTES.md

@@ -12,3 +12,7 @@ is no group-level max-width token in the schema (`checkbox-group_variants_layout
 covers gutter/margin/padding) — fixed by leaving `controlMaxWidth` `undefined`, matching
 `SwitchGroup`'s existing pattern. Same bug existed in `RadioGroup`, fixed the same way.
 Mirrors the identical fix in mantine-adapter (source of truth).
+
+### Accessible name lands on the native `<input>` (2026-10-15)
+
+`RequireAccessibleLabel` enforces a name at compile time (`label`, `aria-label` or `aria-labelledby`). MUI spreads unknown props onto the outer span, so `aria-label`/`aria-labelledby`/`aria-describedby` never reached the `<input>`, and a `label` with no `id` left `<label htmlFor>` unlinked. `useNativeInputA11y` (`src/utils`) moves the aria attributes to `slotProps.input` and generates an `id` for labelled controls. Same fix in Checkbox, Radio and Switch. Covered by `src/components/NativeInputA11y.dom.test.tsx`. Mantine already behaves this way natively and has the same test.

package/src/components/Checkbox/Checkbox.module.css

@@ -66,6 +66,7 @@
   align-items: center;
   justify-content: center;
   margin: 0; /* HARDCODE: structural reset */
+  padding: 0; /* HARDCODE: drops MUI's 9px SwitchBase padding, which would crush the box inside the fixed size */
   width: var(--recursica_ui-kit_components_checkbox_properties_size);
   height: var(--recursica_ui-kit_components_checkbox_properties_size);
   /* Apply font-size to this element so that an 'em' based line-height token evaluates to the correct exact pixel value. */

package/src/components/Checkbox/Checkbox.tsx

@@ -21,6 +21,7 @@ import {
 } from "../FormControlLayout/FormControlLayout";
 import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 
+import { useNativeInputA11y } from "../../utils/useNativeInputA11y";
 import styles from "./Checkbox.module.css";
 
 export type CheckboxWrapperProps = Omit<MuiCheckboxProps, "size" | "color"> &
@@ -67,9 +68,12 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
       "color", // Colors are token-driven; MUI's native palette isn't exposed
     ] as const satisfies readonly (keyof MuiCheckboxProps)[];
 
-    const sanitizedProps = omitUnsupportedProps(
-      filterStylingProps(rest, overStyled),
-      UNSUPPORTED_PROPS,
+    const sanitizedProps = useNativeInputA11y(
+      omitUnsupportedProps(
+        filterStylingProps(rest, overStyled),
+        UNSUPPORTED_PROPS,
+      ),
+      !!label,
     );
     const restRecord = sanitizedProps as Record<string, unknown>;
 
@@ -175,7 +179,6 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
         {...(isControlled ? { checked: isChecked as boolean } : {})}
         onChange={handleChange}
         disableRipple
-        sx={label ? { padding: 0 } : undefined}
         icon={<div className={styles.input} />}
         checkedIcon={
           <div className={`${styles.input} ${styles.inputChecked}`}>

package/src/components/Heading/HEADING_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,10 @@
+# Heading – Implementation Notes
+
+## Heading owns semantic `h1`-`h6` (Matt Massey, 2026-10-08)
+
+**Decision:** `Heading` is the only component that renders semantic `<h1>`-`<h6>` elements. Each
+`order` maps to a heading level that Recursica and Forge define and style
+(`recursica_brand_typography_h{order}`).
+
+**Implementation:** Heading's styles are fixed by the Recursica JSON/CSS. Do not add variants to
+Heading. Any other kind of text belongs in `Text`, which throws if asked to render `h1`-`h6`.

package/src/components/Modal/Modal.module.css

@@ -38,6 +38,9 @@
     --recursica_ui-kit_components_modal_properties_border-radius
   );
   overflow: hidden;
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_content-background-color
+  );
 }
 
 .content {
@@ -80,7 +83,9 @@
     var(
       --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
     );
-  background-color: transparent; /* Inherit from content */
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_header-background-color
+  );
 }
 
 .title {
@@ -209,7 +214,9 @@
     var(
       --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
     );
-  background-color: transparent;
+  background-color: var(
+    --recursica_ui-kit_components_modal_properties_colors_footer-background-color
+  );
   display: flex;
   justify-content: flex-end;
   gap: var(--recursica_ui-kit_components_modal_properties_button-gap);

package/src/components/NativeInputA11y.dom.test.tsx

@@ -0,0 +1,59 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { Checkbox } from "./Checkbox/Checkbox";
+import { Radio } from "./Radio/Radio";
+import { Switch } from "./Switch/Switch";
+const wrap = (n: React.ReactElement) => n;
+
+// Where the naming attributes land matters, not just that they render: a screen reader reads
+// the native <input>, so aria-* on a wrapper leaves the control unnamed.
+function render(node: React.ReactElement): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  flushSync(() => createRoot(container).render(wrap(node)));
+  return container;
+}
+
+const controls = [
+  ["Checkbox", Checkbox],
+  ["Radio", Radio],
+  ["Switch", Switch],
+] as const;
+
+describe.each(controls)("%s accessible name", (_name, Control) => {
+  // The union type under test is already enforced at compile time; cast to exercise each branch.
+  const C = Control as unknown as React.ComponentType<Record<string, unknown>>;
+
+  it("puts aria-label on the native input only", () => {
+    const c = render(<C aria-label="Select all" />);
+    expect(c.querySelector("input")!.getAttribute("aria-label")).toBe(
+      "Select all",
+    );
+    expect(c.querySelectorAll("[aria-label]")).toHaveLength(1);
+  });
+
+  it("puts aria-labelledby and aria-describedby on the native input only", () => {
+    const c = render(<C aria-labelledby="a" aria-describedby="b" />);
+    const input = c.querySelector("input")!;
+    expect(input.getAttribute("aria-labelledby")).toBe("a");
+    expect(input.getAttribute("aria-describedby")).toBe("b");
+    expect(c.querySelectorAll("[aria-labelledby]")).toHaveLength(1);
+    expect(c.querySelectorAll("[aria-describedby]")).toHaveLength(1);
+  });
+
+  it("links a visible label to the input without a caller-supplied id", () => {
+    const c = render(<C label="Hello" />);
+    const input = c.querySelector("input")!;
+    const label = c.querySelector("label")!;
+    expect(input.id).not.toBe("");
+    expect(label.getAttribute("for")).toBe(input.id);
+  });
+
+  it("keeps a caller-supplied id", () => {
+    const c = render(<C label="Hello" id="mine" />);
+    expect(c.querySelector("input")!.id).toBe("mine");
+    expect(c.querySelector("label")!.getAttribute("for")).toBe("mine");
+  });
+});

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -131,3 +131,11 @@ clips descenders (e.g. the "g" in a long title) whenever `text_line-height` is t
 font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
 truncation, but ink can bleed slightly past the line box before it's actually clipped.
 Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.
+
+---
+
+## 10. Always non-modal (Matt Massey, 2026-10-08)
+
+**Decision:** Panel is never modal, and there are no props to change that.
+
+**Implementation:** The house rule is that the page behind a panel stays usable. `Panel.tsx` always renders MUI's Drawer with `variant="persistent"` (after the caller's props), which has no Modal: no backdrop, no focus trap, no scroll lock, no `aria-modal`, and no `aria-hidden` on the rest of the page. Because there is no Modal, `Panel.tsx` supplies the rest itself: a document `keydown` listener (while open) calls `onClose` on Escape, and focus returns to the opener (the element focused at open) on close. Escape is independent of outside clicks and always closes the panel; clicking the page behind never does. `withOverlay` and MUI's `variant`, `hideBackdrop`, `ModalProps`, `BackdropProps`/`BackdropComponent` and `disable*` (escape, scroll lock, enforce focus, auto focus, restore focus) props are omitted from `RecursicaPanelProps`. Every adapter must match.

package/src/components/Panel/Panel.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, type ReactNode } from "react";
+import { forwardRef, useEffect, useRef, type ReactNode } from "react";
 import {
   Drawer as MuiDrawer,
   type DrawerProps as MuiDrawerProps,
@@ -23,13 +23,26 @@ import { type RecursicaPanelProps as BaseRecursicaPanelProps } from "@recursica/
 export interface RecursicaPanelProps
   extends Omit<
       MuiDrawerProps,
-      "classes" | "position" | "style" | "anchor" | "open" | "title"
+      | "classes"
+      | "position"
+      | "style"
+      | "anchor"
+      | "open"
+      | "title"
+      | "variant"
+      | "hideBackdrop"
+      | "ModalProps"
+      | "BackdropComponent"
+      | "BackdropProps"
+      | "disableEscapeKeyDown"
+      | "disableScrollLock"
+      | "disableEnforceFocus"
+      | "disableAutoFocus"
+      | "disableRestoreFocus"
     >,
     BaseRecursicaPanelProps {
   /** Panel header title label. */
   title?: ReactNode;
-  /** Whether to display a background overlay. Default true. */
-  withOverlay?: boolean;
   /** Whether to display the close button in the header. Default true. */
   withCloseButton?: boolean;
 }
@@ -68,13 +81,18 @@ const CloseIcon = () => (
  * </Panel>
  * ```
  *
+ * Always non-modal, with no props to change it: the page behind stays usable
+ * (no overlay, focus trap, scroll lock, `aria-modal` or `aria-hidden` on the
+ * rest of the page), focus returns to the opener on close, Escape always
+ * closes, and outside clicks never do. Implemented with MUI's `persistent`
+ * Drawer variant (no Modal) plus an Escape listener and focus restoration.
+ *
  * Mui Drawer sub-components available via dot-notation:
  * - `Panel.Header` — Top section with title and close button
  * - `Panel.Title` — Title text within the header
  * - `Panel.CloseButton` — Close button within the header
  * - `Panel.Body` — Scrollable body content area
  * - `Panel.Content` — Outer content container
- * - `Panel.Overlay` — Background overlay
  * - `Panel.Root` — Root element for advanced composition
  * - `Panel.Stack` — Stacked drawer context
  */
@@ -85,13 +103,37 @@ const PanelBase = function Panel({
   wrapHeaderText = true,
   opened,
   title,
-  withOverlay = true,
   withCloseButton = true,
   onClose,
   children,
   ...rest
 }: PanelProps) {
   const sanitizedProps = filterStylingProps(rest, overStyled);
+  const isOpen = Boolean(opened);
+  const openerRef = useRef<HTMLElement | null>(null);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  // Non-modal: there is no Modal to handle Escape or focus restoration, so do both here.
+  useEffect(() => {
+    if (!isOpen) return;
+    openerRef.current = document.activeElement as HTMLElement | null;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onCloseRef.current?.(
+          e as unknown as React.SyntheticEvent,
+          "escapeKeyDown",
+        );
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      const opener = openerRef.current;
+      if (opener && opener.isConnected) opener.focus();
+      openerRef.current = null;
+    };
+  }, [isOpen]);
 
   // MUI Drawer's `classes` prop only recognizes its own slot names (`root`, `paper`,
   // `docked`, ...) — unlike Mantine's `classNames`, it has no `content`/`header`/`title`/`body`
@@ -113,10 +155,10 @@ const PanelBase = function Panel({
     <MuiDrawer
       anchor={placement} /* Recursica default: right; Mui default: left */
       keepMounted={keepMounted}
-      open={Boolean(opened)}
-      onClose={onClose}
-      hideBackdrop={!withOverlay}
+      open={isOpen}
       {...(sanitizedProps as unknown as MuiDrawerProps)}
+      /* Always non-modal: persistent variant has no backdrop, focus trap, scroll lock or aria-modal */
+      variant="persistent"
       classes={mergedClassNames as unknown as MuiDrawerProps["classes"]}
     >
       <div

package/src/components/Radio/RADIO_IMPLEMENTATION_NOTES.md

@@ -10,3 +10,7 @@ layout the group's own label got squeezed into that same 400px alongside the rad
 no group-level max-width token in the schema — fixed by leaving `controlMaxWidth` `undefined`,
 matching `SwitchGroup`'s existing pattern. Same bug existed in `CheckboxGroup`, fixed the same
 way. Mirrors the identical fix in mantine-adapter (source of truth).
+
+### Accessible name lands on the native `<input>` (2026-10-15)
+
+`RequireAccessibleLabel` enforces a name at compile time (`label`, `aria-label` or `aria-labelledby`). MUI spreads unknown props onto the outer span, so `aria-label`/`aria-labelledby`/`aria-describedby` never reached the `<input>`, and a `label` with no `id` left `<label htmlFor>` unlinked. `useNativeInputA11y` (`src/utils`) moves the aria attributes to `slotProps.input` and generates an `id` for labelled controls. Same fix in Checkbox, Radio and Switch. Covered by `src/components/NativeInputA11y.dom.test.tsx`. Mantine already behaves this way natively and has the same test.

package/src/components/Radio/Radio.module.css

@@ -75,6 +75,7 @@
   align-items: center;
   justify-content: center;
   margin: 0; /* HARDCODE: structural reset */
+  padding: 0; /* HARDCODE: drops MUI's 9px SwitchBase padding, which would crush the circle inside the fixed size */
   width: var(--recursica_ui-kit_components_radio-button_properties_size);
   height: var(--recursica_ui-kit_components_radio-button_properties_size);
   /* Apply font-size to this element so that an 'em' based line-height token evaluates to the correct exact pixel value. */

package/src/components/Radio/Radio.tsx

@@ -21,6 +21,7 @@ import {
 } from "../FormControlLayout/FormControlLayout";
 import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
 
+import { useNativeInputA11y } from "../../utils/useNativeInputA11y";
 import styles from "./Radio.module.css";
 
 const RadioIcon: React.FC<{
@@ -81,9 +82,12 @@ export const Radio = forwardRef<HTMLInputElement, RadioProps>(
       "color", // Colors are token-driven; MUI's native palette isn't exposed
     ] as const satisfies readonly (keyof MuiRadioProps)[];
 
-    const sanitizedProps = omitUnsupportedProps(
-      filterStylingProps(rest, overStyled),
-      UNSUPPORTED_PROPS,
+    const sanitizedProps = useNativeInputA11y(
+      omitUnsupportedProps(
+        filterStylingProps(rest, overStyled),
+        UNSUPPORTED_PROPS,
+      ),
+      !!label,
     );
     const restRecord = sanitizedProps as Record<string, unknown>;
 
@@ -159,7 +163,6 @@ export const Radio = forwardRef<HTMLInputElement, RadioProps>(
         classes={mergedClassNames}
         disabled={readOnly || disabled}
         disableRipple
-        sx={label ? { padding: 0 } : undefined}
       />
     );
 

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -145,3 +145,7 @@ pattern, not a MUI-only bug). Fixed by not capping the group's control width at
 switch's own label already wraps at 200px via `.labelWrapper`, so no group-level cap is needed.
 Verified live in both adapters: side-by-side now shows the label column at left with the
 switches beside it; stacked layout unaffected.
+
+### Accessible name lands on the native `<input>` (2026-10-15)
+
+`RequireAccessibleLabel` enforces a name at compile time (`label`, `aria-label` or `aria-labelledby`). MUI spreads unknown props onto the outer span, so `aria-label`/`aria-labelledby`/`aria-describedby` never reached the `<input>`, and a `label` with no `id` left `<label htmlFor>` unlinked. `useNativeInputA11y` (`src/utils`) moves the aria attributes to `slotProps.input` and generates an `id` for labelled controls. Same fix in Checkbox, Radio and Switch. Covered by `src/components/NativeInputA11y.dom.test.tsx`. Mantine already behaves this way natively and has the same test.

package/src/components/Switch/Switch.tsx

@@ -20,6 +20,7 @@ import {
   type FormControlLayoutProps,
 } from "../FormControlLayout/FormControlLayout";
 import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
+import { useNativeInputA11y } from "../../utils/useNativeInputA11y";
 import styles from "./Switch.module.css";
 
 import { SwitchGroup, SwitchGroupContext } from "./SwitchGroup";
@@ -110,9 +111,12 @@ export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
       "color", // Recursica hardcodes color="default" below; MUI's palette-driven colors are unused
     ] as const satisfies readonly (keyof MuiSwitchProps)[];
 
-    const sanitizedProps = omitUnsupportedProps(
-      filterStylingProps(rest, overStyled),
-      UNSUPPORTED_PROPS,
+    const sanitizedProps = useNativeInputA11y(
+      omitUnsupportedProps(
+        filterStylingProps(rest, overStyled),
+        UNSUPPORTED_PROPS,
+      ),
+      !!label,
     );
     const restRecord = sanitizedProps as Record<string, unknown>;
 

package/src/components/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -18,3 +18,15 @@ accepts any string since `@recursica/adapter-common` 1.2.0). In development, `Te
 if absent it logs one `console.error` per name and sets `data-typography-missing`, which
 `Typography.module.css` hides with `visibility: hidden`. The attribute is never set when
 `NODE_ENV === "production"`.
+
+## Text must never render `h1`-`h6` (Matt Massey, 2026-10-08)
+
+**Decision:** `Text` must never render an `<h1>`-`<h6>` element. It is not allowed. Semantic
+headings use `Heading`.
+
+**Implementation:** `Text` covers every other kind of text in the system (body, labels, captions,
+etc.). Its variants can extend what the Recursica JSON and CSS define, so a variant need not
+exist in the Recursica tokens. Heading levels are the one thing `Text` can't be: they have a
+fixed definition and styling from Recursica and Forge, owned by `Heading`. `Text.tsx` throws
+`Text cannot render <hN>. Use <Heading> for semantic h1-h6.` when `component` (or
+`variantMapping.inherit`, which MUI uses to pick the element) is `h1`-`h6`.

package/src/components/Text/Text.headings.dom.test.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import { describe, it, expect, vi } from "vitest";
+import { createRoot } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { Text } from "./Text";
+
+class Boundary extends React.Component<
+  { children: React.ReactNode },
+  { message: string | null }
+> {
+  state = { message: null as string | null };
+  static getDerivedStateFromError(error: Error) {
+    return { message: error.message };
+  }
+  render() {
+    return this.state.message ?? this.props.children;
+  }
+}
+
+function render(props: Record<string, unknown>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  flushSync(() =>
+    createRoot(container).render(
+      <Boundary>
+        <Text {...(props as object)}>Content</Text>
+      </Boundary>,
+    ),
+  );
+  return container;
+}
+
+describe("Text heading elements", () => {
+  it.each(["h1", "h2", "h3", "h4", "h5", "h6"])(
+    "throws when component is %s",
+    (component) => {
+      vi.spyOn(console, "error").mockImplementation(() => {});
+      expect(render({ component }).textContent).toContain(
+        `Text cannot render <${component}>. Use <Heading> for semantic h1-h6.`,
+      );
+    },
+  );
+
+  it("throws when variantMapping maps to a heading", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(render({ variantMapping: { inherit: "h2" } }).textContent).toContain(
+      "Text cannot render <h2>.",
+    );
+  });
+
+  it.each(["p", "span", "label"])("renders component=%s", (component) => {
+    expect(render({ component }).querySelector(component)).not.toBeNull();
+  });
+});

package/src/components/Text/Text.tsx

@@ -11,10 +11,26 @@ export type TextProps = RecursicaOverStyled<
   "color"
 >;
 
+const HEADING_ELEMENTS = ["h1", "h2", "h3", "h4", "h5", "h6"];
+
 export const Text = forwardRef<HTMLElement, TextProps>(function Text(
   { variant = "body", emphasis = "high", color = "default", ...rest },
   ref,
 ) {
+  // Text never renders semantic h1-h6; those belong to Heading. MUI picks the element from
+  // `component`, or (for variant "inherit") from `variantMapping.inherit`, so check both.
+  const { component, variantMapping } = rest as {
+    component?: unknown;
+    variantMapping?: Record<string, unknown>;
+  };
+  for (const element of [component, variantMapping?.inherit]) {
+    if (typeof element === "string" && HEADING_ELEMENTS.includes(element)) {
+      throw new Error(
+        `Text cannot render <${element}>. Use <Heading> for semantic h1-h6.`,
+      );
+    }
+  }
+
   // Dev only: an unknown variant hides the text (and logs) instead of silently rendering with the
   // UI kit's default styling.
   const typographyMissing =

package/src/utils/useNativeInputA11y.ts

@@ -0,0 +1,43 @@
+import { useId } from "react";
+
+const INPUT_ARIA_KEYS = [
+  "aria-label",
+  "aria-labelledby",
+  "aria-describedby",
+] as const;
+
+/**
+ * MUI's Checkbox/Radio/Switch spread unknown props (including `aria-*`) onto the outer span,
+ * so a screen reader never sees them on the native `<input>`. Moves the naming attributes to
+ * `slotProps.input`, and guarantees a labelled control has an `id` so `<label htmlFor>` links.
+ */
+export function useNativeInputA11y<T extends object>(
+  props: T,
+  hasLabel: boolean,
+): T {
+  const generatedId = useId();
+  const source = { ...props } as Record<string, unknown>;
+  const slotProps = (source.slotProps ?? {}) as Record<string, unknown>;
+  if (typeof slotProps.input === "function") {
+    throw new Error(
+      "slotProps.input must be an object; function form is not supported",
+    );
+  }
+  const input = { ...(slotProps.input as object | undefined) } as Record<
+    string,
+    unknown
+  >;
+
+  for (const key of INPUT_ARIA_KEYS) {
+    if (key in source) {
+      input[key] = source[key];
+      delete source[key];
+    }
+  }
+  if (hasLabel && source.id === undefined) source.id = generatedId;
+
+  if (Object.keys(input).length > 0) {
+    source.slotProps = { ...slotProps, input };
+  }
+  return source as T;
+}