@k8ordo/ui 1.0.0 → 2.1.0

package/docs/GUIDE.md

@@ -1,18 +1,17 @@
-# k8ordo UI Design Guide
+# @k8ordo/ui Design Guide
 
-`@k8ordo/ui` デザインシステムを使って UI を作るためのガイド。
+How to build UI with the `@k8ordo/ui` design system.
 
-## セットアップ
+## Setup
 
 ```bash
 npm install @k8ordo/ui
 ```
 
 ```tsx
-// 1. スタイルシートを読み込む（エントリポイントで1回）
+// 1. Load the stylesheet (once, at your entry point)
 import '@k8ordo/ui/styles.css';
-
-// 2. Provider でアプリを囲む
+// 2. Wrap the app in the provider
 import { UIProvider } from '@k8ordo/ui';
 
 function App() {
@@ -23,205 +22,325 @@ function App() {
   );
 }
 
-// 3. コンポーネントを使う
+// 3. Use components
 import { Button, Card } from '@k8ordo/ui';
 ```
 
-### スタイルシートの選び方
+### How the styles arrive
+
+`@k8ordo/ui` is written in CSS Modules, and its styles come in two parts:
 
-CSS のエントリは2つある。プロジェクトの CSS 環境で選ぶ：
+- **`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, …).
 
-- **`styles.css`（既定）** — ビルド済み CSS。Tailwind を持たないプロジェクト（CSS Modules・素の CSS）はこちら。import 1行で完結し、Tailwind のセットアップは不要。ライブラリのルールはすべて `@layer` 内にあるため、レイヤー外にある利用側の CSS がカスケードで優先される（唯一の例外は preflight の `[hidden] { display: none !important }`）。デザイントークンは `:root` / `.dark` の CSS カスタムプロパティとしてそのまま参照できる（`var(--fg-mute)` など）。
-- **`tailwind.css`** — Tailwind ソース版。Tailwind CSS 4 を使うプロジェクトはこちらを import すると、デザイントークン（`bg-bg-base` など）を自分のマークアップの Tailwind クラスとしても使える。内部で `@import 'tailwindcss'` を含むため、プロジェクトの CSS は次の1行でよい：
+Every rule of the library sits in a cascade layer. `styles.css` declares the
+order first:
 
 ```css
-@import '@k8ordo/ui/tailwind.css';
+@layer properties, theme, base, components, utilities;
 ```
 
-どちらのエントリも文書全体にベーススタイルを適用する点に注意。Tailwind の preflight（見出し・リスト・余白のリセット等）に加え、ライブラリの base レイヤーが `b` / `strong` の太字や `i` / `em` の斜体を解除し、`body` のタイポグラフィ既定（`font-size` / `overflow-wrap: anywhere` / `scrollbar-gutter: stable` など）を設定する。既存アプリに後付けする場合はコンポーネント以外の見た目にも影響する。
-
-例外がもう1つ: `@k8ordo/ui/ai/response`（`Response`）だけは streamdown のクラスを利用側の Tailwind ビルドで生成する必要があるため、ビルド済み `styles.css` では表示が完成しない。`Response` を使うなら `tailwind.css` + `@source` 設定（[ai-chat](references/ai-chat.md)）が前提。
+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:
 
-### 文言の言語（i18n）
+```css
+@import 'tailwindcss';
+@import '@k8ordo/ui/tailwind.css';
+```
 
-コンポーネントが内部で持つ文言（「閉じる」「必須」「読み込み中」など）は**既定で日本語**。Provider を置かなくても、`messages` を渡さなくても日本語で動くので、日本語のアプリでは何も設定しなくてよい。
+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.
+
+### Page-wide styles
+
+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).
+
+### Dark mode
+
+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.
+
+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)
+
+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' },
+});
+```
 
-英語にするときは `@k8ordo/ui/i18n` の `en` を渡す。
+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
-import { UIProvider } from '@k8ordo/ui';
-import { en } from '@k8ordo/ui/i18n';
+`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:
 
-<UIProvider messages={en}>
-  <App />
-</UIProvider>;
-```
+```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);
 
-```tsx
-<UIProvider messages={{ ...en, close: 'Dismiss' }}>
-  <App />
-</UIProvider>
+// A registered dictionary wins over a built-in one
+registerMessages('en', { ...en, close: 'Dismiss' });
 ```
 
-優先順位は **コンポーネントの prop > Provider の辞書 > 既定（日本語）**。`Spinner` の `label` のように個別の文言 prop を持つコンポーネントでは、その prop が辞書より優先される。
+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.
 
-> [キー一覧・詳細](references/components.md)（「i18n（文言辞書）」の節）
+`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)
 
