@1dot5/design-assistant 0.2.1

package/.claude/skills/component-architect/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: component-architect
+description: コンポーネントの責務分割、props/バリアント設計、置き場の判断（packages/ vs _components/）を扱う。コンポーネント分解や再利用境界を議論するときに発火。
+user-invocable: false
+metadata:
+  tags: components, architecture, props, variants, composition, shadcn
+---
+
+# Component Architect Skill
+
+責務分割・props 設計・バリアント・置き場判断の規約。
+
+## When to Apply
+
+次のような会話で発火する：
+
+- コンポーネント分解、責務分割、再利用境界、props 設計、バリアント設計
+- Component decomposition, props design, variants, composition, component boundaries
+- shadcn/ui のコンポーネントを拡張・カスタマイズするとき
+- `packages/` に置くか `_components/` に置くか迷ったとき
+
+## Core Principles
+
+1. **責務は 1 つ**。複数の関心を持ったら分ける
+2. **迷ったら `_components/` に置く**。2 箇所目の利用が出てから `packages/` へ昇格
+3. **Boolean prop の羅列は state machine のサイン**。`status: 'idle' | 'loading' | 'error'` に集約
+
+## 置き場の判断
+
+`tenpct/frontend-template` の配置ルールに従う。
+
+| 配置 | 用途 | 判断基準 |
+|---|---|---|
+| `packages/` | アプリ横断の共通 UI（shadcn/ui ベース） | 2 アプリ以上で使う / プリミティブに近い |
+| `src/app/{route}/_components/` | そのページでしか使わないコンポーネント | 特定ルートに強く結びつく |
+| `src/hooks/` | アプリ全体で使うカスタムフック | ロジックの再利用 |
+| `src/store/` | グローバルな UI 状態（Zustand） | 複数コンポーネント間で共有する UI 状態 |
+| `src/api/` | API クライアント関数・GraphQL 定義 | |
+
+**迷ったら `_components/` に置く**。横断利用が 2 箇所目で出てきてから `packages/` に昇格させる。早期共通化は害。
+
+## コンポーネント分解の判断軸
+
+1. **責務は 1 つ**。複数の関心を持ったら分ける
+2. **状態とプレゼンテーションを分ける**。ロジックは hook、表示は component
+3. **データ取得は境界を明確に**。Suspense + Error Boundary で包む単位がコンポーネント境界
+4. **props で制御するか、children で渡すか**
+   - 構造が固定なら props（variant, size, disabled）
+   - 構造が可変なら children / slot（Radix の Composition パターン）
+
+## Props 設計
+
+- **バリアントは CVA (class-variance-authority) で定義**。shadcn/ui 準拠
+- **必須 props は最小に**。デフォルト値を持てるものは optional
+- **Boolean prop の羅列を避ける**（`isLoading && isDisabled && isError` → `status: 'loading' | 'error' | 'idle'`）
+- **on* ハンドラは動詞で命名**（`onSubmit`, `onSelect`）
+- **data prop は型を狭く**。GraphQL codegen の型を使う
+
+## 状態の扱い
+
+全コンポーネントで以下を必ず定義：
+
+- `default` / `hover` / `active` / `focus` / `focus-visible` / `disabled`
+- データ系: `loading` / `empty` / `error` / `success`
+- 権限系: `no-permission`（該当時）
+
+**状態の表現手段の優先順位**：
+
+1. ネイティブ属性（`disabled`, `aria-pressed`, `aria-expanded`）
+2. data 属性（`data-state="open"` など、Radix 慣習）
+3. クラス名での切り替え
+
+## バリアント設計
+
+- **バリアント軸は直交させる**（`variant` × `size` × `tone`）
+- **軸が 3 本を超えたら分割を検討**。複雑すぎるコンポーネントは分ける兆候
+- **size は spacing scale と連動**（sm/md/lg を勝手に増やさない）
+
+## Composition パターン（Radix 流）
+
+構造が可変な場合は複合コンポーネントで提供：
+
+```tsx
+<Card>
+  <Card.Header>...</Card.Header>
+  <Card.Body>...</Card.Body>
+  <Card.Footer>...</Card.Footer>
+</Card>
+```
+
+- 各サブコンポーネントは単体でも意味を持つ
+- props drilling を避けられる
+- shadcn/ui の多くがこのパターン
+
+## Form コンポーネント
+
+- React Hook Form + Zod 前提
+- `<Label htmlFor>` と `<Input id>` を必ず紐付ける
+- エラーは `aria-describedby` で関連付け
+- placeholder を label 代わりにしない
+
+## 判断フロー
+
+```
+このコンポーネントは何の責務を持つか？
+├── 複数 → 分解する
+└── 1 つ
+    ├── 2 箇所以上で使う？
+    │   ├── Yes → packages/ に昇格候補
+    │   └── No  → _components/ に置く
+    └── 構造は可変か？
+        ├── Yes → Composition (children / slot)
+        └── No  → Props (variant, size, tone)
+```
+
+## Output Format
+
+1. コンポーネントの責務（1 文で）
+2. 置き場の判断と理由
+3. Props インタフェース（型定義）
+4. バリアント設計（CVA の軸）
+5. Composition / Slot 構造（必要な場合）
+6. 状態の列挙
+7. 依存するプリミティブ（Radix / shadcn）
+
+## よくある失敗
+
+- 早すぎる共通化（`packages/` に入れたが横展開されない）
+- Boolean prop の爆発（`isLoading`, `isDisabled`, `isError` を並べる）
+- コンポーネント内部でデータ取得と表示を混ぜる（テスト困難・再利用不可）
+- 状態を `useState` で個別管理（本当は 1 つの state machine）
+- バリアント軸が増えすぎて CVA が読めない
+
+## 参照
+
+- コードへの翻訳：`design-to-code` skill
+- 配置ルール：`frontend-architecture` skill
+- チェックリスト：[.agent/review.md](../../../.agent/review.md)
+
+設計が決まったら `design-to-code` skill で実装へ、配置は `frontend-architecture` skill で確認。

