@sixthshift/design-system 0.5.0 → 0.6.0

package/src/{theme/recipes/button.css → components/Button/button.recipe.css}

@@ -8,7 +8,7 @@
  * or intent the library never shipped.
  *
  * The grammar is `--button-{context}[-{state}]` — the same `context` and
- * `state` words the semantic layer uses (src/theme/schema.ts). Note what is
+ * `state` words the semantic layer uses (src/theming/vocabulary.ts). Note what is
  * deliberately *absent*: intent and weight never appear in a token name. They
  * select, via the `data-` attributes below. Putting them in the name
  * (`--button-bg-danger`) would restore the combinatorial explosion this layer
@@ -47,7 +47,7 @@
     --button-fg: var(--fg-on-brand);
   }
 
-  /* `neutral` means *no colour family* — the grey tiers. It used to resolve to
+  /* `neutral` means *no colour family* — the grey ramp. It used to resolve to
      the brand fill, which made `intent="neutral"` mean one thing on Button and
      another on Badge and Message, where it was already grey. Button
      was the outlier; this is the cell that ends that. A brand-coloured button

package/src/components/Calendar/Calendar.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { useCallback, useMemo } from "react";
 import {

package/src/components/Calendar/CalendarView.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 /**
  * CalendarView — the Temporal-typed calendar grid.
  *

package/src/components/Calendar/calendar.hooks.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback, useMemo } from "react";
 import { addDays, formatDateMediumYear, isPlainDate, isSameDay, isSameMonth, startOfMonth, startOfWeek, Temporal, today } from "../../date-time";
 import type { DateRangeValue, DateSelectionState, DisabledDateMatcher, SelectionMode } from "./calendar.types";

package/src/components/Card/Card.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
@@ -6,7 +8,7 @@ import * as React from "react";
  * Geometry only, plus the five `--card-*` component tokens.
  *
  * Every colour reads a `--card-*` token whose value is decided by
- * src/theme/recipes/card.css. `size` stays here: it is pure geometry
+ * src/components/Card/card.recipe.css. `size` stays here: it is pure geometry
  * (padding, header gap, corner radius), not colour, so it has no reason to
  * move — the same split Message.tsx documents.
  *
@@ -108,7 +110,7 @@ export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> &
  * `role="button"`, `tabIndex={0}`, and both Enter and Space activate it, not
  * just a pointer click. Omit `onClick` for a purely presentational card.
  *
- * Colour reads `--card-*` component tokens (src/theme/recipes/card.css) —
+ * Colour reads `--card-*` component tokens (src/components/Card/card.recipe.css) —
  * the same seam Button and Badge use — so a consumer can re-point them
  * without a release.
  */

package/src/components/Checkbox/Checkbox.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { Label } from "@sixthshift/design-system/label";
 import { cn } from "@sixthshift/design-system/utils";

package/src/components/CheckboxGroup/CheckboxGroup.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Checkbox } from "@sixthshift/design-system/checkbox";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";

package/src/components/Code/Editor/Editor.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import MonacoEditor from "@monaco-editor/react";
 import type { editor } from "monaco-editor";
 import type { HTMLAttributes } from "react";