-### コアコンセプト
+## Design direction
 
-**「触れるものは柔らかく、読むものは端正に」**
+### Core concept
 
-- **空間と形が主役**: 色ではなく、余白のゆとりと形の柔らかさがこのデザインの個性
-- **要素の性格で使い分ける**: 触れる要素（フォーム、ボタン）は柔らかく、情報を示す要素（Alert、Badge）は端正に
-- **余白で語る**: 詰め込まず、空間にゆとりを持たせる
-- **静かな変化**: アニメーションは控えめに、繊細なフィードバック
-- **穏やかな色**: OKLCH ベースのパレット、セマンティックトークンで抑えたトーンに
+**"Soft where you touch, precise where you read."**
+(触れるものは柔らかく、読むものは端正に)
 
-すべてを同じトーンにしない。要素の性格ごとに柔らかさを変える。
+- **Space and shape lead**: the character of this design comes from generous spacing and soft shapes, not from color
+- **Vary by the element's role**: things you touch (forms, buttons) are soft; things that inform (Alert, Badge) are precise
+- **Let the spacing speak**: do not pack things in; leave room
+- **Quiet motion**: restrained animation, subtle feedback
+- **Calm color**: an OKLCH-based palette kept low-key through semantic tokens
 
-| 要素                                    | 方向性                                                   |
-| --------------------------------------- | -------------------------------------------------------- |
-| フォーム（TextField, Textarea, Button） | 柔らかい（大きな角丸、ピル型ボタン、ゆったりパディング） |
-| カード・コンテナ                        | 柔らかい（`rounded-xl`〜`rounded-2xl`、ふんわり影）      |
-| Alert, Badge                            | 端正（情報の明確さを優先）                               |
-| Tabs, Breadcrumb                        | シャープ（構造を示す要素は端正に）                       |
+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 (`--radius-xl`–`--radius-2xl`, gentle shadow)   |
+| Alert, Badge                        | Precise (clarity of information comes first)         |
+| Tabs, Breadcrumb                    | Sharp (elements that express structure stay precise) |
 
-柔らかな余白と静かな洗練。空間と形の柔らかさで魅せる。
+### Tone
 
-## 美学ガイドライン
+Soft spacing and quiet refinement. The appeal is in space and shape.
 
-### ページ構造
+## Aesthetic guidelines
+
+### Page structure
 
 **DO:**
 
-- ページ背景は `bg-bg-subtle`（薄いグレー）
-- コンテンツは白いカードで浮かせる
-- カード間に十分な余白（`gap-6`〜`gap-10`）
+- Use `--color-bg-subtle` (a light grey) for the page background
+- Float content on white cards
+- Leave enough room between cards (6–10 steps of `--spacing`)
 
 **DON'T:**
 
-- 純白背景にカードをフラットに置く
-- すべてを Card に入れる
-- Card を入れ子にする（Card in Card）
+- Lay flat cards on a pure white background
+- Put everything in a Card
+- Nest cards (Card in Card)
 
-### タイポグラフィ
+### Typography
 
 **DO:**
 
-- 日本語フォント（Noto Sans JP, M PLUS 2）を使う
-- フォントウェイトは 3種類まで（`font-normal`, `font-medium`, `font-bold`）
-- `font-medium` が 450（一般的な 500 より軽い）であることを活かした繊細な強調
+- 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:**
 
-- Inter / Roboto / Open Sans を使う
-- 4種類以上のフォントサイズを1画面で使う
-- テキストにグラデーションをかける
+- Use Inter / Roboto / Open Sans
+- Use four or more font sizes on one screen
+- Apply gradients to text
 
-> [タイポグラフィ詳細](references/typography.md)
+> [Typography details](references/typography.md)
 
-### カラー
+### Color
 
 **DO:**
 
