@recursica/adapter-mui-v7 1.0.0

package/src/components/Tree/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,53 @@
+# Tree Implementation Notes
+
+- **New dependency: `@mui/x-tree-view`.** Neither `@mui/material` nor `@mui/lab` (already a peer dep, used for Timeline) ships a tree component. `@mui/x-tree-view`'s free/MIT community edition (`RichTreeView` + `TreeItem` building blocks) was added as an optional peer + dev dependency (mirroring how `@mui/lab` is declared), confirmed with the user before adding since it's a new external dependency, not a mechanical port.
+
+- **`RichTreeView` over `SimpleTreeView`.** `SimpleTreeView` is composable/children-based (you hand-write nested `<TreeItem>` JSX); `RichTreeView` is data-driven (`items` prop), matching Mantine's `data`-prop shape and our `RecursicaTreeProps.data` API far more directly. No conversion needed for `id`/`children` (bridged via `getItemId`), only `getItemLabel`.
+
+- **Fully custom `slots.item` (`CustomTreeItem`), not the default `TreeItem`.** Every visual property comes from `Tree.module.css` rather than `@mui/x-tree-view`'s own default styles (which apply real theme palette colors for hover/selected/focused states that would otherwise fight our tokens). `CustomTreeItem` is built from the officially-documented low-level building blocks (`useTreeItem`, `TreeItemProvider`, `TreeItemRoot`, `TreeItemContent`, `TreeItemIconContainer`, `TreeItemGroupTransition`, `TreeItemLabel`, `TreeItemIcon`) — the same pattern MUI X's own docs use for "rich"/custom tree items — rather than rebuilding keyboard/focus/ARIA handling from scratch.
+
+- **`getItemLabel` only ever sees a string; the real `React.ReactNode` label comes from `useTreeItemModel`.** `RichTreeView`'s internal model requires `getItemLabel(item): string` (used for its own a11y/typeahead search), so a non-string `RecursicaTreeNode.label` is coerced to `item.value` there — this string is _never actually rendered_. Inside `CustomTreeItem`, `useTreeItemModel<RecursicaTreeNode>(itemId)` retrieves the **original** untransformed node (real `label: ReactNode` included), which is what actually gets rendered in `<TreeItemLabel>`. This is the documented MUI X mechanism for rich/custom tree item content — not a workaround.
+
+- **`TreeItemContent` requires a `status` prop.** Its styled-component variant system reads `status: UseTreeItemStatus` directly (not just via `getContentProps()`'s spread) — omitting it is a compile error, not just a missing visual detail.
+
+- **Indentation: preserve MUI's own depth formula, override only the base.** MUI computes each row's `padding-left` as `calc(<base> + --TreeView-itemChildrenIndentation * --TreeView-itemDepth)`, with `--TreeView-itemChildrenIndentation` set as an **inline style** on the root `<ul>` (see `useTreeViewRootProps` in `@mui/x-tree-view/internals`). `Tree.module.css` overrides that CSS variable with `!important` (same category of override as the mantine-adapter's `--level-offset`, itself modeled on this adapter's own Timeline `--mantine-spacing-xl` / `--tl-line-width` precedent — inline styles beat plain stylesheet rules regardless of specificity, so `!important` is required, not optional). `.row`'s own `padding-left` then reuses the same `calc(... + --TreeView-itemChildrenIndentation * --TreeView-itemDepth)` formula, just substituting our `horizontal-padding` token as the base instead of MUI's theme spacing — so per-level indentation keeps working, only its amount changes.
+
+- **No `!important` needed for color/hover/selected/disabled overrides.** Unlike the CSS-variable overrides above, these come from `@mui/x-tree-view`'s own Emotion-generated _stylesheet_ rules (not inline styles). Because this app's `<StyledEngineProvider injectFirst>` setup (required per `SETUP.md`, already configured in `.storybook/preview.tsx`) injects MUI's baseline styles before our CSS Modules, our classes win via normal DOM source order — matching `COMPONENT_DEV_GUIDE.md`'s explicit "no `!important`" rule for this category, and the existing `Button`/`Menu` precedent in this adapter.
+
+- **`expandOnClick`/`selectOnClick` are approximated, not exact.** Mantine's `Tree` has two independent boolean toggles for these. `@mui/x-tree-view` only has `expansionTrigger: 'content' | 'iconContainer'` (does clicking the row content expand it, or only the icon container?) and `disableSelection` (turns off selection everywhere, not just on a content click). Mapping used: `expansionTrigger = expandOnClick ? "content" : "iconContainer"`, `disableSelection = !selectOnClick`. The specific combination "clicking anywhere expands, but nothing is ever selectable via click" has no exact MUI equivalent beyond `disableSelection` — documented here rather than silently diverging without explanation.
+
+- **Deliberately not implemented (no tokens back them):** checkbox/indeterminate node state (`@mui/x-tree-view` supports `checkboxSelection`, but the Figma UI Kit's `tree` tokens only define `selected`/`unselected`, not a checked state) and per-node `disabled` (no token, and no `disabled` field in `RecursicaTreeNode`). Matches the mantine-adapter implementation's same decision.
+
+- **RESOLVED (2026-08-08) — KNOWN GAP (2026-08-06): Forge's own preview shows a red chevron with more chevron-to-label spacing than what's currently implemented here.** Explained by the Button swap below: Forge's chevron is Button's own "text" variant color (Recursica's red/alert-adjacent brand color), not a `tree`-namespace icon-color token — there never was a missing token to find. Re-verified against both the compiled `recursica_variables_scoped.css` and the raw `recursica_ui-kit.json` at the time: the `tree` schema has no `icon-color` property at all, and `button-node-gap` (used as `.row`'s `gap`) resolves to exactly 4px — confirmed not a mapping bug on our side, just the wrong mental model (a hand-drawn glyph instead of an actual Button).
+
+- **Keyboard nav (Matt Massey, 2026-08-08): arrow up/down already worked — only the focus ring was missing.** `@mui/x-tree-view`'s own `useTreeItem` already implements full WAI-ARIA roving-tabindex keyboard navigation — confirmed via Playwright that focus genuinely moves between rows on `ArrowDown`. The reason it looked broken: DOM focus lands on `.node` (the same `<li role="treeitem">` `TreeItemRoot` renders as), and `.row`'s only focus-related rule reset MUI's own focused-state _background color_ back to the unselected default — no replacement focus indicator was ever added. Fixed by adding the same `:focus-visible` box-shadow ring every other focusable component uses, keyed off `.node:focus-visible` since that's where DOM focus actually lands. Originally drawn on `.row` (the whole button+label box); see the next entry for why it now targets `.label` only.
+
+- **Chevron → `Button` (Matt Massey, 2026-08-08).** Forge's real design uses an actual `Button` (`variant="text"` `size="small"`, icon-only) for the expand/collapse chevron, not a hand-drawn glyph — see the resolved "KNOWN GAP" above. `ExpandGlyph`/`CollapseGlyph`/`EndGlyph` (the three `slots.expandIcon`/`collapseIcon`/`endIcon` components MUI's `TreeItemIcon` picks between based on row state) now all delegate to a shared `ExpandToggleButton`, which renders a real `<Button icon={<ChevronGlyph/>} tabIndex={-1} aria-hidden="true" .../>`:
+
+  - **Doesn't reopen any nested-focusable-element concern**: the embedded Button is never independently focusable or tab-stoppable (`tabIndex={-1}`) and is hidden from assistive tech (`aria-hidden`) — the row (`.node`) stays the single focusable/interactive element. Confirmed MUI's `ButtonBase` doesn't call `stopPropagation()` on click, so clicking the chevron still bubbles up to `TreeItemContent`'s existing click handling and triggers expand/collapse exactly as before — no `onClick` needed on the embedded Button itself.
+  - **Rendered for every row, including leaves** (`EndGlyph` → `ExpandToggleButton hidden`), so every row reserves identical layout space; a `.expandButtonHidden { visibility: hidden; }` class hides it on leaf rows without needing to duplicate Button's own size tokens for a placeholder. `.iconContainer`'s old hardcoded `width: 1em` (sized for the previous plain-SVG glyph) was removed so the real Button can size itself from its own tokens.
+  - **Rotation targets the glyph directly, not Button's internals**: `ChevronGlyph`'s `<svg>` carries its own `styles.chevron`/`styles.chevronExpanded` classes directly, not reached through Button's DOM at all — `Button`'s own `.iconWrapper` isn't reachable from `Tree.module.css` in the first place (CSS Modules don't expose a stable cross-file class name for it, unlike MUI's own stable `Mui*` global classes used elsewhere in this file).
+  - **Focus ring narrowed to `.label` only, excluding the Button** (Matt: "the focus ring for an item should be around just the node, not including the chevron button" / "the chevron button should not have a focus state"). `.label` was given `flex: 1 1 auto; height: 100%` so the ring still reads as a clean box covering the row's remaining width, not a tight text-only outline.
+  - **Found and fixed a real, separate bug while embedding this**: `Button.tsx` (both adapters) explicitly sets `className={finalClass}` (merging `styles.root` with any caller className) but then spreads `{...sanitizedProps}` _after_ it — and `sanitizedProps` still contains the original, unmodified `className` key, since it was only _read_, never deleted. The later spread silently overwrote `finalClass` with just the caller's own class whenever one was passed (e.g. `styles.expandButton` here) — exact same bug class as this adapter's own `Dropdown.tsx`/`BareDropdown.tsx` had. This was fully visible here: the chevron rendered in MUI's own default blue (`MuiButton-colorPrimary`), since `Button-module__root` — and therefore every `[data-variant]` color rule — was missing from the DOM entirely. Confirmed mantine-adapter had the identical bug in its own `Button.tsx`, just masked there by a separate `classNames={{root: ...}}` object prop unaffected by the overwrite — fixed in both regardless.
+
+- **Expand/collapse and select made fully independent (Matt Massey, 2026-08-10), superseding the "approximated, not exact" `expandOnClick`/`selectOnClick` mapping described above.** Matt clarified the real requirement: the button must be the _only_ way to expand/collapse on click, a row click must _only_ select, `Enter`/`Space` must _only_ select (never expand, even on a node with children), and `ArrowLeft`/`ArrowRight` must _only_ expand/collapse (never select) — letting a user toggle a subtree open without ever changing selection, and vice versa. Removed `expandOnClick`/`selectOnClick` entirely (per point 5 of that request), since the old approximation problem disappears once the pattern is fixed rather than configurable.
+
+  - **Click**: `expansionTrigger` is now unconditionally `"iconContainer"` (previously `expandOnClick ? "content" : "iconContainer"`). That alone wasn't enough: `@mui/x-tree-view`'s `createContentHandleClick` (wired onto `TreeItemContent`/`.row`) calls `interactions.handleSelection` on _any_ click that reaches it — including a click on the icon container, since it's a DOM descendant of the content and the icon container's own click handler never stops propagation. `CustomTreeItem` now wraps `getIconContainerProps()`'s `onClick` with `event.stopPropagation()` before delegating to it, so an icon-container click still expands/collapses (via the library's own `createIconContainerHandleClick`) but never bubbles up to also select.
+  - **Enter**: `@mui/x-tree-view`'s own keyboard plugin expands an expandable node on `Enter` and only falls back to selecting when the node has no children — not what we need (`Enter` must always select). `Space` already selects unconditionally by default, so it needed no change. Overrode just `Enter` via `getRootProps({..., onKeyDown: handleRootKeyDown})`: `useTreeItem`'s `createRootHandleKeyDown` runs any externally-supplied `onKeyDown` _before_ its own internal handling and skips that internal handling entirely if the external handler sets `event.defaultMuiPrevented = true` — the library's documented extension point for exactly this kind of override, not an undocumented hack. `handleRootKeyDown` calls `interactions.handleSelection` (from `useTreeItemUtils`, the same hook `useTreeItem` uses internally) directly. `ArrowLeft`/`ArrowRight` needed no changes — the built-in handling already only calls `store.expansion.setItemExpansion`, never touches selection.
+  - **Background/focus scoped to the label, not the whole node** (Matt: "The focus/background color should be on the node's label, not the entire node"): moved every visual property (padding, border, font, unselected/selected colors, hover overlay) off `.row` and onto `.label` — `.row` is now a plain flex layout container (indentation + `button-node-gap` only). `data-selected`/`data-focused` are still only set on `.row` (via `getContentProps()`), so the selected-state rule now reads `.row[data-selected] .label` (a descendant selector) instead of styling `.row` directly; same for the hover overlay (`.row:hover .label::after`). The focus ring (added in the entry above) already targeted `.label` only, so it needed no further change.
+
+- **Three follow-on fixes to the label-scoping work above (Matt Massey, 2026-08-10):**
+
+  - **Selected/hover chip was full-row width, not label width, in both adapters.** `.label` had `flex: 1 1 auto` — the `1` flex-grow stretched it to fill `.row`'s entire remaining width (icon container aside), so the highlighted chip visually covered the whole row even though the _properties_ were correctly scoped to `.label`. Changed to `flex: 0 1 auto`, but that alone wasn't enough here (unlike mantine-adapter): `@mui/x-tree-view`'s own `.MuiTreeItem-label` sets a literal `width: 100%`, which a flex-basis change can't beat since it's a direct `width` declaration, not a sizing default. Added an explicit `width: auto` to `.label` to override it.
+  - **Focusing an expanded parent drew the ring on every descendant label too, in both adapters.** `.node:focus-visible .label` is a plain descendant selector — every child node's `.label` (inside the nested `.subtree` `<ul>`) is _also_ a descendant of the focused parent's `.node` `<li>`, at any depth, so the ring matched all of them at once. Fixed by scoping to `.node:focus-visible > .row .label`: `.row` is always a direct child of its own `.node`, but never of an ancestor `.node` (those reach it through the intervening `.subtree` `<ul>` and nested `<li>` instead) — the `>` combinator excludes every one of them.
+  - **MUI-only: a leftover default selected background was still showing through.** `@mui/x-tree-view`'s own `TreeItemContent` ships a built-in selected tint (`rgba(25, 118, 210, 0.08)`, and a separate, higher-specificity `rgba(25, 118, 210, 0.2)` for the `[data-selected][data-focused]` combination specifically) that the earlier `.row:hover, .row[data-focused] { background-color: transparent; }` neutralizer never covered. Added `.row[data-selected]` to that neutralizer — but the `[data-selected][data-focused]` compound needed its _own_ explicit rule too: MUI's equivalent compound selector has higher specificity (two attribute selectors plus its own class) than a single-attribute `.row[data-selected]` rule, so it kept winning regardless of source order until matched with an equally-specific `.row[data-selected][data-focused]` rule on our side.
+
+- **Whole-tree `disabled` (Matt Massey, 2026-08-10), added to support a `Disabled` story.** Unlike mantine-adapter (which has zero `disabled` concept anywhere in its `Tree` API — see its own note on this), `@mui/x-tree-view` already had per-item `disabled` plumbing sitting mostly dormant here: `CustomTreeItem` already destructured `disabled` off `UseTreeItemParameters`, and `.row[data-disabled] { opacity: ...; cursor: auto; }` already existed in `Tree.module.css` — just with no way for a caller to actually set it, since `RecursicaTreeNode` has no `disabled` field (and still doesn't; per-node disabling remains unexposed, same reasoning as the existing "Deliberately not implemented" entry above).
+
+  - **Implementation**: `isItemDisabled={disabled ? () => true : undefined}` passed to `<RichTreeView>` — marking every item disabled at once, reusing the library's own per-item mechanism rather than inventing a parallel one. `interactions.handleExpansion`/`handleSelection` (used by both the icon container's click handling and our own `Enter`-key override) already check `status.disabled` internally and no-op, so nothing in `CustomTreeItem` needed an extra guard.
+  - **Visual**: the pre-existing `.row[data-disabled]` rule now actually activates. Verified a pre-selected node's chip stays visible underneath the dimming (`.row[data-selected] .label` and `.row[data-disabled]` are independent, non-conflicting selectors — one styles `.label`, the other dims the whole `.row` via `opacity`), per Matt's ask to check that combination.
+  - **Found while verifying**: disabled rows still showed the hover tint (`.label::after` opacity) on mouse-over — MUI's own disabled checks block the actual select/expand _action_ on click, but `:hover` is pure CSS with nothing stopping it. Added `pointer-events: none` to `.row[data-disabled]`, matching mantine-adapter's `.root[data-disabled]` (tree-wide there; per-row here, since MUI's disabled state is inherently per-item even when every item is disabled at once by the same whole-tree prop).
+
+- **`ExpandToggleButton` could still steal DOM focus despite `tabIndex={-1}` (Matt Massey, 2026-08-24), caught via a live browser console warning, in both adapters.** `tabIndex={-1}`/`aria-hidden` only removes the embedded chevron `Button` from the sequential tab order; it doesn't stop a native `<button>` from receiving DOM focus on a direct mouse click on the chevron, which browsers still do regardless of `tabIndex`. Since the button also has `aria-hidden="true"`, clicking it left an aria-hidden element holding focus — flagged by Chrome as "Blocked aria-hidden on an element because its descendant retained focus." Fixed with `onMouseDown={(event) => event.preventDefault()}` on the `Button` inside `ExpandToggleButton`: this suppresses the browser's default click-focuses-the-target behavior without affecting expand/collapse (still driven entirely by `TreeItemIconContainer`'s own click handling, untouched by this). Same fix applied to mantine-adapter's embedded chevron `Button`.
+
+- **Chevron/label gap was actually negative (source-of-truth audit, 2026-08-30).** `.row`'s flex `gap` (`button-node-gap` token) measured correctly as 4px between `.iconContainer` and `.label` via `getComputedStyle`, but the _rendered_ gap between the visible chevron button and the label text was -4px (an 8px overlap) per live `getBoundingClientRect()` — mantine's equivalent measured the correct +4px. Root cause: MUI's own `.MuiTreeItem-iconContainer` hardcodes `width: 16px` (sized for a plain icon glyph); our expand `Button` is 32px and doesn't shrink to fit, so it overflowed its 16px flex-box footprint by 8px on each side while the _container's_ box (the actual flex gap participant) stayed narrow. Fixed with `width: auto` on `.iconContainer` so it sizes to its real (button) content instead of MUI's icon-sized default — verified gap is now +4px on every row, matching mantine exactly.

package/src/components/Tree/Tree.module.css

@@ -0,0 +1,272 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover/focus/disabled state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' / 'Disabled state' — implicit rule for every interactive element; components must not define their own per-component treatment).
+ *   recursica-allow-brand: --recursica_brand_states_disabled
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
+/* HARDCODED VALUES:
+ * - list-style/margin/padding resets on .root/.subtree/.node: layout resets, no corresponding
+ *   design tokens (structural, not visual design values).
+ * - .chevron rotation timing (150ms ease): no dedicated timing token exists for Tree; the glyph
+ *   itself is sized/colored entirely by Button's own "text"/"small" tokens now, not a hand-drawn
+ *   size/color like the previous plain-SVG implementation.
+ * - Hover overlay uses the generic --recursica_brand_states_hover_* tokens (same technique as
+ *   Menu/Accordion/Button): Tree has no component-specific hover tokens of its own.
+ * - .row's padding-left keeps MUI's own depth-based indentation formula (indent * depth), just
+ *   without the horizontal-padding base — that base now lives on .label instead (see below).
+ *
+ * NOTE: the row's box model (padding/border/font/color/background) lives entirely on `.label`,
+ * not `.row` — the highlighted "chip" (hover/selected/focus) covers only the label, never the
+ * expand button. `.row` itself is a plain flex layout container (indentation + button-node-gap).
+ */
+
+.root {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  outline: 0;
+  max-width: var(--recursica_ui-kit_components_tree_properties_max-width);
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_tree_properties_item-gap);
+
+  /* MUI sets this as an inline style on the root <ul> (see useTreeViewRootProps in
+     @mui/x-tree-view). Override with !important to reliably beat it regardless of stylesheet
+     injection order (same category of override as mantine-adapter's --level-offset, itself
+     modeled on Timeline's --mantine-spacing-xl / --tl-line-width). */
+  --TreeView-itemChildrenIndentation: var(
+    --recursica_ui-kit_components_tree_properties_indent
+  ) !important;
+}
+
+.subtree {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: var(--recursica_ui-kit_components_tree_properties_item-gap);
+}
+
+.node {
+  list-style: none;
+}
+
+/* @mui/x-tree-view's roving-tabindex keyboard navigation (arrow up/down moves focus between
+   rows, left/right expand/collapse, matching the WAI-ARIA treeitem pattern) already works out of
+   the box — but with no visible indicator, it looked broken. DOM focus lands on this <li> (.node),
+   not the visible row box, so the ring is drawn on .label instead — the "node" content area,
+   deliberately excluding the expand Button, which never shows a focus state of its own (it's not
+   independently focusable at all: tabIndex={-1}). */
+.node:focus-visible {
+  outline: none;
+}
+/* `> .row` (child combinator), not a plain descendant selector: a node's own `.row` is always a
+   direct child of its `.node` <li>, while every descendant node's `.row` (inside the nested
+   `.subtree` <ul>) is not — without the `>`, focusing a parent node drew the ring on every
+   expanded descendant's label too, since they're all still descendants of the focused `.node`. */
+.node:focus-visible > .row .label {
+  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);
+}
+
+.row {
+  position: relative;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  width: 100%;
+  cursor: pointer;
+  gap: var(--recursica_ui-kit_components_tree_properties_button-node-gap);
+  padding-left: calc(
+    var(--TreeView-itemChildrenIndentation, 0px) * var(--TreeView-itemDepth, 0)
+  );
+}
+
+/* Neutralize MUI's own hover/focused/selected background-color changes (see TreeItemContent's
+   defaults in @mui/x-tree-view, e.g. its built-in `rgba(25, 118, 210, 0.08)` selected tint) so
+   only the Recursica hover overlay and selected styling on .label below control the look; .row
+   itself carries no background-color of its own to fall back to now. The `[data-selected]
+   [data-focused]` compound needs its own rule: MUI's own equivalent compound selector has higher
+   specificity (2 attributes + its class) than a single-attribute `.row[data-selected]` rule
+   would, so it would otherwise still win regardless of source order. */
+.row:hover,
+.row[data-focused],
+.row[data-selected],
+.row[data-selected][data-focused] {
+  background-color: transparent;
+}
+
+.row[data-disabled] {
+  opacity: var(--recursica_brand_states_disabled);
+  cursor: auto;
+  /* MUI's own disabled checks already block select/expand on click, but hover is pure CSS —
+     without this, a disabled row still showed the hover tint (.label::after opacity) on mouse-
+     over, misleadingly suggesting it's interactive. Matches mantine-adapter's `.root[data-
+     disabled] { pointer-events: none; }`, just scoped per-row instead of tree-wide, since MUI's
+     disabled state is a per-item concept even when driven by our own whole-tree prop. */
+  pointer-events: none;
+}
+
+.iconContainer {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: inherit;
+  /* MUI's own `.MuiTreeItem-iconContainer` hardcodes `width: 16px` (sized for a
+     plain icon glyph), narrower than our 32px expand `Button`. The button
+     doesn't shrink to fit, so it overflowed this container by 8px on each
+     side — meaning `.row`'s `gap` (button-node-gap) measured a 4px space
+     between the *container* and `.label`, while the actual button visually
+     overlapped the label by 4px. `width: auto` lets the container size to its
+     real (button) content instead of MUI's icon-sized default. */
+  width: auto;
+}
+
+/* The expand Button is always rendered (even for leaf nodes, which have nothing to toggle) so
+   every row reserves identical layout space — hidden via visibility (not display) on leaf rows so
+   the label stays aligned across the whole tree without duplicating Button's own size tokens. */
+.expandButton {
+  flex-shrink: 0;
+}
+.expandButtonHidden {
+  visibility: hidden;
+}
+
+.chevron {
+  transition: transform 150ms ease;
+}
+.chevronExpanded {
+  transform: rotate(90deg);
+}
+
+.label {
+  position: relative;
+  z-index: 1;
+  /* Sized to its own content, not stretched to fill the row's remaining width — the
+     hover/selected/focus "chip" should cover just the label, not the full row width.
+     `width: auto` is required in addition to `flex: 0 1 auto`: MuiTreeItem's own default
+     `.MuiTreeItem-label` sets a literal `width: 100%`, which a flex-basis alone can't beat. */
+  flex: 0 1 auto;
+  width: auto;
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  padding: var(--recursica_ui-kit_components_tree_properties_vertical-padding)
+    var(--recursica_ui-kit_components_tree_properties_horizontal-padding);
+  border-style: solid; /* HARDCODE: structural border rule; thickness/color are tokened */
+  border-width: var(--recursica_ui-kit_components_tree_properties_border-size);
+  border-radius: var(
+    --recursica_ui-kit_components_tree_properties_border-radius
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_text-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_unselected_properties_colors_border-color
+  );
+}
+
+/* Hover overlay via ::after pseudo-element (same technique as Menu/Accordion), scoped to the
+   label's own box so hover never visually covers the expand button. `.label`'s `position:
+   relative` + `z-index: 1` above already forms a stacking context, so `z-index: -1` here paints
+   the overlay behind the label's real text content within that context, not behind `.label`
+   itself. */
+.label::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: -1;
+  pointer-events: none;
+  background-color: var(--recursica_brand_states_hover_color);
+  opacity: 0;
+  transition: opacity 150ms ease;
+}
+.row:hover .label::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+/* Selected state — read off `.row`'s own `data-selected`/`data-focused` (set by
+   `getContentProps()`), applied to `.label`. Written after the hover/focus reset above so it
+   wins the equal-specificity tie via source order, including when hovered/focused while
+   selected. */
+.row[data-selected] .label,
+.row[data-selected]:hover .label,
+.row[data-selected][data-focused] .label {
+  font-family: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_text_text-transform
+  );
+
+  color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_text-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_tree_variants_selection-states_selected_properties_colors_border-color
+  );
+}