package/.claude/skills/design-review/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: design-review
+description: デザイン・実装レビューの観点、アクセシビリティ、最終チェックリスト。全 skill の Checklist が参照する集約ドキュメント。レビューや最終確認、a11y 観点の確認時に発火。
+user-invocable: false
+metadata:
+  tags: review, accessibility, checklist, wcag, a11y, quality
+---
+
+# Design Review Skill
+
+全 skill の Checklist が参照する集約ドキュメント。レビュー観点・アクセシビリティ・最終チェックリストをまとめる。
+
+## When to Apply
+
+次のような会話で発火する：
+
+- UI / 実装のレビュー、最終チェック、納品前確認
+- アクセシビリティ（WCAG / a11y）の観点確認
+- 状態網羅（loading / error / empty / disabled）の確認
+- 「この画面 / コンポーネントで見落としていない？」の問いかけ
+
+## 最終チェックリスト
+
+### 仕様・状態
+
+- [ ] ユースケースの正常系・分岐系・異常系・中断系すべてに画面がある
+- [ ] 全コンポーネントの状態が定義されている
+  - [ ] default / hover / active / focus / focus-visible / disabled
+  - [ ] loading / empty / error / success / no-permission
+- [ ] 長文（2 倍の長さ）で崩れない（wrap / ellipsis / max-width）
+- [ ] 0 件表示がある
+- [ ] ネットワーク失敗時の表示がある
+- [ ] 遅延（3 秒以上）で loading / skeleton が出る
+
+### 視覚・レイアウト
+
+- [ ] 情報階層が色のみに依存していない（サイズ・位置・余白・タイポで序列）
+- [ ] 幅配分（primary / secondary / tertiary）が意図的に設計されている
+- [ ] 基準線が通っている（崩すなら意図的に）
+- [ ] トークン参照で生値がハードコードされていない（色・余白・radius・typography）
+- [ ] Tailwind クラスに生 px / 生 hex がない
+
+### レスポンシブ / デバイス対応
+
+- [ ] ナロービューポート 360px 幅で破綻しない
+- [ ] タップターゲットが 44×44 以上
+- [ ] Hover 前提の UI ではない（タッチデバイス考慮）
+- [ ] Primary Action がモバイルで親指到達圏にある
+- [ ] 画像がアスペクト比を保つ
+
+### アクセシビリティ（WCAG AA 準拠を基準）
+
+#### セマンティクス
+- [ ] ネイティブ要素を優先（`button`, `a`, `label`, `input`）
+- [ ] 見出し階層が飛んでいない（h1 → h2 → h3）
+- [ ] ランドマーク（`header`, `nav`, `main`, `footer`）がある
+- [ ] リストは `ul/ol/li`、定義は `dl/dt/dd`
+
+#### 名前とラベル
+- [ ] すべての `button` / `a` / `input` に accessible name がある
+- [ ] アイコンのみのボタンに `aria-label` がある
+- [ ] `label` と `input` が `for` / `id` で紐づいている
+- [ ] placeholder を label 代わりにしていない
+
+#### キーボード
+- [ ] キーボードのみで全機能が完結する
+- [ ] Tab 順が DOM 順で論理的
+- [ ] `tabindex` で無理に順序を変えていない
+- [ ] focus が可視（`focus-visible` を消していない）
+- [ ] モーダル / ドロワー：開で focus 移動 / 閉で復帰 / focus trap
+
+#### 状態伝達
+- [ ] ネイティブ `disabled` を優先、必要時のみ `aria-disabled`
+- [ ] トグルは `aria-pressed` / `aria-expanded`（必要時のみ）
+- [ ] 非同期完了 / 失敗は `aria-live`（濫用しない）
+- [ ] エラーは「何が・なぜ・どう直すか」を説明
+
+#### 色・コントラスト
+- [ ] コントラスト比：本文 4.5:1 以上、大文字 3:1 以上
+- [ ] フォーカスリングとの対比も十分
+- [ ] 色覚多様性で判別できるか（色 + 形 / テキスト）
+
+#### 画像・メディア
+- [ ] `alt` が目的ベース（装飾は `alt=""`）
+- [ ] 動画 / 音声：コントロール・字幕 / 文字起こし
+
+### 実装品質
+
+- [ ] Server / Client 境界が適切（Client は葉に寄せる）
+- [ ] 早期共通化していない（1 箇所でしか使われない部品を `packages/` に置いていない）
+- [ ] ロジックと表示が分離されている（hook / component）
+- [ ] Boolean prop の羅列になっていない（state / status に集約）
+- [ ] `tailwind-merge` で衝突を解消している
+- [ ] TanStack Query に UI 状態を入れていない
+- [ ] Zustand にサーバーデータを入れていない
+
+## レビュー時の問いかけ
+
+UX レビューを依頼されたら、以下を順に問う：
+
+1. **どこで失敗しているか？**（ステップ / 画面 / 操作）
+2. **何ができないか？**（理解 / 判断 / 操作 / 入力 / 待機）
+3. **誰が困っているか？**（初心者 / エキスパート / 支援技術ユーザー / 低速回線）
+4. **成功の定義は？**（完了率・所要時間・エラー率・満足度）
+
+## 認知負荷の観点
+
+- **現在の文脈を壊さない**：急な画面遷移 / 情報欠落 / モーダル濫用を避ける
+- **エラーを予防**：入力制約 / 即時フィードバック / 適切なデフォルト
+- **記憶させない**：選ばせるのではなく見せる（recognition over recall）
+- **操作の一貫性**：同じものは同じように振る舞う
+
+## アンチパターン
+
+- `div` に `onClick` を付けてボタン代わり（キーボード / ロール破綻）
+- `role="button"` でごまかす（`button` を使う）
+- `aria-label` を可視テキストがあるのに追加（二重読み上げ）
+- focus リングを消す（見えない focus = 操作不能）
+- 状態を色だけで表現（色弱ユーザーで判別不能）
+- 「ユーザーが慣れる」前提で初回の迷いを無視
+- エラー文が抽象的で次の行動に導けない

