@recursica/mui-adapter 0.18.0 → 0.19.0

package/src/components/Dropdown/Dropdown.module.css

@@ -1,23 +1,36 @@
 /* EXEMPTIONS:
-   - state-specific border-size variables are ignored because a uniform 1px border is applied globally to prevent 
+   - state-specific border-size variables are ignored because a uniform 1px border is applied globally to prevent
      unexpected layout shift or flickering during focus, disabled, or error state transitions. */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_default_properties_border-size */
+/* recursica-ignore: --recursica_ui-kit_components_dropdown_properties_border-size */
 /* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_border-size */
 /* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_error_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_dropdown_variants_states_focus_properties_border-size */
 
 /* LAYOUT SPACING OVERRIDES:
-   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
+   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens.
+   - Also sets the --dropdown-control-{max,min}-width hooks consumed inline in Dropdown.tsx, since
+     the token schema no longer provides a single layout-agnostic min/max width. */
 .layoutOverride {
   --form-control-margin-bottom: var(
     --recursica_ui-kit_components_dropdown_variants_layouts_stacked_properties_top-bottom-margin
   );
+  --dropdown-control-max-width: var(
+    --recursica_ui-kit_components_dropdown_variants_layouts_stacked_properties_max-width
+  );
+  --dropdown-control-min-width: var(
+    --recursica_ui-kit_components_dropdown_variants_layouts_stacked_properties_min-width
+  );
 }
 
 .layoutOverride[data-form-layout="side-by-side"] {
   --form-control-margin-bottom: var(
     --recursica_ui-kit_components_dropdown_variants_layouts_side-by-side_properties_top-bottom-margin
   );
+  --dropdown-control-max-width: var(
+    --recursica_ui-kit_components_dropdown_variants_layouts_side-by-side_properties_max-width
+  );
+  --dropdown-control-min-width: var(
+    --recursica_ui-kit_components_dropdown_variants_layouts_side-by-side_properties_min-width
+  );
 }
 
 /* HARDCODED VALUES:
@@ -101,13 +114,13 @@
 
   /* Base State Default Execution */
   background-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_background
+    --recursica_ui-kit_components_dropdown_properties_colors_background-color
   );
   border-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_border-color
+    --recursica_ui-kit_components_dropdown_properties_colors_border-color
   );
   color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_text
+    --recursica_ui-kit_components_dropdown_properties_colors_text-color
   );
 
   outline: none;
@@ -153,13 +166,13 @@
   width: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
   height: var(--recursica_ui-kit_components_dropdown_properties_icon-size);
   color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_leading-icon
+    --recursica_ui-kit_components_dropdown_properties_colors_leading-icon
   );
 }
 
 .section[data-position="right"] :global(svg) {
   color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_trailing-icon
+    --recursica_ui-kit_components_dropdown_properties_colors_trailing-icon
   );
 }
 
@@ -168,29 +181,16 @@
 -------------------------------------- */
 
 /* Focus State Mapping (Triggered internally via browser pseudo-pseudo-class) */
+/* The token schema no longer provides per-component focus colors; apply the generic focus ring
+   tokens as a box-shadow ring instead of a color swap. */
 .input:focus-within,
 .input:focus {
-  border-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_border-color
-  );
-  background-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_background
-  );
-  color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_text
-  );
-}
-
-.root:focus-within .section[data-position="left"] :global(svg) {
-  color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_leading-icon
-  );
-}
-
-.root:focus-within .section[data-position="right"] :global(svg) {
-  color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_trailing-icon
-  );
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
 }
 
 /* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
@@ -199,10 +199,10 @@
     --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_border-color
   ) !important;
   background-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_background
+    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_background-color
   ) !important;
   color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_text
+    --recursica_ui-kit_components_dropdown_variants_states_error_properties_colors_text-color
   ) !important;
 }
 
@@ -224,10 +224,13 @@
     --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_border-color
   ) !important;
   background-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_background
+    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_background-color
   ) !important;
   color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_text
+    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_colors_text-color
+  ) !important;
+  opacity: var(
+    --recursica_ui-kit_components_dropdown_variants_states_disabled_properties_opacity
   ) !important;
   cursor: not-allowed;
 }
@@ -250,12 +253,10 @@
 
 .dropdown {
   background-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_background
+    --recursica_ui-kit_components_dropdown_properties_colors_background-color
   );
   border: 1px solid
-    var(
-      --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_border-color
-    );
+    var(--recursica_ui-kit_components_dropdown_properties_colors_border-color);
   border-radius: var(
     --recursica_ui-kit_components_dropdown_properties_border-radius
   );
@@ -273,7 +274,7 @@
     --recursica_ui-kit_components_dropdown_properties_text_font-weight
   );
   color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_default_properties_colors_text
+    --recursica_ui-kit_components_dropdown_properties_colors_text-color
   );
   padding: calc(
       var(--recursica_ui-kit_components_dropdown_properties_vertical-padding) *
@@ -283,14 +284,16 @@
   cursor: pointer;
 }
 
+/* No per-option selected/hovered tokens exist in the schema; use the generic overlay tint
+   (same technique as the Mantine reference implementation) to highlight the active option. */
 .option[data-selected="true"],
 .option[data-combobox-selected="true"],
 .option[data-hovered="true"],
 .option:hover {
-  background-color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_background
-  );
-  color: var(
-    --recursica_ui-kit_components_dropdown_variants_states_focus_properties_colors_text
+  background-color: color-mix(
+    in srgb,
+    var(--recursica_brand_states_hover_color)
+      calc(var(--recursica_brand_states_hover_opacity) * 100%),
+    transparent
   );
 }

