@estiva-app/ui 0.12.10 → 0.13.1

package/src/InlineChip.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { IconSquareRounded } from '@tabler/icons-react'
+import { InlineChip } from './InlineChip'
+
+const meta = {
+  title: 'Components/InlineChip',
+  component: InlineChip,
+  args: { tone: 'neutral', children: 'Label' },
+  argTypes: {
+    tone: { control: 'inline-radio', options: ['neutral', 'person', 'urgent', 'quiet'] },
+    icon: { control: false },
+    href: { control: 'text' },
+  },
+  // A chip is a word in a sentence, so every canvas sets it in one, at the body text's size.
+  render: (args) => (
+    <p className="max-w-[480px] text-body-2 text-text-primary">
+      The sentence runs up to <InlineChip {...args} /> and carries on after it, on the same line.
+    </p>
+  ),
+} satisfies Meta<typeof InlineChip>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Anything that is not a person. */
+export const Neutral: Story = {}
+
+// axe color-contrast is off on the stories below that draw the person or quiet
+// tone, until PLAN.md stage 0.10 is ruled. Computed 2026-09-14: the person
+// chip reads 2.70:1 in ship (the accent on its wash — the brand Chip's number)
+// and the quiet chip 3.25:1 in signal (muted on the active fill); AA is 4.5:1.
+const contrastDeferred = { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } }
+
+export const Person: Story = { args: { tone: 'person', children: '@Ana Duarte' }, parameters: contrastDeferred }
+
+/** A person, called urgently. */
+export const Urgent: Story = { args: { tone: 'urgent', children: '@Ana Duarte' } }
+
+/** A reference nobody could resolve: smaller, mono, muted — still there, never an error. */
+export const Quiet: Story = { args: { tone: 'quiet', children: '3f9a…c21e' }, parameters: contrastDeferred }
+
+/** The icon sits first, in a 16px box. */
+export const WithIcon: Story = { args: { icon: <IconSquareRounded size={16} stroke={1.5} />, children: 'Item one' } }
+
+/** With `href` the chip is a link; without one it is a label. */
+export const AsLink: Story = { args: { href: '#', children: 'Item one' } }
+
+/** Every tone in one paragraph that wraps: each line stays one line high, and the chips' words sit level with the text around them. */
+export const InRunningText: Story = {
+  parameters: { controls: { disable: true }, ...contrastDeferred },
+  render: () => (
+    <p className="max-w-[360px] text-body-2 text-text-primary">
+      A paragraph can hold <InlineChip>Item one</InlineChip> beside{' '}
+      <InlineChip icon={<IconSquareRounded size={16} stroke={1.5} />}>Item two</InlineChip>, ask{' '}
+      <InlineChip tone="person">@Ana Duarte</InlineChip> or <InlineChip tone="urgent">@Ana Duarte</InlineChip> to look, and
+      point at <InlineChip tone="quiet">3f9a…c21e</InlineChip> when nothing more is known — and every line keeps its height.
+    </p>
+  ),
+}

package/src/InlineChip.test.tsx