package/src/components/Code/Workspace/StatusBar.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { HTMLAttributes, ReactNode } from "react";
 
 export type StatusBarItem = {

package/src/components/Code/Workspace/Toolbar.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { HTMLAttributes, ReactNode } from "react";
 import { Button } from "../../Button";
 

package/src/components/Code/Workspace/Workspace.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { HTMLAttributes, ReactNode } from "react";
 import { useState } from "react";
 import { Editor } from "../Editor";

package/src/components/DatePicker/DatePicker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
@@ -19,6 +21,7 @@ import {
   toISODateRange,
 } from "../../date-time";
 import { PickerField } from "../../internal";
+import { useEscapeLayer } from "../../internal/escapeLayers";
 import { CalendarView } from "../Calendar/CalendarView";
 import { isDateDisabled } from "../Calendar/calendar.hooks";
 import type { PresetOption } from "../Calendar/calendar.types";
@@ -236,6 +239,10 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
 
   const click = useClick(context);
   const dismiss = useDismiss(context);
+
+  // While open, an Escape press closes this picker's popover and must not
+  // also close a Modal/Sheet it is rendered inside.
+  useEscapeLayer(open);
   const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
 
   // IDs for accessibility

package/src/components/DatePicker/DateSegments.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { type Temporal, today, toISODate } from "../../date-time";
 import { SegmentedField, type SegmentSpec, type SegmentValues } from "../../internal";
 import type { DateSegmentOrder } from "./datepicker.types";

package/src/components/DatePicker/datepicker.hooks.ts

@@ -1,3 +1,5 @@
+"use client";
+
 import { useCallback } from "react";
 import { formatDateMediumYear, isPlainDate, Temporal } from "../../date-time";
 import type { DatePickerMode, DateRangeValue, DateSelectionState, DisabledDateMatcher } from "./datepicker.types";

package/src/components/DateRangePicker/DateRangePicker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { useMemo } from "react";
 import { addDaysISO, startOfMonthISO, todayISO } from "../../date-time";

package/src/components/DateTimePicker/DateTimePicker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
@@ -13,8 +15,8 @@ import {
   today,
   toISOInstantOrUndefined,
 } from "../../date-time";
-
 import { PickerField } from "../../internal";
+import { useEscapeLayer } from "../../internal/escapeLayers";
 import { Button } from "../Button";
 import { CalendarView } from "../Calendar/CalendarView";
 import { isDateDisabled } from "../Calendar/calendar.hooks";
@@ -251,6 +253,10 @@ export const DateTimePicker = React.forwardRef<HTMLDivElement, DateTimePickerPro
 
   const click = useClick(context);
   const dismiss = useDismiss(context);
+
+  // While open, an Escape press closes this picker's popover and must not
+  // also close a Modal/Sheet it is rendered inside.
+  useEscapeLayer(open);
   const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
 
   // IDs for accessibility

package/src/components/DateTimePicker/DateTimeSegments.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Temporal } from "../../date-time";
 import { SegmentedField, type SegmentSpec, type SegmentValues } from "../../internal";
 import { dateFromSegments, dateSpec, dateToSegments, parseDatePasteIn } from "../DatePicker/DateSegments";

package/src/components/DateTimeRangePicker/DateTimeRangePicker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
@@ -16,8 +18,8 @@ import {
   toISOInstant,
   toISOInstantRange,
 } from "../../date-time";
-
 import { PickerField } from "../../internal";
+import { useEscapeLayer } from "../../internal/escapeLayers";
 import { Button } from "../Button";
 import { CalendarView } from "../Calendar/CalendarView";
 import { isDateDisabled } from "../Calendar/calendar.hooks";
@@ -412,6 +414,10 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
 
   const click = useClick(context);
   const dismiss = useDismiss(context);
+
+  // While open, an Escape press closes this picker's popover and must not
+  // also close a Modal/Sheet it is rendered inside.
+  useEscapeLayer(open);
   const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
 
   // IDs for accessibility

package/src/components/FormField/FormField.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Label } from "@sixthshift/design-system/label";
 import { Message } from "@sixthshift/design-system/message";
 import { Muted } from "@sixthshift/design-system/muted";
@@ -10,61 +12,111 @@ export type FormFieldFeedback = {
 };
 
 export type FormFieldProps = React.HTMLAttributes<HTMLDivElement> & {
-  label: string;
-  description?: string;
+  label: React.ReactNode;
+  description?: React.ReactNode;
   feedback?: FormFieldFeedback;
   required?: boolean;
 };
 
