@k8o/arte-odyssey 4.0.0 → 4.2.0

package/docs/references/components.md

@@ -0,0 +1,449 @@
+# ArteOdyssey コンポーネント一覧
+
+## インポート方法
+
+```tsx
+// スタイルシート（必須）
+import '@k8o/arte-odyssey/styles.css';
+
+// プロバイダー（アプリルートで1回）
+import { ArteOdysseyProvider } from '@k8o/arte-odyssey/providers';
+
+// 各コンポーネント（個別インポート）
+import { Button } from '@k8o/arte-odyssey/button';
+import { Card } from '@k8o/arte-odyssey/card';
+```
+
+## レイアウト・ナビゲーション
+
+### Accordion
+
+折りたたみ可能なセクション。
+
+```tsx
+import { Accordion, AccordionItem } from '@k8o/arte-odyssey/accordion';
+
+<Accordion>
+  <AccordionItem title="セクション1">コンテンツ</AccordionItem>
+</Accordion>;
+```
+
+### Breadcrumb
+
+パンくずリスト。
+
+```tsx
+import { Breadcrumb, BreadcrumbItem } from '@k8o/arte-odyssey/breadcrumb';
+
+<Breadcrumb>
+  <BreadcrumbItem href="/">ホーム</BreadcrumbItem>
+  <BreadcrumbItem href="/products">製品</BreadcrumbItem>
+  <BreadcrumbItem>詳細</BreadcrumbItem>
+</Breadcrumb>;
+```
+
+### Card / InteractiveCard
+
+コンテンツをグループ化するカード。
+
+```tsx
+import { Card, InteractiveCard } from '@k8o/arte-odyssey/card';
+
+// 静的カード
+<Card title="タイトル" variant="primary" width="full" appearance="shadow">
+  <div className="p-6">コンテンツ</div>
+</Card>
+
+// クリック可能なカード（hover:scale-[1.02], active:scale-[0.98]）
+<InteractiveCard title="記事" appearance="bordered">
+  <div className="p-6">コンテンツ</div>
+</InteractiveCard>
+```
+
+Props:
+
+- `variant`: `'primary'` | `'secondary'`
+- `title`: string
+- `width`: `'full'` | `'fit'`
+- `appearance`: `'shadow'` | `'bordered'`
+
+### Tabs
+
+タブ切り替え。
+
+```tsx
+import { Tabs, TabList, Tab, TabPanel } from '@k8o/arte-odyssey/tabs';
+
+<Tabs>
+  <TabList>
+    <Tab>タブ1</Tab>
+    <Tab>タブ2</Tab>
+  </TabList>
+  <TabPanel>パネル1</TabPanel>
+  <TabPanel>パネル2</TabPanel>
+</Tabs>;
+```
+
+### Separator
+
+区切り線。
+
+```tsx
+import { Separator } from '@k8o/arte-odyssey/separator';
+
+<Separator />
+<Separator color="mute" />
+<Separator color="subtle" />
+<Separator orientation="vertical" />
+```
+
+### ScrollLinked
+
+スクロール進捗をプログレスバーで表示。
+
+```tsx
+import { ScrollLinked } from '@k8o/arte-odyssey/scroll-linked';
+
+<ScrollLinked />
+<ScrollLinked container={containerRef} />
+```
+
+## ボタン・リンク
+
+### Button
+
+```tsx
+import { Button } from '@k8o/arte-odyssey/button';
+
+<Button
+  size="sm" | "md" | "lg"
+  color="primary" | "gray"
+  variant="contained" | "outlined" | "skeleton"
+  fullWidth={false}
+  startIcon={<Icon />}
+  endIcon={<Icon />}
+  disabled={false}
+>
+  ボタン
+</Button>
+```
+
+### IconButton
+
+アイコンのみのボタン。`bg` prop でスタイルを制御。
+
+```tsx
+import { IconButton } from '@k8o/arte-odyssey/icon-button';
+
+<IconButton label="閉じる" bg="transparent" size="md">
+  <XIcon />
+</IconButton>;
+```
+
+Props:
+
+- `bg`: `'transparent'` | `'base'` | `'primary'`（デフォルト: `'transparent'`）
+- `size`: `'sm'` | `'md'` | `'lg'`
+- `label`: string（必須、aria-label として使用）
+
+### LinkButton
+
+リンクスタイルのボタン。Button と同じ `color` / `variant` props。
+
+```tsx
+import { LinkButton } from '@k8o/arte-odyssey/link-button';
+
+<LinkButton href="/page" color="gray" variant="outlined">
+  リンク
+</LinkButton>;
+```
+
+### IconLink
+
+アイコンのみのリンク。IconButton と同じ `bg` prop。
+
+```tsx
+import { IconLink } from '@k8o/arte-odyssey/icon-link';
+
+<IconLink href="/home" bg="base" label="ホーム">
+  <HomeIcon />
+</IconLink>;
+```
+
+### Anchor
+
+テキストリンク。
+
+```tsx
+import { Anchor } from '@k8o/arte-odyssey/anchor';
+
+<Anchor href="https://example.com" isExternal>
+  外部リンク
+</Anchor>;
+```
+
+## フォーム
+
+### TextField
+
+```tsx
+import { TextField } from '@k8o/arte-odyssey/text-field';
+
+<TextField id="email" defaultValue="" placeholder="example@mail.com" />;
+```
+
+### Textarea
+
+```tsx
+import { Textarea } from '@k8o/arte-odyssey/textarea';
+
+<Textarea label="説明" rows={4} value={value} onChange={onChange} />;
+```
+
+### Checkbox
+
+```tsx
+import { Checkbox } from '@k8o/arte-odyssey/checkbox';
+
+<Checkbox checked={checked} onChange={onChange}>
+  同意する
+</Checkbox>;
+```
+
+### Radio
+
+```tsx
+import { Radio } from '@k8o/arte-odyssey/radio';
+
+<Radio
+  labelId="example-radio"
+  name="example"
+  onChange={onChange}
+  options={[
+    { value: 'a', label: '選択肢A' },
+    { value: 'b', label: '選択肢B' },
+  ]}
+  value={value}
+/>;
+```
+
+### Select
+
+```tsx
+import { Select } from '@k8o/arte-odyssey/select';
+
+<Select
+  label="選択"
+  options={[
+    { value: '1', label: 'オプション1' },
+    { value: '2', label: 'オプション2' },
+  ]}
+  value={value}
+  onChange={onChange}
+/>;
+```
+
+### NumberField
+
+```tsx
+import { NumberField } from '@k8o/arte-odyssey/number-field';
+
+<NumberField label="数量" min={0} max={100} value={value} onChange={onChange} />;
+```
+
+### RangeField
+
+```tsx
+import { RangeField } from '@k8o/arte-odyssey/range-field';
+
+<RangeField label="音量" min={0} max={100} value={value} onChange={onChange} />;
+```
+
+### Autocomplete
+
+```tsx
+import { Autocomplete } from '@k8o/arte-odyssey/autocomplete';
+
+<Autocomplete label="検索" options={options} value={value} onChange={onChange} />;
+```
+
+### FileField
+
+コンポジットパターンのファイルアップロード。
+
+```tsx
+import { FileField } from '@k8o/arte-odyssey/file-field';
+
+<FileField.Root accept="image/*" multiple maxFiles={5}>
+  <FileField.Trigger>ファイルを選択</FileField.Trigger>
+  <FileField.ItemList />
+</FileField.Root>;
+```
+
+Props (Root):
+
+- `accept`: string
+- `multiple`: boolean
+- `maxFiles`: number
+- `isDisabled`, `isInvalid`, `isRequired`: boolean
+
+### FormControl
+
+フォームフィールドのラッパー（ラベル・エラー表示を統一）。
+
+```tsx
+import { FormControl } from '@k8o/arte-odyssey/form-control';
+
+<FormControl label="ラベル" error="エラーメッセージ" isRequired>
+  <TextField id="name" />
+</FormControl>;
+```
+
+## フィードバック
+
+### Alert
+
+```tsx
+import { Alert } from '@k8o/arte-odyssey/alert';
+
+<Alert status="info" | "success" | "warning" | "error">
+  メッセージ
+</Alert>
+```
+
+### Toast
+
+```tsx
+import { useToast } from '@k8o/arte-odyssey/toast';
+
+const toast = useToast();
+toast.show({ message: '保存しました', status: 'success' });
+```
+
+### Progress
+
+```tsx
+import { Progress } from '@k8o/arte-odyssey/progress';
+
+<Progress value={50} max={100} />;
+```
+
+### BaselineStatus
+
+Web API のブラウザサポート状況を表示。
+
+```tsx
+import { BaselineStatus } from '@k8o/arte-odyssey/baseline-status';
+
+<BaselineStatus featureId="dialog" />;
+```
+
+## オーバーレイ
+
+### Dialog
+
+```tsx
+import { Dialog } from '@k8o/arte-odyssey/dialog';
+
+<Dialog open={open} onClose={onClose} title="確認">
+  コンテンツ
+</Dialog>;
+```
+
+### Drawer
+
+```tsx
+import { Drawer } from '@k8o/arte-odyssey/drawer';
+
+<Drawer open={open} onClose={onClose} position="right">
+  コンテンツ
+</Drawer>;
+```
+
+### Modal
+
+```tsx
+import { Modal } from '@k8o/arte-odyssey/modal';
+
+<Modal open={open} onClose={onClose}>
+  コンテンツ
+</Modal>;
+```
+
+### Popover
+
+```tsx
+import { Popover } from '@k8o/arte-odyssey/popover';
+
+<Popover trigger={<Button>開く</Button>}>ポップオーバーコンテンツ</Popover>;
+```
+
+### Tooltip
+
+```tsx
+import { Tooltip } from '@k8o/arte-odyssey/tooltip';
+
+<Tooltip content="ヒント">
+  <Button>ホバー</Button>
+</Tooltip>;
+```
+
+### DropdownMenu
+
+```tsx
+import { DropdownMenu, DropdownMenuItem } from '@k8o/arte-odyssey/dropdown-menu';
+
+<DropdownMenu trigger={<Button>メニュー</Button>}>
+  <DropdownMenuItem onClick={handleClick}>アイテム1</DropdownMenuItem>
+  <DropdownMenuItem>アイテム2</DropdownMenuItem>
+</DropdownMenu>;
+```
+
+## データ表示
+
+### Code
+
+```tsx
+import { Code } from '@k8o/arte-odyssey/code';
+
+<Code language="typescript">{`const x = 1;`}</Code>;
+```
+
+### Heading
+
+```tsx
+import { Heading } from '@k8o/arte-odyssey/heading';
+
+<Heading level={1}>見出し</Heading>;
+```
+
+### TextTag
+
+```tsx
+import { TextTag } from '@k8o/arte-odyssey/text-tag';
+
+<TextTag>タグ</TextTag>;
+```
+
+### ListBox
+
+```tsx
+import { ListBox, ListBoxItem } from '@k8o/arte-odyssey/list-box';
+
+<ListBox>
+  <ListBoxItem>アイテム1</ListBoxItem>
+  <ListBoxItem>アイテム2</ListBoxItem>
+</ListBox>;
+```
+
+## ユーティリティ
+
+### ArteOdysseyProvider
+
+```tsx
+import { ArteOdysseyProvider } from '@k8o/arte-odyssey/providers';
+
+<ArteOdysseyProvider>
+  <App />
+</ArteOdysseyProvider>;
+```