@@ -0,0 +1,81 @@
+// @vitest-environment jsdom
+/**
+ * What the InlineChip page claims, pinned: without `href` it is a label, with
+ * one it is a link a router can take; every tone keeps the shape and its own
+ * size and colour through `cn()`; the icon sits in its 16px box; and the class
+ * function a string-only renderer uses gives the same classes as the component.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { INLINE_CHIP_CLASSES, INLINE_CHIP_TONE_CLASSES, InlineChip, inlineChipClassName } from './InlineChip'
+
+afterEach(cleanup)
+
+const classesOf = (el: Element) => el.getAttribute('class')?.split(' ').filter(Boolean) ?? []
+
+describe('InlineChip', () => {
+  it('without href it is a label, not a link', () => {
+    render(<InlineChip>Label</InlineChip>)
+    const chip = screen.getByText('Label')
+    expect(chip.tagName).toBe('SPAN')
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('with href it is a link, and a router app takes the click with the href intact', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(
+      <InlineChip href="/somewhere" onClick={onClick}>
+        Label
+      </InlineChip>,
+    )
+    const link = screen.getByRole('link', { name: 'Label' })
+    await userEvent.click(link)
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(link.getAttribute('href')).toBe('/somewhere')
+  })
+
+  it('is one line high and pinned to the top of the line, in every tone', () => {
+    for (const tone of Object.keys(INLINE_CHIP_TONE_CLASSES) as (keyof typeof INLINE_CHIP_TONE_CLASSES)[]) {
+      const classes = inlineChipClassName(tone).split(' ')
+      expect(classes).toContain('align-top')
+      expect(classes).toContain('mx-0.5')
+      // One height only: 1.4em of the body size, or the same 19.6px written out where the text is smaller.
+      const heights = classes.filter((c) => c.startsWith('h-'))
+      expect(heights).toEqual([tone === 'quiet' ? 'h-[19.6px]' : 'h-[1.4em]'])
+    }
+  })
+
+  it('each tone keeps its size and its colour through cn()', () => {
+    const neutral = inlineChipClassName('neutral').split(' ')
+    expect(neutral).toContain('text-body-2')
+    expect(neutral).toContain('text-text-primary')
+    const person = inlineChipClassName('person').split(' ')
+    expect(person).toContain('text-body-2')
+    expect(person).toContain('text-accent-primary')
+    const urgent = inlineChipClassName('urgent').split(' ')
+    expect(urgent).toContain('text-warning-default')
+    // quiet is smaller: its caption size replaces the body size, and its colour survives beside it
+    const quiet = inlineChipClassName('quiet').split(' ')
+    expect(quiet).toContain('text-caption')
+    expect(quiet).not.toContain('text-body-2')
+    expect(quiet).toContain('text-text-muted')
+  })
+
+  it('the component and the class function give the same classes', () => {
+    render(
+      <InlineChip tone="person" className="max-w-[24ch]">
+        Label
+      </InlineChip>,
+    )
+    expect(classesOf(screen.getByText('Label'))).toEqual(inlineChipClassName('person', 'max-w-[24ch]').split(' '))
+    expect(INLINE_CHIP_CLASSES.split(' ').every((c) => classesOf(screen.getByText('Label')).includes(c))).toBe(true)
+  })
+
+  it('draws the icon first, in its 16px box', () => {
+    render(<InlineChip icon={<svg data-testid="icon" />}>Label</InlineChip>)
+    const box = screen.getByTestId('icon').parentElement!
+    expect(classesOf(box)).toEqual(expect.arrayContaining(['size-4', 'shrink-0']))
+    expect(box.parentElement!.firstElementChild).toBe(box)
+  })
+})

package/src/InlineChip.tsx

@@ -0,0 +1,90 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A word in a sentence that stands for something: a person, a place, a thing
+ * written into running text. One line high, level with the words around it.
+ *
+ * The shape is Peek's inline chip (D67, Peek PR #206, 2026-09-13), class for
+ * class, moved into the package so both apps draw one (UIG-27). Three things
+ * changed on the way, all ruled by Katerina:
+ *
+ * - the person tone is `person`, not `mention` — every chip here is a
+ *   mention of something;
+ * - the alignment is a class (`align-top h-[1.4em]`), not a `style` object,
+ *   so it is part of the class list like every other size in the package;
+ * - a chip that leads somewhere takes `href` and `onClick`, the way `NavItem`
+ *   does: the package draws an anchor, the app's router takes the click.
+ *
+ * **Why `align-top` and `1.4em`.** `1.4em` is the body text's line height,
+ * so the chip is exactly one line tall; `vertical-align: top` pins it to the
+ * line box, which keeps the line at 19.6px and the chip's words level with
+ * the sentence's, with or without an icon. Measured in Peek on 2026-09-13:
+ * `text-bottom` made the line 21.2px and lifted the chip's words 1.6px;
+ * `baseline` lifted them 3.8px once an icon came first.
+ */
+
+/** The shape every tone shares. Exported for a rich-text editor that renders chips from strings. */
+export const INLINE_CHIP_CLASSES =
+  'inline-flex h-[1.4em] items-center gap-1 rounded-sm px-1 mx-0.5 align-top text-body-2 font-normal select-none'
+
+/** What a chip is made of, by what it stands for. */
+export const INLINE_CHIP_TONE_CLASSES = {
+  /** A thing or a place — anything that is not a person. */
+  neutral: 'bg-bg-active text-text-primary',
+  /** A person. */
+  person: 'bg-accent-muted text-accent-primary',
+  /** A person, called urgently. */
+  urgent: 'bg-warning-muted text-warning-default',
+  /**
+   * A reference nobody could resolve — still a mention, just an anonymous one.
+   * Its height is the body line's 19.6px written out, because `1.4em` here is
+   * the caption's em: 16.8px, with the letters 1.8px above the sentence's
+   * baseline. At 19.6px they sit 0.4px off it (measured 2026-09-14; Peek's
+   * copy of this chip still has the 16.8px box).
+   */
+  quiet: 'h-[19.6px] bg-bg-active text-text-muted font-mono text-caption',
+} as const
+
+export type InlineChipTone = keyof typeof INLINE_CHIP_TONE_CLASSES
+
+/** The chip's classes for a tone, with anything the caller adds. For renderers that cannot use the component. */
+export function inlineChipClassName(tone: InlineChipTone, className?: string) {
+  return cn(INLINE_CHIP_CLASSES, INLINE_CHIP_TONE_CLASSES[tone], className)
+}
+
+export interface InlineChipProps extends Omit<ComponentPropsWithRef<'a'>, 'children'> {
+  /** What the chip stands for. Default `neutral`. */
+  tone?: InlineChipTone
+  /** Drawn before the label in a 16px box: a 16px icon, or a 14px one it centres. */
+  icon?: ReactNode
+  /**
+   * Where the chip leads. With it the chip is an anchor; without it, a span.
+   * A router app passes `onClick` too, and navigates there itself.
+   */
+  href?: string
+  children: ReactNode
+}
+
+export function InlineChip({ tone = 'neutral', icon, href, className, children, ...props }: InlineChipProps) {
+  const body = (
+    <>
+      {icon && <span className="flex size-4 shrink-0 items-center justify-center text-text-secondary">{icon}</span>}
+      {children}
+    </>
+  )
+  const classes = inlineChipClassName(tone, className)
+  // Without somewhere to go it is a label, and a label is not a link.
+  if (href === undefined) {
+    return (
+      <span className={classes} {...(props as ComponentPropsWithRef<'span'>)}>
+        {body}
+      </span>
+    )
+  }
+  return (
+    <a href={href} className={classes} {...props}>
+      {body}
+    </a>
+  )
+}

