@recursica/mantine-adapter 0.35.0 → 0.36.0

package/src/components/Layer/USAGE.md

@@ -0,0 +1,54 @@
+# Layer - Usage Guide
+
+This document describes how to integrate and use the `Layer` component in your projects using `@recursica/mantine-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/mantine-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/mantine-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/IMPLEMENTATION_NOTES.md

@@ -1,15 +1,8 @@
 # Link Component Implementation Notes
 
-## Missing States in Design Tokens
+## States in Design Tokens
 
-Currently, the design tokens (`recursica_variables_scoped.css`) only provide states for:
-
-- `default`
-- `hover`
-- `visited`
-- `visited-hover`
-
-There are no tokens for the `active` or `focus` states. If these are needed, they must be added to the Figma variables and exported via the token pipeline. The component relies on the browser's default focus outline for accessibility unless overriden 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`. There is no per-state token for `hover` anymore (a prior schema version had one); the component currently applies no distinct hover treatment beyond the browser's native `cursor: pointer`. 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.
 
 ## Overriding Mantine's underline Prop
 

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

@@ -1,10 +1,7 @@
 /* EXEMPTIONS:
-   - text_text-transform across multiple link states (default, hover, visited, visited-hover) is ignored 
-     because links naturally inherit casing directly from text children rather than requiring custom CSS transforms. */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_default_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_hover_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_link_variants_states_visited-hover_properties_text_text-transform */
+   - text_text-transform is ignored because links naturally inherit casing directly from text
+     children rather than requiring custom CSS transforms. */
+/* recursica-ignore: --recursica_ui-kit_components_link_properties_text_text-transform */
 
 /* 
 HARDCODED VALUES:
@@ -24,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] {
@@ -57,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
   );
 }
 
@@ -112,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/Link/USAGE.md

@@ -43,16 +43,9 @@ All Recursica components in the `@recursica/mantine-adapter` package adhere stri
 
 ## 4. Key Integration Features & Constraints
 
-## Missing States in Design Tokens
+## States in Design Tokens
 
-Currently, the design tokens (`recursica_variables_scoped.css`) only provide states for:
-
-- `default`
-- `hover`
-- `visited`
-- `visited-hover`
-
-There are no tokens for the `active` or `focus` states. If these are needed, they must be added to the Figma variables and exported via the token pipeline. The component relies on the browser's default focus outline for accessibility unless overriden 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`. There is no per-state token for `hover` anymore (a prior schema version had one); the component currently applies no distinct hover treatment beyond the browser's native `cursor: pointer`. 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.
 
 ## Overriding Mantine's underline Prop
 

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

@@ -15,7 +15,7 @@
 }
 .root[data-size="small"][data-variant="oval"]::after {
   border-width: var(
-    --recursica_ui-kit_components_loader_variants_sizes_small_properties_thickness
+    --recursica_ui-kit_components_loader_variants_sizes_small_properties_thickness-size
   );
   border-radius: var(
     --recursica_ui-kit_components_loader_variants_sizes_small_properties_border-radius
@@ -30,7 +30,7 @@
 }
 .root[data-size="default"][data-variant="oval"]::after {
   border-width: var(
-    --recursica_ui-kit_components_loader_variants_sizes_default_properties_thickness
+    --recursica_ui-kit_components_loader_variants_sizes_default_properties_thickness-size
   );
   border-radius: var(
     --recursica_ui-kit_components_loader_variants_sizes_default_properties_border-radius
@@ -45,7 +45,7 @@
 }
 .root[data-size="large"][data-variant="oval"]::after {
   border-width: var(
-    --recursica_ui-kit_components_loader_variants_sizes_large_properties_thickness
+    --recursica_ui-kit_components_loader_variants_sizes_large_properties_thickness-size
   );
   border-radius: var(
     --recursica_ui-kit_components_loader_variants_sizes_large_properties_border-radius

package/src/components/Menu/Menu.module.css

@@ -1,16 +1,18 @@
 /* EXEMPTIONS:
-   - colors_selected-item_supporting-text-color is ignored because selected menu items do not render 
-     supporting secondary text, making selected state overrides for supporting text colors obsolete. */
-/* recursica-ignore: --recursica_ui-kit_components_menu-item_properties_colors_selected-item_supporting-text-color */
+   - colors_supporting-text-color (selected variant) is ignored because selected menu items do not
+     render supporting secondary text, making the selected-state override for supporting text
+     colors obsolete. */
+/* recursica-ignore: --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_supporting-text-color */
 
 /* HARDCODED VALUES:
    - border-style: solid. Structural rendering rule for the dropdown border (Mantine uses Paper which may not set border natively).
-   - opacity: 0.5 on disabled items. Recursica has no dedicated disabled-opacity token for menu items.
    - NOTE: overflow is intentionally NOT set on .dropdown. Mantine renders sub-menu dropdowns
      inside the parent dropdown DOM tree using Floating UI absolute positioning. Setting
      overflow: hidden clips sub-menus; overflow-y: auto causes unwanted scrollbars.
    - All structural layout (flex, cursor, pointer-events on disabled) is deferred to Mantine's
      native behavior. We only override visual design tokens (colors, typography, spacing, borders).
+   - Hover overlay: the schema no longer provides per-item hover-color/hover-opacity tokens; the
+     overlay now uses the generic --recursica_brand_states_hover_* tokens shared across components.
 */
 
 /* ======================================
@@ -19,7 +21,7 @@
 
 .dropdown {
   background-color: var(
-    --recursica_ui-kit_components_menu_properties_colors_background
+    --recursica_ui-kit_components_menu_properties_colors_background-color
   );
   border-style: solid; /* HARDCODE: Mantine Paper does not set border-style natively */
   border-width: var(--recursica_ui-kit_components_menu_properties_border-size);
