@estiva-app/ui 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/AppShell.stories.tsx

@@ -59,7 +59,7 @@ const rail = (
 /** The structured frame: solid bar, sidebar, content beside it. */
 export const Solid: Story = {
   render: (args) => (
-    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="⌘ K" className="w-[290px]" />} identity={identity} nav={sidebar}>
+    <AppShell {...args} logo="Estiva" search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />} identity={identity} nav={sidebar}>
       <div className="flex h-full items-center justify-center">
         <EmptyState message="Nothing here yet." />
       </div>
@@ -86,7 +86,7 @@ export const Floating: Story = {
       variant="floating"
       menu={menuButton}
       logo="Estiva"
-      search={<SearchInput shortcut="⌘ K" className="w-[290px]" />}
+      search={<SearchInput shortcut="Ctrl+K" className="w-[290px]" />}
       identity={identity}
       nav={rail}
     >

package/src/Divider.tsx

@@ -16,7 +16,11 @@ export function Divider({ orientation = 'horizontal', className }: DividerProps)
     <div
       role="separator"
       aria-orientation={orientation}
-      className={cn('bg-border-subtle', orientation === 'horizontal' ? 'h-px mx-3' : 'w-px self-stretch shrink-0', className)}
+      // shrink-0 on both orientations: a 1px flex child in an overflowing
+      // column shrinks to nothing, and a hairline that renders 0px tall is a
+      // hairline nobody can see — Peek's `/` menu had been drawing two of
+      // them, measured 0px, since it was built (2026-09-05).
+      className={cn('shrink-0 bg-border-subtle', orientation === 'horizontal' ? 'h-px mx-3' : 'w-px self-stretch', className)}
     />
   )
 }

package/src/IconButton.tsx

@@ -13,6 +13,9 @@ export type IconButtonVariant = 'muted' | 'outlined' | 'primary'
 export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: IconButtonVariant
   tooltip?: string
+  /** A key hint drawn as the `Kbd` chip inside the tooltip — for a button
+   *  whose only other affordance is a keyboard shortcut. */
+  tooltipShortcut?: string
   tooltipPlacement?: 'top' | 'bottom'
   /** The icon: 16px, stroke 1.5. */
   children: ReactNode
