@estiva-app/ui 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.13.0",
+  "version": "0.14.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/AttachmentCard.tsx

@@ -80,9 +80,9 @@ const formatBytes = (bytes: number) => {
 /** `'PDF'`, `'ZIP'`, `'DOCX'`, `'FILE'`. */
 const typeLabelOf = (name: string) => extensionOf(name).toUpperCase() || 'FILE'
 
-const TILE = 'size-9 rounded-md bg-bg-active flex items-center justify-center shrink-0 text-text-secondary'
-const NAME = 'text-[12px] font-medium leading-[1.3] text-text-primary truncate'
-const NOTE = 'text-[10px] leading-[1.2] truncate'
+const TILE_CLASSES = 'size-9 rounded-md bg-bg-active flex items-center justify-center shrink-0 text-text-secondary'
+const NAME_CLASSES = 'text-caption font-medium text-text-primary truncate'
+const NOTE_CLASSES = 'text-small tracking-wide leading-tight truncate'
 
 function TypeIcon({ name }: { name: string }) {
   const Icon = ICON_BY_EXTENSION[extensionOf(name)] ?? IconFile
@@ -191,7 +191,7 @@ export function AttachmentCard({
         className={cn('group relative flex items-center gap-2 w-[200px] p-1.5 pr-3', failed ? 'border-error-default' : warning && 'border-warning-default', className)}
         {...props}
       >
-        <div className={cn(TILE, 'overflow-hidden')}>
+        <div className={cn(TILE_CLASSES, 'overflow-hidden')}>
           {state === 'uploading' ? (
             <IconLoader2 size={16} stroke={1.5} className="animate-spin" />
           ) : failed ? (
@@ -201,15 +201,15 @@ export function AttachmentCard({
           ) : image && src ? (
             <img src={src} alt={name} className="size-full object-cover" />
           ) : (
-            <span className="text-[9px] font-semibold">{typeLabelOf(name)}</span>
+            <span className="text-menu font-semibold">{typeLabelOf(name)}</span>
           )}
         </div>
         <div className="flex flex-col gap-[1px] min-w-0">
-          <Truncating text={name} className={NAME} />
+          <Truncating text={name} className={NAME_CLASSES} />
           <Truncating
             text={(failed || warning ? note : state === 'uploading' ? (note ?? 'Uploading…') : (note ?? sizeText)) ?? ''}
             hint={noteHint}
-            className={cn(NOTE, failed ? 'text-error-default' : warning ? 'text-warning-default' : 'text-text-secondary')}
+            className={cn(NOTE_CLASSES, failed ? 'text-error-default' : warning ? 'text-warning-default' : 'text-text-secondary')}
           />
         </div>
         {/* On Base UI's Button, as InputChip's ✕ is (Katerina, 2026-09-14): IconButton is a 24px square
@@ -260,12 +260,12 @@ export function AttachmentCard({
   if (state === 'unreadable') {
     return (
       <Card fill="inset" unreadable className={cn('flex items-center gap-2 w-[240px] p-1.5 opacity-70', className)} {...props}>
-        <div className={TILE}>
+        <div className={TILE_CLASSES}>
           <TypeIcon name={name} />
         </div>
         <div className="flex flex-col gap-[1px] min-w-0 text-left">
-          <Truncating text={name} className={NAME} />
-          <span className={cn(NOTE, 'text-text-secondary')}>{note ?? 'Could not be loaded'}</span>
+          <Truncating text={name} className={NAME_CLASSES} />
+          <span className={cn(NOTE_CLASSES, 'text-text-secondary')}>{note ?? 'Could not be loaded'}</span>
         </div>
       </Card>
     )
@@ -291,7 +291,7 @@ export function AttachmentCard({
           <div className="block w-full">{picture}</div>
         )}
         <div className="flex items-center gap-1 pl-2 pr-1 py-1 min-w-0">
-          <Truncating text={name} className="flex-1 text-[12px] leading-[1.3] text-text-primary truncate" wrapperClassName="flex-1" />
+          <Truncating text={name} className="flex-1 text-caption text-text-primary truncate" wrapperClassName="flex-1" />
           {download}
         </div>
       </Card>
@@ -300,12 +300,12 @@ export function AttachmentCard({
 
   const body = (
     <>
-      <div className={TILE}>
+      <div className={TILE_CLASSES}>
         <TypeIcon name={name} />
       </div>
       <div className="flex flex-col gap-[1px] min-w-0 text-left">
-        <Truncating text={name} className={NAME} />
-        <span className={cn(NOTE, 'text-text-secondary')}>{note ?? `${typeLabelOf(name)} · ${sizeText}`}</span>
+        <Truncating text={name} className={NAME_CLASSES} />
+        <span className={cn(NOTE_CLASSES, 'text-text-secondary')}>{note ?? `${typeLabelOf(name)} · ${sizeText}`}</span>
       </div>
     </>
   )

package/src/Avatar.mdx

@@ -30,11 +30,16 @@ import { Avatar } from '@estiva-app/ui'
 <Avatar name={person.name} src={person.picture} size={24} />
 ```
 
-- The caller resolves `src`. A picture that fails to load falls back to the
-  initials — nothing to handle.
+- The caller resolves `src`. While the picture loads the tile stays empty;
+  once it arrives it fills the tile; if it fails, the initials show — nothing
+  to handle. It is Base UI's `Avatar`, which watches the picture load.
 - Initials come from a **name, never a key**: the first letter of the first
   two words, skipping words that open with a symbol. An unnamed person is
   the silhouette, not a `?` — a question mark reads as an error badge.
+- The initials are centred on the capitals themselves — cap height to
+  baseline — not on the line of text around them (D27). A single face can
+  still sit up to half a pixel off: the screen rounds text to its pixel grid
+  wherever the tile lands.
 - The colour behind initials is per person, chosen from the name, the same
   everywhere they appear. It is a fallback palette, not a token — themes
   have no say in it.

package/src/Avatar.picture.test.tsx

@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+/**
+ * A face's picture in its three moments, as the Avatar page claims them: the
+ * `<img>` is there from the first render and the tile shows nothing else while
+ * it loads; once it loads the initials are gone; if it fails, the initials.
+ *
+ * jsdom never loads an image, so the tests fire the `<img>`'s own events.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+import { Avatar } from './Avatar'
+
+afterEach(cleanup)
+
+const tile = (container: HTMLElement) => container.firstElementChild as HTMLElement
+
+describe('Avatar picture', () => {
+  it('the <img> is in the tile from the first render, with its address', () => {
+    const { container } = render(<Avatar name="Ana Duarte" src="https://example.test/face.png" />)
+    const img = tile(container).querySelector('img')
+    expect(img?.getAttribute('src')).toBe('https://example.test/face.png')
+    // First in the tile, so it covers it; the initials wait below the hidden overflow.
+    expect(tile(container).firstElementChild).toBe(img)
+  })
+
+  it('once the picture loads, the initials are gone', () => {
+    const { container } = render(<Avatar name="Ana Duarte" src="https://example.test/face.png" />)
+    fireEvent.load(tile(container).querySelector('img')!)
+    expect(tile(container).textContent).toBe('')
+    expect(tile(container).querySelector('img')?.hasAttribute('data-error')).toBe(false)
+  })
+
+  it('if the picture fails, it is hidden and the initials show', () => {
+    const { container } = render(<Avatar name="Ana Duarte" src="https://example.test/face.png" />)
+    const img = tile(container).querySelector('img')!
+    fireEvent.error(img)
+    expect(img.hasAttribute('data-error')).toBe(true)
+    expect(img.className).toContain('data-[error]:hidden')
+    expect(tile(container).textContent).toBe('AD')
+  })
+
+  it('no picture: the initials, and no <img>', () => {
+    const { container } = render(<Avatar name="Ana Duarte" />)
+    expect(tile(container).querySelector('img')).toBeNull()
+    expect(tile(container).textContent).toBe('AD')
+  })
+
+  it('the initials are centred on their capitals, not their line box (D27)', () => {
+    const { container } = render(<Avatar name="Ana Duarte" />)
+    const initials = tile(container).querySelector('span')
+    expect(initials?.textContent).toBe('AD')
+    expect(initials?.className).toBe('[text-box:trim-both_cap_alphabetic]')
+  })
+
+  it('no picture and no name: the silhouette', () => {
+    const { container } = render(<Avatar />)
+    expect(tile(container).querySelector('svg')).not.toBeNull()
+    expect(tile(container).textContent).toBe('')
+  })
+})

package/src/Avatar.stories.tsx

@@ -37,7 +37,7 @@ export const Sizes: Story = {
       {[16, 20, 22, 24, 28, 32, 36].map((size) => (
         <div key={size} className="flex flex-col items-center gap-1">
           <Avatar {...args} size={size} />
-          <span className="text-[12px] leading-[120%] text-text-muted">{size}</span>
+          <span className="text-caption text-text-muted">{size}</span>
         </div>
       ))}
     </div>

package/src/Avatar.tsx

@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { Avatar as BaseAvatar } from '@base-ui/react/avatar'
 import { IconUserFilled } from '@tabler/icons-react'
 import { cn } from './cn'
 
@@ -14,6 +14,10 @@ import { cn } from './cn'
  * three-line wrapper that resolves the picture; Ship passes the relay's
  * `kind:0` picture straight in.
  *
+ * On Base UI's `Avatar` since stage 6 of the migration (2026-09-14): Base UI
+ * loads the picture and says when it has arrived or failed, and the initials
+ * or the silhouette are its fallback. The hand-kept "broken" state is gone.
+ *
  * Initials come from a *name*, never from a key: a component that accepted a
  * pubkey would eventually show one (Ship's ruling, 2026-08-24). An unnamed
  * person is the silhouette — `?` on a bright gradient read as an error badge
@@ -44,7 +48,7 @@ export const initialsFor = (name: string) => {
 }
 
 export interface AvatarProps {
-  /** The picture URL, resolved by the caller. A picture that fails to load falls back to the initials. */
+  /** The picture URL, resolved by the caller. Until it arrives, and if it fails, the initials show. */
   src?: string
   /** The person's name — where the initials and the colour come from. */
   name?: string
@@ -68,11 +72,11 @@ export interface AvatarProps {
 }
 
 export function Avatar({ src, name, alt = '', size = 36, label: spoken, className }: AvatarProps) {
-  const [broken, setBroken] = useState(false)
   const label = name || alt
-  const picture = src && !broken ? src : undefined
   return (
-    <div
+    <BaseAvatar.Root
+      // A div, as it was drawn: Base UI's default is a span.
+      render={<div />}
       /* Named or silent, never half of either: with a `label` the tile is one
          image with one name, and everything inside it is that image's pixels;
          without one it is not in the accessibility tree at all. */
@@ -80,10 +84,25 @@ export function Avatar({ src, name, alt = '', size = 36, label: spoken, classNam
       className={cn('rounded-sm overflow-hidden shrink-0 bg-bg-inset', className)}
       style={{ width: size, height: size }}
     >
-      {picture ? (
-        <img src={picture} alt="" className="w-full h-full object-cover" onError={() => setBroken(true)} />
-      ) : label ? (
-        <div
+      {src && (
+        <BaseAvatar.Image
+          src={src}
+          alt=""
+          /*
+            `keepMounted`: the <img> is in the tile from the first render, as it
+            always was, so a picture still loading leaves the tile empty rather
+            than flashing initials and swapping them out, and an app's test that
+            finds the <img> still finds it. The fallback is rendered after it,
+            below the tile's hidden overflow, until the picture arrives (then it
+            unmounts) or fails (then the picture is hidden and it moves up).
+          */
+          keepMounted
+          className="w-full h-full object-cover data-[error]:hidden"
+        />
+      )}
+      {label ? (
+        <BaseAvatar.Fallback
+          render={<div />}
           /*
             `leading-none` is load-bearing (2026-09-03). Centring a flex child
             centres its LINE BOX, and a line box reserves room under the
@@ -99,21 +118,38 @@ export function Avatar({ src, name, alt = '', size = 36, label: spoken, classNam
           */
           className="w-full h-full flex items-center justify-center font-semibold leading-none"
           style={{
+            /* eslint-disable no-restricted-syntax -- the per-person palette (the note at
+               the top): eight hues picked from the name, the one ink that reads on all
+               of them, and a size that follows `size`. None of it can be a token. */
             // The one ink colour that reads on all eight hues, which are a
             // palette rather than tokens (see the note at the top) — so its
             // ink cannot be a token either.
             color: '#08121c',
             fontSize: Math.round(size * 0.36),
             background: `linear-gradient(160deg, color-mix(in srgb, ${hueFor(label)} 92%, #fff) 0%, color-mix(in srgb, ${hueFor(label)} 70%, #0b0d11) 100%)`,
+            /* eslint-enable no-restricted-syntax */
           }}
         >
-          {initialsFor(label)}
-        </div>
+          {/*
+            D27 (ruled 2026-09-08, built 2026-09-14): what is centred is the
+            capitals' own box, cap height to baseline, not the line box. The
+            line box's ascent and descent are rounded to whole pixels before
+            it is centred, which put the baseline up to 0.73px from where
+            centred capitals put it (at 24px: 14.5 against 15.23); trimmed, it
+            lands within 0.06px. On screen, averaged over eight sub-pixel
+            positions, the ink leaned 0.66px high at 24px, 0.44px at 28px and
+            0.27px low at 22px; now every size averages within 0.07px of the
+            middle. Any one face can still sit up to half a pixel off, because
+            the screen rounds text to its pixel grid wherever the tile falls.
+            A browser without `text-box` draws the old line box, as before.
+          */}
+          <span className="[text-box:trim-both_cap_alphabetic]">{initialsFor(label)}</span>
+        </BaseAvatar.Fallback>
       ) : (
-        <div className="w-full h-full bg-accent-muted flex items-center justify-center text-text-muted">
+        <BaseAvatar.Fallback render={<div />} className="w-full h-full bg-accent-muted flex items-center justify-center text-text-muted">
           <IconUserFilled size={Math.round(size * 0.5)} />
-        </div>
+        </BaseAvatar.Fallback>
       )}
-    </div>
+    </BaseAvatar.Root>
   )
 }

package/src/AvatarGroup.tsx

@@ -55,6 +55,7 @@ export function AvatarGroup({ members, size = 24 }: AvatarGroupProps) {
         <span
           key={i}
           className="relative flex rounded-sm"
+          /* eslint-disable-next-line no-restricted-syntax -- the ring's width is the `ring` prop, so it cannot be a class; its colour is the surface token */
           style={{ marginRight: -overlap, boxShadow: `0 0 0 ${ring}px var(--bg-surface)` }}
         >
           {/* Each face says whose it is: a stack stands on its own, with no

package/src/Breadcrumb.tsx

@@ -69,7 +69,7 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
   }, [measure, items])
 
   return (
-    <nav ref={navRef} aria-label="Breadcrumb" className={cn('flex min-w-0 items-center gap-1.5 text-[14px] leading-[140%]', className)}>
+    <nav ref={navRef} aria-label="Breadcrumb" className={cn('flex min-w-0 items-center gap-1.5 text-body-2', className)}>
       {items.map((item, index) => {
         const last = index === items.length - 1
         // The mono size is an arbitrary value (the caption token) because this
@@ -81,7 +81,7 @@ export function Breadcrumb({ items, className }: BreadcrumbProps) {
           // A mono crumb is a ref — the identity. It never gives up width to a
           // long name beside it (the LongName story always claimed "the ref
           // stays"; flexbox was squeezing it anyway until this line).
-          item.mono && 'shrink-0 font-mono text-[12px] leading-[120%]',
+          item.mono && 'shrink-0 font-mono text-caption',
           tone,
         )
         const setLabelRef = (el: HTMLElement | null) => {

package/src/Card.mdx

@@ -25,8 +25,10 @@ move it.
   hover.
 - `hover="fill"` — a card in a feed: it lights up when pointed at, so the light
   says which one you are on. `quietUntilHover` hides its hairline until then.
+- `hovered` — hold that look while the pointer is elsewhere: a card whose own
+  menu or picker is open stays lit, because the menu opens outside the card.
 - `selected` — the one you are on. `active` — the one being changed in place.
-  Neither answers the pointer.
+  Neither answers the pointer, and `hovered` changes neither.
 - `attention` — a hairline that asks to be looked at: `accent` for something
   new, `warning` for something urgent.
 - `unreadable` — it stands for something that could not be read: the hairline
@@ -60,8 +62,12 @@ import { Card } from '@estiva-app/ui'
 - With `href` it renders `Link`'s anchor, with every anchor prop passed through,
   so a router app takes the click and the address stays real.
 - Without `href`, a card that responds to a click gets `cursor-pointer` from its
-  `hover` and your `onClick`. Controls inside it should stop their own clicks
-  from reaching the card.
+  `hover` and your `onClick` — the selected one too, since it can open again;
+  the one being changed does not. Controls inside it should stop their own
+  clicks from reaching the card.
+- Keep a card lit while its menu is open by passing `hovered` from your own
+  state: set it when the pointer enters, and clear it when the pointer leaves
+  and nothing of the card's is open.
 
 ## Props
 

package/src/Card.stories.tsx

@@ -75,6 +75,9 @@ export const InAFeed: Story = {
   ),
 }
 
+/** Its menu is open: the pointer is on the menu, outside the card, and the card stays lit under it. */
+export const HeldWhileItsMenuIsOpen: Story = { args: { hover: 'fill', quietUntilHover: true, hovered: true, onClick: () => {}, className: 'p-3' } }
+
 /** Being changed in place: the selected fill and the accent hairline. */
 export const Active: Story = { args: { active: true, hover: 'fill' } }
 

package/src/Card.test.tsx

@@ -84,6 +84,47 @@ describe('Card', () => {
     expect(active.some((c) => c.startsWith('hover:'))).toBe(false)
   })
 
+  it('hovered holds the hover look without the pointer: a feed card stays lit, a link card keeps its stronger hairline', () => {
+    const feed = classesOf(card(<Card hover="fill" quietUntilHover hovered onClick={() => {}}>Item one</Card>))
+    expect(feed).toContain('bg-bg-hover')
+    expect(feed).toContain('border-border-default')
+    expect(feed).not.toContain('bg-bg-surface')
+    expect(feed).not.toContain('border-transparent')
+    cleanup()
+    const link = classesOf(card(<Card href="#" hovered>Item one</Card>))
+    expect(link).toContain('border-border-strong')
+    cleanup()
+    const inset = classesOf(card(<Card fill="inset" href="#" hovered>Item one</Card>))
+    expect(inset).toContain('border-border-default')
+    expect(inset).not.toContain('border-border-subtle')
+    cleanup()
+    // Nothing to hold on a card that does not answer the pointer.
+    const still = classesOf(card(<Card hovered>Item one</Card>))
+    expect(still).toContain('bg-bg-surface')
+    expect(still).not.toContain('bg-bg-hover')
+  })
+
+  it('hovered is ignored by the one you are on and the one being changed; attention still colours the hairline', () => {
+    const selected = classesOf(card(<Card hover="fill" hovered selected>Item one</Card>))
+    expect(selected).toContain('bg-bg-selected')
+    expect(selected).not.toContain('bg-bg-hover')
+    cleanup()
+    const active = classesOf(card(<Card hover="fill" hovered active>Item one</Card>))
+    expect(active).toContain('border-accent-primary')
+    expect(active).not.toContain('bg-bg-hover')
+    cleanup()
+    const urgent = classesOf(card(<Card hover="fill" quietUntilHover hovered attention="warning">Item one</Card>))
+    expect(urgent).toContain('bg-bg-hover')
+    expect(urgent).toContain('border-warning-muted')
+    expect(urgent).not.toContain('border-border-default')
+  })
+
+  it('the one you are on can still be clicked, and says so; the one being changed does not', () => {
+    expect(classesOf(card(<Card hover="fill" selected onClick={() => {}}>Item one</Card>))).toContain('cursor-pointer')
+    cleanup()
+    expect(classesOf(card(<Card hover="fill" active onClick={() => {}}>Item one</Card>))).not.toContain('cursor-pointer')
+  })
+
   it('attention recolours the hairline, at rest and on hover', () => {
     const classes = classesOf(card(<Card hover="fill" quietUntilHover attention="warning">Item one</Card>))
     expect(classes).toContain('border-warning-muted')

package/src/Card.tsx

@@ -44,6 +44,14 @@ const HAIRLINE_HOVER_CLASSES: Record<CardFill, string> = {
   none: 'hover:border-border-default',
 }
 
+/** The same step, held by `hovered` rather than by the pointer. */
+const HAIRLINE_HELD_CLASSES: Record<CardFill, string> = {
+  surface: 'border-border-strong',
+  elevated: 'border-border-strong',
+  inset: 'border-border-default',
+  none: 'border-border-default',
+}
+
 const ATTENTION_CLASSES: Record<CardAttention, string> = {
   accent: 'border-accent-muted hover:border-accent-muted',
   warning: 'border-warning-muted hover:border-warning-muted',
@@ -58,6 +66,12 @@ export interface CardProps extends ComponentPropsWithRef<'div'> {
   hover?: CardHover
   /** No hairline until it is pointed at — a row in a feed that shows its edge only when you are on it. */
   quietUntilHover?: boolean
+  /**
+   * Draw the hover look now, whatever the pointer does. For a card whose own menu or picker is open: the menu
+   * opens outside the card, so the pointer on it leaves the card, and the card would go dark under its own menu.
+   * Ignored while `selected` or `active`, like the pointer.
+   */
+  hovered?: boolean
   /** The one you are on: the selected fill, a subtle hairline, and no hover. */
   selected?: boolean
   /** Being changed in place: the selected fill with the accent hairline, and no hover. */
@@ -74,6 +88,7 @@ export function Card({
   href,
   hover = href ? 'hairline' : 'none',
   quietUntilHover = false,
+  hovered = false,
   selected = false,
   active = false,
   attention,
@@ -91,7 +106,10 @@ export function Card({
     quietUntilHover && 'border-transparent',
     !still && hover === 'hairline' && HAIRLINE_HOVER_CLASSES[fill],
     !still && hover === 'fill' && 'hover:bg-bg-hover hover:border-border-default',
-    !still && hover !== 'none' && !href && props.onClick && 'cursor-pointer',
+    !still && hovered && hover === 'hairline' && HAIRLINE_HELD_CLASSES[fill],
+    !still && hovered && hover === 'fill' && 'bg-bg-hover border-border-default',
+    // The one you are on can still be clicked (it opens again); the one being changed cannot.
+    !active && hover !== 'none' && !href && props.onClick && 'cursor-pointer',
     selected && 'bg-bg-selected border-border-subtle',
     active && 'bg-bg-selected border-accent-primary',
     !active && attention && ATTENTION_CLASSES[attention],

package/src/Checkbox.tsx

@@ -37,7 +37,7 @@ export interface CheckboxProps {
 
 function squareClasses(checked: boolean, disabled: boolean, interactive: boolean, className?: string) {
   return cn(
-    'inline-flex items-center justify-center size-4 shrink-0 rounded-[4px] border transition-colors',
+    'inline-flex items-center justify-center size-4 shrink-0 rounded-sm border transition-colors',
     checked ? 'bg-accent-primary border-accent-primary text-text-inverse' : 'bg-transparent border-border-strong hover:border-text-muted',
     disabled && 'opacity-50 pointer-events-none',
     interactive ? 'cursor-pointer' : 'pointer-events-none',

package/src/Chip.tsx

@@ -44,7 +44,7 @@ export function Chip({ type = 'neutral', label, leadingIcon, trailingIcon, class
         // the screenshot diff caught every descender cut off. `clip` is the
         // one overflow that leaves the other axis visible. A chip with no cap
         // draws exactly as before.
-        <span className="min-w-0 overflow-x-clip text-ellipsis whitespace-nowrap text-chip signal:font-mono signal:text-[10px] signal:font-semibold signal:tracking-[0.02em] signal:tabular-nums">{label}</span>
+        <span className="min-w-0 overflow-x-clip text-ellipsis whitespace-nowrap text-chip signal:font-mono signal:text-small signal:font-semibold signal:tracking-wide signal:tabular-nums">{label}</span>
       )}
       {trailingIcon && <span className="flex size-3 shrink-0 items-center justify-center">{trailingIcon}</span>}
     </div>

package/src/DialogShell.stories.tsx

@@ -82,7 +82,7 @@ export const WithHeaderContent: Story = {
         <Button variant="primary">Save</Button>
       </>
     ),
-    children: <p className="text-body-2 leading-[1.4] text-text-primary">The header is the caller's, and the ✕ is still the dialog's.</p>,
+    children: <p className="text-body-2 text-text-primary">The header is the caller's, and the ✕ is still the dialog's.</p>,
   },
 }
 

package/src/Divider.mdx

@@ -6,8 +6,9 @@ import * as DividerStories from './Divider.stories'
 # Divider
 
 A hairline in `border-subtle`. Horizontal it is inset 12px each side;
-`orientation="vertical"` stands it up to its row's height, no inset. It
-carries the `separator` role for assistive tech.
+`orientation="vertical"` stands it up to its row's height, no inset. It is
+Base UI's `Separator`, which gives it the `separator` role and its
+orientation for assistive tech.
 
 <Canvas of={DividerStories.Default} />
 

package/src/Divider.test.tsx

@@ -12,6 +12,21 @@ describe('Divider', () => {
     expect(screen.getByRole('separator').getAttribute('aria-orientation')).toBe('horizontal')
   })
 
+  it('is Base UI’s Separator: the orientation is also a data attribute, for both orientations', () => {
+    render(
+      <>
+        <Divider />
+        <Divider orientation="vertical" />
+        <Divider label="Today" />
+      </>,
+    )
+    const [horizontal, vertical, labelled] = screen.getAllByRole('separator')
+    expect(horizontal.getAttribute('data-orientation')).toBe('horizontal')
+    expect(vertical.getAttribute('aria-orientation')).toBe('vertical')
+    expect(vertical.getAttribute('data-orientation')).toBe('vertical')
+    expect(labelled.getAttribute('data-orientation')).toBe('horizontal')
+  })
+
   it('with a label, the separator is named by it and the words are drawn once', () => {
     render(<Divider label="New since you last read this" tone="warning" />)
     const rule = screen.getByRole('separator', { name: 'New since you last read this' })

package/src/Divider.tsx

@@ -1,10 +1,14 @@
+import { Separator } from '@base-ui/react/separator'
 import { cn } from './cn'
 
 /**
  * Peek's Divider (2026-08-28): a hairline in `border-subtle`, inset 12px each
  * side. Plus what Ship added: `orientation="vertical"` — the same hairline
- * standing up, stretching to its row's height, no inset — and the separator
- * role for assistive tech.
+ * standing up, stretching to its row's height, no inset.
+ *
+ * On Base UI's `Separator` since stage 6 of the migration (2026-09-14). It
+ * writes the `separator` role and `aria-orientation` this component used to
+ * write by hand, and adds `data-orientation`. Nothing it draws changed.
  */
 export interface DividerProps {
   orientation?: 'horizontal' | 'vertical'
@@ -29,22 +33,20 @@ export function Divider({ orientation = 'horizontal', label, tone = 'default', c
   if (label && orientation === 'horizontal') {
     const line = tone === 'warning' ? 'bg-warning-muted' : 'bg-border-subtle'
     return (
-      <div
-        role="separator"
-        aria-orientation="horizontal"
+      <Separator
+        orientation="horizontal"
         aria-label={label}
         className={cn('flex shrink-0 items-center gap-2 mx-3', className)}
       >
         <span aria-hidden="true" className={cn('h-px flex-1', line)} />
         <span className={cn('shrink-0 text-caption', tone === 'warning' ? 'text-warning-default' : 'text-text-muted')}>{label}</span>
         <span aria-hidden="true" className={cn('h-px flex-1', line)} />
-      </div>
+      </Separator>
     )
   }
   return (
-    <div
-      role="separator"
-      aria-orientation={orientation}
+    <Separator
+      orientation={orientation}
       // 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

package/src/EditableText.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
     placeholder: 'Add a title',
     label: 'Title',
     onCommit: () => true as boolean,
-    className: 'text-[16px] leading-[1.4] font-medium',
+    className: 'text-body-1 font-medium',
   },
   argTypes: { onCommit: { control: false } },
   decorators: [(Story) => <div className="w-80">{Story()}</div>],
@@ -44,7 +44,7 @@ export const Multiline: Story = {
     placeholder: 'Add a description',
     label: 'Description',
     multiline: true,
-    className: 'text-[14px] leading-[1.4]',
+    className: 'text-body-2',
   },
 }
 

package/src/EmptyState.mdx

@@ -18,8 +18,9 @@ alone and left-aligned when one section of a page is.
   bubble for one that matches the subject.
 - **`section`** — one section of a page is empty and the page has other
   things on it: no replies under an item, a search with no results. The
-  line alone, left-aligned, no icon. A section's emptiness is one line
-  among the page's content, not a stage of its own.
+  line alone, left-aligned, no icon, in the quiet look — 12px caption in
+  the muted colour, like a Field's helper line. A section's emptiness is
+  one line among the page's content, not a stage of its own.
 
 <Canvas of={EmptyStateStories.Section} />
 

package/src/EmptyState.stories.tsx

@@ -17,15 +17,19 @@ type Story = StoryObj<typeof meta>
 
 /** The `page` manner: the default icon over the caller's words, in the middle of its box both ways. */
 export const Page: Story = { decorators: [inBox] }
-/** The `section` manner: the words alone, left-aligned — one line in a page that has other things on it. */
-export const Section: Story = { args: { scope: 'section' }, decorators: [inBox] }
+// axe color-contrast is off on the two section stories until PLAN.md stage 0.10 is ruled: the section
+// line is muted caption text, 3.94:1 on --bg-base in signal (AA 4.5:1); 6.08:1 in ship.
+const sectionContrastDeferred = { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } }
+
+/** The `section` manner: the words alone, left-aligned, in the quiet caption — one line in a page that has other things on it. */
+export const Section: Story = { args: { scope: 'section' }, decorators: [inBox], parameters: sectionContrastDeferred }
 export const LongerMessage: Story = { args: { message: 'No items yet. Add one from any list.' }, decorators: [inBox] }
 export const CustomIcon: Story = { args: { icon: <IconLock size={16} stroke={1.5} />, message: 'Nothing you can read here yet.' }, decorators: [inBox] }
 
 /** One box, written once, holding the rows or the empty state: its padding places both, so the line starts where the first row does. */
 export const InsideTheRowsBox: Story = {
   args: { scope: 'section' },
-  parameters: { controls: { disable: true } },
+  parameters: { controls: { disable: true }, ...sectionContrastDeferred },
   render: (args) => {
     const box = 'flex h-[160px] w-[260px] flex-col gap-2 rounded-lg border border-border-default p-4'
     return (