@estiva-app/ui 0.13.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.13.1",
+  "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/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 (

package/src/EmptyState.test.tsx

@@ -31,6 +31,21 @@ describe('EmptyState', () => {
     expect(line.className).not.toContain('text-center')
   })
 
+  it('a section is the quiet line: caption size, muted colour (Katerina, 2026-09-15)', () => {
+    render(<EmptyState scope="section" message="Nothing here yet." />)
+    const classes = screen.getByText('Nothing here yet.').className.split(' ')
+    expect(classes).toContain('text-caption')
+    expect(classes).toContain('text-text-muted')
+    expect(classes).not.toContain('text-body-2')
+    expect(classes).not.toContain('text-text-secondary')
+  })
+
+  it('a caller’s placement class does not take the quiet look away', () => {
+    render(<EmptyState scope="section" className="py-8" message="Nothing here yet." />)
+    const classes = screen.getByText('Nothing here yet.').className.split(' ')
+    expect(classes).toEqual(expect.arrayContaining(['text-caption', 'text-text-muted', 'py-8']))
+  })
+
   it('a section carries no space of its own, so the box it sits in decides where it starts', () => {
     // Katerina, 2026-09-14: the box is written once and holds the rows or the empty
     // state; the empty state is never padded. So it may carry no padding or margin.

package/src/EmptyState.tsx

@@ -15,6 +15,9 @@ import { cn } from './cn'
  * - `section` — one section of a page is empty, and the page has other
  *   things on it: the line alone, left-aligned, no icon. A section's
  *   emptiness is a line among the page's content, not a stage of its own.
+ *   It is the quiet line — caption size in the muted colour, as a Field's
+ *   helper line is — so beside rows it reads as "nothing here", not as one
+ *   more row (Katerina, 2026-09-15: "not that intense", "smaller font").
  *
  * The message is the caller's — a shared component has no words of its own
  * for what is missing.
@@ -30,7 +33,7 @@ export interface EmptyStateProps {
 
 export function EmptyState({ icon, message, scope = 'page', className }: EmptyStateProps) {
   if (scope === 'section') {
-    return <p className={cn('text-body-2 text-text-secondary', className)}>{message}</p>
+    return <p className={cn('text-caption text-text-muted', className)}>{message}</p>
   }
   return (
     <div className={cn('flex flex-1 flex-col items-center justify-center gap-2', className)}>

package/src/IconButton.stories.tsx

@@ -41,7 +41,7 @@ export const AllVariants: Story = {
           <IconButton variant={variant} disabled aria-label="Settings">
             <IconSettings className="size-4" stroke={1.5} />
           </IconButton>
-          <span className="text-[12px] leading-[120%] text-text-muted">{variant}</span>
+          <span className="text-caption text-text-muted">{variant}</span>
         </div>
       ))}
     </div>

package/src/Kbd.tsx

@@ -30,9 +30,9 @@ 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-bg-wash signal:font-mono signal:text-[10px]',
-        'ship:border-b-2 ship:pt-[2px] ship:pb-px ship:bg-bg-wash ship:font-mono ship:text-[10px]',
+        '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-caption text-text-secondary',
+        'signal:border-b-2 signal:pt-[2px] signal:pb-px signal:bg-bg-wash signal:font-mono signal:text-small',
+        'ship:border-b-2 ship:pt-[2px] ship:pb-px ship:bg-bg-wash ship:font-mono ship:text-small',
         className,
       )}
     >

package/src/Menu.stories.tsx

@@ -72,7 +72,7 @@ export const WithARow: Story = {
   render: () => (
     <MenuPanel className="w-64">
       <MenuRow>
-        <span className="min-w-0 flex-1 truncate text-[14px] leading-[140%] text-text-primary">Item one</span>
+        <span className="min-w-0 flex-1 truncate text-body-2 text-text-primary">Item one</span>
         <SectionLabel className="text-text-secondary">Label</SectionLabel>
       </MenuRow>
       <Divider className="my-1" />
@@ -134,7 +134,7 @@ export const OnACard: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex w-[420px] items-start gap-3 rounded-lg border border-border-default p-3">
-      <span className="min-w-0 flex-1 text-[14px] leading-[140%] text-text-primary">
+      <span className="min-w-0 flex-1 text-body-2 text-text-primary">
         A card. Press the control at the end of the row, then walk down the rows and out to the submenu.
       </span>
       <Menu

package/src/Menu.tsx

@@ -426,10 +426,10 @@ function MenuItemBody({ label, children, size = 'default', description, leading,
           colour. Ship's copy said `text-sm`, which was never the ramp. */}
       {children ?? (
         <span className={cn('flex min-w-0 flex-1 flex-col', size === 'tall' && 'gap-[2px]')}>
-          <span className={cn('truncate text-[14px] leading-[140%]', destructive ? 'text-error-default' : 'text-text-primary')}>
+          <span className={cn('truncate text-body-2', destructive ? 'text-error-default' : 'text-text-primary')}>
             {label}
           </span>
-          {description && <span className="truncate text-[12px] leading-[120%] text-text-secondary">{description}</span>}
+          {description && <span className="truncate text-caption text-text-secondary">{description}</span>}
         </span>
       )}
       {(edge || hint) && (
@@ -538,7 +538,7 @@ export function EnterHint({ target }: { target?: string }) {
     <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 className="text-menu signal:font-mono signal:text-small signal:tracking-wider">{target}</span>
       )}
     </span>
   )

package/src/Popover.stories.tsx

@@ -167,7 +167,7 @@ export const FromASelection: Story = {
             can, which is the real case; `-1` gives this one the same property
             without adding a Tab stop. Without it focus is left on the document
             body when the panel closes — measured. */}
-        <p ref={body} tabIndex={-1} onMouseUp={read} onKeyUp={readOnKey} className="text-[14px] leading-[1.6] text-text-primary outline-none">
+        <p ref={body} tabIndex={-1} onMouseUp={read} onKeyUp={readOnKey} className="text-body-2 text-text-primary outline-none">
           Select any part of this sentence with the pointer, and a panel appears
           above the selection rather than beside a button — because a selection
           is not a control and there is no trigger to hang from.