@@ -34,10 +36,7 @@
   min-width: var(--recursica_ui-kit_components_menu_properties_min-width);
   max-height: var(--recursica_ui-kit_components_menu_properties_max-height);
   max-width: var(--recursica_ui-kit_components_menu_properties_max-width);
-
-  /* HARDCODE: Figma UI Kit does not export padding tokens for the Menu container itself. 
-     If added in the future, it would be mapped here. */
-  padding: 8px;
+  padding: var(--recursica_ui-kit_components_menu_properties_padding);
 }
 
 /* ======================================
@@ -55,6 +54,7 @@
   border-radius: var(
     --recursica_ui-kit_components_menu-item_properties_border-radius
   );
+  margin-bottom: var(--recursica_ui-kit_components_menu_properties_item-gap);
 
   /* Typography */
   font-family: var(
@@ -84,22 +84,27 @@
 
   /* Default State: Unselected */
   background-color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_background-color
   );
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_text
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_text-color
   );
   opacity: 1;
 }
+.item:last-of-type {
+  margin-bottom: 0;
+}
 
 /* Override Mantine's native hover background to use our overlay technique */
 .item:hover {
   background-color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_background-color
   );
 }
 
-/* Hover overlay using ::after pseudo-element (same technique as Accordion) */
+/* Hover overlay using ::after pseudo-element (same technique as Accordion); no per-item
+   hover-color/hover-opacity tokens exist anymore, so this uses the generic overlay tokens
+   uniformly regardless of selection state. */
 .item::after {
   content: "";
   position: absolute;
@@ -107,58 +112,46 @@
   border-radius: inherit;
   z-index: 0;
   pointer-events: none;
-  background-color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_hover-color
-  );
+  background-color: var(--recursica_brand_states_hover_color);
   opacity: 0;
   transition: opacity 150ms ease;
 }
 
 .item:hover:not([data-disabled])::after {
-  opacity: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_hover-opacity
-  );
+  opacity: var(--recursica_brand_states_hover_opacity);
 }
 
 /* Selected item state */
 .item[data-selected] {
   background-color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_background
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_background-color
   );
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_text
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_text-color
   );
   opacity: 1;
 }
 
-.item[data-selected]::after {
-  background-color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_hover-color
-  );
-}
-
 /* Hovered item state (keyboard navigation) */
 .item[data-hovered] {
   background-color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_background
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_background-color
   );
 }
 .item[data-hovered]::after {
-  opacity: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_hover-opacity
-  );
+  opacity: var(--recursica_brand_states_hover_opacity);
 }
 
-.item[data-hovered][data-selected]::after {
+/* Disabled item (opacity differs depending on selection state) */
+.item[data-disabled]:not([data-selected]) {
   opacity: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_hover-opacity
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_variants_states_disabled_properties_opacity
   );
 }
 