@@ -24,6 +27,7 @@ export function IconButton({
   children,
   disabled,
   tooltip,
+  tooltipShortcut,
   tooltipPlacement,
   type = 'button',
   ...props
@@ -51,7 +55,7 @@ export function IconButton({
 
   if (tooltip) {
     return (
-      <WithTooltip label={tooltip} placement={tooltipPlacement}>
+      <WithTooltip label={tooltip} shortcut={tooltipShortcut} placement={tooltipPlacement}>
         {button}
       </WithTooltip>
     )

package/src/Kbd.mdx

@@ -0,0 +1,77 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as KbdStories from './Kbd.stories'
+
+<Meta of={KbdStories} />
+
+# Kbd
+
+The small chip that names the key which does the same thing. A bordered
+`kbd` on the inset fill, `caption` type in secondary ink, sized to its
+content and never shrinking.
+
+<Canvas of={KbdStories.Row} />
+
+## When
+
+- **At the right edge of a menu row** — `MenuItem`'s `shortcut` draws one for
+  you; pass the string, not the element.
+- **Inside a tooltip** — `Tooltip` and `WithTooltip` take a `shortcut` for the
+  same reason: an icon button whose only other affordance is a key.
+  `IconButton` forwards its own `tooltipShortcut` there.
+- **At the right edge of a search field** — `SearchInput`'s `shortcut`, for
+  the key that puts the cursor in it.
+- **In a shortcuts sheet**, where the key is the content rather than a hint.
+
+## Naming the key
+
+The label is a word, never a symbol — `Cmd+K`, `Enter`, `Esc`, `Backspace`.
+Two reasons, and they cost nothing to obey:
+
+1. A symbol is often wrong. `⌘` on a Windows machine names a key that is not
+   there.
+2. **The symbols are not in the font.** Geist Mono has no `⌘`, `⌫` or `↩`, so
+   the browser silently borrows each one from another face — measured at 10px,
+   every character the font owns advances exactly 6px, while `↩` comes back
+   8.63px and `⌫` 12.81px. One borrowed glyph in a row of chips makes that
+   chip wider and its ink a different shape.
+
+**`↑` and `↓` are the exception** — they are in Geist Mono at the same 6px, and
+an arrow is what is printed on the key. Their horizontal partners are not:
+Geist Mono owns `←` and `→` but draws them 10px wide, so a chip holding one
+comes out wider than the chips beside it. Measure before adding a symbol to
+this list; the font's coverage is not uniform.
+
+And a trigger is the character you would actually type. Peek's resolution
+block fires on `->`, so its row says `->` — there is no `→` key to press.
+
+## When not
+
+- A status, count or category → **Chip**. This one means *press this*.
+- A run of code inside prose → the consumer's own `code` styling; a keyboard
+  hint and a code span are different ideas that happen to both be monospace-ish.
+- Anything clickable → **Button**. A key hint is a label, not a control.
+
+## How
+
+```tsx
+import { Kbd } from '@estiva-app/ui'
+
+<Kbd>Cmd+K</Kbd>
+```
+
+Most callers never reach for it directly — they pass a string:
+
+```tsx
+<MenuItem label="Heading" shortcut="#" />
+<Tooltip label="Bold" shortcut="Cmd+B" />
+```
+
+<Canvas of={KbdStories.InContext} />
+
+It renders what it is given and formats nothing. A modifier is called Cmd on
+Apple platforms and Ctrl elsewhere, and only the caller knows which it is
+looking at — so decide there and pass the finished label.
+
+## Props
+
+<Controls of={KbdStories.Default} />

package/src/Kbd.stories.tsx

@@ -0,0 +1,58 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Kbd } from './Kbd'
+import { Menu, MenuItem, MenuSection } from './Menu'
+import { Tooltip } from './Tooltip'
+
+const meta = {
+  title: 'Primitives/Kbd',
+  component: Kbd,
+  args: { children: 'Cmd+K' },
+  argTypes: { children: { control: 'text' } },
+} satisfies Meta<typeof Kbd>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+/** A single trigger character, the way a command menu names its own key. */
+export const TriggerCharacter: Story = { args: { children: '/' } }
+
+/** A chord. Whoever passes it decides the platform's spelling. */
+export const Chord: Story = { args: { children: 'Ctrl+Alt+1' } }
+
+/** A named key. */
+export const NamedKey: Story = { args: { children: 'Esc' } }
+
+/** The four side by side. */
+export const Row: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      {['/', 'Cmd+K', 'Ctrl+Alt+1', 'Esc'].map((k) => (
+        <Kbd key={k}>{k}</Kbd>
+      ))}
+    </div>
+  ),
+}
+
+/** Where it appears on its own: a menu row's `shortcut`, and a tooltip's. */
+export const InContext: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-start gap-6">
+      <Menu onClose={() => {}} className="static w-[220px]">
+        <MenuSection label="Format">
+          <MenuItem label="Heading" shortcut="#" />
+          <MenuItem label="Quote" shortcut=">" />
+          <MenuItem label="Numbered list" shortcut="1." />
+        </MenuSection>
+      </Menu>
+      <div className="flex flex-col gap-2">
+        <Tooltip label="Bold" shortcut="Cmd+B" />
+        <Tooltip label="Italic" shortcut="Ctrl+I" />
+        <Tooltip label="Comment" />
+      </div>
+    </div>
+  ),
+}