package/src/components/Dropdown/Dropdown.tsx

@@ -120,8 +120,8 @@ export const Dropdown = forwardRef<HTMLInputElement, DropdownProps>(
       <WithReadOnlyWrapper
         className={wrapperClass}
         style={injectedStyles}
-        controlMaxWidth="var(--recursica_ui-kit_components_dropdown_properties_max-width)"
-        controlMinWidth="var(--recursica_ui-kit_components_dropdown_properties_min-width)"
+        controlMaxWidth="var(--dropdown-control-max-width)"
+        controlMinWidth="var(--dropdown-control-min-width)"
         overStyled={overStyled as true}
         formLayout={formLayout}
         labelSize={labelSize}

package/src/components/FormControlWrapper/FormControlWrapper.module.css

@@ -10,28 +10,29 @@
 
   /* Global Form Field Colors */
   --form-field-background: var(
-    --recursica_ui-kit_globals_form_field_colors_background
+    --recursica_ui-kit_globals_form_field_colors_background-color
   );
   --form-field-background-read-only: var(
-    --recursica_ui-kit_globals_form_field_colors_background-read-only
+    --recursica_ui-kit_globals_form_field_colors_background-color-read-only
   );
-  --form-field-border: var(--recursica_ui-kit_globals_form_field_colors_border);
-  --form-field-border-error: var(
-    --recursica_ui-kit_globals_form_field_colors_border-error
+  --form-field-border: var(
+    --recursica_ui-kit_globals_form_field_colors_border-color
   );
-  --form-field-border-focus: var(
-    --recursica_ui-kit_globals_form_field_colors_border-focus
+  --form-field-border-error: var(
+    --recursica_ui-kit_globals_form_field_colors_error-border-color
   );
   --form-field-border-selected: var(
     --recursica_ui-kit_globals_form_field_colors_border-selected
   );
   --form-field-disabled-background: var(
-    --recursica_ui-kit_globals_form_field_colors_disabled-background
+    --recursica_ui-kit_globals_form_field_colors_disabled-background-color
   );
   --form-field-disabled-text: var(
     --recursica_ui-kit_globals_form_field_colors_disabled-text
   );
-  --form-field-icon: var(--recursica_ui-kit_globals_form_field_colors_icon);
+  --form-field-icon: var(
+    --recursica_ui-kit_globals_form_field_colors_icon-color
+  );
   --form-field-placeholder-text-opacity: var(
     --recursica_ui-kit_globals_form_field_colors_placeholder-text-opacity
   );
@@ -40,15 +41,14 @@
   );
 
   /* Global Form Field Geometric Sizes */
+  /* No focus-specific border-color/border-size tokens exist anymore; components use the generic
+     --recursica_brand_states_focus_* ring tokens directly instead (see e.g. TextField.module.css). */
   --form-field-border-radius: var(
     --recursica_ui-kit_globals_form_field_size_border-radius
   );
   --form-field-border-size-default: var(
     --recursica_ui-kit_globals_form_field_size_border-size-default
   );
-  --form-field-border-size-focus: var(
-    --recursica_ui-kit_globals_form_field_size_border-size-focus
-  );
   --form-field-horizontal-padding: var(
     --recursica_ui-kit_globals_form_field_size_horizontal-padding
   );

package/src/components/HoverCard/HoverCard.module.css

@@ -19,7 +19,7 @@
 
 .dropdown {
   background-color: var(
-    --recursica_ui-kit_components_hover-card-popover_properties_colors_background
+    --recursica_ui-kit_components_hover-card-popover_properties_colors_background-color
   );
   border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
   border-width: var(

package/src/components/Label/Label.module.css

@@ -1,3 +1,9 @@
+/* EXEMPTIONS:
+   - layouts_stacked sizes width variables are ignored because stacked labels naturally occupy 100% width block-level
+     real estate in HTML rendering, making explicit width properties redundant. Mirrors the mantine-adapter reference. */
+/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_default_properties_width */
+/* recursica-ignore: --recursica_ui-kit_components_label_variants_layouts_stacked_variants_sizes_small_properties_width */
+
 .root {
   /* Prevent default MUI absolute positioning logic */
   position: relative;
@@ -37,7 +43,7 @@
     --recursica_ui-kit_components_label_properties_label-text_text-transform
   );
 
-  color: var(--recursica_ui-kit_components_label_properties_colors_text);
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
 }
 
 .innerLayout {
@@ -56,7 +62,9 @@
 
 .required {
   /* Override the `.MuiInputLabel-asterisk` natively */
-  color: var(--recursica_ui-kit_components_label_properties_colors_asterisk);
+  color: var(
+    --recursica_ui-kit_components_label_properties_colors_asterisk-color
+  );
   margin-left: var(
     --recursica_ui-kit_components_label_properties_required-indicator-gap
   );
@@ -70,7 +78,7 @@
    We explicitly override this bleed to prevent the main label text from turning red, 
    while allowing the asterisk to take the error color! */
 .root:global(.Mui-error) {
-  color: var(--recursica_ui-kit_components_label_properties_colors_text);
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
 }
 .root:global(.Mui-error) .required {
   color: var(
@@ -112,11 +120,17 @@
   text-transform: var(
     --recursica_ui-kit_components_label_properties_optional-text_text-transform
   );
+  opacity: var(
+    --recursica_ui-kit_components_label_properties_optional-text-opacity
+  );
 }
 
 .actionArea {
   display: flex;
   align-items: center;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
 }
 
 .editIcon {
@@ -127,6 +141,9 @@
   background: none;
   border: none;
   padding: 0;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
 
   width: 16px;
   height: 16px;

package/src/components/Layer/USAGE.md

@@ -0,0 +1,50 @@
+# Layer - Usage Guide
+
+This document describes how to integrate and use the `Layer` component in your projects using `@recursica/mui-adapter`.
+
+> [!NOTE] > `Layer` is defined once in `@recursica/adapter-common` and re-exported here so it shares the exact same behavior across every Recursica adapter.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Layer } from "@recursica/mui-adapter";
+```
+
+---
+
+## 2. Basic Example
+
+`Layer` sets `data-recursica-layer` on its root element, which is what makes the theme+layer scoped CSS variables (surface color, border, elevation, padding) in `recursica_variables_scoped.css` actually apply. [`RecursicaThemeProvider`](../RecursicaThemeProvider/USAGE.md) automatically wraps your app in a `layer={0}` `Layer` by default (via its `initLayer0` prop), so you don't need to add one yourself for the base page. You still add `Layer`s manually for anything visually elevated above the page background:
+
+```tsx
+import { RecursicaThemeProvider, Layer, Card } from "@recursica/mui-adapter";
+
+function App() {
+  return (
+    <RecursicaThemeProvider theme="light">
+      {/* Page background/surface already uses layer 0, applied automatically */}
+      <Layer layer={1}>
+        <Card>Elevated content sits on layer 1</Card>
+      </Layer>
+    </RecursicaThemeProvider>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+> [!IMPORTANT]
+>
+> - **Layer 0 is automatic**: `RecursicaThemeProvider` applies it for you by default. Only opt out (`initLayer0={false}`) if you need to control exactly where layer 0 starts in the tree, or need `contentsOnly` on the base layer — see [RecursicaThemeProvider usage](../RecursicaThemeProvider/USAGE.md).
+> - **Layers 1–3 are manual**: Wrap any content that's visually elevated above the page background (a Card, Modal, Popover, etc.) in its own `<Layer layer={1|2|3}>`. Nesting `Layer`s is how Recursica communicates elevation to descendant components — do **not** pass a `layer` prop directly to other components; wrap them in a `Layer` instead (every other component's `USAGE.md` repeats this rule).
+> - **`contentsOnly`**: When `true`, `Layer` renders with `display: contents` and omits `data-recursica-layer` entirely — use this when you need a layer boundary in your component tree without adding an extra DOM box or applying layer styling (e.g. a purely structural wrapper).
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`Layer` has no visual variants of its own — its entire purpose is to bind a subtree to a numbered layer's design tokens. It does not accept `overStyled`; instead, if you find yourself needing to override a layer's surface styling, that's a signal you may want a different layer number rather than an escape hatch.

package/src/components/Link/Link.module.css

@@ -1,4 +1,9 @@
-/* 
+/* EXEMPTIONS:
+   - text_text-transform is ignored because links naturally inherit casing directly from text
+     children rather than requiring custom CSS transforms. Mirrors the mantine-adapter reference. */
+/* recursica-ignore: --recursica_ui-kit_components_link_properties_text_text-transform */
+
+/*
 HARDCODED VALUES:
 - display: inline-flex; (Base layout to align icon and text correctly)
 - align-items: center;
@@ -16,31 +21,27 @@ HARDCODED VALUES:
   text-decoration: none;
   color: inherit;
 
-  /* Typography Default Tokens */
+  /* Typography Tokens */
   font-family: var(
     --recursica_ui-kit_components_link_properties_text_font-family
   );
   font-size: var(--recursica_ui-kit_components_link_properties_text_font-size);
+  font-style: var(
+    --recursica_ui-kit_components_link_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_properties_text_font-weight
+  );
   letter-spacing: var(
     --recursica_ui-kit_components_link_properties_text_letter-spacing
   );
   line-height: var(
     --recursica_ui-kit_components_link_properties_text_line-height
   );
-
-  /* Default State Tokens */
-  font-style: var(
-    --recursica_ui-kit_components_link_variants_states_default_properties_text_font-style
-  );
-  font-weight: var(
-    --recursica_ui-kit_components_link_variants_states_default_properties_text_font-weight
-  );
   text-decoration: var(
-    --recursica_ui-kit_components_link_variants_states_default_properties_text_text-decoration
-  );
-  color: var(
-    --recursica_ui-kit_components_link_variants_states_default_properties_colors_text
+    --recursica_ui-kit_components_link_properties_text_text-decoration
   );
+  color: var(--recursica_ui-kit_components_link_properties_colors_text-color);
 }
 
 .root[data-has-icon] {
@@ -49,49 +50,9 @@ HARDCODED VALUES:
   gap: var(--recursica_ui-kit_components_link_properties_icon-text-gap);
 }
 
-.root:hover {
-  /* Reset Mantine's potential hover override */
-  text-decoration: var(
-    --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-decoration
-  );
-  font-style: var(
-    --recursica_ui-kit_components_link_variants_states_hover_properties_text_font-style
-  );
-  font-weight: var(
-    --recursica_ui-kit_components_link_variants_states_hover_properties_text_font-weight
-  );
-  color: var(
-    --recursica_ui-kit_components_link_variants_states_hover_properties_colors_text
-  );
-}
-
 .root:visited {
-  text-decoration: var(
-    --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-decoration
-  );
-  font-style: var(
-    --recursica_ui-kit_components_link_variants_states_visited_properties_text_font-style
-  );
-  font-weight: var(
-    --recursica_ui-kit_components_link_variants_states_visited_properties_text_font-weight
-  );
-  color: var(
-    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_text
-  );
-}
-
-.root:visited:hover {
-  text-decoration: var(
-    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-decoration
-  );
-  font-style: var(
-    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_font-style
-  );
-  font-weight: var(
-    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_font-weight
-  );
   color: var(
-    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_colors_text
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_text-color
   );
 }
 
@@ -104,26 +65,12 @@ HARDCODED VALUES:
 
   width: var(--recursica_ui-kit_components_link_properties_icon-size);
   height: var(--recursica_ui-kit_components_link_properties_icon-size);
-  color: var(
-    --recursica_ui-kit_components_link_variants_states_default_properties_colors_icon
-  );
-}
-
-.root:hover .iconWrapper {
-  color: var(
-    --recursica_ui-kit_components_link_variants_states_hover_properties_colors_icon
-  );
+  color: var(--recursica_ui-kit_components_link_properties_colors_icon-color);
 }
 
 .root:visited .iconWrapper {
   color: var(
-    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_icon
-  );
-}
-
-.root:visited:hover .iconWrapper {
-  color: var(
-    --recursica_ui-kit_components_link_variants_states_visited-hover_properties_colors_icon
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_icon-color
   );
 }
 

package/src/components/Loader/Loader.module.css

@@ -19,7 +19,7 @@
 }
 .root[data-size="small"][data-variant="oval"] {
   --loader-thickness: var(
-    --recursica_ui-kit_components_loader_variants_sizes_small_properties_thickness
+    --recursica_ui-kit_components_loader_variants_sizes_small_properties_thickness-size
   );
 }
 .root[data-size="small"]:not([data-variant="oval"]) span {
@@ -36,7 +36,7 @@
 }
 .root[data-size="default"][data-variant="oval"] {
   --loader-thickness: var(
-    --recursica_ui-kit_components_loader_variants_sizes_default_properties_thickness
+    --recursica_ui-kit_components_loader_variants_sizes_default_properties_thickness-size
   );
 }
 .root[data-size="default"]:not([data-variant="oval"]) span {
@@ -53,7 +53,7 @@
 }
 .root[data-size="large"][data-variant="oval"] {
   --loader-thickness: var(
-    --recursica_ui-kit_components_loader_variants_sizes_large_properties_thickness
+    --recursica_ui-kit_components_loader_variants_sizes_large_properties_thickness-size
   );
 }
 .root[data-size="large"]:not([data-variant="oval"]) span {