-/* Disabled item */
-.item[data-disabled] {
+.item[data-disabled][data-selected] {
   opacity: var(
-    --recursica_ui-kit_components_menu-item_properties_disabled-opacity
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_variants_states_disabled_properties_opacity
   );
 }
 
@@ -192,7 +185,7 @@
     --recursica_ui-kit_components_menu-item_properties_icon-text-gap
   );
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_leading-icon-color
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_leading-icon-color
   );
 }
 
@@ -205,19 +198,19 @@
   );
   margin-left: var(--recursica_ui-kit_components_menu-item_properties_text-gap);
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_trailing-icon-color
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_trailing-icon-color
   );
 }
 
 .item[data-selected] .itemSection[data-position="left"] {
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_leading-icon-color
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_leading-icon-color
   );
 }
 
 .item[data-selected] .itemSection[data-position="right"] {
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_selected-item_trailing-icon-color
+    --recursica_ui-kit_components_menu-item_variants_selection-states_selected_properties_colors_trailing-icon-color
   );
 }
 
@@ -271,7 +264,7 @@
   );
 
   color: var(
-    --recursica_ui-kit_components_menu-item_properties_colors_unselected-item_supporting-text-color
+    --recursica_ui-kit_components_menu-item_variants_selection-states_unselected_properties_colors_supporting-text-color
   );
   opacity: 0.7;
 }

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

@@ -1,9 +1,13 @@
 /* EXEMPTIONS:
-   - content-style and header-style parent variables represent raw JSON styling objects rather than 
+   - content-style and header-style parent variables represent raw JSON styling objects rather than
      direct CSS variables and cannot be applied directly in standard CSS files.
-     Sub-properties are fully and individually mapped to elements natively. */
+     Sub-properties are fully and individually mapped to elements natively.
+   - header/footer background-color are ignored because .header/.footer are intentionally
+     transparent (inheriting .content's background), matching Panel's header/footer treatment. */
 /* recursica-ignore: --recursica_ui-kit_components_modal_properties_content-style */
 /* recursica-ignore: --recursica_ui-kit_components_modal_properties_header-style */
+/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_footer-background-color */
+/* recursica-ignore: --recursica_ui-kit_components_modal_properties_colors_header-background-color */
 
 .root {
 }
@@ -37,7 +41,7 @@
 
   /* Appearance */
   background-color: var(
-    --recursica_ui-kit_components_modal_properties_colors_background
+    --recursica_ui-kit_components_modal_properties_colors_content-background-color
   );
   box-shadow: var(--recursica_ui-kit_components_modal_properties_elevation);
 
@@ -47,8 +51,12 @@
 }
 
 .header {
-  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
-    var(--recursica_ui-kit_components_modal_properties_horizontal-padding);
+  padding: var(
+      --recursica_ui-kit_components_modal_properties_header-footer-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
+    );
   background-color: transparent; /* Inherit from content */
 }
 
@@ -93,8 +101,12 @@
 }
 
 .scrollArea {
-  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
-    var(--recursica_ui-kit_components_modal_properties_horizontal-padding);
+  padding: var(
+      --recursica_ui-kit_components_modal_properties_content-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_modal_properties_content-horizontal-padding
+    );
 
   /* Internal scrolling */
   flex: 1 1 auto;
@@ -137,11 +149,11 @@
   /* Smooth divider transitions */
   transition: border-color 0.15s ease;
   border-top: var(
-      --recursica_ui-kit_components_modal_properties_scroll-divider-thickness
+      --recursica_ui-kit_components_modal_properties_scroll-divider-size
     )
     solid transparent;
   border-bottom: var(
-      --recursica_ui-kit_components_modal_properties_scroll-divider-thickness
+      --recursica_ui-kit_components_modal_properties_scroll-divider-size
     )
     solid transparent;
 }
@@ -159,8 +171,12 @@
 }
 
 .footer {
-  padding: var(--recursica_ui-kit_components_modal_properties_vertical-padding)
-    var(--recursica_ui-kit_components_modal_properties_horizontal-padding);
+  padding: var(
+      --recursica_ui-kit_components_modal_properties_header-footer-vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_modal_properties_header-footer-horizontal-padding
+    );
   background-color: transparent;
   display: flex;
   justify-content: flex-end;