@botiverse/raft-ui 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.7.1](https://github.com/botiverse/raft-design/compare/v0.7.0...v0.7.1) (2026-10-19)
+
+### Added
+
+- `stack-y-*` / `stack-x-*` (including negative and arbitrary values) and `rule-y` / `rule-x` / `rule-<colour>`: space and rules between siblings, written as the owl `> * + *` at zero specificity. Use them instead of Tailwind's `space-*` / `divide-*`. ([#534](https://github.com/botiverse/raft-design/pull/534))
+
+### Fixed
+
+- **iOS scroll and open/close jank from structural selectors.** Tailwind v4 compiles `space-*` / `divide-*` to `:where(.x > :not(:last-child))`, which WebKit tests against every element; appending or removing a last child anywhere then restyled the previous last child's whole subtree (180–430ms under a long chat timeline). The package and its docs no longer use them, and `no-unanchored-structural.test.ts` keeps any rule from ending in an unanchored structural pseudo-class. Consumers should move their own `space-*` / `divide-*` to `stack-*` / `rule-*`. ([#534](https://github.com/botiverse/raft-design/pull/534))
+- `codemods/package-name.mjs` keeps a deliberate `raft-ui` npm alias instead of rewriting it. ([#522](https://github.com/botiverse/raft-design/pull/522))
+
+### Changed
+
+- The design-system pages and component guides describe what the product ships. ([#523](https://github.com/botiverse/raft-design/pull/523), [#524](https://github.com/botiverse/raft-design/pull/524), [#526](https://github.com/botiverse/raft-design/pull/526), [#528](https://github.com/botiverse/raft-design/pull/528)–[#530](https://github.com/botiverse/raft-design/pull/530), [#532](https://github.com/botiverse/raft-design/pull/532))
+
 ## [0.7.0](https://github.com/botiverse/raft-design/compare/v0.6.1...v0.7.0) (2026-10-18)
 
 ### Breaking Changes

package/codemods/package-name.mjs

@@ -83,7 +83,9 @@ export function renameDependency(json, version) {
     "optionalDependencies",
   ]) {
     const deps = json[field];
-    if (!deps || !("raft-ui" in deps)) continue;
+    // `"raft-ui": "npm:@botiverse/raft-ui@…"` is an alias kept on purpose, for a dependency
+    // that peers on the unscoped name: leave it.
+    if (!deps || !("raft-ui" in deps) || deps["raft-ui"].startsWith(`npm:${NEW}@`)) continue;
     const next = {};
     for (const [name, range] of Object.entries(deps)) {
       if (name === "raft-ui")

package/dist/foundation.css

@@ -9,9 +9,9 @@
                  (unordered axis — names say where the token is used)
      intensity = (bare default) > muted > hint for foreground;
                  hairline < seam < strong for line
-     layer = places on the elevation ladder; fill = opaque neutral interaction
-     fills (resting/hover/active/disabled surfaces) — the opaque counterpart
-     of the translucent ink washes.
+     layer = places on the elevation ladder; fill = neutral interaction fills
+     (resting/hover/active/disabled surfaces): fill-muted and fill-strong are
+     opaque, the -pressed overlays are translucent ink laid over a surface.
    Families:  {family}(-{slot})
      family = brand | attention | info | success | warning | danger | inactive
      slot   = -strong (deep shade: readable text, rings) > bare (solid fill)
@@ -20,8 +20,8 @@
               | -hover / -active (derived interaction pair, opt-in per family;
                 an opted-in family always gets both)
    Washes:    ink-{alpha%} (2..40) — neutral overlays, hairlines, hover fills.
-   Opacity rule: layer and fill tokens are opaque in every theme; -backdrop is
-   the only translucent layer token (an overlay by contract).
+   Opacity rule: layer tokens are opaque in every theme, except -backdrop (an
+   overlay by contract); among fills only the -pressed overlays are translucent.
    Interaction fills: transparent resting → ink-N directly; solid family fill →
    the family's -hover/-active pair; neutral or tinted surface → step up its ladder.
    Escape hatches: ink ramp for one-off washes; inline oklch() literals for

package/dist/index.d.mts

@@ -906,8 +906,8 @@ type SidebarItemRootProps = useRender.ComponentProps<"button"> & {
 type SidebarItemProps = SidebarItemRootProps & {
   /** For a row whose content is two lines (a name and a second line): the row
    * grows from its fixed height and its content aligns to the first line. The
-   * name itself stays on one line and truncates, in every group (decision
-   * 0030); never use this to let a long name wrap. */
+   * name itself stays on one line and truncates, in every group (Sidebar's
+   * rules); never use this to let a long name wrap. */
   wrap?: boolean;
   /** Something waits for you (a 700 name), the place is muted (an ink-2
    *  name), or it is away: offline or not joined (an ink-3 name). */
@@ -3925,7 +3925,7 @@ declare const notificationCenter: import("tailwind-variants/lite").TVReturnType<
   title: string[];
   count: string[];
   scroller: string[];
-  list: string[];
+  list: never[];
   item: string[];
   itemRow: string[];
   itemIcon: string[];
@@ -3984,7 +3984,7 @@ declare const notificationCenter: import("tailwind-variants/lite").TVReturnType<
   title: string[];
   count: string[];
   scroller: string[];
-  list: string[];
+  list: never[];
   item: string[];
   itemRow: string[];
   itemIcon: string[];
@@ -4043,7 +4043,7 @@ declare const notificationCenter: import("tailwind-variants/lite").TVReturnType<
   title: string[];
   count: string[];
   scroller: string[];
-  list: string[];
+  list: never[];
   item: string[];
   itemRow: string[];
   itemIcon: string[];

package/dist/index.mjs

@@ -5984,7 +5984,7 @@ const avatar = tv({
 		],
 		group: [
 			"group/avatar-group flex items-center",
-			"space-x-[-5px]",
+			"stack-x-[-5px]",
 			"*:data-[slot=avatar]:shadow-[0_0_0_1.5px_var(--sticker-edge),0_0_0_3px_var(--layer-canvas)]",
 			"*:data-[slot=avatar-group-count]:shadow-[0_0_0_1.5px_var(--sticker-edge),0_0_0_3px_var(--layer-canvas)]"
 		]
@@ -6643,7 +6643,7 @@ const messageItem = tv({
 		],
 		searchMatch: searchHit,
 		embedded: ["min-w-0", "mt-2"],
-		attachments: ["space-y-2", "mt-2"],
+		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",
@@ -7903,8 +7903,8 @@ const messageActionCardContent = tv({ slots: {
 	property: ["contents"],
 	propertyLabel: ["max-w-40 min-w-0 wrap-break-word", "text-footnote font-medium text-foreground-hint"],
 	propertyValue: ["m-0 min-w-0 wrap-break-word", "min-h-8 py-1.5 text-callout text-foreground"],
-	scopeList: ["mt-0 space-y-1.5"],
-	scopeListViewport: ["overflow-y-auto overscroll-contain", "max-h-[164px] space-y-1.5 pr-1"],
+	scopeList: ["mt-0 stack-y-1.5"],
+	scopeListViewport: ["overflow-y-auto overscroll-contain", "max-h-[164px] stack-y-1.5 pr-1"],
 	scopeListLabel: ["text-footnote font-medium text-foreground-hint"],
 	scope: ["min-w-0 border p-1.5", "rounded-control border-line-hairline bg-layer-card px-2.5 py-2"],
 	scopeName: ["break-all font-mono", "text-mono-meta font-normal text-foreground"],
@@ -8374,7 +8374,7 @@ function MessageAttachmentAction({ className, render, ...props }) {
 //#region src/components/message-attachment/message-image-gallery.recipe.ts
 const messageImageGallery = tv({
 	slots: {
-		root: ["max-w-[min(360px,calc(100vw-112px))] space-y-1 md:max-w-[360px]"],
+		root: ["max-w-[min(360px,calc(100vw-112px))] stack-y-1 md:max-w-[360px]"],
 		row: ["grid", "gap-1"],
 		item: [
 			"group/img relative overflow-hidden text-left",
@@ -10308,17 +10308,17 @@ function TableColumn({ className, render, ...props }) {
 const filePreview = tv({
 	slots: {
 		root: ["relative flex h-10 w-10 shrink-0 items-center justify-center"],
-		document: ["relative h-10 w-8 space-y-1.5 rounded-md rounded-tr-[15%] p-1.5 ring-1", "bg-layer-card shadow-none ring-line-hairline"],
+		document: ["relative h-10 w-8 stack-y-1.5 rounded-md rounded-tr-[15%] p-1.5 ring-1", "bg-layer-card shadow-none ring-line-hairline"],
 		file: ["relative flex h-10 w-8 items-center justify-center rounded-md rounded-tr-[15%] ring-1", "bg-layer-card shadow-none ring-line-hairline"],
 		code: ["relative flex h-10 w-8 items-center justify-center rounded-md rounded-tr-[15%] ring-1", "bg-layer-card shadow-none ring-line-hairline"],
 		fileZip: ["flex h-7 items-center justify-center"],
 		fileZipStack: ["relative -translate-y-0.5 flex flex-col items-center"],
-		fileZipTeeth: ["space-y-px"],
+		fileZipTeeth: ["stack-y-px"],
 		fileZipRow: ["flex overflow-hidden rounded-full"],
 		fileZipDark: ["size-0.5", "bg-foreground/40"],
 		fileZipLight: ["size-0.5", "bg-foreground/15"],
 		fileZipPull: ["mt-0.5 h-1 w-2.5 rounded-sm border", "border-foreground/40 bg-foreground/10"],
-		codeStack: ["-translate-y-0.5 space-y-px"],
+		codeStack: ["-translate-y-0.5 stack-y-px"],
 		codeRow: ["flex items-center gap-0.5 leading-none"],
 		codeRowIndent: ["flex items-center gap-0.5 pl-1.5 leading-none"],
 		codeTextRow: ["block pl-3"],
@@ -11988,7 +11988,7 @@ const notificationCenter = tv({
 		title: ["font-sans text-headline text-foreground"],
 		count: ["ml-auto", "font-mono text-mono-meta text-foreground-hint"],
 		scroller: ["min-h-0 flex-1 overflow-y-auto overscroll-contain"],
-		list: ["divide-y-0"],
+		list: [],
 		item: [
 			"group/notification-center-item relative px-4 py-3",
 			"before:pointer-events-none before:absolute before:top-0 before:right-0 before:left-4 before:hidden before:border-t before:border-line-hairline",
@@ -14801,7 +14801,7 @@ function createTaskDndOverStore() {
 //#endregion
 //#region src/components/task-list/task-list-section.recipe.ts
 const taskListSection = tv({ slots: {
-	root: ["space-y-2"],
+	root: ["stack-y-2"],
 	trigger: [
 		"group flex w-full touch-manipulation items-center text-left outline-none",
 		"disabled:cursor-default",
@@ -14825,7 +14825,7 @@ const taskListSection = tv({ slots: {
 		"group-hover:text-foreground"
 	],
 	panel: ["data-ending-style:hidden"],
-	items: ["space-y-2"],
+	items: ["stack-y-2"],
 	empty: [
 		"px-3",
 		"flex min-h-16 items-center justify-center py-3",
@@ -14838,7 +14838,7 @@ const taskListSection = tv({ slots: {
 function TaskListRoot({ className, render, ...props }) {
 	const defaultProps = {
 		"data-slot": "task-list-root",
-		className: cn("space-y-6", className)
+		className: cn("stack-y-6", className)
 	};
 	return useRender({
 		defaultTagName: "div",
@@ -15247,14 +15247,14 @@ const legacyTaskPanel = tv({
 			"[&_svg]:size-3.5"
 		],
 		title: ["flex flex-col items-start gap-0.5 overflow-visible whitespace-normal"],
-		body: ["space-y-4 overflow-y-auto px-5 py-4"],
+		body: ["stack-y-4 overflow-y-auto px-5 py-4"],
 		status: ["flex flex-wrap items-center gap-2"],
-		section: ["p-4", "space-y-3 rounded-container border border-line-hairline bg-layer-card shadow-none"],
+		section: ["p-4", "stack-y-3 rounded-container border border-line-hairline bg-layer-card shadow-none"],
 		field: [],
 		fieldLabel: ["mb-0.5 font-sans text-footnote font-medium text-foreground-hint"],
 		fieldTitle: ["m-0 wrap-break-word", "text-body font-semibold text-foreground"],
 		fieldText: ["m-0 whitespace-pre-wrap wrap-break-word", "text-subhead text-foreground-muted"],
-		meta: ["p-4 text-sm", "space-y-0 rounded-container border border-line-hairline bg-layer-card px-4 py-2 shadow-none"],
+		meta: ["p-4 text-sm", "rounded-container border border-line-hairline bg-layer-card px-4 py-2 shadow-none"],
 		metaRow: ["flex justify-between gap-3", "min-h-8 items-center"],
 		metaLabel: ["font-sans text-footnote font-medium text-foreground-hint"],
 		metaValue: ["text-right", "text-callout text-foreground"]
@@ -16254,7 +16254,7 @@ const searchThread = tv({ slots: {
 	],
 	threadTimestamp: ["normal-case", "ml-auto"],
 	threadTitle: ["font-sans text-callout font-semibold text-foreground"],
-	threadMessages: ["flex flex-col [&>*:first-child]:border-t-0", "border-t-0 bg-transparent"]
+	threadMessages: ["flex flex-col", "border-t-0 bg-transparent"]
 } });
 //#endregion
 //#region src/components/search/search-thread.tsx

package/dist/styles.css

@@ -389,3 +389,56 @@ body {
 @utility press-overlay-sticker {
   background-image: linear-gradient(var(--sticker-pressed), var(--sticker-pressed));
 }
+
+/* Space and rules between siblings: stack-y-* / stack-x-* and rule-y / rule-x
+   / rule-<colour>. Use these, never Tailwind's space-* and divide-*.
+
+   Tailwind v4 compiles space-* and divide-* to `:where(.x > :not(:last-child))`.
+   Its rightmost part has no class, so WebKit (every iOS browser) tests it
+   against every element and marks every parent as depending on which child is
+   last. Appending or removing a last child anywhere then restyles the previous
+   last child's whole subtree: 180-430ms when a chat's bottom controls mount
+   after its timeline. Chromium does not pay this, so it only shows on iOS.
+   The owl `> * + *` depends only on the previous sibling, so appending at the
+   end restyles nothing. Zero specificity, like Tailwind's, so a child's own
+   margin or border class still wins. */
+@utility stack-y-* {
+  :where(& > * + *) {
+    margin-block-start: calc(var(--spacing) * --value(number));
+    margin-block-start: --value([length]);
+  }
+}
+@utility stack-y-px {
+  :where(& > * + *) {
+    margin-block-start: 1px;
+  }
+}
+@utility stack-x-* {
+  :where(& > * + *) {
+    margin-inline-start: calc(var(--spacing) * --value(number));
+    margin-inline-start: --value([length]);
+  }
+}
+@utility -stack-x-* {
+  :where(& > * + *) {
+    margin-inline-start: calc(var(--spacing) * --value(number) * -1);
+    margin-inline-start: calc(--value([length]) * -1);
+  }
+}
+@utility rule-y {
+  :where(& > * + *) {
+    border-block-start-width: 1px;
+    border-block-start-style: solid;
+  }
+}
+@utility rule-x {
+  :where(& > * + *) {
+    border-inline-start-width: 1px;
+    border-inline-start-style: solid;
+  }
+}
+@utility rule-* {
+  :where(& > * + *) {
+    border-color: --value(--color-*, [color]);
+  }
+}

package/package.json

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

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

@@ -11,7 +11,7 @@ The design guidance (which component to use, how components combine into screens
 
 - **Index:** https://raft-design.botiverse.build/llms.txt lists every page with a one-line summary.
 - **Components:** https://raft-design.botiverse.build/components.json lists every component with its status, other names and doc URLs. Each component page, `https://raft-design.botiverse.build/components/<component>.md`, has when to use it, its parts, rules and an API generated from the code.
-- **Choosing a component:** https://raft-design.botiverse.build/patterns/choosing-components.md.
+- **Choosing a component:** https://raft-design.botiverse.build/components/overview.md#how-to-choose-a-component.
 
 This skill keeps what is specific to the code: the [adoption](./rules/adoption.md) order, [looking up](./rules/lookup.md) props and tokens, and the [technical overview](./rules/technical-overview.md) (package contents, stylesheets, providers). Do not register or install skills in a consumer project unless requested.
 
@@ -68,8 +68,8 @@ The guideline rules this skill used to carry are pages of the design system now.
 
 | For                                               | Read                                                                                                                       |
 | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Which component, which feedback, which overlay    | https://raft-design.botiverse.build/patterns/choosing-components.md                                                        |
-| Combining parts, things built from existing parts | https://raft-design.botiverse.build/patterns/composites.md                                                                 |
+| Which component, which feedback, which overlay    | https://raft-design.botiverse.build/components/overview.md#how-to-choose-a-component                                       |
+| Combining parts, things built from existing parts | https://raft-design.botiverse.build/components/overview.md#built-from-existing-parts                                       |
 | Forms and settings                                | https://raft-design.botiverse.build/patterns/forms.md                                                                      |
 | Feedback, loading, empty and error states         | https://raft-design.botiverse.build/patterns/feedback.md                                                                   |
 | Shell, panels, headers, navigation                | https://raft-design.botiverse.build/patterns/page-structure.md, https://raft-design.botiverse.build/patterns/navigation.md |

package/skills/raft-ui-guide/rules/composition.md

@@ -7,8 +7,8 @@ description: "Moved to the Raft Design System docs: combining compound parts, ov
 
 This guidance is part of the Raft Design System docs now, which are its single source. Each page is Markdown; read only the ones the task needs.
 
-- Composites: what is built from existing parts: https://raft-design.botiverse.build/patterns/composites.md
-- Choosing a component: https://raft-design.botiverse.build/patterns/choosing-components.md
+- Built from existing parts: https://raft-design.botiverse.build/components/overview.md#built-from-existing-parts
+- Choosing a component: https://raft-design.botiverse.build/components/overview.md#how-to-choose-a-component
 - The component's own page, for its parts: https://raft-design.botiverse.build/components/<component>.md
 
 Check every prop, part and token you use against [lookup.md](./lookup.md).

package/skills/raft-ui-guide/rules/feedback.md

@@ -8,6 +8,6 @@ description: "Moved to the Raft Design System docs: banners, toasts, loading, em
 This guidance is part of the Raft Design System docs now, which are its single source. Each page is Markdown; read only the ones the task needs.
 
 - Feedback: https://raft-design.botiverse.build/patterns/feedback.md
-- Choosing a component: telling people something, and waiting: https://raft-design.botiverse.build/patterns/choosing-components.md#telling-people-something
+- Choosing a component: telling people something, and waiting: https://raft-design.botiverse.build/components/overview.md#telling-people-something
 
 Check every prop, part and token you use against [lookup.md](./lookup.md).

package/skills/raft-ui-guide/rules/forms.md

@@ -8,6 +8,6 @@ description: "Moved to the Raft Design System docs: choosing and composing form
 This guidance is part of the Raft Design System docs now, which are its single source. Each page is Markdown; read only the ones the task needs.
 
 - Forms and settings: https://raft-design.botiverse.build/patterns/forms.md
-- Choosing a component: picking something: https://raft-design.botiverse.build/patterns/choosing-components.md#picking-something
+- Choosing a component: picking something: https://raft-design.botiverse.build/components/overview.md#picking-something
 
 Check every prop, part and token you use against [lookup.md](./lookup.md).

package/skills/raft-ui-guide/rules/overlays.md

@@ -7,7 +7,7 @@ description: "Moved to the Raft Design System docs: dialogs, drawers, popovers,
 
 This guidance is part of the Raft Design System docs now, which are its single source. Each page is Markdown; read only the ones the task needs.
 
-- Choosing a component: overlays: https://raft-design.botiverse.build/patterns/choosing-components.md#overlays
+- Choosing a component: overlays: https://raft-design.botiverse.build/components/overview.md#overlays
 - Elevation: which things float, and how popups are positioned: https://raft-design.botiverse.build/foundations/elevation.md
 
 Check every prop, part and token you use against [lookup.md](./lookup.md).

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

@@ -77,4 +77,4 @@ Custom fonts use `--heading-font`, `--sans-font`, and `--mono-font`.
 - Base UI overlays portal to `document.body`. An app root with `isolation: isolate` keeps its stacking contexts below those surfaces. Embedded previews can use `portalProps.container` (toasts: `ToastProvider portalContainer`) to keep overlays inside their scope.
 - SSR apps with persisted mode need to restore it before first paint to avoid a theme flash.
 
-What floats and how popups are positioned is in [Elevation](https://raft-design.botiverse.build/foundations/elevation.md); which overlay to use is in [Choosing a component](https://raft-design.botiverse.build/patterns/choosing-components.md#overlays).
+What floats and how popups are positioned is in [Elevation](https://raft-design.botiverse.build/foundations/elevation.md); which overlay to use is in [Choosing a component](https://raft-design.botiverse.build/components/overview.md#overlays).