-- 60-30-10 ルール（ニュートラル60%, サポート30%, アクセント10%）
-- セマンティックカラートークンを使う（`bg-bg-subtle`, `text-fg-mute` 等）
-- ダークモードを独立したトーンで設計する
-- 色は穏やかに、空間と形で魅せる
+- Follow the 60-30-10 rule (60% neutral, 30% supporting, 10% accent)
+- 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:**
 
-- グラデーション背景
-- ホバーに `bg-primary-bg` — `bg-bg-mute` を使う
-- 透明度(`/90`)で状態表現 — 専用トークンを使う
-- 鮮やかな色を広範囲に使う
-- 生のパレット色（`bg-teal-500`）— セマンティックトークン（`bg-primary-bg`）を使う
+- Use gradient backgrounds
+- 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 (`--teal-500`) — use semantic tokens (`--color-primary-bg`)
 
-> [カラー詳細](references/color.md)
+> [Color details](references/color.md)
 
-### スペーシング
+### Spacing
 
 **DO:**
 
-- `p-8` を標準パディングとする（フォーム・カード内）
-- 余白の差で関連度を表す（`mt-2` 近い、`mt-4` 標準、`mt-8` セクション間）
-- Separator でセクションを区切る
+- 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:**
 
-- すべてを Card に入れる
-- Card を入れ子にする（Card in Card）
-- `gap-1` のような極端に狭いスペーシング
+- Put everything in a Card
+- Nest cards (Card in Card)
+- Use extremely tight spacing such as one step
 
-> [スペーシング詳細](references/spatial-design.md)
+> [Spacing details](references/spatial-design.md)
 
-### インタラクション
+### Interaction
 
 **DO:**
 
-- `transition-colors` を基本にする
-- `focus-visible:ring-2 focus-visible:ring-border-info` でフォーカス表現
-- `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:**
 
-- bounce / spring 系のイージング
-- 300ms を超えるアニメーション
-- ホバーに強い原色を使う
+- Use bounce or spring easing
+- Animate for longer than 300ms
+- Use a strong primary color on hover
 
-> [インタラクション詳細](references/interaction-design.md)
+> [Interaction details](references/interaction-design.md)
 
-## コンポーネント使用の原則
+## Component usage principles
 
 ### Button
 
-`color` と `variant` で統一されたスタイル。ピル型（`rounded-full`）。
+Styling is unified through `color` and `variant`. Pill-shaped (`--radius-full`).
 
 ```tsx
 import { Button } from '@k8ordo/ui';
 
-// プライマリアクション
-<Button color="primary" variant="solid">保存する</Button>
+// Primary action
+<Button color="primary" variant="solid">Save</Button>
 
-// セカンダリアクション
-<Button color="base" variant="outline">キャンセル</Button>
+// Secondary action
+<Button color="base" variant="outline">Cancel</Button>
 
-// テキストのみ
-<Button variant="skeleton">詳細を見る</Button>
+// Text only
+<Button variant="skeleton">View details</Button>
 
-// リンクとしてレンダーする（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
 </Button>
 ```
 
 ### IconButton
 
-`color` prop でスタイルを制御（`variant` ではない）。`label` は必須。
+Styling is controlled by `color` (not `variant`). `label` is required.
 
 ```tsx
 import { IconButton } from '@k8ordo/ui';
 
-<IconButton color="transparent" label="コピー"><CopyIcon /></IconButton>
-<IconButton color="primary" label="送信"><SendIcon /></IconButton>
+<IconButton color="transparent" label="Copy"><CopyIcon /></IconButton>
+<IconButton color="primary" label="Send"><SendIcon /></IconButton>
 