package/src/Link.mdx

@@ -0,0 +1,59 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LinkStories from './Link.stories'
+
+<Meta of={LinkStories} />
+
+# Link
+
+A link, in one of four looks. It is a real anchor with a real address, and
+the app decides how it navigates.
+
+<Canvas of={LinkStories.AllVariants} />
+
+## When
+
+- **`text`** — a link written inside text: the info colour, always
+  underlined, dimming on hover.
+- **`quiet`** — a title or a time that is also a link. It takes the colour and
+  size of the text it sits in, and underlines on hover.
+- **`underlined`** — a short "open it there" beside a note. It takes the
+  note's colour, is always underlined, and brightens on hover.
+- **`plain`** — a box or a row that is a link as a whole. No look of its own:
+  what it wraps draws itself.
+- `external` — another site or app: it opens in a new tab, with
+  `noopener noreferrer`.
+
+## When not
+
+- An action — something happens, nothing is navigated to → **Button**.
+- A row of a sidebar → **NavItem**. A tile of a rail → **RailItem**.
+- The trail back up → **Breadcrumb**.
+- A word standing for a person or a thing, drawn in a small box → **InlineChip**
+  with `href`.
+
+## How
+
+```tsx
+import { Link } from '@estiva-app/ui'
+
+<p className="text-body-2">
+  Read <Link href="https://example.com" external>the guide</Link> first.
+</p>
+
+<h3 className="text-body-2 font-semibold text-text-primary">
+  <Link href={itemUrl} variant="quiet" onClick={navigate}>Item one</Link>
+</h3>
+```
+
+- It renders a plain anchor and passes every anchor prop through. A router app
+  passes `onClick`, prevents the default and navigates; the `href` stays a real
+  address, so a modified click or a new tab still works.
+- `quiet` and `underlined` set no size and no colour at rest: put them inside
+  the text whose look they should take.
+- `plain` wraps a block: give the Link `className="block"` and let the child
+  draw the border, the fill and the hover.
+- If your router also exports a `Link`, rename one of them on import.
+
+## Props
+
+<Controls of={LinkStories.Text} />

