@sableui/react 0.14.0 → 0.16.0

package/dist/themes/verdant/verdant.css

@@ -128,6 +128,15 @@
 	--tone-warning: oklch(53% 0.12 65);
 	--tone-warning-text: oklch(51% 0.12 65); /* a step under the fill: 53% is 4.44:1 as text on muted */
 	--tone-warning-foreground: oklch(98.6% 0.004 106);
+	/* Graphic strength (MARK_TOKENS): meters, bars, dots, chart series and soft tints.
+	   The same hues lifted and saturated; held to 2:1 on the page, not a text ratio. */
+	--theme-destructive-mark: oklch(62.0% 0.244 22.0);
+	--theme-success-mark: oklch(70.0% 0.131 173.0);
+	--theme-tone-warning-mark: oklch(71.0% 0.156 65.0);
+	--theme-tone-info-mark: oklch(63.0% 0.156 250.0);
+	--theme-tone-1-mark: oklch(70.0% 0.131 173.0);
+	--theme-tone-2-mark: oklch(70.0% 0.091 175.0);
+	--theme-tone-3-mark: oklch(60.0% 0.018 175.0);
 	--highlight: oklch(90% 0.05 100);
 	--highlight-foreground: oklch(24% 0.035 175);
 	--overlay: oklch(16% 0.03 175 / 0.6);
@@ -209,6 +218,15 @@
 	--tone-warning: oklch(80% 0.13 75);
 	--tone-warning-text: oklch(80% 0.13 75);
 	--tone-warning-foreground: oklch(16% 0.03 175);
+	/* Graphic strength (MARK_TOKENS): meters, bars, dots, chart series and soft tints.
+	   The same hues lifted and saturated; held to 2:1 on the page, not a text ratio. */
+	--theme-destructive-mark: oklch(65.0% 0.218 22.0);
+	--theme-success-mark: oklch(74.0% 0.139 173.0);
+	--theme-tone-warning-mark: oklch(80.0% 0.149 75.0);
+	--theme-tone-info-mark: oklch(76.0% 0.125 250.0);
+	--theme-tone-1-mark: oklch(76.0% 0.137 173.0);
+	--theme-tone-2-mark: oklch(74.0% 0.103 175.0);
+	--theme-tone-3-mark: oklch(72.0% 0.015 175.0);
 	--highlight: oklch(40% 0.06 90);
 	--highlight-foreground: oklch(98.6% 0.004 106);
 	--overlay: oklch(8% 0.015 175 / 0.7);

package/llms/blocks/message-reactions-block.md