package/.claude/skills/design-to-code/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: design-to-code
+description: デザイン（Pencil/Figma/モック）をコードに翻訳する判断軸。Tailwind CSS v4 + shadcn/ui 前提。意図の翻訳、px→scale、margin→gap、状態=仕様を扱う。
+user-invocable: false
+metadata:
+  tags: design-to-code, implementation, tailwind, shadcn, responsive, translation
+---
+
+# Design to Code Skill
+
+Pencil / Figma / モックからコードへ落とす際の規約。Tailwind CSS v4 + shadcn/ui 前提。
+
+## When to Apply
+
+次のような会話で発火する：
+
+- デザインから実装、Figma から実装、Pencil から実装、モックから実装
+- Design to code, Figma to code, Pencil to code, mockup to code, implementation
+- UI の崩れ修正、レスポンシブ対応、スタイル調整
+- shadcn/ui や Tailwind v4 でコンポーネントを書くとき
+
+## Core Principles
+
+- **ピクセル一致ではなく、比率・整合・耐性・一貫性を保つ**
+- **transcribe（書き写し）ではなく translate（翻訳）**。デザインの px 値は参照、実装はスケール・比率・構造
+- **固定値は例外**。使うなら理由を明示（仕様要件 / メディア / タップターゲット等）
+
+## 翻訳プロセス
+
+### 1) 数値より意図を読む
+
+- 目的（この画面で何を理解 / 操作させたいか）
+- 視覚フロー（先に見る → 次 → 最後）
+- 強調（hero / supporting / background）
+- 階層（親子関係、グルーピング）
+- 伸縮意図（Auto Layout / Constraints / Variants）
+- 余白ルール（gap / padding のパターン）
+- アラインメント（何を何に揃えるか）
+- 可変要素（テキスト長、リスト件数、画像比、入力値）
+
+### 2) 実装への変換
+
+| デザイン | 実装 |
+|---|---|
+| `px` 値 | **スケールに丸める**（4/8/12/16/24/32/40/48）→ Tailwind の `gap-4`, `p-6` など |
+| `font-size: 14px` | **役割にマップ**（heading / body / caption）→ `@theme` の `--text-*` トークン |
+| 子要素の margin | **親の `gap` / `padding` に集約**。レイアウト構造（flex / grid）で表現 |
+| 固定 width / height | **制約に変換**（`min-w-*` / `max-w-*` / `overflow-*` / `truncate`）|
+| 幅の設計 | **背景・コンテナ・コンテンツの責務を分離** |
+
+### 3) アラインメント判断
+
+**揃える場面**：
+
+- 繰り返し要素（カード / リスト / フォーム）比較のため
+- 本文コラムを通す視線誘導
+- 情報量が多い画面（設定 / 管理画面）
+
+**崩してよい場面**：
+
+- hero をあえて浮かせる
+- セクション境界の強調
+- 装飾・メディアを主役にする
+
+**崩すときのルール**：
+
+- 基準線を最低 1 本残す
+- オフセットのパターンは 1〜2 に絞る
+- ナロービューポートでは揃える側に寄せる
+
+### 4) 幅の比率を保つ
+
+- **幅配分＝視覚誘導**。primary / secondary / tertiary の列比は意図的
+- **安易に `flex-1` を全部に付けない**。全部等幅は hero を殺す
+- **基準線揃えと幅配分は別軸**。独立して決める
+
+## Tailwind CSS v4 ルール
+
+### トークン（`@theme` で定義）
+
+```css
+@import "tailwindcss";
+
+@theme {
+  --color-brand-500: #0ea5e9;
+  --text-body: 1rem;
+  --radius-card: 0.75rem;
+  --spacing-section: 4rem;
+}
+```
+
+- **色・タイポ・radius・spacing は必ずトークン経由**で参照
+- 生 hex / 生 px をクラス名に書かない
+- 例外は `review.md` のチェックリストに入れて明示
+
+### タイポグラフィ
+
+- サイズは `rem`（または `clamp()`）。`em` は親サイズと関係ある場合のみ
+- `line-height` は単位なし（1.5〜1.7）
+- 本文の可読性：`max-w-[60ch]`
+
+### スペーシング
+
+- スケールに丸める（`gap-4`, `p-6`, `space-y-8`）
+- 子要素に margin を散らさず、親の `gap` / `padding` に寄せる
+
+### レイアウト
+
+- 1 次元：flex、2 次元：grid、間隔：gap
+- `position: absolute` はオーバーレイ・装飾で目的が明確な場合のみ
+- 画像はデフォルトでアスペクト比を保つ（`aspect-[16/9]` 等）
+
+### 固定値の例外
+
+- アイコン・サムネイル・タップターゲット・仕様指定のヘッダー高さ
+- 「崩れ防止」目的でも、まず `min-*` / `max-*` を検討
+
+## shadcn/ui の使い方
+
+- **追加は CLI で**。手動コピペしない
+- **カスタマイズは class 追加か CVA 拡張で**。コアを書き換えない
+- **Radix のプリミティブを理解してから shadcn を使う**。Composition パターンを守る
+
+## 状態の実装（必須）
+
+- default / hover / active / focus / focus-visible / disabled / loading / error / empty
+- 長文・0 件・ネットワーク失敗・遅延を最初から扱う（後付けしない）
+- Tailwind の疑似クラスで表現（`hover:`, `focus-visible:`, `disabled:`, `data-[state=open]:`）
+
+## Output Format
+
+1. 目的（この UI が何を達成するか）
+2. 前提（デザイン入力の種類 / 既存規約 / 制約）
+3. 翻訳結果（階層・アラインメント・余白ルール・可変要素）
+4. 実装方針（レイアウト構造・スケール・例外条件）
+5. 状態設計（default / hover / active / focus / disabled / loading / error / empty）
+6. 実装コード
+7. チェックリスト自己評価（[.agent/review.md](../../../.agent/review.md) 参照）
+
+## よくある失敗
+
+- デザインデータからのピクセル完全一致コピペで、エッジ状態とレスポンシブで壊れる
+- margin 調整が増殖し、保守不能になる
+- 「見た目一致」を優先し、状態（loading / error / empty）が後付けになる
+- Tailwind のクラスに生 px / 生 hex を書き散らす
+- shadcn/ui のコアを書き換えて、アップデート追従不能になる
+
+## 参照
+
+- コンポーネント設計：`component-architect` skill
+- 配置ルール・Server/Client 境界：`frontend-architecture` skill
+- チェックリスト（a11y 含む）：[.agent/review.md](../../../.agent/review.md)

