09. デザインシステムとUI/UXガイドライン

1. デザイン哲学 (Design Philosophy)

本プロジェクト「BluePeriod」のデザインは、単なる装飾ではなく、「創作」という行為への深い敬意と、「個」の尊重を体現するためのシステムです。

1.1. 静謐なアトリエ (A Serene Atelier)

UIは、ユーザー（創作者）の集中力を削ぐノイズであってはなりません。

Minimalism: 不要な装飾、過度なアニメーション、派手な色彩を排除します。
Focus: ユーザーが「書くこと」「読むこと」に没入できる、静かで落ち着いた環境を提供します。

1.2. コンテンツファースト (Content First)

主役は常に「作品」です。UIは黒子に徹し、作品の魅力を最大限に引き立てる枠組みを提供します。

Bookshelf / Explore: グリッドレイアウトと美しいカバー画像表示により、作品そのものの存在感を強調します。
Typography: 可読性を最優先し、長時間の執筆・読書でも疲れないタイポグラフィを採用します。

1.3. 数字からの脱却 (Beyond Numbers)

本プラットフォームは、安易なランキングや数値による序列化を否定します。

No Public Metrics: 「いいね数」や「閲覧数」といった定量的な指標を、公共の場（Exploreなど）で表示しません。
Quality over Quantity: 数字の多寡ではなく、「誰が読んだか」「どんな感想を持ったか」という文脈（Context）や定性的なフィードバックを可視化することで、作品の真の価値を伝えます。

2. テクニカル・デザインスタック (Technical Stack)

本プロジェクトのデザインシステムは、以下のモダンな技術スタックによって実装・管理されています。

Tailwind CSS: ユーティリティファーストなCSSフレームワーク。スタイリングの基盤となります。
shadcn/ui: Radix UIをベースとした、アクセシブルでカスタマイズ可能なコンポーネントライブラリ。UIの構成要素となります。
Lucide React: 一貫性のある美しいアイコンライブラリ。
Next.js Fonts / Fontsource: 最適化されたWebフォントの配信。

3. テーマとカラースキーム (Theme & Color Scheme)

3.1. テーマ定義

現在、next-app/public/themes/blue-period-light.json がすべての基準テーマとして運用しています。まずはこれを参照しましょう。

プロジェクトは、以下のテーマ定義（CSS変数）に基づき、ライトモードとダークモードの両方で美しく機能するように設計されています。

Primary Color: 知的で落ち着いた印象を与える、深みのある「青」を基調とします。
Background: 純粋な白や黒ではなく、目に優しいオフホワイトやダークグレーを採用します。

(src/app/globals.css および tailwind.config.ts も参照)

3.2. 実装ルール: セマンティックトークンの強制 (Strict Semantic Token Usage)

【重要】 UIコンポーネントの実装において、text-blue-500 や bg-red-400 といった具体的な色名（Raw Colors）の使用を原則禁止します。代わりに、必ずglobals.cssおよびテーマ定義で提供されるセマンティックトークンを使用してください。