@@ -0,0 +1,116 @@
+# MessageReactionsBlock
+
+A short thread you can react to: right-click or long-press a bubble for a menu with a row of quick reactions above Reply and Copy, or use the add-reaction pill under a message. A new reaction blooms in and sprays copies of its emoji.
+
+**Intent:** Reach for this when a conversation excerpt should be reactable — a team thread, a comment card, a support transcript. A read-only excerpt is ChatThreadBlock; a working chat with a composer and history is the ChatPanel page shell.
+
+**Block:** Social & messaging · card · designed for 18rem–24rem wide (fills its container up to the max)
+
+## Notes
+
+- Two ways in, on purpose: the right-click / long-press menu is fast once you know it is there, and the add-reaction pill is how a first-time reader finds reactions at all.
+- The quick row in the menu is MenuReactions (checkbox menu items) and the one in the pill's popover is ReactionPicker (a toolbar), so each is reachable by the keyboard model of the surface it sits in.
+- Only the reader's own reaction celebrates. Counts from other people roll quietly, and the reactions a page loads with never play.
+- The add-reaction pill appears only on messages that already have reactions; a message with none is reacted to from its menu, which keeps quiet rows quiet.
+
+## Accessibility
+
+- Each bubble is focusable, and its menu opens on right click, long press, Shift+F10 or the Menu key; its reactions are checkbox items reporting whether the reader has used each one.
+- Each reaction pill is a toggle named by its meaning and count ("Party, 3") with `aria-pressed`; the emoji and the burst are hidden from assistive tech.
+- Under reduced motion the reaction appears and the count changes at once; nothing else is lost.
+
+## Source
+
+```tsx
+import { Bubble, BubbleReaction, BubbleReactionAdd, BubbleReactions, Card, CardContent, CardFooter, cn, ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger, DEFAULT_REACTIONS, MenuReactions, Message } from "@sableui/react"
+
+const messages: { id: string; text: string; mine: boolean; reactions: Record<string, number> }[] = [
+	{ id: "m1", text: "The new onboarding flow is live on staging 🚀", mine: false, reactions: { "🎉": 2, "👀": 1 } },
+	{ id: "m2", text: "Clicked through it twice. The progress bar is so smooth.", mine: true, reactions: {} },
+	{ id: "m3", text: "Ship it Friday?", mine: false, reactions: { "👍": 1 } },
+]
+const hint = "Right-click or long-press a message to react."
+// Every emoji that can appear needs a name: it is the pill's accessible label.
+const labels: Record<string, string> = {
+	...Object.fromEntries(DEFAULT_REACTIONS.map((r) => [r.emoji, r.label])),
+	"👀": "Eyes",
+}
+
+export interface MessageReactionsBlockProps {
+	className?: string
+	/** false drops the card's surface and border. Keep it framed on a muted page: incoming bubbles are the muted surface too. */
+	framed?: boolean
+	/** Called when the reader adds or removes a reaction, with the message, the emoji and whether it is now on. */
+	onReact?: (messageId: string, emoji: string, on: boolean) => void
+}
+
+export function MessageReactionsBlock({ className, framed = true, onReact }: MessageReactionsBlockProps) {
+	// The reader's own reactions, per message. Everyone else's are the counts above.
+	const [mine, setMine] = useState<Record<string, string[]>>({ m1: ["🎉"] })
+	const toggle = (messageId: string, emoji: string) => {
+		const on = !(mine[messageId] ?? []).includes(emoji)
+		// Decided again from `prev`, so two toggles in one batch cannot add an emoji twice.
+		setMine((prev) => {
+			const current = prev[messageId] ?? []
+			const next = current.includes(emoji) ? current.filter((e) => e !== emoji) : [...current, emoji]
+			return { ...prev, [messageId]: next }
+		})
+		onReact?.(messageId, emoji, on)
+	}
+
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-sm", className)}>
+			<CardContent className="flex flex-col gap-3">
+				{messages.map((m) => {
+					const align = m.mine ? "end" : "start"
+					const chosen = mine[m.id] ?? []
+					// Others' counts, plus the reader's own: a reaction only the reader gave
+					// is a pill of its own, ordered after the ones already there.
+					const counts: Record<string, number> = { ...m.reactions }
+					for (const emoji of chosen) counts[emoji] = (counts[emoji] ?? 0)
+					const pills = Object.entries(counts).map(([emoji, others]) => ({
+						emoji,
+						active: chosen.includes(emoji),
+						count: others + (chosen.includes(emoji) ? 1 : 0),
+					}))
+					return (
+						<Message key={m.id} messageId={m.id} align={m.mine ? "end" : undefined}>
+							<ContextMenu>
+								<ContextMenuTrigger
+									// Focusable, so Shift+F10 or the Menu key opens the same menu.
+									render={<Bubble tabIndex={0} variant={m.mine ? "primary" : undefined} align={align} />}
+								>
+									{m.text}
+								</ContextMenuTrigger>
+								<ContextMenuContent>
+									<MenuReactions selected={chosen} onSelect={(emoji) => toggle(m.id, emoji)} />
+									<ContextMenuSeparator />
+									<ContextMenuItem>Reply</ContextMenuItem>
+									<ContextMenuItem>Copy text</ContextMenuItem>
+								</ContextMenuContent>
+							</ContextMenu>
+							{/* Rendered even while empty (it hides itself), so the first reaction still celebrates. */}
+							<BubbleReactions align={align}>
+								{pills.map((p) => (
+									<BubbleReaction
+										key={p.emoji}
+										emoji={p.emoji}
+										label={labels[p.emoji]}
+										count={p.count}
+										active={p.active}
+										onClick={() => toggle(m.id, p.emoji)}
+									/>
+								))}
+								{pills.length > 0 ? (
+									<BubbleReactionAdd selected={chosen} onSelect={(emoji) => toggle(m.id, emoji)} />
+								) : null}
+							</BubbleReactions>
+						</Message>
+					)
+				})}
+			</CardContent>
+			<CardFooter className="text-caption text-muted-foreground">{hint}</CardFooter>
+		</Card>
+	)
+}
+```

package/llms/blocks/wallet-block.md