package/src/Kbd.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A keyboard hint — the small chip that names the key which does the same thing.
+ *
+ * **The look is SearchInput's shortcut chip** (Katerina, 2026-09-05), which is
+ * the one the apps already show: an inset pill with a hairline border, and under
+ * Signal and Ship the keycap treatment — mono, 10px, a lighter fill and a thicker
+ * bottom edge, so it reads as a key rather than a label.
+ *
+ * It existed before this file did, drawn inline inside `MenuItem` and again
+ * inside `SearchInput`. Extracted when `Tooltip` needed a third copy.
+ *
+ * **Sizes are arbitrary values on purpose.** `text-caption` beside a
+ * `text-{color}` is dropped by tailwind-merge, so the chip silently inherited
+ * whatever size surrounded it — 10px in a composer, something else elsewhere.
+ * `text-[12px]` survives the merge.
+ *
+ * Content is whatever names the key — a trigger character (`/`, `@`), a chord
+ * (`Cmd+B`, `Ctrl+Alt+1`), or a word (`Esc`). It does not format anything: a caller
+ * that knows the platform passes the label it wants.
+ */
+export interface KbdProps {
+  children: ReactNode
+  className?: string
+}
+
+export function Kbd({ children, className }: KbdProps) {
+  return (
+    <kbd
+      className={cn(
+        'inline-flex shrink-0 items-center justify-center whitespace-nowrap rounded-sm border border-border-strong bg-bg-inset px-1 py-px font-sans text-[12px] leading-[120%] font-normal text-text-secondary',
+        'signal:border-b-2 signal:pt-[2px] signal:pb-px signal:bg-[rgba(255,255,255,.05)] signal:font-mono signal:text-[10px]',
+        'ship:border-b-2 ship:pt-[2px] ship:pb-px ship:bg-[rgba(255,255,255,.05)] ship:font-mono ship:text-[10px]',
+        className,
+      )}
+    >
+      {children}
+    </kbd>
+  )
+}

package/src/Menu.mdx

@@ -9,9 +9,16 @@ The shell every menu shares: an elevated container — hairline border, 8px
 radius, 8px padding, the large shadow — and the two exits every menu owes,
 **Escape and a click outside, owned here and never by the caller**. Rows are
 **MenuItem**, headings are **MenuSection**, a non-interactive line at row
-geometry is **MenuRow**, and **EnterHint** is the "↩ Enter" a picker row
+geometry is **MenuRow**, and **EnterHint** is the `↩ Enter` chip a picker row
 shows while highlighted.
 
+**MenuPanel** is the container on its own, without the behaviour — for the
+one case that cannot have it: a type-ahead popup inside a text editor, where
+the editor's own plugin already owns the keyboard and the placement, and a
+second Escape handler fights it. `Menu` renders `MenuPanel`, so the surface
+has one definition either way. If your surface opens from a trigger, you want
+`Menu`; reach for `MenuPanel` only when something else is already driving.
+
 <Canvas of={MenuStories.Items} />
 
 ## When

package/src/Menu.stories.tsx