禁止例 (Don't):

❌ bg-blue-600 (青すぎる、テーマが変わると浮く)
❌ text-gray-500 (ダークモードで見えなくなる可能性がある)
❌ border-yellow-400

推奨例 (Do):

✅ bg-primary (メインアクションとして適切)
✅ text-muted-foreground (補足テキストとして適切)
✅ border-destructive (警告・危険な操作として適切)

例外:

ユーザーが作成したコンテンツのラベル色など、UIテーマとは独立した固有の色を表現する場合。
どうしても既存のトークンで表現できない場合（この場合は新たなセマンティックトークンの定義を検討してください）。

3.3. テーマシステムの実装詳細

テーマ定義ファイル: next-app/public/themes/*.json

各テーマJSONは以下の構造を持ちます：

{
  "name": "Blue Period Light",
  "id": "blue-period-light",
  "variables": {
    "background": "220 12% 82%",  // HSL形式
    "foreground": "220 20% 15%",
    "primary": "220 80% 23%",
    // ... 他50個以上の変数
  }
}

テーマ適用の仕組み:

コンポーネント	役割
`ThemeProvider`	テーマJSONを`/public/themes/`から読み込み、CSS変数として適用
`ThemeManager`	フォント設定・シンタックスハイライトの動的切り替え
`settingsAtoms.ts`	`themeAtom = atomWithStorage('app-theme', 'blue-period-light')` でデフォルト設定

利用可能なテーマ一覧:

blue-period-light (デフォルト) / blue-period-dark
light / dark
overlayer-light / overlayer-dark
dislife-light / dislife-dark
dorothy-blood-light / dorothy-blood-dark
lazy-lily-light / lazy-lily-dark

注意: テーマJSON内には *-hover（success-hover, secondary-hover等）の変数が定義されていますが、現時点では使用されていません。これらは将来の拡張用またはテンプレートの名残であり、なくても問題なく動作します。

3.4. モードの切り替え

ユーザーのOS設定または手動選択により、シームレスにテーマを切り替える機能を標準で提供します。
執筆画面などの長時間見つめる画面では、コントラスト比に特に配慮してください。

4. レスポンシブデザイン戦略 (Responsive Strategy)

4.1. モバイルファーストではない「体験ファースト」

単に画面幅に合わせて要素を積み重ねるのではなく、デバイスごとの利用シーンに合わせた最適なUIを提供します。

PCビュー: 3パネルレイアウト（プロット、原稿、アシスタント）による、一覧性の高い執筆環境。
モバイルビュー: ボトムナビゲーションによる、機能ごとの画面切り替え。親指で操作可能なエリア（Thumb Zone）への操作系集約。
- 統一されたメニュー体験: デスクトップ・モバイル共通でグローバルヘッダーのプロフィールアイコンからメニューを提供し、デバイス間のUIの一貫性と機能の同期を確保します。

4.2. 実装アプローチ

useMobileフック: 画面幅によるレイアウトの分岐は、CSSメディアクエリだけでなく、useMobileフックを用いた条件付きレンダリングによって制御します。これにより、PC/モバイルそれぞれに最適化されたDOM構造を実現します。

インライン・エクスパンダー: 作品一覧では、ページ遷移を伴わない詳細表示（クリックで下部に展開）を採用し、ザッピング体験を向上させます。
コンテキスト表示: 作品カードには、「数値」ではなく「文脈（誰が読んだか、レビューの抜粋）」を表示するスペースを確保してください。

6.2. Reader（読書体験）

タイポグラフィの統一: 読書画面およびその付帯要素（目次、ヘッダーの章題など）では、原則として原稿用フォント（var(--font-manuscript)）を使用し、没入感を高めます。
レスポンシブな文字組:
- 長いチャプター名や作品タイトルは、モバイル表示において省略（truncated）せず、適切に折り返して全内容を表示することで、ユーザーが現在地を正確に把握できるようにします。
- 目次（Drawer/Sidebar）内では、文字サイズと余白のバランスを調整し、リストとしての読みやすさと、原稿としての雰囲気を両立させます。

6.3. Agent Tool Review (HITL)

エージェントが実行するアクション（特にファイルの変更）をユーザーが承認するためのパターンです。

Diff View: 変更前（Original）と変更後（New）を明確に比較させます。
Mobile optimization: 狭い画面では横並びの比較が困難なため、Originalを上、Newを下にするVertical Stackレイアウトを採用し、一文字単位の差分（diff-chars）にフォーカスします。
Focus Mode: レビュー時は情報密度を下げるため、メインのテキストエディタなどを一時的に隠し、差分比較に集中できる環境を提供します。

6.4. チャット・コンテキストの表示 (Context Disclosure)

AIが内部的に取得・参照・記憶した情報を透過的にユーザーに伝えるためのパターンです。

Referenced Memories (参照した記憶): 直期記憶から検索された情報は、メッセージ下部に「参照した記憶」としてアコーディオン形式で表示します。
Newly Memorized Facts (新しく記憶した内容): AIが会話を通じて新しく「記憶（長期記憶への保存）」を決定した事実は、メッセージ下部に「新しく記憶した内容」というアコーディオン形式で表示します。
Thought Log (思考ログ): エージェント実行中の詳細なステップは、別の折り畳みセクション（Thought Log）にまとめ、ノイズにならないよう配慮します。

6.5. Session Artifacts とコンテキスト制御

ユーザーがAIの「文脈」を明示的に、かつ視覚的に管理するためのパターンです。

isActive トグル: 各Artifactカードに配置されるトグルスイッチです。これをONにすることで、その資料の内容がAIのコンテキスト（インデックス/スニペット）に含まれるようになります。
Files パネル (Artifacts Sidebar): チャット画面のヘッダーにある「📑」ボタンからアクセスできるサイドパネルです。セッション内で生成されたすべての資料を一覧し、コンテキストのON/OFFを一括して管理できます。
削除によるパージ: 不要になった資料を削除することで、物理的にAIの参照可能範囲から除外できます。

6.6. Pro Membership Visuals (会員ステータスの明示)

ユーザーが Pro 会員であることを、控えめかつ明確に伝えるためのパターンです。

PRO Badge: セマンティックトークン primary を背景色とし、白抜きのテキストで「PRO」と表示する小さなバッジです。
Placement:
- Header: ユーザープロフィールの近傍に表示し、現在のログイン状態と権限を常に把握可能にします。
- ProfileHeader (Settings): ユーザー名の横に大きく表示し、プレミアムな体験の所有を強調します。

6.7. インポート/エクスポート

PWA/ファイル連携: 将来的にはFile Handling API等を用いたネイティブライクな連携を目指しますが、当面はファイル選択ダイアログやドラッグ＆ドロップによる直感的な操作を提供します。

6.8. バックグラウンド進捗通知 (Background Progress Notification)

AIモデルのダウンロードや大規模なデータ処理など、ユーザーの操作を直接ブロッキングせずに進行する長時間タスクの状態を伝えるためのパターンです。

配置: 画面下部（モバイルではボトムナビ上部、PCでは右下）にフローティング表示されるトースト形式のカード。
デザイン: bg-background/95 と backdrop-blur を使用し、コンテンツを透過させつつ情報を際立たせます。
アクセシビリティ: 処理が完了、あるいはエラーになった後も、ユーザーが認識できるよう数秒間の「余韻」を持って表示を維持します。
ノイズの低減: 進捗状況が0%または100%付近で頻繁にちらつかないよう、一定期間内の更新頻度を制御するか、アニメーションで変化を吸収します。

7. タイポグラフィ階層 (Typography Hierarchy)

作品詳細ページ（ProjectDetailView）や各種コンポーネントにおいて、情報の重要度と性質を視覚的に伝えるため、以下のタイポグラフィ階層を適用します。

7.1. 明朝体 (`font-serif`) の用途

知的で情緒的な雰囲気を演出し、視線のフックとなる要素に使用します。

作品タイトル / キャッチコピー (Headline)
各セクションの大見出し (Synopsis, Table of Contents, AI Review Analysis 等)
レーダーチャートの軸名

7.2. サンセリフ体 (`font-sans`) の用途

情報の可読性と機能性を重視する要素に使用します。

あらすじ本文 / 各種説明文
レビューコメント / 評価詳細
タグ / バッジ / メタ情報
ボタン / ナビゲーション項目

7.3. 混在時の原則

同じコンポーネント内でこれらを使い分けることで、「見出しで惹きつけ、本文で読ませる」というメリハリのある読書体験・探索体験を演出します。

8. モバイル・アクセシビリティ・ルール (Mobile Accessibility Rules)

タッチデバイス（スマートフォンやタブレット）における操作性と情報の発見性を確保するため、以下のルールを遵守します。

ホバー依存の禁止: 重要な補助情報（設定項目の詳細説明など）は、マウスホバー（hover）のみで表示させてはなりません。タッチデバイスではホバー状態を模倣できないため、情報が閲覧不能になります。
タップ（Click）による制御: ツールチップ（Tooltip）の代わりに、または組み合わせてポップオーバー（Popover）を検討し、タップすることで明示的に表示・非表示を切り替えられるようにします。
ヒットエリアの確保: 情報を表示するためのアイコン（Infoアイコンなど）は、単体で配置する場合も十分なヒットエリア（最低 44x44px 相当の反応領域、または隣接するラベルを含めたタップ領域）を確保し、指での操作を容易にします。

8.2. インライン表示の優先

画面の複雑性を著しく高めない限り、補足説明はアイコンに隠さず、ラベルの下などに微細なテキストでインライン表示することを検討してください。これにより、ユーザーの「確認の手間（タップ回数）」を削減します。

9. スタイリング実装に関する注意点 (Styling Implementation Notes)

9.1. IDEによるCSS警告について

globals.cssで以下の警告がIDE（VSCode等）から出力される場合がありますが、これらは**誤検知（False Positive）**であり、実際の動作には問題ありません。

警告内容	原因
`@tailwind` ディレクティブが不明	PostCSS処理前のディレクティブをIDEが認識できない
`@apply` ディレクティブが不明	同上（Tailwindの機能をIDEが認識できない）
`scrollbar-width` / `scrollbar-color` が非サポート	以前はFirefox独自仕様（Chrome 121+でサポート）。リンターデータベースが古い

対処方法（オプション）:

VSCodeのCSS Validateを無効化（.vscode/settings.json）
「Tailwind CSS IntelliSense」拡張機能をインストール
警告を無視（推奨：ビルド時には正しく処理されます）

9.2. CSSファイル構成

ファイル	用途
`next-app/src/app/globals.css`	メインのCSSファイル（Tailwindディレクティブ、CSS変数定義）
`next-app/src/app/markdown.css`	チャットメッセージ内のMarkdown表示用スタイル
`next-app/src/app/markdown-reader.css`	リーダー画面用のMarkdownスタイル

globals.cssの先頭で以下をインポートしています：

@import "highlight.js/styles/github-dark.css";
@import "./markdown-reader.css";
@import "./markdown.css";

9.3. highlight.js CDNについて

シンタックスハイライトにhighlight.jsを使用しており、現在はCDN（cdnjs.cloudflare.com）からスタイルシートを読み込んでいます。

使用箇所:

globals.css:1 - @import "highlight.js/styles/github-dark.css"
ThemeManager.tsx - テーマ切り替え時に動的にCDNから切り替え
コードブロック（<pre><code>）のシンタックスハイライト

注意: Localhost開発時、ブラウザのトラッキング防止機能によってCDNへのアクセスがブロックされることがあります。これは開発環境特有の現象であり、本番環境では正常に動作します。

将来的な改善案: highlight.jsをnpmパッケージとしてインストールし、ローカルから読み込むことでCDN依存を解消できます。

デザインシステムとUI/UXガイドライン