package/src/Link.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Link } from './Link'
+
+const meta = {
+  title: 'Navigation/Link',
+  component: Link,
+  args: { href: '#', variant: 'text', external: false, children: 'a link' },
+  argTypes: {
+    variant: { control: 'inline-radio', options: ['text', 'quiet', 'underlined', 'plain'] },
+  },
+} satisfies Meta<typeof Link>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** Inside written text: the info colour, always underlined. Hover dims it. */
+export const Text: Story = {
+  render: (args) => (
+    <p className="max-w-[480px] text-body-2 text-text-primary">
+      A sentence can hold <Link {...args} /> in the middle of it, and the words around it read on.
+    </p>
+  ),
+}
+
+/** A title, or a small time, that is also a link: it keeps its text's colour and size, and underlines on hover. */
+export const Quiet: Story = {
+  args: { variant: 'quiet', children: 'Item one' },
+  render: (args) => (
+    <div className="flex flex-col gap-2">
+      <p className="text-body-2 font-semibold text-text-primary">
+        <Link {...args} />
+      </p>
+      <p className="text-caption text-text-secondary">
+        <Link {...args}>2:14 PM</Link>
+      </p>
+    </div>
+  ),
+}
+
+/** Beside a note, a short way to open the thing somewhere else: the note's colour, always underlined. Hover brightens it. */
+export const Underlined: Story = {
+  args: { variant: 'underlined', external: true, children: 'Open it there ↗' },
+  render: (args) => (
+    <p className="max-w-[480px] text-caption text-text-secondary">
+      This can’t be shown here. <Link {...args} />
+    </p>
+  ),
+}
+
+/** No look of its own: what it wraps draws itself — a box, a row. */
+export const Plain: Story = {
+  args: { variant: 'plain', children: undefined },
+  render: (args) => (
+    <Link {...args} className="block w-[280px]">
+      <div className="rounded-lg border border-border-default bg-bg-surface p-3 text-body-2 text-text-primary transition-colors hover:border-border-strong">
+        Item one
+      </div>
+    </Link>
+  ),
+}
+
+/** Another site or app: a new tab, and `noopener noreferrer`. It looks the same; the difference is where it opens. */
+export const External: Story = {
+  args: { external: true, children: 'a page elsewhere' },
+  render: (args) => (
+    <p className="max-w-[480px] text-body-2 text-text-primary">
+      Read <Link {...args} /> in a new tab.
+    </p>
+  ),
+}
+
+/** The four looks, each where it belongs. */
+export const AllVariants: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex max-w-[480px] flex-col gap-4">
+      <p className="text-body-2 text-text-primary">
+        <span className="text-text-secondary">text — </span>a sentence with <Link href="#">a link</Link> in it.
+      </p>
+      <p className="text-body-2 font-semibold text-text-primary">
+        <span className="font-normal text-text-secondary">quiet — </span>
+        <Link href="#" variant="quiet">
+          Item one
+        </Link>
+      </p>
+      <p className="text-caption text-text-secondary">
+        underlined — This can’t be shown here.{' '}
+        <Link href="#" variant="underlined" external>
+          Open it there ↗
+        </Link>
+      </p>
+      <div className="flex flex-col gap-1">
+        <span className="text-body-2 text-text-secondary">plain —</span>
+        <Link href="#" variant="plain" className="block w-[280px]">
+          <div className="rounded-lg border border-border-default bg-bg-surface p-3 text-body-2 text-text-primary transition-colors hover:border-border-strong">
+            Item one
+          </div>
+        </Link>
+      </div>
+    </div>
+  ),
+}

