@k8ordo/ui 1.0.0 → 2.1.0

package/docs/references/components.md

@@ -1,20 +1,77 @@
-# k8ordo UI コンポーネント一覧
+# @k8ordo/ui component catalog
 
-## インポート方法
+## Importing
 
 ```tsx
-// スタイルシート（必須）。Tailwind CSS 4 のプロジェクトは
-// 代わりに '@k8ordo/ui/tailwind.css' を import する
+// The stylesheet (required). In a Tailwind CSS 4 project, a CSS file
+// imports 'tailwindcss' and then '@k8ordo/ui/tailwind.css' instead
 import '@k8ordo/ui/styles.css';
-
-// プロバイダー（アプリルートで1回）
+// The provider (once, at the app root)
 import { UIProvider } from '@k8ordo/ui';
-
-// コンポーネント（すべてルートからインポート）
+// Components (all from the root entry)
 import { Button, Card, TextField } from '@k8ordo/ui';
+// Except CodeBlock, which highlights on the server and has its own entry
+import { CodeBlock } from '@k8ordo/ui/code-block';
 ```
 
-## ボタン・リンク
+Every component can be rendered from a Server Component, compound ones
+included: `Dialog.Root`, `Tabs.Root`, `Popover.Trigger`, and the rest are
+composed outside the client modules, so the parts resolve on the server. Only
+the interactive parts carry `'use client'`.
+
+## Render props
+
+Two different contracts are spelled `render*`, and mixing them up is the usual
+source of surprise.
+
+**Replacing the element** — `renderItem` on `Button` and `IconButton`,
+`renderAnchor` on `Anchor`, `Breadcrumb.Link`, and `SideNav.Link`. The component computes
+everything and hands back the exact props it would have put on its own element,
+so substituting an `<a>`, a framework `<Link>`, or your own button loses
+nothing. For `Button` and `IconButton` that is the resolved `className`, the
+composed `children` (icons and the pending spinner included), the click handler,
+the disabled and pending state, the `ref`, and every `aria-*` / `data-*` /
+native attribute the caller passed in. Spread the bag onto whatever you render.
+
+- Handlers and the `ref` are typed for `HTMLElement` rather than for the
+  element the component would have rendered, so the bag spreads onto any tag.
+- `disabled` and `type` are the only members that exist on `<button>` alone.
+  Destructure them away when you render something else — `aria-disabled` in the
+  same bag carries the state, and the supplied `onClick` already does nothing
+  and calls `preventDefault()` while disabled, so a disabled link will not
+  navigate. The examples below name them `_disabled` / `_type` so the discarded
+  bindings pass a `no-unused-vars` rule.
+- `disabled` is only the `disabled` you passed. While an action is pending (see
+  [Button](#button)), the bag carries `aria-disabled` and `aria-busy` but
+  `disabled` stays `false`, so the pressed element keeps focus; the supplied
+  `onClick` is what ignores presses meanwhile.
+- Spreading onto a real `<button>` is exact, but write `type` on the element
+  anyway: the `button-has-type` lint rule cannot see a `type` that arrives
+  through a spread.
+
+The link components own less, so their bags are smaller:
+
+- `Anchor` hands back `href`, `className`, `children` (with the new-tab icon on
+  an external link), `target` / `rel` on an external link, and every other
+  anchor attribute the caller passed, plus `kind` (`'internal'` |
+  `'external'`). `kind` is not an attribute: destructure it away before
+  spreading, or use it to choose between a framework `<Link>` and a plain `<a>`.
+  There is no `ref` and no disabled state.
+- `Breadcrumb.Link` hands back `href`, `className`, and `children` only — it
+  takes no other attributes. A `current` link renders
+  `<span aria-current="page">` and does not call `renderAnchor`.
+- `SideNav.Link` hands back `href`, `className`, `children`, `aria-current`
+  (`'page'` on the current link), and every other anchor attribute the caller
+  passed. A current link is still a link.
+
+**Filling a slot** — `renderInput` on `FormControl`, `renderItem` on
+`Popover.Trigger`, `Tooltip.Trigger`, `FileField.Trigger`, and `Alert`'s
+`action`. Here the component owns no element of its own. It computes wiring —
+ids, ARIA relationships, open/close handlers — and you supply the element that
+wiring belongs to. Those bags carry only the wiring, and they are required
+rather than optional.
+
+## Buttons
 
 ### Button
 
@@ -31,81 +88,100 @@ import { Button } from '@k8ordo/ui';
   disabled={false}
   isActive={false}
 >
-  ボタン
+  Button
 </Button>
 ```
 
 Props:
 
 - `children`: `ReactNode`
-- `color`: `'primary'` | `'secondary'` | `'base'`（既定: `'primary'`）
+- `color`: `'primary'` | `'secondary'` | `'base'` (default: `'primary'`)
 - `endIcon`: `ReactNode`
-- `fullWidth`: `boolean`（既定: `false`）
-- `isActive`: `boolean`（既定: `false`）
+- `fullWidth`: `boolean` (default: `false`)
+- `isActive`: `boolean` (default: `false`)
 - `onAction`: `() => void | Promise<void>`
-- `renderItem`: `(props: { className: string; children: ReactNode }) => ReactNode`
-- `size`: `'sm'` | `'md'` | `'lg'`（既定: `'md'`）
+- `renderItem`: `(props: ButtonRenderItemProps) => ReactNode`
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
 - `startIcon`: `ReactNode`
-- `type`: `'button'` | `'submit'`（既定: `'button'`）
-- `variant`: `'solid'` | `'outline'` | `'skeleton'`（既定: `'solid'`）
-
-リンクとしてレンダーする場合は `renderItem` prop を使う。Next.js の `<Link>` などにも応用できる。
+- `type`: `'button'` | `'submit'` (default: `'button'`)
+- `variant`: `'solid'` | `'outline'` | `'skeleton'` (default: `'solid'`)
+- Other props are forwarded to `ComponentPropsWithRef<'button'>`, except `className` / `style`.
+
+`onAction` runs inside a transition. While the promise it returns is pending —
+and, with `type="submit"`, while the form's action is pending — the button shows
+a spinner, carries `aria-busy` and `aria-disabled`, and ignores presses,
+including the implicit submission of pressing Enter in a field. It does not
+become natively `disabled`: Chromium moves focus to `body` when the focused
+element is disabled, so a keyboard user who pressed the button would lose their
+place. The `disabled` you pass is native, and takes the button out of the tab
+order.
+
+`renderItem` replaces the `<button>`; see [Render props](#render-props) for the
+contract. It receives `className`, the composed `children`, `ref`, `type`,
+`disabled`, `aria-disabled`, `aria-busy`, `onClick`, and every other attribute
+passed to `Button`. Use it to render a link — the same shape works for things
+like Next.js's `<Link>`.
 
 ```tsx
 <Button
   color="base"
   variant="outline"
-  renderItem={({ className, children }) => (
-    <a className={className} href="/page">
+  renderItem={({ children, disabled: _disabled, type: _type, ...props }) => (
+    <a href="/page" {...props}>
       {children}
     </a>
   )}
 >
-  リンク
+  Link
 </Button>
 ```
 
 ### IconButton
 
-アイコンのみのボタン。`color` prop でスタイルを制御。
+An icon-only button. Styling is controlled by the `color` prop.
 
 ```tsx
 import { IconButton } from '@k8ordo/ui';
 
-<IconButton label="閉じる" color="transparent" size="md">
+<IconButton label="Close" color="transparent" size="md">
   <CloseIcon />
 </IconButton>;
 ```
 
 Props:
 
-- `label`: `string`（必須）
+- `label`: `string` (required)
 - `children`: `ReactNode`
-- `color`: `'transparent'` | `'base'` | `'primary'` | `'secondary'`（既定: `'transparent'`）
+- `color`: `'transparent'` | `'base'` | `'primary'` | `'secondary'` (default: `'transparent'`)
 - `onAction`: `() => void | Promise<void>`
-- `renderItem`: `(props: { className: string; children: ReactNode; 'aria-label': string; triggerProps: IconButtonTriggerProps; }) => ReactNode`
-- `size`: `'sm'` | `'md'` | `'lg'`（既定: `'md'`）
-- `tooltipDisabled`: `boolean`（既定: `false`）
-- `tooltipPlacement`: `Placement`（既定: `'top'`）
-
-リンクとしてレンダーする場合は `renderItem` prop を使う。`triggerProps` を `<a>` にスプレッドすると hover/focus 時に `label` が Tooltip として表示される。
+- `renderItem`: `(props: IconButtonRenderItemProps) => ReactNode`
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
+- `tooltipDisabled`: `boolean` (default: `false`)
+- `tooltipPlacement`: `Placement` (default: `'top'`)
+- Other props are forwarded to `ComponentPropsWithRef<'button'>`, except `type` / `className` / `style`.
+
+`onAction` keeps the button busy the way `Button`'s does — `aria-busy`,
+`aria-disabled`, presses ignored, focus kept — without the spinner.
+
+`renderItem` replaces the `<button>` under the same contract as `Button`'s,
+with one addition: the tooltip wiring is kept in a nested `triggerProps` so it
+stays free of any element type. Spread it too, and `label` shows as a tooltip on
+hover and focus. `triggerProps` also carries the merged `ref` and any
+`onMouseEnter` / `onMouseLeave` / `onFocus` / `onBlur` the caller passed, so the
+flat part of the bag holds neither.
 
 ```tsx
 <IconButton
   color="base"
-  label="メール"
+  label="Mail"
   renderItem={({
-    className,
     children,
-    'aria-label': ariaLabel,
+    disabled: _disabled,
     triggerProps,
+    type: _type,
+    ...props
   }) => (
-    <a
-      aria-label={ariaLabel}
-      className={className}
-      href="/contact"
-      {...triggerProps}
-    >
+    <a href="/contact" {...props} {...triggerProps}>
       {children}
     </a>
   )}
@@ -114,80 +190,117 @@ Props:
 </IconButton>
 ```
 
-### Anchor
+### CopyButton
 
-テキストリンク。外部リンクには自動で新規タブアイコンが付く。
+A button that copies text to the clipboard and shows that it did: its icon
+turns into a check for two seconds (an error icon if the write fails), and a
+live region beside it announces `copied` / `copyFailed` from the dictionary. The
+button's name stays the same throughout. By default it is an outline `Button`
+with its `label` as text; `iconOnly` makes it a transparent `IconButton` whose
+`label` is the tooltip.
 
 ```tsx
-import { Anchor } from '@k8ordo/ui';
+import { CopyButton } from '@k8ordo/ui';
+
+<CopyButton value={css} label="Copy CSS" size="sm" />;
 
-<Anchor href="https://example.com">外部リンク</Anchor>
-<Anchor href="/about">内部リンク</Anchor>
-<Anchor href="/docs" openInNewTab>新規タブで開く</Anchor>
+// Icon only, e.g. in the header of a code block
+<CopyButton value={code} label="Copy code" iconOnly size="sm" />;
+
+// Build the text when the button is pressed: read the DOM, or fetch it
+<CopyButton
+  label="Copy as Markdown"
+  value={async () => (await fetch(`/blog/${slug}.md`)).text()}
+/>;
 ```
 
+`value` may be a function, and it may return a `Promise`. It is called on the
+click, and the promise goes to the clipboard as it is (a `ClipboardItem`), so the
+write starts inside the click even when the text arrives later. Safari refuses
+a write that begins after an `await`.
+
 Props:
 
-- `children`: `ReactNode`（必須）
-- `href`: `T`（必須）
-- `openInNewTab`: `boolean`（既定: `false`）
-- `renderAnchor`: `(props: RenderAnchorProps<T>) => ReactNode`（既定: `defaultRenderAnchor`）
+- `value`: `string` | `(() => string | Promise<string>)` (required)
+- `disabled`: `boolean` (default: `false`)
+- `iconOnly`: `boolean` (default: `false`)
+- `label`: `string`
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
 
-## レイアウト・ナビゲーション
+### Toolbar
 
-### Accordion
+A group of controls that takes one Tab stop (the WAI-ARIA toolbar). Arrow keys
+move between the items — left/right when `orientation` is `horizontal`, up/down
+when `vertical`, and in vertical writing mode the other pair, since the row
+itself runs vertically — `Home` / `End` jump to the ends, and disabled items are
+skipped. Tab leaves the toolbar, and coming back lands on the item last focused.
 
-折りたたみ可能なセクション。Compound component パターン。
+Each item is a slot: `Toolbar.Item`'s `renderItem` receives `ref`, `tabIndex`,
+and `onFocus` (`ToolbarItemProps`) to spread onto a `Button`, an `IconButton`,
+or any other button. A toggle item sets `aria-pressed`; the toolbar shades a
+pressed item. The root needs a name (`aria-label` or `aria-labelledby`).
+Items are meant to be buttons: a control that uses the arrow keys itself (a text
+field, a slider) would fight the toolbar for them.
 
 ```tsx
-import { Accordion } from '@k8ordo/ui';
-
-<Accordion.Root>
-  <Accordion.Item>
-    <Accordion.Button>セクション1</Accordion.Button>
-    <Accordion.Panel>コンテンツ</Accordion.Panel>
-  </Accordion.Item>
-</Accordion.Root>;
+import { IconButton, Toolbar } from '@k8ordo/ui';
+
+<Toolbar.Root aria-label="Formatting">
+  <Toolbar.Item
+    renderItem={(props) => (
+      <IconButton {...props} label="Copy">
+        <CopyIcon />
+      </IconButton>
+    )}
+  />
+  <Toolbar.Separator />
+  <Toolbar.Item
+    renderItem={(props) => (
+      <IconButton
+        {...props}
+        aria-pressed={isList}
+        label="Bulleted list"
+        onClick={toggleList}
+      >
+        <ListIcon />
+      </IconButton>
+    )}
+  />
+</Toolbar.Root>;
 ```
 
-Props (Accordion.Button):
-
-- `children`: `ReactNode`
-
-Props (Accordion.Item):
+Props (Root):
 
 - `children`: `ReactNode`
-- `defaultOpen`: `boolean`（既定: `false`）
-- `isOpen`: `boolean`
-- `onChange`: `(isOpen: boolean) => void`
-
-Props (Accordion.Panel):
+- `orientation`: `'horizontal'` | `'vertical'` (default: `'horizontal'`)
+- `ref`: `Ref<HTMLDivElement>`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style` / `role` / `aria-orientation`.
 
-- `children`: `ReactNode`
+Props (Toolbar.Item):
 
-Props (Accordion.Root):
+- `renderItem`: `(props: ToolbarItemProps) => ReactElement` (required)
 
-- `children`: `ReactNode`
+## Navigation
 
 ### Breadcrumb
 
-パンくずリスト。Compound component パターン。
+A breadcrumb trail, as a compound component.
 
 ```tsx
 import { Breadcrumb } from '@k8ordo/ui';
 
 <Breadcrumb.List>
   <Breadcrumb.Item>
-    <Breadcrumb.Link href="/">ホーム</Breadcrumb.Link>
+    <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
   </Breadcrumb.Item>
   <Breadcrumb.Separator />
   <Breadcrumb.Item>
-    <Breadcrumb.Link href="/products">製品</Breadcrumb.Link>
+    <Breadcrumb.Link href="/products">Products</Breadcrumb.Link>
   </Breadcrumb.Item>
   <Breadcrumb.Separator />
   <Breadcrumb.Item>
     <Breadcrumb.Link href="/products/1" current>
-      詳細
+      Details
     </Breadcrumb.Link>
   </Breadcrumb.Item>
 </Breadcrumb.List>;
@@ -196,14 +309,17 @@ import { Breadcrumb } from '@k8ordo/ui';
 Props (Breadcrumb.List):
 
 - `children`: `ReactNode`
-- `size`: `'sm'` | `'md'` | `'lg'`（既定: `'md'`）
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
 
 Props (Breadcrumb.Link):
 
-- `href`: `T`（必須）
+- `href`: `T` (required)
 - `children`: `ReactNode`
-- `current`: `boolean`（既定: `false`）
-- `renderAnchor`: `(props: RenderBreadcrumbAnchorProps<T>) => ReactNode`（既定: `defaultRenderBreadcrumbAnchor`）
+- `current`: `boolean` (default: `false`)
+- `renderAnchor`: `(props: RenderBreadcrumbAnchorProps<T>) => ReactNode` (default: `defaultRenderBreadcrumbAnchor`)
+
+`Breadcrumb.Link`'s `renderAnchor` receives `href`, `className`, and `children`;
+see [Render props](#render-props).
 
 Props (Breadcrumb.Item):
 
@@ -211,7 +327,7 @@ Props (Breadcrumb.Item):
 
 ### Pagination
 
-ページ送り。前後ボタンと現在ページの表示のみで、ページ番号のリストは持たない。
+Pagination. It shows previous/next buttons and the current page only — there is no list of page numbers.
 
 ```tsx
 import { Pagination } from '@k8ordo/ui';
@@ -221,206 +337,294 @@ import { Pagination } from '@k8ordo/ui';
 
 Props:
 
-- `currentPage`: `number`（必須）
-- `onChange`: `(page: number) => void`（必須）
-- `totalPages`: `number`（必須）
+- `currentPage`: `number` (required)
+- `onChange`: `(page: number) => void` (required)
+- `totalPages`: `number` (required)
 - `aria-label`: `string`
-- `disabled`: `boolean`（既定: `false`）
+- `disabled`: `boolean` (default: `false`)
 - `nextLabel`: `string`
 - `prevLabel`: `string`
 - `ref`: `Ref<HTMLElement>`
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `className` / `style` / `children`.
 
-### Tabs
+### Stepper
 
-タブ切り替え。Compound component パターン。
+The steps of a process in order, as an `<ol>`: done steps show a check and are
+read with the built-in `stepperComplete` wording, and the current step carries
+`aria-current="step"`. `value` is the index of the current step (0-based);
+`steps.length` marks every step done. With `interactive`, done steps become
+buttons that go back to them (`onChange` receives the index); steps ahead are
+never buttons. Name the list with `aria-label`.
 
-```tsx
-import { Tabs } from '@k8ordo/ui';
+`orientation` is logical: `horizontal` lays the steps along the line and
+`vertical` stacks them, so inside `writing-v` they run top to bottom and right
+to left respectively, with the connecting lines drawn to match and the step
+numbers kept upright. In `horizontal`, every step takes an equal share of the
+width: the first row holds only the step markers and the lines between them,
+and each step's label and description sit under its marker, wrapping within
+that share. The lines keep their length however long the labels are, and a
+narrow container wraps the text rather than squeezing the lines.
 
-<Tabs.Root ids={['tab1', 'tab2']}>
-  <Tabs.List label="タブ">
-    <Tabs.Tab id="tab1">タブ1</Tabs.Tab>
-    <Tabs.Tab id="tab2">タブ2</Tabs.Tab>
-  </Tabs.List>
-  <Tabs.Panel id="tab1">パネル1</Tabs.Panel>
-  <Tabs.Panel id="tab2">パネル2</Tabs.Panel>
-</Tabs.Root>;
-```
+In a multi-step form (see `@k8ordo/form`'s guide), keep every step mounted and
+drive `value` from the step you show.
 
-Props (Tabs.Root):
+```tsx
+import { Stepper } from '@k8ordo/ui';
+
+<Stepper
+  aria-label="Sign-up"
+  interactive
+  onChange={setStep}
+  steps={[
+    { label: 'Plan', description: 'Pick what fits' },
+    { label: 'Payment' },
+    { label: 'Review' },
+  ]}
+  value={step}
+/>;
+```
 
-- `ids`: `[string, ...string[]]`（必須）
-- `children`: `ReactNode`
-- `defaultSelectedId`: `string` | `null`（既定: `null`）
-- `onChange`: `(id: string) => void`
-- `selectedId`: `string`
+Props:
 
-Props (Tabs.List):
+- `steps`: `readonly StepperStep[]` (required)
+- `defaultValue`: `number`
+- `interactive`: `boolean` (default: `false`)
+- `onChange`: `(value: number) => void`
+- `orientation`: `'horizontal'` | `'vertical'` (default: `'horizontal'`)
+- `ref`: `Ref<HTMLOListElement>`
+- `value`: `number`
+- Other props are forwarded to `OlHTMLAttributes<HTMLOListElement>`, except `className` / `style` / `children`.
 
-- `label`: `string`（必須）
-- `children`: `ReactNode`
+### SideNav
 
-Props (Tabs.Panel):
+Side navigation: groups of links, each under a small title, with the page being
+shown marked by a bar (`aria-current="page"`). The library has no router, so
+you say which link is current, and swap the `<a>` for your router's link with
+`renderAnchor` — it replaces the element, and its bag holds `href`,
+`className`, `children`, `aria-current`, and every other anchor attribute you
+passed (an `onClick` that closes a drawer, say). Every part renders from a
+Server Component.
 
-- `id`: `string`（必須）
-- `children`: `ReactNode`
+```tsx
+import { SideNav } from '@k8ordo/ui';
+
+<SideNav.Root label="Components">
+  <SideNav.Group title="Buttons">
+    <SideNav.Link current={pathname === '/button'} href="/button">
+      Button
+    </SideNav.Link>
+    <SideNav.Link
+      href="/icon-button"
+      renderAnchor={({ children, ...props }) => (
+        <Link {...props}>{children}</Link>
+      )}
+    >
+      IconButton
+    </SideNav.Link>
+  </SideNav.Group>
+</SideNav.Root>;
+```
 
-Props (Tabs.Tab):
+Props (SideNav.Root):
 
-- `id`: `string`（必須）
+- `label`: `string` (required)
 - `children`: `ReactNode`
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `className` / `style` / `aria-label`.
 
-### Card
-
-コンテンツをグループ化するカード。
+A group can hold a level that opens and closes, `SideNav.Sub`, to make the
+navigation a tree. It is a `<details>`, so it opens and closes without
+JavaScript; open the one holding the current page with `defaultOpen`.
 
 ```tsx
-import { Card } from '@k8ordo/ui';
+<SideNav.Group title="Components">
+  <SideNav.Link href="/components">Overview</SideNav.Link>
+  <SideNav.Sub defaultOpen title="Buttons">
+    <SideNav.Link current href="/button">
+      Button
+    </SideNav.Link>
+  </SideNav.Sub>
+  <SideNav.Sub title="Navigation">
+    <SideNav.Link href="/tabs">Tabs</SideNav.Link>
+  </SideNav.Sub>
+</SideNav.Group>
+```
 
-// 静的カード
-<Card width="full" variant="shadow">
-  <div className="p-6">コンテンツ</div>
-</Card>
+Props (SideNav.Group):
 
-// クリック可能なカード（hover:scale-[1.02], active:scale-[0.98]）
-<Card variant="outline" interactive>
-  <div className="p-6">コンテンツ</div>
-</Card>
-```
+- `title`: `string` (required)
+- `children`: `ReactNode`
 
-Props:
+Props (SideNav.Sub):
 
+- `title`: `string` (required)
 - `children`: `ReactNode`
-- `interactive`: `boolean`（既定: `false`）
-- `variant`: `'shadow'` | `'outline'`（既定: `'shadow'`）
-- `width`: `'full'` | `'fit'`（既定: `'full'`）
+- `defaultOpen`: `boolean` (default: `false`)
 
-### Separator
+Props (SideNav.Link):
 
-区切り線。
+- `children`: `ReactNode` (required)
+- `href`: `T` (required)
+- `current`: `boolean` (default: `false`)
+- `renderAnchor`: `(props: RenderSideNavAnchorProps<T>) => ReactNode` (default: `defaultRenderAnchor`)
+- Other props are forwarded to `AnchorHTMLAttributes<HTMLAnchorElement>`, except `className` / `style` / `aria-current`.
+
+### TableOfContents
+
+The contents of the page, with the heading being read marked
+(`aria-current="location"`). Pass the headings as a tree of `{ id, label,
+children? }`; each item links to `#id`.
 
 ```tsx
-import { Separator } from '@k8ordo/ui';
+import { TableOfContents } from '@k8ordo/ui';
 
-<Separator />
-<Separator color="mute" />
-<Separator color="subtle" />
-<Separator orientation="vertical" />
+<TableOfContents
+  items={[
+    { id: 'install', label: 'Install' },
+    {
+      id: 'usage',
+      label: 'Usage',
+      children: [{ id: 'usage-basic', label: 'Basics' }],
+    },
+  ]}
+/>;
 ```
 
+- The heading being read is the last one whose start has passed the heading's
+  own `scroll-margin-block-start`: set the margin your sticky header needs on
+  the headings, and a heading reached from the contents becomes the current
+  one. At the end of the document, the last heading is current even if its
+  section is too short to reach that line.
+- It follows the document's scroll: the headings are expected to scroll with
+  the page, and `items` to be in document order. It measures on scroll, on
+  resize, and when the page's size changes. In a vertical document it reads
+  from right to left (`vertical-rl`) or left to right (`vertical-lr`).
+- `label` replaces the title (`tableOfContents` in the message dictionary),
+  which also names the `nav`.
+
 Props:
 
-- `color`: `'base'` | `'mute'` | `'subtle'`（既定: `'base'`）
-- `orientation`: `'horizontal'` | `'vertical'`（既定: `'horizontal'`）
+- `items`: `readonly TableOfContentsItem[]` (required)
+- `label`: `string`
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `className` / `style` / `children` / `aria-labelledby`.
 
-### ScrollLinked
+### Tabs
 
-スクロール進捗をプログレスバーで表示。
+Tab switching, as a compound component.
 
 ```tsx
-import { ScrollLinked } from '@k8ordo/ui';
+import { Tabs } from '@k8ordo/ui';
 
-<ScrollLinked />
-<ScrollLinked container={containerRef} />
+<Tabs.Root ids={['tab1', 'tab2']}>
+  <Tabs.List label="Tabs">
+    <Tabs.Tab id="tab1">Tab 1</Tabs.Tab>
+    <Tabs.Tab id="tab2">Tab 2</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel id="tab1">Panel 1</Tabs.Panel>
+  <Tabs.Panel id="tab2">Panel 2</Tabs.Panel>
+</Tabs.Root>;
 ```
 
-Props:
+Selecting a tab is a transition: the panels cross-fade through React's
+`<ViewTransition>` (off under `prefers-reduced-motion`), and a panel that
+suspends keeps the current one on screen until it is ready.
 
-- `container`: `RefObject<HTMLElement | null>`
+The keys follow the WAI-ARIA tabs pattern, and focusing a tab selects it.
+`ArrowLeft` / `ArrowRight` move to the previous / next tab, wrapping at the
+ends, and swap under `dir="rtl"`; in vertical writing mode the list is
+vertical and `ArrowUp` / `ArrowDown` do the same. `Home` / `End` go to the
+first / last tab.
 
-### Stack
+Props (Tabs.Root):
 
-縦横一方向に並べるレイアウト。`gap` はスペーシングトークンから選ぶ。
+- `ids`: `[string, ...string[]]` (required)
+- `children`: `ReactNode`
+- `defaultSelectedId`: `string` | `null` (default: `null`)
+- `onChange`: `(id: string) => void`
+- `selectedId`: `string`
 
-```tsx
-import { Stack } from '@k8ordo/ui';
+Props (Tabs.List):
 
-<Stack gap="lg">
-  <Card>1</Card>
-  <Card>2</Card>
-</Stack>
+- `label`: `string` (required)
+- `children`: `ReactNode`
 
-<Stack direction="row" justify="between" align="center">
-  <Heading level="h2">タイトル</Heading>
-  <Button>操作</Button>
-</Stack>
-```
+Props (Tabs.Panel):
 
-Props:
+- `id`: `string` (required)
+- `children`: `ReactNode`
 
-- `align`: `'start'` | `'center'` | `'end'` | `'stretch'`
+Props (Tabs.Tab):
+
+- `id`: `string` (required)
 - `children`: `ReactNode`
-- `direction`: `'row'` | `'column'`（既定: `'column'`）
-- `gap`: `GapSize`（既定: `'md'`）
-- `justify`: `'start'` | `'center'` | `'end'` | `'between'`
-- `padding`: `PaddingSize`
 
-### Grid
+### Anchor
 
-グリッドレイアウト。`cols` に `'auto-fill'` / `'auto-fit'` を渡すと `minItemSize` を下限に折り返す。
+A text link. External links automatically get a new-tab icon.
 
 ```tsx
-import { Grid } from '@k8ordo/ui';
-
-<Grid cols={3} gap="md">
-  <Card>1</Card>
-  <Card>2</Card>
-  <Card>3</Card>
-</Grid>
+import { Anchor } from '@k8ordo/ui';
 
-<Grid cols="auto-fill" minItemSize={64}>
-  {items.map((item) => (
-    <Card key={item.id}>{item.name}</Card>
-  ))}
-</Grid>
+<Anchor href="https://example.com">External link</Anchor>
+<Anchor href="/about">Internal link</Anchor>
+<Anchor href="/docs" openInNewTab>Open in a new tab</Anchor>
 ```
 
 Props:
 
-- `children`: `ReactNode`
-- `cols`: `1` | `2` | `3` | `4` | `5` | `6` | `'auto-fill'` | `'auto-fit'`（既定: `'auto-fill'`）
-- `gap`: `GapSize`（既定: `'md'`）
-- `minItemSize`: `24` | `32` | `40` | `48` | `64` | `80`（既定: `48`）
+- `children`: `ReactNode` (required)
+- `href`: `T` (required)
+- `openInNewTab`: `boolean` (default: `false`)
+- `renderAnchor`: `(props: RenderAnchorProps<T>) => ReactNode` (default: `defaultRenderAnchor`)
+- Other props are forwarded to `AnchorHTMLAttributes<HTMLAnchorElement>`, except `target` / `rel` / `className` / `style`.
+
+`renderAnchor` replaces the `<a>`; its bag is described under
+[Render props](#render-props).
 
-## フォーム
+## Forms
 
-フォームコンポーネントは `FormControl` の `renderInput` パターンと組み合わせて使用する。各フォームコンポーネントは controlled / uncontrolled の両方に対応。
+Form components are used together with `FormControl`'s `renderInput` pattern. Every form component except `FileField` supports both controlled and uncontrolled use; `FileField.Root` takes only `defaultValue` and keeps the selected files itself.
 
-`ref` は実要素（`input` / `textarea` / `select` / `fieldset`）に届く。内部で ref を使う `Textarea` / `FileField` も内部 ref と合成されるため、`react-hook-form` の `register()` などをそのまま渡せる。`Radio`（複数の input を描くグループ）と `FormControl`（ラッパー）は `ref` を受け取らない。
+`ref` reaches the real element (`input` / `textarea` / `select` / `fieldset`). `FileField` uses a ref internally but composes it with yours, so the `ref` you pass still reaches the element. `Radio` (a group that renders several inputs) puts its `ref` on the radiogroup `<div>`, and `FormControl` (a wrapper) on its wrapper element — a `<div>`, or a `<fieldset>` with `labelAs="legend"`.
+
+An uncontrolled field keeps its value in the DOM, so a form reset — `form.reset()`, a reset button, or React resetting the form after an action — puts it back to its `defaultValue`, and a `defaultValue` that changes after mount (the values a failed submission echoes back) is where the next reset goes. A value a component changes in code (a stepper, a chosen option, a removed file) is announced with an `input` event, so a form library listening on the `<form>` hears it like typing.
+
+Every field takes the attributes `@k8ordo/form`'s `formFields` derives as they are — spread `field.input` after `FormControl`'s props. Its guide's "Working with @k8ordo/ui" section has one example per component.
 
 ### Form
 
-`<form>` のラッパー。`action` には Server Action（`(formData) => …`）も URL 文字列も渡せる。
+A wrapper for `<form>`. `action` accepts a Server Action (`(formData) => …`) or a URL string.
 
 ```tsx
 import { Button, Form, FormControl, TextField } from '@k8ordo/ui';
 
 <Form action={submitAction}>
   <FormControl
-    label="メール"
+    label="Email"
     required
     renderInput={(props) => <TextField {...props} name="email" />}
   />
-  <Button type="submit">送信</Button>
+  <Button type="submit">Submit</Button>
 </Form>;
 ```
 
 Props:
 
-- `children`: `ReactNode`（必須）
+- `children`: `ReactNode` (required)
 - `action`: `((formData: FormData) => void | Promise<void>)` | `string`
+- `ref`: `Ref<HTMLFormElement>`
+- Other props are forwarded to `FormHTMLAttributes<HTMLFormElement>`, except `className` / `style`.
 
 ### FormControl
 
-フォームフィールドのラッパー。ラベル・ヘルプテキスト・エラー表示を統一する。
+A wrapper for a form field. It unifies the label, help text, and error display.
 
 ```tsx
 import { FormControl, TextField } from '@k8ordo/ui';
 
 <FormControl
-  label="メールアドレス"
-  errorText="入力してください"
-  helpText="会社のメールアドレスを入力してください"
+  label="Email address"
+  errorText="This field is required"
+  helpText="Enter your work email address"
   required
   renderInput={(props) => (
     <TextField {...props} placeholder="example@mail.com" />
@@ -430,19 +634,20 @@ import { FormControl, TextField } from '@k8ordo/ui';
 
 Props:
 
-- `label`: `string`（必須）
-- `renderInput`: `(props: { id: string; 'aria-describedby': string | undefined; 'aria-labelledby': string; disabled: boolean; invalid: boolean; required: boolean; }) => ReactElement`（必須）
-- `disabled`: `boolean`（既定: `false`）
+- `label`: `string` (required)
+- `renderInput`: `(props: { id: string; 'aria-describedby': string | undefined; 'aria-labelledby': string; disabled: boolean; invalid: boolean; required: boolean; }) => ReactElement` (required)
+- `disabled`: `boolean` (default: `false`)
 - `errorText`: `string`
 - `helpText`: `string`
-- `invalid`: `boolean`（既定: `false`）
-- `labelAs`: `'label'` | `'legend'`（既定: `'label'`）
+- `invalid`: `boolean` (default: `false`)
+- `labelAs`: `'label'` | `'legend'` (default: `'label'`)
 - `ref`: `Ref<HTMLElement>`
-- `required`: `boolean`（既定: `false`）
+- `required`: `boolean` (default: `false`)
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `className` / `style` / `children`.
 
-`renderInput` は `{ id, 'aria-describedby', 'aria-labelledby', disabled, invalid, required }` を受け取る。
+`renderInput` receives `{ id, 'aria-describedby', 'aria-labelledby', disabled, invalid, required }`.
 
-ラッパー要素は `labelAs` で変わる。`'label'`（既定）は `<div>` + `<label htmlFor>`、`'legend'` は `<fieldset>` + `<legend>`。単一フィールドを名前の無いグループにしないため、`<fieldset>` は `legend` のときだけ使う。`Radio` / `CheckboxGroup` のようなグループ入力を包むときは `labelAs="legend"` を指定する。
+The wrapper element depends on `labelAs`. `'label'` (the default) gives `<div>` + `<label htmlFor>`; `'legend'` gives `<fieldset>` + `<legend>`. `<fieldset>` is used only for `legend`, so that a single field never becomes an unnamed group. Pass `labelAs="legend"` when wrapping a group input such as `Radio` or `CheckboxGroup`.
 
 ### TextField
 
@@ -457,16 +662,23 @@ import { TextField } from '@k8ordo/ui';
 <TextField id="email" value={value} onChange={onChange}
   invalid={false} disabled={false} required={false} />
 
-// type も渡せる（デフォルト: "text"）
+// type can be passed too (default: "text")
 <TextField id="tel" type="tel" inputMode="numeric" />
+
+// date and time inputs render as the browser's own pickers
+<TextField id="birthday" type="date" />
 ```
 
+`type` also accepts any string, so the `type` `@k8ordo/form` derives
+(`email`, `url`, `date`, `time`, `datetime-local`, …) spreads as it is.
+
 Props:
 
 - `children`: `ReactNode`
-- `invalid`: `boolean`（既定: `false`）
+- `invalid`: `boolean` (default: `false`)
 - `ref`: `Ref<HTMLInputElement>`
-- `type`: `TextInputType`（既定: `'text'`）
+- `type`: `'date'` | `'datetime-local'` | `'email'` | `'month'` | `'search'` | `'tel'` | `'text'` | `'time'` | `'url'` | `'week'` | `(string & Record<never, never>)` (default: `'text'`)
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `className` / `style`.
 
 ### Textarea
 
@@ -485,44 +697,187 @@ import { Textarea } from '@k8ordo/ui';
 
 Props:
 
-- `autoResize`: `boolean`（既定: `false`）
+- `autoResize`: `boolean` (default: `false`)
 - `children`: `ReactNode`
-- `fullHeight`: `boolean`（既定: `false`）
-- `invalid`: `boolean`（既定: `false`）
+- `fullHeight`: `boolean` (default: `false`)
+- `invalid`: `boolean` (default: `false`)
 - `ref`: `Ref<HTMLTextAreaElement>`
+- `type`: `string`
+- Other props are forwarded to `TextareaHTMLAttributes<HTMLTextAreaElement>`, except `className` / `style`.
+
+`type` is accepted and dropped: a `<textarea>` has none, and the attributes
+`@k8ordo/form` derives for a string carry `type="text"`. A `pattern` is not
+checked by the browser on a `<textarea>` either.
 
 ### NumberField
 
 ```tsx
 import { NumberField } from '@k8ordo/ui';
 
+// Uncontrolled: starts empty unless defaultValue is given
+<NumberField
+  id="quantity"
+  name="quantity"
+  min={0}
+  max={100}
+  invalid={false}
+  disabled={false}
+  required={false}
+/>;
+
+// Controlled: null is an empty field
+const [value, setValue] = useState<number | null>(null);
 <NumberField
   id="quantity"
   min={0}
   max={100}
   value={value}
-  onChange={onChange}
+  onChange={setValue}
   invalid={false}
   disabled={false}
   required={false}
 />;
 ```
 
+An empty field is `null`, never `0`. While empty the input submits `''` and
+has no `aria-valuenow`, and leaving it keeps it empty; clearing the field
+reports `null` to `onChange`. The first ArrowUp / ArrowDown or stepper press on
+an empty field fills in `0`, or the nearer of `min` / `max` when `0` is out of
+range. `required` reaches the input itself, so an empty required field fails
+native validation.
+
+The input is `type="text"` (so it can format to `precision` and step with the
+arrow keys), which the browser does not range-check — so the field does it: a
+value below `min` or above `max` is reported with `setCustomValidity`, using
+the `numberFieldRangeUnderflow` / `numberFieldRangeOverflow` wording. Leaving the
+field clamps the value into range. A message set by someone else on the same
+input — a form library's cross-field rule — is left alone.
+
+`min`, `max`, and an uncontrolled `defaultValue` also take strings, and `step`
+takes `'any'`, which is what `@k8ordo/form` derives. `precision` defaults to the
+number of decimals in `step`; with `step="any"` the value is not rounded.
+
+A value the field writes itself — an arrow key, a stepper press, formatting on
+blur — is announced with one `input` event, and `onChange` is still called once.
+
+A form reset — `form.reset()`, a reset button, or React resetting the form after
+an action — puts an uncontrolled field back to `defaultValue` (or to empty) and
+reports that value to `onChange`. A controlled field keeps its `value`; reset
+your own state from the form's `onReset`.
+
 Props:
 
-- `defaultValue`: `never`
-- `invalid`: `boolean`（既定: `false`）
-- `max`: `number`（既定: `9_007_199_254_740_991`）
-- `min`: `number`（既定: `-9_007_199_254_740_991`）
-- `onChange`: `(value: number) => void`
-- `precision`: `number`（既定: `0`）
+- `defaultValue`: `number` | `string`
+- `invalid`: `boolean` (default: `false`)
+- `max`: `number` | `string`
+- `min`: `number` | `string`
+- `onChange`: `(value: number | null) => void`
+- `precision`: `number`
 - `ref`: `Ref<HTMLInputElement>`
-- `step`: `number`（既定: `1`）
-- `value`: `number`
+- `step`: `number` | `'any'` (default: `1`)
+- `value`: `number` | `null`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `role` / `className` / `style` / `children`.
+
+### DateField
+
+A native `<input type="date">` styled like `TextField`. The value is a
+`YYYY-MM-DD` string (`''` when empty), and the browser checks `min` / `max` /
+`required` itself. `onChange` is the native event, as with `TextField`.
+
+It accepts what `@k8ordo/form` derives from `z.iso.date()` as is: spread the
+field's `input` and nothing needs to be taken out. `type` is always `date`, so a
+`type` in the spread does not replace it.
+
+```tsx
+import { DateField, FormControl } from '@k8ordo/ui';
+
+const eventDate = form.field('eventDate'); // z.iso.date()
+
+<FormControl
+  errorText={eventDate.error}
+  invalid={eventDate.invalid}
+  label="Date"
+  required={eventDate.required}
+  renderInput={(props) => <DateField {...props} {...eventDate.input} />}
+/>;
+```
+
+Props:
+
+- `invalid`: `boolean` (default: `false`)
+- `ref`: `Ref<HTMLInputElement>`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `className` / `style` / `type` / `children`.
+
+### DatePicker
+
+`DateField` with a button that opens `Calendar` in a popover. The field is the
+same native `<input type="date">`, so typing a date, `name`, `required`, and
+`min` / `max` all work as they do on `DateField`, and spreading a derived
+`@k8ordo/form` field works the same way. `onChange` takes the value
+(`YYYY-MM-DD`, `''` when cleared), not the event, because a date picked from the
+calendar has no input event of its own.
+
+Picking a date writes it into the input and dispatches an `input` event, so a
+form sees it exactly as if it had been typed (dirty state, rules, and clearing
+an error). The popover closes and focus returns to the calendar button.
+
+Firefox draws its own calendar button inside every `<input type="date">` and
+offers no way to hide it, so there the field shows two calendar buttons: the
+browser's and this component's. Chromium and Safari show only this one.
+
+```tsx
+import { DatePicker } from '@k8ordo/ui';
+
+<DatePicker
+  aria-label="Check-in"
+  min="2026-01-01"
+  name="checkIn"
+  onChange={setCheckIn}
+  value={checkIn}
+/>;
+```
+
+Props:
+
+- `defaultValue`: `string`
+- `invalid`: `boolean` (default: `false`)
+- `onChange`: `(value: string) => void`
+- `ref`: `Ref<HTMLInputElement>`
+- `value`: `string`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `className` / `style` / `type` / `children`.
+
+### Calendar
+
+A month grid for picking one day (the WAI-ARIA date picker grid). The value is
+a `YYYY-MM-DD` string. Arrow keys move by day and week, `Home` / `End` to the
+ends of the week, `PageUp` / `PageDown` by month (with `Shift`, by year), and
+`Enter` / `Space` select. Days outside `min` / `max` stay focusable but cannot
+be selected.
+
+Month and weekday names, and the first day of the week, follow the same locale
+as the built-in wording (i18n, below). Today is marked with
+`aria-current="date"` in the visitor's time zone, which only the browser knows,
+so the calendar renders in the browser alone: the server writes an empty box of
+the same size. It submits nothing; inside a form, use `DatePicker` or
+`DateField`.
+
+```tsx
+import { Calendar } from '@k8ordo/ui';
+
+<Calendar defaultValue="2026-09-25" max="2026-12-31" onChange={setDay} />;
+```
+
+Props:
+
+- `defaultValue`: `string`
+- `max`: `string`
+- `min`: `string`
+- `onChange`: `(value: string) => void`
+- `value`: `string` | `null`
 
 ### PasswordInput
 
-パスワード入力。表示/非表示トグル付き。
+A password input, with a show/hide toggle.
 
 ```tsx
 import { PasswordInput } from '@k8ordo/ui';
@@ -534,8 +889,8 @@ import { PasswordInput } from '@k8ordo/ui';
   invalid={false}
   disabled={false}
   required={false}
-  showLabel="表示"
-  hideLabel="非表示"
+  showLabel="Show"
+  hideLabel="Hide"
 />;
 ```
 
@@ -543,9 +898,13 @@ Props:
 
 - `children`: `ReactNode`
 - `hideLabel`: `string`
-- `invalid`: `boolean`（既定: `false`）
+- `invalid`: `boolean` (default: `false`)
 - `ref`: `Ref<HTMLInputElement>`
 - `showLabel`: `string`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `className` / `style`.
+
+A spread `type="password"` (what `@k8ordo/form` derives for a password) does not
+override the show/hide toggle.
 
 ### Select
 
@@ -555,8 +914,8 @@ import { Select } from '@k8ordo/ui';
 <Select
   id="category"
   options={[
-    { value: '1', label: 'オプション1' },
-    { value: '2', label: 'オプション2' },
+    { value: '1', label: 'Option 1' },
+    { value: '2', label: 'Option 2' },
   ]}
   value={value}
   onChange={onChange}
@@ -568,14 +927,33 @@ import { Select } from '@k8ordo/ui';
 
 Props:
 
-- `options`: `readonly Option[]`（必須）
+- `options`: `readonly Option[]` (required)
 - `children`: `ReactNode`
-- `invalid`: `boolean`（既定: `false`）
+- `invalid`: `boolean` (default: `false`)
 - `ref`: `Ref<HTMLSelectElement>`
+- Other props are forwarded to `SelectHTMLAttributes<HTMLSelectElement>`, except `className` / `style`.
+
+React applies a `<select>`'s `defaultValue` only when it mounts; `Select` also
+applies a later one, so the next reset — React's after a form action included —
+goes back to it. With `required`, put a placeholder option whose `value` is
+`''` first; leaving it selected fails validation.
 
 ### Autocomplete
 
-複数選択のオートコンプリート。`value` / `onChange` は `string[]`。
+A multi-select autocomplete over a fixed list of options, shown as removable
+tags. `value` and `onChange` are `string[]`. To pick one option, or to search a
+list that lives on a server, use `Combobox`.
+
+Typing filters `options` by label. `ArrowDown` / `ArrowUp` open the list and
+move through it, `Enter` adds or removes the active option, `Backspace` in an
+empty field removes the last tag, and `Escape` closes the list. Keys pressed
+while an IME is composing belong to the IME.
+
+With a `name`, the selection is submitted through a visually hidden
+`<select multiple>`: one entry per selected value, and `required` means at
+least one. It is always present — nothing selected included — so native
+validation and a form library's rules reach it, and when a form moves focus to
+it after a failure, focus goes on to the text input.
 
 ```tsx
 import { Autocomplete } from '@k8ordo/ui';
@@ -593,96 +971,227 @@ import { Autocomplete } from '@k8ordo/ui';
 
 Props:
 
-- `id`: `string`（必須）
-- `options`: `readonly Option[]`（必須）
-- `defaultValue`: `never`
-- `invalid`: `boolean`（既定: `false`）
+- `id`: `string` (required)
+- `options`: `readonly Option[]` (required)
+- `defaultValue`: `string[]`
+- `invalid`: `boolean` (default: `false`)
 - `onChange`: `(value: string[]) => void`
 - `ref`: `Ref<HTMLInputElement>`
 - `value`: `string[]`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `role` / `className` / `style` / `children` / `autoComplete` / `aria-autocomplete` / `aria-controls` / `aria-expanded` / `aria-activedescendant`.
+
+### ColorPicker
+
+A color field whose value is `#rrggbb`. The value lives in a text input that
+carries `name`, so it submits and resets like any other field; hue, saturation,
+and lightness sliders and optional `swatches` (toggle buttons named by their
+`label`) write into it and announce the change with an `input` event, as if it
+had been typed. The color chip beside the text input is a native
+`<input type="color">`, named by the built-in `colorPickerOpen` wording: pressing
+it opens the browser's own color picker, which writes into the text input the
+same way, while it is dragged too. It carries no `name`, so only the text input
+submits; with no color yet it opens on the sliders' gray. The chip, sliders,
+and swatches are all disabled while the field is `disabled`, `readOnly`, or its
+form is pending. Typing reports a color only once it has six digits; on blur and
+on Enter the text is tidied to lowercase `#rrggbb`, and a three-digit `#f80` is
+expanded. Emptying the field reports `''`. Spread `@k8ordo/form`'s `input` onto
+it as is: a `.regex()` in the schema arrives as `pattern` and replaces the
+built-in `#[0-9a-fA-F]{6}`. The panel stays horizontal inside vertical writing
+mode.
+
+```tsx
+import { ColorPicker, FormControl } from '@k8ordo/ui';
+
+<FormControl
+  label="Accent color"
+  renderInput={(props) => (
+    <ColorPicker
+      {...props}
+      defaultValue="#0d9488"
+      name="accent"
+      swatches={[
+        { value: '#0d9488', label: 'Teal' },
+        { value: '#f97316', label: 'Orange' },
+      ]}
+    />
+  )}
+/>;
+```
+
+Props:
+
+- `defaultValue`: `string`
+- `invalid`: `boolean` (default: `false`)
+- `onChange`: `(value: string) => void`
+- `ref`: `Ref<HTMLInputElement>`
+- `swatches`: `readonly ColorPickerSwatch[]`
+- `type`: `string`
+- `value`: `string`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `className` / `style` / `children`.
+
+### Combobox
+
+A text field with a list of options, for picking one (the WAI-ARIA combobox
+with list autocomplete and manual selection). `value` and `onChange` are the
+chosen option's `value`, `''` when nothing is chosen. To pick several from a
+fixed list, use `Autocomplete`.
+
+Typing opens the list; nothing is chosen until an option is picked with a click
+or `Enter`, so leaving half-typed text puts the chosen option's label back, and
+leaving the field empty clears the choice. `ArrowDown` / `ArrowUp` open the list
+and move through it (`Alt+ArrowDown` opens it without entering it), `Escape`
+closes it and, pressed again, drops what was typed. Keys pressed while an IME is
+composing belong to the IME.
+
+Without `search`, typing filters `options` by label. With `search`, typing
+calls it for the options instead — each call gets a `signal` that aborts when
+the text changes again, so pass it to `fetch` — and `options` becomes the list
+shown before anything is typed and where the current value's label is looked
+up. While a search runs, the list is marked busy; a failed one says so with
+`comboboxFailed`, an empty result with `comboboxEmpty`.
+
+With a `name`, the choice is submitted through a visually hidden `<select>`, the
+same way `Autocomplete` submits, so `required`, a form library's rules, reset,
+and moving focus to the field after a failure all work on it.
+
+```tsx
+import { Combobox } from '@k8ordo/ui';
+
+<Combobox aria-label="Prefecture" name="prefecture" options={prefectures} />;
+
+// Options from a server
+<Combobox
+  aria-label="City"
+  name="city"
+  search={async (query, { signal }) => {
+    const response = await fetch(`/api/cities?q=${encodeURIComponent(query)}`, {
+      signal,
+    });
+    return response.json();
+  }}
+/>;
+```
+
+Props:
+
+- `defaultValue`: `string`
+- `invalid`: `boolean` (default: `false`)
+- `onChange`: `(value: string) => void`
+- `options`: `readonly Option[]`
+- `ref`: `Ref<HTMLInputElement>`
+- `search`: `ComboboxSearch`
+- `type`: `string`
+- `value`: `string`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `role` / `className` / `style` / `children` / `autoComplete` / `aria-autocomplete` / `aria-controls` / `aria-expanded` / `aria-activedescendant`.
 
 ### Checkbox
 
-ラベルは `label` prop で渡す（children ではない）。`onChange` は `(checked, event)`。
+The label is passed as the `label` prop, not as children. `onChange` is `(checked, event)`.
+
+`itemValue` is the input's `value`: the string a checked box submits under its `name`. Without it the box renders no `value` and submits the browser's default, `on`. There is no `value` prop — on a checkbox it is easily mistaken for the checked state, which is `checked`.
 
 ```tsx
 import { Checkbox } from '@k8ordo/ui';
 
 // Controlled
-<Checkbox checked={checked} label="同意する" onChange={onChange} />
+<Checkbox checked={checked} label="I agree" onChange={onChange} />
 
 // Uncontrolled
-<Checkbox defaultChecked label="同意する" />
+<Checkbox defaultChecked label="I agree" />
+
+// Submits inStock=true when checked, instead of inStock=on
+<Checkbox itemValue="true" label="In stock only" name="inStock" />
 ```
 
+`indeterminate` shows the mixed state — some of a set selected — and sets the
+input's `indeterminate` property, so it is announced as partly checked.
+`labelHidden` keeps `label` as the accessible name but does not draw it, for a
+place with no room for text such as a table cell.
+
 Props:
 
-- `label`: `string`（必須）
+- `label`: `string` (required)
 - `checked`: `boolean`
-- `defaultChecked`: `never`
+- `defaultChecked`: `boolean`
+- `indeterminate`: `boolean` (default: `false`)
+- `invalid`: `boolean` (default: `false`)
 - `itemValue`: `string`
+- `labelHidden`: `boolean` (default: `false`)
 - `onChange`: `(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void`
 - `ref`: `Ref<HTMLInputElement>`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `className` / `style` / `value` / `children`.
 
 ### CheckboxGroup
 
-複数チェックボックスのグループ。子は `CheckboxGroup.Item`（= `Checkbox`）で、`itemValue` が必須。
+A group of checkboxes. The children are `CheckboxGroup.Item` (= `Checkbox`), and `itemValue` is required.
+
+The group's selection lives in `value` / `onChange` (`string[]`). That is a different thing from a lone `Checkbox` holding a boolean in `checked` — do not conflate them.
 
-グループの選択状態は `value` / `onChange`（`string[]`）で持つ。単体の `Checkbox` が真偽値を `checked` で持つのとは別物なので、混同しないこと。
+It renders a `fieldset[role="group"]`, so `aria-labelledby` is required. Convey that the group is required through the referenced label element (for example `FormControl`'s required marker). `role="group"` does not allow `aria-required`, so do not put it on the group.
 
-`fieldset[role="group"]` を描くため `aria-labelledby` が必須。必須入力であることは、参照先のラベル要素（`FormControl` の必須表示など）に含めて伝える。`role="group"` は `aria-required` を許可していないので、グループ側には出さない。
+Uncontrolled, the selection lives in the checkboxes themselves: `onChange`
+receives the checked values in document order, and a form reset puts the boxes
+back to `defaultValue` without leaving a stale selection behind.
 
 ```tsx
 import { CheckboxGroup } from '@k8ordo/ui';
 
-<p id="interests-label">興味のある分野</p>
+<p id="interests-label">Areas of interest</p>
 <CheckboxGroup.Root
   aria-labelledby="interests-label"
   name="interests"
   value={values}
   onChange={setValues}
 >
-  <CheckboxGroup.Item itemValue="music" label="音楽" />
-  <CheckboxGroup.Item itemValue="movie" label="映画" />
+  <CheckboxGroup.Item itemValue="music" label="Music" />
+  <CheckboxGroup.Item itemValue="movie" label="Film" />
 </CheckboxGroup.Root>;
 ```
 
 Props (CheckboxGroup.Item):
 
-- `label`: `string`（必須）
+- `label`: `string` (required)
 - `checked`: `boolean`
-- `defaultChecked`: `never`
+- `defaultChecked`: `boolean`
+- `indeterminate`: `boolean` (default: `false`)
+- `invalid`: `boolean` (default: `false`)
 - `itemValue`: `string`
+- `labelHidden`: `boolean` (default: `false`)
 - `onChange`: `(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void`
 - `ref`: `Ref<HTMLInputElement>`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `className` / `style` / `value` / `children`.
 
 Props (CheckboxGroup.Root):
 
-- `aria-labelledby`: `string`（必須）
-- `name`: `string`（必須）
+- `aria-labelledby`: `string` (required)
+- `name`: `string` (required)
 - `children`: `ReactNode`
-- `defaultValue`: `never`
-- `invalid`: `boolean`（既定: `false`）
+- `defaultValue`: `string[]`
+- `invalid`: `boolean` (default: `false`)
 - `onChange`: `(value: string[]) => void`
 - `ref`: `Ref<HTMLFieldSetElement>`
 - `value`: `string[]`
+- Other props are forwarded to `FieldsetHTMLAttributes<HTMLFieldSetElement>`, except `className` / `style` / `role`.
 
 ### CheckboxCard
 
-カードスタイルのチェックボックス。
+A card-styled checkbox. Uncontrolled, the selection and its look follow the
+checkboxes themselves (`:checked`), so a form reset restores both; `onChange`
+receives the checked values in document order.
 
 ```tsx
 import { CheckboxCard } from '@k8ordo/ui';
 
 <CheckboxCard
+  aria-labelledby="plan-checkbox"
   name="plan"
   disabled={false}
   options={[
-    { value: 'basic', label: 'ベーシック', description: '月額980円' },
+    { value: 'basic', label: 'Basic', description: '$9 / month' },
     {
       value: 'pro',
-      label: 'プロ',
-      description: '月額1,980円',
+      label: 'Pro',
+      description: '$19 / month',
       visual: <Icon />,
     },
   ]}
@@ -693,13 +1202,14 @@ import { CheckboxCard } from '@k8ordo/ui';
 
 Props:
 
-- `aria-labelledby`: `string`（必須）
-- `options`: `readonly CheckboxCardOption[]`（必須）
-- `defaultValue`: `never`
-- `invalid`: `boolean`（既定: `false`）
+- `aria-labelledby`: `string` (required)
+- `options`: `readonly CheckboxCardOption[]` (required)
+- `defaultValue`: `string[]`
+- `invalid`: `boolean` (default: `false`)
 - `onChange`: `(value: string[]) => void`
 - `ref`: `Ref<HTMLFieldSetElement>`
 - `value`: `string[]`
+- Other props are forwarded to `FieldsetHTMLAttributes<HTMLFieldSetElement>`, except `className` / `style` / `children` / `role`.
 
 ### Radio
 
@@ -711,8 +1221,8 @@ import { Radio } from '@k8ordo/ui';
   name="example"
   onChange={onChange}
   options={[
-    { value: 'a', label: '選択肢A' },
-    { value: 'b', label: '選択肢B' },
+    { value: 'a', label: 'Choice A' },
+    { value: 'b', label: 'Choice B' },
   ]}
   value={value}
 />;
@@ -720,17 +1230,21 @@ import { Radio } from '@k8ordo/ui';
 
 Props:
 
-- `aria-labelledby`: `string`（必須）
-- `options`: `readonly Option[]`（必須）
-- `disabled`: `boolean`（既定: `false`）
+- `aria-labelledby`: `string` (required)
+- `options`: `readonly Option[]` (required)
+- `defaultValue`: `string`
+- `disabled`: `boolean` (default: `false`)
+- `invalid`: `boolean` (default: `false`)
 - `name`: `string`
 - `onChange`: `(value: string, event: ChangeEvent<HTMLInputElement>) => void`
 - `ref`: `Ref<HTMLDivElement>`
+- `required`: `boolean` (default: `false`)
 - `value`: `string`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `role` / `className` / `style` / `children`.
 
 ### RadioCard
 
-カードスタイルのラジオボタン。`fieldset[role="radiogroup"]` の中に本物の `input[type="radio"]` を並べるため、矢印キーのローミングと単一選択はブラウザに任せている。テストからは `getByRole('radio', { checked })` で参照する。
+A card-styled radio button. Real `input[type="radio"]` elements sit inside a `fieldset[role="radiogroup"]`, so arrow-key roving and single selection are left to the browser. Reach them from tests with `getByRole('radio', { checked })`. `required` goes to every radio, and an uncontrolled selection's look follows `:checked`, so a form reset restores it.
 
 ```tsx
 import { RadioCard } from '@k8ordo/ui';
@@ -740,11 +1254,11 @@ import { RadioCard } from '@k8ordo/ui';
   name="plan"
   disabled={false}
   options={[
-    { value: 'basic', label: 'ベーシック', description: '月額980円' },
+    { value: 'basic', label: 'Basic', description: '$9 / month' },
     {
       value: 'pro',
-      label: 'プロ',
-      description: '月額1,980円',
+      label: 'Pro',
+      description: '$19 / month',
       visual: <Icon />,
     },
   ]}
@@ -755,17 +1269,21 @@ import { RadioCard } from '@k8ordo/ui';
 
 Props:
 
-- `aria-labelledby`: `string`（必須）
-- `options`: `readonly RadioCardOption[]`（必須）
-- `defaultValue`: `never`
-- `invalid`: `boolean`（既定: `false`）
+- `aria-labelledby`: `string` (required)
+- `options`: `readonly RadioCardOption[]` (required)
+- `defaultValue`: `string`
+- `invalid`: `boolean` (default: `false`)
 - `onChange`: `(value: string) => void`
 - `ref`: `Ref<HTMLFieldSetElement>`
+- `required`: `boolean` (default: `false`)
 - `value`: `string`
+- Other props are forwarded to `FieldsetHTMLAttributes<HTMLFieldSetElement>`, except `className` / `style` / `children` / `role`.
 
 ### Slider
 
-レンジスライダー。
+A range slider. Uncontrolled, the value lives in the input, so a form reset
+puts it back to `defaultValue` and the filled track follows. `min`, `max`, and
+an uncontrolled `defaultValue` also take strings, and `step` takes `'any'`.
 
 ```tsx
 import { Slider } from '@k8ordo/ui';
@@ -784,18 +1302,62 @@ import { Slider } from '@k8ordo/ui';
 
 Props:
 
-- `defaultValue`: `never`
-- `invalid`: `boolean`（既定: `false`）
-- `max`: `number`（既定: `100`）
-- `min`: `number`（既定: `0`）
+- `defaultValue`: `number` | `string`
+- `invalid`: `boolean` (default: `false`)
+- `max`: `number` | `string`
+- `min`: `number` | `string`
 - `onChange`: `(value: number) => void`
 - `ref`: `Ref<HTMLInputElement>`
-- `step`: `number`（既定: `1`）
+- `step`: `number` | `'any'` (default: `1`)
 - `value`: `number`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `className` / `style` / `children`.
+
+### RangeSlider
+
+A slider with two thumbs for picking a range (the WAI-ARIA multi-thumb slider).
+Each thumb is a real `<input type="range">`, so the keyboard behaves as the
+browser's own slider does, and neither thumb can pass the other: the lower
+thumb's `aria-valuemax` is the upper value and the upper thumb's
+`aria-valuemin` the lower one. `value` / `defaultValue` / `onChange` carry the
+pair `[lower, upper]`.
+
+`name` is a pair too: the two thumbs submit as two form fields. Uncontrolled,
+the thumbs keep their values in the DOM, so a form's reset and its dirty check
+(value against default value) work on them as on any input. The whole slider is
+a `role="group"`: name it with `aria-label` or `aria-labelledby`
+(`FormControl`'s `renderInput` props work), and each thumb is read as that name
+followed by the built-in `rangeSliderStart` / `rangeSliderEnd` wording.
+
+```tsx
+import { RangeSlider } from '@k8ordo/ui';
+
+<RangeSlider
+  aria-label="Price"
+  defaultValue={[20, 80]}
+  max={100}
+  min={0}
+  name={['priceMin', 'priceMax']}
+/>;
+```
+
+Props:
+
+- `defaultValue`: `readonly [number, number]`
+- `disabled`: `boolean` (default: `false`)
+- `invalid`: `boolean` (default: `false`)
+- `max`: `number` (default: `100`)
+- `min`: `number` (default: `0`)
+- `name`: `readonly [string, string]`
+- `onChange`: `(value: [number, number]) => void`
+- `ref`: `Ref<HTMLDivElement>`
+- `required`: `boolean` (default: `false`)
+- `step`: `number` (default: `1`)
+- `value`: `readonly [number, number]`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style` / `children` / `role`.
 
 ### Switch
 
-トグルスイッチ。
+A toggle switch.
 
 ```tsx
 import { Switch } from '@k8ordo/ui';
@@ -804,7 +1366,7 @@ import { Switch } from '@k8ordo/ui';
   checked={checked}
   disabled={false}
   invalid={false}
-  label="通知を有効にする"
+  label="Enable notifications"
   onChange={onChange}
   required={false}
 />;
@@ -812,16 +1374,18 @@ import { Switch } from '@k8ordo/ui';
 
 Props:
 
-- `label`: `string`（必須）
+- `label`: `string` (required)
 - `checked`: `boolean`
-- `defaultChecked`: `never`
-- `invalid`: `boolean`（既定: `false`）
+- `defaultChecked`: `boolean`
+- `invalid`: `boolean` (default: `false`)
 - `onChange`: `(checked: boolean, event: ChangeEvent<HTMLInputElement>) => void`
 - `ref`: `Ref<HTMLInputElement>`
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `role` / `className` / `style` / `value` / `children`.
 
 ### FileField
 
-コンポジットパターンのファイルアップロード。
+File upload, as a composite pattern. A string `defaultValue` (the type
+`@k8ordo/form`'s derived attributes carry) is accepted and ignored.
 
 ```tsx
 import { FileField } from '@k8ordo/ui';
@@ -830,7 +1394,7 @@ import { FileField } from '@k8ordo/ui';
   <FileField.Trigger
     renderItem={({ onClick, disabled }) => (
       <Button onClick={onClick} disabled={disabled}>
-        ファイルを選択
+        Choose files
       </Button>
     )}
   />
@@ -838,15 +1402,53 @@ import { FileField } from '@k8ordo/ui';
 </FileField.Root>;
 ```
 
+`FileField.Dropzone` is an area files can be dropped onto. Left empty, it holds
+the built-in `fileFieldDrop` wording and a "choose files" button, so the field
+stays usable by keyboard; pass children to lay it out yourself (put a
+`FileField.Trigger` inside). Dropped files are added exactly like picked ones:
+they respect `multiple` and `maxFiles`, land in the input so they are
+submitted, and are announced with an `input` event so a form sees the change.
+A dropped folder is skipped (choose folders through the picker with
+`webkitDirectory`). The browser applies `accept` only to the picker, so the
+field applies it to dropped files itself, by the same rules: a file it does not
+match is left out, and a drop with nothing it matches changes nothing — no
+`onChange`, no `input` event.
+
+The input holds exactly what `ItemList` lists, so what is listed is what is
+submitted:
+
+- With `multiple` or `webkitDirectory`, each pick or drop adds to the list, up
+  to `maxFiles`, and the input is rewritten to the whole list — the browser
+  alone would keep only the files just picked. A rewrite is announced with an
+  `input` event.
+- Removing a file from `ItemList` removes it from the input.
+- A `File[]` `defaultValue` is submitted as well as listed, and a form reset
+  puts both back to it (to an empty list without one).
+- `onChange` receives that whole list — not only the files just picked or
+  dropped — after every pick, drop, and removal. Only a pick passes the
+  `event`.
+
+```tsx
+<FileField.Root accept="image/*" multiple name="photos">
+  <FileField.Dropzone />
+  <FileField.ItemList clearable />
+</FileField.Root>
+```
+
 Props (Root):
 
 - `children`: `ReactNode`
-- `defaultValue`: `File[]`
-- `invalid`: `boolean`（既定: `false`）
+- `defaultValue`: `File[]` | `string`
+- `invalid`: `boolean` (default: `false`)
 - `maxFiles`: `number`
 - `onChange`: `(files: FileList | null, event?: ChangeEvent<HTMLInputElement>) => void`
 - `ref`: `Ref<HTMLInputElement>`
-- `webkitDirectory`: `boolean`（既定: `false`）
+- `webkitDirectory`: `boolean` (default: `false`)
+- Other props are forwarded to `InputHTMLAttributes<HTMLInputElement>`, except `type` / `className` / `style` / `value`.
+
+Props (FileField.Dropzone):
+
+- `children`: `ReactNode`
 
 Props (FileField.ItemList):
 
@@ -855,37 +1457,38 @@ Props (FileField.ItemList):
 
 Props (FileField.Trigger):
 
-- `renderItem`: `(props: { onClick: () => void; disabled: boolean; invalid: boolean; }) => ReactElement`（必須）
+- `renderItem`: `(props: { onClick: () => void; disabled: boolean; invalid: boolean; }) => ReactElement` (required)
 
-## データ表示
+## Data display
 
 ### Heading
 
-セマンティック見出し。`type` prop で HTML 要素を指定。
+A semantic heading. The `level` prop selects the HTML element.
 
 ```tsx
 import { Heading } from '@k8ordo/ui';
 
-<Heading level="h1">ページタイトル</Heading>
-<Heading level="h2">セクション見出し</Heading>
-<Heading level="h3">サブセクション</Heading>
+<Heading level="h1">Page title</Heading>
+<Heading level="h2">Section heading</Heading>
+<Heading level="h3">Subsection</Heading>
 ```
 
 Props:
 
-- `level`: `'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'`（必須）
+- `level`: `'h1'` | `'h2'` | `'h3'` | `'h4'` | `'h5'` | `'h6'` (required)
 - `children`: `ReactNode`
 - `lineClamp`: `1` | `2` | `3` | `4` | `5` | `6`
+- Other props are forwarded to `HTMLAttributes<HTMLHeadingElement>`, except `className` / `style`.
 
 ### Avatar
 
-ユーザーアバター。
+A user avatar.
 
 ```tsx
 import { Avatar } from '@k8ordo/ui';
 
-<Avatar src="/avatar.jpg" alt="ユーザー名" size="md" />
-<Avatar name="田中太郎" fallback="田" size="lg" />
+<Avatar src="/avatar.jpg" alt="User name" size="md" />
+<Avatar name="Ada Lovelace" fallback="A" size="lg" />
 <Avatar color="primary" icon={<AssistantIcon />} name="AI" size="sm" />
 ```
 
@@ -893,36 +1496,38 @@ Props:
 
 - `alt`: `string`
 - `children`: `ReactNode`
-- `color`: `'base'` | `'primary'` | `'secondary'`（既定: `'base'`）
+- `color`: `'base'` | `'primary'` | `'secondary'` (default: `'base'`)
 - `fallback`: `string`
 - `icon`: `ReactNode`
 - `name`: `string`
-- `size`: `'sm'` | `'md'` | `'lg'`（既定: `'md'`）
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
 - `src`: `string`
+- Other props are forwarded to `HTMLAttributes<HTMLSpanElement>`, except `role` / `aria-label` / `className` / `style`.
 
 ### Badge
 
-ステータスバッジ。
+A status badge.
 
 ```tsx
 import { Badge } from '@k8ordo/ui';
 
-<Badge label="新着" tone="info" variant="solid" />
-<Badge label="完了" tone="success" variant="outline" />
-<Badge label="フィルター" interactive />
+<Badge label="New" tone="info" variant="solid" />
+<Badge label="Done" tone="success" variant="outline" />
+<Badge label="Filter" interactive />
 ```
 
 Props:
 
-- `label`: `string`（必須）
-- `interactive`: `true`
-- `size`: `Size`
-- `tone`: `Tone`
-- `variant`: `Variant`
+- `label`: `string` (required)
+- `interactive`: `boolean`
+- `size`: `'sm'` | `'md'` | `'lg'`
+- `tone`: `'neutral'` | `'info'` | `'success'` | `'warning'` | `'error'`
+- `variant`: `'solid'` | `'outline'`
+- Other props are forwarded to `ButtonHTMLAttributes<HTMLButtonElement> | HTMLAttributes<HTMLSpanElement>`, except `children` / `className` / `style` / `type`.
 
 ### Code
 
-インラインコード表示。
+Inline code.
 
 ```tsx
 import { Code } from '@k8ordo/ui';
@@ -932,11 +1537,155 @@ import { Code } from '@k8ordo/ui';
 
 Props:
 
-- `children`: `string`（必須）
+- `children`: `string` (required)
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `className` / `style`.
 
-### Table
+### CodeBlock
 
-データテーブル。Compound component パターン。
+A block of code, highlighted on the server with shiki, with a copy button.
+It is an async Server Component on its own subpath, `@k8ordo/ui/code-block`,
+and imports `server-only`: the highlighter never reaches the browser, and
+importing it from a Client Component fails the build. Only the copy button is a
+client module.
+
+```tsx
+import { CodeBlock } from '@k8ordo/ui/code-block';
+
+<CodeBlock code={source} lang="tsx" title="save.tsx" />;
+```
+
+- `lang` is any language shiki bundles (`tsx`, `bash`, `css`, …). A name it
+  does not know renders as plain text rather than failing, so a Markdown fence
+  can pass its info string through as it is. The header shows `title` when
+  given (as the figure's `figcaption`), and the language otherwise.
+- It looks like the code blocks on k8o's blog: one surface in `bg-surface`
+  with no border, the language (or `title`, in monospace) as a small label at
+  its top, and the copy button over its top corner. The syntax colors are
+  shiki's `one-light` in light and `plastic` in dark, unchanged, written as
+  `light-dark()` so they follow the `color-scheme` the stylesheet sets with
+  `.dark`. Some of them, the comments among them, fall short of 4.5:1 on the
+  surface; the library's own accessibility checks exempt the code's text from
+  the contrast rule and nothing else. Stretched by its parent, the block gives
+  the extra height to the code, never to the label.
+- `marks` marks lines by their 1-based number, with a bar and a tint in the
+  status tokens: `highlight`, `add` (drawn with a `＋`), or `remove` (drawn
+  with a `－`). `callouts` puts a note under a line
+  (an array puts several, in order) as a bubble pointing up at it, indented
+  like the line, and tints the line it points at. A line can carry both; the
+  note's tint wins. Neither is part of the copied text: the button copies
+  `code` exactly.
+
+```tsx
+<CodeBlock
+  callouts={{ 3: 'Guard the division' }}
+  code={source}
+  lang="ts"
+  marks={{ 2: 'remove', 3: 'add' }}
+/>
+```
+
+- Inside a `.writing-v` tree it stays a horizontal island.
+- It cannot render in a generative-UI spec, which renders on the client; see
+  [generative-ui](generative-ui.md).
+
+Props:
+
+- `code`: `string` (required)
+- `callouts`: `Readonly<Record<number, string | readonly string[]>>`
+- `lang`: `string` (default: `'text'`)
+- `marks`: `Readonly<Record<number, 'highlight' | 'add' | 'remove'>>`
+- `title`: `string`
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `children` / `className` / `style`.
+
+### Kbd
+
+One keyboard key, drawn as a key cap. A shortcut is several `Kbd` side by side,
+one per key. When the key is a symbol a screen reader would not say usefully
+(`⌘`, `⇧`), pass `label`: the symbol stays on screen and the label is what is
+read out.
+
+```tsx
+import { Kbd } from '@k8ordo/ui';
+
+<Kbd>Esc</Kbd>
+
+<Kbd label="Command">⌘</Kbd>
+<Kbd>K</Kbd>
+```
+
+Props:
+
+- `children`: `string` (required)
+- `label`: `string`
+- Other props are forwarded to `HTMLAttributes<HTMLElement>`, except `className` / `style`.
+
+### Carousel
+
+Slides that scroll along the inline axis, snapping one slide at a time, with
+previous and next buttons under them. It is built on scroll snapping, so a
+trackpad, a touch swipe, and the arrow keys (the track takes focus) all move it
+as well; the buttons move one slide per press and are disabled at either end.
+
+```tsx
+import { Carousel } from '@k8ordo/ui';
+
+<Carousel.Root label="Featured posts" slideSize="md">
+  {posts.map((post) => (
+    <Carousel.Slide key={post.id} label={post.title}>
+      <PostCard post={post} />
+    </Carousel.Slide>
+  ))}
+</Carousel.Root>;
+```
+
+`slideSize` sets how much of the track one slide takes: `full` (one at a time),
+`lg` (the next one peeks in), `md` (two), `sm` (three). With `full` and `lg` the
+current position is shown as `2 / 5`; with several slides in view there is no
+single current slide, so no position is shown. The region is announced as a
+carousel and each slide as a slide (`aria-roledescription`); give a slide a
+`label` when its content has a title. The slides follow the writing mode, so
+under `.writing-v` the track scrolls vertically. There is no autoplay.
+
+Props (Carousel.Root):
+
+- `label`: `string` (required)
+- `children`: `ReactNode`
+- `slideSize`: `'full'` | `'lg'` | `'md'` | `'sm'` (default: `'full'`)
+
+Props (Carousel.Slide):
+
+- `children`: `ReactNode`
+- `label`: `string`
+
+### Prose
+
+A container that puts the typesetting of body text back — for Markdown or MDX
+rendered to HTML. Only bare elements (no `class`) are typeset, so components
+placed inside keep their own look; the spacing between blocks applies to
+everything. Tuned for Japanese: loose leading, emphasis dots for `em`, and a
+one-character paragraph indent in vertical writing. See
+[Typography](typography.md#long-form-text-prose) for what it sets.
+
+```tsx
+import { Prose } from '@k8ordo/ui';
+
+<article>
+  <Prose>
+    <MDXContent components={{ pre: MyCodeBlock }} />
+  </Prose>
+</article>;
+```
+
+Props:
+
+- `children`: `ReactNode`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style`.
+
+### Table
+
+A data table, as a compound component. `Table.EmptyState` is the row to put in
+`Table.Body` when there are no rows: it spans `colSpan` columns and draws an
+`EmptyState` with the rest of its props.
 
 ```tsx
 import { Table } from '@k8ordo/ui';
@@ -944,13 +1693,13 @@ import { Table } from '@k8ordo/ui';
 <Table.Root>
   <Table.Head>
     <Table.Row>
-      <Table.HeaderCell>名前</Table.HeaderCell>
-      <Table.HeaderCell align="right">金額</Table.HeaderCell>
+      <Table.HeaderCell>Name</Table.HeaderCell>
+      <Table.HeaderCell align="right">Amount</Table.HeaderCell>
     </Table.Row>
   </Table.Head>
   <Table.Body>
     <Table.Row interactive>
-      <Table.Cell>商品A</Table.Cell>
+      <Table.Cell>Product A</Table.Cell>
       <Table.Cell align="right">¥1,000</Table.Cell>
     </Table.Row>
   </Table.Body>
@@ -960,59 +1709,309 @@ import { Table } from '@k8ordo/ui';
 Props (Table.Body):
 
 - `children`: `ReactNode`
+- Other props are forwarded to `HTMLAttributes<HTMLTableSectionElement>`, except `className` / `style`.
 
 Props (Table.Caption):
 
 - `children`: `ReactNode`
+- Other props are forwarded to `HTMLAttributes<HTMLTableCaptionElement>`, except `className` / `style`.
 
 Props (Table.Cell):
 
-- `align`: `CellAlign`（既定: `'left'`）
+- `align`: `CellAlign` (default: `'left'`)
 - `children`: `ReactNode`
-- `color`: `'base'` | `'mute'`（既定: `'base'`）
+- `color`: `'base'` | `'mute'` (default: `'base'`)
+- Other props are forwarded to `TdHTMLAttributes<HTMLTableCellElement>`, except `className` / `style`.
 
 Props (Table.EmptyState):
 
-- `children`: `ReactNode`（必須）
-- `colSpan`: `number`（必須）
+- `colSpan`: `number` (required)
+- `title`: `string` (required)
+- `action`: `ReactNode`
+- `description`: `ReactNode`
+- `icon`: `ReactNode`
+- Other props are forwarded to `ComponentProps<typeof EmptyState>`.
 
 Props (Table.Head):
 
 - `children`: `ReactNode`
+- Other props are forwarded to `HTMLAttributes<HTMLTableSectionElement>`, except `className` / `style`.
 
 Props (Table.HeaderCell):
 
-- `align`: `CellAlign`（既定: `'left'`）
+- `align`: `CellAlign` (default: `'left'`)
 - `children`: `ReactNode`
-- `scope`: `'col'` | `'row'` | `'colgroup'` | `'rowgroup'`（既定: `'col'`）
+- `scope`: `'col'` | `'row'` | `'colgroup'` | `'rowgroup'` (default: `'col'`)
+- Other props are forwarded to `ThHTMLAttributes<HTMLTableCellElement>`, except `className` / `style`.
 
 Props (Table.Root):
 
 - `children`: `ReactNode`
+- Other props are forwarded to `TableHTMLAttributes<HTMLTableElement>`, except `className` / `style`.
 
 Props (Table.Row):
 
 - `children`: `ReactNode`
-- `interactive`: `boolean`（既定: `false`）
+- `interactive`: `boolean` (default: `false`)
+- `selected`: `boolean` (default: `false`)
+- Other props are forwarded to `HTMLAttributes<HTMLTableRowElement>`, except `className` / `style`.
+
+### DataTable
+
+A table with sorting, row selection, and column visibility. Every piece of state
+is **controlled** and owned by the caller, so it can live anywhere — component
+state, or the URL through `@k8ordo/state`'s url slot, which keeps the sort and
+the page in a shareable link. It takes functions (`cell`, `getRowId`, the
+handlers), so render it from the Client Component that owns that state.
+
+```tsx
+'use client';
+import { DataTable, type DataTableSort } from '@k8ordo/ui';
+
+const [sort, setSort] = useState<DataTableSort | null>(null);
+const [selectedIds, setSelectedIds] = useState<string[]>([]);
+const [hiddenColumnIds, setHiddenColumnIds] = useState<string[]>([]);
+
+<DataTable
+  columns={[
+    { id: 'name', header: 'Name', cell: (m) => m.name, sortable: true },
+    { id: 'role', header: 'Role', cell: (m) => m.role, hideable: false },
+  ]}
+  getRowId={(m) => m.id}
+  hiddenColumnIds={hiddenColumnIds}
+  label="Members"
+  onHiddenColumnIdsChange={setHiddenColumnIds}
+  onSelectedIdsChange={setSelectedIds}
+  onSortChange={setSort}
+  rows={sortMembers(members, sort)}
+  selectedIds={selectedIds}
+  sort={sort}
+/>;
+```
+
+- A column is a `DataTableColumn<Row>`: `id`, `header` (text), `cell(row)`
+  (what to draw), and optionally `align`, `sortable`, and `hideable`.
+- **It does not sort, filter, or page.** It draws `rows` in the order given, so
+  the same component works when the server sorts. `sort` is
+  `{ columnId, direction: 'ascending' | 'descending' } | null`; a sortable
+  header cycles ascending → descending → unsorted and carries `aria-sort`.
+  Put `Pagination` under it for pages.
+- Each feature appears only when you pass its handler: sort buttons on the
+  `sortable` columns with `onSortChange`, a checkbox column with
+  `onSelectedIdsChange`, and a "Columns" menu (every column but those with
+  `hideable: false`) with `onHiddenColumnIdsChange`.
+- The header checkbox selects or clears the rows on screen and shows the mixed
+  state when some are selected (`Checkbox`'s `indeterminate`). The first column
+  is the row header (`th scope="row"`), and each row's checkbox is named after
+  it ("Select row Aoki").
+- `emptyState` is drawn in a row spanning the columns when `rows` is empty —
+  pass an `EmptyState`.
+- Selected rows use `Table.Row`'s `selected`. For bulk actions, render your own
+  bar above the table from `selectedIds`.
+
+Props:
+
+- `columns`: `ReadonlyArray<DataTableColumn<Row>>` (required)
+- `getRowId`: `(row: Row) => string` (required)
+- `label`: `string` (required)
+- `rows`: `readonly Row[]` (required)
+- `emptyState`: `ReactNode`
+- `hiddenColumnIds`: `readonly string[]` (default: `NONE`)
+- `onHiddenColumnIdsChange`: `(ids: string[]) => void`
+- `onSelectedIdsChange`: `(ids: string[]) => void`
+- `onSortChange`: `(sort: DataTableSort | null) => void`
+- `selectedIds`: `readonly string[]` (default: `NONE`)
+- `sort`: `DataTableSort` | `null` (default: `null`)
+
+### Tree
+
+A hierarchy whose parents open and close — files and folders, an outline —
+with the WAI-ARIA tree view keyboard model. Pass the nodes as a tree of
+`{ id, label, icon?, children? }`.
+
+```tsx
+import { Tree } from '@k8ordo/ui';
+
+<Tree
+  defaultExpandedIds={['src']}
+  items={[
+    {
+      id: 'src',
+      label: 'src',
+      children: [{ id: 'index', label: 'index.ts' }],
+    },
+    { id: 'readme', label: 'README.md' },
+  ]}
+  label="Files"
+  onChange={(id) => open(id)}
+/>;
+```
+
+- Which parents are open is controllable (`expandedIds` / `defaultExpandedIds`
+  / `onExpandedChange`), and so is the selected node (`selectedId` /
+  `defaultSelectedId` / `onChange`, called with the node's `id`).
+- Keyboard: Down / Up move between the visible nodes; Right opens a closed
+  parent, then moves to its first child; Left closes an open parent, or moves
+  to the parent; Home / End go to the first / last visible node; Enter or Space
+  selects; a character moves to the next node whose label starts with it.
+- Clicking a node selects it and, on a parent, opens or closes it.
+- One node takes Tab at a time (roving tabindex): the focused one, else the
+  selected one, else the first.
+- Under `.writing-v` the nodes run right to left, so Left / Right move between
+  them and Down / Up open and close.
+
+Props:
+
+- `items`: `readonly TreeItem[]` (required)
+- `label`: `string` (required)
+- `defaultExpandedIds`: `readonly string[]`
+- `defaultSelectedId`: `string` | `null` (default: `null`)
+- `expandedIds`: `readonly string[]`
+- `onChange`: `(id: string) => void`
+- `onExpandedChange`: `(ids: readonly string[]) => void`
+- `selectedId`: `string` | `null`
+- Other props are forwarded to `HTMLAttributes<HTMLUListElement>`, except `children` / `className` / `style` / `role` / `aria-label`.
+
+### Accordion
 
-## フィードバック
+A collapsible section, as a compound component.
+
+```tsx
+import { Accordion } from '@k8ordo/ui';
+
+<Accordion.Root>
+  <Accordion.Item>
+    <Accordion.Button>Section 1</Accordion.Button>
+    <Accordion.Panel>Content</Accordion.Panel>
+  </Accordion.Item>
+</Accordion.Root>;
+```
+
+Props (Accordion.Button):
+
+- `children`: `ReactNode`
+
+Props (Accordion.Item):
+
+- `children`: `ReactNode`
+- `defaultOpen`: `boolean` (default: `false`)
+- `isOpen`: `boolean`
+- `onChange`: `(isOpen: boolean) => void`
+
+Props (Accordion.Panel):
+
+- `children`: `ReactNode`
+
+Props (Accordion.Root):
+
+- `children`: `ReactNode`
+
+### Card
+
+A card that groups content.
+
+```tsx
+import { Card } from '@k8ordo/ui';
+
+// Static card. The card has no padding of its own
+<Card width="full" variant="shadow">
+  <div style={{ padding: 'calc(var(--spacing) * 6)' }}>Content</div>
+</Card>
+
+// Clickable card (scales to 1.02 on hover and to 0.98 while pressed)
+<Card variant="outline" interactive>
+  <div style={{ padding: 'calc(var(--spacing) * 6)' }}>Content</div>
+</Card>
+```
+
+Props:
+
+- `children`: `ReactNode`
+- `interactive`: `boolean` (default: `false`)
+- `variant`: `'shadow'` | `'outline'` (default: `'shadow'`)
+- `width`: `'full'` | `'fit'` (default: `'full'`)
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style`.
+
+## Feedback
 
 ### Alert
 
+Reports a status: the result of something the user did, or a state the
+application is in. It is a live region (`role="alert"` for `warning` and
+`error`, `role="status"` otherwise), so a screen reader announces it when it
+appears. For a note that is part of the content, use `Callout`.
+
 ```tsx
 import { Alert } from '@k8ordo/ui';
 
-<Alert tone="info" message="情報メッセージ" />
-<Alert tone="error" message={['エラー1', 'エラー2']} />
+<Alert tone="info" message="An informational message" />
+<Alert tone="error" message={['Error 1', 'Error 2']} />
 ```
 
 Props:
 
-- `message`: `string` | `string[]`（必須）
-- `tone`: `Status`（必須）
+- `message`: `string` | `string[]` (required)
+- `tone`: `Status` (required)
 - `action`: `AlertAction`
 - `closeLabel`: `string`
 - `onClose`: `() => void`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `children` / `role` / `className` / `style`.
+
+`action` is an `AlertAction`, `{ label: string; renderItem: (props: { children: ReactNode }) => ReactNode }`.
+`renderItem` receives `label` as `children`; render your own button or link
+around it.
+
+### Callout
+
+A note that sits in the content: a tip beside a paragraph, a pitfall in a
+guide, a dated-content notice at the top of an article. Unlike `Alert`, it is
+not a live region (`role="note"`), so a page that renders one, or a client
+navigation that brings one in, does not have it announced as a warning. The
+body is `children`, so it can hold paragraphs, `Code`, and links; `label` is an
+optional bold line above it.
+
+```tsx
+import { Callout, Code } from '@k8ordo/ui';
+
+<Callout label="Pitfall" tone="warning">
+  <p>
+    Passing <Code>value</Code> makes the field controlled, and a form reset no
+    longer restores it.
+  </p>
+</Callout>;
+```
+
+Props:
+
+- `children`: `ReactNode` (required)
+- `tone`: `Status` (required)
+- `label`: `string`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `role` / `className` / `style`.
+
+### EmptyState
+
+What a list, a table, or a search shows when there is nothing in it: a title,
+an optional description and icon, and an optional action. Inside a table, use
+`Table.EmptyState`, which puts the same content in a row spanning the columns.
+
+```tsx
+import { Button, EmptyState, TableIcon } from '@k8ordo/ui';
+
+<EmptyState
+  action={<Button onClick={clearFilters}>Clear filters</Button>}
+  description="Try removing a filter."
+  icon={<TableIcon size="lg" />}
+  title="No matching posts"
+/>;
+```
+
+Props:
+
+- `title`: `string` (required)
+- `action`: `ReactNode`
+- `description`: `ReactNode`
+- `icon`: `ReactNode`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `children` / `className` / `style`.
 
 ### Toast
 
@@ -1021,21 +2020,26 @@ import { useToast } from '@k8ordo/ui';
 
 const { open, close, closeAll } = useToast();
 
-open('success', '保存しました');
-open('error', 'エラーが発生しました');
+open('success', 'Saved');
+open('error', 'Something went wrong');
+
+const syncingId = open('info', 'Syncing…', {
+  duration: Number.POSITIVE_INFINITY,
+});
+close(syncingId);
 ```
 
-`ToastProvider` は `UIProvider` に含まれるため、別途ラップ不要。
+`ToastProvider` is already inside `UIProvider`, so no extra wrapper is needed.
 
-`useToast()` の戻り値:
+What `useToast()` returns:
 
-- `open`: `(tone: Status, message: string, options?: ToastOptions) => void`（`ToastOptions` は `{ duration?: number; action?: ToastAction }`）
-- `close`: `(id: string) => void`
+- `open`: `(tone: Status, message: string, options?: ToastOptions) => string` (returns the toast's id; `ToastOptions` is `{ duration?: number; action?: ToastAction }`. `duration` is in milliseconds and defaults to `5000`; `Number.POSITIVE_INFINITY` keeps the toast until it is closed. `ToastAction` is the same type as `AlertAction`.)
+- `close`: `(id: string) => void` (closes only the toast with the id `open` returned)
 - `closeAll`: `() => void`
 
 ### ToastProvider
 
-出す位置や Portal 先を変えたいときだけ、`UIProvider` の内側で明示的にラップする。
+Wrap explicitly inside `UIProvider` only when you want to change where toasts appear or which Portal root they use.
 
 ```tsx
 import { ToastProvider } from '@k8ordo/ui';
@@ -1048,43 +2052,53 @@ import { ToastProvider } from '@k8ordo/ui';
 Props:
 
 - `children`: `ReactNode`
-- `portalRef`: `RefObject<HTMLElement | null>`（既定: `null`）
-- `position`: `'fixed'` | `'absolute'`（既定: `'fixed'`）
+- `portalRef`: `RefObject<HTMLElement | null>` (default: `null`)
+- `position`: `'fixed'` | `'absolute'` (default: `'fixed'`)
 
 ### Progress
 
+Leave `value` out when how far along it is cannot be known: the bar then slides
+back and forth, has no `aria-valuenow`, and is named `label` (the built-in
+`loading` wording when omitted). With reduced motion it stops sliding and
+pulses across the whole track instead.
+
 ```tsx
 import { Progress } from '@k8ordo/ui';
 
-<Progress value={50} max={100} />
-<Progress value={50} max={100} min={0} label="進捗" />
+<Progress value={50} />
+<Progress value={150} max={200} min={100} label="Progress" />
+
+// Progress that cannot be measured
+<Progress label="Uploading" />
 ```
 
 Props:
 
-- `max`: `number`（必須）
-- `value`: `number`（必須）
 - `label`: `string`
-- `min`: `number`（既定: `0`）
+- `max`: `number` (default: `100`)
+- `min`: `number` (default: `0`)
+- `value`: `number`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `children` / `className` / `style`.
 
 ### Spinner
 
-ローディングスピナー。
+A loading spinner.
 
 ```tsx
 import { Spinner } from '@k8ordo/ui';
 
-<Spinner size="md" label="読み込み中" />;
+<Spinner size="md" label="Loading" />;
 ```
 
 Props:
 
 - `label`: `string`
-- `size`: `'sm'` | `'md'` | `'lg'`（既定: `'md'`）
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
+- Other props are forwarded to `OutputHTMLAttributes<HTMLOutputElement>`, except `children` / `aria-label` / `className` / `style`.
 
 ### Skeleton
 
-コンテンツプレースホルダー。
+A content placeholder.
 
 ```tsx
 import { Skeleton } from '@k8ordo/ui';
@@ -1096,21 +2110,22 @@ import { Skeleton } from '@k8ordo/ui';
 
 Props:
 
-- `animate`: `boolean`（既定: `true`）
-- `shape`: `'rect'` | `'circle'`（既定: `'rect'`）
-- `size`: `'sm'` | `'md'` | `'lg'`（既定: `'md'`）
+- `animate`: `boolean` (default: `true`)
+- `shape`: `'rect'` | `'circle'` (default: `'rect'`)
+- `size`: `'sm'` | `'md'` | `'lg'` (default: `'md'`)
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `children` / `className` / `style`.
 
-## オーバーレイ
+## Overlays
 
 ### Modal
 
-ベースのオーバーレイコンポーネント。`<dialog>` 要素を使用。
+The base overlay component. It uses the `<dialog>` element.
 
 ```tsx
 import { Modal } from '@k8ordo/ui';
 
 <Modal isOpen={open} onClose={onClose} side="center">
-  コンテンツ
+  Content
 </Modal>;
 ```
 
@@ -1124,27 +2139,27 @@ Props:
 - `isOpen`: `boolean`
 - `onClose`: `() => void`
 - `ref`: `Ref<HTMLDialogElement>`
-- `side`: `ModalSide`（既定: `'center'`）
+- `side`: `ModalSide` (default: `'center'`)
 
-名前の解決順は `aria-label` / `aria-labelledby` > 中の `Dialog.Root` が登録した見出し。どちらも無ければ無名の dialog になるため、`Dialog` を入れずに直接コンテンツを置くときは `aria-label` を渡す。
+Name resolution goes `aria-label` / `aria-labelledby` first, then the heading registered by a `Dialog.Root` inside. With neither, the dialog is unnamed — so pass `aria-label` when you place content directly without a `Dialog`.
 
 ```tsx
-<Modal aria-label="画像プレビュー" isOpen={open} onClose={onClose}>
+<Modal aria-label="Image preview" isOpen={open} onClose={onClose}>
   <img alt="" src={src} />
 </Modal>
 ```
 
 ### Dialog
 
-Compound component パターン。Modal と組み合わせて使用。
+A compound component, used together with Modal.
 
 ```tsx
 import { Modal, Dialog } from '@k8ordo/ui';
 
 <Modal isOpen={open} onClose={onClose}>
   <Dialog.Root>
-    <Dialog.Header title="確認" onClose={onClose} />
-    <Dialog.Content>コンテンツ</Dialog.Content>
+    <Dialog.Header title="Confirm" onClose={onClose} />
+    <Dialog.Content>Content</Dialog.Content>
   </Dialog.Root>
 </Modal>;
 ```
@@ -1155,8 +2170,8 @@ Props (Dialog.Content):
 
 Props (Dialog.Header):
 
-- `onClose`: `() => void`（必須）
-- `title`: `ReactNode`（必須）
+- `onClose`: `() => void` (required)
+- `title`: `ReactNode` (required)
 
 Props (Dialog.Root):
 
@@ -1166,38 +2181,85 @@ Props (Dialog.Root):
 - `role`: `'dialog'` | `'alertdialog'`
 - `tabIndex`: `number`
 
+### CommandPalette
+
+A command palette: a `Modal` holding a search field and the list of commands it
+filters. Typing matches each item's `label` and `keywords`, case-insensitively.
+`ArrowDown` / `ArrowUp` move through the matches and wrap around, `Enter` or a
+click runs the item's `onSelect` after closing the palette, and `Escape` closes
+it; focus stays in the search field throughout (the WAI-ARIA combobox, with the
+list always shown). Items that share a `group` are gathered under that heading,
+in the order the group first appears, and `shortcut` keys are drawn with `Kbd`.
+Each opening starts from an empty search. Open and close it like `Modal`
+(`isOpen` / `defaultOpen` / `onClose`); a key such as ⌘K / Ctrl+K is the
+application's to wire.
+
+```tsx
+import { CommandPalette } from '@k8ordo/ui';
+
+<CommandPalette
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  items={[
+    {
+      id: 'new-file',
+      label: 'New file',
+      group: 'File',
+      shortcut: ['⌘', 'N'],
+      onSelect: createFile,
+    },
+    {
+      id: 'theme',
+      label: 'Toggle theme',
+      keywords: ['dark', 'light'],
+      onSelect: toggleTheme,
+    },
+  ]}
+/>;
+```
+
+Props:
+
+- `items`: `readonly CommandPaletteItem[]` (required)
+- `aria-label`: `string`
+- `defaultOpen`: `boolean`
+- `isOpen`: `boolean`
+- `onClose`: `() => void`
+- `placeholder`: `string`
+- `ref`: `Ref<HTMLDialogElement>`
+
 ### Drawer
 
-サイドパネル。内部で Modal を使用。
+A side panel. It uses Modal internally.
 
 ```tsx
 import { Drawer } from '@k8ordo/ui';
 
-<Drawer title="メニュー" isOpen={open} onClose={onClose} side="right">
-  コンテンツ
+<Drawer title="Menu" isOpen={open} onClose={onClose} side="right">
+  Content
 </Drawer>;
 ```
 
 Props:
 
-- `title`: `ReactNode`（必須）
+- `title`: `ReactNode` (required)
 - `children`: `ReactNode`
 - `defaultOpen`: `boolean`
 - `isOpen`: `boolean`
 - `onClose`: `() => void`
-- `side`: `DrawerSide`（既定: `'right'`）
+- `side`: `DrawerSide` (default: `'right'`)
 
 ### Popover
 
-CSS Anchor Positioning ベースのポップオーバー。Compound component パターン。
+A popover built on CSS Anchor Positioning, as a compound component.
 
 ```tsx
 import { Popover } from '@k8ordo/ui';
 
 <Popover.Root placement="bottom">
-  <Popover.Trigger renderItem={(props) => <Button {...props}>開く</Button>} />
+  <Popover.Trigger renderItem={(props) => <Button {...props}>Open</Button>} />
   <Popover.Content
-    renderItem={(props) => <div {...props}>ポップオーバーコンテンツ</div>}
+    renderItem={(props) => <div {...props}>Popover content</div>}
   />
 </Popover.Root>;
 ```
@@ -1205,48 +2267,48 @@ import { Popover } from '@k8ordo/ui';
 Props (Root):
 
 - `children`: `ReactNode`
-- `closeOnClickAway`: `boolean`（既定: `true`）
-- `defaultOpen`: `boolean`（既定: `false`）
-- `flipDisabled`: `boolean`（既定: `false`）
+- `closeOnClickAway`: `boolean` (default: `true`)
+- `defaultOpen`: `boolean` (default: `false`)
+- `flipDisabled`: `boolean` (default: `false`)
 - `isOpen`: `boolean`
 - `onChange`: `(isOpen: boolean) => void`
-- `placement`: `Placement`（既定: `'bottom-start'`）
-- `role`: `'dialog'` | `'menu'` | `'listbox'`（既定: `'menu'`）
-- `trapFocus`: `boolean`（既定: `true`）
+- `placement`: `Placement` (default: `'bottom-start'`)
+- `role`: `'dialog'` | `'menu'` | `'listbox'` (default: `'menu'`)
+- `trapFocus`: `boolean` (default: `true`)
 
-Escape は入れ子のうち**最も内側の 1 枚だけ**を閉じる。
+Escape closes **only the innermost one** when they are nested.
 
 Props (Popover.Content):
 
-- `renderItem`: `(props: PopoverContentProps) => ReactElement`（必須）
-- `animation`: `'scale'` | `'fade'`（既定: `'scale'`）
+- `renderItem`: `(props: PopoverContentProps) => ReactElement` (required)
+- `animation`: `'scale'` | `'fade'` (default: `'scale'`)
 
 Props (Popover.Trigger):
 
-- `renderItem`: `(props: PopoverTriggerProps) => ReactElement`（必須）
+- `renderItem`: `(props: PopoverTriggerProps) => ReactElement` (required)
 
 ### Tooltip
 
-ツールチップ。Compound component パターン。
+A tooltip, as a compound component.
 
 ```tsx
 import { Tooltip } from '@k8ordo/ui';
 
 <Tooltip.Root placement="top">
-  <Tooltip.Trigger renderItem={(props) => <Button {...props}>ホバー</Button>} />
-  <Tooltip.Content>ヒント</Tooltip.Content>
+  <Tooltip.Trigger renderItem={(props) => <Button {...props}>Hover</Button>} />
+  <Tooltip.Content>A hint</Tooltip.Content>
 </Tooltip.Root>;
 ```
 
 Props (Root):
 
 - `children`: `ReactNode`
-- `closeDelay`: `number`（既定: `150`）
+- `closeDelay`: `number` (default: `150`)
 - `defaultOpen`: `boolean`
 - `isOpen`: `boolean`
 - `onChange`: `(isOpen: boolean) => void`
-- `openDelay`: `number`（既定: `0`）
-- `placement`: `Placement`（既定: `'bottom'`）
+- `openDelay`: `number` (default: `0`)
+- `placement`: `Placement` (default: `'bottom'`)
 
 Props (Tooltip.Content):
 
@@ -1254,20 +2316,20 @@ Props (Tooltip.Content):
 
 Props (Tooltip.Trigger):
 
-- `renderItem`: `(props: TooltipTriggerProps) => ReactElement`（必須）
+- `renderItem`: `(props: TooltipTriggerProps) => ReactElement` (required)
 
 ### DropdownMenu
 
-ドロップダウンメニュー。Compound component パターン。
+A dropdown menu, as a compound component.
 
 ```tsx
 import { DropdownMenu } from '@k8ordo/ui';
 
 <DropdownMenu.Root>
-  <DropdownMenu.Trigger label="メニュー" />
+  <DropdownMenu.Trigger label="Menu" />
   <DropdownMenu.Content>
-    <DropdownMenu.Item label="アイテム1" onAction={handleClick} />
-    <DropdownMenu.Item label="アイテム2" onAction={handleClick} />
+    <DropdownMenu.Item label="Item 1" onAction={handleClick} />
+    <DropdownMenu.Item label="Item 2" onAction={handleClick} />
   </DropdownMenu.Content>
 </DropdownMenu.Root>;
 ```
@@ -1278,12 +2340,12 @@ Props (Root):
 - `defaultOpen`: `boolean`
 - `isOpen`: `boolean`
 - `onChange`: `(isOpen: boolean) => void`
-- `placement`: `Placement`（既定: `'bottom-start'`）
+- `placement`: `Placement` (default: `'bottom-start'`)
 
-Trigger バリアント:
+Trigger variants:
 
-- `DropdownMenu.Trigger`: テキストベース（`label`, `size`, `variant`）
-- `DropdownMenu.IconTrigger`: アイコンベース（`icon`, `label`）
+- `DropdownMenu.Trigger`: text-based (`label`, `size`, `variant`)
+- `DropdownMenu.IconTrigger`: icon-based (`icon`, `label`)
 
 Props (DropdownMenu.Content):
 
@@ -1291,30 +2353,90 @@ Props (DropdownMenu.Content):
 
 Props (DropdownMenu.IconTrigger):
 
-- `icon`: `ReactNode`（必須）
-- `label`: `string`（必須）
+- `icon`: `ReactNode` (required)
+- `label`: `string` (required)
 
 Props (DropdownMenu.Item):
 
-- `label`: `string`（必須）
-- `onAction`: `() => void`（必須）
+- `label`: `string` (required)
+- `onAction`: `() => void` (required)
 
-`DropdownMenu.SubMenu` は入れ子メニュー。`label` の行をホバーまたはキーボードで開くと、子要素のメニューが右側に開く。
+`DropdownMenu.SubMenu` is a nested menu. Hovering the `label` row, or opening it from the keyboard, opens the child menu to the right.
 
 Props (DropdownMenu.SubMenu):
 
-- `label`: `string`（必須）
+- `label`: `string` (required)
 - `children`: `ReactNode`
 
 Props (DropdownMenu.Trigger):
 
-- `label`: `string`（必須）
-- `size`: `ComponentProps<typeof Button>['size']`（既定: `'md'`）
-- `variant`: `ComponentProps<typeof Button>['variant']`（既定: `'solid'`）
+- `label`: `string` (required)
+- `size`: `ComponentProps<typeof Button>['size']` (default: `'md'`)
+- `variant`: `ComponentProps<typeof Button>['variant']` (default: `'solid'`)
+
+### ContextMenu
+
+A menu opened by right-clicking (or by the keyboard's context-menu key or
+Shift+F10) on an area, shown at the pointer. The inside is `DropdownMenu`'s —
+`ContextMenu.Content`, `ContextMenu.Item` (`label` / `onAction`), and
+`ContextMenu.SubMenu` behave exactly like theirs — and only how it opens and
+where differ. When it closes from inside (an item, Escape), focus returns to
+the element that had it before it opened; closing by clicking elsewhere leaves
+focus where the click put it.
+
+`ContextMenu.Trigger` fills a slot: `renderItem` receives `onContextMenu` to
+put on the area. To open it from the keyboard, the area (or something in it)
+has to be able to take focus.
+
+```tsx
+import { ContextMenu } from '@k8ordo/ui';
+
+<ContextMenu.Root>
+  <ContextMenu.Trigger
+    renderItem={(props) => (
+      <div {...props} tabIndex={0}>
+        report.pdf
+      </div>
+    )}
+  />
+  <ContextMenu.Content>
+    <ContextMenu.Item label="Rename" onAction={rename} />
+    <ContextMenu.SubMenu label="Move to">
+      <ContextMenu.Item label="Archive" onAction={archive} />
+    </ContextMenu.SubMenu>
+    <ContextMenu.Item label="Delete" onAction={remove} />
+  </ContextMenu.Content>
+</ContextMenu.Root>;
+```
+
+Props (Root):
+
+- `children`: `ReactNode`
+- `defaultOpen`: `boolean`
+- `isOpen`: `boolean`
+- `onChange`: `(isOpen: boolean) => void`
+
+Props (ContextMenu.Content):
+
+- `children`: `ReactNode`
+
+Props (ContextMenu.Item):
+
+- `label`: `string` (required)
+- `onAction`: `() => void` (required)
+
+Props (ContextMenu.SubMenu):
+
+- `label`: `string` (required)
+- `children`: `ReactNode`
+
+Props (ContextMenu.Trigger):
+
+- `renderItem`: `(props: { onContextMenu: MouseEventHandler<HTMLElement>; }) => ReactElement` (required)
 
 ### ListBox
 
-リスト選択。Compound component パターン。選択肢は `Select` と同じ `Option`（`{ value, label }`）。
+List selection, as a compound component. The choices use the same `Option` (`{ value, label }`) as `Select`.
 
 ```tsx
 import { ListBox } from '@k8ordo/ui';
@@ -1322,31 +2444,31 @@ import { ListBox } from '@k8ordo/ui';
 <ListBox.Root
   onChange={onChange}
   options={[
-    { value: '1', label: 'オプション1' },
-    { value: '2', label: 'オプション2' },
+    { value: '1', label: 'Option 1' },
+    { value: '2', label: 'Option 2' },
   ]}
   value={value}
 >
-  <ListBox.Trigger label="表示件数" size="md" />
+  <ListBox.Trigger label="Items per page" size="md" />
   <ListBox.Content />
 </ListBox.Root>;
 ```
 
 Props (Root):
 
-- `options`: `readonly Option[]`（必須）
+- `options`: `readonly Option[]` (required)
 - `children`: `ReactNode`
 - `defaultValue`: `Option['value']`
 - `onChange`: `(value: Option['value']) => void`
-- `placement`: `Placement`（既定: `'bottom'`）
+- `placement`: `Placement` (default: `'bottom'`)
 - `value`: `Option['value']`
 
-Trigger バリアント:
+Trigger variants:
 
-- `ListBox.Trigger`: テキストベース（`size`, `label`）
-- `ListBox.IconTrigger`: アイコンベース（`size`, `icon`, `label`）
+- `ListBox.Trigger`: text-based (`size`, `label`)
+- `ListBox.IconTrigger`: icon-based (`size`, `icon`, `label`)
 
-`label` を渡すとトリガーのアクセシブル名が「ラベル + 現在値」になる。省略すると現在値だけになるため、周囲に見出しが無いときは渡す。
+Passing `label` makes the trigger's accessible name "label + current value". Omit it and only the current value is used, so pass it when there is no heading nearby.
 
 Props (Content):
 
@@ -1354,113 +2476,421 @@ Props (Content):
 
 Props (ListBox.IconTrigger):
 
-- `icon`: `ReactElement`（必須）
+- `icon`: `ReactElement` (required)
 - `label`: `string`
-- `size`: `ComponentProps<typeof Button>['size']`（既定: `'md'`）
+- `size`: `ComponentProps<typeof Button>['size']` (default: `'md'`)
 
 Props (ListBox.Trigger):
 
 - `label`: `string`
-- `size`: `ComponentProps<typeof Button>['size']`（既定: `'md'`）
+- `size`: `ComponentProps<typeof Button>['size']` (default: `'md'`)
 
-## プロバイダー
+## Layout
 
-### UIProvider
+### Separator
 
-アプリのルートで1回ラップする。ToastProvider と文言辞書（下記 i18n）を含む。
+A dividing rule.
 
 ```tsx
-import { UIProvider } from '@k8ordo/ui';
+import { Separator } from '@k8ordo/ui';
 
-<UIProvider>
-  <App />
-</UIProvider>;
+<Separator />
+<Separator color="mute" />
+<Separator color="subtle" />
+<Separator orientation="vertical" />
 ```
 
 Props:
 
+- `color`: `'base'` | `'mute'` | `'subtle'` (default: `'base'`)
+- `orientation`: `'horizontal'` | `'vertical'` (default: `'horizontal'`)
+- Other props are forwarded to `HTMLAttributes<HTMLSpanElement>`, except `children` / `role` / `aria-orientation` / `className` / `style`.
+
+### Stack
+
+Lays children out along one axis. Pick `gap` from the spacing tokens.
+
+```tsx
+import { Stack } from '@k8ordo/ui';
+
+<Stack gap="lg">
+  <Card>1</Card>
+  <Card>2</Card>
+</Stack>
+
+<Stack direction="row" justify="between" align="center">
+  <Heading level="h2">Title</Heading>
+  <Button>Action</Button>
+</Stack>
+```
+
+Props:
+
+- `align`: `'start'` | `'center'` | `'end'` | `'stretch'`
 - `children`: `ReactNode`
-- `messages`: `Partial<Messages>`
+- `direction`: `'row'` | `'column'` (default: `'column'`)
+- `gap`: `GapSize` (default: `'md'`)
+- `justify`: `'start'` | `'center'` | `'end'` | `'between'`
+- `padding`: `PaddingSize`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style`.
 
-### PortalRootProvider
+### Grid
 
-Portal のルート要素を指定する。
+A grid layout. Passing `'auto-fill'` or `'auto-fit'` to `cols` wraps with `minItemSize` as the lower bound.
 
 ```tsx
-import { PortalRootProvider, usePortalRoot } from '@k8ordo/ui';
+import { Grid } from '@k8ordo/ui';
 
-<PortalRootProvider value={containerRef}>{children}</PortalRootProvider>;
+<Grid cols={3} gap="md">
+  <Card>1</Card>
+  <Card>2</Card>
+  <Card>3</Card>
+</Grid>
+
+<Grid cols="auto-fill" minItemSize={64}>
+  {items.map((item) => (
+    <Card key={item.id}>{item.name}</Card>
+  ))}
+</Grid>
 ```
 
 Props:
 
 - `children`: `ReactNode`
-- `value`: `RefObject<HTMLElement | null>`
+- `cols`: `1` | `2` | `3` | `4` | `5` | `6` | `'auto-fill'` | `'auto-fit'` (default: `'auto-fill'`)
+- `gap`: `GapSize` (default: `'md'`)
+- `minItemSize`: `24` | `32` | `40` | `48` | `64` | `80` (default: `48`)
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style`.
+
+### ResizablePanels
+
+Two panes with a divider between them that the user drags or moves with the
+arrow keys (the WAI-ARIA window splitter). `value` is the first pane's share in
+percent, kept between `min` and `max`; the second pane takes the rest. The root
+fills its parent, so give that parent a size — a vertical split needs a height.
+Each pane scrolls on its own.
+
+The divider is a focusable `separator` whose value is the first pane's size and
+whose `aria-controls` points at it. The arrow keys move it the way they point
+on screen — left/right when the panes sit side by side, up/down when they are
+stacked — so in a right-to-left page `ArrowLeft` widens a first pane that sits
+on the right; `Home` / `End` jump to `min` / `max`. `orientation="horizontal"`
+lays the panes along the line of text, so in vertical writing mode they stack.
+Name the divider after the first pane with `aria-labelledby` when it has a
+heading; otherwise it falls back to `resizablePanelsHandle` from the dictionary.
+
+```tsx
+import { ResizablePanels } from '@k8ordo/ui';
+
+<div style={{ height: '24rem' }}>
+  <ResizablePanels.Root defaultValue={25}>
+    <ResizablePanels.Panel>
+      <h2 id="files">Files</h2>
+    </ResizablePanels.Panel>
+    <ResizablePanels.Handle aria-labelledby="files" />
+    <ResizablePanels.Panel>…</ResizablePanels.Panel>
+  </ResizablePanels.Root>
+</div>;
+```
+
+Props (Root):
+
+- `children`: `ReactNode`
+- `defaultValue`: `number` (default: `50`)
+- `max`: `number` (default: `90`)
+- `min`: `number` (default: `10`)
+- `onChange`: `(value: number) => void`
+- `orientation`: `'horizontal'` | `'vertical'` (default: `'horizontal'`)
+- `ref`: `Ref<HTMLDivElement>`
+- `step`: `number` (default: `5`)
+- `value`: `number`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style`.
+
+Props (ResizablePanels.Panel):
+
+- `children`: `ReactNode`
+- `ref`: `Ref<HTMLDivElement>`
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style`.
+
+Props (ResizablePanels.Handle):
+
+- _No props of its own._
+- Other props are forwarded to `HTMLAttributes<HTMLDivElement>`, except `className` / `style` / `role` / `children` / `tabIndex` / `aria-orientation` / `aria-valuenow` / `aria-valuemin` / `aria-valuemax` / `aria-controls`.
+
+## Observers
+
+Components that watch their children and report back without adding a wrapper
+element. They are built on React's Fragment refs, so whatever the children
+render is what gets observed — including host elements that mount later.
+
+### InView
+
+Reports whether its children are inside the viewport, or inside `root`.
+
+```tsx
+import { InView } from '@k8ordo/ui';
+
+const [isInView, setIsInView] = useState(false);
+
+<InView onChange={setIsInView}>
+  <section>…</section>
+</InView>;
+
+// inside a scroll container, and only until it has been seen once
+const [container, setContainer] = useState<HTMLElement | null>(null);
+
+<div ref={setContainer} style={{ overflowY: 'auto' }}>
+  <InView once onChange={reveal} root={container} rootMargin="0px 0px 24px 0px">
+    <img alt="" src="…" />
+  </InView>
+</div>;
+```
+
+- `onChange` reports the state as soon as a host element is observed, then again
+  each time it flips. The same value is never reported twice in a row, even
+  when `root` changes and the observer is re-created.
+- With several host elements, `isInView` is `true` while **any** of them
+  intersects, and it follows children that mount or unmount later. While the
+  children render no host element, `onChange` is not called at all — the first
+  report comes once one mounts.
+- `once` stops observing after the first `true`.
+- Hold `root` in state, not a `RefObject`: the observer has to be re-created
+  once the element exists.
+
+Props:
+
+- `children`: `ReactNode` (required)
+- `onChange`: `(isInView: boolean) => void` (required)
+- `once`: `boolean` (default: `false`)
+- `root`: `Element` | `null` (default: `null`)
+- `rootMargin`: `string` (default: `'0px'`)
+- `threshold`: `number` (default: `0`)
+
+### Resize
+
+Calls `onChange` when the size of its children changes.
+
+```tsx
+import { Resize } from '@k8ordo/ui';
+
+<Resize onChange={remeasure}>
+  <div>…</div>
+</Resize>;
+```
+
+- `onChange` is also called once when observation starts, as a native
+  `ResizeObserver` is.
+- It takes no argument; read what you need from the DOM in the handler.
+
+Props:
 
-## i18n（文言辞書）
+- `children`: `ReactNode` (required)
+- `onChange`: `() => void` (required)
 
-コンポーネントが内部で持つ文言（閉じる、必須、読み込み中 …）は辞書から引く。**既定は日本語**で、Provider を置かなくても、`messages` を渡さなくても日本語で動く。
+## Icons
 
-英語に切り替えるときは `@k8ordo/ui/i18n` の `en` を渡す。
+Decorative icons, all from the root entry. Each renders an `<svg>` with
+`aria-hidden` and `focusable="false"`, so the accessible name belongs to the
+control around it — an `IconButton`'s `label`, for example.
+
+```tsx
+import { AlertIcon, ChevronIcon, CloseIcon } from '@k8ordo/ui';
+
+<CloseIcon />
+<ChevronIcon direction="down" size="sm" />
+<AlertIcon status="warning" />
+```
+
+Every icon takes one optional prop and nothing else:
+
+- `size`: `'xs'` | `'sm'` | `'md'` | `'lg'` | `'xl'` | `'2xl'` | `'3xl'` (default: `'md'`)
+
+Two of them also require a prop that picks the glyph:
+
+- `ChevronIcon`: `direction`: `Direction` (`'up'` | `'down'` | `'left'` | `'right'`)
+- `AlertIcon`: `status`: `Status` (`'success'` | `'info'` | `'warning'` | `'error'`)
+
+<!-- generated:icons -->
+
+The icons: `AccessibilityIcon`, `AIIcon`, `AlertIcon`, `AssistantIcon`,
+`AtomIcon`, `BadIcon`, `BlogIcon`, `BoringIcon`, `CheckIcon`, `ChevronIcon`,
+`ChromeIcon`, `CloseIcon`, `CodeXmlIcon`, `ColorContrastIcon`, `ColorInfoIcon`,
+`ColorScaleIcon`, `CopyIcon`, `DarkModeIcon`, `DifficultIcon`, `EasyIcon`,
+`EdgeIcon`, `ExternalLinkIcon`, `FirefoxIcon`, `FlaskIcon`, `ForkIcon`,
+`FormIcon`, `FullscreenIcon`, `GitHubIcon`, `GoodIcon`, `HistoryIcon`,
+`HorizontalWritingIcon`, `InformativeIcon`, `InterestingIcon`, `LightModeIcon`,
+`LinkIcon`, `ListIcon`, `LocationIcon`, `LockIcon`, `LockOpenIcon`, `LogoIcon`,
+`MailIcon`, `MinusIcon`, `MixedColorIcon`, `NavigationMenuIcon`, `NewsIcon`,
+`PackageIcon`, `PaletteIcon`, `PlusIcon`, `PrepareIcon`, `PublishDateIcon`,
+`QiitaIcon`, `RefreshIcon`, `RSSIcon`, `SafariIcon`, `SendIcon`, `ShallowIcon`,
+`ShieldCheckIcon`, `SlideIcon`, `SparklesIcon`, `SquircleIcon`, `SubscribeIcon`,
+`TableIcon`, `TagIcon`, `TwitterIcon`, `UpdateDateIcon`, `VerticalWritingIcon`,
+`ViewIcon`, `ViewOffIcon`.
+
+<!-- /generated:icons -->
+
+`Logo` is the mark `LogoIcon` draws, as a bare `<svg>` without the sizing: it
+takes `className`, `aria-hidden`, and `focusable` (`Partial<IconRenderProps>`)
+instead of `size`. The types `BaseIconProps` (`{ size }`) and
+`IconRenderProps` (`{ className: string; 'aria-hidden': true; focusable: 'false' }`)
+are exported as well.
+
+## Providers
+
+### UIProvider
+
+Wrap the app root once. It includes ToastProvider. The components' own wording needs no provider: it follows `@k8ordo/i18n` (i18n, below).
 
 ```tsx
 import { UIProvider } from '@k8ordo/ui';
-import { en } from '@k8ordo/ui/i18n';
 
-<UIProvider messages={en}>
+<UIProvider>
   <App />
 </UIProvider>;
 ```
 
-一部だけ差し替えるときは辞書をスプレッドして上書きする（`Partial<Messages>` なので全キーを埋める必要はない）。
+Props:
+
+- `children`: `ReactNode`
+
+### PortalRootProvider
+
+A context that shares a portal container with your own `createPortal` calls;
+read it with `usePortalRoot()`. The library's overlays do not read it — they
+open in the top layer (`<dialog>`, the Popover API), and toasts go where
+`ToastProvider`'s `portalRef` points. `Modal` passes its own `<dialog>` as the
+value, so a portal placed through `usePortalRoot()` inside a modal stays in it.
 
 ```tsx
-<UIProvider messages={{ ...en, close: 'Dismiss' }}>
-  <App />
-</UIProvider>
+import { PortalRootProvider, usePortalRoot } from '@k8ordo/ui';
+
+<PortalRootProvider value={containerRef}>{children}</PortalRootProvider>;
 ```
 
-日本語のまま一部だけ変えるなら、そのキーだけ渡せばよい。
+Props:
+
+- `value`: `RefObject<HTMLElement | null>` (required)
+- `children`: `ReactNode`
+
+## i18n (message dictionary)
+
+The wording components own internally (close, required, loading, …) comes from a dictionary, picked by `@k8ordo/i18n`'s current locale. There is no provider and nothing to pass.
+
+- An application that defines its locale set with `defineLocales` gets the locale its messages render in: the one the URL names, or the set's default.
+- An application that defines no set gets **English**, whatever its URL starts with, so the server and the browser agree.
+- The module defining the set has to be loaded in the browser as well; where no set is defined the components speak English.
+
+`ja` and `en` ship with the library. Register any other locale — or replace a built-in one — with `registerMessages`, next to where the set is defined:
 
 ```tsx
-<UIProvider messages={{ close: '閉じる（Esc）' }}>
-  <App />
-</UIProvider>
+import { en, registerMessages } from '@k8ordo/ui/i18n';
+import type { Messages } from '@k8ordo/ui/i18n';
+
+const fr: Messages = { close: 'Fermer' /* …every key */ };
+registerMessages('fr', fr);
+
+registerMessages('en', { ...en, close: 'Dismiss' });
 ```
 
-### 優先順位
+A regional tag without a dictionary of its own (`en-US`) reads its language's (`en`). Rendering in a locale nothing has text for throws, naming the locale and `registerMessages`.
+
+### Resolution order
 
-**コンポーネントの prop > Provider に渡した辞書 > 既定（日本語）**。
+**Component prop > registered dictionary > built-in dictionary**.
 
-`Spinner` の `label`、`Alert` の `closeLabel`、`PasswordInput` の `showLabel` / `hideLabel`、`Pagination` の `prevLabel` / `nextLabel` のように個別の文言 prop を持つコンポーネントは、その prop が辞書より優先される。
+A component with a wording prop of its own — `Spinner`'s `label`, `Alert`'s `closeLabel`, `PasswordInput`'s `showLabel` / `hideLabel`, `Pagination`'s `prevLabel` / `nextLabel` — takes that prop over the dictionary.
 
 ```tsx
-// 辞書が en でも、この Spinner だけは「保存中」になる
+// Whatever the locale, this one Spinner reads 「保存中」
 <Spinner label="保存中" />
 ```
 
-### エクスポート
+### Exports
 
 ```tsx
-import { en, ja, type Messages } from '@k8ordo/ui/i18n';
+import {
+  en,
+  getMessages,
+  ja,
+  messageUsage,
+  registerMessages,
+  type Messages,
+} from '@k8ordo/ui/i18n';
 ```
 
-`ja` / `en` は本体のバンドルに載らないよう、ルートではなく `@k8ordo/ui/i18n` サブパスからのみ export される。
+### Reading the wording in your own elements
 
-### キー一覧
+`getMessages` returns the wording in effect: the dictionary for the current locale, a registered one before a built-in one. Read from it in an element you draw through `renderItem`, or in a component of your own that sits beside the library, and it follows the same language and replacements as the components do. It is not a hook, so a Server Component calls it too.
 
-`Messages` 型の全キー。値はすべて `string`。
+```tsx
+import { getMessages } from '@k8ordo/ui/i18n';
+
+function DismissButton({ onDismiss }) {
+  const { close } = getMessages();
+  return (
+    <button aria-label={close} onClick={onDismiss} type="button">
+      ×
+    </button>
+  );
+}
+```
 
-| 分類          | キー                                                                                                                               |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| 共通          | `close`, `required`, `loading`, `avatar`, `color`                                                                                  |
-| Alert         | `alertSuccess`, `alertInfo`, `alertWarning`, `alertError`                                                                          |
-| Toast         | `toastRegion`                                                                                                                      |
-| Autocomplete  | `autocompletePlaceholder`, `autocompleteRemoveTag`, `autocompleteClear`, `autocompleteEmpty`                                       |
-| FileField     | `fileFieldRemove`                                                                                                                  |
-| NumberField   | `numberFieldIncrement`, `numberFieldDecrement`                                                                                     |
-| PasswordInput | `passwordShow`, `passwordHide`                                                                                                     |
-| ListBox       | `listBoxPlaceholder`                                                                                                               |
-| Breadcrumb    | `breadcrumb`                                                                                                                       |
-| Pagination    | `paginationLabel`, `paginationPrevious`, `paginationNext`                                                                          |
-| AI チャット   | `chat`, `scrollToLatest`, `reasoning`, `reasoningStreaming`, `suggestions`, `send`, `stop`, `toolInput`, `toolOutput`, `toolError` |
+### Key list
+
+Every key in the `Messages` type, grouped by the components that draw it —
+the same mapping `messageUsage` exports. All values are `string`.
+
+<!-- generated:message-keys -->
+
+- Alert / Dialog / Drawer / Response: `close`
+- FormControl: `required`
+- Spinner / Progress / Combobox: `loading`
+- Avatar: `avatar`
+- Code: `color`
+- Alert / Callout: `alertSuccess`, `alertInfo`, `alertWarning`, `alertError`
+- ToastProvider: `toastRegion`
+- CopyButton / Message.Copy: `copy`
+- CopyButton / CodeBlock / Message.Copy: `copied`, `copyFailed`
+- Autocomplete: `autocompletePlaceholder`, `autocompleteRemoveTag`, `autocompleteClear`, `autocompleteEmpty`
+- Combobox: `comboboxToggle`, `comboboxEmpty`, `comboboxFailed`
+- FileField: `fileFieldRemove`
+- FileField.Dropzone / FileField (generative UI): `fileFieldTrigger`, `fileFieldDrop`
+- NumberField: `numberFieldIncrement`, `numberFieldDecrement`, `numberFieldRangeUnderflow` (`{min}` is replaced), `numberFieldRangeOverflow` (`{max}` is replaced)
+- RangeSlider: `rangeSliderStart`, `rangeSliderEnd`
+- Calendar / DatePicker: `calendarPreviousMonth`, `calendarNextMonth`
+- DatePicker: `datePickerOpen`, `datePickerDialog`
+- ColorPicker: `colorPickerHue`, `colorPickerSaturation`, `colorPickerLightness`, `colorPickerSwatches`, `colorPickerOpen`
+- PasswordInput: `passwordShow`, `passwordHide`
+- ListBox: `listBoxPlaceholder`
+- Breadcrumb: `breadcrumb`
+- Tabs (generative UI): `tabList`
+- Pagination: `paginationLabel`, `paginationPrevious`, `paginationNext`
+- Stepper: `stepperComplete`
+- DataTable: `dataTableColumns`, `dataTableSelectAll`, `dataTableSelectRow`
+- CodeBlock: `codeBlockCopy`
+- Carousel: `carousel`, `carouselPrevious`, `carouselNext`
+- Carousel.Slide: `carouselSlide`
+- ResizablePanels.Handle: `resizablePanelsHandle`
+- TableOfContents: `tableOfContents`
+- CommandPalette: `commandPalette`, `commandPaletteSearch`, `commandPaletteEmpty`
+- Conversation.Messages: `chat`
+- Conversation.ScrollButton: `scrollToLatest`
+- Reasoning: `reasoning`, `reasoningStreaming`
+- Suggestion.List: `suggestions`
+- PromptInput: `send`, `stop`
+- PromptInput.Attach: `attach`
+- Attachment.List / PromptInput.Attachments: `attachments`
+- PromptInput.Attachments: `attachmentRemove`
+- Attachment.Item / PromptInput.Attachments: `attachmentImage`
+- Source.List: `sources`
+- Message.Actions: `messageActions`
+- Message.Regenerate: `regenerate`
+- Message.Feedback: `feedbackPositive`, `feedbackNegative`
+- ToolInvocation: `toolInput`, `toolOutput`, `toolError`, `toolDenied`, `toolApprovalRequest`, `toolApprove`, `toolDeny`
+- Response: `responseCopied`, `responseCopyCode`, `responseCopyLink`, `responseCopyTable`, `responseCopyTableAsCsv`, `responseCopyTableAsMarkdown`, `responseCopyTableAsTsv`, `responseDownloadDiagram`, `responseDownloadDiagramAsMmd`, `responseDownloadDiagramAsPng`, `responseDownloadDiagramAsSvg`, `responseDownloadFile`, `responseDownloadImage`, `responseDownloadTable`, `responseDownloadTableAsCsv`, `responseDownloadTableAsMarkdown`, `responseExitFullscreen`, `responseViewFullscreen`, `responseImageNotAvailable`, `responseOpenExternalLink`, `responseExternalLinkWarning`, `responseOpenLink`
+
+<!-- /generated:message-keys -->
+
+`fileFieldTrigger` is the button text of an empty `FileField.Dropzone`, and
+with `tabList` it is also what the generative-UI renderers fall back to when a
+spec leaves the trigger text or the tab-list name out.