@recursica/mantine-adapter 0.55.0 → 0.55.2

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.55.0",
+  "version": "0.55.2",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",
@@ -103,7 +103,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.28.0"
+    "@recursica/adapter-common": "^0.28.2"
   },
   "peerDependencies": {
     "@mantine/core": "^8.0.0",

package/src/components/Accordion/Accordion.stories.tsx

@@ -1,6 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Accordion } from "./Accordion";
-import { Layer } from "@recursica/adapter-common";
 
 const SVGIcon = () => (
   <svg
@@ -188,26 +187,3 @@ export const Disabled: StoryObj<typeof Accordion> = {
     );
   },
 };
-
-/** Demonstrates the component nested inside a non-default layer — the one case where an
- * explicit `<Layer>` wrap belongs in a story (see COMPONENT_STORYBOOK_GUIDE.md §9). */
-export const LayerOne: StoryObj<typeof Accordion> = {
-  render: () => {
-    return (
-      <Layer layer={1} style={{ padding: "24px" }}>
-        <Accordion defaultValue="demo" chevron={<ChevronIcon />}>
-          <Accordion.Item value="demo">
-            <Accordion.Control leftIcon={<SVGIcon />}>
-              Layer 1 Render Engine
-            </Accordion.Control>
-            <Accordion.Panel>
-              This Accordion dynamically updates its colors, borders, and
-              typography variables because it is wrapped securely by the
-              simulated `data-recursica-layer="1"`.
-            </Accordion.Panel>
-          </Accordion.Item>
-        </Accordion>
-      </Layer>
-    );
-  },
-};

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

@@ -38,9 +38,7 @@ export const DefaultHelp: Story = {
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
-    <Layer layer={0} style={{ padding: "48px" }}>
-      <AssistiveElement {...args} />
-    </Layer>
+    <AssistiveElement {...args} />
   ),
 };
 
@@ -53,9 +51,7 @@ export const ErrorState: Story = {
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
-    <Layer layer={0} style={{ padding: "48px" }}>
-      <AssistiveElement {...args} />
-    </Layer>
+    <AssistiveElement {...args} />
   ),
 };
 
@@ -68,8 +64,6 @@ export const NoIconHelp: Story = {
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (
-    <Layer layer={0} style={{ padding: "48px" }}>
-      <AssistiveElement {...args} />
-    </Layer>
+    <AssistiveElement {...args} />
   ),
 };

package/src/components/Avatar/Avatar.stories.tsx

@@ -1,7 +1,6 @@
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Avatar } from "./Avatar";
-import { Layer } from "@recursica/adapter-common";
 
 type AvatarStoryProps = React.ComponentProps<typeof Avatar>;
 
@@ -91,17 +90,3 @@ export const IconSmallGhost: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Avatar {...args} />,
 };
-
-export const LayerOneOutline: Story = {
-  args: {
-    children: "L1",
-    variant: "outline",
-    size: "default",
-  },
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
-  render: ({ withLayer, layer, ...args }: any) => (
-    <Layer layer={1} style={{ padding: "24px", display: "inline-block" }}>
-      <Avatar {...args} />
-    </Layer>
-  ),
-};

package/src/components/Breadcrumb/BREADCRUMB_IMPLEMENTATION_NOTES.md

@@ -12,3 +12,36 @@ We attach `gap` to `.root` directly within `.module.css`. Mantine's inner `separ
 
 We preserve standard hierarchical composition based on Mantine's defaults. The component natively accepts typical anchor tags as children without wrapping them in structural spans, allowing developers to utilize `Link` wrappers as needed contextually.
 The separator character is inherited natively from Mantine's default configuration (`/`) unless overridden by passing `separator={<Icon />}` to the component props.