@@ -28,7 +28,10 @@ const activity = [
 	{ title: "Subscription", detail: "Team plan · 2h ago", amount: "+49.00", tone: "1" },
 	{ title: "Refund", detail: "Order 1042 · Yesterday", amount: "-24.00", tone: "2" },
 	{ title: "Payout", detail: "To checking · Mon", amount: "-850.00", tone: "3" },
-]
+] as const
+
+/** Each row's mark: its tone at graphic strength, which every theme tunes. */
+const TONE_MARK = { "1": "bg-tone-1-mark", "2": "bg-tone-2-mark", "3": "bg-tone-3-mark" } as const
 
 export interface WalletBlockProps {
 	className?: string
@@ -62,9 +65,7 @@ export function WalletBlock({ className, framed = true, onSend, onReceive }: Wal
 							leading={
 								<span
 									aria-hidden
-									className="block size-8 rounded-full"
-									// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
-									style={{ background: `oklch(from var(--tone-${item.tone}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h)` }}
+									className={cn("block size-8 rounded-full", TONE_MARK[item.tone])}
 								/>
 							}
 							title={item.title}

package/llms/components/app-shell.md

@@ -4,7 +4,7 @@
 
 The application frame: slots for status banners, a mobile header, a desktop sidebar, main content, a mobile bottom nav, a persistent dock (a now-playing or call bar), and floating overlays — plus a built-in skip link and #main-content target.
 
-**Keywords:** app shell, layout, frame, sidebar, header, bottom nav, mobile, banners, main, dock, player bar, now playing, persistent
+**Keywords:** app shell, layout, frame, sidebar, header, bottom nav, mobile, banners, main, dock, player bar, now playing, persistent, inset, inset frame, floating panel, rounded content, scroll container
 
 ## Usage
 
@@ -16,7 +16,10 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 - Do: Pass app-wide outage or status messages through banners so they remain above the frame.
 - Do: Use Region inside the main content to choose each route's reading width.
 - Do: Wrap EVERY return of a route in its own Page or Region — including early returns for loading, empty and error states. AppShell's <main> deliberately carries no padding (it is a frame, and padding belongs to the region that chose the width), so a route that returns a bare spinner or error renders flush against the chrome. This is the most common conversion bug: the happy path gets a Page, the three early returns do not.
+- Do: Use frame="inset" for dense, multi-pane product apps — a CRM, an issue tracker, an AI workspace — where framing the content as one raised panel on the rail's ground helps it read as the workspace and the rail as chrome. Keep the Sidebar on surface="rail" so its tint is the ground. Inset moves the page scroll from the window to <main id="main-content"> on desktop: point scroll listeners, scroll restoration and scroll-to-top at that element, not window.
 - Don't: Nest AppShell inside route cards or panels. It is page chrome, not local content.
+- Don't: Wrap a route in its own h-full overflow-y-auto box inside an inset shell. main is already the page's scroll container; a second one traps the scrollbar inside a smaller box and breaks sticky headers and the skip link's scroll target. Scroll a genuinely separate pane (a list beside a detail view) with Scroller. → use **Scroller**
+- Don't: Combine frame="inset" with a full-width header bar above the rail. The inset ground is the rail running the full height of the window; a bar across the top cuts it off. Use the flush frame with Sidebar surface="page" for that layout.
 - Don't: Put desktop-only navigation in the mobile header slot or mobile-only controls in the sidebar slot.
 
 ### Anatomy
@@ -26,7 +29,7 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 | Banners | no | Full-width app status messages rendered above the shell. |
 | Header | no | Mobile top chrome, usually AppHeader. |
 | Sidebar | no | Desktop navigation chrome, usually Sidebar. |
-| Main | yes | The route content landmark with id main-content. |
+| Main | yes | The route content landmark with id main-content. With frame="inset", from lg it is a rounded, bordered panel that scrolls inside itself. |
 | Bottom nav | no | Mobile fixed navigation with reserved bottom space. |
 | Dock | no | Persistent bottom chrome that outlives routes — a now-playing bar, a call bar. Sticky above the bottom nav; the desktop Sidebar shortens to clear it. |
 
@@ -46,10 +49,11 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 | bottomNav | ReactNode | — | Mobile bottom navigation (e.g. BottomNav); fixed to the bottom edge. main reserves space for it. |
 | dock | ReactNode | — | Persistent chrome kept on screen across routes (a now-playing bar, an active-call bar, an upload tray). Full width, sticky to the bottom edge and above bottomNav on mobile; its height is published as --dock-height and the app Sidebar subtracts it. In flow, so main needs no reserved space. The contents paint their own surface and top border, and name themselves (e.g. <section aria-label="Player">). Mount AppShell in a layout that survives navigation, or the playback restarts. |
 | overlays | ReactNode | — | Floating overlays — a message launcher, FAB, or modal mount points. |
+| frame | "flush" \| "inset" | "flush" | How the desktop frame (lg and up) holds the content; below lg both are the same mobile layout with page scroll. "flush": main sits on the page beside the rail and the document scrolls. "inset": the shell fills the viewport and paints the shell-ground token (one step off the rail's surface, tunable with --theme-shell-ground) behind the rail and around the panel; main becomes a rounded-lg panel with a hairline border and shadow-sm, inset by a spacing step from the window edges, that scrolls inside itself (scrollbar-quiet) while the rail stays put. The Sidebar in the sidebar slot drops its right border and fills the row. main stays the #main-content target (tabIndex -1, so the skip link lands focus in the scroller) and the inline-size query container; sticky children stick to the panel's top; banners and the dock stay in flow, so the panel's bottom gap sits above a dock. With Sidebar surface="page" the ground is the page colour and the panel's border alone lifts it. |
 
 ## Tokens used
 
-`background`, `foreground`, `primary`, `primary-foreground`
+`background`, `foreground`, `primary`, `primary-foreground`, `sidebar`, `shell-ground`, `border`
 
 ## Accessibility
 
@@ -57,6 +61,7 @@ Use AppShell as the outer product frame for authenticated or app-like experience
 - Wraps content in a <main id="main-content"> landmark.
 - Slot components own their own ARIA (nav landmarks, labels).
 - The dock follows <main> in DOM order, so keyboard and screen-reader users reach the player after the page content, not before it.
+- With frame="inset", <main> is the desktop scroll container and takes tabIndex -1: the skip link moves focus into it, so PageDown and the arrow keys scroll the content, without adding a tab stop.
 
 ## Related
 
@@ -96,6 +101,70 @@ import { AppHeader, AppShell, Banner, BottomNav, BottomNavItem, Icon, PageHeader
 </AppShell>
 ```
 
+### Inset frame
+
+```tsx
+import { AppHeader, AppShell, BottomNav, BottomNavItem, Button, Card, CardContent, Icon, Page, PageHeader, Sidebar, SidebarBrand, SidebarHeader, SidebarItem, SidebarNav, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<AppShell
+  frame="inset"
+  header={<AppHeader title="Pipeline" />}
+  sidebar={
+    <Sidebar>
+      <SidebarHeader>
+        <SidebarBrand mark={<Icon name="gem" variant="solid" />} label="Relay" render={<Link to="/" />} />
+      </SidebarHeader>
+      <SidebarNav>
+        <SidebarItem icon={<Icon name="inbox" />} label="Inbox" render={<Link to="/inbox" />} />
+        <SidebarItem icon={<Icon name="user" />} label="People" active render={<Link to="/people" />} />
+        <SidebarItem icon={<Icon name="folder" />} label="Companies" render={<Link to="/companies" />} />
+      </SidebarNav>
+    </Sidebar>
+  }
+  bottomNav={
+    <BottomNav>
+      <BottomNavItem icon={<Icon name="inbox" />} label="Inbox" render={<Link to="/inbox" />} />
+      <BottomNavItem icon={<Icon name="user" />} label="People" active render={<Link to="/people" />} />
+      <BottomNavItem icon={<Icon name="folder" />} label="Companies" render={<Link to="/companies" />} />
+    </BottomNav>
+  }
+>
+  <Page max="wide" gap={4} className="py-6">
+    <PageHeader
+      title="People"
+      description="Everyone in your pipeline, newest first."
+      actions={<Button><Icon name="plus" />Add person</Button>}
+    />
+    <Card>
+      <CardContent flush>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead>Name</TableHead>
+              <TableHead>Company</TableHead>
+              <TableHead numeric>Deals</TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            <TableRow>
+              <TableCell>Ada Lovelace</TableCell>
+              <TableCell>Northwind</TableCell>
+              <TableCell numeric>4</TableCell>
+            </TableRow>
+            <TableRow>
+              <TableCell>Grace Hopper</TableCell>
+              <TableCell>Harbor Labs</TableCell>
+              <TableCell numeric>2</TableCell>
+            </TableRow>
+          </TableBody>
+        </Table>
+      </CardContent>
+    </Card>
+  </Page>
+</AppShell>
+```
+
 ### SkipLink in a layout of your own
 
 ```tsx

package/llms/components/area-chart.md

@@ -45,7 +45,7 @@ Use AreaChart for volume over time — visitors, revenue, usage — where the fi
 
 ## Tokens used
 
-`tone-1`, `tone-2`, `tone-3`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+`tone-1`, `tone-2`, `tone-3`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`, `tone-warning-mark`, `tone-info-mark`, `tone-1-mark`, `tone-2-mark`, `tone-3-mark`
 
 ## Motion
 

package/llms/components/attachment.md

@@ -52,7 +52,7 @@ The card a file takes in a conversation — in the composer while it uploads, an
 
 ## Tokens used
 
-`card`, `border`, `border-strong`, `muted`, `muted-foreground`, `foreground`, `destructive`, `overlay`, `overlay-foreground`, `ring`
+`card`, `border`, `border-strong`, `muted`, `muted-foreground`, `foreground`, `destructive`, `overlay`, `overlay-foreground`, `ring`, `destructive-mark`
 
 ## Motion
 

package/llms/components/badge.md

@@ -46,7 +46,7 @@ Use Badge for any short static label: metadata, categories, tone-coded labels, a
 
 ## Tokens used
 
-`palette-wash`, `palette-wash-strong`, `palette-edge`, `palette-dot`, `palette-solid`, `palette-text`, `palette-solid-ink`, `secondary`, `secondary-foreground`, `border`, `foreground`, `background`, `muted`, `muted-foreground`, `tone-1`, `tone-2`, `tone-3`, `tone-info`, `success`, `tone-warning`, `destructive`, `overlay`, `overlay-foreground`, `tone-1-foreground`, `tone-2-foreground`, `tone-3-foreground`, `tone-info-foreground`, `success-foreground`, `tone-warning-foreground`, `destructive-foreground`
+`palette-wash`, `palette-wash-strong`, `palette-edge`, `palette-dot`, `palette-solid`, `palette-text`, `palette-solid-ink`, `secondary`, `secondary-foreground`, `border`, `foreground`, `background`, `muted`, `muted-foreground`, `tone-1`, `tone-2`, `tone-3`, `tone-info`, `success`, `tone-warning`, `destructive`, `overlay`, `overlay-foreground`, `tone-1-foreground`, `tone-2-foreground`, `tone-3-foreground`, `tone-info-foreground`, `success-foreground`, `tone-warning-foreground`, `destructive-foreground`, `destructive-mark`, `success-mark`, `tone-warning-mark`, `tone-info-mark`, `tone-1-mark`, `tone-2-mark`, `tone-3-mark`
 
 ## Accessibility
 

package/llms/components/banner.md

@@ -47,7 +47,7 @@ Use Banner for page-level or app-level messages that affect the current experien
 
 ## Tokens used
 
-`secondary`, `secondary-foreground`, `foreground`, `background`, `tone-info`, `tone-info-foreground`, `success`, `success-foreground`, `tone-warning`, `tone-warning-foreground`, `tone-1`, `tone-1-foreground`, `destructive`, `destructive-foreground`
+`secondary`, `secondary-foreground`, `foreground`, `background`, `tone-info`, `tone-info-foreground`, `success`, `success-foreground`, `tone-warning`, `tone-warning-foreground`, `tone-1`, `tone-1-foreground`, `destructive`, `destructive-foreground`, `destructive-mark`, `success-mark`, `tone-warning-mark`, `tone-info-mark`, `tone-1-mark`
 
 ## Accessibility
 

package/llms/components/bar-chart.md

@@ -49,7 +49,7 @@ Use BarChart to compare amounts across categories — the default chart for "how
 
 ## Tokens used
 
-`tone-1`, `tone-2`, `tone-3`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+`tone-1`, `tone-2`, `tone-3`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`, `tone-warning-mark`, `tone-info-mark`, `tone-1-mark`, `tone-2-mark`, `tone-3-mark`
 
 ## Motion
 

package/llms/components/bubble.md

@@ -28,14 +28,16 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 | --- | --- | --- |
 | Bubble | yes | The surface itself. Holds the variant, the side, and the tail. |
 | BubbleReactions | no | The row of reaction pills, just under the bubble at the message column's small gap, so it reads as belonging to that message rather than the next row. |
-| BubbleReaction | no | One reaction pill — emoji, count (hidden at 1), and pressed state. |
+| BubbleReaction | no | One reaction pill — emoji, count (hidden at 1), and pressed state. Celebrates when it becomes the reader's own. |
+| BubbleReactionAdd | no | The add-reaction pill at the end of the row: opens a ReactionPicker above it. |
 
 ## Subcomponents
 
 | Name | Type | Description |
 | --- | --- | --- |
 | BubbleReactions | { align?: "start" \| "end" } & ComponentPropsWithRef<"div"> | Row container for reaction pills. Match `align` to the Bubble so the row hangs off the same edge. |
-| BubbleReaction | { emoji: ReactNode; count?: number; active?: boolean } & ComponentPropsWithRef<"button"> | One reaction pill. A toggle, not a label: `active` drives `aria-pressed` as well as the styling, and `count` is hidden at 1 because the pill already says "one". |
+| BubbleReaction | { emoji: ReactNode; label?: string; count?: number; active?: boolean; motion?: MotionLevel } & ComponentPropsWithRef<"button"> | One reaction pill. A toggle, not a label: `active` drives `aria-pressed` as well as the styling, `label` names it ("Party, 3"), and `count` is hidden at 1 because the pill already says "one". When it turns on — pressed, or newly added already on — the emoji blooms, copies of it burst out and the count rolls; pills the page loads with stay still. |
+| BubbleReactionAdd | { reactions?: Reaction[]; selected?: string[]; onSelect?: (emoji: string) => void; label?: string; motion?: MotionLevel } & ComponentPropsWithRef<"button"> | The add-reaction pill: a smiley that opens a ReactionPicker above it. Choosing an emoji closes the picker and calls `onSelect`; add the emoji to the row and its new pill celebrates on arrival. |
 
 ## Props
 
@@ -56,16 +58,23 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 
 `muted`, `foreground`, `primary`, `primary-foreground`, `border`, `card`, `card-foreground`, `accent`, `accent-foreground`, `muted-foreground`, `ring`
 
+## Motion
+
+- **arrival** · Bubble · _no motion_ — A bubble arrives with its Message row, which owns how a new message enters the transcript. A reaction pill that the reader just added arrives with its own celebration (below).
+- **response** · BubbleReaction · `motion-bloom` — Reacting is the reader's choice, so it is answered like a like: the emoji grows from nothing past its size and settles, while copies of it spray outward and fade (Burst with the emoji as its particle, the way chat apps answer a reaction). Plays when a pill turns on and when a pill mounts already on into a row that has rendered — never for the pills a page loads with. Pills inherit Pill's motion-interactive and motion-press.
+- **transition** · BubbleReaction · _custom (outside the recipe layer)_ — The count rolls with NumberTicker as people react. Turning a reaction off is quiet: the tint eases out and the count rolls back, with no burst. Under `subtle` or reduced motion the bloom and the spray are dropped and the tint and count alone answer.
+- **activity** · Bubble · _no motion_ — A bubble is static content; a message still being written is StreamingText or a Marker, not a state of the surface.
+
 ## Accessibility
 
 - The surface is a plain container with no imposed role — a bubble is presentation, and announcing one as a region would put a landmark around every line of a conversation.
-- Reaction pills are real buttons reporting `aria-pressed`, so the reader's own reaction is state rather than colour alone; the emoji is hidden from AT and the count is left readable.
+- Reaction pills are real buttons reporting `aria-pressed`, so the reader's own reaction is state rather than colour alone. Give each a `label`: it is named "Party, 3", with the emoji and its burst hidden from AT. The add-reaction pill is named "Add reaction" and opens a toolbar picker.
 - `whitespace-pre-wrap` and `break-words` keep pasted logs, long URLs, and hard-wrapped text inside the surface instead of overflowing the conversation.
 - Every variant meets AA against its own surface, including `primary`, which pairs the primary fill with its paired foreground token rather than a hardcoded white.
 
 ## Related
 
-- Components: Message, MessageScroller, Marker, Attachment
+- Components: Message, MessageScroller, Marker, Attachment, ReactionPicker
 
 ## Examples
 
@@ -96,13 +105,14 @@ import { Avatar, Bubble, CodeBlock, Message } from "@sableui/react"
 ### With reactions
 
 ```tsx
-import { Bubble, BubbleReaction, BubbleReactions, Message } from "@sableui/react"
+import { Bubble, BubbleReaction, BubbleReactionAdd, BubbleReactions, Message } from "@sableui/react"
 
 <Message messageId="m3">
 	<Bubble>Shipped 0.45.0.</Bubble>
 	<BubbleReactions>
-		<BubbleReaction emoji="🎉" count={3} active onClick={() => toggle("🎉")} />
-		<BubbleReaction emoji="👀" count={1} onClick={() => toggle("👀")} />
+		<BubbleReaction emoji="🎉" label="Party" count={3} active onClick={() => toggle("🎉")} />
+		<BubbleReaction emoji="👀" label="Eyes" count={1} onClick={() => toggle("👀")} />
+		<BubbleReactionAdd selected={mine} onSelect={toggle} />
 	</BubbleReactions>
 </Message>
 ```

package/llms/components/chat-composer.md

@@ -67,7 +67,7 @@ Pairs with MessageScroller to make a working chat. A single surface rather than
 
 ## Tokens used
 
-`card`, `input`, `ring`, `destructive`, `foreground`, `muted-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`
+`field`, `field-border`, `ring`, `destructive`, `foreground`, `muted-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`
 
 ## Motion
 

package/llms/components/combobox.md

@@ -56,13 +56,14 @@ Use Combobox when users choose from a list that benefits from typing, filtering,
 | items | readonly any[] \| readonly ComboboxItemGroup[] | — | The pool of options, flat or grouped ({ value, items }). Drives type-to-filter and is required for ComboboxEmpty to render its fallback. |
 | multiple | boolean | false | Select several items instead of one. `value` / `defaultValue` / `onValueChange` become arrays, choosing an item toggles its membership, and the popup stays open between picks. Pair it with ComboboxChips in place of ComboboxInput; every other part is unchanged. |
 | filter | null \| ((item, query, itemToString?) => boolean) | Base UI's locale-aware contains | How items match the query. `null` turns matching off, for items a server already filtered: pair it with `onInputValueChange` to fetch. |
+| highlightMatches | boolean | true | Paints the typed text wherever it appears in a row's label, on the `highlight` / `highlight-foreground` pair, through the CSS Custom Highlight API — no `<mark>` in the row, and the accessible name is unchanged. Only typed text counts: a field still holding the selected item's label lists everything and lights nothing. A literal, case-insensitive match within the label; a `filter` that matches differently leaves rows it kept unpainted. `false` turns it off. |
 | onInputValueChange | (inputValue: string, eventDetails) => void | — | Fires as the reader types. The place to fetch results for a server-backed combobox. |
 | itemToStringLabel | (item) => string | item.label for { value, label } items | The text an object item shows in the input once chosen, and is matched by. Needed for object items without a `label` field. |
 | virtualized | boolean | false | Tells Base UI the DOM holds only part of the list. Required when using ComboboxVirtualList. |
 
 ## Tokens used
 
-`input`, `card`, `foreground`, `muted-foreground`, `ring`, `destructive`, `popover`, `popover-foreground`, `border`, `accent`, `accent-foreground`, `primary`, `secondary`, `secondary-foreground`
+`highlight`, `highlight-foreground`, `field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`, `popover`, `popover-foreground`, `border`, `accent`, `accent-foreground`, `primary`, `secondary`, `secondary-foreground`
 
 ## Motion
 

package/llms/components/command-menu.md

@@ -40,7 +40,7 @@ Use CommandMenu for global or contextual keyboard-driven actions: navigation, cr
 
 | Name | Type | Description |
 | --- | --- | --- |
-| CommandMenuTrigger | { onOpen?: () => void; placeholder?: string; shortcut?: string \| false; size?: "sm" \| "md"; disabled?: boolean } | The search field in a header that is really a button. Wears SearchInput's shell (border-input, card surface, leading magnifier, muted placeholder) on the control ladder, with a trailing Kbd: ⌘K on macOS, Ctrl K elsewhere. onOpen runs on click and on the shortcut, which it listens for page-wide (useCommandMenuShortcut). shortcut is the key (default "k"); false drops both the hint and the listener. size is sm in a header beside small buttons, md (default) beside Input and SearchInput. It sits outside CommandMenu, so the Dialog returns focus to it on close. |
+| CommandMenuTrigger | { onOpen?: () => void; placeholder?: string; shortcut?: string \| false; size?: "sm" \| "md"; disabled?: boolean } | The search field in a header that is really a button. Wears SearchInput's shell (the field fill and outline, leading magnifier, muted placeholder) on the control ladder, with a trailing Kbd: ⌘K on macOS, Ctrl K elsewhere. onOpen runs on click and on the shortcut, which it listens for page-wide (useCommandMenuShortcut). shortcut is the key (default "k"); false drops both the hint and the listener. size is sm in a header beside small buttons, md (default) beside Input and SearchInput. It sits outside CommandMenu, so the Dialog returns focus to it on close. |
 | useCommandMenuShortcut | (onShortcut: (event: KeyboardEvent) => void, key?: string \| false) => void | The page-wide ⌘K / Ctrl+K listener CommandMenuTrigger installs, for a palette with no visible trigger. Ignored while focus is in a text field, textarea, select or contenteditable (Ctrl+K belongs to the field there) except the palette's own input, so the callback may toggle. It calls preventDefault() on a match and skips an event already prevented, so two listeners on one page fire once. key defaults to "k"; false turns it off. Removed on unmount. |
 | CommandMenuPanel | { items?: CommandItem[]; query?: string; onQueryChange?: (query: string) => void; filter?: CommandFilter; listClassName?: string; placeholder?: string; emptyMessage?: string; title?: string; scope?: ReactNode; inputProps?: ComponentProps<'input'>; className?: string; children?: ReactNode } | The palette rendered in place: the same search header, filtered and grouped listbox, keyboard model and result-count live region, on a static card (border-border, bg-card, no shadow) instead of in a Dialog. Takes every CommandMenu prop except open, onOpenChange, finalFocus and description; className lands on the card, title names the listbox. Focus is not trapped and the input does not take focus on mount (inputProps.autoFocus opts in). Esc clears the query, and passes through once it is empty, so a Popover around the panel still closes. A chosen row runs its onSelect and the panel stays as it was. The page-wide shortcut does not fire from its input. |
 | CommandMenuGroup | { label: string; children } | A labelled group of command rows. |
@@ -58,6 +58,7 @@ Use CommandMenu for global or contextual keyboard-driven actions: navigation, cr
 | query | string | — | Controlled query. Leave undefined to let the palette own it; either way it resets on close (a controlled caller gets onQueryChange('')). |
 | onQueryChange | (query: string) => void | — | Called on every query change. Required to control query, optional otherwise. |
 | filter | ((items: CommandItem[], query: string) => CommandItem[]) \| null | case-insensitive substring match on label | Replaces or disables the built-in match. A function ranks and filters items itself and its order is kept verbatim; null renders items exactly as given. Either also stops declarative CommandMenuItem children self-filtering. The query arrives raw — trimming and case are policy, and this is the prop that hands policy over. |
+| highlightMatches | boolean | true | Paints the query wherever it appears in a row's label (not its detail or hint), on the `highlight` / `highlight-foreground` pair, through the CSS Custom Highlight API — no `<mark>` in the row, and the accessible name is unchanged. A literal, case-insensitive match, so under a fuzzy `filter` a row that matched as a subsequence keeps an unpainted label. `false` turns it off. Applies to CommandMenuPanel too. |
 | listClassName | string | — | Classes for the scrolling list. className lands on the dialog surface, so this is the seam for the list's own height cap — listClassName="max-h-[60vh]". The list is a Scroller, so the cap lands on the element that scrolls and the edge fades come free. |
 | placeholder | string | "Type a command or search…" | Placeholder for the search input. |
 | emptyMessage | string | "No results found." | Copy shown when the query matches nothing. |
@@ -68,7 +69,7 @@ Use CommandMenu for global or contextual keyboard-driven actions: navigation, cr
 
 ## Tokens used
 
-`card`, `card-foreground`, `border`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`
+`highlight`, `highlight-foreground`, `card`, `card-foreground`, `border`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`
 
 ## Motion
 

package/llms/components/date-picker.md

@@ -38,7 +38,7 @@ Use DatePicker when users need to choose one date — or, with granularity="minu
 
 ## Tokens used
 
-`primary`, `primary-foreground`, `accent`, `accent-foreground`, `foreground`, `muted-foreground`, `popover`, `popover-foreground`, `border`, `input`, `card`, `ring`
+`primary`, `primary-foreground`, `accent`, `accent-foreground`, `foreground`, `muted-foreground`, `popover`, `popover-foreground`, `border`, `field-border`, `field`, `ring`
 
 ## Accessibility
 

package/llms/components/feedback.md

@@ -32,12 +32,13 @@ Use Feedback to collect lightweight sentiment, usefulness, or quality signals fr
 
 ## Tokens used
 
-`popover`, `popover-foreground`, `border`, `input`, `card`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`, `ring`, `success`
+`popover`, `popover-foreground`, `border`, `input`, `card`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`, `ring`, `success`, `success-mark`
 
 ## Motion
 
 - **arrival** · Popover · `motion-pop` — The form opens from its trigger, so the eye goes from the button it pressed to the field it should type in. Popover owns the recipe.
 - **response** · Rating toggles · `motion-interactive` — The rating row is a choice among a few similar marks. The eased selected fill is what makes the pick read as made, not just hovered.
+- **response** · Chosen rating mark · `motion-bloom` — The mark itself answers the pick: it blooms past its size and settles, so choosing reads as a small decision landing rather than a fill changing. Only the chosen mark, only on choosing — nothing blooms when the form opens or a pick is let go. Expressive: under subtle the fill alone answers.
 - **transition** · Thanks · `motion-tick` — Sending is the one moment the person needs to know their words arrived. The form fades out in place and a check draws itself in over it, then the popover closes. Without it the popover just vanished, which looks the same as the form being dismissed or the message lost.
 - **activity** · Root · _no motion_ — The thanks shows as soon as the form is sent; delivery is the app's background work. A spinner for a one-line report would make a quick, optional gesture feel heavy.
 

package/llms/components/gradient-art.md

@@ -8,13 +8,15 @@ Placeholder artwork painted by a static WebGL shader from the preset's own art d
 
 ## Usage
 
-Use GradientArt where a real image belongs but none exists yet, or where the image is decoration: a product cover before upload, a profile banner, an album tile, an avatar with no photo. It reads the theme's own tokens, so it follows every preset, mode and live edit; `seed` fixes each item's composition so a list of covers or avatars stays individually recognisable.
+Use GradientArt where a real image belongs but none exists yet, or where the image is decoration: a product cover before upload, a profile banner, an album tile, an avatar with no photo. It reads the theme's own tokens, so it follows every preset, mode and live edit; `seed` fixes each item's composition so a list of covers or avatars stays individually recognisable. `intensity="soft"` paints the same art as a pastel wash — the iridescent aura AI products use as a card or modal header band, and as a stage for floating chips and logo tiles.
 
 ### Best practices
 
 - Do: Pass a stable `seed` per item — the name for an avatar, the title for a cover. Each item then keeps the same art across renders, reloads and themes, which is what lets someone recognise it.
 - Do: Size it with layout classes (`aspect-[4/3]`, `h-20`, `size-10 rounded-full`) and put any glyph or initials inside as children; they render above the art.
 - Do: Keep the default `mesh` for covers, tiles and avatars. Reach for `grain` where a printed, tactile surface suits — a banner, a hero card — and keep one variant per surface type so art reads as a system.
+- Do: Use `intensity="soft"` as a stage: a card or modal header band, the art on an integration or pricing card, a field behind floating prompt chips or rounded logo tiles. Make the tiles and chips floating surfaces (`bg-popover` with `border-border-floating` and a shadow, or a `floating` Button) so they lift off the wash; soft stays light in dark mode too, so the same composition holds in both.
+- Don't: Do not put text straight on soft art with `text-overlay-foreground` ink. Soft is a light ground in every mode, so overlay ink washes out on it; put the content on a Card or a chip over the art, or use the default vivid intensity for a short overlay label.
 - Don't: Do not put body text over it. The art spans the palette's lightest and most saturated tones, so no single ink is guaranteed to clear contrast across it; reserve overlays for a short label on a scrim or an avatar's initials.
 - Don't: Do not pass colours, and reach for `tones` rarely. The art follows the preset's --art-* tokens on purpose; to change how a product's art looks, set the --theme-art-* hooks in its theme or preset, so every cover, banner and avatar changes together.
 - Don't: Do not use it as a page or hero background. It paints at the element's pixel size, so a full-viewport instance costs a large frame on every theme change; it is sized for covers, banners and tiles.
@@ -26,12 +28,14 @@ Use GradientArt where a real image belongs but none exists yet, or where the ima
 | variant | "mesh" \| "grain" | "mesh" | mesh: soft spots of colour pulled together by gentle waves. grain: glowing light over deep corners with a printed texture. |
 | tones | ("info" \| "3" \| "2" \| "1" \| "warning")[] | — | Paint these `--tone-*` colours instead of the preset's art palette. Leave unset to follow the preset's art direction. |
 | seed | string \| number | — | Fixes the composition: the same seed paints the same art in every theme. Pass a stable id. |
+| intensity | "vivid" \| "soft" | "vivid" | vivid: the preset's art at full strength. soft: every colour and the ground lifted to a light pastel of itself (high lightness, half chroma) — a wash for header bands and for staging chips and logo tiles, light in both modes. |
 | children | ReactNode | — | Rendered above the art — initials, a glyph, a short label. |
 | className | string | — | Size and shape: aspect, height, rounding. |
 
 ## Variants
 
 - **variant**: mesh, grain
+- **intensity**: vivid, soft
 
 ## Tokens used
 
@@ -78,3 +82,26 @@ import { GradientArt } from "@sableui/react"
 
 <GradientArt seed="Mara Okafor" className="grid size-10 place-items-center rounded-full text-label-md text-overlay-foreground">MO</GradientArt>
 ```
+
+### Soft header band with logo tiles
+
+```tsx
+import { Button, Card, CardDescription, CardFooter, CardHeader, CardTitle, GradientArt, Icon } from "@sableui/react"
+
+<Card className="w-full max-w-sm">
+	<GradientArt intensity="soft" seed="Integrations" className="flex h-32 items-center justify-center gap-3 rounded-t-lg">
+		{["mail", "calendar", "chart"].map((name) => (
+			<span key={name} className="grid size-12 place-items-center rounded-lg border border-border-floating bg-popover text-popover-foreground shadow-md">
+				<Icon name={name} className="text-xl" />
+			</span>
+		))}
+	</GradientArt>
+	<CardHeader>
+		<CardTitle>Connect your tools</CardTitle>
+		<CardDescription>Bring mail, calendar and analytics into one place.</CardDescription>
+	</CardHeader>
+	<CardFooter>
+		<Button>Connect</Button>
+	</CardFooter>
+</Card>
+```

package/llms/components/input-group.md

@@ -30,7 +30,7 @@ Use InputGroup when something belongs inside the field with the text: a unit, a
 
 ## Tokens used
 
-`input`, `card`, `ring`, `destructive`, `muted-foreground`, `foreground`
+`field-border`, `field`, `ring`, `destructive`, `muted-foreground`, `foreground`
 
 ## Motion
 

package/llms/components/input.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-Styled native text input. Soft-square (rounded-sm), card surface, 2px focus ring; aria-invalid raises the destructive error treatment.
+Styled native text input. Soft-square (rounded-sm), the theme's field surface (outlined or filled), 2px focus ring; aria-invalid raises the destructive error treatment.
 
 **Keywords:** input, text input, field, form, email, search, file, invalid, validation
 
@@ -16,6 +16,8 @@ Use Input for short freeform text, search, email, password, file, and native inp
 - Do: Use type, inputMode, autoComplete, and placeholder as progressive hints, not as the only label.
 - Do: Set aria-invalid or use Field error copy when validation fails.
 - Do: Keep a focusable field at 16px or larger on mobile. iOS Safari zooms the whole page when a focused input computes under 16px and never zooms back out. Input handles this itself — below the sm breakpoint it renders text-body-lg (17px) and returns to text-body-md at sm and up. Build a custom field the same way: a second paired tier under a max-sm: variant, never a hand-set font-size.
+- Do: Choose outlined or filled fields once, in the theme: `--theme-field: var(--muted)` with `--theme-field-border: transparent` turns every Input, Textarea, Select, Combobox, SearchInput, InputGroup and ChatComposer into a borderless filled well; unset, they are outlined on the card. Every field reads the `field` / `field-border` pair, so they change together.
+- Don't: Restyle one Input as a filled chip with `bg-muted border-transparent`. It drifts from every other field on the page, and the theme can no longer move them together; set the field tokens instead.
 - Don't: Override an Input's type with a page tier below 16px (text-body-md, text-body-sm, text-label-*) without a >=16px mobile arm — that reintroduces the iOS focus zoom.
 - Don't: Use placeholder text as the label; it disappears once the user types and is not enough context.
 - Don't: Use Input for long body copy. Use Textarea for multi-line content.
@@ -45,7 +47,7 @@ Use Input for short freeform text, search, email, password, file, and native inp
 
 ## Tokens used
 
-`input`, `card`, `foreground`, `muted-foreground`, `ring`, `destructive`
+`field-border`, `field`, `foreground`, `muted-foreground`, `ring`, `destructive`
 
 ## Accessibility