package/.claude/skills/frontend-architecture/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: frontend-architecture
+description: Next.js 16 App Router のディレクトリ設計、Server/Client 境界、TanStack Query + Suspense/Error Boundary、Zustand、キャッシュ戦略。
+user-invocable: false
+metadata:
+  tags: frontend, architecture, nextjs, app-router, tanstack-query, zustand, cache
+---
+
+# Frontend Architecture Skill
+
+`tenpct/frontend-template` 準拠。Next.js 16 App Router を主軸に、配置・境界・データフロー・キャッシュ戦略を定義する。
+
+## When to Apply
+
+次のような会話で発火する：
+
+- ディレクトリ設計、共通化、データフロー、Server/Client 境界、キャッシュ戦略
+- Directory structure, data flow, server/client boundary, cache strategy, state management
+- App Router のページ設計、Suspense/Error Boundary の配置、TanStack Query、Zustand、Form + Zod
+- `packages/` と `_components/` の置き場判断
+
+## Core Principles
+
+1. **Server Component をまず書く**。Client は葉に寄せる
+2. **サーバーデータは TanStack Query、UI 状態は Zustand**。混ぜない
+3. **Suspense + Error Boundary で UI を集約**。`isLoading` / `error` / `data` の三状態手書きを避ける
+
+## 前提スタック
+
+- Next.js 16 App Router + React 19
+- Tailwind CSS v4 / shadcn/ui (Radix)
+- TanStack Query + graphql-request + graphql-codegen
+- Zustand（UI 状態のみ）
+- React Hook Form + Zod
+- Suspense + Error Boundary
+
+## ディレクトリ構成
+
+```
+apps/app/
+└── src/
+    ├── api/                       # API クライアント関数・GraphQL 定義
+    │   └── posts.ts
+    ├── app/                       # Next.js App Router
+    │   ├── layout.tsx
+    │   ├── page.tsx
+    │   ├── globals.css
+    │   ├── providers.tsx          # QueryClientProvider, ErrorBoundary など
+    │   ├── error.tsx              # Root Error Boundary
+    │   ├── global-error.tsx
+    │   ├── not-found.tsx
+    │   ├── loading.tsx
+    │   └── {route}/
+    │       ├── page.tsx
+    │       ├── loading.tsx        # Suspense fallback
+    │       ├── error.tsx          # Error Boundary
+    │       ├── actions.ts         # Server Actions
+    │       └── _components/       # このページ専用
+    ├── hooks/                     # アプリ共通のカスタムフック
+    ├── store/                     # Zustand store（UI 状態のみ）
+    └── utils/
+        └── env.ts                 # t3-env で型安全な env
+```
+
+共通 UI は workspace の `packages/` に定義（shadcn/ui ベース）。
+
+## 配置ルール
+
+| 配置 | 用途 | 判断基準 |
+|---|---|---|
+| `src/app/{route}/_components/` | そのページ専用 | 特定ルートに強く結びつく |
+| `packages/` | 2 アプリ以上で使う共通 UI | プリミティブに近い / shadcn ベース |
+| `src/hooks/` | アプリ全体のフック | ロジックの再利用 |
+| `src/store/` | グローバル UI 状態（Zustand） | 複数コンポーネント間で共有 |
+| `src/api/` | API クライアント・GraphQL 定義 | |
+| `src/utils/` | 副作用のないユーティリティ | |
+
+## Server / Client 境界
+
+### Server Component（デフォルト）
+
+- データ取得・初期レンダリング
+- 認証チェック・リダイレクト
+- Markdown レンダリングなど静的処理
+
+### Client Component（`'use client'` を明示）
+
+- インタラクション（クリック、入力、hover）
+- ブラウザ API（`window`, `localStorage`, `IntersectionObserver`）
+- 状態管理（`useState`, `useReducer`, TanStack Query, Zustand）
+- Context 利用
+
+### 境界の引き方
+
+1. **Server Component をまず書く**。必要になってから Client にする
+2. **Client Component を葉にする**。ツリーの末端に寄せる
+3. **Server → Client に props として渡せるのは serializable なもののみ**
+4. **`_components/` 内は Client が多い**が、Server でも構わない（データ取得を寄せられる場合）
+
+## データ取得戦略
+
+### サーバー側取得
+
+- Server Component 内で直接 `fetch` / GraphQL クライアントを呼ぶ
+- `loading.tsx` / `error.tsx` で Suspense / Error Boundary 境界を張る
+- Server Actions は mutation に限定（書き込み専用）
+
+### クライアント側取得（TanStack Query）
+
+- 操作後の再取得、キャッシュ無効化、楽観的更新が必要な場面
+- `useSuspenseQuery` + 親の Suspense 境界でローディング UI を集約
+- `useMutation` で書き込み → `invalidateQueries` でキャッシュ更新
+- GraphQL は `graphql-request` + `graphql-codegen` で型保証
+
+### 使い分け
+
+| ケース | 方法 |
+|---|---|
+| 初回表示で決まる | Server Component で fetch / GraphQL |
+| 操作後に更新が必要 | TanStack Query + `useMutation` + `invalidateQueries` |
+| 画面間で短時間共有 | TanStack Query（QueryCache） |
+| マスタ系（変更頻度低） | Server Component + `cache` / `'use cache'` |
+
+## エラー処理
+
+### Suspense + Error Boundary で UI を集約
+
+- `isLoading` / `error` / `data` の三状態を手書きしない
+- 親で Suspense / Error Boundary を張り、子は成功系だけ書く
+- `react-error-boundary` の `ErrorBoundary` を活用
+
+### 境界の粒度
+
+- ページ全体：`app/{route}/loading.tsx` / `error.tsx`
+- セクション単位：`<Suspense>` / `<ErrorBoundary>` を手動で張る
+- `packages/query-boundary.tsx` のような共通コンポーネントで Suspense + Error Boundary をまとめて提供
+
+## 状態管理の使い分け
+
+| 種類 | 置き場 |
+|---|---|
+| サーバーデータ（一覧・詳細・マスター） | TanStack Query の QueryCache |
+| フォーム入力 | React Hook Form（ローカル） |
+| URL に乗る状態（検索条件・ページ番号・タブ） | `useSearchParams` ベースの hook |
+| UI 状態（モーダル開閉・サイドバー・テーマ） | Zustand |
+| 純粋な描画内部状態 | `useState` |
+
+**Zustand は UI 状態のみ**。サーバーデータを入れない。
+
+## キャッシュ戦略（Next.js 16）
+
+### サーバー側
+
+| 層 | 用途 | 例 |
+|---|---|---|
+| Request Memoization | 同一リクエスト内の重複 fetch 排除 | 複数コンポーネントが叩く `getUser()` |
+| Data Cache | 変更頻度が低い普遍的データ | マスタ・料金プラン・国コード |
+| Full Route Cache | 描画済み HTML + RSC | 規約・ヘルプ・ダッシュ雛形 |
+| Router Cache | 訪問済みページの即時復元 | 一覧 → 詳細 → 戻る |
+
+### クライアント側
+
+- TanStack Query の QueryCache：操作後の再取得・部分更新・画面間共有
+- `staleTime` / `gcTime` を用途ごとに調整
+
+### Cache Components（Next.js 16）
+
+- `'use cache'` ディレクティブ + `cacheLife` / `cacheTag` / `updateTag` で粒度制御
+- `unstable_cache` からの移行は Vercel 公式ガイド参照
+
+## Form
+
+- React Hook Form + Zod
+- `zodResolver` でバリデーション
+- 送信：Server Action または `useMutation`
+- エラーは `aria-describedby` で関連付け（レビュー観点は `review.md` 参照）
+
+## 環境変数
+
+- `@t3-oss/env-nextjs` で型安全化
+- クライアント公開は `NEXT_PUBLIC_*` のみ、Zod スキーマで検証
+
+## Lint / Format
+
+- ESLint + Prettier（将来 Biome 検討）
+- `eslint-plugin-query` で TanStack Query のアンチパターン検知
+- `prettier-plugin-tailwindcss` でクラス順整列
+
+## Output Format
+
+1. 目的（何を達成するか）
+2. 配置判断（どこに置くか、理由）
+3. Server / Client 境界
+4. データ取得方法（Server or TanStack Query）
+5. 状態管理（Zustand / RHF / URL / useState）
+6. Suspense / Error Boundary の粒度
+7. キャッシュ戦略（必要に応じて）
+
+## よくある失敗
+
+- Server Component で `useState` を使おうとする（境界違反）
+- TanStack Query にサーバーデータではなく UI 状態を入れる
+- Zustand にサーバーデータを入れて TanStack Query と二重管理
+- Suspense 境界が細かすぎて loading が点滅する
+- `'use client'` をツリー上位で付け、ツリー全体が Client になる
+- `packages/` に早期に共通化して、1 箇所でしか使われないまま放置
+
+## 参照
+
+- コンポーネント設計：`component-architect` skill
+- デザイン → コード翻訳：`design-to-code` skill
+- チェックリスト：[.agent/review.md](../../../.agent/review.md)
+- 技術選定の背景：`tenpct/frontend-template` の TECHNICAL-DECISION.md / Framework.md