+
+## Current-page Crumb: Best-effort Enforcement, Not a Guarantee
+
+**The last crumb should always be plain, non-interactive text — a `<span>`, not a `Link`.** It
+represents the current page; per standard breadcrumb UX and the ARIA breadcrumb pattern, it
+shouldn't be clickable. Passing a `Link` (or an anchor) for the last item is a misuse of the
+component, even though `Breadcrumb.tsx` tries to correct for it — see below.
+
+Breadcrumb intentionally keeps the flexible Mantine `children`-as-anchors interface (unlike BEAM's
+`Breadcrumb.Item`, which renders its own `Link` internally and can't accept a caller-supplied
+router-aware Link or `onClick`). That flexibility means Breadcrumb.tsx can't fully own what the
+last item renders as, so it does what it can via `markCurrentPageItem` (`@recursica/adapter-common`):
+
+- Adds `aria-current="page"` to the last child, always.
+- If that child looks interactive (has `href` or `onClick`), strips both and sets `tabIndex={-1}`.
+- In dev, warns to the console when it had to strip anything — a signal the caller should switch
+  that item to plain text instead of relying on this fallback.
+
+Backed up by a CSS rule targeting `[aria-current="page"]` (Breadcrumb.module.css) that resets
+color/text-decoration and sets `pointer-events: none`, and sets `font-family`/`font-size` to Link's own tokens
+(per product decision: the current item should typographically match Link, just without Link's
+color/decoration/interactivity).
+
+**Why this isn't a real guarantee:** `cloneElement` can only override props an element actually
+reads. A custom Link component (e.g. React Router's `<Link to="...">`) that navigates from its own
+internal handler, independent of a passed-through `onClick`, will still navigate — stripping
+`onClick`/`href` here doesn't touch that internal logic, and `pointer-events: none` only blocks
+mouse activation, not keyboard/Enter on a focusable custom element. Treat all of the above as a
+safety net for the common case (plain anchors, our own `Link`), not a substitute for callers doing
+the right thing and passing plain text for the last crumb.
+
+The story's `items` convenience prop demonstrates the correct pattern: every crumb except the last
+is wrapped in `Link`, and the last is a plain `<span>`.

package/src/components/Breadcrumb/Breadcrumb.module.css

@@ -26,3 +26,23 @@
   /* Neutralize Mantine's built-in margin-inline (--mantine-spacing-xs default) so .root's gap alone controls spacing */
   margin-inline: 0;
 }