+/** What FormField knows about the control it wraps — see `useFormField`. */
+export type FormFieldContextValue = {
+  /** The id the control should carry, and the label's `htmlFor` target. */
+  id: string;
+  /** Space-separated ids of the description/feedback texts, for `aria-describedby`. `undefined` when there are none. */
+  describedBy: string | undefined;
+  /** True when `feedback.intent` is `"danger"` — the control should set `aria-invalid`. */
+  invalid: boolean;
+  /** Mirrors the `required` prop, for `aria-required`/`required` on the control. */
+  required: boolean;
+};
+
+const FormFieldContext = React.createContext<FormFieldContextValue | null>(null);
+
+/**
+ * The wiring `FormField` provides to whatever control it wraps: `id`,
+ * `describedBy`, `invalid`, `required`. Direct element children get these
+ * cloned on automatically; a control nested deeper — inside a wrapper div, a
+ * render prop, a custom composite — can call this instead and apply them
+ * itself. Returns `null` outside a `FormField`.
+ */
+export const useFormField = () => React.useContext(FormFieldContext);
+
 /**
  * Wraps a form control with a label, optional description, and optional
  * validation feedback — the composition point for `Input`, `Textarea`,
  * `Select` and similar controls inside a form.
  *
- * Generates an `id` (or uses the one passed in) and clones it, plus
- * `aria-describedby` (pointing at the description and/or feedback text) and
- * `aria-invalid` (when `feedback.intent` is `"danger"`), onto its child —
- * so the wrapped control does not need those wired by hand. It expects a
- * single child control: the same id and aria attributes get cloned onto
- * every child if more than one is passed.
+ * Generates an `id` (or uses the one passed in) and wires it, plus
+ * `aria-describedby` (pointing at the description and/or feedback text),
+ * `aria-invalid` (when `feedback.intent` is `"danger"`) and `aria-required`
+ * (when `required`), onto the first element child. A child's own attributes
+ * win: an explicit `id` is kept (and becomes the label's `htmlFor` target),
+ * an existing `aria-describedby` is merged with FormField's rather than
+ * replaced. Controls that aren't the first element child can self-wire via
+ * `useFormField`.
  *
  * Distinct from `Field`, which displays a read-only label/value pair rather
  * than wrapping an interactive control.
  */
-const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(({ className, label, description, feedback, required, children, id, ...props }, ref) => {
-  const generatedId = React.useId();
-  const fieldId = id ?? generatedId;
-  const descriptionId = description ? `${fieldId}-description` : undefined;
-  const feedbackId = feedback ? `${fieldId}-feedback` : undefined;
-
-  return (
-    <div ref={ref} className={cn("flex flex-col gap-1.5", className)} {...props}>
-      <Label htmlFor={fieldId}>
-        {label}
-        {required && <span className="ml-0.5 text-fg-danger">*</span>}
-      </Label>
-
-      {description && <Muted id={descriptionId}>{description}</Muted>}
-
-      {React.Children.map(children, (child) => {
-        if (React.isValidElement(child)) {
-          return React.cloneElement(child, {
-            id: fieldId,
-            "aria-describedby": cn(descriptionId, feedbackId) || undefined,
-            "aria-invalid": feedback?.intent === "danger" ? true : undefined,
-          } as React.HTMLAttributes<HTMLElement>);
-        }
-        return child;
-      })}
-
-      {feedback && (
-        <Message id={feedbackId} intent={feedback.intent} size="sm">
-          {feedback.message}
-        </Message>
-      )}
-    </div>
-  );
-});
+const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(
+  ({ className, label, description, feedback, required = false, children, id, ...props }, ref) => {
+    const generatedId = React.useId();
+    const fieldId = id ?? generatedId;
+
+    // The label must point at the id the control actually carries: when the
+    // (first element) child brings its own id, that id wins over ours.
+    const childArray = React.Children.toArray(children);
+    const firstElementIndex = childArray.findIndex((child) => React.isValidElement(child));
+    const firstElement = firstElementIndex === -1 ? null : (childArray[firstElementIndex] as React.ReactElement<React.HTMLAttributes<HTMLElement>>);
+    const controlId = firstElement?.props.id ?? fieldId;
+
+    const descriptionId = description ? `${fieldId}-description` : undefined;
+    const feedbackId = feedback ? `${fieldId}-feedback` : undefined;
+    const invalid = feedback?.intent === "danger";
+
+    const contextValue = React.useMemo<FormFieldContextValue>(
+      () => ({
+        id: controlId,
+        describedBy: cn(descriptionId, feedbackId) || undefined,
+        invalid,
+        required,
+      }),
+      [controlId, descriptionId, feedbackId, invalid, required]
+    );
+
+    const wiredChildren = childArray.map((child, index) => {
+      if (index !== firstElementIndex || !React.isValidElement(child)) return child;
+      const childProps = child.props as React.HTMLAttributes<HTMLElement>;
+      return React.cloneElement(child, {
+        id: controlId,
+        // The child's own describedby (a tooltip, an external hint) is kept and
+        // FormField's ids are appended, rather than overwritten.
+        "aria-describedby": cn(childProps["aria-describedby"], descriptionId, feedbackId) || undefined,
+        "aria-invalid": childProps["aria-invalid"] ?? (invalid ? true : undefined),
+        "aria-required": childProps["aria-required"] ?? (required ? true : undefined),
+      } as React.HTMLAttributes<HTMLElement>);
+    });
+
+    return (
+      <div ref={ref} className={cn("flex flex-col gap-1.5", className)} {...props}>
+        <Label htmlFor={controlId}>
+          {label}
+          {required && <span className="ml-0.5 text-fg-danger">*</span>}
+        </Label>
+
+        {description && <Muted id={descriptionId}>{description}</Muted>}
+
+        <FormFieldContext.Provider value={contextValue}>{wiredChildren}</FormFieldContext.Provider>
+
+        {feedback && (
+          <Message id={feedbackId} intent={feedback.intent} size="sm">
+            {feedback.message}
+          </Message>
+        )}
+      </div>
+    );
+  }
+);
 FormField.displayName = "FormField";
 
 export { FormField };

