@k8o/arte-odyssey 4.1.0 → 4.2.0

package/README.md

@@ -66,15 +66,9 @@ function MyPage() {
 }
 ```
 
-## AI Agent Skills
+## AI Agent Documentation
 
-ArteOdyssey provides an Agent Skill for AI coding assistants. It gives your agent knowledge of the design system, component APIs, and design principles.
-
-```bash
-npx skills add k35o/ArteOdyssey --skill arte-odyssey-usage
-```
-
-Compatible with Claude Code, Cursor, GitHub Copilot, and other [Agent Skills](https://agentskills.io/) compatible tools.
+ArteOdyssey includes design system documentation in `docs/` directory. When installed via npm, AI coding assistants can reference `node_modules/@k8o/arte-odyssey/docs/GUIDE.md` for design principles, component APIs, and usage patterns.
 
 ## Component Categories
 
@@ -132,7 +126,6 @@ Compatible with Claude Code, Cursor, GitHub Copilot, and other [Agent Skills](ht
 
 ### Utilities
 
-- **ErrorBoundary** - Error handling wrapper
 - **ArteOdysseyProvider** - Context providers for the library
 - **Icons** - Icon component collection
 

package/dist/components/icons/base.d.mts

@@ -2,7 +2,7 @@ import { FC, ReactNode } from "react";
 
 //#region src/components/icons/base.d.ts
 type BaseIconProps = {
-  size: 'sm' | 'md' | 'lg';
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
 };
 declare const BaseIcon: FC<BaseIconProps & {
   renderItem: (arg: {

package/dist/components/icons/base.mjs

@@ -1,7 +1,16 @@
 import { cn } from "../../helpers/cn.mjs";
 //#region src/components/icons/base.tsx
+const sizeClass = {
+	xs: "size-3",
+	sm: "size-4",
+	md: "size-6",
+	lg: "size-8",
+	xl: "size-10",
+	"2xl": "size-12",
+	"3xl": "size-14"
+};
 const BaseIcon = ({ size, renderItem }) => {
-	return renderItem({ className: cn(size === "sm" && "size-4", size === "md" && "size-6", size === "lg" && "size-8") });
+	return renderItem({ className: cn(sizeClass[size]) });
 };
 //#endregion
 export { BaseIcon };

package/dist/components/index.d.mts

@@ -52,5 +52,4 @@ import { Popover } from "./overlays/popover/popover.mjs";
 import { Tooltip } from "./overlays/tooltip/tooltip.mjs";
 import { ArteOdysseyProvider } from "./providers/arte-odyssey-provider.mjs";
 import { PortalRootProvider, usePortalRoot } from "./providers/portal-root.mjs";
-import { ErrorBoundary } from "./utility/error-boundary/index.mjs";
-export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Drawer, DropdownMenu, EasyIcon, ErrorBoundary, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, useOpenContext, usePortalRoot, useToast };
+export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Drawer, DropdownMenu, EasyIcon, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, useOpenContext, usePortalRoot, useToast };

package/dist/components/index.mjs

@@ -52,5 +52,4 @@ import { Popover } from "./overlays/popover/popover.mjs";
 import { DropdownMenu } from "./overlays/dropdown-menu/dropdown-menu.mjs";
 import { ListBox } from "./overlays/list-box/list-box.mjs";
 import { Tooltip } from "./overlays/tooltip/tooltip.mjs";
-import { ErrorBoundary } from "./utility/error-boundary/index.mjs";
-export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Drawer, DropdownMenu, EasyIcon, ErrorBoundary, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, useOpenContext, usePortalRoot, useToast };
+export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Drawer, DropdownMenu, EasyIcon, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, useOpenContext, usePortalRoot, useToast };

package/dist/index.d.mts

@@ -53,7 +53,6 @@ import { Popover } from "./components/overlays/popover/popover.mjs";
 import { Tooltip } from "./components/overlays/tooltip/tooltip.mjs";
 import { ArteOdysseyProvider } from "./components/providers/arte-odyssey-provider.mjs";
 import { PortalRootProvider, usePortalRoot } from "./components/providers/portal-root.mjs";
-import { ErrorBoundary } from "./components/utility/error-boundary/index.mjs";
 import { cn } from "./helpers/cn.mjs";
 import { findAllColors } from "./helpers/color/find-all-colors.mjs";
 import { isInternalRoute } from "./helpers/is-internal-route.mjs";
@@ -74,4 +73,4 @@ import { useStep } from "./hooks/step/index.mjs";
 import { useTimeout } from "./hooks/timeout/index.mjs";
 import { useWindowResize } from "./hooks/window-resize/index.mjs";
 import { useWindowSize } from "./hooks/window-size/index.mjs";
-export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Direction, Drawer, DropdownMenu, EasyIcon, ErrorBoundary, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, Option, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, Status, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, between, cast, cn, commalize, findAllColors, isInternalRoute, toPrecision, useClickAway, useClient, useClipboard, useHash, useInterval, useLocalStorage, useOpenContext, usePortalRoot, useResize, useScrollDirection, useStep, useTimeout, useToast, useWindowResize, useWindowSize, uuidV4 };
+export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Direction, Drawer, DropdownMenu, EasyIcon, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, Option, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, Status, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, between, cast, cn, commalize, findAllColors, isInternalRoute, toPrecision, useClickAway, useClient, useClipboard, useHash, useInterval, useLocalStorage, useOpenContext, usePortalRoot, useResize, useScrollDirection, useStep, useTimeout, useToast, useWindowResize, useWindowSize, uuidV4 };

package/dist/index.mjs

@@ -62,7 +62,6 @@ import { Popover } from "./components/overlays/popover/popover.mjs";
 import { DropdownMenu } from "./components/overlays/dropdown-menu/dropdown-menu.mjs";
 import { ListBox } from "./components/overlays/list-box/list-box.mjs";
 import { Tooltip } from "./components/overlays/tooltip/tooltip.mjs";
-import { ErrorBoundary } from "./components/utility/error-boundary/index.mjs";
 import { useClient } from "./hooks/client/index.mjs";
 import { useClipboard } from "./hooks/clipboard/index.mjs";
 import { useHash } from "./hooks/hash/index.mjs";
@@ -73,4 +72,4 @@ import { useScrollDirection } from "./hooks/scroll-direction/index.mjs";
 import { useStep } from "./hooks/step/index.mjs";
 import { useWindowResize } from "./hooks/window-resize/index.mjs";
 import { useWindowSize } from "./hooks/window-size/index.mjs";
-export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Drawer, DropdownMenu, EasyIcon, ErrorBoundary, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, between, cast, cn, commalize, findAllColors, isInternalRoute, toPrecision, useClickAway, useClient, useClipboard, useHash, useInterval, useLocalStorage, useOpenContext, usePortalRoot, useResize, useScrollDirection, useStep, useTimeout, useToast, useWindowResize, useWindowSize, uuidV4 };
+export { AIIcon, AccessibilityIcon, Accordion, Alert, AlertIcon, Anchor, ArteOdyssey, ArteOdysseyProvider, AtomIcon, Autocomplete, Avatar, BadIcon, Badge, BaselineStatus, BlogIcon, BoringIcon, Breadcrumb, Button, Card, CheckIcon, Checkbox, CheckboxCard, CheckboxGroup, ChevronIcon, CloseIcon, Code, ColorContrastIcon, ColorInfoIcon, CopyIcon, DarkModeIcon, Dialog, DifficultIcon, Drawer, DropdownMenu, EasyIcon, ExternalLinkIcon, FileField, FormControl, FormIcon, GitHubIcon, GoodIcon, Heading, HistoryIcon, IconButton, IconLink, InformativeIcon, InteractiveCard, InterestingIcon, LightModeIcon, LinkButton, LinkIcon, ListBox, ListIcon, LocationIcon, Logo, LogoIcon, MailIcon, MinusIcon, MixedColorIcon, Modal, NavigationMenuIcon, NewsIcon, NumberField, PaletteIcon, PasswordInput, PlusIcon, Popover, PortalRootProvider, PrepareIcon, Progress, PublishDateIcon, QiitaIcon, RSSIcon, Radio, RadioCard, ScrollLinked, Select, SendIcon, Separator, ShallowIcon, ShieldCheckIcon, Skeleton, SlideIcon, Slider, SparklesIcon, Spinner, SubscribeIcon, Switch, Table, TableIcon, Tabs, TagIcon, TextField, Textarea, ToastProvider, Tooltip, TwitterIcon, UpdateDateIcon, ViewIcon, ViewOffIcon, between, cast, cn, commalize, findAllColors, isInternalRoute, toPrecision, useClickAway, useClient, useClipboard, useHash, useInterval, useLocalStorage, useOpenContext, usePortalRoot, useResize, useScrollDirection, useStep, useTimeout, useToast, useWindowResize, useWindowSize, uuidV4 };

package/docs/GUIDE.md

@@ -0,0 +1,232 @@
+# ArteOdyssey Design Guide
+
+`@k8o/arte-odyssey` デザインシステムを使って UI を作るためのガイド。
+
+## セットアップ
+
+```bash
+npm install @k8o/arte-odyssey
+```
+
+```tsx
+// 1. スタイルシートを読み込む（エントリポイントで1回）
+import '@k8o/arte-odyssey/styles.css';
+
+// 2. Provider でアプリを囲む
+import { ArteOdysseyProvider } from '@k8o/arte-odyssey/providers';
+
+function App() {
+  return (
+    <ArteOdysseyProvider>
+      <YourApp />
+    </ArteOdysseyProvider>
+  );
+}
+
+// 3. コンポーネントを使う
+import { Button } from '@k8o/arte-odyssey/button';
+import { Card } from '@k8o/arte-odyssey/card';
+```
+
+### Tailwind CSS の設定
+
+`@k8o/arte-odyssey` は Tailwind CSS 4 以上が必要。プロジェクトの CSS で以下を追加：
+
+```css
+@import 'tailwindcss';
+@import '@k8o/arte-odyssey/styles.css';
+```
+
+## デザインの方向性
+
+### コアコンセプト
+
+**「静謐で落ち着いた、余白を活かしたUI」**
+
+- **引き算の美学**: 装飾は最小限。必要なものだけ残す
+- **余白で語る**: 詰め込まず、空間にゆとりを持たせる
+- **静かな変化**: アニメーションは控えめに、繊細なフィードバック
+- **穏やかな色**: 目に優しいトーン、グレー系を活かす
+
+### トーン
+
+「図書館の読書スペース」のような空気感。静かで集中できる、心地よい緊張感。
+
+## 美学ガイドライン
+
+### タイポグラフィ
+
+**DO:**
+
+- 日本語フォント（Noto Sans JP, M PLUS 2）を使う
+- フォントウェイトは 3種類まで（`font-normal`, `font-medium`, `font-bold`）
+- `font-medium` が 450（一般的な 500 より軽い）であることを活かした繊細な強調
+
+**DON'T:**
+
+- Inter / Roboto / Open Sans を使う
+- 4種類以上のフォントサイズを1画面で使う
+- テキストにグラデーションをかける
+
+> [タイポグラフィ詳細](references/typography.md)
+
+### カラー
+
+**DO:**
+
+- 60-30-10 ルール（ニュートラル60%, サポート30%, アクセント10%）
+- セマンティックカラートークンを使う（`bg-bg-subtle`, `text-fg-mute` 等）
+- ダークモードを独立したトーンで設計する
+
+**DON'T:**
+
+- グラデーション背景
+- ホバーに `bg-primary-bg` — `bg-bg-mute` を使う
+- 透明度(`/90`)で状態表現 — 専用トークンを使う
+- 生のカラー値（`bg-teal-500`）— セマンティックトークン（`bg-primary-bg`）を使う
+
+> [カラー詳細](references/color.md)
+
+### スペーシング
+
+**DO:**
+
+- `p-6` を標準パディングとする
+- 余白の差で関連度を表す（`mt-2` 近い、`mt-4` 標準、`mt-8` セクション間）
+- Separator でセクションを区切る
+
+**DON'T:**
+
+- すべてを Card に入れる
+- Card を入れ子にする（Card in Card）
+- `gap-1` のような極端に狭いスペーシング
+
+> [スペーシング詳細](references/spatial-design.md)
+
+### インタラクション
+
+**DO:**
+
+- `transition-colors` を基本にする
+- `focus-visible:ring-2 focus-visible:ring-border-info` でフォーカス表現
+- `hover:bg-bg-mute` で穏やかなホバー
+
+**DON'T:**
+
+- bounce / spring 系のイージング
+- 300ms を超えるアニメーション
+- ホバーに強い原色を使う
+
+> [インタラクション詳細](references/interaction-design.md)
+
+## コンポーネント使用の原則
+
+### Button / LinkButton
+
+`color` と `variant` で統一されたスタイル。
+
+```tsx
+import { Button } from '@k8o/arte-odyssey/button';
+import { LinkButton } from '@k8o/arte-odyssey/link-button';
+
+// プライマリアクション
+<Button color="primary" variant="contained">保存する</Button>
+
+// セカンダリアクション
+<Button color="gray" variant="outlined">キャンセル</Button>
+
+// テキストのみ
+<Button variant="skeleton">詳細を見る</Button>
+
+// リンクボタン（同じ props）
+<LinkButton href="/settings" color="gray">設定へ</LinkButton>
+```
+
+### IconButton / IconLink
+
+`bg` prop でスタイルを制御（`variant` ではない）。
+
+```tsx
+import { IconButton } from '@k8o/arte-odyssey/icon-button';
+import { IconLink } from '@k8o/arte-odyssey/icon-link';
+
+<IconButton bg="transparent" label="コピー"><CopyIcon /></IconButton>
+<IconButton bg="primary" label="送信"><SendIcon /></IconButton>
+<IconLink href="/home" bg="base" label="ホーム"><HomeIcon /></IconLink>
+```
+
+### Card / InteractiveCard
+
+`appearance` prop でシャドウかボーダーかを選択。
+
+```tsx
+import { Card, InteractiveCard } from '@k8o/arte-odyssey/card';
+
+// 静的カード
+<Card title="設定" appearance="bordered">
+  <p>カードのコンテンツ</p>
+</Card>
+
+// クリック可能なカード（ホバーでスケールアップ）
+<InteractiveCard title="記事" appearance="shadow">
+  <p>コンテンツ</p>
+</InteractiveCard>
+```
+
+### フォーム
+
+```tsx
+import { TextField } from '@k8o/arte-odyssey/text-field';
+import { Select } from '@k8o/arte-odyssey/select';
+import { FileField } from '@k8o/arte-odyssey/file-field';
+
+<TextField id="email" placeholder="example@mail.com" />
+
+<Select
+  label="カテゴリ"
+  options={[{ value: '1', label: 'オプション1' }]}
+  value={value}
+  onChange={onChange}
+/>
+
+<FileField.Root accept="image/*" multiple>
+  <FileField.Trigger>ファイルを選択</FileField.Trigger>
+  <FileField.ItemList />
+</FileField.Root>
+```
+
+## アンチパターン: 「AI スロップ」を避ける
+
+AI が生成したと一目でわかるUIの特徴を避ける。
+
+| アンチパターン                 | ArteOdyssey での代替                               |
+| ------------------------------ | -------------------------------------------------- |
+| パープルグラデーション         | Teal/Cyan のフラットカラー                         |
+| Card in Card（入れ子カード）   | Separator + 余白で区切り                           |
+| グレー背景にグレーテキスト     | `text-fg-base` / `text-fg-mute` のコントラスト確保 |
+| すべてに `rounded-2xl`         | `rounded-lg` を基本、用途で使い分け                |
+| bounce / spring アニメーション | `transition-colors duration-150 ease-out`          |
+| Inter フォント                 | Noto Sans JP / M PLUS 2                            |
+| 過剰な glassmorphism           | border + subtle な背景色                           |
+| 装飾的な絵文字やアイコン       | lucide-react の線画アイコンを控えめに              |
+| 情報の詰め込み                 | 余白を活かした疎な配置                             |
+
+### AI スロップテスト
+
+> このUIを誰かに見せて「AIが作った」と言ったら、すぐに信じるだろうか？
+> もし「はい」なら、それが問題だ。
+
+## 実装の原則
+
+- **既存コンポーネントを使う**: カスタムUIの前にまず ArteOdyssey コンポーネントを探す
+- **セマンティックトークンを使う**: 生のカラー値（`bg-teal-500`）ではなくトークン（`bg-primary-bg`）
+- **ダークモードを忘れない**: セマンティックトークンを使えば自動対応
+- **アクセシビリティ**: `aria-label`, キーボードナビゲーション, カラーだけに頼らない状態表現
+
+## 詳細リファレンス
+
+- タイポグラフィ: [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)

package/docs/references/color.md

@@ -0,0 +1,86 @@
+# カラーシステム
+
+ArteOdyssey のカラーは「穏やかさ」を第一に設計されている。
+
+## 設計思想
+
+- **60-30-10 ルール**: 60% ニュートラル（グレー系）、30% サポート（bg-subtle 等）、10% アクセント（primary/secondary）
+- Primary に Teal、Secondary に Cyan を使用
+- ダークモードは「ライトモードの反転」ではなく、独立したトーンで設計
+- セマンティックトークンを使えばダークモードは自動対応
+
+## セマンティックカラー（前景）
+
+| 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-700   | blue-300   | 情報             |
+| `text-fg-success` | green-700  | green-300  | 成功             |
+| `text-fg-warning` | yellow-700 | yellow-300 | 警告             |
+| `text-fg-error`   | red-700    | red-300    | エラー           |
+
+## セマンティックカラー（背景）
+
+| 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    | 反転背景         |
+
+## セマンティックカラー（ボーダー）
+
+| 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 | 強調ボーダー   |
+
+## ブランドカラー（Primary: Teal）
+
+| Tailwind クラス         | Light    | Dark     | 用途                |
+| ----------------------- | -------- | -------- | ------------------- |
+| `text-primary-fg`       | teal-700 | teal-300 | Primary テキスト    |
+| `bg-primary-bg`         | teal-300 | teal-700 | Primary 背景        |
+| `bg-primary-bg-subtle`  | teal-100 | teal-900 | 薄い Primary 背景   |
+| `bg-primary-bg-mute`    | teal-200 | teal-800 | 控えめ Primary 背景 |
+| `border-primary-border` | teal-600 | teal-600 | Primary ボーダー    |
+
+## ブランドカラー（Secondary: Cyan）
+
+| 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-base border border-border-mute rounded-lg p-6">
+  <h2 className="text-fg-base font-bold">タイトル</h2>
+  <p className="text-fg-mute mt-2">補足テキスト</p>
+  <span className="text-primary-fg">アクセントテキスト</span>
+</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`）— セマンティックトークンを使う
+- ダークモードで単純にカラーを反転させる

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` を日本語テキストに適用する
+- テキストにグラデーションをかける
+- フォントサイズだけで階層を作る（余白も活用する）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8o/arte-odyssey",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "k8o's react ui library",
   "keywords": [
     "components",
@@ -20,7 +20,8 @@
     "url": "git+https://github.com/k35o/ArteOdyssey.git"
   },
   "files": [
-    "dist/**"
+    "dist/**",
+    "docs/**"
   ],
   "type": "module",
   "sideEffects": [
@@ -45,7 +46,6 @@
     "clsx": "2.1.1",
     "lucide-react": "0.577.0",
     "motion": "12.36.0",
-    "react-error-boundary": "6.1.1",
     "tailwind-merge": "3.5.0"
   },
   "devDependencies": {

package/dist/components/utility/error-boundary/index.d.mts

@@ -1,2 +0,0 @@
-import { ErrorBoundary } from "react-error-boundary";
-export { ErrorBoundary };

package/dist/components/utility/error-boundary/index.mjs

@@ -1,2 +0,0 @@
-import { ErrorBoundary } from "react-error-boundary";
-export { ErrorBoundary };