@k8ordo/ui 1.0.0

package/docs/references/ai-chat.md

@@ -0,0 +1,354 @@
+# k8ordo UI AI チャットコンポーネント
+
+AI チャット UI（会話ログ・メッセージ・入力欄・推論表示・ツール実行表示）を構築するコンポーネント群。ルートではなく専用サブパスからインポートする。
+
+## インポート方法
+
+```tsx
+// 基本コンポーネント（追加の依存なし）
+import {
+  Conversation,
+  Message,
+  PromptInput,
+  Reasoning,
+  Suggestion,
+  ToolInvocation,
+} from '@k8ordo/ui/ai';
+
+// ストリーミング対応 Markdown 描画（optional peer: streamdown）
+import { Response } from '@k8ordo/ui/ai/response';
+
+// AI SDK 連携（optional peer: ai）
+import { mapMessageParts } from '@k8ordo/ui/ai-sdk';
+```
+
+型も `@k8ordo/ui/ai` から export される：
+
+- `ChatStatus`: `'ready' | 'submitted' | 'streaming' | 'error'`（AI SDK の `status` と互換）
+- `ToolState`: `'input-streaming' | 'input-available' | 'approval-requested' | 'approval-responded' | 'output-available' | 'output-error' | 'output-denied'`（AI SDK v7 のツール状態と 1:1）
+
+### optional peer のセットアップ
+
+使うサブパスの分だけインストールする。`@k8ordo/ui/ai` 本体はどちらも不要。
+
+```bash
+# @k8ordo/ui/ai/response（Response）を使う場合
+pnpm add streamdown
+# @k8ordo/ui/ai-sdk（mapMessageParts）を使う場合
+pnpm add ai
+```
+
+`Response` を使う場合は streamdown のスタイルシートの読み込みと、Tailwind の `@source` 設定も必要。streamdown のスタイルはビルド済み `styles.css` には含まれないため、`Response` だけは Tailwind CSS 4 のビルド（`@k8ordo/ui/tailwind.css` エントリ）が前提になる：
+
+```tsx
+import 'streamdown/styles.css';
+```
+
+```css
+/* アプリの CSS エントリに追加（パスは CSS ファイルから node_modules への相対） */
+@source '../node_modules/streamdown/dist/*.js';
+```
+
+なお本リファレンスの例で使う `useChat` は AI SDK の React バインディング（`pnpm add @ai-sdk/react`）から import する。
+
+以下に出てくる `label` / `sendLabel` などの「デフォルト」は文言辞書の既定値（日本語）。`<UIProvider messages={en}>` で辞書ごと切り替えられる（[i18n](components.md)）。個別の prop を渡した場合はそちらが辞書より優先される。
+
+## 全体像
+
+`Conversation`（会話ログ）+ `Message`（吹き出し）+ `PromptInput`（入力欄）が骨組み。`Response` / `Reasoning` / `ToolInvocation` は後から足せる。
+
+```tsx
+'use client';
+import { Avatar, AssistantIcon } from '@k8ordo/ui';
+import { Conversation, Message, PromptInput } from '@k8ordo/ui/ai';
+import { useChat } from '@ai-sdk/react';
+import type { UIMessage } from 'ai';
+
+const textOf = (m: UIMessage) =>
+  m.parts.map((p) => (p.type === 'text' ? p.text : '')).join('');
+
+export function Chat() {
+  const { messages, sendMessage, status, stop } = useChat();
+
+  return (
+    <div className="flex h-full flex-col gap-3">
+      <Conversation.Root>
+        <Conversation.Messages isStreaming={status === 'streaming'}>
+          {messages.map((m) => (
+            <Message.Root
+              from={m.role === 'user' ? 'user' : 'assistant'}
+              key={m.id}
+            >
+              {m.role !== 'user' && (
+                <Avatar
+                  color="primary"
+                  icon={<AssistantIcon />}
+                  name="AI"
+                  size="sm"
+                />
+              )}
+              <Message.Content>{textOf(m)}</Message.Content>
+            </Message.Root>
+          ))}
+        </Conversation.Messages>
+        <Conversation.ScrollButton />
+      </Conversation.Root>
+
+      <PromptInput.Root
+        onStop={stop}
+        onSubmit={(text) => sendMessage({ text })}
+        status={status}
+      >
+        <PromptInput.Textarea placeholder="メッセージを入力" />
+        <PromptInput.Submit />
+      </PromptInput.Root>
+    </div>
+  );
+}
+```
+
+## Conversation
+
+会話ログのスクロール領域。Compound component パターン。最下部に張り付き、新しいメッセージで自動スクロールする。最下部から離れると `ScrollButton` が現れる。
+
+```tsx
+import { Conversation } from '@k8ordo/ui/ai';
+
+<Conversation.Root>
+  <Conversation.Messages isStreaming={isStreaming}>
+    {/* Message.Root ... */}
+  </Conversation.Messages>
+  <Conversation.ScrollButton />
+</Conversation.Root>;
+```
+
+Props (Conversation.Messages):
+
+- `label`: string（デフォルト: `'チャット'`、aria-label として使用）
+- `isStreaming`: boolean（`aria-busy` に反映）
+
+Props (Conversation.ScrollButton):
+
+- `label`: string（デフォルト: `'最新のメッセージへ移動'`）
+
+## Message
+
+メッセージ 1 件。`from="user"` は右寄せの吹き出し、`from="assistant"` は地の文として描画される。アバターなどは `Message.Root` の子として自由に並べられる。
+
+```tsx
+import { Message } from '@k8ordo/ui/ai';
+
+<Message.Root from="user">
+  <Message.Content>こんにちは</Message.Content>
+</Message.Root>
+
+<Message.Root from="assistant">
+  <Message.Content isStreaming>生成中の本文…</Message.Content>
+</Message.Root>
+```
+
+Props (Message.Root):
+
+- `from`: `'user'` | `'assistant'`（必須）
+
+Props (Message.Content):
+
+- `isStreaming`: boolean（true でストリーミングカーソルを表示）
+
+## PromptInput
+
+送信フォーム。Enter で送信、Shift+Enter で改行。IME 変換確定の Enter では送信しない。`status` が `'submitted'` / `'streaming'` の間は `Submit` が停止ボタンに切り替わる。本文は trim され、空文字は送信されない。
+
+```tsx
+import { PromptInput } from '@k8ordo/ui/ai';
+
+<PromptInput.Root
+  status={status}
+  onSubmit={(message) => send(message)}
+  onStop={stop}
+>
+  <PromptInput.Textarea placeholder="メッセージを入力" />
+  <PromptInput.Submit />
+</PromptInput.Root>;
+```
+
+Props (PromptInput.Root):
+
+- `status`: ChatStatus（デフォルト: `'ready'`）
+- `value` / `defaultValue` / `onChange`: controlled / uncontrolled 両対応（`onChange` は `(value: string) => void`）
+- `onSubmit`: `(message: string) => void`（trim 済みの本文）
+- `onStop`: `() => void`（送信中に停止ボタンを押したとき）
+
+Props (PromptInput.Textarea):
+
+- `placeholder`: string ほか textarea 属性
+
+Props (PromptInput.Submit):
+
+- `sendLabel`: string（デフォルト: `'送信'`）
+- `stopLabel`: string（デフォルト: `'停止'`）
+
+## Reasoning
+
+推論（思考過程）の折りたたみ表示。ストリーミング中はラベルが「思考中…」になる。
+
+```tsx
+import { Reasoning } from '@k8ordo/ui/ai';
+
+<Reasoning isStreaming={isThinking}>{reasoningText}</Reasoning>;
+```
+
+Props:
+
+- `isStreaming`: boolean
+- `isOpen` / `defaultOpen` / `onChange`: 開閉の controlled / uncontrolled 両対応（`onChange` は `(isOpen: boolean) => void`）
+
+## Response
+
+ストリーミング対応の Markdown レンダラ。未クローズのコードブロックなど途中の Markdown も破綻なく描画する。optional peer の `streamdown` が必要（[セットアップ](#optional-peer-のセットアップ)参照）。
+
+```tsx
+import { Response } from '@k8ordo/ui/ai/response';
+import 'streamdown/styles.css';
+
+<Message.Content>
+  <Response isStreaming={isStreaming}>{markdown}</Response>
+</Message.Content>;
+```
+
+Props:
+
+- `children`: string（Markdown 文字列、必須）
+- `isStreaming`: boolean
+- 上記以外の streamdown の props（`translations` / `controls` / `linkSafety` / `plugins` / `components` / `urlTransform` / `dir` など）はそのまま透過する。`className` と `mode` はライブラリが握る（`mode` は `isStreaming` から決まる）
+
+文言は i18n 辞書から引くので、既定では「コードをコピー」「表をダウンロード」などが日本語で出る。個別に変えたいときは `translations` を渡す（prop > 辞書 > streamdown 既定）。
+
+`linkSafety` はライブラリ側で**無効を既定にしている**。streamdown の既定（有効）ではリンクが `<a>` ではなく `<button>` で描画され、⌘クリック・中クリック・リンクアドレスのコピー・支援技術の link ロールが失われるため。確認ダイアログを挟みたい場合は明示的に有効化する:
+
+```tsx
+<Response linkSafety={{ enabled: true }}>{markdown}</Response>
+```
+
+なお `javascript:` のような危険なスキームは `linkSafety` とは無関係に rehype-harden が無効化するので、既定のままでも生きたリンクにはならない。
+
+## Suggestion
+
+候補プロンプトのチップ表示。クリックで `onSelect` に `value` が渡る。
+
+```tsx
+import { Suggestion } from '@k8ordo/ui/ai';
+
+<Suggestion.List>
+  <Suggestion.Item onSelect={send} value="IME 対応について教えて" />
+  <Suggestion.Item onSelect={send} value="streaming">
+    ストリーミング表示は？
+  </Suggestion.Item>
+</Suggestion.List>;
+```
+
+Props (Suggestion.List):
+
+- `label`: string（デフォルト: `'候補'`、aria-label として使用）
+
+Props (Suggestion.Item):
+
+- `value`: string（必須。children 省略時は表示テキストも兼ねる）
+- `onSelect`: `(value: string) => void`
+
+## ToolInvocation
+
+ツール呼び出しの折りたたみ表示。`state` に応じてスピナー / 成功 / エラー / 拒否のアイコンが切り替わる（承認待ち・承認応答・入力中は進行中としてスピナー）。
+
+```tsx
+import { ToolInvocation } from '@k8ordo/ui/ai';
+
+<ToolInvocation
+  name="search_web"
+  state="output-available"
+  input={{ query: 'k8ordo UI' }}
+  output="検索結果…"
+/>;
+```
+
+Props:
+
+- `name`: string（必須、ツール名）
+- `state`: ToolState（必須）
+- `input`: unknown（文字列以外は JSON 表示）
+- `output`: ReactNode（文字列は `pre` 表示、要素はそのまま描画）
+- `errorText`: string（`state="output-error"` 時の表示。省略時は既定文言）
+- `deniedReason`: string（`state="output-denied"` 時の表示。省略時は既定文言）
+- `isOpen` / `defaultOpen` / `onChange`: 開閉の controlled / uncontrolled 両対応
+
+## AI SDK 連携（mapMessageParts）
+
+`@k8ordo/ui/ai-sdk` の `mapMessageParts` は、AI SDK の `UIMessage.parts` を描画しやすい `MappedPart[]` に変換する。React 非依存で、optional peer の `ai`（v7）が必要。
+
+```ts
+type MappedPart =
+  | { kind: 'text'; text: string }
+  | { kind: 'reasoning'; text: string }
+  | {
+      kind: 'tool';
+      name: string;
+      toolCallId: string;
+      state: ToolState;
+      input?: unknown;
+      output?: unknown;
+      errorText?: string;
+      deniedReason?: string;
+    };
+```
+
+利用側が `kind` で分岐して `Response` / `Reasoning` / `ToolInvocation` を描画する：
+
+```tsx
+import { mapMessageParts } from '@k8ordo/ui/ai-sdk';
+import { Reasoning, ToolInvocation } from '@k8ordo/ui/ai';
+import { Response } from '@k8ordo/ui/ai/response';
+
+<Message.Content>
+  {mapMessageParts(message).map((part, i) => {
+    if (part.kind === 'reasoning')
+      return <Reasoning key={i}>{part.text}</Reasoning>;
+    if (part.kind === 'tool') {
+      // output は unknown なので、ReactNode に変換してから渡す
+      return (
+        <ToolInvocation
+          key={part.toolCallId}
+          name={part.name}
+          state={part.state}
+          input={part.input}
+          output={
+            typeof part.output === 'string'
+              ? part.output
+              : JSON.stringify(part.output, null, 2)
+          }
+          errorText={part.errorText}
+          deniedReason={part.deniedReason}
+        />
+      );
+    }
+    return <Response key={i}>{part.text}</Response>;
+  })}
+</Message.Content>;
+```
+
+`ChatStatus` / `ToolState` 型は `@k8ordo/ui/ai-sdk` からも re-export される。
+
+## 生成 UI との組み合わせ
+
+LLM がツール結果として返した UI spec を、チャットの吹き出し内で描画できる。詳細は [生成 UI リファレンス](generative-ui.md) を参照。
+
+```tsx
+'use client';
+import { Message } from '@k8ordo/ui/ai';
+import { JsonRenderUI } from '@k8ordo/ui/json-render/registry';
+
+<Message.Root from="assistant">
+  <Message.Content>
+    <JsonRenderUI spec={spec} />
+  </Message.Content>
+</Message.Root>;
+```

package/docs/references/color.md

@@ -0,0 +1,121 @@
+# カラーシステム
+
+k8ordo UI のカラーは OKLCH 色空間で定義され、穏やかなトーンでUIに出る。
+
+## 設計思想
+
+- **OKLCH パレット**: 全色を OKLCH で定義。明度（L）を全色相で統一し、同じステップ番号同士のコントラストが揃う
+- **鮮やかなパレット、穏やかなトークン**: パレット自体は鮮やかに保ち、セマンティックトークンで抑えたトーンにマッピング
+- **WCAG AAA 準拠**: fg/bg の組み合わせで 7:1 以上のコントラスト比を確保
+- **60-30-10 ルール**: 60% ニュートラル（グレー系）、30% サポート（bg-subtle 等）、10% アクセント（primary）
+- Primary に Teal（H:180）、Secondary に Cyan（H:210）を使用
+- ダークモードは「ライトモードの反転」ではなく、独立したトーンで設計
+
+## OKLCH パレット設計
+
+明度スケール（全色相で共通）:
+
+| Step | L     | 用途                       |
+| ---- | ----- | -------------------------- |
+| 50   | 0.975 | 最も薄い背景               |
+| 100  | 0.945 | 薄い背景                   |
+| 200  | 0.900 | 控えめな背景               |
+| 300  | 0.840 | サポートカラー             |
+| 400  | 0.750 | 中間トーン                 |
+| 500  | 0.660 | コアカラー                 |
+| 600  | 0.575 | やや暗い                   |
+| 700  | 0.490 | 暗いトーン                 |
+| 800  | 0.410 | テキスト用（AAA on white） |
+| 900  | 0.370 | 最も暗い                   |
+
+Chroma は色相ごとに最適化（gamut 内で最大化）。
+
+## セマンティックカラー（前景）
+
+| Tailwind クラス   | Light      | Dark       | 用途             |
+| ----------------- | ---------- | ---------- | ---------------- |
+| `text-fg-base`    | gray-900   | gray-50    | 基本テキスト     |
+| `text-fg-subtle`  | gray-400   | gray-500   | プレースホルダー |
+| `text-fg-mute`    | gray-700   | gray-300   | 補足テキスト     |
+| `text-fg-inverse` | gray-50    | gray-900   | 反転テキスト     |
+| `text-fg-info`    | blue-800   | blue-200   | 情報             |
+| `text-fg-success` | green-800  | green-200  | 成功             |
+| `text-fg-warning` | yellow-800 | yellow-200 | 警告             |
+| `text-fg-error`   | red-800    | red-200    | エラー           |
+
+## セマンティックカラー（背景）
+
+| Tailwind クラス   | Light      | Dark       | 用途             |
+| ----------------- | ---------- | ---------- | ---------------- |
+| `bg-bg-base`      | white      | gray-900   | カード背景       |
+| `bg-bg-subtle`    | gray-100   | gray-800   | ページ背景       |
+| `bg-bg-mute`      | gray-200   | gray-700   | ホバー状態用     |
+| `bg-bg-emphasize` | gray-300   | gray-600   | アクティブ状態用 |
+| `bg-bg-inverse`   | gray-900   | white      | 反転背景         |
+| `bg-bg-info`      | blue-100   | blue-900   | 情報背景         |
+| `bg-bg-success`   | green-100  | green-900  | 成功背景         |
+| `bg-bg-warning`   | yellow-100 | yellow-900 | 警告背景         |
+| `bg-bg-error`     | red-100    | red-900    | エラー背景       |
+
+## セマンティックカラー（ボーダー）
+
+| Tailwind クラス           | Light      | Dark       | 用途           |
+| ------------------------- | ---------- | ---------- | -------------- |
+| `border-border-base`      | gray-400   | gray-600   | 標準ボーダー   |
+| `border-border-subtle`    | gray-100   | gray-900   | 薄いボーダー   |
+| `border-border-mute`      | gray-200   | gray-800   | 控えめボーダー |
+| `border-border-emphasize` | gray-500   | gray-500   | 強調ボーダー   |
+| `border-border-inverse`   | gray-700   | gray-300   | 反転ボーダー   |
+| `border-border-info`      | blue-500   | blue-500   | 情報ボーダー   |
+| `border-border-success`   | green-500  | green-500  | 成功ボーダー   |
+| `border-border-warning`   | yellow-500 | yellow-500 | 警告ボーダー   |
+| `border-border-error`     | red-500    | red-500    | エラーボーダー |
+
+## ブランドカラー（Primary: Teal H:180）
+
+| Tailwind クラス           | Light    | Dark     | 用途                |
+| ------------------------- | -------- | -------- | ------------------- |
+| `text-primary-fg`         | teal-800 | teal-100 | Primary テキスト    |
+| `bg-primary-bg`           | teal-200 | teal-800 | Primary 背景        |
+| `bg-primary-bg-subtle`    | teal-50  | teal-900 | 薄い Primary 背景   |
+| `bg-primary-bg-mute`      | teal-100 | teal-800 | 控えめ Primary 背景 |
+| `bg-primary-bg-emphasize` | teal-200 | teal-700 | 強調 Primary 背景   |
+| `border-primary-border`   | teal-500 | teal-500 | Primary ボーダー    |
+
+## ブランドカラー（Secondary: Cyan H:210）
+
+| Tailwind クラス           | Light    | Dark     | 用途                |
+| ------------------------- | -------- | -------- | ------------------- |
+| `text-secondary-fg`       | cyan-700 | cyan-300 | Secondary テキスト  |
+| `bg-secondary-bg`         | cyan-300 | cyan-700 | Secondary 背景      |
+| `bg-secondary-bg-subtle`  | cyan-100 | cyan-900 | 薄い Secondary 背景 |
+| `border-secondary-border` | cyan-600 | cyan-600 | Secondary ボーダー  |
+
+## 使い方の例
+
+```tsx
+// ページ背景にカードを浮かせる
+<div className="bg-bg-subtle min-h-screen">
+  <Card appearance="shadow">
+    <div className="p-8">
+      <h2 className="text-fg-base font-bold">タイトル</h2>
+      <p className="text-fg-mute mt-2">補足テキスト</p>
+      <span className="text-primary-fg">アクセントテキスト</span>
+    </div>
+  </Card>
+</div>
+
+// ホバー状態
+<button className="bg-bg-base hover:bg-bg-mute transition-colors">
+  ボタン
+</button>
+```
+
+## やってはいけないこと
+
+- グラデーション背景（`bg-gradient-to-*`）
+- 彩度の高い色の広範囲使用（アクセントは小面積で）
+- 透明度による状態表現（`/90`, `/80` など）— 専用のセマンティックカラーを使う
+- ホバーに `bg-primary-bg` を使う — `bg-bg-mute` を優先
+- 生のパレット色（`bg-teal-500`）を直接使う — セマンティックトークンを使う
+- ダークモードで単純にカラーを反転させる