@botiverse/raft-ui 0.73.0 → 0.75.0

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## [0.75.0](https://github.com/botiverse/raft-design/compare/v0.74.0...v0.75.0) (2026-11-08)
+
+### Changed
+
+- **A horizontal DescriptionList puts its labels above their values only when a value doesn't fit**: the list measures its labels and values and keeps each label beside its value while every value fits on one line there; once one doesn't (but would on a line of its own), or the value column would be narrower than 160px, the whole list stacks. It no longer stacks below a fixed 24rem (384px), and is no longer a size container. MessageActionCard's properties follow the same rule. ([#1065](https://github.com/botiverse/raft-design/pull/1065))
+  - Why: an agent's Role, Computer and Model stacked in a 370px profile though they fit beside their labels; the switch should follow the content, not a width picked for the longest label (Artea, #triage:428e3ce6).
+  - Affects: short facts in panels from about 300px to 384px, and on a phone, now stand beside their labels. A list whose values are wide still stacks, at the width they stop fitting.
+  - Docs: https://raft-design.botiverse.build/components/description-list/#labels-go-above-only-when-a-value-doesnt-fit
+
+### Fixed
+
+- **Chinese text on Linux uses Noto Sans CJK**: the Simplified Chinese fallback lists `Noto Sans CJK SC`, the name Linux distributions install it under, after `Noto Sans SC`, as the Traditional Chinese list already did with `Noto Sans CJK TC`. ([#1063](https://github.com/botiverse/raft-design/pull/1063))
+  - Why: on a Linux machine with only the distribution's CJK font, Chinese and its full-width punctuation fell to the system's last-resort face, whose colon sits centered with space around it (Remy, #proj-raft-ui:0c3f4e06; seen in the read line's screenshots from CI).
+  - Affects: Linux desktops and CI screenshots; Mac and Windows already matched PingFang SC or Microsoft YaHei first.
+  - Docs: https://raft-design.botiverse.build/foundations/typography/
+
+## [0.74.0](https://github.com/botiverse/raft-design/compare/v0.73.0...v0.74.0) (2026-11-08)
+
+### Added
+
+- **Lint rules for apps**: `@botiverse/raft-ui/lint` is a lint plugin with the design system's rules for app code, in the ESLint plugin format, which Oxlint loads as a JS plugin. Its first rule, `raft-ui/prefer-scroll-area`, reports a class or an inline style that makes an element scroll natively (`overflow-auto`, `overflow-scroll` and their `-x-` and `-y-` forms, with any variant) where an app writes it, unless a `// raft-ui: native-scroll <reason>` comment on the line above says which exception it is. The comment covers the string on the next line only, not the rest of a multi-line `cn(...)`, so a class added to the list later is still checked. Turn on every rule at once by extending `./node_modules/@botiverse/raft-ui/dist/lint/recommended.json` from `.oxlintrc.json` (or `configs.recommended` in an ESLint flat config); a rule added later reaches the app with the upgrade. ([#1058](https://github.com/botiverse/raft-design/pull/1058), [#1059](https://github.com/botiverse/raft-design/pull/1059))
+  - Why: the design system's rules should reach the apps, and the agents working in them, with raft-ui itself rather than through each repository's instructions; every region that scrolls is a ScrollArea, and nothing outside raft-ui checked it (Artea, #proj-raft-ui:#209).
+  - Affects: nothing until an app turns the plugin on. Then each native scroller in its code is reported: make it a ScrollArea (or `PanelScrollViewport` in a Panel), or add the comment with its reason.
+  - Docs: https://raft-design.botiverse.build/about/use-raft-ui/#lint-rules
+
+### Changed
+
+- **useScrollAreaContainer gives its container the overflow**: the classes in `containerProps.className` make the element scroll in the `orientation`, as ScrollArea's own container does (vertical: `overflow-y: auto` and `overflow-x: hidden`; horizontal: the other way round; both: `auto`), so the element needs no overflow class of its own and nothing for `raft-ui/prefer-scroll-area` to report. `ComposerInput` and `ActivityInboxViewport` no longer carry `overflow-y-auto`. ([#1059](https://github.com/botiverse/raft-design/pull/1059))
+  - Why: the hook asked the app to add a native overflow class, which the new lint rule reports (Jasper's review of the lint rule).
+  - Affects: apps can drop the overflow class from a `useScrollAreaContainer` element. One they keep still wins (the hook's rule has no specificity), so nothing breaks. A vertical container that had only `overflow-y-auto` now clips sideways (`overflow-x: hidden`) instead of scrolling sideways with no scrollbar; pass `orientation="both"` for content that scrolls both ways.
+  - Docs: https://raft-design.botiverse.build/components/scroll-area/#your-own-container
+
+### Design System
+
+- **A thread's timeline**: conversation.md lists what a thread's timeline shows (the message it started from and every message a person wrote), when it appears, the rail for a mouse, the Timeline entry in the thread's More menu on every device, a half-height sheet on a phone and a popover wider, and how its items are marked. No raft-ui component changed. ([#1057](https://github.com/botiverse/raft-design/pull/1057))
+  - Why: a long thread buries the few messages people wrote under agents' work (Artea, #proj-raft-ui:#206).
+  - Docs: https://raft-design.botiverse.build/patterns/conversation/#a-threads-timeline
+
 ## [0.73.0](https://github.com/botiverse/raft-design/compare/v0.72.0...v0.73.0) (2026-11-08)
 
 ### Changed

package/dist/components/activity-inbox/activity-inbox-shell.recipe.mjs

@@ -9,7 +9,7 @@ const activityInboxShell = tv({ slots: {
 	],
 	frame: ["min-h-0 flex-1"],
 	viewport: [
-		"relative flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto *:shrink-0",
+		"relative flex min-h-0 flex-1 flex-col gap-0.5 *:shrink-0",
 		"outline-none focus-visible:shadow-focus",
 		"bg-layer-canvas px-0 pt-2 pb-[calc(8px+env(safe-area-inset-bottom,0px))]"
 	],

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

@@ -12,7 +12,7 @@ const composer = tv({
 		inputFrame: ["w-full min-w-0", "[--r-scroll-area-resize-grip-size:0px]"],
 		input: [
 			"max-h-32 w-full resize-none bg-transparent outline-none",
-			"field-sizing-content overflow-y-auto",
+			"field-sizing-content",
 			"min-h-6 px-0.5",
 			"font-sans text-body font-normal text-foreground",
 			"placeholder:text-foreground-hint"

package/dist/components/description-list/description-list.d.mts

@@ -49,7 +49,7 @@ declare const descriptionList: import("tailwind-variants/lite").TVReturnType<{
 }>>;
 export type DescriptionListDirection = NonNullable<VariantProps<typeof descriptionList>["direction"]>;
 export type DescriptionListProps = useRender.ComponentProps<"dl"> & Pick<VariantProps<typeof descriptionList>, "direction">;
-export declare function DescriptionList({ direction, className, render, ...props }: DescriptionListProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export declare function DescriptionList({ direction, className, render, ref, ...props }: DescriptionListProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type DescriptionItemProps = useRender.ComponentProps<"div">;
 export declare function DescriptionItem({ className, render, ...props }: DescriptionItemProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export type DescriptionTermProps = useRender.ComponentProps<"dt">;

package/dist/components/description-list/description-list.mjs

@@ -1,4 +1,6 @@
 import { tv } from "../../lib/tv.mjs";
+import { useLabelValueFit } from "../../lib/label-value-fit.mjs";
+import { useCallback, useState } from "react";
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
 //#region src/components/description-list/description-list.tsx
@@ -21,10 +23,10 @@ const descriptionList = tv({
 	variants: { direction: {
 		vertical: {},
 		horizontal: { root: [
-			"@container/description-list w-full grid items-baseline",
-			"[&>[data-slot=description-item]>*]:@max-sm/description-list:col-span-full",
-			"[&>[data-slot=description-item]>[data-slot=description-details]]:@max-sm/description-list:min-h-0",
-			"[&>[data-slot=description-item]+[data-slot=description-item]>[data-slot=description-term]]:@max-sm/description-list:mt-2",
+			"w-full grid items-baseline",
+			"[&[data-stacked]>[data-slot=description-item]>*]:col-span-full",
+			"[&[data-stacked]>[data-slot=description-item]>[data-slot=description-details]]:min-h-0",
+			"[&[data-stacked]>[data-slot=description-item]+[data-slot=description-item]>[data-slot=description-term]]:mt-2",
 			"*:data-[slot=description-item]:contents",
 			"[&>[data-slot=description-item]>[data-slot=description-term]]:mb-0",
 			"[&>[data-slot=description-item]>[data-slot=description-term]]:max-w-40",
@@ -52,12 +54,20 @@ const descriptionList = tv({
 	} },
 	defaultVariants: { direction: "vertical" }
 });
-function DescriptionList({ direction = "vertical", className, render, ...props }) {
+const listParts = {
+	label: ":scope > [data-slot=description-item] > [data-slot=description-term]",
+	value: ":scope > [data-slot=description-item] > [data-slot=description-details]"
+};
+function DescriptionList({ direction = "vertical", className, render, ref, ...props }) {
+	const [list, setList] = useState(null);
+	const listRef = useCallback((element) => setList(element), []);
+	useLabelValueFit(list, direction === "horizontal", listParts);
 	const { root } = descriptionList({ direction });
 	const defaultProps = { className: root({ className }) };
 	return useRender({
 		defaultTagName: "dl",
 		render,
+		ref: ref ? [listRef, ref] : listRef,
 		props: mergeProps(defaultProps, props),
 		state: { slot: "description-list" }
 	});

package/dist/components/message-action-card/message-action-card-content.recipe.mjs

@@ -1,7 +1,7 @@
 import { tv } from "../../lib/tv.mjs";
 //#region src/components/message-action-card/message-action-card-content.recipe.ts
 const messageActionCardContent = tv({ slots: {
-	root: ["p-3", "@container/action-card flex flex-col gap-2 px-3 pt-0 pb-3"],
+	root: ["p-3", "flex flex-col gap-2 px-3 pt-0 pb-3"],
 	panel: [
 		"h-(--collapsible-panel-height) overflow-hidden",
 		"transition-[height] duration-200 ease-out motion-reduce:transition-none",
@@ -9,19 +9,19 @@ const messageActionCardContent = tv({ slots: {
 	],
 	properties: [
 		"m-0 grid",
-		"@max-sm/action-card:grid-cols-1",
+		"data-stacked:grid-cols-1",
 		"grid-cols-[minmax(88px,max-content)_minmax(0,1fr)] items-baseline gap-x-4 gap-y-0.5"
 	],
 	property: ["contents"],
 	propertyLabel: [
 		"max-w-40 min-w-0 wrap-break-word",
 		"text-footnote font-medium text-foreground-hint",
-		"[[data-slot=message-action-card-property]+[data-slot=message-action-card-property]>&]:@max-sm/action-card:mt-2"
+		"[[data-stacked]>[data-slot=message-action-card-property]+[data-slot=message-action-card-property]>&]:mt-2"
 	],
 	propertyValue: [
 		"m-0 min-w-0 wrap-break-word",
 		"min-h-8 py-1.5 text-callout text-foreground",
-		"@max-sm/action-card:min-h-0 @max-sm/action-card:py-0"
+		"[[data-stacked]>[data-slot=message-action-card-property]>&]:min-h-0 [[data-stacked]>[data-slot=message-action-card-property]>&]:py-0"
 	],
 	scopeList: ["mt-0 stack-y-1.5"],
 	scopeListViewport: ["max-h-[136px]"],

package/dist/components/message-action-card/message-action-card.d.mts

@@ -32,7 +32,7 @@ export declare function MessageActionCardStatus({ className, appearance, ...prop
 export declare function MessageActionCardCollapseTrigger({ className, ...props }: MessageActionCardCollapseTriggerProps): import("react").JSX.Element;
 export declare function MessageActionCardHeader({ className, render, ...props }: useRender.ComponentProps<"div">): import("react").JSX.Element;
 export declare function MessageActionCardHeaderStatus({ className, render, ...props }: useRender.ComponentProps<"span">): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
-export declare function MessageActionCardProperties({ className, render, ...props }: useRender.ComponentProps<"dl">): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export declare function MessageActionCardProperties({ className, render, ref, ...props }: useRender.ComponentProps<"dl">): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export declare function MessageActionCardProperty({ className, render, ...props }: useRender.ComponentProps<"div">): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export declare function MessageActionCardPropertyLabel({ className, render, ...props }: useRender.ComponentProps<"dt">): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 export declare function MessageActionCardPropertyValue({ className, render, ...props }: useRender.ComponentProps<"dd">): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/dist/components/message-action-card/message-action-card.mjs

@@ -1,10 +1,12 @@
 import { ScrollArea } from "../scroll-area/scroll-area.mjs";
 import { Badge } from "../badge/badge.mjs";
+import { useLabelValueFit } from "../../lib/label-value-fit.mjs";
 import { MessageEmbed, MessageEmbedContent, MessageEmbedHeader } from "../message-embed/message-embed.mjs";
 import { messageActionCard } from "./message-action-card.recipe.mjs";
 import { messageActionCardContent } from "./message-action-card-content.recipe.mjs";
 import { ChevronDown, Info, Zap } from "lucide-react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
 import { Collapsible } from "@base-ui/react/collapsible";
@@ -127,11 +129,19 @@ function MessageActionCardHeaderStatus({ className, render, ...props }) {
 		state: { slot: "message-action-card-header-status" }
 	});
 }
-function MessageActionCardProperties({ className, render, ...props }) {
+const propertyParts = {
+	label: ":scope > [data-slot=message-action-card-property] > [data-slot=message-action-card-property-label]",
+	value: ":scope > [data-slot=message-action-card-property] > [data-slot=message-action-card-property-value]"
+};
+function MessageActionCardProperties({ className, render, ref, ...props }) {
+	const [list, setList] = useState(null);
+	const listRef = useCallback((element) => setList(element), []);
+	useLabelValueFit(list, true, propertyParts);
 	const { properties } = messageActionCardContent();
 	return useRender({
 		defaultTagName: "dl",
 		render,
+		ref: ref ? [listRef, ref] : listRef,
 		props: mergeProps({ className: properties({ className }) }, props),
 		state: { slot: "message-action-card-properties" }
 	});
@@ -249,7 +259,7 @@ function MessageActionCardNotice({ className, render, icon, children, ...props }
 		render,
 		props: mergeProps({
 			className: notice({ className }),
-			children: /* @__PURE__ */ jsxs(Fragment, { children: [icon ?? /* @__PURE__ */ jsx(Info, { "aria-hidden": true }), /* @__PURE__ */ jsx("span", { children })] })
+			children: /* @__PURE__ */ jsxs(Fragment$1, { children: [icon ?? /* @__PURE__ */ jsx(Info, { "aria-hidden": true }), /* @__PURE__ */ jsx("span", { children })] })
 		}, props),
 		state: { slot: "message-action-card-notice" }
 	});

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

@@ -24,8 +24,8 @@
  * `--overflow-{y,x}-{start,end}` (more content past that edge; `x` is
  * inline; these and `--rtl` are set by the script with `classList`, never
  * rendered) and `--textarea`; `__container` (with absolute gutters, the
- * container), `__viewport` (ScrollArea's own `<div>` container: its
- * overflow), `__content`, `__textarea`, `__gutters` (with `--scrolling`,
+ * container), `__viewport` (ScrollArea's own `<div>` container),
+ * `__content`, `__textarea`, `__gutters` (with `--scrolling`,
  * from the first scroll until `hideDelay` after the last, and `--dragging`,
  * both set by the script: on the layer, so toggling them restyles only the
  * gutters, not the content under the root), `__gutter` (`--vertical`,
@@ -216,9 +216,9 @@
   }
 
   /*
-   * The container. Its own overflow, layout and focus are its own (a list,
-   * a textarea); the overlay scrollbars replace its native ones. With sticky
-   * gutters it is the root.
+   * The container. Its layout and focus are its own (a list, a textarea);
+   * its overflow is the orientation's (below), and the overlay scrollbars
+   * replace its native ones. With sticky gutters it is the root.
    */
   .r-scroll-area.r-scroll-area--sticky-gutters,
   .r-scroll-area.r-scroll-area--absolute-gutters > .r-scroll-area__container {
@@ -242,17 +242,34 @@
     position: relative;
   }
 
-  /* ScrollArea's own `<div>` container (always sticky) scrolls in the orientation. */
-  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area__viewport {
+  /*
+   * Every container scrolls in the orientation: ScrollArea's own `<div>` and
+   * a `useScrollAreaContainer` element alike, so a caller never writes the
+   * overflow. With no specificity (`:where`), so a component's own rule for
+   * its scroller (VirtualList's) or an overflow in the caller's `className`
+   * still wins over it.
+   */
+  :where(.r-scroll-area.r-scroll-area--sticky-gutters),
+  :where(.r-scroll-area.r-scroll-area--absolute-gutters > .r-scroll-area__container) {
     overflow: hidden auto;
-    position: relative;
   }
-  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--horizontal-orientation.r-scroll-area__viewport {
+  :where(.r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--horizontal-orientation),
+  :where(
+    .r-scroll-area.r-scroll-area--absolute-gutters.r-scroll-area--horizontal-orientation
+      > .r-scroll-area__container
+  ) {
     overflow: auto hidden;
   }
-  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--both-orientation.r-scroll-area__viewport {
+  :where(.r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area--both-orientation),
+  :where(
+    .r-scroll-area.r-scroll-area--absolute-gutters.r-scroll-area--both-orientation
+      > .r-scroll-area__container
+  ) {
     overflow: auto;
   }
+  .r-scroll-area.r-scroll-area--sticky-gutters.r-scroll-area__viewport {
+    position: relative;
+  }
 
   /*
    * A scroll that reaches the end stops there instead of scrolling the page:

package/dist/components/scroll-area/types.d.mts

@@ -116,7 +116,9 @@ export type ScrollAreaContainerProps<E extends HTMLElement = HTMLElement> = {
   ref: RefCallback<E>;
   /**
    * Before your own classes. With sticky gutters the container is the root, so these are the
-   * root's classes and modifiers; with absolute gutters, `r-scroll-area__container`.
+   * root's classes and modifiers; with absolute gutters, `r-scroll-area__container`. They give the
+   * element the orientation's overflow (vertical: `overflow-y: auto`, `overflow-x: hidden`), so
+   * it needs no overflow class of its own; one of yours still wins over it.
    */
   className: string;
   /** With sticky gutters, the root's variables (`railInset`, the timelines); merge your style after it. */

package/dist/components/scroll-area/use-scroll-area-container.d.mts

@@ -6,7 +6,8 @@ import { ScrollAreaContainer, ScrollAreaContainerOptions, ScrollAreaFrameProps }
  * its scroll, and keeps the state; you render the elements.
  *
  * Spread `containerProps` on the element that scrolls (a `<ul>`, a `<textarea>`, VirtualList's
- * scroller through `domRef`), merging your own `className` and `style` with them (pass your own
+ * scroller through `domRef`), merging your own `className` and `style` with them; its classes give
+ * the element the orientation's overflow, so it needs no overflow class (pass your own
  * refs as `containerRef` and `frameRef`: the returned `ref`s already forward to them), and render
  * `<ScrollAreaGutters {...guttersProps} />` where `guttersPosition` says:
  *

package/dist/fonts.css

@@ -11,10 +11,10 @@
 :where(:root) {
   --heading-font:
     "Space Grotesk", Arial, "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
-    "Noto Sans SC", system-ui, sans-serif;
+    "Noto Sans SC", "Noto Sans CJK SC", system-ui, sans-serif;
   --sans-font:
     "Space Grotesk", Arial, "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
-    "Noto Sans SC", system-ui, sans-serif;
+    "Noto Sans SC", "Noto Sans CJK SC", system-ui, sans-serif;
   --mono-font: "Space Mono", ui-monospace, "SF Mono", Menlo, monospace;
 }
 

package/dist/lib/label-value-fit.mjs

@@ -0,0 +1,117 @@
+import { useLayoutEffect } from "react";
+//#region src/lib/label-value-fit.ts
+/** The narrowest the label column gets: `minmax(88px, max-content)` in both lists. */
+const minLabelColumn = 88;
+/**
+* The narrowest the value column may be beside its labels: as wide as a label
+* may grow (`max-w-40`). A value column narrower than its label column reads
+* as the label's footnote, not its answer.
+*/
+const minValueColumn = 160;
+/**
+* Reads every element's width with nothing wrapping inside it: all of them
+* go to one-line layout, are read in one pass and get their inline style
+* back, so the list is laid out once for the read, not once per element.
+*/
+function oneLineWidths(els) {
+	const saved = els.map(({ style }) => [
+		style.width,
+		style.maxWidth,
+		style.whiteSpace,
+		style.flexWrap
+	]);
+	for (const { style } of els) {
+		style.width = "max-content";
+		style.maxWidth = "none";
+		style.whiteSpace = "nowrap";
+		style.flexWrap = "nowrap";
+	}
+	const widths = els.map((el) => el.getBoundingClientRect().width);
+	els.forEach(({ style }, i) => {
+		[style.width, style.maxWidth, style.whiteSpace, style.flexWrap] = saved[i];
+	});
+	return widths;
+}
+/**
+* Whether a two-column label/value list has to put its labels above their
+* values: some value doesn't fit on one line beside the label column, but
+* would on a line of its own, or the value column would be narrower than
+* `minValueColumn`. A value too long for a line of its own (a paragraph)
+* wraps either way and doesn't decide. Measured in one-line layout whatever
+* the list shows now, so the answer depends only on the list's width and its
+* content and can't flap at the boundary.
+*/
+function labelsGoAbove(list, parts) {
+	const style = getComputedStyle(list);
+	const width = list.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight);
+	const gap = parseFloat(style.columnGap) || 0;
+	const labels = Array.from(list.querySelectorAll(parts.label));
+	const values = Array.from(list.querySelectorAll(parts.value));
+	const caps = labels.map((label) => parseFloat(getComputedStyle(label).maxWidth));
+	const widths = oneLineWidths([...labels, ...values]);
+	let labelColumn = minLabelColumn;
+	labels.forEach((_, i) => {
+		const natural = widths[i];
+		const cap = caps[i];
+		labelColumn = Math.max(labelColumn, Number.isNaN(cap) ? natural : Math.min(natural, cap));
+	});
+	const valueColumn = width - labelColumn - gap;
+	if (valueColumn < minValueColumn) return true;
+	for (const natural of widths.slice(labels.length)) if (natural - valueColumn > .5 && natural - width <= .5) return true;
+	return false;
+}
+/**
+* Sets `data-stacked` on a two-column label/value list while its labels have
+* to go above their values (`labelsGoAbove`), and takes it off when they fit
+* beside them again: the list's CSS does the rest. The decision is taken
+* synchronously, in the layout effect and the observers' callbacks, so the
+* first frame and every resize paint the right layout; again when the list
+* or a value resizes, a label or value changes, or a web font arrives
+* (design/patterns/responsive.md#when-a-row-runs-out-of-room).
+*/
+function useLabelValueFit(list, enabled, parts) {
+	const { label, value } = parts;
+	useLayoutEffect(() => {
+		if (!list || !enabled || typeof ResizeObserver === "undefined") return void 0;
+		const selectors = {
+			label,
+			value
+		};
+		const fit = () => {
+			const stacked = labelsGoAbove(list, selectors);
+			if (stacked !== list.hasAttribute("data-stacked")) list.toggleAttribute("data-stacked", stacked);
+		};
+		const resize = new ResizeObserver(fit);
+		const observeAll = () => {
+			resize.disconnect();
+			resize.observe(list);
+			for (const el of Array.from(list.querySelectorAll(`${label}, ${value}`))) for (const child of Array.from(el.children)) resize.observe(child);
+		};
+		observeAll();
+		const mutation = new MutationObserver(() => {
+			observeAll();
+			fit();
+		});
+		mutation.observe(list, {
+			childList: true,
+			subtree: true,
+			characterData: true
+		});
+		const fonts = typeof document === "undefined" ? void 0 : document.fonts;
+		fonts?.addEventListener("loadingdone", fit);
+		fit();
+		return () => {
+			resize.disconnect();
+			mutation.disconnect();
+			fonts?.removeEventListener("loadingdone", fit);
+			list.removeAttribute("data-stacked");
+		};
+	}, [
+		list,
+		enabled,
+		label,
+		value
+	]);
+}
+//#endregion
+export { labelsGoAbove, useLabelValueFit };

package/dist/lint/prefer-scroll-area.d.mts

@@ -0,0 +1,75 @@
+//#region src/lint/prefer-scroll-area.d.ts
+/**
+ * raft-ui/prefer-scroll-area: every region that scrolls is a ScrollArea
+ * (scroll-area.md#native-scrolling), so a native overflow that makes an
+ * element scroll is reported where an app writes it.
+ *
+ * Reported:
+ * - a native-scrolling Tailwind class (`overflow`, `overflow-x` or `overflow-y`
+ *   set to auto or scroll, with any variant prefix, `!`, or as an arbitrary
+ *   property) in a string or template literal that is a class: the value of a
+ *   `className`, `class` or `*ClassName` JSX attribute, or an argument of
+ *   `cn`, `clsx`, `cx`, `tv`, `cva`, `twMerge`, `twJoin` or `classNames`,
+ *   through conditionals, `&&`, arrays, objects (keys and values) and `+`;
+ * - an inline `style={{ overflow | overflowX | overflowY: "auto" | "scroll" }}`.
+ *
+ * Allowed with a `raft-ui: native-scroll <reason>` comment, line or block, on
+ * the line above the reported string (or at the end of its line): it covers
+ * the string that starts on that line only, not the rest of the call or the
+ * attribute it is in, so a class added to a multi-line `cn(...)` later is
+ * still reported. For an inline style, the line of its property. A comment
+ * without a reason doesn't count.
+ *
+ * It looks only at literals, with no scope or type information: a class built
+ * in a variable outside these calls isn't seen.
+ */
+export interface Position {
+  line: number;
+  column: number;
+}
+export interface Node {
+  type: string;
+  parent?: Node | null;
+  loc?: {
+    start: Position;
+    end: Position;
+  };
+  range?: [number, number];
+  [key: string]: unknown;
+}
+export interface Comment {
+  type: string;
+  value: string;
+  loc?: {
+    start: Position;
+    end: Position;
+  };
+  range?: [number, number];
+}
+export interface SourceCode {
+  getAllComments(): Comment[];
+  getLocFromIndex(index: number): Position;
+}
+export interface RuleContext {
+  sourceCode?: SourceCode;
+  getSourceCode?: () => SourceCode;
+  report(descriptor: {
+    node: Node;
+    messageId: string;
+  }): void;
+}
+export type RuleVisitor = Record<string, (node: Node) => void>;
+/** An ESLint rule, the format Oxlint's JS plugins take. */
+export interface RuleModule {
+  meta: {
+    type: "problem" | "suggestion" | "layout";
+    docs: {
+      description: string;
+      url: string;
+    };
+    messages: Record<string, string>;
+    schema: readonly unknown[];
+  };
+  create(context: RuleContext): RuleVisitor;
+}
+//#endregion

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

@@ -0,0 +1,157 @@
+//#region src/lint/prefer-scroll-area.ts
+const NATIVE_SCROLL_CLASS = /(?<![\w-])overflow(?:-[xy])?-(?:auto|scroll)(?![\w-])/;
+const NATIVE_SCROLL_ARBITRARY = /\[overflow(?:-[xy])?:[^\]]*\b(?:auto|scroll)\b[^\]]*\]/;
+const NATIVE_SCROLL_STYLE_KEYS = /* @__PURE__ */ new Set([
+	"overflow",
+	"overflowX",
+	"overflowY"
+]);
+const NATIVE_SCROLL_STYLE_VALUES = /* @__PURE__ */ new Set(["auto", "scroll"]);
+const CLASS_FUNCTIONS = /* @__PURE__ */ new Set([
+	"cn",
+	"clsx",
+	"cx",
+	"tv",
+	"cva",
+	"twMerge",
+	"twJoin",
+	"classNames",
+	"classnames"
+]);
+const CLASS_ATTRIBUTE = /^(?:class|className|\w+ClassName)$/;
+const PASS_THROUGH = /* @__PURE__ */ new Set([
+	"ArrayExpression",
+	"BinaryExpression",
+	"ConditionalExpression",
+	"JSXExpressionContainer",
+	"LogicalExpression",
+	"ObjectExpression",
+	"ParenthesizedExpression",
+	"Property",
+	"SpreadElement",
+	"TemplateLiteral",
+	"TSAsExpression",
+	"TSNonNullExpression",
+	"TSSatisfiesExpression"
+]);
+const ESCAPE = /\braft-ui:\s*native-scroll\s+\S/;
+/** Whether a class string has a native-scrolling class in it. */
+function hasNativeScrollClass(value) {
+	if (!value.includes("overflow")) return false;
+	return NATIVE_SCROLL_CLASS.test(value) || NATIVE_SCROLL_ARBITRARY.test(value);
+}
+function attributeName(node) {
+	const name = node.name;
+	return name?.type === "JSXIdentifier" ? name.name : void 0;
+}
+/** The attribute or call that makes a string a class, or undefined when it isn't one. */
+function classContext(node) {
+	let child = node;
+	let parent = node.parent;
+	while (parent) {
+		if (parent.type === "JSXAttribute") {
+			const name = attributeName(parent);
+			return name !== void 0 && CLASS_ATTRIBUTE.test(name) ? parent : void 0;
+		}
+		if (parent.type === "CallExpression") {
+			const callee = parent.callee;
+			return callee.type === "Identifier" && CLASS_FUNCTIONS.has(callee.name) && parent.arguments.includes(child) ? parent : void 0;
+		}
+		if (!PASS_THROUGH.has(parent.type)) return void 0;
+		child = parent;
+		parent = parent.parent;
+	}
+}
+function stringValue(node) {
+	if (node.type === "Literal" && typeof node.value === "string") return node.value;
+	if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+		const [quasi] = node.quasis;
+		const value = quasi?.value;
+		return value?.cooked ?? value?.raw;
+	}
+}
+/** The string literals an inline style value can be: `"auto"`, `a ? "auto" : "hidden"`, `a && "auto"`. */
+function styleValueStrings(node, out) {
+	if (node.type === "ConditionalExpression") {
+		styleValueStrings(node.consequent, out);
+		styleValueStrings(node.alternate, out);
+	} else if (node.type === "LogicalExpression") {
+		styleValueStrings(node.left, out);
+		styleValueStrings(node.right, out);
+	} else if (node.type === "TSAsExpression" || node.type === "TSSatisfiesExpression") styleValueStrings(node.expression, out);
+	else if (stringValue(node) !== void 0) out.push(node);
+	return out;
+}
+function propertyKey(property) {
+	const key = property.key;
+	if (property.computed) return stringValue(key);
+	return key.type === "Identifier" ? key.name : stringValue(key);
+}
+const preferScrollArea = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Scrolling regions use ScrollArea from @botiverse/raft-ui, not a native overflow.",
+			url: "https://raft-design.botiverse.build/about/use-raft-ui/#lint-rules"
+		},
+		messages: { preferScrollArea: "Scrolling regions use ScrollArea from @botiverse/raft-ui (or PanelScrollViewport inside a Panel). If this one must scroll natively, say why in an `// raft-ui: native-scroll <reason>` comment on the line above. https://raft-design.botiverse.build/components/scroll-area/" },
+		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: "preferScrollArea"
+			});
+		}
+		function checkClassString(node, value) {
+			if (!hasNativeScrollClass(value)) return;
+			if (classContext(node)) report(node, node);
+		}
+		return {
+			Literal(node) {
+				if (typeof node.value === "string") checkClassString(node, node.value);
+			},
+			TemplateLiteral(node) {
+				checkClassString(node, node.quasis.map((quasi) => quasi.value.raw).join(" "));
+			},
+			JSXAttribute(node) {
+				if (attributeName(node) !== "style") return;
+				const value = node.value;
+				const expression = value?.type === "JSXExpressionContainer" ? value.expression : void 0;
+				if (expression?.type !== "ObjectExpression") return;
+				for (const property of expression.properties) {
+					if (property.type !== "Property") continue;
+					const key = propertyKey(property);
+					if (key === void 0 || !NATIVE_SCROLL_STYLE_KEYS.has(key)) continue;
+					for (const literal of styleValueStrings(property.value, [])) if (NATIVE_SCROLL_STYLE_VALUES.has(stringValue(literal).trim())) report(literal, property);
+				}
+			}
+		};
+	}
+};
+//#endregion
+export { hasNativeScrollClass, preferScrollArea };

package/dist/lint/recommended.json

@@ -0,0 +1,6 @@
+{
+  "jsPlugins": ["@botiverse/raft-ui/lint"],
+  "rules": {
+    "raft-ui/prefer-scroll-area": "error"
+  }
+}

package/dist/lint.d.mts

@@ -0,0 +1,22 @@
+import { RuleContext, RuleModule, RuleVisitor } from "./lint/prefer-scroll-area.mjs";
+//#region src/lint/index.d.ts
+export interface RaftUiLintConfig {
+  name: string;
+  plugins: Record<string, RaftUiLintPlugin>;
+  rules: Record<string, "error" | "warn" | "off">;
+}
+export interface RaftUiLintPlugin {
+  meta: {
+    name: string;
+  };
+  rules: Record<string, RuleModule>;
+  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">;
+declare const plugin: RaftUiLintPlugin;
+/** ESLint flat config: `export default [raftUi.configs.recommended]`. */
+export declare const recommended: RaftUiLintConfig;
+//#endregion
+export { type RuleContext, type RuleModule, type RuleVisitor, plugin as default };

package/dist/lint.mjs

@@ -0,0 +1,29 @@
+import { preferScrollArea } from "./lint/prefer-scroll-area.mjs";
+//#region src/lint/index.ts
+/**
+* raft-ui's lint plugin: the Raft Design System's rules for the code of an app
+* built on raft-ui, in the ESLint plugin format, which Oxlint loads as a JS
+* plugin (`jsPlugins`). Published as `@botiverse/raft-ui/lint`.
+*
+* Enable every rule at once by extending `recommended.json` from the same
+* package (Oxlint) or adding `configs.recommended` (ESLint flat config), so a
+* 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 plugin = {
+	meta: { name: "raft-ui" },
+	rules,
+	configs: {}
+};
+/** ESLint flat config: `export default [raftUi.configs.recommended]`. */
+const recommended = {
+	name: "raft-ui/recommended",
+	plugins: { "raft-ui": plugin },
+	rules: recommendedRules
+};
+plugin.configs.recommended = recommended;
+//#endregion
+export { plugin as default, recommended, recommendedRules, rules };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/raft-ui",
-  "version": "0.73.0",
+  "version": "0.75.0",
   "description": "React components and CSS foundations for the Raft Design System.",
   "keywords": [
     "agent-skills",
@@ -46,6 +46,11 @@
       "types": "./dist/wip.d.mts",
       "default": "./dist/wip.mjs"
     },
+    "./lint": {
+      "types": "./dist/lint.d.mts",
+      "default": "./dist/lint.mjs"
+    },
+    "./lint/recommended.json": "./dist/lint/recommended.json",
     "./fonts.css": "./dist/fonts.css",
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json",

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

@@ -90,6 +90,7 @@ When reviewing or editing code that uses raft-ui, check:
 - [ ] Menu rows are `…Item` parts, not raw `<button>`s; raw buttons drop out of keyboard navigation
 - [ ] 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
 
 ## Stability
 

package/skills/raft-ui-guide/rules/technical-overview.md

@@ -19,6 +19,7 @@ description: "raft-ui's technical foundations, package contents, and integration
 | `@botiverse/raft-ui/foundation.css` | Native CSS theme variables              |
 | `@botiverse/raft-ui/styles.css`     | Tailwind integration                    |
 | `@botiverse/raft-ui/fonts.css`      | Optional web fonts                      |
+| `@botiverse/raft-ui/lint`           | Lint plugin with the DS rules for apps  |
 
 Component declarations live in `dist/index.d.mts` (see [API lookup](./lookup.md)). Version-matched Markdown guides and optional `raft-ui-guide` / `raft-ui-critique` skills ship in `skills/`.