@estiva-app/ui 0.7.0 → 0.9.0

package/src/Tabs.mdx

@@ -43,10 +43,19 @@ import { Tabs } from '@estiva-app/ui'
 ```
 
 - Generic over the id type — `onChange` hands back your union, not a
-  string.
-- It renders `role="tablist"` / `role="tab"` with `aria-selected`;
-  switching is by click (there is no arrow-key roving), and wiring the
-  panels — what shows for the active tab — is the caller's.
+  string, and only for a person's choice.
+- Built on Base UI Tabs: `role="tablist"` / `role="tab"` with
+  `aria-selected`, one Tab stop for the row, arrow keys between the tabs.
+  Wiring the panels — what shows for the active tab — is the caller's.
+- `className` lands on the outer box, around the row.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| Tab | Into the row, onto the selected tab; out of it on the next press. |
+| ← → | Select the previous / next tab. The ends wrap. |
+| Home / End | Select the first / last tab. |
 
 ## Props
 

package/src/Tabs.test.tsx

@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+/**
+ * What the Tabs page claims about the keyboard, pinned. The keys come from
+ * Base UI's Tabs (stage 1 of the migration); before it, every tab was its own
+ * Tab stop and the arrow keys did nothing.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { Tabs, type TabDef } from './Tabs'
+
+afterEach(cleanup)
+
+type Id = 'one' | 'two' | 'three'
+const THREE: TabDef<Id>[] = [
+  { id: 'one', label: 'One' },
+  { id: 'two', label: 'Two', count: 3 },
+  { id: 'three', label: 'Three' },
+]
+
+/** A parent that owns the state, as every caller does. */
+function Harness({ onChange, initial = 'one' }: { onChange?: (id: Id) => void; initial?: Id }) {
+  const [active, setActive] = useState<Id>(initial)
+  return (
+    <>
+      <button type="button">Before</button>
+      <Tabs
+        tabs={THREE}
+        active={active}
+        onChange={(id) => {
+          onChange?.(id)
+          setActive(id)
+        }}
+      />
+      <button type="button">After</button>
+    </>
+  )
+}
+
+const tab = (name: string) => screen.getByRole('tab', { name: new RegExp(`^${name}`) })
+const selected = (name: string) => tab(name).getAttribute('aria-selected')
+const tabindex = (name: string) => tab(name).getAttribute('tabindex')
+const focused = () => document.activeElement
+
+describe('Tabs', () => {
+  it('marks the active tab selected, and makes it the only Tab stop in the row', async () => {
+    const user = userEvent.setup()
+    render(<Harness />)
+    expect(selected('One')).toBe('true')
+    expect(selected('Two')).toBe('false')
+    expect(tabindex('One')).toBe('0')
+    expect(tabindex('Two')).toBe('-1')
+    expect(tabindex('Three')).toBe('-1')
+
+    await user.tab()
+    expect(focused()).toBe(screen.getByRole('button', { name: 'Before' }))
+    await user.tab()
+    expect(focused()).toBe(tab('One'))
+    await user.tab()
+    expect(focused()).toBe(screen.getByRole('button', { name: 'After' }))
+  })
+
+  it('selects on click and hands back the id', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onChange={onChange} />)
+    await user.click(tab('Two'))
+    expect(onChange).toHaveBeenCalledTimes(1)
+    expect(onChange).toHaveBeenCalledWith('two')
+    expect(selected('Two')).toBe('true')
+    expect(selected('One')).toBe('false')
+  })
+
+  it('selects the next and previous tab with the arrow keys, wrapping at the ends', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Harness onChange={onChange} />)
+    await user.click(tab('One'))
+    onChange.mockClear()
+
+    await user.keyboard('{ArrowRight}')
+    expect(focused()).toBe(tab('Two'))
+    expect(selected('Two')).toBe('true')
+    await user.keyboard('{ArrowRight}')
+    expect(selected('Three')).toBe('true')
+    await user.keyboard('{ArrowRight}')
+    expect(selected('One')).toBe('true')
+    await user.keyboard('{ArrowLeft}')
+    expect(selected('Three')).toBe('true')
+    expect(onChange.mock.calls.map(([id]) => id)).toEqual(['two', 'three', 'one', 'three'])
+  })
+
+  it('selects the first and last tab with Home and End', async () => {
+    const user = userEvent.setup()
+    render(<Harness initial="two" />)
+    await user.click(tab('Two'))
+    await user.keyboard('{End}')
+    expect(selected('Three')).toBe('true')
+    await user.keyboard('{Home}')
+    expect(selected('One')).toBe('true')
+  })
+
+  it('stays quiet when `active` matches no tab: onChange is for a person, not a fallback', () => {
+    const onChange = vi.fn()
+    render(<Tabs tabs={THREE} active={'nowhere' as Id} onChange={onChange} />)
+    expect(onChange).not.toHaveBeenCalled()
+    expect(screen.getAllByRole('tab').map((t) => t.getAttribute('aria-selected'))).toEqual(['false', 'false', 'false'])
+  })
+
+  it('puts className on the outer box, around the row', () => {
+    const { container } = render(<Tabs tabs={THREE} active="one" onChange={() => {}} className="mt-4" />)
+    const outer = container.firstElementChild as HTMLElement
+    expect(outer.classList.contains('mt-4')).toBe(true)
+    expect(outer.querySelector('[role="tablist"]')).not.toBeNull()
+  })
+})

package/src/Tabs.tsx

@@ -1,9 +1,12 @@
 import type { ReactNode } from 'react'
+import { Tabs as BaseTabs } from '@base-ui/react/tabs'
 import { cn } from './cn'
 
 /**
  * A row of tabs. Ship's Tabs (2026-09-01), which was Peek's TopicTabs with
- * the topic-specific ids taken out.
+ * the topic-specific ids taken out; on Base UI Tabs since stage 1 of the
+ * migration (2026-09-06), which is where the keyboard comes from: one Tab
+ * stop for the row, arrow keys between the tabs.
  *
  * A selected tab is a neutral fill (bg-active), not the accent tint —
  * Katerina's ruling (2026-08-27), extended to every app (2026-09-01). Two
@@ -31,43 +34,51 @@ export interface TabsProps<T extends string> {
   onChange: (id: T) => void
   /** `default` 14px; `small` 12px, the denser geometry. */
   size?: 'default' | 'small'
+  /** Lands on the outer box, around the row. */
   className?: string
 }
 
 export function Tabs<T extends string>({ tabs, active, onChange, size = 'default', className }: TabsProps<T>) {
   return (
-    <div role="tablist" className={cn('flex items-center gap-2', className)}>
-      {tabs.map((tab) => (
-        <button
-          key={tab.id}
-          type="button"
-          role="tab"
-          aria-selected={active === tab.id}
-          onClick={() => onChange(tab.id)}
-          className={cn(
-            'flex cursor-pointer items-center transition-colors',
-            // Arbitrary sizes (the body-2 and caption tokens): the colour branch below
-            // follows them through cn(), and tw-merge drops a custom text-{size}
-            // once a text-{colour} lands after it. Measured: tabs rendered 16px.
-            // gap: default is Ship's 6px; small keeps Peek's original 4px, or
-            // "small is Peek's geometry" stops being true.
-            size === 'default' ? 'gap-1.5 rounded-md px-2 py-1 text-[14px] leading-[140%]' : 'gap-1 rounded px-1.5 py-0.5 text-[12px] leading-[120%]',
-            active === tab.id ? 'bg-bg-active text-text-primary' : 'text-text-secondary hover:bg-bg-hover',
-          )}
-        >
-          {tab.icon}
-          {/* Label and count share a baseline: a smaller text centred as a box
-              (items-center) floats above the label's baseline — the digits
-              read as riding high. Baseline alignment is what makes two sizes
-              sit on one line. */}
-          <span className="flex items-baseline">
-            {tab.label}
-            {tab.count !== undefined ? (
-              <span className="ml-2.5 font-mono text-caption tabular-nums text-text-secondary">{tab.count}</span>
-            ) : null}
-          </span>
-        </button>
-      ))}
-    </div>
+    <BaseTabs.Root
+      value={active}
+      onValueChange={(value, details) => {
+        // Only a person's choice reaches the caller. Base UI also reports its
+        // own fallbacks (an `active` that matches no tab), and those carry
+        // `null`, which is not a T.
+        if (details.reason === 'none') onChange(value as T)
+      }}
+      className={className}
+    >
+      <BaseTabs.List activateOnFocus className="flex items-center gap-2">
+        {tabs.map((tab) => (
+          <BaseTabs.Tab
+            key={tab.id}
+            value={tab.id}
+            className={(state) =>
+              cn(
+                'flex cursor-pointer items-center transition-colors',
+                // gap: default is Ship's 6px; small keeps Peek's original 4px, or
+                // "small is Peek's geometry" stops being true.
+                size === 'default' ? 'gap-1.5 rounded-md px-2 py-1 text-body-2' : 'gap-1 rounded px-1.5 py-0.5 text-caption',
+                state.active ? 'bg-bg-active text-text-primary' : 'text-text-secondary hover:bg-bg-hover',
+              )
+            }
+          >
+            {tab.icon}
+            {/* Label and count share a baseline: a smaller text centred as a box
+                (items-center) floats above the label's baseline — the digits
+                read as riding high. Baseline alignment is what makes two sizes
+                sit on one line. */}
+            <span className="flex items-baseline">
+              {tab.label}
+              {tab.count !== undefined ? (
+                <span className="ml-2.5 font-mono text-caption tabular-nums text-text-secondary">{tab.count}</span>
+              ) : null}
+            </span>
+          </BaseTabs.Tab>
+        ))}
+      </BaseTabs.List>
+    </BaseTabs.Root>
   )
 }

package/src/Toast.tsx

@@ -31,19 +31,19 @@ export interface ToastProps {
 
 // Signal: every toast is the same dark overlay pill (v3) — the type lives in
 // the icon color + glow, not the surface.
-const SURFACE_BY_TYPE: Record<ToastType, string> = {
+const SURFACE_STYLES: Record<ToastType, string> = {
   success: 'bg-success-muted signal:bg-bg-inset signal:border signal:border-border-default signal:shadow-[shadow:var(--shadow-md)]',
   brand: 'bg-accent-muted signal:bg-bg-inset signal:border signal:border-border-default signal:shadow-[shadow:var(--shadow-md)]',
   neutral: 'bg-bg-inset border border-border-subtle signal:border-border-default signal:shadow-[shadow:var(--shadow-md)]',
 }
 
-const ICON_BY_TYPE: Record<ToastType, string> = {
-  success: 'signal:text-success-default signal:drop-shadow-[0_0_5px_rgba(63,222,140,0.7)]',
-  brand: 'signal:text-text-interactive signal:drop-shadow-[0_0_5px_rgba(86,200,255,0.6)]',
+const ICON_STYLES: Record<ToastType, string> = {
+  success: 'signal:text-success-default signal:drop-shadow-glow-success',
+  brand: 'signal:text-text-interactive signal:drop-shadow-glow-accent',
   neutral: 'signal:text-text-secondary',
 }
 
-const ACTION_BORDER_BY_TYPE: Record<ToastType, string> = {
+const ACTION_BORDER_STYLES: Record<ToastType, string> = {
   success: 'signal:border signal:border-border-default signal:hover:border-border-strong',
   brand: 'signal:border signal:border-border-default signal:hover:border-border-strong',
   neutral: 'border border-border-default',
@@ -58,13 +58,13 @@ export function Toast({ label, type = 'neutral', leadingIcon = true, actionLabel
         // Without an action the label needs real right padding; the action
         // button brings its own edge, so the tight pr-1 only applies there.
         hasAction ? 'pr-1 gap-[46px]' : 'pr-3',
-        SURFACE_BY_TYPE[type],
+        SURFACE_STYLES[type],
         className,
       )}
     >
       <div className="flex items-center gap-2 shrink-0">
         {leadingIcon && (
-          <IconCircleCheck size={16} stroke={1.5} className={cn('text-text-primary shrink-0', ICON_BY_TYPE[type])} />
+          <IconCircleCheck size={16} stroke={1.5} className={cn('text-text-primary shrink-0', ICON_STYLES[type])} />
         )}
         <span className="font-normal text-[14px] leading-[1.4] text-text-primary whitespace-nowrap">{label}</span>
       </div>
@@ -74,7 +74,7 @@ export function Toast({ label, type = 'neutral', leadingIcon = true, actionLabel
           onClick={onAction}
           className={cn(
             'h-6 flex items-center justify-center gap-1 px-1 py-1 rounded-md shrink-0 transition-colors',
-            ACTION_BORDER_BY_TYPE[type],
+            ACTION_BORDER_STYLES[type],
             type === 'neutral' ? 'hover:border-border-strong' : 'hover:opacity-80',
           )}
         >

package/src/TopBar.stories.tsx

@@ -14,7 +14,13 @@ import { TopBar } from './TopBar'
 const meta = {
   title: 'Frame/TopBar',
   component: TopBar,
-  parameters: { layout: 'fullscreen' },
+  parameters: {
+    layout: 'fullscreen',
+    // axe color-contrast is off here until PLAN.md stage 0.10 is ruled:
+    // the placeholder content under the bar is muted text, 3.94:1 on --bg-base in
+    // signal (AA 4.5:1).
+    a11y: { config: { rules: [{ id: 'color-contrast', enabled: false }] } },
+  },
   argTypes: {
     variant: { control: 'inline-radio', options: ['solid', 'floating'] },
     menu: { control: false },

package/src/cn.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import preset from '../tailwind-preset.js'
-import { cn, _fontSizeTokens } from './cn'
+import { cn, _boxShadowTokens, _dropShadowTokens, _fontSizeTokens } from './cn'
 
 describe('cn knows the type ramp', () => {
   it('lists exactly the preset fontSize keys', () => {
@@ -25,3 +25,22 @@ describe('cn knows the type ramp', () => {
     expect(cn('text-left text-body-2 text-text-primary')).toBe('text-left text-body-2 text-text-primary')
   })
 })
+
+describe('cn knows the shadow tokens', () => {
+  it('lists exactly the preset boxShadow and dropShadow keys', () => {
+    const extend = (preset as { theme: { extend: { boxShadow: Record<string, unknown>; dropShadow: Record<string, unknown> } } }).theme.extend
+    expect([..._boxShadowTokens].sort()).toEqual(Object.keys(extend.boxShadow).sort())
+    expect([..._dropShadowTokens].sort()).toEqual(Object.keys(extend.dropShadow).sort())
+  })
+
+  it('treats a shadow token as a shadow: two of them conflict, the last wins', () => {
+    expect(cn('shadow-glow-warning', 'shadow-md')).toBe('shadow-md')
+    expect(cn('shadow-focus-ring', 'shadow-glow-warning')).toBe('shadow-glow-warning')
+    expect(cn('drop-shadow-glow-success', 'drop-shadow-glow-accent')).toBe('drop-shadow-glow-accent')
+  })
+
+  it('keeps a shadow token beside a colour, and under a variant', () => {
+    expect(cn('signal:shadow-glow-warning text-text-primary')).toBe('signal:shadow-glow-warning text-text-primary')
+    expect(cn('signal:border-warning-outline', 'text-warning-default')).toBe('signal:border-warning-outline text-warning-default')
+  })
+})

package/src/cn.ts

@@ -21,8 +21,24 @@ const FONT_SIZE_TOKENS = [
   'btn-default', 'btn-small', 'input-label', 'input-value', 'input-helper', 'chip',
 ]
 
+/**
+ * The preset's box-shadow and drop-shadow keys, for the same reason: stock
+ * tailwind-merge files an unknown `shadow-x` under shadow-COLOUR, so
+ * `shadow-focus-ring` beside `shadow-glow-warning` lost one of them, and
+ * `shadow-glow-warning` beside `shadow-md` kept both (measured 2026-09-06).
+ * `cn.test.ts` pins these to the preset too.
+ */
+const BOX_SHADOW_TOKENS = ['sm', 'md', 'lg', 'focus-ring', 'glow-warning', 'highlight-inset']
+const DROP_SHADOW_TOKENS = ['glow-success', 'glow-accent']
+
 const twMerge = extendTailwindMerge({
-  extend: { classGroups: { 'font-size': [{ text: FONT_SIZE_TOKENS }] } },
+  extend: {
+    classGroups: {
+      'font-size': [{ text: FONT_SIZE_TOKENS }],
+      shadow: [{ shadow: BOX_SHADOW_TOKENS }],
+      'drop-shadow': [{ 'drop-shadow': DROP_SHADOW_TOKENS }],
+    },
+  },
 })
 
 /** Merge class names, last-one-wins on conflicting Tailwind utilities. */
@@ -30,4 +46,4 @@ export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
 
-export { FONT_SIZE_TOKENS as _fontSizeTokens }
+export { FONT_SIZE_TOKENS as _fontSizeTokens, BOX_SHADOW_TOKENS as _boxShadowTokens, DROP_SHADOW_TOKENS as _dropShadowTokens }

package/stories/Choosing.mdx

@@ -0,0 +1,101 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Docs/Choosing a component" />
+
+# Choosing a component
+
+Find what you need; take the row. When nothing fits, build it in your app —
+and if what you built knows nothing about your product's objects, propose
+it for the package. A component that nearly fits is **forked, not fought**:
+fork freely, owe nothing back, mention it on the package's ticket.
+
+## An action
+
+| You need | Reach for |
+|---|---|
+| A labeled action — a verb, clicked once | **Button** — `primary` at most once per surface |
+| An icon-only action | **IconButton** — it requires an `aria-label` |
+| An action in a popover list | **MenuItem**, inside a **Menu** |
+| A destructive action | **Button** `destructive`, guarded by a **ConfirmDialog** |
+
+## A choice
+
+| You need | Reach for | Not |
+|---|---|---|
+| One value for a form field | **Select** | a Menu — Select's trigger shows the value |
+| Several values, typed then removable | **ChipInput** | checkboxes in a Menu |
+| Yes or no | **Checkbox** | a toggle we don't have |
+| Switching between views of one thing | **Tabs** | a row of Buttons |
+| View options behind a `…` | **Menu**, `selected` on the current row | Select |
+| Rows of checkboxes that stay open | a list in a **DialogShell** | a Menu — a Checkbox inside a `menuitem` is invalid HTML |
+
+## Typing
+
+| You need | Reach for |
+|---|---|
+| One line | **TextInput** |
+| Several lines | **Textarea** |
+| Typing that filters a list | **SearchInput** |
+| A title edited in place | **EditableText** |
+| Label and required-mark around any control | **Field** |
+
+## People
+
+| You need | Reach for |
+|---|---|
+| One face | **Avatar** |
+| Several faces, overlapping | **AvatarGroup** |
+| Face and name in a row | **Person** |
+| The face that opens a menu | **PersonTrigger** |
+| Who you are, where you are, sign out | **IdentityMenu** — the account menu, ready-made |
+
+## Floating surfaces
+
+| You need | Reach for |
+|---|---|
+| A list of verbs from a trigger | **Menu** — Escape and outside-click come with it |
+| A hint on hover | **Tooltip** / **WithTooltip** |
+| Anything with a title, body and footer | **DialogShell** |
+| "Are you sure?" | **ConfirmDialog** |
+
+## Structure and wayfinding
+
+| You need | Reach for |
+|---|---|
+| Label–value rows (a details rail) | **Property** — `row` and `stacked` |
+| A section heading, chevron, hover actions | **SectionHeader** |
+| The uppercase micro-label | **SectionLabel** |
+| A hairline | **Divider** |
+| Where am I, and the way back up | **Breadcrumb** |
+| The key that does this too | **Kbd** — or the `shortcut` prop on **MenuItem**, **Tooltip** and **SearchInput** |
+
+## Feedback
+
+| You need | Reach for |
+|---|---|
+| Data is on its way | **Skeleton** — shaped like what will arrive |
+| Nothing to show | **EmptyState** — says what would fill it |
+| It happened, briefly | **Toast**, via `useToast` inside a `ToastProvider` |
+| The whole surface has something to say | **Banner** — the strip under the top bar |
+
+## The frame
+
+Two frames, two pairs: the **solid** TopBar goes with the **Sidebar**;
+the **floating** TopBar goes with the **Rail** and the content card.
+
+| You need | Reach for |
+|---|---|
+| The structured frame: solid bar, sidebar, content | **AppShell** `solid` |
+| The floating frame: bar over the content, rail, rounded card | **AppShell** `floating` |
+| The 52px bar alone | **TopBar** — `solid` in flow, or `floating` over the content |
+| A 240px navigation column | **Sidebar**, filled with **NavItem** rows |
+| A 64px icon strip | **Rail**, filled with **RailItem** tiles |
+| The menu button and the logo | the TopBar's `menu` and `logo` slots — collapsing stays yours |
+
+## Deliberately not in the package
+
+- Anything that knows your **product's objects** — its documents, threads,
+  files, tickets. Build it in your app, out of these parts, and keep its
+  stories in your app's own Storybook.
+- Page layouts — panels inside the content, split views, side rails —
+  not here yet; they are the next batch.

package/stories/DesignTokens.mdx

@@ -0,0 +1,10 @@
+import { Meta, Unstyled } from '@storybook/addon-docs/blocks'
+import { TokensPage } from './TokensPage'
+
+<Meta title="Docs/Design Tokens" />
+
+{/* Unstyled: the docs container sets 16px Nunito Sans on every div outside it,
+    at the same specificity as a token class, so the page draws its own type. */}
+<Unstyled>
+  <TokensPage />
+</Unstyled>

package/stories/GettingStarted.mdx

@@ -0,0 +1,108 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Docs/Getting started" />
+
+# Getting started
+
+Wiring a new Estiva app to the package, in six steps. After these, every
+component on these pages works in your app — right theme, right sizes,
+right scrollbars.
+
+## 1 · Install
+
+```bash
+npm install @estiva-app/ui
+```
+
+Peers you provide: `react` / `react-dom` 19, `tailwindcss` 3.4, and
+`@tabler/icons-react` — the icon set every component and example draws from.
+
+## 2 · The Tailwind preset — and the content spread
+
+```js
+// tailwind.config.js
+import estiva, { estivaContent } from '@estiva-app/ui/tailwind-preset'
+
+export default {
+  presets: [estiva],
+  content: [...estivaContent, './index.html', './src/**/*.{ts,tsx}'],
+}
+```
+
+The spread is not optional. Tailwind does not merge `content` from a
+preset, so without it every class only these components use is purged —
+the build succeeds, and components render at the wrong size.
+
+## 3 · The stylesheets
+
+```css
+/* your entry CSS, before anything that uses a token */
+@import '@estiva-app/ui/tokens.css';
+@import '@estiva-app/ui/base.css';
+```
+
+`tokens.css` is the token values, one block per theme. `base.css` is the
+shared chrome that is not a token — the thin, token-coloured scrollbar
+every Estiva app shows.
+
+## 4 · Pick a theme
+
+```html
+<html data-theme="ship">
+```
+
+| Theme | Selected by |
+|---|---|
+| `signal` | `data-theme="signal"` |
+| `ship` | `data-theme="ship"` |
+
+A new app starts on one of these. Its own look, when it earns one, is **one
+new block in `tokens.css`** defining every token — the package's test holds
+every theme to the full set, so nothing can half-exist.
+
+## 5 · Merge classes with the package `cn()`
+
+```tsx
+import { cn } from '@estiva-app/ui'
+```
+
+It is tailwind-merge taught this preset's type ramp: token size classes
+(`text-body-2`, `text-caption`) survive merging next to a text colour.
+Stock `twMerge` silently drops them — don't bring your own.
+
+## 6 · First screen
+
+```tsx
+import { Button, Field, TextInput, ToastProvider, useToast } from '@estiva-app/ui'
+
+function NewThing() {
+  const { showToast } = useToast()
+  return (
+    <div className="flex max-w-sm flex-col gap-4 p-6">
+      <Field label="Name" required>
+        <TextInput placeholder="What is it called?" />
+      </Field>
+      <Button variant="primary" onClick={() => showToast({ label: 'Created' })}>
+        Create
+      </Button>
+    </div>
+  )
+}
+
+export default function App() {
+  return (
+    <ToastProvider>
+      <NewThing />
+    </ToastProvider>
+  )
+}
+```
+
+## Where next
+
+- **[Choosing a component](?path=/docs/docs-choosing-a-component--docs)** —
+  what to reach for, by what you need.
+- Each component's page: when, when not — with the alternative named — and
+  how.
+- The README's rules travel with the package: fork freely; tokens, never
+  raw hex; the five popover rules; only offer actions that can succeed.

package/stories/Introduction.mdx

@@ -0,0 +1,36 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+
+<Meta title="Docs/Introduction" />
+
+# @estiva-app/ui
+
+The shared foundation of every Estiva app's interface: the **design tokens**
+(colour, type, radius, shadow) and a **small set of primitives** built on
+them.
+
+**Tokens are the contract. Components are a convenience.** An app must not
+diverge from the token names. It may fork any component, freely, and owes
+nothing back — a fork is information about the seam, not a failure; say so
+on the package's ticket, and never bend your view around a component.
+
+## Start here
+
+1. **[Getting started](?path=/docs/docs-getting-started--docs)** — wire a
+   new app to the package, in six steps.
+2. **[Choosing a component](?path=/docs/docs-choosing-a-component--docs)**
+   — what to reach for, by what you need.
+3. **[Design Tokens](?path=/docs/docs-design-tokens--docs)** — the
+   vocabulary everything here is written in.
+4. Every component's own page says **when** to use it, when **not** — with
+   the alternative named — and **how**, with its stories live on the page.
+
+Use the **Theme** toolbar anywhere in this Storybook to see every page
+under each of the package's themes: the same token names, a different look.
+
+## What belongs here
+
+- In the package: components that know nothing about any product — built
+  from tokens, generic over their content, with stories that need no app
+  data.
+- In your app: anything that knows your product's objects. Build it there,
+  out of these parts, and keep its stories in your app's own Storybook.