@@ -27,7 +27,7 @@ export const Items: Story = {
   render: (args) => (
     <Menu {...args}>
       <MenuItem label="Rename" leading={<IconPencil size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuItem label="Copy link" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="⌘ C" onClick={() => {}} />
+      <MenuItem label="Copy link" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
       <Divider className="my-1" />
       <MenuItem label="Delete" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
     </Menu>

package/src/Menu.tsx

@@ -2,6 +2,7 @@ import { createContext, useCallback, useContext, useEffect, useLayoutEffect, use
 import { IconChevronRight } from '@tabler/icons-react'
 import { createPortal } from 'react-dom'
 import { cn } from './cn'
+import { Kbd } from './Kbd'
 import { clampBox, fitMenu, fitSubmenu } from './fit'
 import { SectionLabel } from './SectionLabel'
 
@@ -70,6 +71,38 @@ export interface MenuProps {
  *  submenu panel — the one hover region the old inline submenus had for free. */
 const MenuHoverContext = createContext<{ hold: () => void; release: () => void } | null>(null)
 
+/**
+ * The menu's surface, with none of its behaviour — an elevated box with a
+ * hairline border, 8px radius, 8px padding and the large shadow.
+ *
+ * Split out of `Menu` on 2026-09-05. `Menu` owns Escape, outside-click and
+ * placement, and that is right for a menu opened from a trigger — but a
+ * type-ahead popup inside a text editor cannot have them: the editor's
+ * suggestion plugin already owns the keyboard and positions the popup, and a
+ * second Escape handler fights it. So Peek's `@`, `/` and `[` menus each drew
+ * this box by hand, and the three had already drifted apart.
+ *
+ * `Menu` renders this, so there is still exactly one definition of the
+ * surface — change it here and every menu in every app follows.
+ *
+ * Width, height and internal rhythm belong to the caller: a picker that lists
+ * people is not the width of one that lists verbs.
+ */
+export interface MenuPanelProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  children: ReactNode
+}
+
+export function MenuPanel({ children, className, ...props }: MenuPanelProps) {
+  return (
+    <div
+      className={cn('flex flex-col rounded-lg border border-border-default bg-bg-elevated p-2 shadow-lg', className)}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+}
+
 export function Menu({ onClose, anchor, align = 'left', position, closeOnLeave = false, children, className }: MenuProps) {
   const ref = useRef<HTMLDivElement>(null)
   const leaveTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
@@ -152,12 +185,12 @@ export function Menu({ onClose, anchor, align = 'left', position, closeOnLeave =
     : undefined
   const node = (
     <MenuHoverContext.Provider value={{ hold, release }}>
-      <div
+      <MenuPanel
         ref={ref}
         role="menu"
         data-interactive
         className={cn(
-          'z-50 flex min-w-[180px] flex-col rounded-lg border border-border-default bg-bg-elevated p-2 shadow-lg',
+          'z-50 min-w-[180px]',
           portalled ? 'fixed overflow-y-auto' : 'absolute right-0 top-full mt-1',
           className,
         )}
@@ -167,7 +200,7 @@ export function Menu({ onClose, anchor, align = 'left', position, closeOnLeave =
         onMouseLeave={closeOnLeave ? release : undefined}
       >
         {children}
-      </div>
+      </MenuPanel>
     </MenuHoverContext.Provider>
   )
   return portalled ? createPortal(node, document.body) : node
@@ -237,17 +270,17 @@ export function MenuSub({ label, leading, selected, children, className }: MenuS
       <MenuItem label={label} leading={leading} selected={selected} submenu />
       {open &&
         createPortal(
-          <div
+          <MenuPanel
             ref={panelRef}
             role="menu"
             data-interactive
-            className={cn('fixed z-50 flex w-[160px] flex-col rounded-lg border border-border-default bg-bg-elevated p-2 shadow-lg', className)}
+            className={cn('fixed z-50 w-[160px]', className)}
             style={placed ?? { left: 0, top: 0, visibility: 'hidden' }}
             onMouseEnter={enter}
             onMouseLeave={leave}
           >
             {children}
-          </div>,
+          </MenuPanel>,
           document.body,
         )}
     </div>
@@ -269,6 +302,23 @@ export interface MenuItemProps extends Omit<ComponentPropsWithRef<'button'>, 'ch
   leading?: ReactNode
   /** At the right edge: a hint, a value — anything. Wins over `shortcut` and `submenu`. */
   trailing?: ReactNode
+  /**
+   * Shown at the right edge **only while this row is the one you are pointing
+   * at or have arrowed onto** — an `EnterHint`, typically.
+   *
+   * Pass it unconditionally. Do not do `trailing={active ? <EnterHint/> : undefined}`:
+   * that mounts the hint, and a mount is instant while the row's own fill is a
+   * 150ms fade, so the hint lands ahead of the highlight on the way in and
+   * vanishes ahead of it on the way out (measured 2026-09-05 — ~7 frames of a
+   * chip sitting on an unhighlighted row, and two rows lit at once when
+   * sweeping). This slot is always in the DOM and revealed by the *same*
+   * `:hover` / `selected` the fill uses, on the same duration and curve, so
+   * the two cannot come apart — and the row does not reflow when it appears.
+   *
+   * It cross-fades with `trailing`/`shortcut`/`submenu` rather than displacing
+   * them, and reserves the wider of the two, so nothing moves either way.
+   */
+  hint?: ReactNode
   /** A keyboard hint, drawn as the kbd chip. */
   shortcut?: string
   /** The row opens another menu: draws the chevron at the right edge. */
@@ -278,13 +328,11 @@ export interface MenuItemProps extends Omit<ComponentPropsWithRef<'button'>, 'ch
   selected?: boolean
 }
 
-export function MenuItem({ label, children, size = 'default', description, leading, trailing, shortcut, submenu, destructive, selected, className, ...props }: MenuItemProps) {
+export function MenuItem({ label, children, size = 'default', description, leading, trailing, hint, shortcut, submenu, destructive, selected, className, ...props }: MenuItemProps) {
   const edge =
     trailing ??
     (shortcut ? (
-      <kbd className="inline-flex shrink-0 items-center justify-center rounded-sm border border-border-strong bg-bg-inset px-1 py-px text-caption text-text-secondary">
-        {shortcut}
-      </kbd>
+      <Kbd>{shortcut}</Kbd>
     ) : submenu ? (
       <IconChevronRight size={16} stroke={1.5} className="shrink-0 text-text-muted" />
     ) : null)
@@ -293,7 +341,21 @@ export function MenuItem({ label, children, size = 'default', description, leadi
       type="button"
       role="menuitem"
       className={cn(
-        'flex w-full cursor-pointer items-center rounded-lg text-left hover:bg-bg-hover transition-colors',
+        // shrink-0: a menu is a flex column that scrolls at its max height,
+        // and a flex child shrinks before its container does — so every row
+        // in an overflowing menu was squashed to its `min-h`, and a row given
+        // an explicit height silently lost it (Peek's `[` menu: h-12 rows
+        // measured 40px). The same fix NavItem took on 2026-09-02.
+        // `group`: the `hint` slot reveals itself from this row's own :hover,
+        // so the hint and the fill are one CSS state change, not two engines.
+        //
+        // No transition on the fill (Katerina, 2026-09-05). It faded over
+        // 150ms, and anything appearing with it had to fade too or arrive
+        // ahead of it — which, sweeping a pointer down a list, read as the
+        // hint flickering in and out. Both are instant now: they still change
+        // on exactly the same :hover, so they cannot come apart, and a row
+        // lights and unlights crisply as the pointer crosses it.
+        'group flex w-full shrink-0 cursor-pointer items-center rounded-lg text-left hover:bg-bg-hover',
         // tall: as tall as its content, never shorter than 40px (Katerina,
         // 2026-09-01) — a single-line picker row sits at 40, a row with a
         // 32px face and a role line comes out at its natural 48. One rule,
@@ -316,20 +378,52 @@ export function MenuItem({ label, children, size = 'default', description, leadi
           {description && <span className="truncate text-[12px] leading-[120%] text-text-secondary">{description}</span>}
         </span>
       )}
-      {edge && <span className="flex shrink-0 items-center">{edge}</span>}
+      {(edge || hint) && (
+        // One grid cell holding both, right-aligned: the slot is as wide as
+        // the wider of the two and never changes, so revealing the hint moves
+        // nothing. No transition here either — the hint switches on the same
+        // :hover / `selected` as the fill, in the same frame.
+        <span className="grid shrink-0 items-center justify-items-end [&>*]:col-start-1 [&>*]:row-start-1">
+          {edge && (
+            <span className={cn('flex items-center', hint && 'group-hover:opacity-0', hint && selected && 'opacity-0')}>
+              {edge}
+            </span>
+          )}
+          {hint && (
+            <span className={cn('flex items-center opacity-0 group-hover:opacity-100', selected && 'opacity-100')}>
+              {hint}
+            </span>
+          )}
+        </span>
+      )}
     </button>
   )
 }
 
 /**
- * The keyboard hint a picker row shows while highlighted — "↩ Enter",
- * "↩ #topic" — hand-rolled in five files before this (2026-09-01).
+ * The keyboard hint a picker row shows while highlighted — hand-rolled in
+ * five files before this (2026-09-01), and drawn as its own thing until
+ * 2026-09-05, when it became the `Kbd` chip every other key hint uses. A
+ * picker row and a menu row sit in the same menu; they named the same key
+ * two ways.
+ *
+ * `target` is what pressing it gives you, when that is worth saying — the
+ * topic picker's "↩ Enter #topic". It sits after the chip, in the picker's
+ * own 9px voice, because it is not a key.
+ *
+ * Katerina, 2026-09-05, told the measurement and asked again: the chip keeps
+ * the `↩` character. It is not in Geist Mono — the browser borrows it, so it
+ * advances 8.63px where the font's own characters advance 6 — and that is a
+ * knowing trade for the glyph, not an oversight. If the width ever has to go,
+ * Tabler's IconCornerDownLeft draws the same shape.
  */
-export function EnterHint({ label = 'Enter' }: { label?: string }) {
+export function EnterHint({ target }: { target?: string }) {
   return (
-    <span className="flex shrink-0 items-center gap-2 text-text-muted">
-      <span className="text-[12px] leading-[120%]">↩</span>
-      <span className="text-[9px] font-medium leading-[115%] signal:font-mono signal:text-[9.5px] signal:tracking-[0.04em]">{label}</span>
+    <span className="flex shrink-0 items-center gap-1.5 text-text-muted">
+      <Kbd>↩ Enter</Kbd>
+      {target && (
+        <span className="text-[9px] font-medium leading-[115%] signal:font-mono signal:text-[9.5px] signal:tracking-[0.04em]">{target}</span>
+      )}
     </span>
   )
 }

package/src/MenuItem.mdx

@@ -39,7 +39,7 @@ import { IconPencil } from '@tabler/icons-react'
 <MenuItem
   label="Rename"
   leading={<IconPencil size={16} stroke={1.5} className="text-text-secondary" />}
-  shortcut="⌘ R"
+  shortcut="Ctrl+R"
   onClick={rename}
 />
 ```

package/src/MenuItem.stories.tsx

@@ -40,7 +40,7 @@ export const WithAnIcon: Story = {
 }
 
 export const WithAShortcut: Story = {
-  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: '⌘ C' },
+  args: { label: 'Copy link', leading: <IconCopy size={16} stroke={1.5} className="text-text-secondary" />, shortcut: 'Ctrl+C' },
 }
 
 /** The row opens another menu. */
@@ -54,7 +54,7 @@ export const APerson: Story = {
     label: 'Ana Duarte',
     description: 'Product designer',
     leading: <Avatar name="Ana Duarte" size={32} />,
-    trailing: <span className="text-[12px] leading-[120%] text-text-muted">↩</span>,
+    trailing: <EnterHint />,
   },
 }
 
@@ -74,10 +74,10 @@ export const AllVariants: Story = {
     <>
       <MenuItem label="Bare" onClick={() => {}} />
       <MenuItem label="With an icon" leading={<IconPin size={16} stroke={1.5} className="text-text-secondary" />} onClick={() => {}} />
-      <MenuItem label="With a shortcut" shortcut="⌘ K" onClick={() => {}} />
-      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="⌘ C" onClick={() => {}} />
+      <MenuItem label="With a shortcut" shortcut="Ctrl+K" onClick={() => {}} />
+      <MenuItem label="Icon and shortcut" leading={<IconCopy size={16} stroke={1.5} className="text-text-secondary" />} shortcut="Ctrl+C" onClick={() => {}} />
       <MenuItem label="Opens another menu" submenu onClick={() => {}} />
-      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<span className="text-[12px] leading-[120%] text-text-muted">↩</span>} onClick={() => {}} />
+      <MenuItem label="Ana Duarte" description="Product designer" leading={<Avatar name="Ana Duarte" size={32} />} trailing={<EnterHint />} onClick={() => {}} />
       <MenuItem label="The chosen value" selected onClick={() => {}} />
       <MenuItem label="Destructive" destructive leading={<IconTrash size={16} stroke={1.5} className="text-error-default" />} onClick={() => {}} />
       <MenuItem label="A very long label that runs out of room and truncates" onClick={() => {}} />

package/src/Reaction.mdx

@@ -0,0 +1,49 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ReactionStories from './Reaction.stories'
+
+<Meta of={ReactionStories} />
+
+# Reaction
+
+An emoji, how many people chose it, and whether you are one of them. A
+24px pill that toggles — Chip's shape at a control's height.
+
+<Canvas of={ReactionStories.Row} />
+
+## When
+
+- Under a message, in a row of them. `pressed` is **you are one of the
+  reactors**: the accent's muted tint and an accent edge, so a glance
+  separates "two people, one of them me" from "two people".
+- Any emoji at all. Another app may publish one outside your set, and a
+  reaction you cannot name is still one you must draw.
+
+<Canvas of={ReactionStories.Pressed} />
+
+## When not
+
+- Standing information nobody can toggle — a status, a category → **Chip**
+  (a Chip is not a control).
+- Adding a reaction that is not there yet: that is a picker, and a strip of
+  icon actions is a toolbar of **IconButton**s.
+- An action with a verb for a label → **Button**.
+
+## How
+
+```tsx
+import { Reaction } from '@estiva-app/ui'
+
+<Reaction emoji="👍" count={2} pressed aria-label="Makes sense, 2" onClick={toggle} />
+```
+
+- **`aria-label` is required.** The emoji is `aria-hidden` — a glyph read
+  aloud is noise, and its spoken name differs per screen reader — so the
+  count is the only visible text and the control would otherwise be
+  announced as "2". Pass the meaning and the count.
+- It is a real `<button>` with `aria-pressed`, so "mine" reaches assistive
+  tech as a toggle rather than as a colour. Every native prop passes
+  through; `type` defaults to `"button"`.
+
+## Props
+
+<Controls of={ReactionStories.Default} />

package/src/Reaction.stories.tsx

@@ -0,0 +1,49 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { fn } from 'storybook/test'
+import { Reaction } from './Reaction'
+
+const meta = {
+  title: 'Components/Reaction',
+  component: Reaction,
+  args: { emoji: '👍', count: 2, 'aria-label': 'Makes sense, 2', onClick: fn() },
+} satisfies Meta<typeof Reaction>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Somebody else's reaction: the inset fill and a hairline, like a neutral Chip. */
+export const Default: Story = {}
+
+/**
+ * Yours.
+ *
+ * The state a reaction has and a chip does not — the accent's muted tint and an
+ * accent edge, so a glance separates "two people, one of them me" from "two
+ * people". `aria-pressed` carries the same fact to assistive tech.
+ */
+export const Pressed: Story = { args: { pressed: true } }
+
+/** A row of them, as a message carries them. */
+export const Row: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-1">
+      <Reaction {...args} emoji="👍" count={3} aria-label="Makes sense, 3" pressed />
+      <Reaction {...args} emoji="🎉" count={1} aria-label="Congrats, 1" />
+      <Reaction {...args} emoji="🚀" count={12} aria-label="Let's go!, 12" />
+    </div>
+  ),
+}
+
+/** A count with two digits, so the pill grows rather than clipping. */
+export const WideCount: Story = { args: { count: 128, 'aria-label': 'Makes sense, 128' } }
+
+/** Momentarily unavailable — signing in, or a write already in flight. */
+export const Disabled: Story = { args: { disabled: true } }
+
+/**
+ * An emoji from outside any curated set.
+ *
+ * Another client may publish anything, and a reaction a consumer cannot name is
+ * still one it must draw rather than hide — so nothing here validates the glyph.
+ */
+export const UnknownEmoji: Story = { args: { emoji: '🦆', count: 1, 'aria-label': '🦆, 1' } }