@botiverse/raft-ui 0.84.0 → 0.85.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [0.85.0](https://github.com/botiverse/raft-design/compare/v0.84.0...v0.85.0) (2026-11-10)
+
+### Added
+
+- **Named layers, `z-below` to `z-drag`, and the lint rule `raft-ui/no-raw-z-index`**: every z-index has a name and a place in one order ([Layer order](https://raft-design.botiverse.build/foundations/elevation/#layer-order)). The names are ordinary Tailwind `z-*` utilities from `--z-index-*` theme variables in `styles.css` (`@theme static`, so CSS can always read `var(--z-index-sticky)`): in the page `z-below` -1, `z-base` 0, `z-raised` 1, `z-control` 10, `z-sticky` 20, `z-float` 30, `z-chrome` 35, `z-cover` 40, `z-app` 45, `z-scrollbar` 49; overlays `z-popup` and `z-dialog` 50, `z-dialog-layer` 60, `z-lightbox` 70, `z-toast` 80, `z-drag` 999. They take every variant (`max-md:z-chrome`, `before:z-below`), and `cn` and the recipes merge them with a number an app passes (`z-popup` and `z-40` keep `z-40`). raft-ui's own components use them. The new rule reports a z class with a number or an arbitrary value (`z-10`, `-z-1`, `z-[60]`), a numeric `zIndex` in a style object, a `zIndex={n}` prop and `el.style.zIndex = n`; a number kept on purpose takes a `// raft-ui: z-index <reason>` comment on the line above. `z-index-named.test.ts` holds raft-ui's own code to the same rule, CSS included, with its kept exceptions listed.
+  - Why: slock alone writes 186 z-index values, and the same role has up to five numbers (sticky headers at 2, 10, 15, 20 and 30) while one number has up to seven roles; a share lightbox at 100 hides its own toast, and a badge menu at 1000 sits above the drag lift (#proj-raft-ui:#218, step 1, approved by Artea).
+  - Affects: nothing on the upgrade for an app that extends `recommended.json`: the rule is `"off"` in it for now, so an app that lints with `--max-warnings=0` (slock) stays green. It turns on there as `"error"` once slock has moved to the names (#218 step 2). An app can opt in early with `"raft-ui/no-raw-z-index": "warn"` or `"error"` in its own `rules`. Map each value with the table in Elevation: a local lift is `z-raised` inside an `isolate` root (there is no third local level: order a third part by DOM order); a popup, menu, dialog, lightbox, toast or drag copy takes raft-ui's component and no z-index of its own. Nothing may sit above the toasts (80) or the drag lift (999). slock's InlineBadgeEditor (1000) and SelectShareLightbox (100) are not exceptions: they move onto `Popover` and `z-lightbox` in step 2.
+  - Docs: https://raft-design.botiverse.build/foundations/elevation/#layer-order, https://raft-design.botiverse.build/about/use-raft-ui/#lint-rules
+
+### Changed
+
+- **raft-ui's in-page layers take the scale's values**: where a component's z-index moved to a name with another number, it renders the same inside the component, but its number against an app's own layers changes. Overlays keep theirs (50, 60, 70, 80, 999).
+  - Raised parts 10 → 1 (`z-raised`): Button's and Toast's label and loading indicator, Avatar's badge, InboxItem's lead, badge, selection, text, trail and corner (its trigger is `z-base`, 0), ChoiceList's control column, Comment's cover and active comment, CodeBlock's actions, ComposerAttachment's veils, FilePreview's corner badge, MessageImageGallery's "+N" veil, MessageItem's trailing meta, MobileNav's icons, Select's scroll arrows, Tabs' tab content and drop placeholder, Tooltip's kbd, Lightbox's arrows, info dock and counter, ConversationPanelEmptyState's illustration. 20 → 1: CodeBlock's corners, ComposerAttachment's progress bar (over the veil by DOM order), ComposerDropOverlay's second icon (and its first, 10 → 1), Lightbox's close, a dragged TaskDraggable. MessageList's end fade 5 → 1.
+  - Up: MessageList's jump controls and SelectionToolbar 10 → 30 (`z-float`), the pull-to-refresh indicator 10 → 20 (`z-sticky`), PanelHeader's sticky phone header 30 → 35 (`z-chrome`), ThreadPanel's header 20 → 35 (inside the panel's `isolate`), AppShellOverlaySlot 20 → 40 (`z-cover`).
+  - Down: MessageItem's hover toolbar 20 → 10 and ComposerAttachment's remove button 20 → 10 (`z-control`), the composer attachment row's arrows 30 → 10 (outside the row's ScrollArea, so still over it). The sidebar header mask -10 → -1 (`z-below`).
+  - Isolation: a tab is now `isolate` instead of `z-10`, and a dragged tab is lifted by `var(--z-index-raised)` instead of 20, all inside the tab list's `isolate`. TaskDraggable is `isolate`, so a card's own parts rank only inside the card, and a dragged card at `z-raised` is above every other card.
+  - Why: the scale has one number per role; the old numbers made the same role differ between components and forced slock to workarounds (a day heading at `z-15`, an `isolate` around the artifacts dashboard, `max-md:z-40` beside the phone header) (#proj-raft-ui:#218).
+  - Affects: an app layer that sat between the old and the new number of a raft-ui layer it overlaps. In slock, move these in the same upgrade: a cover at `z-30` beside a PanelHeader (MainLayout, ProfilePanel, ChannelSideArea, LegacyTaskPanel, TaskConversationDialog, `index.css`) to `z-cover`, or the header, now 35, is drawn over it; the typing line (`z-6`) to `z-float`, so it stays over the end fade and beside the jump pills; a hit target at `z-10` in a message (MessageItem) to `z-raised`, so the hover toolbar, now 10, stays above it; ThreadsInbox's day heading (`z-15`) and "new" pill (`z-20`) to `z-sticky` and `z-float`, which InboxItem's parts at 1 now allow.
+  - Docs: https://raft-design.botiverse.build/foundations/elevation/#in-page-layers
+
 ## [0.84.0](https://github.com/botiverse/raft-design/compare/v0.83.0...v0.84.0) (2026-11-10)
 
 ### Added

package/dist/cn.d.mts

@@ -1,5 +1,7 @@
 import { ClassValue } from "cnfast";
 //#region src/lib/cn.d.ts
+/** The `--z-index-*` names of styles.css, in order (design/foundations/elevation.md#layer-order). */
+export declare const Z_INDEX_NAMES: string[];
 export declare function cn(...inputs: ClassValue[]): string;
 //#endregion
 export type { ClassValue };

package/dist/cn.mjs

@@ -1,6 +1,25 @@
 import { clsx } from "cnfast";
 import { extendTailwindMerge } from "tailwind-merge";
 //#region src/lib/cn.ts
+/** The `--z-index-*` names of styles.css, in order (design/foundations/elevation.md#layer-order). */
+const Z_INDEX_NAMES = [
+	"below",
+	"base",
+	"raised",
+	"control",
+	"sticky",
+	"float",
+	"chrome",
+	"cover",
+	"app",
+	"scrollbar",
+	"popup",
+	"dialog",
+	"dialog-layer",
+	"lightbox",
+	"toast",
+	"drag"
+];
 const twMerge = extendTailwindMerge({ extend: {
 	theme: { spacing: [
 		"control",
@@ -59,6 +78,7 @@ const twMerge = extendTailwindMerge({ extend: {
 			"x"
 		] }],
 		opacity: [{ opacity: ["dimmed"] }],
+		z: [{ z: Z_INDEX_NAMES }],
 		"bg-image": [{ overlay: [
 			"subtle",
 			"medium",
@@ -71,4 +91,4 @@ function cn(...inputs) {
 	return twMerge(clsx(inputs));
 }
 //#endregion
-export { cn };
+export { Z_INDEX_NAMES, cn };

package/dist/components/alert-dialog/alert-dialog.mjs

@@ -13,9 +13,9 @@ import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/alert-dialog/alert-dialog.tsx
 const alertDialog = tv({
 	slots: {
-		overlay: ["fixed inset-0 z-50 bg-layer-backdrop"],
+		overlay: ["fixed inset-0 z-dialog bg-layer-backdrop"],
 		content: [
-			"fixed top-1/2 left-1/2 z-50 grid w-[calc(100%-2rem)] -translate-1/2 outline-none",
+			"fixed top-1/2 left-1/2 z-dialog grid w-[calc(100%-2rem)] -translate-1/2 outline-none",
 			decisionWidth,
 			"overflow-clip rounded-dialog bg-layer-popover text-foreground",
 			"shadow-float ring-1 ring-line-seam"

package/dist/components/app-shell/app-shell.mjs

@@ -19,7 +19,7 @@ const appShell = tv({
 		sidebarSlot: ["hidden min-h-0 shrink-0 flex-col md:flex"],
 		mainSlot: ["flex min-h-0 min-w-0 flex-1 flex-col"],
 		panelSlot: ["hidden min-h-0 min-w-0 flex-col md:flex"],
-		overlaySlot: ["absolute inset-0 z-20 flex min-h-0 min-w-0"]
+		overlaySlot: ["absolute inset-0 z-cover flex min-h-0 min-w-0"]
 	},
 	variants: { overlay: {
 		false: {},
@@ -135,7 +135,7 @@ function AppShellSidebarSlot({ className, id: idProp, render, ...props }) {
 		id,
 		inert: collapsed ? true : void 0,
 		className: sidebarSlot({ className: cn(className, sidebar?.collapsible && [
-			"group-data-[state=expanded]/app-shell:relative group-data-[state=expanded]/app-shell:z-1",
+			"group-data-[state=expanded]/app-shell:relative group-data-[state=expanded]/app-shell:z-raised",
 			"group-data-[state=collapsed]/app-shell:pointer-events-none",
 			"group-data-[state=collapsed]/app-shell:opacity-0"
 		]) })

package/dist/components/avatar/avatar.mjs

@@ -37,7 +37,7 @@ const avatar = tv({
 			"[[data-size='3xs']>&]:[&>svg]:size-2"
 		],
 		badge: [
-			"absolute z-10 select-none",
+			"absolute z-raised select-none",
 			"size-[11px] -right-1 -bottom-1 rounded-[2px]",
 			"outline-2 outline-solid outline-layer-canvas",
 			"group-data-[size=xl]/avatar:size-5 group-data-[size=xl]/avatar:-right-2 group-data-[size=xl]/avatar:-bottom-2",

package/dist/components/button/button-split.mjs

@@ -10,11 +10,11 @@ const buttonSplit = tv({ base: [
 	"data-sticker-edge:ring-[1.5px]",
 	"data-[size=lg]:rounded-(--control-radius)"
 ] });
-const buttonSplitMain = tv({ base: ["rounded-e-none border-e-0", "ring-0 focus-visible:z-1"] });
+const buttonSplitMain = tv({ base: ["rounded-e-none border-e-0", "ring-0 focus-visible:z-raised"] });
 const buttonSplitMenu = tv({
 	base: [
 		"min-w-0 rounded-s-none px-0",
-		"ring-0 focus-visible:z-1",
+		"ring-0 focus-visible:z-raised",
 		"after:inset-s-0"
 	],
 	variants: {

package/dist/components/button/button.mjs

@@ -38,8 +38,8 @@ const buttonVariants = tv({
 			"disabled:border-line-hairline disabled:bg-fill-muted disabled:bg-none disabled:text-foreground-disabled disabled:ring-0",
 			"aria-disabled:border-line-hairline aria-disabled:bg-fill-muted aria-disabled:bg-none aria-disabled:text-foreground-disabled aria-disabled:ring-0"
 		],
-		content: "relative z-10 inline-flex min-w-0 max-w-full items-center justify-center gap-[inherit] data-[loading=true]:invisible",
-		loadingIndicator: "pointer-events-none absolute inset-0 z-10 flex items-center justify-center"
+		content: "relative z-raised inline-flex min-w-0 max-w-full items-center justify-center gap-[inherit] data-[loading=true]:invisible",
+		loadingIndicator: "pointer-events-none absolute inset-0 z-raised flex items-center justify-center"
 	},
 	variants: {
 		variant: {

package/dist/components/choice-list/choice-list.recipe.mjs

@@ -24,7 +24,7 @@ const choiceList = tv({
 		description: ["block truncate font-sans text-footnote font-normal text-foreground-muted", "in-data-disabled:text-foreground-disabled"],
 		meta: ["block truncate font-sans text-footnote font-normal text-foreground-muted", "in-data-disabled:text-foreground-disabled"],
 		action: [
-			"relative z-10 col-start-2 flex h-lh items-center self-start pr-1",
+			"relative z-raised col-start-2 flex h-lh items-center self-start pr-1",
 			"mt-option-inset pointer-coarse:mt-[calc((--spacing(11)-1lh)/2)]",
 			"font-sans text-subhead"
 		],

package/dist/components/code-block/code-block.recipe.mjs

@@ -16,11 +16,11 @@ const codeBlock = tv({ slots: {
 	actions: [
 		"ml-auto flex items-center gap-1",
 		"[[data-slot=code-block-body]>&]:col-start-2 [[data-slot=code-block-body]>&]:row-start-1",
-		"[[data-slot=code-block-body]>&]:z-10 [[data-slot=code-block-body]>&]:ml-3",
+		"[[data-slot=code-block-body]>&]:z-raised [[data-slot=code-block-body]>&]:ml-3",
 		"[[data-slot=code-block-body]>&]:my-[calc(var(--control-embedded-inset)-0.5rem-1px)] [[data-slot=code-block-body]>&]:mr-[calc(var(--control-embedded-inset)-0.75rem-1px)]"
 	],
 	corner: [
-		"pointer-events-none absolute z-20 size-1",
+		"pointer-events-none absolute z-raised size-1",
 		"data-[y=top]:top-0 data-[y=bottom]:bottom-0",
 		"data-[x=left]:left-0 data-[x=right]:right-0",
 		"hidden"

package/dist/components/combobox/combobox.mjs

@@ -60,7 +60,7 @@ const combobox = tv({
 			"first:rounded-t-container has-focus-visible:keyboard:inset-ring-2 has-focus-visible:keyboard:inset-ring-foreground"
 		],
 		input: ["w-full outline-none"],
-		positioner: ["isolate z-50 outline-none"],
+		positioner: ["isolate z-popup outline-none"],
 		content: [
 			"h-auto max-h-(--available-height) min-w-[220px] overflow-hidden",
 			"max-w-[min(var(--available-width),max(var(--anchor-width),24rem))]",

package/dist/components/combobox-select/combobox-select.css

@@ -161,7 +161,7 @@
   box-shadow: inset 0 0 0 2px var(--foreground);
 }
 .r-combobox-select__positioner {
-  z-index: 50;
+  z-index: var(--z-index-popup);
   isolation: isolate;
   outline: 0;
 }

package/dist/components/comment/comment.recipe.mjs

@@ -7,7 +7,7 @@ const comment = tv({
 			"absolute inset-x-0 top-0",
 			"data-animate:transition-transform data-animate:duration-150 data-animate:ease-out",
 			"motion-reduce:transition-none",
-			"data-active:z-10"
+			"data-active:z-raised"
 		],
 		card: [
 			"relative flex min-w-0 flex-col gap-2",
@@ -16,7 +16,7 @@ const comment = tv({
 			"data-active:border-[1.5px] data-active:border-line-strong data-active:p-[11.5px] data-active:shadow-float"
 		],
 		cardTrigger: [
-			"absolute -inset-px z-10 cursor-pointer",
+			"absolute -inset-px z-raised cursor-pointer",
 			"rounded-container border-0 bg-transparent p-0",
 			"hover:bg-fill-subtle active:bg-fill-medium",
 			"outline-none focus-visible:shadow-focus"

package/dist/components/composer/composer-attachment.recipe.mjs

@@ -20,7 +20,7 @@ const composerAttachment = tv({
 			"pe-1.5"
 		],
 		attachmentsNav: [
-			"absolute top-1/2 z-30 -translate-y-1/2",
+			"absolute top-1/2 z-control -translate-y-1/2",
 			"size-8 rounded-chip shadow-none",
 			"[&_svg:not([class*='size-'])]:size-4.5"
 		],
@@ -42,26 +42,26 @@ const composerAttachment = tv({
 		attachmentTitle: ["block truncate", "font-sans text-footnote font-semibold text-foreground"],
 		attachmentMeta: ["block w-full truncate", "text-left font-mono text-mono-meta text-foreground-hint"],
 		attachmentUploadingOverlay: [
-			"absolute inset-0 z-10 flex flex-col items-center justify-center px-1",
+			"absolute inset-0 z-raised flex flex-col items-center justify-center px-1",
 			"text-center",
 			"rounded-control bg-layer-veil",
 			"font-mono text-mono-meta font-bold text-foreground"
 		],
 		attachmentUploadProgressBar: [
-			"absolute z-20 h-1 overflow-hidden",
+			"absolute z-raised h-1 overflow-hidden",
 			"right-1.5 bottom-1.5 left-1.5 w-auto rounded-[2px]",
 			"bg-layer-card"
 		],
 		attachmentUploadProgressBarIndicator: ["block h-full", "rounded-[inherit] bg-info"],
 		attachmentFailedOverlay: [
-			"absolute inset-0 z-10 flex flex-col items-center justify-center px-1",
+			"absolute inset-0 z-raised flex flex-col items-center justify-center px-1",
 			"[border-width:var(--ca-overlay-border,2px)]",
 			"text-center",
 			"rounded-control border-danger-strong bg-layer-veil",
 			"font-sans text-caption font-semibold text-danger-strong"
 		],
 		attachmentRemove: [
-			"absolute z-20 flex items-center justify-center",
+			"absolute z-control flex items-center justify-center",
 			"transition-opacity group-hover/composer-attachment:opacity-100",
 			"[@media(hover:none)]:opacity-100",
 			"[&_svg]:shrink-0",

package/dist/components/composer/composer-drop-overlay.mjs

@@ -42,11 +42,11 @@ function ComposerDropOverlayPrompt({ children, ...props }) {
 					children: /* @__PURE__ */ jsx(FileText, { className: "text-foreground-muted" })
 				}),
 				/* @__PURE__ */ jsx("span", {
-					className: dropOverlayIcon({ className: "absolute z-10" }),
+					className: dropOverlayIcon({ className: "absolute z-raised" }),
 					children: /* @__PURE__ */ jsx(Upload, { className: "text-foreground-muted" })
 				}),
 				/* @__PURE__ */ jsx("span", {
-					className: dropOverlayIcon({ className: "absolute z-20 translate-x-7 translate-y-1 rotate-12" }),
+					className: dropOverlayIcon({ className: "absolute z-raised translate-x-7 translate-y-1 rotate-12" }),
 					children: /* @__PURE__ */ jsx(Image, { className: "text-foreground-muted" })
 				})
 			]

package/dist/components/composer/composer-drop-overlay.recipe.mjs

@@ -2,7 +2,7 @@ import { tv } from "../../lib/tv.mjs";
 //#region src/components/composer/composer-drop-overlay.recipe.ts
 const composerDropOverlay = tv({ slots: {
 	dropOverlay: [
-		"absolute inset-0 z-30 flex items-center justify-center",
+		"absolute inset-0 z-float flex items-center justify-center",
 		"rounded-container border-[1.5px] border-dashed border-line-seam",
 		"bg-layer-card bg-[linear-gradient(var(--info-soft),var(--info-soft))]"
 	],

package/dist/components/composer/sortable-composer-attachments.mjs

@@ -225,7 +225,7 @@ function SortableComposerAttachment({ id, label, children }) {
 	const style = {
 		transform: isDragging ? void 0 : CSS.Translate.toString(transform),
 		transition: isDragging ? void 0 : transition,
-		zIndex: isDragging ? 0 : void 0
+		zIndex: isDragging ? "var(--z-index-base)" : void 0
 	};
 	const place = isDragging && !home;
 	return /* @__PURE__ */ jsxs("div", {

package/dist/components/context-menu/context-menu.mjs

@@ -7,7 +7,7 @@ import { ContextMenu } from "@base-ui/react";
 //#region src/components/context-menu/context-menu.tsx
 const contextMenu = tv({ slots: {
 	trigger: ["select-none"],
-	positioner: ["isolate z-50 outline-none"],
+	positioner: ["isolate z-popup outline-none"],
 	content: [
 		"flex flex-col max-h-(--available-height) overflow-hidden",
 		"outline-none",

package/dist/components/conversation-panel/conversation-panel-empty-state.mjs

@@ -12,7 +12,7 @@ const conversationPanelEmptyState = tv({ slots: {
 	brand: ["shrink-0", "mb-1 inline-flex rounded-none p-0 text-foreground-hint"],
 	brandMark: [
 		"relative flex items-center justify-center",
-		"[&>svg]:relative [&>svg]:z-10",
+		"[&>svg]:relative [&>svg]:z-raised",
 		"size-9 overflow-visible rounded-none",
 		"[&>svg]:size-9 [&>svg]:stroke-2"
 	]

package/dist/components/dialog/dialog.mjs

@@ -22,9 +22,9 @@ import { createPortal } from "react-dom";
 //#region src/components/dialog/dialog.tsx
 const dialog = tv({
 	slots: {
-		overlay: ["fixed inset-0 z-50 bg-layer-backdrop"],
+		overlay: ["fixed inset-0 z-dialog bg-layer-backdrop"],
 		content: [
-			"fixed top-1/2 left-1/2 z-50 flex w-[calc(100%-2rem)] -translate-1/2 flex-col",
+			"fixed top-1/2 left-1/2 z-dialog flex w-[calc(100%-2rem)] -translate-1/2 flex-col",
 			"max-h-[calc(100dvh-2rem)] outline-none",
 			"overflow-clip rounded-dialog bg-layer-popover text-foreground",
 			"shadow-float ring-1 ring-line-seam"
@@ -83,8 +83,8 @@ const dialog = tv({
 				content: []
 			},
 			1: {
-				overlay: ["z-60"],
-				content: ["z-60"]
+				overlay: ["z-dialog-layer"],
+				content: ["z-dialog-layer"]
 			}
 		},
 		nested: {

package/dist/components/drag/drag-lift.d.mts

@@ -49,8 +49,9 @@ export declare function keepGrabInside(proxyWidth: number, inset?: number): Modi
  */
 export declare function cancelDrag(win?: Window): void;
 /**
- * Above every raft-ui layer (popovers 50, a stacked dialog 60, toasts and the
- * lightbox 70) and an app's own top layers, among the layers rendered in
+ * `--z-index-drag` (`z-drag`) as a number: above every raft-ui layer (popups
+ * and dialogs 50, a `layer={1}` dialog 60, the lightbox 70, toasts 80) and an
+ * app's own top layers, among the layers rendered in
  * `document.body`, where the copy goes by default. dnd-kit's own default.
  */
 export declare const DRAG_LIFT_Z_INDEX = 999;

package/dist/components/drag/drag-lift.mjs

@@ -109,8 +109,9 @@ function cancelDrag(win = window) {
 	win.dispatchEvent(new Event("resize"));
 }
 /**
-* Above every raft-ui layer (popovers 50, a stacked dialog 60, toasts and the
-* lightbox 70) and an app's own top layers, among the layers rendered in
+* `--z-index-drag` (`z-drag`) as a number: above every raft-ui layer (popups
+* and dialogs 50, a `layer={1}` dialog 60, the lightbox 70, toasts 80) and an
+* app's own top layers, among the layers rendered in
 * `document.body`, where the copy goes by default. dnd-kit's own default.
 */
 const DRAG_LIFT_Z_INDEX = 999;

package/dist/components/drag/drag.recipe.mjs

@@ -18,7 +18,7 @@ const drag = tv({
 			"border-[1.5px] border-dashed border-line-strong bg-fill-subtle"
 		],
 		hint: [
-			"pointer-events-none fixed top-0 left-0 z-999 max-w-80",
+			"pointer-events-none fixed top-0 left-0 z-drag max-w-80",
 			"rounded-chip px-2 py-1",
 			"font-sans text-caption",
 			"bg-layer-hud text-foreground-on-hud shadow-float ring-1 ring-line-seam"

package/dist/components/drawer/drawer.recipe.mjs

@@ -66,13 +66,13 @@ const drawer = tv({
 	extend: drawerMotion,
 	slots: {
 		overlay: [
-			"fixed inset-0 z-50 min-h-dvh select-none",
+			"fixed inset-0 z-dialog min-h-dvh select-none",
 			"supports-[-webkit-touch-callout:none]:absolute",
 			"bg-layer-backdrop"
 		],
-		viewport: ["pointer-events-none fixed inset-0 z-50 select-none"],
+		viewport: ["pointer-events-none fixed inset-0 z-dialog select-none"],
 		popup: [
-			"group/drawer-popup pointer-events-auto fixed z-50 flex h-(--drawer-content-height) flex-col outline-none",
+			"group/drawer-popup pointer-events-auto fixed z-dialog flex h-(--drawer-content-height) flex-col outline-none",
 			"[--drawer-inset:12px] [--drawer-content-height:var(--drawer-height,auto)]",
 			"data-nested-drawer-open:overflow-hidden",
 			"bg-layer-popover text-foreground",
@@ -80,7 +80,7 @@ const drawer = tv({
 		],
 		content: ["flex min-h-0 flex-1 flex-col rounded-[inherit] select-text", "group-data-swiping/drawer-popup:select-none"],
 		swipeHandle: [
-			"relative z-10 shrink-0 cursor-grab select-none active:cursor-grabbing",
+			"relative z-control shrink-0 cursor-grab select-none active:cursor-grabbing",
 			"before:absolute before:content-['']",
 			"before:rounded-full before:bg-line-seam"
 		],

package/dist/components/dropdown-menu/dropdown-menu.mjs

@@ -9,7 +9,7 @@ import { Menu } from "@base-ui/react/menu";
 //#region src/components/dropdown-menu/dropdown-menu.tsx
 const dropdownMenu = tv({ slots: {
 	trigger: ["select-none"],
-	positioner: ["isolate z-50 outline-none"],
+	positioner: ["isolate z-popup outline-none"],
 	content: [
 		"max-h-(--available-height) overflow-hidden",
 		"outline-none",

package/dist/components/file-preview/file-preview.recipe.mjs

@@ -30,7 +30,7 @@ const filePreview = tv({
 		media: ["relative h-10 w-8 overflow-hidden rounded-md ring-1", "bg-fill-muted shadow-none ring-line-hairline"]
 	},
 	variants: { placement: {
-		corner: { badge: "absolute -right-1.5 bottom-0.5 z-10" },
+		corner: { badge: "absolute -right-1.5 bottom-0.5 z-raised" },
 		inline: { badge: "inline-flex h-3.5 w-7 shrink-0 items-center justify-center px-0 py-0" }
 	} },
 	defaultVariants: { placement: "corner" }

package/dist/components/inbox-item/inbox-item.recipe.mjs

@@ -18,17 +18,17 @@ const inboxItem = tv({
 			"has-[[data-slot=inbox-item-open]:focus-visible]:keyboard:before:inset-ring-2 has-[[data-slot=inbox-item-open]:focus-visible]:keyboard:before:inset-ring-foreground",
 			"not-data-[density=compact]:has-data-[slot=inbox-item-trailing]:[--inbox-item-content-display:grid] not-data-[density=compact]:has-data-[slot=inbox-item-trailing]:[--inbox-item-content-end:-1]"
 		],
-		itemTrigger: ["absolute inset-0 z-0 outline-none"],
-		itemLeading: ["pointer-events-none relative z-10 flex size-9 shrink-0 items-center justify-center"],
+		itemTrigger: ["absolute inset-0 z-base outline-none"],
+		itemLeading: ["pointer-events-none relative z-raised flex size-9 shrink-0 items-center justify-center"],
 		itemLeadingBadge: [
-			"absolute -right-0.5 -bottom-0.5 z-10 inline-flex size-3.5 items-center justify-center",
+			"absolute -right-0.5 -bottom-0.5 z-raised inline-flex size-3.5 items-center justify-center",
 			"rounded-[3px] border border-sticker-ink outline-2 outline-layer-canvas outline-solid",
 			"bg-layer-canvas bg-[linear-gradient(var(--info-soft),var(--info-soft))] text-foreground",
 			"[&_svg]:size-2.5 [&_svg]:shrink-0"
 		],
-		itemSelection: ["relative z-10 flex size-5 shrink-0 items-center justify-center"],
+		itemSelection: ["relative z-raised flex size-5 shrink-0 items-center justify-center"],
 		itemContent: [
-			"pointer-events-none relative z-10 min-w-0 flex-1 text-left",
+			"pointer-events-none relative z-raised min-w-0 flex-1 text-left",
 			"-col-start-3 col-end-(--inbox-item-content-end) row-start-1",
 			"[display:var(--inbox-item-content-display,block)] grid-cols-subgrid"
 		],
@@ -57,7 +57,7 @@ const inboxItem = tv({
 			"[&>svg]:text-foreground-hint"
 		],
 		itemTrailing: [
-			"pointer-events-none relative z-10 col-[-2/-1] row-start-1",
+			"pointer-events-none relative z-raised col-[-2/-1] row-start-1",
 			"flex shrink-0",
 			"mt-0 flex-col items-end gap-2 pt-px",
 			"max-md:flex-col max-md:items-end max-md:gap-2",
@@ -138,7 +138,7 @@ const inboxItem = tv({
 		} },
 		reveal: { hover: {
 			itemActions: [
-				"absolute top-0 right-0 z-10",
+				"absolute top-0 right-0 z-raised",
 				"pointer-events-none opacity-0 transition-opacity",
 				"group-hover/inbox-item:pointer-events-auto group-hover/inbox-item:opacity-100",
 				"group-focus-within/inbox-item:pointer-events-auto group-focus-within/inbox-item:opacity-100",

package/dist/components/lightbox/lightbox.d.mts

@@ -39,10 +39,10 @@ export type LightboxTriggerProps = Dialog.Trigger.Props;
 export declare function LightboxTrigger(props: LightboxTriggerProps): import("react").JSX.Element;
 export type LightboxPortalProps = StyledProps<Dialog.Portal.Props>;
 /**
- * The lightbox's own stacking context, at `z-70` above the page's dialogs
+ * The lightbox's own stacking context, at `z-lightbox` (70) above the page's dialogs
  * and popups: the scrim, the content, and every Base UI popup opened from
  * inside, which Base UI portals into this element by default, in DOM order.
- * A popup's own `z-50` then counts inside the lightbox, so it is drawn above
+ * A popup's own `z-popup` then counts inside the lightbox, so it is drawn above
  * the content instead of under the scrim, and a press on it is a press inside
  * the lightbox.
  */

package/dist/components/lightbox/lightbox.mjs

@@ -15,11 +15,11 @@ import { useHotkey } from "@tanstack/react-hotkeys";
 //#region src/components/lightbox/lightbox.tsx
 const lightbox = tv({
 	slots: {
-		portal: ["relative isolate z-70"],
+		portal: ["relative isolate z-lightbox"],
 		backdrop: ["fixed inset-0 bg-layer-backdrop data-closed:hidden"],
 		content: [
 			"pointer-events-none fixed inset-0 flex flex-col data-closed:hidden",
-			"*:data-lightbox-close:pointer-events-auto *:data-lightbox-close:absolute *:data-lightbox-close:z-20",
+			"*:data-lightbox-close:pointer-events-auto *:data-lightbox-close:absolute *:data-lightbox-close:z-raised",
 			"*:data-lightbox-close:top-[calc(16px+env(safe-area-inset-top,0px))] *:data-lightbox-close:right-[calc(16px+env(safe-area-inset-right,0px))]"
 		],
 		header: [
@@ -61,7 +61,7 @@ const lightbox = tv({
 		stage: ["pointer-events-none relative flex min-h-0 flex-1 items-center justify-center overflow-hidden"],
 		media: ["pointer-events-auto max-h-[80vh] max-w-[86vw] border-0 bg-transparent shadow-none"],
 		navigationButton: [
-			"pointer-events-auto absolute z-10 inline-flex items-center justify-center",
+			"pointer-events-auto absolute z-raised inline-flex items-center justify-center",
 			"transition-[background-color,color,opacity,box-shadow,transform] duration-150",
 			"outline-[1px] outline-offset-2 outline-transparent",
 			"data-[disabled=true]:cursor-default",
@@ -71,7 +71,7 @@ const lightbox = tv({
 			"focus-visible:outline-transparent focus-visible:shadow-focus",
 			"[&_svg]:size-5.5"
 		],
-		infoDock: ["pointer-events-none absolute right-6 bottom-20 left-6 z-10 flex justify-center"],
+		infoDock: ["pointer-events-none absolute right-6 bottom-20 left-6 z-raised flex justify-center"],
 		infoBar: [
 			"pointer-events-auto flex items-center",
 			"w-[clamp(144px,20vw,224px)] max-w-[calc(100vw-48px)] min-w-36",
@@ -87,7 +87,7 @@ const lightbox = tv({
 			"*:data-[slot=button]:after:inset-x-[-3px] *:data-[slot=button]:first:after:left-[-9.5px] *:data-[slot=button]:last:after:right-[-9.5px]",
 			"pointer-coarse:*:data-[slot=button]:after:inset-y-[-9.5px]"
 		],
-		thumbnailStrip: ["pointer-events-none absolute right-0 bottom-4 left-0 z-10", "flex items-center justify-center gap-1.5"],
+		thumbnailStrip: ["pointer-events-none absolute right-0 bottom-4 left-0 z-raised", "flex items-center justify-center gap-1.5"],
 		thumbnail: [
 			"group/lightbox-thumb pointer-events-auto relative size-12 overflow-hidden",
 			"transition-[border-color,opacity,box-shadow] duration-150",
@@ -155,10 +155,10 @@ function LightboxTrigger(props) {
 	});
 }
 /**
-* The lightbox's own stacking context, at `z-70` above the page's dialogs
+* The lightbox's own stacking context, at `z-lightbox` (70) above the page's dialogs
 * and popups: the scrim, the content, and every Base UI popup opened from
 * inside, which Base UI portals into this element by default, in DOM order.
-* A popup's own `z-50` then counts inside the lightbox, so it is drawn above
+* A popup's own `z-popup` then counts inside the lightbox, so it is drawn above
 * the content instead of under the scrim, and a press on it is a press inside
 * the lightbox.
 */

package/dist/components/message-attachment/message-image-gallery.recipe.mjs

@@ -13,7 +13,7 @@ const messageImageGallery = tv({
 			"outline-none focus-visible:keyboard:inset-ring-2 focus-visible:keyboard:inset-ring-foreground"
 		],
 		action: [
-			"absolute z-10 hidden items-center justify-center",
+			"absolute z-raised hidden items-center justify-center",
 			"focus:flex",
 			"group-hover/img:flex",
 			"right-[calc(var(--control-embedded-inset)-1px)] bottom-[calc(var(--control-embedded-inset)-1px)] size-8 rounded-chip border-[1.5px] border-line-strong",

package/dist/components/message-item/message-item.recipe.mjs

@@ -81,7 +81,7 @@ const messageItem = tv({
 			"dark:shadow-[0_0_0_3px_var(--mi-row-fill,transparent),0_0_0_3px_var(--layer-canvas)]"
 		],
 		edited: ["ms-1 whitespace-nowrap", "text-caption text-foreground-hint"],
-		trailing: ["absolute end-0 bottom-0 z-10 flex h-lh items-center", "select-none! **:select-none!"],
+		trailing: ["absolute end-0 bottom-0 z-raised flex h-lh items-center", "select-none! **:select-none!"],
 		body: [
 			"wrap-break-word select-text",
 			"**:select-text",
@@ -93,7 +93,7 @@ const messageItem = tv({
 		attachments: ["stack-y-2", "mt-2"],
 		footer: ["mt-1.5 flex flex-wrap items-center gap-1.5"],
 		toolbar: [
-			"absolute z-20 flex items-center",
+			"absolute z-control flex items-center",
 			"opacity-(--mi-toolbar-opacity,0)",
 			"[pointer-events:var(--mi-toolbar-pe,none)]",
 			"top-[-18px] md:pointer-fine:top-[calc(-1*(var(--control-height)+8px)/2)] right-3 gap-1 overflow-visible rounded-container p-1",

package/dist/components/message-list/message-list.recipe.mjs

@@ -14,7 +14,7 @@ const messageList = tv({
 		dateDividerRule: ["flex-1", "min-w-3 border-t border-line-hairline"],
 		dateDividerChip: ["inline-flex items-center", "font-mono text-mono-meta whitespace-nowrap text-foreground-hint"],
 		endFade: [
-			"pointer-events-none absolute inset-x-0 bottom-0 z-5",
+			"pointer-events-none absolute inset-x-0 bottom-0 z-raised",
 			"h-timeline-section",
 			"bg-linear-to-t from-layer-canvas to-transparent"
 		],
@@ -35,7 +35,7 @@ const messageList = tv({
 });
 const messageListJump = tv({
 	slots: {
-		controls: ["absolute inset-x-0 z-10 mx-auto", "flex w-fit max-w-[calc(100%-1.5rem)] flex-wrap items-center justify-center gap-x-2 gap-y-3"],
+		controls: ["absolute inset-x-0 z-float mx-auto", "flex w-fit max-w-[calc(100%-1.5rem)] flex-wrap items-center justify-center gap-x-2 gap-y-3"],
 		group: ["inline-flex shrink-0 items-stretch", "*:data-[slot=message-list-jump-pill]:rounded-e-none"],
 		dismiss: [
 			"rounded-s-none border-s-0",

package/dist/components/mobile-nav/mobile-nav.mjs

@@ -17,8 +17,8 @@ const mobileNav = tv({ slots: {
 		"[&_svg]:shrink-0",
 		"isolate min-w-0 flex-col justify-start gap-[7px] border-0 px-0 pt-1 pb-0",
 		"font-sans text-[10px]/3 font-semibold text-foreground-hint",
-		"*:relative *:z-10 [&_svg]:size-[22px] [&_svg]:stroke-2",
-		"before:pointer-events-none before:absolute before:top-0 before:left-1/2 before:z-0 before:-translate-x-1/2",
+		"*:relative *:z-raised [&_svg]:size-[22px] [&_svg]:stroke-2",
+		"before:pointer-events-none before:absolute before:top-0 before:left-1/2 before:z-base before:-translate-x-1/2",
 		"before:h-[30px] before:w-14 before:rounded-control before:border-[1.5px] before:border-transparent before:content-['']",
 		"active:before:bg-fill-medium",
 		"data-[selected=true]:font-bold data-[selected=true]:text-foreground",

package/dist/components/notification-center/notification-center.mjs

@@ -162,7 +162,7 @@ function NotificationCenterPopup({ viewport = "desktop", size = "md", className,
 			side,
 			sideOffset,
 			sticky,
-			className: "isolate z-50 outline-none",
+			className: "isolate z-popup outline-none",
 			children: /* @__PURE__ */ jsx(Popover.Popup, {
 				"aria-label": props["aria-label"] ?? "Notification center",
 				"data-slot": "notification-center-popup",

package/dist/components/panel/panel-header.recipe.mjs

@@ -61,7 +61,7 @@ const panelHeader = tv({
 			"flex h-(--shell-header-height,var(--header-height)) shrink-0 items-center gap-3 max-md:gap-2",
 			panelHeadEdges,
 			"border-b border-line-seam bg-layer-canvas text-foreground",
-			"max-md:sticky max-md:top-0 max-md:z-30"
+			"max-md:sticky max-md:top-0 max-md:z-chrome"
 		]
 	}, {
 		slots: ["sectionHeader"],

package/dist/components/panel/panel-split-action.recipe.mjs

@@ -21,7 +21,7 @@ const panelSplitAction = tv({ base: [
 const splitActionMainParts = [
 	"pointer-events-auto rounded-e-none",
 	"after:end-0",
-	"focus-visible:z-1 aria-pressed:z-1 data-pressed:z-1",
+	"focus-visible:z-raised aria-pressed:z-raised data-pressed:z-raised",
 	"bg-(--split-action-main-tint,transparent)",
 	"group-hover/split-action:bg-fill-subtle",
 	"hover:bg-fill-medium active:bg-fill-medium"
@@ -40,7 +40,7 @@ const panelSplitActionMenu = tv({
 		"pointer-events-auto min-w-0 rounded-s-none px-0",
 		"w-6 me-5 md:pointer-fine:w-5 md:pointer-fine:me-0",
 		"after:start-0 after:inset-e-[-21.5px] md:pointer-fine:after:-end-[calc(var(--spacing-control-hit)+1.5px)]",
-		"focus-visible:z-1",
+		"focus-visible:z-raised",
 		"[[data-split-action-main][data-pressed]~&]:[--split-action-menu-tint:var(--fill-subtle)]",
 		"[[data-split-action-main][aria-pressed=true]~&]:[--split-action-menu-tint:var(--fill-subtle)]",
 		"bg-(--split-action-menu-tint,transparent)",

package/dist/components/popover/popover.mjs

@@ -9,7 +9,7 @@ import { Popover } from "@base-ui/react/popover";
 const popover = tv({
 	slots: {
 		trigger: ["select-none"],
-		positioner: ["isolate z-50 outline-none"],
+		positioner: ["isolate z-popup outline-none"],
 		content: [
 			"max-h-(--available-height) min-w-[220px] overflow-hidden",
 			"outline-none",

package/dist/components/preview-card/preview-card.mjs

@@ -10,7 +10,7 @@ import { PreviewCard } from "@base-ui/react/preview-card";
 const previewCard = tv({
 	slots: {
 		trigger: [],
-		positioner: ["isolate z-50 outline-none"],
+		positioner: ["isolate z-popup outline-none"],
 		popup: [
 			"max-h-(--available-height) min-w-[220px] overflow-hidden",
 			"outline-none",

package/dist/components/pull-to-refresh/pull-to-refresh-indicator.mjs

@@ -45,7 +45,7 @@ const pullToRefreshIndicator = tv({
 			surface: ["size-full"]
 		},
 		android: {
-			root: ["sticky top-0 z-10 h-0 overflow-visible"],
+			root: ["sticky top-0 z-sticky h-0 overflow-visible"],
 			surface: [
 				"absolute inset-x-0 top-0 mx-auto size-10 rounded-full bg-layer-popover shadow-float",
 				"translate-y-[calc(var(--pull-distance)-100%)]",

package/dist/components/resizable/resizable.recipe.mjs

@@ -4,7 +4,7 @@ const resizable = tv({ slots: {
 	group: ["flex size-full  min-h-0 min-w-0", "data-[orientation=vertical]:flex-col"],
 	panel: ["min-h-0 min-w-0"],
 	handle: [
-		"right-0 z-10 cursor-ew-resize touch-none select-none",
+		"right-0 z-control cursor-ew-resize touch-none select-none",
 		"relative -mr-3 flex w-3 shrink-0 items-center justify-center pointer-coarse:-mr-6 pointer-coarse:w-6",
 		"before:pointer-events-none before:absolute before:transition-colors before:content-['']",
 		"focus-visible:outline-none focus-visible:before:outline-2 focus-visible:before:outline-offset-2 focus-visible:before:outline-foreground",

package/dist/components/scroll-area/scroll-area.css

@@ -469,6 +469,7 @@
   .r-scroll-area > .r-scroll-area__gutters {
     pointer-events: none;
     user-select: none;
+    /* raft-ui: z-index the gutters paint over every layer inside the area (its root is isolate) until slock's layers inside its ScrollAreas are named (#218 step 2); then var(--z-index-scrollbar). */
     z-index: 2147483647;
   }
   /*

package/dist/components/select/select.mjs

@@ -39,7 +39,7 @@ const select = tv({
 			"[&>svg]:size-4 [&>svg]:stroke-2 [&>svg_*]:stroke-2"
 		],
 		value: ["flex min-w-0 flex-1 truncate text-left"],
-		positioner: ["isolate z-50 outline-none"],
+		positioner: ["isolate z-popup outline-none"],
 		content: [
 			"relative max-h-(--available-height) min-w-[max(var(--anchor-width),220px)] overflow-hidden",
 			"max-w-[min(var(--available-width),max(var(--anchor-width),24rem))]",
@@ -92,7 +92,7 @@ const select = tv({
 		groupLabel: ["py-2", "px-2.5 pt-2 pb-1 text-caption font-bold text-foreground-hint"],
 		separator: ["h-px shrink-0 border-0", "-mx-1 my-1 bg-line-hairline"],
 		scrollArrow: [
-			"absolute inset-x-0 z-10 flex h-6 w-full cursor-default items-center justify-center",
+			"absolute inset-x-0 z-raised flex h-6 w-full cursor-default items-center justify-center",
 			"outline-none transition-colors",
 			"data-[direction=up]:top-0 data-[direction=down]:bottom-0",
 			"[&_svg]:pointer-events-none [&_svg]:shrink-0",

package/dist/components/selection-toolbar/selection-toolbar.recipe.mjs

@@ -3,7 +3,7 @@ import { tv } from "../../lib/tv.mjs";
 const selectionToolbar = tv({
 	slots: {
 		dock: [
-			"pointer-events-none absolute inset-x-0 bottom-0 z-10 flex justify-center",
+			"pointer-events-none absolute inset-x-0 bottom-0 z-float flex justify-center",
 			"px-5 pb-[calc(--spacing(3)+env(safe-area-inset-bottom))]",
 			"*:pointer-events-auto"
 		],

package/dist/components/sidebar/sidebar.recipe.mjs

@@ -16,7 +16,7 @@ const sidebarRecipe = tv({ slots: {
 		headEdgePull,
 		"[@media(max-height:600px)]:h-(--header-height-short)"
 	],
-	sidebarHeaderMask: ["pointer-events-none absolute inset-x-0 top-0 -z-10 hidden"],
+	sidebarHeaderMask: ["pointer-events-none absolute inset-x-0 top-0 z-below hidden"],
 	sidebarHeaderMaskLayer: ["absolute inset-x-0 top-0"],
 	sidebarHeaderTitle: ["truncate font-bold", "font-sans text-headline text-foreground max-md:text-foreground-on-frame"],
 	sidebarGroupLabel: ["px-5 pt-4 pb-0 md:pointer-fine:px-(--sidebar-glyph-axis) md:pointer-fine:pt-2", "font-sans text-footnote font-bold normal-case tracking-normal text-foreground-hint"],

package/dist/components/tabs/tabs.mjs

@@ -22,7 +22,7 @@ const tabs = tv({
 		],
 		background: ["", "hidden"],
 		tab: [
-			"relative z-10 flex shrink-0 cursor-pointer touch-manipulation select-none [-webkit-touch-callout:none] items-center gap-1.5 whitespace-nowrap outline-none",
+			"relative isolate flex shrink-0 cursor-pointer touch-manipulation select-none [-webkit-touch-callout:none] items-center gap-1.5 whitespace-nowrap outline-none",
 			"data-[reorderable=true]:cursor-pointer data-[dragging-source=true]:cursor-grabbing",
 			"font-sans text-callout font-semibold text-foreground-muted",
 			"transition-[background-color,box-shadow,color] duration-100 ease-out",
@@ -31,7 +31,7 @@ const tabs = tv({
 			"[&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg]:stroke-2 [&_svg:not([class*='size-'])]:size-4",
 			"data-disabled:pointer-events-none data-disabled:text-foreground-disabled"
 		],
-		content: ["relative z-10 inline-flex items-center gap-[inherit]"],
+		content: ["relative z-raised inline-flex items-center gap-[inherit]"],
 		label: [""],
 		panel: ["outline-none"],
 		indicator: ["", "hidden"]
@@ -416,7 +416,7 @@ function SortableTabsTab({ value, ...props }) {
 		...baseStyle,
 		transform: translate === void 0 ? void 0 : vertical ? `translate3d(0, ${translate}px, 0)` : `translate3d(${translate}px, 0, 0)`,
 		transition,
-		zIndex: isDragging ? 20 : baseStyle?.zIndex,
+		zIndex: isDragging ? "var(--z-index-raised)" : baseStyle?.zIndex,
 		cursor: isDragging ? "grabbing" : "pointer",
 		...isDragging && !home ? PLACE_STYLE : null
 	}), [
@@ -483,7 +483,7 @@ function TabsTabButton({ value, sortableRef, dropPlace = false, className, child
 			"data-slot": "tabs-tab-content",
 			className: content({ className: dropPlace ? "invisible" : void 0 }),
 			children
-		}), dropPlace ? /* @__PURE__ */ jsx(DropPlaceholder, { className: "absolute inset-0 z-10 rounded-control" }) : null]
+		}), dropPlace ? /* @__PURE__ */ jsx(DropPlaceholder, { className: "absolute inset-0 z-raised rounded-control" }) : null]
 	});
 }
 function TabsLabel({ className, ...props }) {

package/dist/components/task-dnd/task-dnd.recipe.mjs

@@ -2,9 +2,9 @@ import { tv } from "../../lib/tv.mjs";
 //#region src/components/task-dnd/task-dnd.recipe.ts
 const taskDnd = tv({ slots: {
 	draggable: [
-		"group/task-draggable relative cursor-grab touch-manipulation select-none [-webkit-touch-callout:none] active:cursor-grabbing",
+		"group/task-draggable relative isolate cursor-grab touch-manipulation select-none [-webkit-touch-callout:none] active:cursor-grabbing",
 		"outline-none",
-		"data-[dragging=true]:z-20 data-[dragging=true]:will-change-transform",
+		"data-[dragging=true]:z-raised data-[dragging=true]:will-change-transform",
 		"data-[disabled=true]:cursor-default data-[disabled=true]:touch-auto",
 		"rounded-container",
 		"focus-visible:shadow-focus"

package/dist/components/thread-panel/thread-panel.recipe.mjs

@@ -17,7 +17,7 @@ const threadPanel = tv({ slots: {
 	titleMeta: ["font-normal text-foreground-hint"],
 	actions: panelHeadActions,
 	search: [
-		"relative z-20 flex shrink-0 items-center gap-1.5 py-2",
+		"relative z-chrome flex shrink-0 items-center gap-1.5 py-2",
 		"[&>[data-slot=input-group]]:min-w-0 *:data-[slot=input-group]:flex-1",
 		"border-b border-line-hairline bg-layer-canvas px-(--surface-inset)"
 	],

package/dist/components/toast/toast.mjs

@@ -10,8 +10,8 @@ import { Toast } from "@base-ui/react/toast";
 //#region src/components/toast/toast.tsx
 const toastStyles = tv({
 	slots: {
-		viewport: ["pointer-events-none isolate z-80 w-[min(24rem,calc(100vw-2rem))]", "outline-none"],
-		positioner: ["isolate z-[calc(80-var(--toast-index))] outline-none"],
+		viewport: ["pointer-events-none isolate z-toast w-[min(24rem,calc(100vw-2rem))]", "outline-none"],
+		positioner: ["isolate z-[calc(var(--z-index-toast)-var(--toast-index))] outline-none"],
 		root: [
 			"group/toast pointer-events-auto",
 			"select-text",
@@ -101,7 +101,7 @@ const toastStyles = tv({
 		layout: {
 			stacked: { root: [
 				"absolute inset-x-0 bottom-0 mx-auto h-(--toast-stack-height) origin-bottom",
-				"z-[calc(70-var(--toast-index))]",
+				"z-[calc(var(--z-index-toast)-var(--toast-index))]",
 				"before:pointer-events-auto before:absolute before:inset-x-0 before:top-full before:h-[calc(var(--toast-gap)+3px)] before:content-['']",
 				"[--toast-peek-dir:-1]",
 				"transform-[translateX(var(--toast-swipe-movement-x))_translateY(calc(var(--toast-swipe-movement-y)+(var(--toast-index)*var(--toast-peek)*var(--toast-peek-dir))))_scale(var(--toast-scale))]",
@@ -185,8 +185,8 @@ const toastAction = tv({ slots: {
 		"data-[loading=true]:cursor-wait data-[loading=true]:opacity-100",
 		"[&_svg]:pointer-events-none [&_svg]:shrink-0 **:data-icon:size-[1em] [&_svg:not([class*='size-'])]:size-3"
 	],
-	content: "relative z-10 inline-flex items-center justify-center gap-[inherit] data-[loading=true]:invisible",
-	loadingIndicator: "pointer-events-none absolute inset-0 z-10 flex items-center justify-center"
+	content: "relative z-raised inline-flex items-center justify-center gap-[inherit] data-[loading=true]:invisible",
+	loadingIndicator: "pointer-events-none absolute inset-0 z-raised flex items-center justify-center"
 } });
 const createToastManager = Toast.createToastManager;
 const useToastManager = Toast.useToastManager;

package/dist/components/tooltip/tooltip.mjs

@@ -9,7 +9,7 @@ import { Tooltip } from "@base-ui/react/tooltip";
 const tooltip = tv({
 	slots: {
 		trigger: ["select-none"],
-		positioner: ["isolate z-50 pointer-events-none outline-none"],
+		positioner: ["isolate z-popup pointer-events-none outline-none"],
 		content: [
 			"pointer-events-none relative inline-block max-w-[min(20rem,var(--available-width,20rem))] min-w-0 px-2.5 py-1",
 			"origin-(--transform-origin) outline-none",
@@ -25,7 +25,7 @@ const tooltip = tv({
 		],
 		body: [
 			"block min-w-0 text-footnote whitespace-normal wrap-break-word",
-			"**:data-[slot=kbd]:relative **:data-[slot=kbd]:z-10 **:data-[slot=kbd]:ml-1.5",
+			"**:data-[slot=kbd]:relative **:data-[slot=kbd]:z-raised **:data-[slot=kbd]:ml-1.5",
 			"**:data-[slot=kbd-group]:ml-1.5 [&_[data-slot=kbd-group]_[data-slot=kbd]]:ml-0",
 			"**:data-[slot=kbd]:h-4 **:data-[slot=kbd]:min-w-4 **:data-[slot=kbd]:px-1 **:data-[slot=kbd]:py-0",
 			"[&_[data-slot=kbd][data-glyph=icon]]:px-0",

package/dist/lib/list-cell.mjs

@@ -5,7 +5,7 @@ const listCell = [
 	"md:pointer-fine:[--cell-pad-x:calc(var(--page-inset)-var(--cell-inset-x))]",
 	"[--cell-inset-end:max(0px,calc(var(--cell-inset-x)-var(--scrollbar-size,0px)))]",
 	"pr-[calc(var(--cell-inset-end)+var(--cell-pad-x))] pl-[calc(var(--cell-inset-x)+var(--cell-pad-x))]",
-	"before:pointer-events-none before:absolute before:-z-1 before:block before:content-['']",
+	"before:pointer-events-none before:absolute before:z-below before:block before:content-['']",
 	"before:inset-y-0 before:right-(--cell-inset-end) before:left-(--cell-inset-x)",
 	"before:rounded-(--cell-radius) before:border-0",
 	"before:transition-colors before:duration-150 before:ease-out"

package/dist/lint/no-raw-z-index.mjs

@@ -0,0 +1,142 @@
+import { classContext, constDeclarator, propertyKey, stringValue } from "./prefer-scroll-area.mjs";
+//#region src/lint/no-raw-z-index.ts
+/**
+* raft-ui/no-raw-z-index: every z-index is a named layer of the scale
+* (design/foundations/elevation.md#layer-order), so a number of the app's own,
+* which ranks its layer above or below layers it doesn't know about, is
+* reported where an app writes it.
+*
+* Reported:
+* - a Tailwind z-index class with a number or an arbitrary value (`z-10`,
+*   `-z-1`, `z-[60]`, `z-(--my-z)`, `[z-index:5]`, with any variant prefix or
+*   `!`) in a string or template literal that is a class, found as
+*   `raft-ui/prefer-scroll-area` finds one (a `className`, `class` or
+*   `*ClassName` attribute or property, an argument of `cn`, `tv` and the
+*   like, or a `const` of the same file used as a class). `z-auto` and the
+*   named layers (`z-raised`, `max-md:z-chrome`) are not reported;
+* - a `zIndex` property whose value is a number or a numeric string
+*   (`style={{ zIndex: 10 }}`, `const s = { zIndex: open ? 20 : "5" }`), a
+*   `zIndex={n}` JSX attribute, and an assignment `el.style.zIndex = "n"`.
+*   A `var(--z-index-…)` string is a name, and is not reported.
+*
+* Allowed with a `raft-ui: z-index <reason>` comment, line or block, on the
+* line above the reported string or property (or at the end of its line), as
+* for `raft-ui/prefer-scroll-area`. A comment without a reason doesn't count.
+*/
+const RAW_Z_CLASS = /(?<![\w-])!?-?z-(?:\d+|\[[^\]\s]*\]|\([^)\s]*\))!?(?![\w-])/;
+const RAW_Z_ARBITRARY = /\[z-index:[^\]]*\]/;
+const NUMERIC = /^\s*[-+]?\d+(?:\.\d+)?\s*$/;
+const ESCAPE = /\braft-ui:\s*z-index\s+\S/;
+/** Whether a class string has a z-index class with a number or an arbitrary value. */
+function hasRawZIndexClass(value) {
+	if (!value.includes("z-")) return false;
+	return RAW_Z_CLASS.test(value) || RAW_Z_ARBITRARY.test(value);
+}
+/** The numeric literals a `zIndex` value can be: `10`, `-1`, `"10"`, `a ? 20 : undefined`. */
+function numericLiterals(node, out) {
+	if (node.type === "ConditionalExpression") {
+		numericLiterals(node.consequent, out);
+		numericLiterals(node.alternate, out);
+	} else if (node.type === "LogicalExpression") {
+		numericLiterals(node.left, out);
+		numericLiterals(node.right, out);
+	} else if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression" || node.type === "ParenthesizedExpression" || node.type === "JSXExpressionContainer") numericLiterals(node.expression, out);
+	else if (node.type === "UnaryExpression" && (node.operator === "-" || node.operator === "+")) {
+		if (numericLiterals(node.argument, []).length > 0) out.push(node);
+	} else if (node.type === "Literal" && typeof node.value === "number") out.push(node);
+	else {
+		const text = stringValue(node);
+		if (text !== void 0 && NUMERIC.test(text)) out.push(node);
+	}
+	return out;
+}
+const noRawZIndex = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "A z-index is a named layer of the Raft Design System's scale (z-raised, z-sticky, ...), not a number.",
+			url: "https://raft-design.botiverse.build/foundations/elevation/#layer-order"
+		},
+		messages: { noRawZIndex: "Use a named layer instead of a z-index number: z-below, z-base, z-raised (inside an `isolate` root), z-control, z-sticky, z-float, z-chrome, z-cover, z-app; a popup, dialog, lightbox, toast or drag lift takes raft-ui's own component and no z-index. If this number must stay, say why in a `// raft-ui: z-index <reason>` comment on the line above. https://raft-design.botiverse.build/foundations/elevation/#layer-order" },
+		schema: []
+	},
+	create(context) {
+		const sourceCode = context.sourceCode ?? context.getSourceCode?.();
+		let escapeLines;
+		function line(index) {
+			return sourceCode.getLocFromIndex(index).line;
+		}
+		/** The lines an escape comment covers: the one it ends on and the next. */
+		function escaped() {
+			if (escapeLines) return escapeLines;
+			escapeLines = /* @__PURE__ */ new Set();
+			for (const comment of sourceCode?.getAllComments() ?? []) {
+				if (!ESCAPE.test(comment.value)) continue;
+				const end = comment.loc?.end.line ?? line(comment.range[1]);
+				escapeLines.add(end);
+				escapeLines.add(end + 1);
+			}
+			return escapeLines;
+		}
+		function startLine(node) {
+			return node.loc?.start.line ?? line(node.range[0]);
+		}
+		/** Reports `node` unless an escape comment covers the line `anchor` starts on. */
+		function report(node, anchor) {
+			const lines = escaped();
+			if (lines.size > 0 && lines.has(startLine(anchor))) return;
+			context.report({
+				node,
+				messageId: "noRawZIndex"
+			});
+		}
+		const constStrings = /* @__PURE__ */ new Map();
+		const classNames = /* @__PURE__ */ new Set();
+		function checkClassString(node, value) {
+			if (!hasRawZIndexClass(value)) return;
+			if (classContext(node)) return report(node, node);
+			const declarator = constDeclarator(node);
+			if (!declarator) return;
+			const name = declarator.id.name;
+			constStrings.set(name, [...constStrings.get(name) ?? [], node]);
+		}
+		function checkZIndexValue(value, anchor) {
+			for (const literal of numericLiterals(value, [])) report(literal, anchor);
+		}
+		return {
+			Literal(node) {
+				if (typeof node.value === "string") checkClassString(node, node.value);
+			},
+			TemplateLiteral(node) {
+				checkClassString(node, node.quasis.map((quasi) => quasi.value.raw).join(" "));
+			},
+			Identifier(node) {
+				const parent = node.parent;
+				if (parent?.type === "Property" && parent.key === node && !parent.computed && !parent.shorthand) return;
+				if (classContext(node)) classNames.add(node.name);
+			},
+			Property(node) {
+				if (propertyKey(node) !== "zIndex") return;
+				checkZIndexValue(node.value, node);
+			},
+			JSXAttribute(node) {
+				const name = node.name;
+				if (name?.type !== "JSXIdentifier" || name.name !== "zIndex") return;
+				const value = node.value;
+				if (value) checkZIndexValue(value, node);
+			},
+			AssignmentExpression(node) {
+				const target = node.left;
+				if (target.type !== "MemberExpression") return;
+				const property = target.property;
+				if ((target.computed ? stringValue(property) : property.type === "Identifier" ? property.name : void 0) !== "zIndex") return;
+				checkZIndexValue(node.right, node);
+			},
+			"Program:exit"() {
+				for (const name of classNames) for (const node of constStrings.get(name) ?? []) report(node, node);
+			}
+		};
+	}
+};
+//#endregion
+export { hasRawZIndexClass, noRawZIndex };

package/dist/lint/prefer-scroll-area.mjs

@@ -186,4 +186,4 @@ const preferScrollArea = {
 	}
 };
 //#endregion
-export { hasNativeScrollClass, preferScrollArea };
+export { attributeName, classContext, constDeclarator, hasNativeScrollClass, preferScrollArea, propertyKey, stringValue };

package/dist/lint/recommended.json

@@ -2,6 +2,7 @@
   "plugins": [],
   "jsPlugins": ["@botiverse/raft-ui/lint"],
   "rules": {
-    "raft-ui/prefer-scroll-area": "error"
+    "raft-ui/prefer-scroll-area": "error",
+    "raft-ui/no-raw-z-index": "off"
   }
 }

package/dist/lint.d.mts

@@ -13,8 +13,14 @@ export interface RaftUiLintPlugin {
   configs: Record<string, RaftUiLintConfig>;
 }
 export declare const rules: Record<string, RuleModule>;
-/** Every rule of the plugin with its severity, as `recommended.json` lists them. */
-export declare const recommendedRules: Record<string, "error">;
+/**
+ * Every rule of the plugin with its severity, as `recommended.json` lists them.
+ * A rule an app can't pass yet ships `off`, so an app that lints with
+ * `--max-warnings=0` (slock) stays green on the upgrade; an app turns it on in
+ * its own `rules` to clear what it reports, and it turns `error` here once the
+ * app has.
+ */
+export declare const recommendedRules: Record<string, "error" | "warn" | "off">;
 declare const plugin: RaftUiLintPlugin;
 /** ESLint flat config: `export default [raftUi.configs.recommended]`. */
 export declare const recommended: RaftUiLintConfig;

package/dist/lint.mjs

@@ -1,4 +1,5 @@
 import { preferScrollArea } from "./lint/prefer-scroll-area.mjs";
+import { noRawZIndex } from "./lint/no-raw-z-index.mjs";
 //#region src/lint/index.ts
 /**
 * raft-ui's lint plugin: the Raft Design System's rules for the code of an app
@@ -10,9 +11,21 @@ import { preferScrollArea } from "./lint/prefer-scroll-area.mjs";
 * rule added in a later release reaches the app with the upgrade. See
 * design/about/use-raft-ui.md#lint-rules.
 */
-const rules = { "prefer-scroll-area": preferScrollArea };
-/** Every rule of the plugin with its severity, as `recommended.json` lists them. */
-const recommendedRules = { "raft-ui/prefer-scroll-area": "error" };
+const rules = {
+	"prefer-scroll-area": preferScrollArea,
+	"no-raw-z-index": noRawZIndex
+};
+/**
+* Every rule of the plugin with its severity, as `recommended.json` lists them.
+* A rule an app can't pass yet ships `off`, so an app that lints with
+* `--max-warnings=0` (slock) stays green on the upgrade; an app turns it on in
+* its own `rules` to clear what it reports, and it turns `error` here once the
+* app has.
+*/
+const recommendedRules = {
+	"raft-ui/prefer-scroll-area": "error",
+	"raft-ui/no-raw-z-index": "off"
+};
 const plugin = {
 	meta: { name: "raft-ui" },
 	rules,

package/dist/styles.css

@@ -200,6 +200,34 @@
   }
 }
 
+/* Raft Design System layer order (design/foundations/elevation.md#layer-order).
+   Each name is an ordinary Tailwind `z-*` utility (`z-raised`, `max-md:z-chrome`,
+   `before:z-below`) and a variable for CSS (`var(--z-index-sticky)`). In-page
+   layers stay below 50, where the overlays begin; nothing sits above toasts or
+   the drag lift. `z-below`, `z-base` and `z-raised` are local: the component's
+   root is `isolate`, so they rank parts inside it only. A component that needs
+   a third local layer orders it by DOM order inside its own `isolate`.
+   Static, so every variable exists for an app's own CSS whether or not a
+   utility uses it. `z-index-named.test.ts` keeps the order. */
+@theme static {
+  --z-index-below: -1;
+  --z-index-base: 0;
+  --z-index-raised: 1;
+  --z-index-control: 10;
+  --z-index-sticky: 20;
+  --z-index-float: 30;
+  --z-index-chrome: 35;
+  --z-index-cover: 40;
+  --z-index-app: 45;
+  --z-index-scrollbar: 49;
+  --z-index-popup: 50;
+  --z-index-dialog: 50;
+  --z-index-dialog-layer: 60;
+  --z-index-lightbox: 70;
+  --z-index-toast: 80;
+  --z-index-drag: 999;
+}
+
 @theme inline {
   /* A drag settling: the drop and cancel glide, siblings sliding apart, a
      layout reflowing on a drop (design/foundations/motion.md). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-ui",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "description": "React components and CSS foundations for the Raft Design System.",
   "keywords": [
     "agent-skills",

package/skills/raft-ui-guide/SKILL.md

@@ -91,6 +91,7 @@ When reviewing or editing code that uses raft-ui, check:
 - [ ] Product state (upload, permissions, read/unread) lives in the app; the component renders parts, not a `state` prop
 - [ ] No shadow written as `shadow-[var(--…)]`: named utility or fully literal
 - [ ] Every region that scrolls is a `ScrollArea` (or `PanelScrollViewport` in a Panel), not `overflow-auto` / `overflow-scroll`; a native scroller kept on purpose has a `// raft-ui: native-scroll <reason>` comment. The `raft-ui/prefer-scroll-area` lint rule checks it: https://raft-design.botiverse.build/about/use-raft-ui.md#lint-rules
+- [ ] Every z-index is a layer name (`z-raised`, `z-control`, `z-sticky`, `z-float`, `z-chrome`, `z-cover`, `z-app`; `var(--z-index-…)` in CSS), never a number; popups, dialogs, lightboxes, toasts and drag lifts take raft-ui's components and no z-index. A number kept on purpose has a `// raft-ui: z-index <reason>` comment. The `raft-ui/no-raw-z-index` lint rule checks it: https://raft-design.botiverse.build/foundations/elevation.md#layer-order
 
 ## Stability