package/docs/references/interaction-design.md

@@ -0,0 +1,74 @@
+# インタラクションデザイン
+
+ArteOdyssey のインタラクションは「静かな変化」を原則とする。
+
+## インタラクティブ状態
+
+8つの状態を意識して設計する。
+
+| 状態     | スタイル                                              |
+| -------- | ----------------------------------------------------- |
+| Default  | 基本スタイル                                          |
+| Hover    | `hover:bg-bg-mute` — 穏やかな色変化                   |
+| Focus    | `focus-visible:ring-2 focus-visible:ring-border-info` |
+| Active   | `active:bg-bg-emphasize`                              |
+| Disabled | `opacity-50 cursor-not-allowed`                       |
+| Loading  | スピナーまたはスケルトン                              |
+| Selected | `bg-primary-bg-subtle`                                |
+| Error    | `border-border-error` + `text-fg-error`               |
+
+## トランジション
+
+控えめで自然な動き。
+
+| 用途                 | 推奨設定                                   |
+| -------------------- | ------------------------------------------ |
+| ホバー色変化         | `transition-colors duration-150 ease-out`  |
+| 透過度変化           | `transition-opacity duration-200 ease-out` |
+| サイズ変化を伴う場合 | `transition-all duration-150 ease-out`     |
+
+### タイミングの原則
+
+- **100ms**: 即時フィードバック（ボタンプレス）
+- **150–200ms**: 標準トランジション（ホバー、フォーカス）
+- **300ms**: 開閉アニメーション（Accordion, Drawer の限度）
+- **300ms を超えない** — 重く感じる
+
+## フォーカス管理
+
+- `focus-visible` を使う（`focus` ではなく）— マウスクリック時にリングが出ない
+- フォーカスリングは `ring-border-info` で統一
+- `outline-hidden` でデフォルトのアウトラインを消してから ring を適用
+
+```tsx
+className = 'focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-border-info';
+```
+
+## フォームデザイン
+
+- ラベルは入力の上に配置（左配置は日本語で読みにくい）
+- エラーメッセージは入力の直下に `text-fg-error text-sm`
+- 必須マークは `*` でラベルの後ろに
+- `FormControl` コンポーネントでラベル・エラー表示を統一
+
+```tsx
+import { FormControl } from '@k8o/arte-odyssey/form-control';
+
+<FormControl label="メールアドレス" error="入力してください" isRequired>
+  <TextField id="email" placeholder="example@mail.com" />
+</FormControl>;
+```
+
+## アクセシビリティ
+
+- `aria-label` / `aria-describedby` を適切に設定
+- キーボードナビゲーションを確保（Tab, Enter, Escape, 矢印キー）
+- `prefers-reduced-motion` を考慮 — ArteOdyssey の motion ライブラリが自動対応
+- カラーだけに頼らない状態表現（アイコンやテキストを併用）
+
+## やってはいけないこと
+
+- bounce / spring 系のイージング
+- 300ms を超えるアニメーション
+- ホバーに強い原色（`bg-primary-bg`）を使う
+- `cursor-pointer` をボタン以外に付ける（リンクにも不要）