+
+/* Current-page item (last crumb): Breadcrumb.tsx (via markCurrentPageItem) marks it
+   aria-current="page". This is a style-layer backstop in case that item still renders as a Link
+   despite having its href/onClick stripped — see BREADCRUMB_IMPLEMENTATION_NOTES.md. Two classes'
+   worth of specificity beats Link's single .root color/text-decoration rule regardless of module
+   load order. pointer-events only blocks mouse activation, not a router Link's own internal
+   handler — the last crumb should really just be plain text. */
+.root [aria-current="page"] {
+  color: inherit;
+  text-decoration: none;
+  pointer-events: none;
+
+  /* Per product decision: the current-page item should match Link's font-family/size (it's
+     typically rendered as plain text, with no font styling of its own — otherwise it falls back
+     to Mantine's default font-size) but not any of Link's other styling. */
+  font-family: var(
+    --recursica_ui-kit_components_link_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_link_properties_text_font-size);
+}

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -11,6 +11,18 @@ const meta: Meta<BreadcrumbStoryProps> = {
   title: "UI-Kit/Breadcrumb",
   component: Breadcrumb,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "**Proper usage** (see `Default`): every crumb except the last is a `Link`; the last " +
+          "crumb — the current page — is plain text (e.g. a `<span>`), not a link. `Breadcrumb` " +
+          "does its best to neutralize a `Link` passed as the last item anyway (see " +
+          "`LastItemAsLink`), but that's a safety net, not something to rely on — see " +
+          "BREADCRUMB_IMPLEMENTATION_NOTES.md.",
+      },
+    },
+  },
   argTypes: {
     children: {
       table: {
@@ -35,11 +47,17 @@ const meta: Meta<BreadcrumbStoryProps> = {
   },
   render: ({ items, children, ...args }) => {
     const mappedChildren = items
-      ? items.map((label, index) => (
-          <Link href="#" key={index}>
-            {label}
-          </Link>
-        ))
+      ? items.map((label, index) =>
+          // The last crumb represents the current page, so it's plain text,
+          // not a link — matches standard breadcrumb UX.
+          index === items.length - 1 ? (
+            <span key={index}>{label}</span>
+          ) : (
+            <Link href="#" key={index}>
+              {label}
+            </Link>
+          ),
+        )
       : children;
 
     return <Breadcrumb children={mappedChildren} {...args} />;
@@ -62,3 +80,35 @@ export const CustomSeparator: Story = {
     separator: "→",
   },
 };
+
+export const LastItemAsLink: Story = {
+  name: "Last Item As Link (Incorrect Usage)",
+  args: {
+    // Bypass the `items` convenience prop (which always renders the last crumb as a span) to
+    // demonstrate what happens if a caller wraps every crumb, including the last, in a `Link`.
+    items: undefined,
+    children: [
+      <Link href="#" key="dashboard">
+        Dashboard
+      </Link>,
+      <Link href="#" key="settings">
+        Settings
+      </Link>,
+      <Link href="#" key="security">
+        Security
+      </Link>,
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Incorrect usage, kept as a story to prove Breadcrumb still handles it: the last " +
+          'crumb is a `Link`, but Breadcrumb adds `aria-current="page"`, strips its `href`/' +
+          "`onClick`, drops it from the tab order, and the CSS reset removes Link's color/" +
+          "underline — it renders identically to `Default`'s plain-text current item. Don't " +
+          "rely on this; pass plain text for the last crumb instead.",
+      },
+    },
+  },
+};

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -12,16 +12,30 @@ import styles from "./Breadcrumb.module.css";
 
 // Currently there are no Recursica prop additions specific to Breadcrumbs (like size or variant)
 // according to recursica_ui-kit.json
-import { type RecursicaBreadcrumbProps } from "@recursica/adapter-common";
+import {
+  markCurrentPageItem,
+  type RecursicaBreadcrumbProps,
+} from "@recursica/adapter-common";
 
 export type BreadcrumbProps = RecursicaOverStyled<
   Omit<MantineBreadcrumbsProps, "variant" | "size"> & RecursicaBreadcrumbProps
 >;
 
+/**
+ * The last child should always be plain, non-interactive text (e.g. a `<span>`) — it represents
+ * the current page and shouldn't be a link. Breadcrumb tries to correct for a Link/anchor passed
+ * there anyway via `markCurrentPageItem` (aria-current, stripped href/onClick, CSS reset in
+ * Breadcrumb.module.css), but that's a best-effort safety net, not a guarantee — it can't stop a
+ * custom Link component (e.g. a router Link) that navigates from its own internal handler. See
+ * BREADCRUMB_IMPLEMENTATION_NOTES.md.
+ */
 export const Breadcrumb = forwardRef<HTMLDivElement, BreadcrumbProps>(
-  function Breadcrumb({ overStyled = false, separator = ">", ...rest }, ref) {
+  function Breadcrumb(
+    { overStyled = false, separator = ">", children, ...rest },
+    ref,
+  ) {
     const sanitizedProps = filterStylingProps(
-      { separator, ...rest },
+      { separator, children: markCurrentPageItem(children), ...rest },
       overStyled,
     );
 

package/src/components/Breadcrumb/markCurrentPageItem.test.ts

@@ -0,0 +1,49 @@
+import { createElement, type ReactElement } from "react";
+import { describe, it, expect } from "vitest";
+import { markCurrentPageItem } from "@recursica/adapter-common";
+
+type Props = Record<string, unknown>;
+
+describe("markCurrentPageItem", () => {
+  it("marks the last item aria-current=page and leaves earlier items untouched", () => {
+    const items = markCurrentPageItem([
+      createElement("a", { href: "/one" }, "One"),
+      createElement("a", { href: "/two" }, "Two"),
+      createElement("span", {}, "Three"),
+    ]) as ReactElement<Props>[];
+
+    expect(items[0].props.href).toBe("/one");
+    expect(items[0].props["aria-current"]).toBeUndefined();
+    expect(items[1].props.href).toBe("/two");
+    expect(items[1].props["aria-current"]).toBeUndefined();
+    expect(items[2].props["aria-current"]).toBe("page");
+  });
+
+  it("strips href/onClick and drops tab order on an interactive last item", () => {
+    const onClick = () => {};
+    const [last] = markCurrentPageItem([
+      createElement("a", { href: "/current", onClick }, "Current"),
+    ]) as ReactElement<Props>[];
+
+    expect(last.props.href).toBeUndefined();
+    expect(last.props.onClick).toBeUndefined();
+    expect(last.props.tabIndex).toBe(-1);
+    expect(last.props["aria-current"]).toBe("page");
+  });
+
+  it("leaves a non-interactive last item's other props untouched", () => {
+    const [last] = markCurrentPageItem([
+      createElement("span", { className: "current" }, "Current"),
+    ]) as ReactElement<Props>[];
+
+    expect(last.props.className).toBe("current");
+    expect(last.props.tabIndex).toBeUndefined();
+    expect(last.props["aria-current"]).toBe("page");
+  });
+
+  it("passes through non-element children (e.g. plain text) unchanged", () => {
+    const items = markCurrentPageItem(["First", "Last"]);
+
+    expect(items).toEqual(["First", "Last"]);
+  });
+});

package/src/components/Button/Button.module.css

@@ -334,6 +334,14 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-color
   );
+  /* Exposed so the loading-state Loader (color="var(--button-color)" in Button.tsx) matches
+     this exact text-color token instead of Mantine's own unrelated --button-color default.
+     !important: Mantine's own Button sets --button-color via an inline `style` attribute on
+     this same root element, which normal-weight stylesheet rules can never outrank regardless
+     of selector specificity (see IMPLEMENTATION_NOTES.md). */
+  --button-color: var(
+    --recursica_ui-kit_components_button_variants_styles_solid_properties_colors_text-color
+  ) !important;
 
   .iconWrapper {
     color: var(
@@ -367,6 +375,10 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text-color
   );
+  /* !important: see solid variant's identical comment above. */
+  --button-color: var(
+    --recursica_ui-kit_components_button_variants_styles_outline_properties_colors_text-color
+  ) !important;
 
   .iconWrapper {
     color: var(
@@ -400,6 +412,10 @@
   color: var(
     --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-color
   );
+  /* !important: see solid variant's identical comment above. */
+  --button-color: var(
+    --recursica_ui-kit_components_button_variants_styles_text_properties_colors_text-color
+  ) !important;
 
   .iconWrapper {
     color: var(

package/src/components/Button/Button.tsx

@@ -117,8 +117,21 @@ const _Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
 
   let mergedLoaderProps = userLoaderProps;
   if (useRecursicaLoader) {
+    // color="var(--button-color)" makes the loader ring match this button's own text color
+    // (Mantine's Button sets --button-color per variant/state) instead of Loader's own
+    // standalone indicator-color token, which Loader.module.css's `.root` would otherwise
+    // apply unconditionally, ignoring this nesting context. overStyled is required to pass
+    // `color` at all (blocked by default) — fully internal composition, no prop threading to
+    // callers, so it doesn't widen Loader's public API. See Button's IMPLEMENTATION_NOTES.md.
     mergedLoaderProps = {
-      children: <Loader variant={loaderVariant} size={resolvedLoaderSize} />,
+      children: (
+        <Loader
+          variant={loaderVariant}
+          size={resolvedLoaderSize}
+          overStyled
+          color="var(--button-color)"
+        />
+      ),
       ...userLoaderProps,
     };
   }

package/src/components/Button/IMPLEMENTATION_NOTES.md

@@ -48,11 +48,37 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 
 ---
 
-## Loader color contrast
-
-**Decision:** When a Button is in a loading state, the `Recursica Loader` component is injected. The `Loader` component strictly defines its own colors and styles per variant, meaning it does not inherit the text color (`currentColor`) from the Button.
-
-**Constraint:** This can lead to contrast issues (e.g., a blue dots loader inside a solid blue button). Design has explicitly decided not to address this at the moment. As such, developers using the `loading` prop must be aware that the loader's color is fixed by its internal tokens, not by the button's context.
+## Loader color contrast — fixed (source-of-truth audit, 2026-08-30)
+
+**Superseded:** the entry below originally documented an explicit decision _not_ to fix this.
+Re-verified during the mantine-vs-mui source-of-truth audit by measuring actual computed styles
+in the `Loading` story: the loader ring rendered `#c21b43` (Loader's own standalone
+`indicator-color` token) against a label text color of `rgb(249, 249, 249)` — a real, confirmed
+mismatch on the `solid` variant, not a false report.
+
+**Root cause:** `Loader.module.css`'s `.root` unconditionally sets `--loader-color:
+var(--recursica_..._loader_properties_indicator-color)` directly on the Loader's own root
+`<span>`. Mantine's own Button internally wraps `loaderProps.children` in a generic `<Loader
+size color>` that sets `--loader-color: var(--button-color)` as an _inline_ style on an outer
+wrapper div — but our own nested `<Loader>` (rendered as `loaderProps.children`) has an identical
+class (`mantine-Loader-root`) on its own root, so its own stylesheet rule locally re-declares
+`--loader-color`, shadowing the inherited value from that outer wrapper for anything computed on
+or under our own element (CSS custom properties resolve against the nearest self-or-ancestor
+declaration — a local re-declaration always wins over what an ancestor tried to pass down,
+regardless of whether the ancestor's value came from an inline style or not).
+
+**Fix:** pass `color="var(--button-color)"` to the Button-owned `<Loader>` — Mantine's own
+`Loader` factory writes any `color` prop straight through `getThemeColor()`/`parseThemeColor()`
+(safely falls through unresolved CSS values like a `var()` reference verbatim, per
+`@mantine/core`'s own `parse-theme-color.cjs`) into an _inline_ `--loader-color` style on that
+same root span — which, being inline, now wins over our own `.root` stylesheet declaration.
+Also added `--button-color` (`!important`) to each variant's own block in `Button.module.css`,
+set to that variant's own `colors_text-color` token — needed because Mantine's Button sets its
+own generic `--button-color: var(--mantine-color-white)` via an inline style on the button root
+itself, which our external stylesheet couldn't otherwise outrank at equal/lower priority
+regardless of selector specificity. Verified live: loader ring color now matches the label text
+color exactly (`rgb(249, 249, 249)`) across solid/outline/text variants, no visual regression on
+non-loading stories.
 
 ---
 

package/src/components/DatePicker/DATEPICKER_IMPLEMENTATION_NOTES.md

@@ -7,7 +7,7 @@ The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerI
 ## Structural Constraints
 
 1. **Naked Input Usage**: We intentionally pass `label={undefined}`, `description={undefined}`, and `error={undefined}` to the Mantine `DatePickerInput` component. This suppresses Mantine's internal macro form wrapping and ensures that only our `WithReadOnlyWrapper` > `FormControlWrapper` orchestrates labels, description text, and ARIA state error boundaries.
-2. **Read-Only Implementation**: Since the value type for `DatePickerInput` can be a date object, string, or array, the `WithReadOnlyWrapper` attempts to safely cast the output value using standard `String(value)`. For production apps utilizing heavy date formatting logic, developers can pass a custom `readOnlyComponent` explicitly to bypass this default cast.
+2. **Read-Only Implementation**: `readOnlyValue` is formatted via `@mantine/dates`' own `getFormattedDate` helper using the same `valueFormat` the editable `DatePickerInput` renders with — so a read-only date reads identically to that same value while editable (`05/20/26`, not a raw JS `Date.toString()`). Developers can still pass a custom `readOnlyComponent` to fully replace this rendering.
 3. **Calendar Portal/Dropdown (Figma Token Issue)**: The Recursica UI Kit's `date-picker` component in Figma fails to export any explicit structural or color properties for the calendar popover itself (e.g. elevation, surface background, selected day colors, hover, today, in-range). To solve this organically within the framework without breaking strict token adherence, we manually map every calendar state to the closest existing Recursica token instead of leaving any of it on Mantine's own un-tokenized defaults:
    - **Surface** (`.dropdown`) & **selected day** (`.day[data-selected]`): `--recursica_ui-kit_components_hover-card-popover` tokens for elevation/padding/surface, `--recursica_ui-kit_components_button_variants_styles_solid` tokens for the selected day fill (unchanged from before).
    - **Header content, weekday row** (`.calendarHeader`, `.weekday`): the hover-card-popover content-color token — previously unmapped, so these leaked Mantine's own text colors.
@@ -28,3 +28,4 @@ The `DatePicker` component is a wrapper around the `@mantine/dates` `DatePickerI
 - **Default placeholder**: `placeholder="MM / DD / YY"`, set the same way (before `sanitizedProps`, so consumers can override).
 - **Single-line enforcement (bug fix)**: `DatePickerInput` renders its value/placeholder as a `<button>`'s text content, not a native `<input>` — it wraps like any other block text by default. A long placeholder (e.g. the original story's `"Select a deadline..."`) wrapped to two lines, inflating the field's height well past its `min-height` token and making the field visually look narrower than its actual `width` token value even though the box itself was always the right size. Fixed with `white-space: nowrap`/`text-overflow: ellipsis`/`overflow-x: clip`/`overflow-y: visible` on `.input`, the same convention `FileInput.module.css`'s `.value` uses.
 - **Day focus ring (bug fix)**: Mantine's `Day` ships no built-in `:focus-visible` style of its own (unlike `.calendarHeaderControl`/`.calendarHeaderLevel`, which are styled as `Button` and inherited a focus ring from that treatment), so a focused day — e.g. the auto-focused selected/today day when the calendar opens — fell through to the browser's native blue outline instead of a Recursica token. Fixed by adding `.day:focus-visible` with the same generic `--recursica_brand_states_focus_*` box-shadow ring already used by `.input` and `.calendarHeaderControl`/`.calendarHeaderLevel`. mui-adapter's `.MuiPickerDay-root.Mui-focusVisible` already had this — only the mantine-adapter side was missing it.
+- **Read-only value format (bug fix, 2026-08-30)**: `readOnlyValue` used to be a bare `String(value)`/`String(defaultValue)` cast — `Date`'s own `toString()`, e.g. `"Wed May 20 2026 17:00:00 GMT-0700 (Pacific Daylight Time)"` — completely ignoring `valueFormat`, so `ui-kit-datepicker--static-read-only` rendered a totally different (and far less usable) date string than the same value shown editable, or than mui-adapter's equivalent (which already formats its read-only text via dayjs). Fixed by running the value through `@mantine/dates`' exported `getFormattedDate({ type: "default", date, locale: "en", format: valueFormat, labelSeparator: "" })` — the same formatter `DatePickerInput` uses internally — so read-only and editable rendering of the same value always agree.

package/src/components/DatePicker/DatePicker.tsx

@@ -1,5 +1,9 @@
 import React, { forwardRef } from "react";
-import { DatePickerInput, type DatePickerInputProps } from "@mantine/dates";
+import {
+  DatePickerInput,
+  type DatePickerInputProps,
+  getFormattedDate,
+} from "@mantine/dates";
 import { type ReadOnlyControlProps } from "@recursica/adapter-common";
 import {
   filterStylingProps,
@@ -161,13 +165,23 @@ export const DatePicker = forwardRef<HTMLButtonElement, DatePickerProps>(
         readOnlyComponent={readOnlyComponent}
         emptyValueComponent={emptyValueComponent}
         readOnlyType="text"
-        readOnlyValue={
-          value !== undefined
-            ? String(value)
-            : defaultValue
-              ? String(defaultValue)
-              : undefined
-        }
+        readOnlyValue={(() => {
+          const readOnlyDate = value !== undefined ? value : defaultValue;
+          // `DatePickerInput` formats its own displayed value via `valueFormat` internally
+          // (using this same `getFormattedDate` helper) — the read-only text swap-in bypassed
+          // that entirely and rendered `String(date)` instead (a raw JS `Date.toString()`, e.g.
+          // "Wed May 20 2026 17:00:00 GMT-0700 (Pacific Daylight Time)"), so a read-only
+          // DatePicker never matched what the same value looks like while editable.
+          return readOnlyDate
+            ? getFormattedDate({
+                type: "default",
+                date: readOnlyDate,
+                locale: "en",
+                format: valueFormat,
+                labelSeparator: "",
+              })
+            : undefined;
+        })()}
         readOnlyNativeProps={props}
         activeComponent={
           /* Naked Input execution safely decoupled from Mantine's macro Input.Wrapper DOM hooks */

package/src/components/Dropdown/Dropdown.stories.tsx

@@ -27,7 +27,6 @@ const meta: Meta<DropdownStoryProps> = {
     disabled: false,
     required: false,
     readOnly: false,
-    searchable: false,
     clearable: false,
   },
   argTypes: {
@@ -38,9 +37,6 @@ const meta: Meta<DropdownStoryProps> = {
     readOnly: {
       control: "boolean",
     },
-    searchable: {
-      control: "boolean",
-    },
     clearable: {
       control: "boolean",
     },
@@ -63,12 +59,10 @@ export const Default: Story = {
   args: {},
 };
 
-export const SearchableClearable: Story = {
+export const Clearable: Story = {
   args: {
-    label: "Search & Clear Options",
-    searchable: true,
+    label: "Clearable Options",
     clearable: true,
-    placeholder: "Start typing...",
   },
 };
 

package/src/components/Dropdown/Dropdown.tsx

@@ -23,7 +23,7 @@ import { type RecursicaDropdownProps as BaseRecursicaDropdownProps } from "@recu
 export interface RecursicaDropdownProps
   extends Omit<
       MantineSelectProps,
-      "size" | "variant" | "radius" | "wrapperProps" | "data"
+      "size" | "variant" | "radius" | "wrapperProps" | "data" | "searchable"
     >,
     Omit<
       RecursicaFormControlWrapperProps,
@@ -40,6 +40,7 @@ const UNSUPPORTED_PROPS = [
   "size", // Recursica controls sizing via the `size` variant + design tokens, not raw dimensions.
   "variant", // Colors/variants are token-driven; the library's native palette isn't exposed.
   "radius", // Recursica does not expose the library's native corner-radius system.
+  "searchable", // Not a supported Dropdown feature — that's what makes it an AutoComplete.
 ] as const satisfies readonly (keyof MantineSelectProps)[];
 
 export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(

package/src/components/FormControlLayout/FormControlLayout.stories.tsx

@@ -23,7 +23,7 @@ const meta: Meta<typeof FormControlLayout> = {
     },
     labelSize: {
       control: "radio",
-      options: ["default", "small", "md"],
+      options: ["default", "small"],
       description: "Dictates the physical width of the left column.",
     },
     children: {

package/src/components/Grid/GRID_IMPLEMENTATION_NOTES.md

@@ -7,3 +7,12 @@ Per the layout-components rule (no formal Recursica common props definition —
 `Grid.Col`'s `span`, `offset`, `order`, `visibleFrom`, and `hiddenFrom` props are passed straight through to Mantine's `Grid.Col` unchanged, using Mantine's own breakpoint scale (`xs`/`sm`/`md`/`lg`/`xl` — there is no `base` breakpoint in Mantine; `xs` is the smallest).
 
 Like the other primitive layout components, `Grid` and `Grid.Col` use `WithRecursicaSpacing<T>` rather than `RecursicaOverStyled<T>` and are listed in the "Primitive Layout Components Exemption" section of `OVERSTYLING.md`.
+
+## Added `ResponsiveSizes` story (2026-08-30, source-of-truth audit)
+
+mui-adapter has a `ui-kit-grid--responsive-sizes` story with no counterpart here — its `story
+parity with source of truth` check would otherwise fail for mui-adapter. Added an equivalent
+`ResponsiveSizes` story using Mantine's own `span` prop (Mantine's `Grid.Col` has no `size` prop
+— see the naming-divergence note above and mui-adapter's own `IMPLEMENTATION_NOTES.md`). This is
+functionally identical to the existing `ResponsiveSpans` story above; it exists purely so
+mui-adapter's differently-named story id has a source-of-truth golden to diff against.

package/src/components/Grid/Grid.stories.tsx

@@ -113,6 +113,30 @@ export const ResponsiveSpans: Story = {
   ),
 };
 
+// Mirrors mui-adapter's `ResponsiveSizes` story (same breakpoints/content) under mantine's own
+// prop name — Mantine's Grid.Col has no `size` prop, only `span`, which is what `ResponsiveSpans`
+// above already exercises. This one exists purely so mui-adapter's `responsive-sizes` story id
+// has a source-of-truth counterpart to diff against (see Grid's IMPLEMENTATION_NOTES.md).
+export const ResponsiveSizes: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Grid {...args}>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+      <Grid.Col span={{ xs: 12, sm: 6, md: 3 }}>
+        <Swatch>xs 12 / sm 6 / md 3</Swatch>
+      </Grid.Col>
+    </Grid>
+  ),
+};
+
 export const Offset: Story = {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => (

package/src/components/Label/Label.stories.tsx

@@ -20,7 +20,7 @@ const meta: Meta<LabelStoryProps> = {
   argTypes: {
     labelSize: {
       control: "inline-radio",
-      options: ["default", "small", "md"],
+      options: ["default", "small"],
       description:
         "Sizing metrics for the Label. Only visually distinguishable once composed inside a `side-by-side` FormControlLayout, which is where the resulting width constraint applies.",
     },

package/src/components/Link/IMPLEMENTATION_NOTES.md

@@ -2,7 +2,7 @@
 
 ## States in Design Tokens
 
-The design tokens (`recursica_variables_scoped.css`) provide the base link styling directly on `--recursica_ui-kit_components_link_properties_*` (no distinct `default` state), plus a `visited` variant that overrides only `colors_text-color`/`colors_icon-color`. Hover is not a per-component `link_variants_states_hover_*` token; it's driven by the brand-level `--recursica_brand_states_link_decoration` token (resolves to `underline`), applied on `.root:hover`. Earlier this token was exported as an invalid quoted string (`"underline"`), which silently failed and was mistaken for the token not existing at all — now fixed upstream to a bare keyword. There are no tokens for `active` or `focus` either; the component relies on the browser's default focus outline for accessibility unless overridden by a global reset.
+The design tokens (`recursica_variables_scoped.css`) provide the base link styling directly on `--recursica_ui-kit_components_link_properties_*` (no distinct `default` state), plus a `visited` variant that overrides only `colors_text-color`/`colors_icon-color`. Hover is not a per-component `link_variants_states_hover_*` token; it's driven by the brand-level `--recursica_brand_states_link_decoration` token (resolves to `underline`), applied on `.root:hover`. Earlier this token was exported as an invalid quoted string (`"underline"`), which silently failed and was mistaken for the token not existing at all — now fixed upstream to a bare keyword. There is no token for `active`. There isn't a per-component `focus` token either, but focus isn't left to the browser default: like every other interactive component (see Button), `.root:focus-visible` replaces the native outline with the global `--recursica_brand_states_focus_*` ring. This was previously missing here — Link (and anything composing it, e.g. Breadcrumb) fell back to the browser's native focus outline instead.
 
 ## Overriding Mantine's underline Prop