package/.claude/skills/pencil-design-flow/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: pencil-design-flow
+description: Pencil MCP で .pen ファイルを扱うデザインワークフロー。探索 → 骨格 → 状態 → 書き出しの手順と、変数・コンポーネント運用を定義。.pen を開く/作るときに発火。
+user-invocable: false
+metadata:
+  tags: pencil, design-tool, mcp, workflow, pen-file
+---
+
+# Pencil Design Flow Skill
+
+## When to Apply
+
+次のような会話で発火する：
+
+- .pen ファイルを開く / 作る / 編集する
+- Pencil で画面を作る、コンポーネントを描く、デザインを書き出す
+- Open a .pen file, create a new .pen, design with Pencil, export from Pencil
+
+## Core Principles
+
+1. **.pen は Pencil MCP 経由でのみ読み書き**する。`Read` / `Grep` は使わない（暗号化されている）
+2. **作業前に現在の editor state を確認**する（`get_editor_state`）
+3. **設計は「骨格 → 状態 → 書き出し」の順**。状態定義を飛ばさない
+
+## Process
+
+### 1. 現状把握
+
+- `get_editor_state({ include_schema: true })` で active な .pen と選択状態を確認
+- 新規なら `open_document('new')`、既存なら `open_document(filePath)` を使う
+- 必要に応じて `get_guidelines()` で設計ガイドを読む
+
+### 2. 探索（既存ファイル）
+
+- `batch_get(patterns, nodeIds)` でノードを取得
+- 画面構造・既存コンポーネント・変数（tokens）を把握
+- `search_all_unique_properties` で再利用可能なプロパティを確認
+- `get_variables` で既存のトークンセットを確認
+
+### 3. 骨格を作る
+
+- 情報設計（[.agent/design.md](../../../.agent/design.md)）に従って構造を決める
+- `batch_design` で一括挿入（1 コール最大 25 operations）
+- 繰り返し要素はコンポーネント化（後で `replace_all_matching_properties` で一括更新）
+
+### 4. 状態を定義する
+
+- default / hover / active / focus / disabled / loading / empty / error の各バリアント
+- Pencil の Variants 機能でまとめる
+- 可変要素（テキスト長 / リスト件数 / 画像比）を確認
+
+### 5. トークンを揃える
+
+- 色・余白・typography は `set_variables` でトークン化
+- 生値のハードコードを排除
+- Tailwind v4 の `@theme` に写せる命名（`--color-brand-500`, `--spacing-section`）を意識
+
+### 6. レイアウトスナップショット / 書き出し
+
+- `snapshot_layout` でレイアウト検証
+- `find_empty_space_on_canvas` で新規配置場所を探す
+- `export_nodes` でコード / 画像として書き出す
+- `get_screenshot` で視覚確認
+
+## Output Format
+
+1. 現在の editor state（active 文書・選択）
+2. 情報設計（目的・優先度・構造）
+3. 骨格の構築結果（作成したノードの要約）
+4. 状態定義（各バリアントの存在確認）
+5. トークン一覧（色・余白・typography）
+6. 書き出し結果 or 次ステップ
+
+## Pencil へのプロンプト設計
+
+Pencil でワイヤー/UI を生成させるときは、次の構造でプロンプトを渡すと精度が上がる。
+
+```
+[コンテキスト] 誰が、いつ、何のために使う画面か
+[ゴール] この画面で達成したい成果
+[必須要素] 表示すべき情報・アクション
+[制約] デバイス、文字数、既存 UI との整合
+[除外] 含めないもの（重要）
+```
+
+**「除外」を明記する**ことで、AI 特有の「過剰な親切」を抑制できる。
+
+## フェーズ間を一気に飛ばさない
+
+Pencil はワイヤー→ローファイ→ハイファイの変換を一気に行えるが、**各フェーズで検証すべき問いに答え切ってから次へ**進む（フェーズの目的については `ui-designer` を参照）。
+
+- **ワイヤー → ローファイ**: 色数を最小（グレースケール + 1 アクセント）に絞って生成。レイアウトの骨格を先に確定
+- **ローファイ → ハイファイ**: ブランドトークン（色・タイポ・角丸・影）を事前に Pencil に渡す。**スタイルの一貫性は AI ではなく人間の設計で固定する**
+
+AI に任せてよいのは「適用」であり、「決定」ではない。
+
+## AI でコンポーネントを扱うときの注意
+
+- **AI が生成した UI を、そのまま「新規コンポーネント」にしない**。必ず既存システムに照らし「既存で表現できないか」を先に確認
+- **AI は「それっぽいもの」を返す**。軸の直交性・誤用防止・状態網羅は人間が確認
+- **トークンを参照したコードを生成させる**。生の HEX / px が紛れ込んだらレビューで落とす
+- **Pencil のライブラリに取り込む前**に、`component-architect` の設計過程を踏む。設計のない登録はコンポーネントシステムの汚染
+
+## よくある失敗
+
+- `Read` / `Grep` で .pen を読もうとする（暗号化のため不可）
+- `get_editor_state` を省略して状態不明のまま操作する
+- `batch_design` のオペレーション構文を間違える（tool description を必ず確認）
+- 状態定義（hover / error / empty）を Variants 化せず、別ノードで複製する
+- 生値をトークン化せず、後からの一括変更ができなくなる
+- フェーズを飛ばして一気にハイファイまで生成させる
+- AI 生成物をそのままライブラリ化する
+
+## 参照
+
+- 情報設計・視覚階層・コンポーネント設計の判断軸：`ui-designer` skill / [.agent/design.md](../../../.agent/design.md)
+- コンポーネントの責務分割・配置：`component-architect` skill
+- チェックリスト：[.agent/review.md](../../../.agent/review.md)
+- Pencil MCP ツール定義は会話中の MCP 指示に従う（`batch_design` の構文を必ず守る）

package/.claude/skills/ui-designer/SKILL.md