package/docs/references/spatial-design.md

@@ -0,0 +1,101 @@
+# スペーシング・レイアウト
+
+ArteOdyssey は「余白で語る」デザイン。詰め込まず、空間にゆとりを持たせる。
+
+## スペーシングの原則
+
+4pt ベースのスペーシングシステム。Tailwind の標準スケールを使用。
+
+### コンポーネント内部パディング
+
+| 用途       | クラス | 値   |
+| ---------- | ------ | ---- |
+| コンパクト | `p-4`  | 16px |
+| 標準       | `p-6`  | 24px |
+| ゆったり   | `p-8`  | 32px |
+
+### リスト・メニューアイテム
+
+```tsx
+className = 'px-3 py-2'; // 水平に余裕、垂直はコンパクト
+```
+
+### テキスト間の余白
+
+| 関係性         | クラス  | 用途                         |
+| -------------- | ------- | ---------------------------- |
+| 近い要素       | `mt-2`  | 説明テキスト、ヘルプテキスト |
+| 標準           | `mt-4`  | 段落間、フォームフィールド間 |
+| セクション間   | `mt-8`  | セクション区切り             |
+| 大セクション間 | `mt-12` | ページレベルの区切り         |
+
+## 角丸
+
+| 用途                       | クラス         |
+| -------------------------- | -------------- |
+| Badge, Tag 等小さい要素    | `rounded-sm`   |
+| Button, Input              | `rounded-md`   |
+| Card, Modal, Dialog        | `rounded-lg`   |
+| プログレスバー, IconButton | `rounded-full` |
+
+`rounded-2xl` 以上は使わない。
+
+## シャドウ
+
+基本的に使わない。ボーダーで区切りを表現する。
+
+| 用途                     | スタイル                                                  |
+| ------------------------ | --------------------------------------------------------- |
+| Card（shadow）           | `shadow-sm`（`appearance="shadow"` 時）                   |
+| Card（bordered）         | `border border-border-mute`（`appearance="bordered"` 時） |
+| Modal / Dialog / Tooltip | `shadow-md`                                               |
+| Dropdown / ListBox       | `shadow-md`                                               |
+| Button                   | なし                                                      |
+
+`shadow-xl` 以上は使わない。
+
+## レイアウトパターン
+
+### 余白で階層を作る
+
+```tsx
+// Good: 余白の差で関連度を示す
+<section className="mt-12">
+  <Heading level={2}>セクション</Heading>
+  <p className="mt-2">直接関連する説明</p>
+  <div className="mt-8">やや離れたコンテンツ</div>
+</section>
+
+// Bad: すべて同じ余白
+<section className="mt-4">
+  <Heading level={2}>セクション</Heading>
+  <p className="mt-4">説明</p>
+  <div className="mt-4">コンテンツ</div>
+</section>
+```
+
+### カードは万能ではない
+
+すべてのコンテンツをカードに入れる必要はない。余白と Separator で十分なケースが多い。
+
+```tsx
+import { Separator } from '@k8o/arte-odyssey/separator';
+
+// Good: Separator で区切る
+<div>
+  <section>コンテンツA</section>
+  <Separator className="my-8" />
+  <section>コンテンツB</section>
+</div>
+
+// 過剰: すべてカードに入れる
+<Card>コンテンツA</Card>
+<Card>コンテンツB</Card>
+```
+
+## やってはいけないこと
+
+- `gap-1` や `p-1` のような極端に狭いスペーシング
+- コンテンツの詰め込み（情報密度より余白を優先）
+- ネストされたカード（Card in Card）
+- 12 を超える z-index 値