package/src/Link.test.tsx

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+/**
+ * What the Link page claims, pinned: it is a real anchor with a real address;
+ * `external` opens a new tab that cannot reach back; a router app takes the
+ * click through `onClick` and the address survives it; each look is its own
+ * class list and `plain` carries none; a ref reaches the anchor.
+ */
+import { createRef } from 'react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Link } from './Link'
+
+afterEach(cleanup)
+
+const classesOf = (el: Element) => el.getAttribute('class')?.split(' ').filter(Boolean) ?? []
+
+describe('Link', () => {
+  it('is an anchor with its address', () => {
+    render(<Link href="/documents">Documents</Link>)
+    const link = screen.getByRole('link', { name: 'Documents' })
+    expect(link.tagName).toBe('A')
+    expect(link.getAttribute('href')).toBe('/documents')
+  })
+
+  it('stays in the same tab unless it is external', () => {
+    render(<Link href="/documents">Documents</Link>)
+    const link = screen.getByRole('link', { name: 'Documents' })
+    expect(link.getAttribute('target')).toBeNull()
+    expect(link.getAttribute('rel')).toBeNull()
+  })
+
+  it('external opens a new tab that cannot reach back into this page', () => {
+    render(
+      <Link href="https://example.com" external>
+        Example
+      </Link>,
+    )
+    const link = screen.getByRole('link', { name: 'Example' })
+    expect(link.getAttribute('target')).toBe('_blank')
+    expect(link.getAttribute('rel')).toBe('noopener noreferrer')
+  })
+
+  it('a router app takes the click through onClick, and the href stays a real address', async () => {
+    const onClick = vi.fn((event: { preventDefault: () => void }) => event.preventDefault())
+    render(
+      <Link href="/documents" onClick={onClick}>
+        Documents
+      </Link>,
+    )
+    await userEvent.click(screen.getByRole('link', { name: 'Documents' }))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(screen.getByRole('link', { name: 'Documents' }).getAttribute('href')).toBe('/documents')
+  })
+
+  it('text is the info colour, always underlined, and is the default', () => {
+    render(<Link href="#">Label</Link>)
+    const classes = classesOf(screen.getByRole('link'))
+    expect(classes).toContain('text-info-default')
+    expect(classes).toContain('underline')
+    expect(classes).toContain('underline-offset-2')
+  })
+
+  it('quiet sets no colour and no size of its own, and underlines on hover', () => {
+    render(
+      <Link href="#" variant="quiet">
+        Label
+      </Link>,
+    )
+    expect(classesOf(screen.getByRole('link'))).toEqual(['hover:underline'])
+  })
+
+  it('underlined sets no colour at rest, is always underlined, and brightens on hover', () => {
+    render(
+      <Link href="#" variant="underlined">
+        Label
+      </Link>,
+    )
+    expect(classesOf(screen.getByRole('link'))).toEqual(['underline', 'underline-offset-2', 'hover:text-text-primary'])
+  })
+
+  it('plain carries no class at all, so what it wraps draws itself', () => {
+    render(
+      <Link href="#" variant="plain">
+        Label
+      </Link>,
+    )
+    expect(classesOf(screen.getByRole('link'))).toEqual([])
+  })
+
+  it('a ref reaches the anchor', () => {
+    const ref = createRef<HTMLAnchorElement>()
+    render(
+      <Link href="#" ref={ref}>
+        Label
+      </Link>,
+    )
+    expect(ref.current?.tagName).toBe('A')
+  })
+})

package/src/Link.tsx

