@k8ordo/ui 2.0.0 → 2.1.0

package/docs/GUIDE.md

@@ -11,7 +11,6 @@ npm install @k8ordo/ui
 ```tsx
 // 1. Load the stylesheet (once, at your entry point)
 import '@k8ordo/ui/styles.css';
-
 // 2. Wrap the app in the provider
 import { UIProvider } from '@k8ordo/ui';
 
@@ -27,57 +26,160 @@ function App() {
 import { Button, Card } from '@k8ordo/ui';
 ```
 
-### Choosing a stylesheet
+### How the styles arrive
+
+`@k8ordo/ui` is written in CSS Modules, and its styles come in two parts:
+
+- **`styles.css`** — import it once. It declares the cascade layers, the design
+  tokens (custom properties on `:root` and their modes), a reset (the same
+  rules as Tailwind CSS 4's preflight), and the page-wide defaults.
+- **Each component's own CSS** — imported by the component's JavaScript, so a
+  page loads the CSS of the components it uses and nothing else. Any bundler
+  that handles a CSS import from a package does this for you (Vite, Next.js,
+  webpack, Rspack, …).
+
+Every rule of the library sits in a cascade layer. `styles.css` declares the
+order first:
 
-There are two CSS entries. Pick the one that matches your project:
+```css
+@layer properties, theme, base, components, utilities;
+```
 
-- **`styles.css` (default)** — prebuilt CSS. Use it if your project has no Tailwind (CSS Modules, plain CSS). A single import is all it takes, and no Tailwind setup is needed. Every library rule sits inside `@layer`, so your own unlayered CSS wins the cascade (the one exception is preflight's `[hidden] { display: none !important }`). Design tokens are readable as CSS custom properties on `:root` / `.dark` (`var(--fg-mute)`, …).
-- **`tailwind.css`** — the Tailwind source entry. Import this in a Tailwind CSS 4 project and the design tokens become usable as Tailwind classes (`bg-bg-base`, …) in your own markup too. It contains `@import 'tailwindcss'` internally, so one line is enough for your project's CSS:
+The reset and the defaults are in `base` and the components in `components`.
+These are Tailwind CSS 4's layers in Tailwind's order, so in a Tailwind project
+your utilities win over the components; without Tailwind, any CSS of yours that
+is not in a layer wins, and so does a layer you declare after `components`. The
+one rule that does not yield is the reset's
+`[hidden] { display: none !important }`.
+
+The CSS is written for what browsers ship today: `@scope`, container style
+queries, `light-dark()`, `:dir()`, nesting. Keep your bundler's CSS target
+recent (in Vite, `build.cssTarget`): an older target makes Lightning CSS
+rewrite `:dir(rtl)` into `:lang()` selectors, which no longer follow `dir`.
+
+Components take no `className`. To change how one looks, change the tokens, or
+render your own element through its `renderItem` / `renderAnchor`, which hands
+you the component's `className` to keep or to add to.
+
+### Tokens
+
+The tokens are custom properties declared at `:root`, named by category:
+`--color-*`, `--spacing` (and `--spacing-em`), `--radius-*`, `--shadow-*`,
+`--font-family-*`, `--font-size-*`, `--font-weight-*`, `--line-height-*`,
+`--letter-spacing-*`, `--z-index-*`, `--duration-*`, `--easing-*` and
+`--breakpoint-*`. Read them in your own CSS (`color: var(--color-fg-mute)`,
+`padding: calc(var(--spacing) * 6)`). The palette they are built from
+(`--gray-500`, …) is not part of the API.
+
+They are declared outside any layer, so to override one, declare it after
+`styles.css` is loaded: between unlayered rules of equal specificity, source
+order decides. `@k8ordo/ui/tokens` exports the same tokens as data, a DTCG
+resolver document (Resolver Module 2025.10), with each mode (`.dark`,
+`prefers-contrast: more`) as a modifier.
+
+[better-css-modules](https://github.com/k35o/better-css-modules) holds CSS
+Modules to these tokens: list `@k8ordo/ui/styles.css` in its `globalCss`, and
+its `check` reports a raw value, a misspelt token, or a palette color in your
+own modules.
+
+### Tailwind CSS 4
+
+In a Tailwind CSS 4 project, import `tailwind.css` after Tailwind, instead of
+`styles.css`. It brings in `styles.css` and a theme whose utilities read the
+tokens: `bg-bg-base` is `var(--color-bg-base)`, `text-md` is
+`var(--font-size-md)` with its line height, `p-6` is `calc(var(--spacing) * 6)`.
+It does not import Tailwind itself, so `@k8ordo/ui` does not depend on
+`tailwindcss`; your project's own Tailwind comes first:
 
 ```css
+@import 'tailwindcss';
 @import '@k8ordo/ui/tailwind.css';
 ```
 
-Note that either entry applies base styles document-wide. On top of Tailwind's
-preflight (resets for headings, lists, and margins), the library's base layer
-unsets bold on `b` / `strong` and italics on `i` / `em`, and sets `body`
-typography defaults (`font-size`, `overflow-wrap: anywhere`,
-`scrollbar-gutter: stable`, …). Adding it to an existing app restyles more than
-the library's own components.
+It also defines the `dark:`, `light:` and `vertical:` variants and the
+`grid-cols-auto-fill-*`, `writing-*` and `z-overlay` / `z-modal` / `z-toast`
+utilities. The components do not need Tailwind; it is only for your own markup.
 
-One more exception: `@k8ordo/ui/ai/response` (`Response`) needs streamdown's
-classes to be generated by _your_ Tailwind build, so the prebuilt `styles.css`
-alone will not render it completely. Using `Response` requires `tailwind.css`
-plus a `@source` entry — see [ai-chat](references/ai-chat.md).
+### Page-wide styles
 
-### Wording language (i18n)
+Note that `styles.css` applies base styles document-wide. On top of the reset
+(headings, lists, and margins), it unsets bold on `b` / `strong` and italics on
+`i` / `em`, and sets `body` typography defaults (`font-size`,
+`overflow-wrap: anywhere`, `scrollbar-gutter: stable`, …). Adding it to an
+existing app restyles more than the library's own components. Wrap rendered
+Markdown or MDX in `Prose` to get the typesetting of body text back inside it —
+see [Typography](references/typography.md#long-form-text-prose).
 
-The wording components own internally ("close", "required", "loading", …)
-**defaults to Japanese**. It works without a provider and without passing
-`messages`, so a Japanese app needs no setup at all.
+### Dark mode
 
-To switch to English, pass `en` from `@k8ordo/ui/i18n`.
+The tokens switch on a `dark` class: `:root` holds the light values and `.dark`
+the dark ones, so everything under an element with the class is dark. The
+library never adds the class itself. In a k8ordo application
+`@k8ordo/color-scheme` does, resolving the visitor's choice and the system
+preference into `dark` on `<html>` before the first paint; anything else that
+toggles the class works the same.
 
-```tsx
-import { UIProvider } from '@k8ordo/ui';
-import { en } from '@k8ordo/ui/i18n';
+The base layer sets the CSS `color-scheme` property to match — `light` on
+`:root`, `dark` under `.dark` — so the browser's own rendering (scrollbars, form
+controls, a `<dialog>`'s default colors) follows the tokens rather than the OS.
+Your own CSS follows the same way when it reads the tokens. With
+`tailwind.css`, the `dark:` variant applies under `.dark` and `light:`
+everywhere else.
+
+### Wording language (i18n)
 
-<UIProvider messages={en}>
-  <App />
-</UIProvider>;
+The wording components own internally ("close", "required", "loading", …) is
+read in `@k8ordo/i18n`'s current locale. There is no provider to configure and
+nothing to pass: `@k8ordo/i18n` is a peer dependency, installed with this
+package.
+
+- **With a locale set.** Once the application defines its set with
+  `defineLocales`, the components speak the locale its messages do — the one
+  the URL names, or the set's default.
+- **Without one.** An application that defines no set (a Next.js or plain
+  Vite app that does not use `@k8ordo/i18n`) gets **English**, whatever its
+  URL starts with — so the server's HTML and the browser agree.
+
+```ts
+// src/i18n.ts — a Japanese-only app defines a set of one
+import { defineLocales } from '@k8ordo/i18n';
+
+export const locales = defineLocales({
+  ja: { timeZone: 'Asia/Tokyo', dir: 'ltr' },
+});
 ```
 
-To replace only some of it, spread the dictionary and override those keys.
+The module that defines the set has to be loaded in the browser too, not
+only by the server render: where no set is defined the components speak
+English, and would disagree with the HTML. In a k8ordo app a client component
+that links (`bindParams`) or switches language already imports it; elsewhere,
+import it from a client module the root renders.
 
-```tsx
-<UIProvider messages={{ ...en, close: 'Dismiss' }}>
-  <App />
-</UIProvider>
+`ja` and `en` ship with the library. Any other locale is registered next to
+the set, and a regional tag without a dictionary of its own (`en-US`) reads
+its language's (`en`); a locale nothing has text for throws, naming how to
+register it:
+
+```ts
+import { en, ja, registerMessages } from '@k8ordo/ui/i18n';
+import type { Messages } from '@k8ordo/ui/i18n';
+
+const fr: Messages = { close: 'Fermer' /* …every key */ };
+registerMessages('fr', fr);
+
+// A registered dictionary wins over a built-in one
+registerMessages('en', { ...en, close: 'Dismiss' });
 ```
 
-Resolution order is **component prop > provider dictionary > built-in default
-(Japanese)**. For a component with a wording prop of its own, such as
-`Spinner`'s `label`, that prop wins over the dictionary.
+Resolution order is **component prop > registered dictionary > built-in
+dictionary**. For a component with a wording prop of its own, such as
+`Spinner`'s `label`, that prop wins.
+
+`getMessages()` from `@k8ordo/ui/i18n` returns the wording in effect for your
+own elements (a `renderItem`, a component beside the library). It is not a
+hook, so it works in a Server Component — which is also why `Spinner`,
+`Breadcrumb`, `Code`, `Alert`, `Callout`, `Reasoning`, and `ToolInvocation`
+are Server Components.
 
 > [Full key list and details](references/components.md) (the "i18n (message dictionary)" section)
 
@@ -99,7 +201,7 @@ Do not give everything the same tone. Soften in proportion to the element's role
 | Element                             | Direction                                            |
 | ----------------------------------- | ---------------------------------------------------- |
 | Forms (TextField, Textarea, Button) | Soft (large radii, pill buttons, generous padding)   |
-| Cards and containers                | Soft (`rounded-xl`–`rounded-2xl`, gentle shadow)     |
+| Cards and containers                | Soft (`--radius-xl`–`--radius-2xl`, gentle shadow)   |
 | Alert, Badge                        | Precise (clarity of information comes first)         |
 | Tabs, Breadcrumb                    | Sharp (elements that express structure stay precise) |
 
@@ -113,9 +215,9 @@ Soft spacing and quiet refinement. The appeal is in space and shape.
 
 **DO:**
 
-- Use `bg-bg-subtle` (a light grey) for the page background
+- Use `--color-bg-subtle` (a light grey) for the page background
 - Float content on white cards
-- Leave enough room between cards (`gap-6`–`gap-10`)
+- Leave enough room between cards (6–10 steps of `--spacing`)
 
 **DON'T:**
 
@@ -127,9 +229,9 @@ Soft spacing and quiet refinement. The appeal is in space and shape.
 
 **DO:**
 
-- Use the Japanese fonts (Noto Sans JP, M PLUS 2)
-- Keep to three font weights at most (`font-normal`, `font-medium`, `font-bold`)
-- Lean on `font-medium` being 450 — lighter than the usual 500 — for delicate emphasis
+- Use the Japanese fonts (Noto Sans JP, M PLUS 2), which your app loads and sets — the library sets no font of its own, so text stays on the reset's system stack until your app sets one
+- Keep to three weights: 400 (the inherited default), `--font-weight-medium`, `--font-weight-bold`
+- Lean on `--font-weight-medium` being 450 — lighter than the usual 500 — for delicate emphasis
 
 **DON'T:**
 
@@ -144,17 +246,17 @@ Soft spacing and quiet refinement. The appeal is in space and shape.
 **DO:**
 
 - Follow the 60-30-10 rule (60% neutral, 30% supporting, 10% accent)
-- Use semantic color tokens (`bg-bg-subtle`, `text-fg-mute`, …)
+- Use semantic color tokens (`--color-bg-subtle`, `--color-fg-mute`, …)
 - Design dark mode as its own tone, not a derivative
 - Keep color calm; let space and shape carry the design
 
 **DON'T:**
 
 - Use gradient backgrounds
-- Use `bg-primary-bg` on hover — use `bg-bg-mute`
-- Express state with opacity (`/90`) — use the dedicated token
+- Use `--color-primary-bg` on hover — use `--color-bg-mute`
+- Express state with opacity — use the dedicated token
 - Spread vivid color over large areas
-- Use raw palette colors (`bg-teal-500`) — use semantic tokens (`bg-primary-bg`)
+- Use raw palette colors (`--teal-500`) — use semantic tokens (`--color-primary-bg`)
 
 > [Color details](references/color.md)
 
@@ -162,15 +264,15 @@ Soft spacing and quiet refinement. The appeal is in space and shape.
 
 **DO:**
 
-- Treat `p-8` as the standard padding (inside forms and cards)
-- Express relatedness through the size of the gap (`mt-2` close, `mt-4` standard, `mt-8` between sections)
+- Treat 6 steps of `--spacing` (`calc(var(--spacing) * 6)`) as the standard padding (inside forms and cards), 4 when compact and 8 when generous
+- Express relatedness through the size of the gap (2 steps close, 4 standard, 8 between sections)
 - Separate sections with Separator
 
 **DON'T:**
 
 - Put everything in a Card
 - Nest cards (Card in Card)
-- Use extremely tight spacing such as `gap-1`
+- Use extremely tight spacing such as one step
 
 > [Spacing details](references/spatial-design.md)
 
@@ -178,9 +280,9 @@ Soft spacing and quiet refinement. The appeal is in space and shape.
 
 **DO:**
 
-- Start from `transition-colors`
-- Express focus with `focus-visible:ring-2 focus-visible:ring-border-info`
-- Keep hover gentle with `hover:bg-bg-mute`
+- Start from a color transition over `--duration-fast` with `--easing-out`
+- Express focus with `box-shadow: var(--shadow-ring-info)` on `:focus-visible`
+- Keep hover gentle with `--color-bg-mute`
 
 **DON'T:**
 
@@ -194,7 +296,7 @@ Soft spacing and quiet refinement. The appeal is in space and shape.
 
 ### Button
 
-Styling is unified through `color` and `variant`. Pill-shaped (`rounded-full`).
+Styling is unified through `color` and `variant`. Pill-shaped (`--radius-full`).
 
 ```tsx
 import { Button } from '@k8ordo/ui';
@@ -208,11 +310,14 @@ import { Button } from '@k8ordo/ui';
 // Text only
 <Button variant="skeleton">View details</Button>
 
-// Render as a link (renderItem prop)
+// Render as a link (renderItem prop). The bag holds everything the <button>
+// would have received, so drop the two <button>-only members and spread the
+// rest: className, children, ref, onClick, aria-disabled, aria-busy, and any
+// attribute passed to Button all ride along.
 <Button
   color="base"
-  renderItem={({ className, children }) => (
-    <a className={className} href="/settings">{children}</a>
+  renderItem={({ children, disabled: _disabled, type: _type, ...props }) => (
+    <a href="/settings" {...props}>{children}</a>
   )}
 >
   Settings
@@ -229,12 +334,13 @@ import { IconButton } from '@k8ordo/ui';
 <IconButton color="transparent" label="Copy"><CopyIcon /></IconButton>
 <IconButton color="primary" label="Send"><SendIcon /></IconButton>
 
-// Render as a link (renderItem prop)
+// Render as a link (renderItem prop). triggerProps holds the tooltip wiring
+// and the merged ref; spread it alongside the rest.
 <IconButton
   color="base"
   label="Home"
-  renderItem={({ className, children, 'aria-label': ariaLabel, triggerProps }) => (
-    <a aria-label={ariaLabel} className={className} href="/home" {...triggerProps}>
+  renderItem={({ children, disabled: _disabled, triggerProps, type: _type, ...props }) => (
+    <a href="/home" {...props} {...triggerProps}>
       {children}
     </a>
   )}
@@ -243,21 +349,42 @@ import { IconButton } from '@k8ordo/ui';
 </IconButton>
 ```
 
+### CopyButton
+
+For copying text, reach for `CopyButton` rather than an `IconButton` and your own
+clipboard code: it writes to the clipboard, shows a check, and announces the
+result to screen readers.
+
+```tsx
+import { CopyButton } from '@k8ordo/ui';
+
+<CopyButton value={code} label="Copy code" iconOnly size="sm" />
+<CopyButton value={() => window.location.href} label="Copy link" />
+```
+
 ### Card
 
-Floating on a shadow is the default: a white card over a `bg-subtle` page.
+Floating on a shadow is the default: a white card over a `--color-bg-subtle`
+page. The card has no padding of its own.
+
+```css
+/* card.module.css */
+.body {
+  padding: calc(var(--spacing) * 6);
+}
+```
 
 ```tsx
 import { Card } from '@k8ordo/ui';
 
 // Static card (floated with a shadow)
 <Card variant="shadow">
-  <div className="p-8">Card content</div>
+  <div className={styles.body}>Card content</div>
 </Card>
 
 // Clickable card (interactive scales it up on hover)
 <Card variant="shadow" interactive>
-  <div className="p-8">Content</div>
+  <div className={styles.body}>Content</div>
 </Card>
 ```
 
@@ -297,19 +424,39 @@ import {
 </FileField.Root>
 ```
 
+With `@k8ordo/form`, spread what `form.field(name).input` derives onto the
+field after `FormControl`'s props — `type`, `required`, the length and range
+bounds, and the echoed `defaultValue` all go in as they are, whichever field
+renders them. Uncontrolled fields keep their value in the DOM, so the form's
+reset, `isDirty`, and error clearing hear every change, including ones a
+component makes in code. The pairing per component is in `@k8ordo/form`'s
+guide (`node_modules/@k8ordo/form/docs/GUIDE.md`, "Working with @k8ordo/ui").
+
+```tsx
+const title = form.field('title');
+
+<FormControl
+  errorText={title.error}
+  invalid={title.invalid}
+  label="Title"
+  required={title.required}
+  renderInput={(props) => <TextField {...props} {...title.input} />}
+/>;
+```
+
 ## Anti-patterns: avoiding "AI slop"
 
 Avoid the traits that make a UI recognizably AI-generated at a glance.
 
-| Anti-pattern               | The @k8ordo/ui alternative                         |
-| -------------------------- | -------------------------------------------------- |
-| Purple gradients           | Flat teal/cyan color                               |
-| Card in Card               | A Separator and spacing instead                    |
-| Grey text on a grey ground | Hold contrast with `text-fg-base` / `text-fg-mute` |
-| Bounce / spring animation  | `transition-colors duration-150 ease-out`          |
-| The Inter typeface         | Noto Sans JP / M PLUS 2                            |
-| Heavy glassmorphism        | A border plus a subtle background color            |
-| Cramming information in    | Sparse placement that lets the space breathe       |
+| Anti-pattern               | The @k8ordo/ui alternative                                |
+| -------------------------- | --------------------------------------------------------- |
+| Purple gradients           | Flat teal/cyan color                                      |
+| Card in Card               | A Separator and spacing instead                           |
+| Grey text on a grey ground | Hold contrast with `--color-fg-base` / `--color-fg-mute`  |
+| Bounce / spring animation  | A color transition over `--duration-fast`, `--easing-out` |
+| The Inter typeface         | Noto Sans JP / M PLUS 2                                   |
+| Heavy glassmorphism        | A border plus a subtle background color                   |
+| Cramming information in    | Sparse placement that lets the space breathe              |
 
 ### The AI slop test
 
@@ -321,11 +468,32 @@ Avoid the traits that make a UI recognizably AI-generated at a glance.
 - **Use the existing components**: look for a @k8ordo/ui component before building custom UI
 - **Render from Server Components**: every component, compound ones included (`Dialog.Root`, `Tabs.Root`, …), can be placed in a Server Component; only the interactive parts are client modules
 - **Keep placed state in `@k8ordo/state`**: state that lives in the URL, a history entry, localStorage, or memory is `defineLocalState` and friends, not a hook from this package
-- **Use semantic tokens**: tokens (`bg-primary-bg`), never raw color values (`bg-teal-500`)
+- **Browser-only rendering is React's**: a component that can only render in a browser calls `use(browser())` (`browser` from `react-dom`) under a `<Suspense>`; there is no `useClient` here and no "mounted" flag
+- **Use semantic tokens**: tokens (`--color-primary-bg`), never raw color values or the palette (`--teal-500`)
 - **Let space and shape carry it**: character comes from spacing and soft radii, not from vivid color
 - **Do not forget dark mode**: semantic tokens handle it for you
+- **High contrast is handled too**: the tokens follow `prefers-contrast: more` and the components stay legible under `forced-colors: active`; for your own UI, see [High contrast and forced colors](references/color.md#high-contrast-and-forced-colors)
 - **Accessibility**: `aria-label`, keyboard navigation, and state that does not rely on color alone
 
+## Testing
+
+Run component tests in a real browser — Vitest browser mode or Playwright —
+the way this library tests itself. Every interactive component is built
+directly on APIs a browser has and jsdom does not: `ResizeObserver`,
+`IntersectionObserver`, `matchMedia`, `HTMLDialogElement`'s `showModal` /
+`close`, and the Popover API. None of them is called through a support check,
+so under jsdom `Tooltip`, `IconButton` (unless `tooltipDisabled`), `Tabs`,
+`Autocomplete`, `Combobox`, `Toolbar`, `ResizablePanels`, `InView`, `Resize`,
+and `Conversation` throw as soon as they mount; `Modal`, `CommandPalette`,
+`Drawer`, `Popover`, `DropdownMenu`, `ContextMenu`, `ListBox`, and `DatePicker`
+throw the moment they open (a `DropdownMenu` holding a `SubMenu` already at
+mount); and a `clearable` `FileField.ItemList` throws once it lists a file.
+
+This is not a gap to be stubbed around. A synthetic DOM (jsdom, happy-dom) has
+no layout engine, so even with stubs in place a passing assertion about focus,
+placement, or visibility there means very little — the thing you wanted to
+check is the thing it cannot model.
+
 ## Detailed reference
 
 - Typography: [references/typography.md](references/typography.md)
@@ -333,7 +501,6 @@ Avoid the traits that make a UI recognizably AI-generated at a glance.
 - Spacing and layout: [references/spatial-design.md](references/spatial-design.md)
 - Interaction: [references/interaction-design.md](references/interaction-design.md)
 - Component catalog: [references/components.md](references/components.md)
-- Hooks: [references/hooks.md](references/hooks.md)
-- Helpers and types: [references/helpers.md](references/helpers.md)
+- Types: [references/types.md](references/types.md)
 - AI chat (Conversation / Message / PromptInput, …): [references/ai-chat.md](references/ai-chat.md)
 - Generative UI (having an LLM generate UI via json-render / OpenUI): [references/generative-ui.md](references/generative-ui.md)

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # @k8ordo/ui
 
 > React components from k8ordo, with semantic design tokens, dark mode,
-> built-in Japanese/English wording, AI chat components, and official generative UI
+> built-in wording that follows `@k8ordo/i18n` (Japanese and English included), AI chat components, and official generative UI
 > adapters (json-render & OpenUI) that let an LLM generate, validate, and render
 > on-brand UIs from these components.
 >
@@ -14,16 +14,20 @@ Start with GUIDE.md, then follow the reference most relevant to the task.
 
 ## Guide
 
-- [Design Guide](GUIDE.md): setup, i18n (default Japanese, switching to English), design direction, aesthetic guidelines, component usage principles, anti-patterns, implementation principles.
+- [Design Guide](GUIDE.md): setup, dark mode (the `dark` class that `@k8ordo/color-scheme` puts on `<html>`, and the `color-scheme` the stylesheet sets to match), i18n (wording in `@k8ordo/i18n`'s current locale, English without a locale set, registering other locales), design direction, aesthetic guidelines, component usage principles, anti-patterns, implementation principles, testing (component tests belong in a real browser — Vitest browser mode or Playwright — because the components call browser APIs jsdom does not implement).
 
 ## References
 
-- [Components](references/components.md): full component list, import paths, props, and i18n — every component, compound ones included (`Dialog.Root`, `Tabs.Root`, …), renders from a Server Component — component wording comes from a dictionary that defaults to Japanese; `@k8ordo/ui/i18n` exports `ja` / `en` / the `Messages` type for `<UIProvider messages={...}>` (per-component wording props win over the dictionary).
-- [AI chat](references/ai-chat.md): AI chat components from `@k8ordo/ui/ai` (Conversation / Message / PromptInput / Reasoning / Suggestion / ToolInvocation), streaming Markdown `Response` from `@k8ordo/ui/ai/response` (optional peer `streamdown`), and `mapMessageParts` from `@k8ordo/ui/ai-sdk` to render AI SDK `UIMessage.parts` (optional peer `ai`).
-- [Generative UI](references/generative-ui.md): use json-render / OpenUI to make an LLM generate UIs — `catalog.prompt()` (server-safe), `<JsonRenderUI spec={spec} />` (client), `validateGeneratedSpec()` (validate/repair LLM output), `satisfies UISpec` (typed specs), and `@k8ordo/ui/openui/prompt`.
+- [Components](references/components.md): full component list, import paths, props, and i18n — every component, compound ones included (`Dialog.Root`, `Tabs.Root`, …), renders from a Server Component — component wording comes from the dictionary of `@k8ordo/i18n`'s current locale (English when the app defines no locale set); `@k8ordo/ui/i18n` exports `ja` / `en` / the `Messages` type, `registerMessages(locale, messages)` for any other locale or a replacement (per-component wording props win over any dictionary), and `getMessages()` — not a hook — to read the wording in effect in your own elements.
+- [AI chat](references/ai-chat.md): AI chat components from `@k8ordo/ui/ai` (Conversation / Message / PromptInput / Reasoning / Suggestion / ToolInvocation / Attachment / Source) — tool approval, attachments, sources, and message actions included, streaming Markdown `Response` from `@k8ordo/ui/ai/response` (optional peer `streamdown`), and `mapMessageParts` from `@k8ordo/ui/ai-sdk` to render AI SDK `UIMessage.parts` (optional peer `ai`).
+- [Generative UI](references/generative-ui.md): use json-render / OpenUI to make an LLM generate UIs — `catalog.prompt()` (server-safe), `<JsonRenderUI spec={spec} />` (client), `validateGeneratedSpec()` (validate/repair LLM output), `satisfies UISpec` (typed specs), `@k8ordo/ui/openui/prompt`, and which exports the catalog leaves out on purpose.
 - [Typography](references/typography.md): type scale and usage.
 - [Color](references/color.md): semantic token system and dark mode.
 - [Spacing & layout](references/spatial-design.md): spacing scale and layout patterns.
 - [Interaction](references/interaction-design.md): motion and interaction guidelines.
-- [Hooks](references/hooks.md): custom hooks for UI mechanics (disclosure, timing, DOM observation). State that lives in a place (URL, history, localStorage, memory) belongs to `@k8ordo/state`, not to a hook here.
-- [Helpers & types](references/helpers.md): the five helper functions (`chain` / `cn` / `createSafeContext` / `mergeProps` / `mergeRefs`) and the public types (`Status` / `Direction` / `Placement` / `ModalSide` / `DrawerSide` / `Option`).
+- [Types](references/types.md): the shared types for typing component props (`Status` / `Direction` / `Placement` / `ModalSide` / `DrawerSide` / `Option`).
+
+## Data exports
+
+- `@k8ordo/ui/tokens`: the design tokens as data — `tokens`, a DTCG resolver document (Resolver Module 2025.10) whose set is the `:root` tokens and whose modifiers are the modes (`.dark`, `prefers-contrast: more`).
+- `@k8ordo/ui/props.json`: every component's props as JSON (`docs/props.generated.json`), generated from the types — the same data as the Props blocks in components.md.