package/src/components/FormField/index.ts

@@ -1,2 +1,2 @@
-export type { FormFieldFeedback, FormFieldProps } from "./FormField";
-export { FormField } from "./FormField";
+export type { FormFieldContextValue, FormFieldFeedback, FormFieldProps } from "./FormField";
+export { FormField, useFormField } from "./FormField";

package/src/components/HoverCard/HoverCard.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { autoUpdate, flip, offset, type Placement, safePolygon, shift, useDismiss, useFloating, useFocus, useHover, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import type * as React from "react";

package/src/components/HoverCard/components/HoverCardContent.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { FloatingPortal } from "@floating-ui/react";
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";

package/src/components/HoverCard/components/HoverCardContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, useContext } from "react";
 
 export type HoverCardContextValue = {

package/src/components/HoverCard/components/HoverCardTrigger.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { Slot } from "../../../internal/Slot";
 import type { WritableRefObject } from "../../../internal/types";

package/src/components/Message/Message.tsx

@@ -10,7 +10,7 @@ import { MessageTitle } from "./components/MessageTitle";
  * Geometry only, plus the three `--message-*` component tokens.
  *
  * Every colour reads a `--message-*` component token whose value is decided by
- * src/theme/recipes/message.css. That file is the mapping from `intent` to a
+ * src/components/Message/message.recipe.css. That file is the mapping from `intent` to a
  * semantic token — the layer that used to be the `intent` entry in `variants`
  * here, compiled into class-name literals and unreachable from outside.
  * `size` stays here: it is pure geometry (padding, gap, font-size), not

package/src/components/Modal/Modal.tsx

@@ -1,7 +1,10 @@
-import { FloatingFocusManager, FloatingOverlay, useDismiss, useFloating, useInteractions, useRole } from "@floating-ui/react";
+"use client";
+
+import { FloatingFocusManager, FloatingOverlay, FloatingPortal, useDismiss, useFloating, useInteractions, useRole } from "@floating-ui/react";
 import { useMergedFloatingRef, usePresence } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
+import { hasOpenEscapeLayer, useEscapeDialog } from "../../internal/escapeLayers";
 import { ModalBody, ModalContext, ModalFooter, ModalHeader } from "./components";
 
 // =============================================================================
@@ -21,9 +24,11 @@ export type ModalProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "sty
   /** Children - use Modal.Header, Modal.Body, Modal.Footer */
   children: ReactNode;
   /**
-   * When true (default), clicking outside closes the modal.
+   * When true (default), clicking outside — and, for a directly-mounted
+   * modal, pressing Escape — closes the modal.
    * When false, the modal can only be closed programmatically.
-   * Note: Escape key is handled by OverlayContext for proper stack ordering.
+   * Note: for modals opened via `useModal()`, Escape is handled by
+   * OverlayContext for proper stack ordering.
    */
   dismissable?: boolean;
   /** When true, shows a close (X) button in the modal header */
@@ -66,6 +71,9 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
   ) => {
     // Prefer explicit prop over context (context is set by useModal's overlay system)
     const contextValue = useContext(ModalContext);
+    // A context means useModal's stack owns this modal — and with it, Escape
+    // ordering. Without one the modal is mounted directly and handles its own.
+    const isStackManaged = contextValue != null;
     // Context provides a parameterless onClose for programmatic modals; adapt to the boolean shape.
     const handleDismiss = useCallback(() => {
       if (onOpenChange) onOpenChange(false);
@@ -84,8 +92,12 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     const { refs, context } = useFloating({
       open: true,
-      onOpenChange: (nextOpen) => {
-        if (!nextOpen) handleClose();
+      onOpenChange: (nextOpen, _event, reason) => {
+        if (nextOpen) return;
+        // A transient overlay (Select dropdown, Popover, picker) open above
+        // this modal consumes the Escape itself — don't also close the modal.
+        if (reason === "escape-key" && hasOpenEscapeLayer()) return;
+        handleClose();
       },
     });
 
@@ -93,8 +105,10 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     const dismiss = useDismiss(context, {
       enabled: dismissable,
-      // OverlayContext handles escape key for proper stack ordering
-      escapeKey: false,
+      // Stack-managed modals leave Escape to OverlayContext, which closes
+      // topmost-first. A directly-mounted modal has no stack above it and
+      // handles its own Escape here.
+      escapeKey: !isStackManaged,
       outsidePress: true,
       outsidePressEvent: "mousedown",
     });
@@ -119,52 +133,63 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     const modalContextValue = useMemo(() => ({ onClose: handleClose, closable, titleId, registerTitle }), [closable, handleClose, titleId, registerTitle]);
 
+    // While mounted (exit animation included), a non-modal Sheet underneath
+    // must leave Escape to this dialog.
+    useEscapeDialog(isMounted);
+
     if (!isMounted) return null;
 
     const isEntering = state === "entering";
     const isExiting = state === "exiting";
 
     return (
-      <FloatingFocusManager context={context} modal>
-        <FloatingOverlay
-          lockScroll
-          className={cn("modal-overlay fixed inset-0 z-modal bg-(--modal-overlay-bg)", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}
-        >
-          <div
-            ref={mergedRef}
-            role="dialog"
-            aria-modal="true"
-            aria-label={ariaLabel}
-            aria-labelledby={labelledBy}
-            aria-describedby={ariaDescribedBy}
-            tabIndex={-1}
-            data-state={state}
-            className={cn(
-              "modal fixed flex flex-col overflow-hidden outline-hidden",
-              "border-(color:--modal-border) rounded-xl border bg-(--modal-bg)",
-              // Size
-              sizeClasses[size],
-              // Cap height so ModalBody scrolls instead of overflowing the viewport
-              "max-h-[95%]",
-              // Mobile: slide up from bottom, full width
-              "max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-b-none",
-              isEntering && "max-sm:animate-slide-up-in",
-              isExiting && "max-sm:animate-slide-up-out",
-              // Desktop: horizontal center + vertical alignment
-              "sm:left-1/2 sm:-translate-x-1/2",
-              align === "center" && "sm:top-1/2 sm:-translate-y-1/2",
-              align === "top" && "sm:top-[15vh]",
-              isEntering && "sm:animate-fade-in",
-              isExiting && "sm:animate-fade-out",
-              className
-            )}
-            style={style}
-            {...getFloatingProps({})}
+      // Self-portalled: `position: fixed` resolves against the nearest
+      // transformed/filtered ancestor, so a modal rendered in place inside a
+      // `transform` container would be positioned (and clipped) by it. Nested
+      // FloatingPortals attach to the parent portal's node, so a stack-managed
+      // modal stays inside the `OverlayProvider`'s custom `modal` root.
+      <FloatingPortal>
+        <FloatingFocusManager context={context} modal>
+          <FloatingOverlay
+            lockScroll
+            className={cn("modal-overlay fixed inset-0 z-modal bg-(--modal-overlay-bg)", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}
           >
-            <ModalContext.Provider value={modalContextValue}>{children}</ModalContext.Provider>
-          </div>
-        </FloatingOverlay>
-      </FloatingFocusManager>
+            <div
+              ref={mergedRef}
+              role="dialog"
+              aria-modal="true"
+              aria-label={ariaLabel}
+              aria-labelledby={labelledBy}
+              aria-describedby={ariaDescribedBy}
+              tabIndex={-1}
+              data-state={state}
+              className={cn(
+                "modal fixed flex flex-col overflow-hidden outline-hidden",
+                "border-(color:--modal-border) rounded-xl border bg-(--modal-bg)",
+                // Size
+                sizeClasses[size],
+                // Cap height so ModalBody scrolls instead of overflowing the viewport
+                "max-h-[95%]",
+                // Mobile: slide up from bottom, full width
+                "max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-b-none",
+                isEntering && "max-sm:animate-slide-up-in",
+                isExiting && "max-sm:animate-slide-up-out",
+                // Desktop: horizontal center + vertical alignment
+                "sm:left-1/2 sm:-translate-x-1/2",
+                align === "center" && "sm:top-1/2 sm:-translate-y-1/2",
+                align === "top" && "sm:top-[15vh]",
+                isEntering && "sm:animate-fade-in",
+                isExiting && "sm:animate-fade-out",
+                className
+              )}
+              style={style}
+              {...getFloatingProps({})}
+            >
+              <ModalContext.Provider value={modalContextValue}>{children}</ModalContext.Provider>
+            </div>
+          </FloatingOverlay>
+        </FloatingFocusManager>
+      </FloatingPortal>
     );
   }
 );
@@ -192,11 +217,12 @@ ModalRoot.displayName = "Modal";
  * Modal is mount-driven — a parent (or `useModal`'s stack) decides whether it
  * renders at all, so there's no `open` prop. `onOpenChange` still exists,
  * firing only with `false` on dismissal, so every overlay in this library
- * shares one open/close shape. Escape is *not* wired inside Modal itself:
- * `OverlayProvider` owns it globally so a stack of modals closes
- * topmost-first. That means Escape only closes a Modal opened through
- * `useModal()` — one a parent mounts directly from its own boolean state
- * won't respond to Escape unless the app wires that separately.
+ * shares one open/close shape. Escape closes the modal: a directly-mounted
+ * Modal handles it itself (via `useDismiss`, so `dismissable={false}` turns
+ * it off along with outside-press), while one opened through `useModal()`
+ * defers to `OverlayProvider`, which closes a stack of modals topmost-first.
+ * Either way, an Escape pressed while a transient overlay (Select dropdown,
+ * Popover, picker) is open above the modal closes only that overlay.
  *
  * Focus moves into the modal on mount and is trapped there
  * (`FloatingFocusManager modal`) until it unmounts, then returns to whatever

package/src/components/Modal/components/ModalContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, type PropsWithChildren, useContext, useMemo } from "react";
 
 /**

package/src/components/Modal/components/ModalHeader.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import { X } from "lucide-react";
 import * as React from "react";