package/docs/references/typography.md

@@ -0,0 +1,67 @@
+# タイポグラフィ
+
+ArteOdyssey のタイポグラフィは「読みやすさ」と「静けさ」を両立する。
+
+## フォントファミリー
+
+日本語最適化のフォントスタック。
+
+```css
+font-family: 'Noto Sans JP', 'M PLUS 2', sans-serif;
+```
+
+- **Inter / Roboto / Open Sans は使わない** — AI が生成した感が出る
+- 日本語テキストが主体のため、和文フォントを優先
+
+## フォントサイズスケール
+
+| Tailwind クラス | 値       | 用途                 |
+| --------------- | -------- | -------------------- |
+| `text-xs`       | 0.75rem  | 注釈、キャプション   |
+| `text-sm`       | 0.875rem | 補足テキスト、ラベル |
+| `text-md`       | 1rem     | 本文（デフォルト）   |
+| `text-lg`       | 1.125rem | 小見出し             |
+| `text-xl`       | 1.25rem  | 見出し               |
+| `text-2xl`      | 1.5rem   | 大見出し             |
+| `text-3xl`      | 1.875rem | ページタイトル       |
+
+## フォントウェイト
+
+ウェイトは控えめに使う。太字の多用は「静けさ」を損なう。
+
+| Tailwind クラス | 値  | 用途                         |
+| --------------- | --- | ---------------------------- |
+| `font-normal`   | 400 | 本文                         |
+| `font-medium`   | 450 | 強調テキスト（控えめな強調） |
+| `font-bold`     | 700 | 見出し、ボタンラベル         |
+
+- `font-semibold` (600) や `font-extrabold` (800) は使わない
+- `font-medium` が 450 であることに注意（一般的な 500 より軽い）
+
+## 行間
+
+日本語テキストは欧文より広い行間が必要。
+
+- 本文: `leading-relaxed` (1.625) を推奨
+- 見出し: `leading-tight` (1.25) か `leading-snug` (1.375)
+- リスト内: デフォルトの `leading-normal` (1.5)
+
+## Heading コンポーネント
+
+見出しには `Heading` コンポーネントを使う。
+
+```tsx
+import { Heading } from '@k8o/arte-odyssey/heading';
+
+<Heading level={1}>ページタイトル</Heading>
+<Heading level={2}>セクション見出し</Heading>
+<Heading level={3}>サブセクション</Heading>
+```
+
+## やってはいけないこと
+
+- 3種類以上のフォントウェイトを1画面で使う
+- `text-3xl` より大きいサイズを使う（ページタイトル以外）
+- `uppercase` や `tracking-widest` を日本語テキストに適用する
+- テキストにグラデーションをかける
+- フォントサイズだけで階層を作る（余白も活用する）