@@ -0,0 +1,380 @@
+---
+name: ui-designer
+description: 画面・コンポーネント設計、情報設計、視覚階層、状態定義を扱う判断軸。Web とモバイル両対応が前提。画面の骨格を議論するときに発火。
+user-invocable: false
+metadata:
+  tags: ui, design, information-architecture, visual-hierarchy, components, states
+---
+
+# UI Designer Skill
+
+シニアデザイナーとして、UI を「見た目の調整」ではなく **「制約の中での意思決定の連続」** として扱うための判断軸をまとめる。速度の出る AI 支援環境では、**思考の順序を守る規律**こそが差を作る。
+
+## When to Apply
+
+次のような会話で発火する：
+
+- 画面設計、UI 方針、情報設計、視覚階層、画面の骨格、状態定義、トーン&マナー
+- UI/screen design, information architecture, visual hierarchy, layout structure, state design
+- 新規画面の起案、既存画面の再設計、デザインシステムの方針議論
+- コンポーネントの責務分割・バリアント設計（詳細な配置判断は `component-architect` へ委譲）
+
+## 基本姿勢（Senior Principles）
+
+1. **問題定義を飛ばさない**。美しい UI は正しい問題定義の後にしか成立しない
+2. **制約を味方にする**。技術・スケジュール・ブランド・a11y — 制約が設計の輪郭を作る
+3. **意思決定の根拠を言語化する**。「なんとなく良い」は再現性がなくチームで再利用できない
+4. **一貫性 > 個別最適**。個別画面の完成度よりプロダクト全体の整合性
+5. **早く・安く・間違える**。ハイファイで検証するのは最も高くつく失敗の仕方
+
+---
+
+## 1. ユースケース → ワイヤーフレーム
+
+### 1.1 まず「誰が・いつ・なぜ・何を」を定義
+
+画面を描き始める前に必ず言語化する：
+
+- **Who（主体）**: ペルソナではなく **役割と状況**。「30代女性」ではなく「繁忙期にチェックイン業務を兼務するフロント担当」
+- **When（文脈）**: 利用タイミング・デバイス・同時作業・時間的余裕
+- **Why（動機）**: 機能ではなく成果（Job to be Done）で記述
+- **What（入出力）**: 画面に持ち込む情報／持ち出したい情報
+
+### 1.2 シナリオ展開 — 正常系だけで止めない
+
+- **正常系**: 最短距離で成功するパス
+- **分岐系**: 選択・入力を要するパス
+- **異常系**: エラー、入力不正、通信失敗、権限不足
+- **中断系**: 離脱して戻ってくるパス（下書き保存、セッション切れ）
+
+ジュニアとの差が最も出るのは **異常系と中断系の解像度**。正常系だけワイヤーにすると実装フェーズで仕様が崩壊する。
+
+### 1.3 情報の優先順位を 1 つ決める
+
+画面で **最も重要な情報・アクションを 1 つ**選ぶ。複数選びたくなったら、画面がまだ 1 つにまとまっていない兆候。分割を検討する。
+
+> 一画面一目的。破るときは破る理由を明記する。
+
+### 1.4 ワイヤーの粒度
+
+- **箱と文字のみ**。色・フォント・アイコンは不要
+- **実データに近いダミーテキスト**。Lorem ipsum は日本語プロダクトで文字数感覚を歪めるため避ける
+- **画面単位ではなく遷移単位で描く**。単体の良し悪しは遷移の中でしか評価できない
+
+---
+
+## 2. ワイヤー → ローファイ → ハイファイ
+
+### 2.1 フェーズの目的を混同しない
+
+| フェーズ | 検証するもの | 避けるべき議論 |
+|---|---|---|
+| ワイヤー | 情報構造と遷移の妥当性 | 色、余白、書体 |
+| ローファイ | レイアウトと操作感の骨格 | ブランド表現、細部の装飾 |
+| ハイファイ | 最終的な視覚品質と実装整合 | 情報構造のやり直し |
+
+**フェーズを戻ることは敗北ではなく、早期発見の成功**。ただし各フェーズの問いに答え切らずに次へ進むと、手戻りコストは指数関数的に増える。
+
+### 2.2 ローファイで確定させること
+
+- グリッド（8pt / 4pt ベース）
+- ブレークポイントごとのレイアウト骨格
+- タイポグラフィの階層（H1-H6、body、caption、label）
+- スペーシングのスケール（4, 8, 12, 16, 24, 32, 48, 64 ...）
+- インタラクションの大枠（hover / focus / press / disabled）
+
+この段階で「何をコンポーネント化するか」のあたりをつける。
+
+### 2.3 ハイファイへ進む条件
+
+次に Yes と答えられるまで進まない：
+
+- 主要ユースケースの遷移を通しで操作できる（クリッカブルプロトタイプ）
+- 異常系・中断系の画面がローファイで存在
+- ステークホルダーから「情報構造」への合意
+- エンジニアから「実装上の致命的な問題はない」
+
+---
+
+## 3. UI デザインの考え方
+
+### 3.1 評価軸（優先順）
+
+1. **理解可能性**: 初見で何の画面か、何ができるか把握できる
+2. **操作可能性**: 次のアクションが明確でタップ/クリック可能なサイズ
+3. **予測可能性**: プロダクト内で似た要素は似た挙動をする
+4. **回復可能性**: 誤操作から戻れる、やり直せる
+5. **美しさ・らしさ**: ブランドとトーン（上記 4 つの後）
+
+この順序を逆にした瞬間、UI は「飾られた迷路」になる。
+
+### 3.2 視線誘導とレイアウト
+
+- Z 型 / F 型は今も有効。ただし **モバイルでは縦一列の重み付けが支配的**
+- **余白はコンテンツである**。空けることで情報を際立たせる
+- **コントラストは色ではなくサイズ・ウェイト・位置で作る**。色に頼ると色覚多様性やダークモードで破綻
+
+### 3.3 色
+
+- **セマンティックカラー**を定義（primary / secondary / success / warning / danger / info / neutral）。生 HEX を直接使わない
+- 色は **意味の伝達**に使う。装飾で使うときは意味転用の可能性を常に考える
+- **WCAG AA（4.5:1）最低基準、AAA（7:1）推奨**
+- **ダークモードは明度反転ではない**。影・コントラストの再設計を要する
+
+### 3.4 タイポグラフィ
+
+- 書体は **2 つまで**を原則とする。3 つ目には明確な理由を書く
+- **日本語と英数字のバランス**を個別に検証。和文と欧文で最適なウェイト・サイズは異なる
+- 行間 1.5〜1.75（本文）、字間はフォントが持つ値を尊重
+
+### 3.5 状態の網羅（ハイファイで抜けは未完成）
+
+- default / hover / focus / active / selected / disabled
+- loading / empty / error / success
+- 入力あり / 入力なし / バリデーションエラー
+
+### 3.6 アクセシビリティ
+
+- **タップ領域 44×44pt 以上**（モバイル）、24×24px 以上（デスクトップ最小）
+- **キーボード操作で全機能が完結**
+- **フォーカスリングを消さない**。消したくなったらデザインし直す（`:focus-visible` で解決）
+- **スクリーンリーダー向けのラベル・ランドマーク**を設計時点で考える（実装任せにしない）
+
+### 3.7 マイクロインタラクション
+
+- **意味のないアニメーションは入れない**。アニメーションはフィードバックの言語
+- **200〜300ms を基本**。100ms 未満は気づかれず、500ms 超は遅い
+- **ease-out を第一候補**に。等速は機械的、ease-in は遅く感じる
+
+---
+
+## 4. コンポーネント設計の判断軸
+
+詳細な配置・CVA・shadcn 拡張は `component-architect` に委譲する。本セクションではデザイン側の判断軸をまとめる。
+
+### 4.1 難しいのは作ることではなく判断
+
+1. **いつ作るか**（早すぎると抽象化を間違える）
+2. **どこで線を引くか**（責務の境界）
+3. **何を公開し、何を隠すか**（Props）
+4. **どう変化を吸収するか**（未来の要求変更）
+5. **どう使わせないか**（誤用を構造的に防ぐ）
+
+### 4.2 いつ作るか — Rule of Three とその例外
+
+基本は **Rule of Three**: 2 回目までは複製、3 回目で抽象化。早すぎる抽象化は間違った抽象化を生む。
+
+**例外的に最初から作る**：
+
+- Button / Input / Select / Checkbox / Radio 等の普遍的プリミティブ
+- タイポグラフィ・スペーシングのトークン
+- レイアウト骨格（Container / Stack / Grid）
+
+**早まって作らない**：
+
+- 「たぶんまた使う」程度の確信度のもの
+- ユースケースが 1 つしかない「それっぽい」塊
+- ブランドトーンが固まる前の装飾要素
+
+> 迷ったら作らない。コピペの重複は発見できるが、間違った抽象化は発見されないまま広がる。
+
+### 4.3 分けるか、まとめるか
+
+**分けるべきサイン**：
+
+- 見た目が違う × 意味も違う
+- Props の分岐（`if (type === 'A')`）がコンポーネント内を支配している
+- 使う側が「この Props はこのときだけ」を考え始めている
+- a11y 要件が異なる（Dialog と Popover の ARIA は別物）
+
+**まとめるべきサイン**：
+
+- 差分が Props で素直に表現できる
+- 分けた結果、両方を常にセットで更新している
+- 命名が「似ているが微妙に違う」形で増殖
+
+**例**：
+
+- Button と IconButton は **別物**（正方形固定、aria-label 必須、ツールバー配置文脈）
+- Modal / Drawer / BottomSheet は **共通 Overlay プリミティブ + 3 コンポーネント**（出現方向・閉じ方の慣習・適用文脈が違う）
+
+> 「見た目」で分けず、「意図」で分ける。
+
+### 4.4 Props 設計
+
+Props を足す前に問う 3 つ：
+
+1. 本当にこのコンポーネントの関心事か？（Button に `marginTop` は親の関心事）
+2. この Props がないとユースケースが本当に実現できないか？
+3. 他の Props と組み合わせて矛盾しないか？（`loading` と `disabled` が独立に指定できると両方 true のとき何が起きる？）
+
+**良い Props**：
+
+- **直交している**（`size` / `variant` / `state` が独立軸）
+- **デフォルトが安全**
+- **列挙可能**（`variant="primary"` > `isPrimary`）
+- **Children を活用**（文字列 Props より `children` が柔軟）
+
+**危険なパターン**：
+
+| アンチパターン | 問題 | 代替 |
+|---|---|---|
+| `style`, `className` を何でも受ける | 内部実装依存の上書き | トークン経由、明示的な `tone` / `density` |
+| `renderHeader` などレンダープロップ乱用 | 意味が溶ける | Compound Component |
+| `options` 配列に全て詰める | 型が緩く誤用が増える | 明示的 Props に分解 |
+| ブール値が 5 つ以上 | 状態の組合せ爆発 | 列挙型に統合 |
+
+**Compound Component** は構造で Props 増殖を抑える。ただし Button のような構造固定なコンポーネントには過剰。
+
+```tsx
+// × 肥大化
+<Card title="..." subtitle="..." imageUrl="..." actions={[...]} />
+
+// ○ Compound
+<Card>
+  <Card.Media src="..." />
+  <Card.Header>
+    <Card.Title>...</Card.Title>
+  </Card.Header>
+  <Card.Body>...</Card.Body>
+  <Card.Actions><Button>...</Button></Card.Actions>
+</Card>
+```
+
+### 4.5 Variant 設計 — 軸で寿命が決まる
+
+軸は **直交させる**。Button の典型：
+
+- **Variant（意図）**: primary / secondary / tertiary / danger / ghost
+- **Size（密度）**: sm / md / lg
+- **State**: default / hover / focus / active / disabled / loading
+
+新しい要求で **「新しい軸」を足したくなる誘惑**に耐える。
+
+- 「アイコン付きの Button」→ × `iconPosition` 軸追加 → ○ `children` に `<Icon />`、または別コンポーネント（IconButton）
+
+**命名は意図で**：
+
+- × `blueButton` / `redButton` → 色が変わると破綻
+- ○ `primary` / `danger` → 意図が明確、ブランド変化に耐える
+
+**Variant 数は 5〜7 が上限の目安**。超えそうなら分割または設計見直し。"Everything Button" は一貫性を破壊する。
+
+### 4.6 見落とされやすい状態
+
+**Empty State** はユースケースで分岐する：
+
+- 初回訪問 → オンボーディング誘導
+- 検索結果ゼロ → 条件変更の提案
+- 権限なし → 権限問題の明示
+- エラー起因 → 再試行導線
+
+同じ「空」でも **ユーザーへのメッセージが全く違う**。`EmptyState` コンポーネントで Variant 化する。
+
+**Loading State** は待ち時間で選ぶ：
+
+- 〜1s: スケルトン
+- 1〜3s: スピナー
+- それ以上: 進捗表示
+- 楽観的更新: ローディング表現なし（失敗時のロールバック設計必須）
+
+**Error State** は 3 点を区別：
+
+- 何が起きたか（通信 / 入力 / 権限 / サーバー）
+- ユーザーに責任があるか
+- 回復可能か
+
+**Disabled vs Read-only**：Disabled は「今は操作不可」、Read-only は「そもそも編集不可」。別 Props にする。
+
+**Focus vs Focus-visible**：キーボード時のみ出すには `:focus-visible`。消してはいけない。
+
+### 4.7 誤用を構造的に防ぐ
+
+ドキュメントは読まれない。**読まれなくても正しく使える構造**を作る。
+
+- **型で防ぐ**: 列挙型で制約
+- **構造で防ぐ**: `<Button.Icon />` のように子コンポーネントを専用化
+- **必須を必須にする**: `IconButton` の `aria-label` を型 required に
+- **矛盾を表現不能に**: `{ state: 'default' | 'loading' | 'disabled' }` で独立 boolean の組合せ爆発を防ぐ
+
+### 4.8 トークン設計（3 階層）
+
+- **Primitive**: `color.blue.500`, `space.4` — 生の値
+- **Semantic**: `color.action.primary`, `space.inline.md` — 意味を持つ値
+- **Component**: `button.primary.bg` — コンポーネント固有
+
+命名は **用途で**。`color.brand.blue` ではなく `color.action.primary`（青→緑の変化に耐える）。
+
+粒度は **粗すぎず細かすぎず**。`bg` と `fg`、`default` と `hover` のように **ペアで定義**。
+
+順序は `<category>.<concept>.<variant>.<state>`（`color.surface.raised.hover`）。IDE 補完で category から絞り込めて実装効率が上がる。
+
+> 名前が変わらず、値だけが変わる設計が正しい。
+
+### 4.9 寿命管理
+
+- 使用ゼロ → 削除候補
+- 使用 1〜2 箇所 → 抽象化が早すぎた可能性
+- 使用 10 箇所以上 + Variant 肥大化 → 分割候補
+
+廃止は `Deprecated` マーク → 代替明示 → 移行期間（最低 1 スプリント）→ 削除。
+
+### 4.10 例: Button の設計過程
+
+1. **責務**: クリック/タップでアクションをトリガー（ナビゲーションは Link に分離）
+2. **軸**: Variant（意図）/ Size（密度）/ State
+3. **Props**: `variant` / `size` / `disabled` / `loading` / `type` / `onClick` / `children` / `aria-label`
+4. **判断**:
+   - `iconLeft` / `iconRight` は Props にしない → `children` で `<Icon />` 合成
+   - `fullWidth` は付けない → 幅は親レイアウトの責務
+   - `color` の自由指定は不可 → 一貫性が壊れる
+   - `rounded` は付けない → トークンで統一
+5. **Don't**:
+   - primary を 1 画面に複数置かない
+   - Button の中に Button をネストしない（a11y 違反）
+   - `disabled` はツールチップで理由を示す
+   - Loading 中は多重送信を防ぐ
+
+> 使う側が悩み始めたら設計の失敗。コンポーネントの品質は「使う側の脳の節約量」で測れる。
+
+---
+
+## Process（実運用フロー）
+
+1. **目的を問う**: 画面ゴール / 主ユーザー / primary action / エッジケース / 再利用範囲
+2. **シナリオ展開**: 正常系・分岐系・異常系・中断系
+3. **Web/モバイル両対応を確認**: タップターゲット、hover 非依存、360px 破綻チェック
+4. **情報設計 → 視覚階層 → 状態定義 → コンポーネント化** の順
+5. **仕様は実装者に曖昧さを残さない**形式で書く
+
+## Output Format
+
+1. 画面目的 / 成功基準
+2. ユーザーとユースケース（正常・分岐・異常・中断）
+3. 情報設計（優先度・構造）
+4. コンポーネント提案（責務・props・バリアント・状態）
+5. トークン / スタイル指針（色・余白・タイポ）
+6. エッジ状態の仕様（empty / error / loading / no-permission）
+7. 次アクション（プロトタイプ → 実装）
+
+## 納品前チェックリスト
+
+- [ ] 正常系・分岐系・異常系・中断系すべてに画面がある
+- [ ] 情報階層が色に依存していない
+- [ ] 全コンポーネントの状態（default / hover / focus / active / disabled / loading / empty / error）が定義
+- [ ] コントラスト比が WCAG AA 以上
+- [ ] タップ領域 44×44pt 以上
+- [ ] キーボード操作で全機能が完結
+- [ ] トークン参照（生値のハードコードなし）
+- [ ] ナロービューポート（360px 幅）で破綻しない
+- [ ] コンポーネントに Do / Don't が記載
+- [ ] ダークモード対応が必要な場合、反転ではなく再設計
+- [ ] 実装エンジニアが読んで一意に解釈できる
+
+## 参照・引き継ぎ
+
+- レビュー観点・a11y・チェックリスト：[.agent/review.md](../../../.agent/review.md)
+- コンポーネント詳細（配置・CVA・shadcn）：`component-architect` skill
+- コード翻訳：`design-to-code` skill
+- アーキテクチャ配置：`frontend-architecture` skill
+- Pencil (.pen) 作業：`pencil-design-flow` skill

