# Ponshu Room — デザイン指針（DESIGN）

本書は **日本酒アプリ（ponshu_room_lite）** の UI/UX の「正」です。実装・レビュー・デザイン議論はここを基準にしてください。v2 新規プロジェクトでも本書の原則を継承し、必要に応じて `DESIGN_v2.md` に分割してください。

---

## 1. 把握の前提（AI・開発者向け）

- **コードベースから分かること**: 画面一覧、ナビゲーション、テーマトークン（`lib/theme/app_colors.dart`）、フォント（`lib/theme/app_theme.dart`）、主要ウィジェットの構造。
- **コードだけでは分からないこと**: 実機での余白感、フォントレンダリング、長時間利用時の疲労。これらは **Flutter Web（`flutter run -d chrome`）または静的プロトタイプ + Cursor ブラウザプレビュー** で確認する。

---

## 2. デザイン原則（5つ）

1. **写真が主役** — ラベル・瓶の画像を最優先。文字情報はそれに従属させる。
2. **迷わせない** — 初回はシンプルなデフォルト。上級者向けカスタムは「設定」に段階的に置く。
3. **和モダン** — 和紙・墨・琥珀の世界観と、読みやすい現代タイポの両立（`ColorVariant.washiSumiKohaku` / `current`）。
4. **一貫したトークン** — 色・余白・角丸は `ThemeExtension<AppColors>` と `AppTheme.spacing*` を経由し、直書き色を増やさない。
5. **アクセシビリティ** — タップ領域は最低 44dp 相当を目安。コントラストは WCAG を意識（特にライトテーマの本文）。

---

## 3. カラー（セマンティック）

定義の単一ソース: [`lib/theme/app_colors.dart`](../lib/theme/app_colors.dart)

| トークン | 用途 |
|----------|------|
| `textPrimary` / `textSecondary` / `textTertiary` | 見出し・本文・補助 |
| `brandPrimary` / `brandAccent` / `brandSurface` | ブランド・強調・背景ティント |
| `surfaceElevated` / `surfaceSubtle` | カード・区画 |
| `divider` | 区切り線 |
| `success` / `warning` / `error` / `info` | 状態 |

**禁止**: `Color(0xFF...)` をウィジェットに直接散らばらせない（新規コードでは ThemeExtension 経由）。

---

## 4. タイポグラフィ

定義: [`lib/theme/app_theme.dart`](../lib/theme/app_theme.dart)

| `AppFontStyle` | 用途の目安 |
|----------------|------------|
| `sans` | デフォルト・本文 |
| `serif` | 銘柄名・見出しに品格を出すとき |
| `pottaOne` | 限定利用・キャンペーン（可読性より雰囲気） |
| `digital` | ゲーミング寄り演出（使いどころを限定） |

---

## 5. スペーシング

`AppTheme` の定数を使用: `spacingTiny` (4) / `spacingSmall` (8) / `spacingMedium` (16) / `spacingLarge` (24) / `spacingXLarge` (32)。

カード内の縦リズムは **8 の倍数** を基本とする。

---

## 6. 画面別の意図（現行）

| 領域 | 役割 |
|------|------|
| Home | コレクション一覧。検索・フィルター・表示モード。FAB から撮影・メニュー導線。 |
| Scan（Pro） | QR 等のスキャン。 |
| Sommelier | 診断・ランキング・レコメンド。シェア体験。 |
| Map | 地域・酒蔵の探索。 |
| Soul | マイページ・成長記録・バックアップ・表示設定。 |

ナビゲーション実装: [`lib/screens/main_screen.dart`](../lib/screens/main_screen.dart)

---

## 7. ユーザー向けカスタム（昇格候補）

A/B や実験から「常設」に昇格したもの・今後載せたいもの:

- **HOME 列数** — 2 カラム / 3 カラム（将来は設定で固定可能に）。
- **表示モード** — リスト / グリッド（`display_mode_provider` と整合）。
- **テーマ** — `ColorVariant` + ライト/ダーク + フォントスタイル。
- **情報密度** — カードに載せるメタ情報の ON/OFF（蔵元・都道府県・タグ等）。

新規カスタムを足すときは **デフォルトを変えず**、「設定で戻す」「初期化」パスを必ず用意する。

---

## 8. モーション

- 画面遷移は Material の標準に寄せる。
- 過剰なループアニメーションは避ける（バッテリー・酔い対策）。
- 解析中ローディングは **`AnalyzingDialog`** 等の既存パターンを踏襲。

---

## 9. ログ・リポジトリ規約（プロジェクト共通）

- **コード・ログ・コミットに絵文字を使わない**（Posimai プロジェクト規約）。
- UI 上の装飾としての記号は別問題。ログは `[TAG]` 形式を推奨。

---

## 10. Cursor ブラウザで UI を一緒に詰める手順

1. ターミナルで `flutter run -d chrome` を実行する。
2. 表示された `http://localhost:...` をチャットに貼る（または「Chrome で開いている」と伝える）。
3. 気になる点を箇条書きで送る（例: 「HOME のカードだけ行間を詰めたい」）。
4. エージェントがスナップショット前提で修正案・コード差分を返す。

**注意**: Android APK 単体だけではブラウザ経由でプレビューできない。Web ビルドか HTML プロトタイプが必要。

---

## 11. 次のアクション（推奨順）

1. **本書をレビュー** — 色名・カスタム項目の追記・削除を 1 セッションで確定。
2. **`flutter run -d chrome` で HOME / Detail を開き**、URL を共有して見た目の微調整ループに入る。
3. **v2 用** — 新リポジトリでは `docs/DESIGN.md` をコピーし、セクション 6 を v2 画面名に差し替える。

---

## 改訂履歴

| 日付 | 内容 |
|------|------|
| 2026-04-16 | 初版作成（現行コードベースと v2 方針を反映） |