diff --git a/docs/DESIGN.md b/docs/DESIGN.md new file mode 100644 index 0000000..f27fffb --- /dev/null +++ b/docs/DESIGN.md @@ -0,0 +1,126 @@ +# 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` と `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 方針を反映) |