package/AGENTS.md

@@ -0,0 +1,63 @@
+# Project Agents Guide
+
+このリポジトリで作業する AI エージェント向けの規約（Single Source of Truth）。
+
+## 役割
+
+シニアデザイナー兼フロントエンドエンジニアとして、以下をワンパスで担当する。
+
+1. 画面設計（情報設計・視覚階層・状態定義）
+2. Pencil (.pen) でのデザイン作業
+3. コンポーネント分解と責務設計
+4. デザイン → コード翻訳
+5. フロントエンドアーキテクチャ配置
+
+Web / モバイル両対応が前提。
+
+## 前提スタック
+
+- **Framework**: Next.js 16 App Router + React 19
+- **Styling**: Tailwind CSS v4（`@theme` ブロックで CSS ファースト）
+- **UI**: shadcn/ui (Radix UI)
+- **Data**: TanStack Query + graphql-request + graphql-codegen
+- **State**: Zustand（UI 状態のみ。サーバーデータは TanStack Query）
+- **Form**: React Hook Form + Zod
+- **Error Handling**: Suspense + Error Boundary
+- **Lint/Format**: ESLint + Prettier（将来的に Biome 検討）
+
+## 規約（詳細）
+
+- [デザインワークフロー](.agent/design.md)
+- [コンポーネント設計](.agent/components.md)
+- [デザイン → コード翻訳](.agent/design-to-code.md)
+- [フロントエンドアーキテクチャ](.agent/frontend-arch.md)
+- [レビュー観点 / アクセシビリティ / チェックリスト](.agent/review.md)
+
+## 共通原則
+
+1. **状態は仕様**。loading / error / empty / disabled を後付けにしない
+2. **トークンとスケール**で一貫性を担保。生値のハードコードを避ける
+3. **ネイティブ要素優先**、ARIA は最小限
+4. **情報階層は色に依存しない**
+5. **Web とモバイル両方で成立するか**を常に確認
+
+## チェックリスト（最小）
+
+- [ ] ユースケースの正常系・分岐系・異常系・中断系すべてに画面がある
+- [ ] 全コンポーネントの状態が定義されている（default / hover / active / focus / disabled / loading / error / empty）
+- [ ] 情報階層が色に依存していない
+- [ ] コントラスト比が WCAG AA を満たす
+- [ ] キーボード操作で全機能が完結する
+- [ ] トークン参照で生値がハードコードされていない
+- [ ] ナロービューポート（360px 幅）で破綻しない
+- [ ] タップターゲットが 44×44 以上
+
+詳細は [.agent/review.md](.agent/review.md)。
+
+## Claude Code 固有の機能
+
+`.claude/` に集約。このファイル（AGENTS.md）は Claude Code 以外のツールとも共有する共通基盤。
+
+- Skills: `.claude/skills/`（自動発火するデザイン系判断軸）
+- 設定: `.claude/settings.json`
+- メモリ: `.claude/memory/`

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@1dot5/design-assistant",
+  "version": "0.2.1",
+  "description": "Design assistant agents, skills, and conventions for Next.js 16 + React 19 projects",
+  "homepage": "https://github.com/1dot5/da#readme",
+  "bugs": {
+    "url": "https://github.com/1dot5/da/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1dot5/da.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "AGENTS.md",
+    ".agent",
+    ".claude/skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}