@botiverse/raft-ui 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -1,3 +1,191 @@
+## [0.21.0](https://github.com/botiverse/raft-design/compare/v0.20.1...v0.21.0) (2026-10-22)
+
+0.20.1 was not published to npm. This release includes its changes, listed under [0.20.1](https://github.com/botiverse/raft-design/blob/v0.21.0/packages/ui/CHANGELOG.md#0201-2026-10-22) in the changelog.
+
+### Design System
+
+- **Timeline rhythm**: a conversation uses three distances between its lines, measured from text to text: 8px between the rows of one turn, the message step (16px) between turns, and the section step (24px) at a boundary: either side of a date line, from the top of the list to its first line, and from the last line to the composer's frame. It applies to MessageItem, SystemMessage, SystemMessageGroupHeader, MessageListDateDivider, MessageListNotice, ThreadPanelOriginalMessage, ThreadPanelReplySummary, ThreadPanelReplyCount, ConversationPanelFooter and ThreadPanelFooter. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: each part kept its own spacing, so a date line sat closer to the message above it than to the one below and looked attached to it, an event line had more space under it than over it, and the composer's frame read as touching the last message; the parts now read one rhythm from tokens, one step wider for each kind of break.
+  - Affects: new tokens `timeline-gap-message` 16px, `timeline-gap-section` 24px and `timeline-row-inset` 4px (the reach of a row's highlight above and below its text).
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+- **A control and its label**: a checkbox, radio or switch sits 8px before its label, centered on the label's first line, and keeps its size wherever it sits. In a settings row with a description, both ends center on the title's first line. A tap between two options lands on the nearer one. It applies to Checkbox, RadioGroupItem and ListRow; FieldItem already followed it. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: a box in a `<label>` row followed the row instead of the text's line, so callers nudged it with a margin, and a settings row's ends centered on the title and description together, level with neither; the components now place the control themselves.
+  - Affects: switch 50 × 30px and checkbox and radio 20px, unchanged; 8px from control to label.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+
+### Breaking Changes
+
+- **ConversationPanelFooter** and **ThreadPanelFooter**: no space of their own above the composer; the end of the list sets it. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: the footer's 12px stacked on whatever space the list left under its last message, so the gap to the composer differed from list to list; now the list ends with one token and the composer's frame sits a section step, 24px, under the last line.
+  - Affects: footer top padding 12px → 0; `pb-timeline-end` is 20px (the 24px section step less the last row's 4px inset).
+  - Migrate: end your message list with `pb-timeline-end` under its last row, in place of any spacer you had there; without it the composer moves 12px closer to the last message. You can also start the list with `pt-timeline-start` over its first row, so its top follows the same step.
+  - Docs: https://raft-design.botiverse.build/components/conversation-panel/
+
+### Added
+
+- **Timeline spacing utilities**: `pt-timeline-start` and `pb-timeline-end` for the top and end of a message list you build, and `timeline-message`, `timeline-section`, `timeline-row`, `timeline-turn` and `timeline-lead`, which the components use. All are registered with the `cn` helper, so they merge with other padding and margin classes. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: a list's top and end were written by hand in each product, which is how the gaps drifted; two utilities now give the section step with the rows' own insets taken out.
+  - Affects: `timeline-start` 12px, `timeline-end` 20px, `timeline-turn` 8px, `timeline-lead` 12px, `timeline-message` 16px, `timeline-section` 24px, `timeline-row` 4px. Use only `timeline-start` and `timeline-end` in a product.
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+- **`ButtonSize`** and **`DeprecatedButtonSize`** types, and the **`button-sizes` codemod**, which renames deprecated Button sizes to the size they render as. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: the deprecated names could only be found by hand, and `sm` and `xs` are also sizes of other components; the codemod parses TSX and renames `size` only on Buttons, the raft-ui parts that pass `size` to a Button and wrappers you name, plus `icon-sm` / `icon-xs` on any element and `size` in `buttonVariants()` calls.
+  - Affects: run `node node_modules/@botiverse/raft-ui/codemods/button-sizes.mjs <src> [--dry] [--components=MyButton]`; it renames `xs`, `sm` → `md` and `icon-xs`, `icon-sm` → `icon-md`, then lists every `sm`, `xs`, `icon-sm` and `icon-xs` it left for review. It needs `@babel/parser`, a new optional peer dependency (`pnpm add -D @babel/parser`); nothing else uses it.
+  - Docs: https://raft-design.botiverse.build/components/button/#sizes
+
+### Changed
+
+- **Button** `size`: `xs` and `sm` are deprecated aliases of `md`, and `icon-xs` and `icon-sm` of `icon-md`, kept until raft-ui 1.0. They already rendered as those sizes, so nothing on screen changes. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: nine names for five sizes made a smaller button look available where there is none; a new Size by place table says which size each place takes.
+  - Affects: sizes `md` (32px), `lg`, `xl`, `icon-md` and `icon-lg`; `size` is typed `ButtonSize | DeprecatedButtonSize`, so every existing size name still type-checks. No runtime warning.
+  - Docs: https://raft-design.botiverse.build/components/button/#size-by-place
+- **Checkbox** and **RadioGroupItem** directly in a `<label>`: the box takes one line of the label's height and centers on it, so it sits on the first line in an `items-start` row and on the one line in an `items-center` row, at any min-height. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: the box followed the row rather than the text's line, so it sat above the center of a line taller than 20px and callers added a `margin-top`; see A control and its label above.
+  - Affects: vertical margin `max(0, (1lh - 20px) / 2)` from the `<label>`'s type (2px on a 24px line); the box stays 20px and a `text-xs` row stays 20px tall. A `margin-top` you added to line it up is no longer needed. Set the label's type on the `<label>`, use `items-start` when the text can wrap, and give a wrapping `text-xs` label `leading-5`.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+- **DescriptionList** `direction="inline"`: every fact is at most 24rem wide, or the row's width if that is narrower, and keeps the same 24px between facts and 8px between lines as the others. ([#697](https://github.com/botiverse/raft-design/pull/697))
+  - Why: a long value, such as a message, made its fact as wide as the row on a line of its own, so one line of facts no longer read as one flow; every fact now wraps the same way, and a long value wraps at the cap, or is cut there when the caller truncates it.
+  - Affects: fact `max-width` none → `min(100%, 24rem)` (384px); plain text longer than that wraps inside the 24rem. To cut a long value on one line instead, truncate it with an ellipsis and make the whole value available elsewhere, such as a tooltip.
+  - Docs: https://raft-design.botiverse.build/components/description-list/
+- **ListRow** `variant="plain"` with a description: the leading icon, avatar or tile and the trailing switch, checkbox, radio, value or chevron center on the title's first line instead of the middle of the title and description. With a title alone, nothing changes. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: with a description the ends sat between the title and the description, level with neither and with no line of text.
+  - Affects: the ends move without changing size, so row heights are unchanged (54px on a phone for a one-line row with a switch).
+  - Docs: https://raft-design.botiverse.build/components/list-row/
+- **MessageListDateDivider**, **SystemMessage**, **SystemMessageGroupHeader**, **MessageListNotice**, **ThreadPanelOriginalMessage**, **ThreadPanelReplySummary** and **ThreadPanelReplyCount**: spaced on the timeline rhythm. ([#694](https://github.com/botiverse/raft-design/pull/694))
+  - Why: see Timeline rhythm above.
+  - Affects: a date line's rule sits 24px from the text above and below it (was 24px / 32px on a phone, 25px / 33px on a desktop); SystemMessage padding 12px / 12px → 12px / 4px, 16px from the text on both sides; a closed SystemMessageGroupHeader keeps the same 12px / 4px around its disclosure's text (padding 6px / 6px → 6px top and −2px bottom on a phone, 7px and −1px on a desktop), and an open one keeps its 6px under the header; MessageListNotice padding 0 / 8px → 12px / 4px; ThreadPanelOriginalMessage bottom padding 8px → 20px and ThreadPanelReplySummary top padding 8px → 12px, so the thread's rule sits 24px from the text on both sides; ThreadPanelReplyCount gains 4px above it (margin 0 / 4px → 4px / 4px). MessageItem keeps its 4px / 8px, now read from the tokens.
+  - Docs: https://raft-design.botiverse.build/foundations/spacing/#timeline-rhythm
+
+### Fixed
+
+- **Select**, **Combobox**, **ComboboxSelect** and **InputGroup**: a value cut with an ellipsis gets its full text as a `title` whenever it is cut. ([#695](https://github.com/botiverse/raft-design/pull/695))
+  - Why: the check compared whole pixels with 1px to spare, so it missed cuts of about 0.6–1.3px that still showed an ellipsis, and it did not measure again when a web font finished loading; it now compares fractional sizes and measures again after fonts load.
+  - Affects: tolerance 1px (whole pixels) → 0.5px (fractional).
+  - Docs: https://raft-design.botiverse.build/components/select/
+- **Checkbox** and **RadioGroupItem** hit areas: in a `<label>` row the box or circle reaches 4px past its line, half the 8px gap to the next option, so a tap between two options lands on the nearer one; the label is the target for the rest. On its own, its hit area is 44px tall on a touch screen. ([#686](https://github.com/botiverse/raft-design/pull/686))
+  - Why: each option's hit area reached across the gap and the next option's covered it, so a tap just under one option could select the next one.
+  - Affects: standalone touch hit area 44px tall (was 36px for a checkbox, 33px for a radio); standalone mouse hit area unchanged; in a `<label>` row the hit area is the line plus 4px above and below, for every pointer.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-control-and-its-label
+
+## [0.20.1](https://github.com/botiverse/raft-design/compare/v0.20.0...v0.20.1) (2026-10-22)
+
+### Design System
+
+- **A mark that leads text**: an icon or status light that starts a line of text is centered on the first line of that text and stays there when the text wraps or a description follows. Only the place is shared; each component keeps its own icon size and gap. A status light beside text is always 9px. It applies to Banner, PanelNotice, ToastIcon, MessageActionCardNotice, Badge and PanelActivity. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: each component placed its mark with its own fixed offset, which held for one type size and drifted at the next; one rule, the line box center (the cap-height center in Space Grotesk), now places every mark.
+  - Affects: offset `(1lh - size) / 2` on the row's own type; status light 9px with a 1.5px ink edge.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-mark-that-leads-text
+- **Popups stay on their trigger**: when the window or a pane scrolls under an open popup, the popup moves with the element that opened it. A context menu stays with the point where it was opened. It applies to SelectContent, ComboboxContent, PopoverContent, PreviewCardContent and NotificationCenterPopup. ([#669](https://github.com/botiverse/raft-design/pull/669))
+  - Why: popups stayed where they opened while the page scrolled, pointing at whatever had scrolled into place; the wrappers no longer turn Base UI's anchor tracking off.
+  - Docs: https://raft-design.botiverse.build/foundations/elevation/#popups
+
+### Added
+
+- **`lead-icon`** and **`lead-dot`** utilities: center an icon (`lead-icon`) or a `Status` light (`lead-dot`) you place yourself on the first line of the text beside it. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: a mark placed outside the components above had no way to follow the same rule except a hand-tuned margin.
+  - Affects: `lead-dot` sizes the light 9px with a 1.5px edge, so don't pass the `Status` a `size`. Both read `1lh`, so put the text's type on the row that holds the mark and the text.
+  - Docs: https://raft-design.botiverse.build/foundations/alignment/#a-mark-that-leads-text
+
+### Changed
+
+- **Status** in Banner, PanelNotice, ToastIcon, Badge and PanelActivity: held at 9px and centered on the first line, whatever `size` or vertical margin it was given. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: the same light showed at different sizes in a toast, a banner and a chip; a light beside text has one size, 9px, the least color that tells green from yellow from orange, plus its ink edges.
+  - Affects: a `Status` passed `xs` (6px), `sm` (8px) or `lg` (11px) in these components renders 9px; the `xs` edge 1px → 1.5px (its 1px corner stays). The default `md` is unchanged, as are icon sizes and gaps.
+  - Docs: https://raft-design.botiverse.build/components/status/#sizes
+
+### Fixed
+
+- **PanelNotice**: a leading status light or icon is centered on the first line of the notice's text. ([#670](https://github.com/botiverse/raft-design/pull/670), [#687](https://github.com/botiverse/raft-design/pull/687))
+  - Why: the mark sat at the top of the first line, a light 6.5px above the line's center on a desktop (5.5px on a phone) and a 16px icon 3px (2px); the notice now follows A mark that leads text.
+  - Affects: icon size and gap are unchanged (your icon's size, 10px before the text).
+  - Docs: https://raft-design.botiverse.build/components/panel/
+- **Popups**: SelectContent, ComboboxContent, PopoverContent, PreviewCardContent and NotificationCenterPopup follow their trigger while the window or a scrolling pane moves. ([#669](https://github.com/botiverse/raft-design/pull/669))
+  - Why: these wrappers turned anchor tracking off by default, so an open popup kept its opening position and drifted off its trigger as soon as anything scrolled; they now leave it to Base UI's default.
+  - Affects: `disableAnchorTracking` default `true` → unset (Base UI's default, tracking on). ContextMenuContent drops its `true` default too; it is anchored to a point, so it looks the same. Pass `disableAnchorTracking` to turn it off for one popup. Select still turns tracking off with `alignItemWithTrigger`.
+  - Docs: https://raft-design.botiverse.build/foundations/elevation/#popups
+
+## [0.20.0](https://github.com/botiverse/raft-design/compare/v0.19.0...v0.20.0) (2026-10-22)
+
+### Design System
+
+- **Hover and press**: hover and press are one translucent ink layer over the resting colour, never a fill swap, in two tiers sized by what is under the pointer. Subtle for rows, messages, readable cards and a row whose menu is open; medium for small controls and for pressing anything clickable. A colour sticker and the frame get their own medium alphas. Selected items and fields don't hover, a message has no press, and every hover sits under `(hover: hover)`. It applies to every row, card, button, badge, tab, segment, sidebar and rail item, table row, inbox item and menu. ([#681](https://github.com/botiverse/raft-design/pull/681))
+  - Why: the same hover looked different on paper, the sidebar and a card, rows and messages used three different steps, and some clickable parts gave no feedback on press; one layer in two tiers reads the same everywhere.
+  - Affects: subtle `fill-subtle` 4% light / 3% dark; medium `fill-medium` 7.8% light / 6.5% dark (was 7.8%); `sticker-medium` 10% (was 12.2%); `fill-frame-medium` 10% light (was 12.2%) / 6% dark (was 7.8%); dark `brand-soft` 16% → 20%; colour `-hover` / `-active` pairs mix 10% ink (was 12%).
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
+- **Inside a frame**: a control embedded in another component's frame (a field, the composer, a toolbar, a card or media corner) wears `radius-chip` (6px) and sits the same distance from every side of the frame and from its siblings; frames themselves don't change. It applies to ComboboxSelect, Combobox, InputGroup, the composer, the message hover and text-selection toolbars, the lightbox and multi-select bars, CodeBlock, media and file card actions, popover close, menus and SegmentedControl / ToggleGroup. ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: embedded buttons at the free-standing 8px corner read nearly round at 20px, and their offsets differed per component; one corner and one even inset make them read as one kind of thing.
+  - Affects: new tokens `control-embedded-inset` 6px and `control-embedded-size` 20px desktop / 32px phone (utilities `embedded-inset`, `control-embedded`); insets 6px in a field, the composer and a corner, 4px in a floating toolbar and for a popup's highlight, 3px between segments.
+  - Docs: https://raft-design.botiverse.build/foundations/shape/#inside-a-frame
+
+### Breaking Changes
+
+- **Dialog** `size`: `sm` is 400px (was 384) and `lg` is 640px (was 512); `md` 448 and `wide` 896 are unchanged. Sizes are chosen by content: `sm` for a decision, `md` for a small task, `lg` for content that needs width. ([#676](https://github.com/botiverse/raft-design/pull/676))
+  - Why: the steps between sizes were too small to mean anything, and a confirmation could be 384 or 400 wide depending on the component; now every confirmation is 400, the same as AlertDialog.
+  - Affects: `sm` `max-w-sm` (384px) → 400px; `lg` `max-w-lg` (512px) → 640px.
+  - Migrate: dialogs with `size="sm"` grow 16px and `size="lg"` 128px; check their content and pick the size by content. Set width with `size` only, not your own `max-w-*`.
+  - Docs: https://raft-design.botiverse.build/components/dialog/#variants
+- **Hover tokens**: renamed to their tier. The old names stay as deprecated aliases until 1.0, but they now resolve to the tier values, so some hovers change. ([#681](https://github.com/botiverse/raft-design/pull/681))
+  - Why: names that said where a fill was used (row hover, message hover, row open, pressed) could not describe two tiers that apply everywhere.
+  - Affects: `fill-row-hover`, `fill-row-open`, `fill-message-hover` → `fill-subtle` (row open 5% → 4%, message hover 3% → 4%); `fill-pressed` → `fill-medium`; `fill-frame-pressed` → `fill-frame-medium`; `sticker-pressed` → `sticker-medium`; utilities `row-hover-overlay`, `row-open-overlay` → `overlay-subtle`, `press-overlay` → `overlay-medium`, `press-overlay-sticker` → `overlay-sticker-medium`. Overlays are registered with the `cn` helper as background images, so a later `hover:bg-none` or another tier replaces them.
+  - Migrate: run `node node_modules/@botiverse/raft-ui/codemods/token-names.mjs <paths>`; it renames classes, `var(--…)` and `var(--color-…)` forms. Then move readable cards that used `press-overlay` for hover to `overlay-subtle`. Tests that assert a token name in a class (for example `var(--fill-row-open)` on a message) look for the new name.
+  - Docs: https://raft-design.botiverse.build/foundations/color/#hover-overlays
+- **MessageItemToolbar** and **MessageTextSelectionToolbar**: 36px tall (was 32), buttons 4px from the frame and 4px apart (was 2px), at `radius-chip`. The hover toolbar rides 18px above the row (was 16). ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: at a 2px inset the buttons' hover fill nearly touched the frame; see Inside a frame above.
+  - Affects: toolbar height 32 → 36px; inset and gap 2 → 4px; the message header's default reserve `--mi-toolbar-reserve` 6.5rem → 7rem (three buttons).
+  - Migrate: if you set `--mi-toolbar-reserve` yourself, compute it as `1rem + 2rem × buttons` (was `1.25rem + 1.75rem × buttons`). Leave at least 18px above the first message of a scroll area and above a thread's root message.
+  - Docs: https://raft-design.botiverse.build/components/message-item/
+- **MessageMultiSelectToolbar**: 36px tall (was 48) with 28px buttons (was 32) 4px from the frame; on a touch screen each button takes a 44px tap. The buttons go in the new `MessageMultiSelectToolbarActions`. ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: every floating toolbar is now 36px with 28px buttons; the touch hit area keeps the smaller buttons easy to tap.
+  - Affects: height 48 → 36px; buttons 32 → 28px; inset 8 / 10 → 4px; gap 6 → 4px.
+  - Migrate: wrap the toolbar's buttons in `MessageMultiSelectToolbarActions`, which owns their 4px gap and the touch hit areas; remove your own gap or padding there.
+  - Docs: https://raft-design.botiverse.build/components/message-item/
+- **ComboboxSelect**, **Combobox** and **InputGroup** chips and end buttons: chips and embedded buttons in a field are 20px on a desktop and 32px on a phone (chips were 28px, end buttons 32px), 6px from the field's edge and from each other, at `radius-chip`, so a field with chips stays 32 / 44px tall (it grew to 42). ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: 28px chips made a field with chips taller than one without, and the embedded buttons sat at different offsets per component.
+  - Affects: chips 28 → 20px desktop / 32px phone; chip remove 16 / 28px at `radius-sticker`; InputGroup end-addon Button 32 → 20 / 32px with a 16px icon; ComboboxSelect `sm` keeps 22px chips at 3px, `lg` uses 40px chips in a 52px field.
+  - Migrate: remove size, offset or radius overrides on chips and end-addon buttons in fields. In an InputGroup end addon, put a Kbd before the Button, so on a phone (Kbd hidden) the button is the last child and ends 6px from the edge.
+  - Docs: https://raft-design.botiverse.build/components/combobox-select/
+
+### Added
+
+- **CodeBlockPre**: renders the code's `pre`. While the code overflows it is a keyboard-reachable named region (`tabindex=0`, `role=region`, `aria-label` "Code" by default), so it can be scrolled from the keyboard; code that fits adds no Tab stop. ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: a scrolling code block could not be reached from the keyboard in Safari.
+  - Docs: https://raft-design.botiverse.build/components/code-block/
+- **MessageMultiSelectToolbarActions**: the multi-select toolbar's actions at its end, 4px apart, with touch hit areas. ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: see MessageMultiSelectToolbar above.
+  - Docs: https://raft-design.botiverse.build/components/message-item/
+- **Press feedback**: Badge, the mention sticker, InboxItem, Table rows, the system-message disclosure and the selected SidebarItem now press with the medium tier. ([#681](https://github.com/botiverse/raft-design/pull/681))
+  - Why: anything clickable presses with the medium tier; these gave no feedback on press.
+  - Affects: solid Badge `sticker-medium`; soft and outline Badge, InboxItem, Table row, system-message disclosure `fill-medium`; selected SidebarItem `sticker-medium`.
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
+
+### Changed
+
+- **MessageItem**, **MessageAttachmentCard**, **MessageReplies**, **TaskCard** and menu-open rows: hover with the subtle tier. ([#681](https://github.com/botiverse/raft-design/pull/681))
+  - Why: a message, a readable card and a row whose menu is open are large things people read; one subtle step keeps text contrast and never stacks with the menu-open fill.
+  - Affects: message hover 3% / 2.2% → 4% / 3%; menu-open row 5% / 4% → 4% / 3%; attachment card, replies bar and task card 7.8% → 4% / 3%. Press stays medium.
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
+- **SegmentedControl**, **ToggleGroup** and **Select**: a selected segment or toggle no longer darkens on hover and presses with `sticker-medium`; the Select trigger and the top-bar SearchTrigger don't hover, only press. SegmentedControl and ToggleGroup items are 3px apart (was 2). ([#681](https://github.com/botiverse/raft-design/pull/681), [#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: selected items and fields don't hover, like selected tabs and the active sidebar item.
+  - Affects: segment gap 2 → 3px.
+  - Docs: https://raft-design.botiverse.build/components/segmented-control/
+- **DropdownMenu**, **ContextMenu**, **Select**, **Combobox**, **ComboboxSelect**, the suggestion list and quick reactions: the highlighted item sits 4px inside the popup at `radius-chip`, and separators take 4px. ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: see Inside a frame above.
+  - Affects: highlight inset 6px (quick reactions 8px) → 4px; highlight radius 8 → 6px; separator margins 6 → 4px.
+  - Docs: https://raft-design.botiverse.build/components/dropdown-menu/
+- **CodeBlock**: the copy and other actions sit 6px from the corner at `radius-chip`, and without a header they take a column of their own instead of covering the first line; the code scrolls beside them. With a header, the actions sit 6px from its end, centred in it, 4px apart. ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: on a phone the copy button covered the first line of code.
+  - Affects: action offset 9px (no header) / 5px (header) → 6px; radius 8 → 6px; a one-line block keeps 6px under the button.
+  - Docs: https://raft-design.botiverse.build/components/code-block/
+- **Composer**, **MessageActionCard**, **Popover** header close, **Lightbox** info bar, video preview, gallery and file card actions: embedded buttons at `radius-chip`, 6px from the frame's sides (4px in the lightbox bar, whose buttons are 28px with a 44px touch target). ([#682](https://github.com/botiverse/raft-design/pull/682))
+  - Why: see Inside a frame above.
+  - Affects: composer buttons 8 / 13px from the sides and 9px from the bottom → 6px; media and file card actions 9 / 7 / 5px → 6px; lightbox buttons 32 → 28px.
+  - Docs: https://raft-design.botiverse.build/foundations/shape/#inside-a-frame
+
+### Fixed
+
+- **ComboboxSelect** and **FloatButton**: hover no longer sticks after a tap on a touch screen; their `:hover` rules are under `(hover: hover)`, and the ghost FloatButton hovers and presses with the overlay instead of a fill swap. ([#681](https://github.com/botiverse/raft-design/pull/681))
+  - Why: ungated `:hover` rules stayed applied after a tap.
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
+
 ## [0.19.0](https://github.com/botiverse/raft-design/compare/v0.18.0...v0.19.0) (2026-10-21)
 
 ### Design System
@@ -165,7 +353,7 @@
 - **Row hover**: rows hover with their own lightest visible step, not the press overlay; a row whose menu is open is marked with one slightly stronger step. ([#641](https://github.com/botiverse/raft-design/pull/641), [#643](https://github.com/botiverse/raft-design/pull/643))
   - Why: the press fill made hovered messages and list rows read as grey and heavy, and on a phone a long-press menu left no mark of which row it belonged to.
   - Affects: hover `fill-pressed` 7.8% → `fill-row-hover` 4% (dark 3%), messages `fill-message-hover` 3% (dark 2.2%), menu-open `fill-row-open` 5% (dark 4%). Press and selection are unchanged; hover stays lighter than selection.
-  - Docs: https://raft-design.botiverse.build/foundations/states/#row-hover
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
 
 ### Added
 
@@ -179,11 +367,11 @@
 - **Message, SidebarItem, List, Inbox, Search, Table and File rows**: hover with `fill-row-hover` (messages with `fill-message-hover`) instead of `fill-pressed`. ([#641](https://github.com/botiverse/raft-design/pull/641))
   - Why: see Row hover above.
   - Affects: hover background 7.8% → 4% (messages 3%).
-  - Docs: https://raft-design.botiverse.build/foundations/states/#row-hover
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
 - **Rows with a menu open** (right-click, ⋯ menu, phone long-press): take `fill-row-open` while the menu is open; selection still wins. **Comment cards** hover with `fill-row-hover`. ([#643](https://github.com/botiverse/raft-design/pull/643))
   - Why: the open menu needs one marker of which row it belongs to, including on a phone where there is no hover.
   - Affects: menu-open background `fill-row-open` 5% / 4%.
-  - Docs: https://raft-design.botiverse.build/foundations/states/#row-hover
+  - Docs: https://raft-design.botiverse.build/foundations/states/#hover-and-press
 - **Select, Combobox**: `collisionPadding` defaults to 8px. ([#642](https://github.com/botiverse/raft-design/pull/642))
   - Why: popups touched the screen edge on phones.
   - Affects: popup inset from the screen edge, 8px.

package/codemods/button-sizes.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+// Renames Button's duplicate sizes to the one they always rendered as.
+//
+//   node node_modules/@botiverse/raft-ui/codemods/button-sizes.mjs <dir-or-file>... [--dry] [--components=MyButton,…]
+//
+// `xs` and `sm` render exactly as `md`, and `icon-xs` and `icon-sm` exactly as
+// `icon-md`, so nothing on screen changes: xs, sm -> md; icon-xs, icon-sm ->
+// icon-md. The old names keep working as deprecated aliases until raft-ui 1.0,
+// so the rewrite can land at any time after upgrading.
+//
+// Needs @babel/parser, an optional peer dependency of raft-ui: install it
+// in the project you migrate (`pnpm add -D @babel/parser`).
+//
+// Each file is parsed as TypeScript and JSX (@babel/parser), so comments,
+// strings and JSX text never confuse it, and a Button anywhere is found: as a
+// child, in another component's prop (`actions={<Button …/>}`,
+// `render={<Button …/>}`), in a callback. It rewrites:
+// - the `size` of `<Button>`, of the raft-ui parts that pass `size` to a
+//   Button (BUTTON_COMPONENTS), and of the components named with
+//   `--components`, for your own wrappers: a string (`size="sm"`,
+//   `size={"sm"}`) or the strings in an expression (`size={inHead ? "sm" :
+//   "lg"}`);
+// - `icon-sm` and `icon-xs` in the `size` of any JSX element: only Button has
+//   those names;
+// - `size: "sm"` in a `buttonVariants({…})` call.
+// `sm` and `xs` are names other components use too (Dialog, Banner, Avatar,
+// Spinner …), so nothing else is touched. It then lists every `sm`, `xs`,
+// `icon-sm` and `icon-xs` string it left, with the element it belongs to, for
+// review by hand: a size kept in a variable, a wrapper you didn't name, a test.
+import { readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+let babelParse;
+
+/**
+ * @babel/parser is an optional peer dependency of raft-ui: only this codemod
+ * uses it. Look in the project being migrated first, then beside raft-ui.
+ */
+function loadParser() {
+  if (babelParse) return babelParse;
+  for (const from of [path.join(process.cwd(), "package.json"), import.meta.url]) {
+    try {
+      babelParse = createRequire(from)("@babel/parser").parse;
+      return babelParse;
+    } catch {
+      // Try the next place.
+    }
+  }
+  throw new Error(
+    "install @babel/parser to run this codemod (it parses your TSX): pnpm add -D @babel/parser",
+  );
+}
+
+/** Deprecated Button size -> the size it renders as. */
+export const BUTTON_SIZE_RENAMES = {
+  xs: "md",
+  sm: "md",
+  "icon-xs": "icon-md",
+  "icon-sm": "icon-md",
+};
+
+/** raft-ui components whose `size` is a Button size. */
+export const BUTTON_COMPONENTS = [
+  "Button",
+  "AlertDialogAction",
+  "AlertDialogCancel",
+  "AlertDialogClose",
+  "AnnouncementDialogAction",
+  "AnnouncementDialogSecondaryAction",
+  "ComposerSubmit",
+  "CopyableCodeAction",
+  "DialogClose",
+  "DrawerClose",
+  "FileAction",
+  "SidebarSectionControl",
+];
+
+const ICON_ONLY = new Set(["icon-xs", "icon-sm"]);
+const OLD = new Set(Object.keys(BUTTON_SIZE_RENAMES));
+
+function parseSource(source, file) {
+  const ext = path.extname(file);
+  const plugins =
+    ext === ".ts" || ext === ".mts" || ext === ".cts" ? ["typescript"] : ["typescript", "jsx"];
+  return loadParser()(source, {
+    sourceType: "unambiguous",
+    plugins,
+    errorRecovery: true,
+    allowReturnOutsideFunction: true,
+  });
+}
+
+/** Depth-first walk over a Babel AST, with each node's parent chain. */
+function walk(node, visit, parents = []) {
+  if (!node || typeof node.type !== "string") return;
+  visit(node, parents);
+  const next = [...parents, node];
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "extra") continue;
+    const value = node[key];
+    if (Array.isArray(value)) for (const child of value) walk(child, visit, next);
+    else if (value && typeof value.type === "string") walk(value, visit, next);
+  }
+}
+
+function elementName(name) {
+  if (!name) return "";
+  if (name.type === "JSXIdentifier") return name.name;
+  if (name.type === "JSXMemberExpression")
+    return `${elementName(name.object)}.${name.property.name}`;
+  if (name.type === "JSXNamespacedName") return `${name.namespace.name}:${name.name.name}`;
+  return "";
+}
+
+/** The string literals a `size` value can resolve to, without entering nested functions or JSX. */
+function sizeStrings(node, out = []) {
+  if (!node) return out;
+  switch (node.type) {
+    case "StringLiteral":
+      out.push(node);
+      break;
+    case "TemplateLiteral":
+      if (node.expressions.length === 0 && node.quasis.length === 1) out.push(node);
+      break;
+    case "JSXExpressionContainer":
+    case "ParenthesizedExpression":
+    case "TSAsExpression":
+    case "TSSatisfiesExpression":
+    case "TSNonNullExpression":
+      sizeStrings(node.expression, out);
+      break;
+    case "ConditionalExpression":
+      sizeStrings(node.consequent, out);
+      sizeStrings(node.alternate, out);
+      break;
+    case "LogicalExpression":
+      sizeStrings(node.left, out);
+      sizeStrings(node.right, out);
+      break;
+    default:
+      break;
+  }
+  return out;
+}
+
+const literalValue = (node) =>
+  node.type === "StringLiteral" ? node.value : node.quasis[0].value.cooked;
+
+function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0; i < index; i += 1) if (source.charCodeAt(i) === 10) line += 1;
+  return line;
+}
+
+/**
+ * Renames the deprecated sizes in one file. Returns the new source and the
+ * strings it left, as `{ line, value, where }`.
+ */
+export function migrateButtonSizes(
+  source,
+  { file = "file.tsx", components = BUTTON_COMPONENTS } = {},
+) {
+  const buttons = new Set(components);
+  const ast = parseSource(source, file);
+  const edits = new Map();
+  const rename = (literal) => {
+    const value = literalValue(literal);
+    const quote = source[literal.start];
+    edits.set(literal.start, {
+      end: literal.end,
+      text: `${quote}${BUTTON_SIZE_RENAMES[value]}${quote}`,
+    });
+  };
+  const handled = new Set();
+
+  walk(ast.program, (node) => {
+    if (node.type === "JSXOpeningElement") {
+      const name = elementName(node.name);
+      const isButton = buttons.has(name);
+      for (const attribute of node.attributes) {
+        if (attribute.type !== "JSXAttribute" || attribute.name.name !== "size") continue;
+        for (const literal of sizeStrings(attribute.value)) {
+          const value = literalValue(literal);
+          if (!OLD.has(value)) continue;
+          handled.add(literal.start);
+          if (isButton || ICON_ONLY.has(value)) rename(literal);
+        }
+      }
+    }
+    if (
+      node.type === "CallExpression" &&
+      node.callee.type === "Identifier" &&
+      node.callee.name === "buttonVariants"
+    ) {
+      for (const argument of node.arguments) {
+        if (argument.type !== "ObjectExpression") continue;
+        for (const property of argument.properties) {
+          if (property.type !== "ObjectProperty") continue;
+          const key = property.key.type === "Identifier" ? property.key.name : property.key.value;
+          if (key !== "size") continue;
+          for (const literal of sizeStrings(property.value)) {
+            if (!OLD.has(literalValue(literal))) continue;
+            handled.add(literal.start);
+            rename(literal);
+          }
+        }
+      }
+    }
+  });
+
+  // Every deprecated name still standing, and what it belongs to.
+  const left = [];
+  walk(ast.program, (node, parents) => {
+    // A test that matches the source (`/size="sm"/`) has to change with it.
+    if (node.type === "RegExpLiteral") {
+      const name = /["'](icon-)?(sm|xs)["']/.exec(node.pattern);
+      if (name) {
+        left.push({
+          line: lineOf(source, node.start),
+          value: name[0].slice(1, -1),
+          where: "a regular expression",
+        });
+      }
+      return;
+    }
+    const isString =
+      node.type === "StringLiteral" ||
+      (node.type === "TemplateLiteral" &&
+        node.expressions.length === 0 &&
+        node.quasis.length === 1);
+    if (!isString || !OLD.has(literalValue(node)) || edits.has(node.start)) return;
+    let where = "a string";
+    let prop = "";
+    for (let i = parents.length - 1; i >= 0; i -= 1) {
+      const parent = parents[i];
+      if (parent.type === "JSXAttribute" && !prop) prop = ` ${parent.name.name}`;
+      if (parent.type === "JSXOpeningElement") {
+        where = `<${elementName(parent.name)}${prop}>`;
+        break;
+      }
+      if (parent.type === "JSXElement" || parent.type === "JSXFragment") break;
+    }
+    left.push({ line: lineOf(source, node.start), value: literalValue(node), where });
+  });
+
+  let out = source;
+  for (const start of [...edits.keys()].sort((a, b) => b - a)) {
+    const { end, text } = edits.get(start);
+    out = out.slice(0, start) + text + out.slice(end);
+  }
+  return { source: out, left };
+}
+
+/** The source with the deprecated sizes renamed (see migrateButtonSizes). */
+export function renameButtonSizes(source, components = BUTTON_COMPONENTS, file = "file.tsx") {
+  return migrateButtonSizes(source, { file, components }).source;
+}
+
+const EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"]);
+const SKIP = new Set(["node_modules", "dist", "build", ".git"]);
+
+function* walkFiles(target) {
+  const stat = statSync(target);
+  if (stat.isFile()) {
+    if (EXTENSIONS.has(path.extname(target))) yield target;
+    return;
+  }
+  for (const name of readdirSync(target)) {
+    if (SKIP.has(name) || name.startsWith(".")) continue;
+    yield* walkFiles(path.join(target, name));
+  }
+}
+
+function main(argv) {
+  const dry = argv.includes("--dry");
+  const option = argv.find((arg) => arg.startsWith("--components="));
+  const components = option
+    ? [...BUTTON_COMPONENTS, ...option.slice("--components=".length).split(",").filter(Boolean)]
+    : BUTTON_COMPONENTS;
+  const targets = argv.filter((arg) => !arg.startsWith("--"));
+  if (targets.length === 0) {
+    console.error("usage: button-sizes.mjs <dir-or-file>... [--dry] [--components=MyButton,…]");
+    process.exit(1);
+  }
+  let changed = 0;
+  const review = [];
+  try {
+    loadParser();
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  const groups = new Map();
+  for (const target of targets) {
+    for (const file of walkFiles(target)) {
+      const before = readFileSync(file, "utf8");
+      if (!/["'`](?:icon-)?(?:sm|xs)["'`]/.test(before)) continue;
+      let result;
+      try {
+        result = migrateButtonSizes(before, { file, components });
+      } catch (error) {
+        review.push(`${file}: could not parse (${error.message}); not changed`);
+        continue;
+      }
+      for (const { line, value, where } of result.left) {
+        review.push(`${file}:${line}  "${value}" in ${where}`);
+        groups.set(where, (groups.get(where) ?? 0) + 1);
+      }
+      if (result.source === before) continue;
+      changed += 1;
+      console.log(`${dry ? "would update" : "updated"} ${file}`);
+      if (!dry) writeFileSync(file, result.source);
+    }
+  }
+  console.log(`${changed} file${changed === 1 ? "" : "s"} ${dry ? "to update" : "updated"}`);
+  if (review.length > 0) {
+    console.log(
+      "\nLeft as they are; check each by hand (another component's size, a variable, your own wrapper).",
+    );
+    console.log("\nBy element and prop:");
+    for (const [where, count] of [...groups].sort((a, b) => b[1] - a[1])) {
+      console.log(`  ${String(count).padStart(4)}  ${where}`);
+    }
+    console.log("\nEach one:");
+    for (const where of review) console.log(`  ${where}`);
+  }
+}
+
+// Run only when invoked directly (see token-names.mjs: pnpm installs through
+// symlinks, so compare real paths).
+function isInvokedDirectly() {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isInvokedDirectly()) main(process.argv.slice(2));

package/codemods/token-names.mjs

@@ -32,6 +32,12 @@ export const TOKEN_RENAMES = {
   "theme-shadow-sticker": "elevation-sticker",
   "theme-focus-ring": "focus-ring",
   "soft-signal": "palette-yellow",
+  "fill-pressed": "fill-medium",
+  "fill-frame-pressed": "fill-frame-medium",
+  "fill-row-hover": "fill-subtle",
+  "fill-row-open": "fill-subtle",
+  "fill-message-hover": "fill-subtle",
+  "sticker-pressed": "sticker-medium",
 };
 
 /** Families renamed with every step: `primary-soft` -> `brand-soft`. */
@@ -61,6 +67,10 @@ export const UTILITY_RENAMES = {
   "shadow-raft-xl": "shadow-float",
   "shadow-raft-sticker": "shadow-sticker",
   "shadow-raft-focus": "shadow-focus",
+  "press-overlay": "overlay-medium",
+  "press-overlay-sticker": "overlay-sticker-medium",
+  "row-hover-overlay": "overlay-subtle",
+  "row-open-overlay": "overlay-subtle",
 };
 
 const COLOR_UTILITY =
@@ -83,6 +93,8 @@ function rules() {
   for (const [from, to] of tokens) {
     list.push([new RegExp(`(?<![\\w-])(${COLOR_UTILITY})-${escape(from)}${END}`, "g"), `$1-${to}`]);
     list.push([new RegExp(`${VAR}${escape(from)}${REF_END}`, "g"), `--${to}`]);
+    // The Tailwind theme variable of the same token: `var(--color-fill-pressed)`.
+    list.push([new RegExp(`${VAR}color-${escape(from)}${REF_END}`, "g"), `--color-${to}`]);
   }
   for (const [from, to] of Object.entries(FAMILY_RENAMES)) {
     list.push([
@@ -90,6 +102,10 @@ function rules() {
       `$1-${to}$2`,
     ]);
     list.push([new RegExp(`${VAR}${from}((?:-[a-z0-9]+)*)${REF_END}`, "g"), `--${to}$1`]);
+    list.push([
+      new RegExp(`${VAR}color-${from}((?:-[a-z0-9]+)*)${REF_END}`, "g"),
+      `--color-${to}$1`,
+    ]);
   }
   for (const [from, to] of Object.entries(PALETTE_COLORS)) {
     list.push([