@@ -0,0 +1,58 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { cn } from './cn'
+
+/**
+ * A link: an anchor with one of four looks, and nothing else of its own.
+ *
+ * It exists because both apps hand-wrote every link they have — 18 raw `<a>`
+ * on 13 September 2026, in three jobs (UIG-27). The looks are the ones those
+ * links already had, reduced by Katerina's ruling:
+ *
+ * - `text` — a link inside written text: the info colour, always underlined,
+ *   dimming on hover. The look a link in a body of text already had.
+ * - `quiet` — a title or a timestamp that is also a link. It takes the colour
+ *   and size of the text it sits in and underlines on hover. Two looks that
+ *   differed only in their text became this one (her ruling, 13 September).
+ * - `underlined` — a short "open it elsewhere" beside a note. It takes the
+ *   note's colour, is always underlined, and brightens on hover. A dotted
+ *   and a solid version became this one, solid (her ruling, 13 September).
+ * - `plain` — no look at all: a card or a row that is a link draws itself.
+ *
+ * **Navigation is the app's.** The package cannot know a router, so like
+ * `NavItem` it renders a real anchor and passes every anchor prop through: a
+ * router app hands in `onClick`, prevents the default and navigates, and the
+ * `href` stays a real address for a modified click or a new tab.
+ */
+export type LinkVariant = 'text' | 'quiet' | 'underlined' | 'plain'
+
+const VARIANT_CLASSES: Record<LinkVariant, string> = {
+  text: 'text-info-default underline underline-offset-2 hover:opacity-80',
+  quiet: 'hover:underline',
+  underlined: 'underline underline-offset-2 hover:text-text-primary',
+  plain: '',
+}
+
+export interface LinkProps extends ComponentPropsWithRef<'a'> {
+  href: string
+  /** Default `text`. */
+  variant?: LinkVariant
+  /**
+   * Another site, or another app: opens in a new tab, with `noopener
+   * noreferrer` so the page it opens cannot reach back into this one.
+   */
+  external?: boolean
+  children: ReactNode
+}
+
+export function Link({ href, variant = 'text', external = false, className, children, ...props }: LinkProps) {
+  return (
+    <a
+      href={href}
+      {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+      className={cn(VARIANT_CLASSES[variant], className)}
+      {...props}
+    >
+      {children}
+    </a>
+  )
+}

package/src/Person.stories.tsx

@@ -3,7 +3,7 @@ import { Person } from './Person'
 
 /** A face beside a name — never a key. */
 const meta = {
-  title: 'Primitives/Person',
+  title: 'Components/Person',
   component: Person,
   args: { name: 'Ana Duarte', size: 20 },
 } satisfies Meta<typeof Person>

package/src/PersonTrigger.stories.tsx

@@ -3,7 +3,7 @@ import { PersonTrigger } from './PersonTrigger'
 
 /** The person, as the button that opens the account menu. The menu itself stays in the app. */
 const meta = {
-  title: 'Primitives/PersonTrigger',
+  title: 'Components/PersonTrigger',
   component: PersonTrigger,
   args: { name: 'Ana Duarte', open: false, compact: false },
 } satisfies Meta<typeof PersonTrigger>

package/src/ProgressBar.mdx

@@ -0,0 +1,47 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as ProgressBarStories from './ProgressBar.stories'
+
+<Meta of={ProgressBarStories} />
+
+# ProgressBar
+
+How much of something is done: a thin rounded track with a success-coloured
+fill.
+
+<Canvas of={ProgressBarStories.WithWords} />
+
+## When
+
+- **`default`** — 6px, the success colour: a bar someone reads, with the words
+  printed beside it.
+- **`quiet`** — 4px, the muted success colour: a glance on the same line as a
+  count.
+
+<Canvas of={ProgressBarStories.Quiet} />
+
+## When not
+
+- Something still loading, with no amount to show → **Skeleton**.
+- A state with a verdict rather than an amount → **Chip**.
+
+## How
+
+```tsx
+import { ProgressBar } from '@estiva-app/ui'
+
+<ProgressBar value={done} max={total} label="Items done" />
+<span className="text-caption text-text-muted">{done} of {total} done</span>
+```
+
+- `label` is required: it is the bar's accessible name. A screen reader hears
+  the name and the share as a percentage; print the counts beside the bar for
+  everyone else.
+- A value above `max` fills the bar and no further. `max={0}` is an empty bar.
+- It is built on Base UI's `Progress`, which owns the `progressbar` role and
+  its numbers. Do not nest it inside a button: the bar's name would become part
+  of the button's.
+- `className` is for placement: a width, a margin, `flex-1` in a row.
+
+## Props
+
+<Controls of={ProgressBarStories.Default} />

package/src/ProgressBar.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { ProgressBar } from './ProgressBar'
+
+const meta = {
+  title: 'Feedback/ProgressBar',
+  component: ProgressBar,
+  args: { value: 10, max: 14, label: 'Items done', variant: 'default' },
+  argTypes: { variant: { control: 'inline-radio', options: ['default', 'quiet'] } },
+  decorators: [(Story) => <div className="w-[346px]">{Story()}</div>],
+} satisfies Meta<typeof ProgressBar>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** 6px, the success colour: a bar someone reads. */
+export const Default: Story = {}
+
+/** The bar, then the words that say it. */
+export const WithWords: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-2">
+      <ProgressBar {...args} />
+      <span className="text-caption tabular-nums text-text-muted">
+        {args.value} of {args.max} done
+      </span>
+    </div>
+  ),
+  // axe color-contrast is off here until PLAN.md stage 0.10 is ruled: the words are
+  // muted caption text, 3.94:1 in signal (computed 2026-09-14; AA 4.5:1) — the same
+  // number NavItem's count is excepted for.
+  parameters: { a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } } },
+}
+
+/** 4px, the muted success colour: a glance, on the same line as a count — a caption label, 12px before the bar. */
+export const Quiet: Story = {
+  args: { variant: 'quiet', value: 3, max: 4 },
+  render: (args) => (
+    <div className="flex items-center gap-3">
+      <span className="shrink-0 text-caption text-text-secondary">
+        Items ({args.value}/{args.max})
+      </span>
+      <ProgressBar {...args} className="flex-1" />
+    </div>
+  ),
+}
+
+export const Empty: Story = { args: { value: 0, max: 14 } }
+export const Complete: Story = { args: { value: 14, max: 14 } }