package/src/components/Tree/Tree.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tree } from "./Tree";
+import { Layer, type RecursicaTreeNode } from "@recursica/adapter-common";
+
+const sampleData: RecursicaTreeNode[] = [
+  {
+    value: "documents",
+    label: "Documents",
+    children: [
+      { value: "documents/resume.pdf", label: "resume.pdf" },
+      { value: "documents/cover-letter.docx", label: "cover-letter.docx" },
+      {
+        value: "documents/taxes",
+        label: "Taxes",
+        children: [
+          { value: "documents/taxes/2023.pdf", label: "2023.pdf" },
+          { value: "documents/taxes/2024.pdf", label: "2024.pdf" },
+        ],
+      },
+    ],
+  },
+  {
+    value: "photos",
+    label: "Photos",
+    children: [
+      { value: "photos/vacation.jpg", label: "vacation.jpg" },
+      { value: "photos/family.jpg", label: "family.jpg" },
+    ],
+  },
+  { value: "readme.md", label: "readme.md" },
+];
+
+const meta: Meta<typeof Tree> = {
+  title: "UI-Kit/Tree",
+  component: Tree,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Tree\` component renders hierarchical \`data\` as an expandable/selectable tree, wrapping \`@mui/x-tree-view\`'s \`RichTreeView\` with a fully custom item renderer so every visual property (row box model, selected/unselected colors and typography, indent, item spacing) comes from Recursica's \`tree\` design tokens.
+
+Each node needs a unique \`value\` and a \`label\`; a \`children\` array (even empty) makes a node expandable.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+export const Default: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree data={sampleData} initialExpandedValues={["documents"]} />
+  ),
+};
+
+export const AllExpanded: StoryObj<typeof Tree> = {
+  render: () => <Tree data={sampleData} initialExpandedValues="*" />,
+};
+
+export const PreSelected: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree
+      data={sampleData}
+      initialExpandedValues={["documents"]}
+      initialSelectedValues={["documents/resume.pdf"]}
+    />
+  ),
+};
+
+export const MultipleSelection: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree
+      data={sampleData}
+      initialExpandedValues="*"
+      initialSelectedValues={["documents/resume.pdf", "photos/vacation.jpg"]}
+      multiple
+    />
+  ),
+};
+
+/** Whole tree disabled, with a node pre-selected so the selected chip's styling under the
+ * disabled dimming can be checked alongside unselected rows. */
+export const Disabled: StoryObj<typeof Tree> = {
+  render: () => (
+    <Tree
+      data={sampleData}
+      initialExpandedValues={["documents"]}
+      initialSelectedValues={["documents/resume.pdf"]}
+      disabled
+    />
+  ),
+};
+
+/** 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 Tree> = {
+  render: () => (
+    <Layer layer={1} style={{ padding: "24px" }}>
+      <Tree data={sampleData} initialExpandedValues={["documents"]} />
+    </Layer>
+  ),
+};

package/src/components/Tree/Tree.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Tree component tests. Add tests here if/when needed.