-// リンクとしてレンダーする（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="ホーム"
-  renderItem={({ className, children, 'aria-label': ariaLabel, triggerProps }) => (
-    <a aria-label={ariaLabel} className={className} href="/home" {...triggerProps}>
+  label="Home"
+  renderItem={({ children, disabled: _disabled, triggerProps, type: _type, ...props }) => (
+    <a href="/home" {...props} {...triggerProps}>
       {children}
     </a>
   )}
@@ -230,27 +349,48 @@ 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
 
-シャドウで浮かせるのが基本。ページ背景 `bg-subtle` の上に白カード。
+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">カードのコンテンツ</div>
+  <div className={styles.body}>Card content</div>
 </Card>
 
-// クリック可能なカード（interactive でホバー時にスケールアップ）
+// Clickable card (interactive scales it up on hover)
 <Card variant="shadow" interactive>
-  <div className="p-8">コンテンツ</div>
+  <div className={styles.body}>Content</div>
 </Card>
 ```
 
-### フォーム
+### Forms
 
-`FormControl` + 各フォームコンポーネントの `renderInput` パターン。
+`FormControl` plus each form component's `renderInput` pattern.
 
 ```tsx
 import {
@@ -261,14 +401,14 @@ import {
   TextField,
 } from '@k8ordo/ui';
 
-<FormControl label="メール" required renderInput={(props) => (
+<FormControl label="Email" required renderInput={(props) => (
   <TextField {...props} placeholder="example@mail.com" />
 )} />
 
-<FormControl label="カテゴリ" renderInput={(props) => (
+<FormControl label="Category" renderInput={(props) => (
   <Select
     {...props}
-    options={[{ value: '1', label: 'オプション1' }]}
+    options={[{ value: '1', label: 'Option 1' }]}
     value={value}
     onChange={onChange}
   />
@@ -277,48 +417,90 @@ import {
 <FileField.Root accept="image/*" multiple>
   <FileField.Trigger
     renderItem={({ onClick, disabled }) => (
-      <Button disabled={disabled} onClick={onClick}>ファイルを選択</Button>
+      <Button disabled={disabled} onClick={onClick}>Choose files</Button>
     )}
   />
   <FileField.ItemList />
 </FileField.Root>
 ```
 
-## アンチパターン: 「AI スロップ」を避ける
-
-AI が生成したと一目でわかるUIの特徴を避ける。
+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").
 
-| アンチパターン                 | k8ordo UI での代替                                 |
-| ------------------------------ | -------------------------------------------------- |
-| パープルグラデーション         | Teal/Cyan のフラットカラー                         |
-| Card in Card（入れ子カード）   | Separator + 余白で区切り                           |
-| グレー背景にグレーテキスト     | `text-fg-base` / `text-fg-mute` のコントラスト確保 |
-| bounce / spring アニメーション | `transition-colors duration-150 ease-out`          |
-| Inter フォント                 | Noto Sans JP / M PLUS 2                            |
-| 過剰な glassmorphism           | border + subtle な背景色                           |
-| 情報の詰め込み                 | 余白を活かした疎な配置                             |
-
-### AI スロップテスト
-
-> このUIを誰かに見せて「AIが作った」と言ったら、すぐに信じるだろうか？
-> もし「はい」なら、それが問題だ。
-
-## 実装の原則
-
-- **既存コンポーネントを使う**: カスタムUIの前にまず k8ordo UI コンポーネントを探す
-- **セマンティックトークンを使う**: 生のカラー値（`bg-teal-500`）ではなくトークン（`bg-primary-bg`）
-- **空間と形で魅せる**: 色の華やかさではなく、余白と角丸の柔らかさで個性を出す
-- **ダークモードを忘れない**: セマンティックトークンを使えば自動対応
-- **アクセシビリティ**: `aria-label`, キーボードナビゲーション, カラーだけに頼らない状態表現
-
-## 詳細リファレンス
+```tsx
+const title = form.field('title');
+
+<FormControl
+  errorText={title.error}
+  invalid={title.invalid}
+  label="Title"
+  required={title.required}
+  renderInput={(props) => <TextField {...props} {...title.input} />}
+/>;
+```
 
-- タイポグラフィ: [references/typography.md](references/typography.md)
-- カラーシステム: [references/color.md](references/color.md)
-- スペーシング・レイアウト: [references/spatial-design.md](references/spatial-design.md)
-- インタラクション: [references/interaction-design.md](references/interaction-design.md)
-- コンポーネント一覧: [references/components.md](references/components.md)
-- Hooks: [references/hooks.md](references/hooks.md)
-- ヘルパー・型: [references/helpers.md](references/helpers.md)
-- AI チャット（Conversation / Message / PromptInput など）: [references/ai-chat.md](references/ai-chat.md)
-- 生成 UI（json-render / OpenUI で LLM に UI を生成させる）: [references/generative-ui.md](references/generative-ui.md)
+## 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 `--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
+
+> Show this UI to someone and tell them an AI made it. Would they believe it
+> immediately? If yes, that is the problem.
+
+## Implementation principles
+
+- **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
+- **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)
+- Color system: [references/color.md](references/color.md)
+- 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)
+- 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)