AME UI Philosophy Skill

本 Skill は、TypeScript + Tailwind
CSS を用いる各種プロダクト・共通コンポーネントに適用可能な、汎用 UI/UX デザイン・統一基準を AI
Agent が実行可能なガイドラインとして定義したものです。特定プロジェクト専用ではなく、同スタックを使う任意のリポジトリで利用できます。コンポーネント生成・修正・リファクタリングを行う際は、必ず本ドキュメントを適用してください。タイポグラフィ（フォント定義・多言語フォント切替・見出し階層）の詳細ルールは
[[ame-ui-typography]] Skillに分離されているため、併用すること。

1. 核心哲学 (Core Philosophy)

すべての UI 設計は、以下の 3 原則を起点に判断すること。

• 引き算のデザイン: 装飾は情報伝達を助ける場合のみ許可。自己主張する装飾は排除する。
• 余白による構造: 構造は「線（border/hr）」より「余白」で作る。線は最後の手段。
• 真面目感（フォーマルさ）: 開発ツールとして厳格で落ち着いたトーンを維持する。

2. デザイン4大原則 (Design Principles)

Tailwind クラス適用時は次を厳守する。

原則	適用ルール (Tailwind)
近接 (Proximity)	関連情報は近づける (gap-2, gap-4)。無関係情報は離す (mt-8, p-6)。区切りは安易な border-b / hr ではなく余白を優先。
整列 (Alignment)	原則 左揃え (text-left, items-start)。中央揃えはロゴや短いコピー等の限定用途のみ。
反復 (Repetition)	8px グリッド（4, 8, 16, 24, 32...）を厳守。任意値 (p-[13px]) 禁止。角丸は rounded-md / rounded-lg のみ。
コントラスト (Contrast)	サイズ・太さ・色濃さに明確な差をつける。中途半端な差（text-base と text-sm のみ等）を禁止。

3. アイコン・図表 (Icons & Diagrams)

3.1 アイコン使用ルール

• 既知のサービス・機能・操作に紐づく要素（ボタン、ラベル、ナビゲーション項目等）には、文言だけでなく対応するアイコンを併記する。例:「GitHub」ボタンには GitHub アイコン、「コピー」操作には Copy アイコンを付与する。
• アイコンセットは Lucide
  を標準とする（利用スタックに応じたパッケージを選択する。例: lucide-react, lucide-vue-next,
  lucide-svelte）。ストローク型・currentColor
  継承のため、本 Skill の配色/ダークモード規定（§4）と親和性が高く、装飾目的の多色アイコン（禁止事項 §9 参照）を避けられる。
• サイズは Tailwind の 8px グリッドに揃える（インラインテキスト添え字は
  size-4、単体ボタン・見出し添え字は size-5）。任意ピクセル値 (w-[18px]) は禁止。
• アイコン単体で意味を持たせる場合（アイコンのみボタン等）は、必ず aria-label
  を付与しテキスト情報を代替する（アクセシビリティ §7 準拠）。
• 装飾目的のみのアイコン追加は禁止。情報伝達・操作対象の明確化に資する場合のみ使用する（核心哲学 §1「引き算のデザイン」準拠）。

3.2 図表・ダイアグラムの実装手段

表現内容に応じて実装手段を使い分ける。

種別	実装手段	例
相対配置で表現できる簡易な図（フロー図、ボックス＆矢印、レイアウト模式図）	HTML + Tailwind	flex/grid と border/bg-* の組み合わせ
座標・パス・角度・スケールの精密な制御が必要な図（グラフ、図形描画、任意曲線）	SVG	<svg> + <path>/<circle> 等

• 判断基準: Flexbox/Grid の相対配置だけで組めるか（→ HTML）、絶対座標やパスの計算が要るか（→
  SVG）で選択する。
• HTML 実装はレスポンシブ・ダークモード対応が容易なため、座標計算が不要な限り優先する。
• SVG 実装時も色は --color-primary または currentColor 経由にし、dark:
  でのコントラスト維持を確保する（§4 準拠）。

3.3 図表の可変性（フォント・多言語・カラー対応）

図表（HTML/SVG いずれの実装でも）は、通常の UI コンポーネントと同じ可変性要件に従うこと。決め打ちの見た目で固定しない。

• フォント: 図表内のラベル・注釈テキストにも font-family を決め打ちせず、[[ame-ui-typography]]
  Skill の --font-ui-ja-sans / --font-ui-en-sans 等の CSS 変数を継承させる。SVG 内 <text> も
  font-family: var(--font-ui-...) を指定し、locale 切替でフォントが自動的に追従するようにする。
• 多言語 (i18n): 図表内の文言は翻訳キー経由にし、ハードコードしない（§8 準拠）。ja/en
  でラベル長が変わっても崩れないよう、SVG は固定座標へのテキストのはめ込みを避け、viewBox
  や余白を可変にする。HTML 実装は flex/grid の伸縮性を活かし、折返し・最小幅で対応する。
• カラー: §3.2 の通り --color-primary / currentColor
  を使い、ライト/ダーク切替と 1ポイントカラー変更（§4.2）の両方に追従させる。

4. 配色システムとダークモード (Color + Dark Mode)

4.1 ベース配色

• ライトモード: 背景 bg-white / bg-gray-50、テキスト text-gray-900/700/500
• ダークモード: 背景 bg-gray-900（純黒 #000 を避ける）、テキスト text-gray-100/300/400

テーマ切替は light / dark / system をサポートし、app_settings
へ永続化する。保存スキーマ例（本リポジトリ）:
{ locale: "ja"|"en", themeMode: "light"|"dark"|"system", colorPreset: "<presetId>", fontPreset: <FontPreset enum 値>, customFont: string }（fontPreset
の enum 値の定義は ame-ui-typography
Skill を参照）。キー名・既定値は実装（SettingsContext 等）と同期させること。フォント関連項目（fontPreset
/ customFont）の仕様・enum 値の定義は ame-ui-typography
Skill を単一の情報源として参照する（本 Skill では重複定義しない）。

クラスベース配色（標準実装）: テーマは <html> の .dark クラスで制御する。Tailwind CSS
v4 では dark: バリアントの既定が
prefers-color-scheme（OS 依存）のため、クラスベース配色を採用する場合は
@custom-variant dark (&:where(.dark, .dark *)); をスタイルエントリへ追加し、 .dark
クラス連動に変更すること（CSS 変数 --color-* は .dark ブロックで別値を定義）。 system
モードでは matchMedia("(prefers-color-scheme: dark)")
の変更リスナーで OS テーマ変更へライブ追従すること（初回描画時のみの適用で止めない）。

FOUC 対策（初回描画のちらつき防止）: <head> のインラインスクリプトで保存済みテーマモード
（app_settings.themeMode）を描画前に .dark
クラスへ適用すること。適用対象はテーマモードのみとし、色プリセット・フォントはアプリ側のマウント処理で適用する。

4.2 1ポイントカラー（5プリセット）

--color-primary を切り替えて利用する。ライト・ダークで別値を持つこと。

名称	Light	Dark Variant	意味
Trust Blue	#005B99	#3B82C4	信頼・技術
Stable Green	#2D6A4F	#4F8A6E	安定・成長
Grounded Orange	#C2410C	#DD6B3D	注意・アクション
Sophisticated Indigo	#4338CA	#7C79E8	高級感・モダン
Clarity Teal	#0F766E	#2FA39A	明瞭・冷静

通常テキストのコントラスト比は最低 4.5:1（WCAG AA）を満たすこと。

5. スペーシング・レイアウト (Spacing & Layout)

• 8px グリッド厳守: 4 / 8 / 16 / 24 / 32 / 48 / 64px（gap-1/2/4/6/8/12/16）
• 任意値禁止: p-[13px] 等を使用しない
• 角丸: rounded-md / rounded-lg
  のみ。ただし、アイコン、バッジ、アバター、スウォッチ等の円形UIは rounded-full を許容する。
• 境界線: border / border-b / divide-y / hr
  は最終手段。先に余白で解決する（※ヘッダーやタブ等の下線は許容）

6. アニメーション (Animation)

6.1 規定値（duration / easing）

用途	duration	easing	Tailwind 例
マイクロインタラクション	150ms	ease-out	transition-all duration-150 ease-out
状態変化（色・背景）	200ms	ease-out	transition-colors duration-200 ease-out
要素の出現・消失	200-300ms	ease-in-out	transition-opacity duration-300 ease-in-out
ページ切替	200-300ms	ease-in-out	ルーティング遷移
チャットテキスト描画	ストリーミング	-	文字/ブロック単位フェード（duration-150）

6.2 制約

• 300ms 超のアニメーション禁止
• 装飾目的のアニメーション（回転・バウンス・パララックス）禁止（※稼働状態やロードを示すパルス・スピン等は例外）
• prefers-reduced-motion: reduce 時は motion-reduce:* で無効化

7. アクセシビリティ (Accessibility: WCAG 2.1 AA)

• 通常テキスト 4.5:1 以上、大テキスト 3:1 以上
• 色だけに依存せず、ラベル・アイコン・形状差を併用
• 全機能キーボード操作可能、focus-visible: で明確なフォーカス表示
• セマンティック HTML と正しい見出し階層を維持
• フォームは label を関連付け、エラーはテキストで明示
• 動的更新（チャット追加など）は aria-live で通知

8. 多言語対応 (i18n)

8.1 対応言語

• 初期リリースは ja / en
• 将来言語を追加可能な i18n 構造を前提に設計

8.2 実装要件

• UI 文字列はすべて翻訳リソース経由（ハードコード禁止）
• 言語切替は設定 UI から実行可能にする
• 選択言語は app_settings に永続化する
• 日付・時刻・数値は Intl API 等でロケール準拠にする
• ラベル長が増えても崩れないレイアウト（折返し・最小幅・余白）を確保する

8.3 フォントと i18n の接続ルール

locale に応じたフォント切替の詳細ルール（言語別フォント定義、Mono フォールバック等）は
[[ame-ui-typography]] Skill の「フォントと多言語対応 (i18n) の接続ルール」を参照・適用すること。

9. 禁止事項 (Negative Constraints)

1. 過度なドロップシャドウ（shadow-lg, shadow-xl）
2. グラデーション背景（bg-gradient-to-*）
3. 余白で解決可能な区切り線（border-b, hr）
4. 8px グリッド外の任意値（p-[13px] 等）
5. text-justify
6. rounded-xl 以上
7. テキストのハードコード（翻訳リソースを通さない UI 文言）

10. AI 実行ワークフロー (Execution Workflow)

コンポーネント生成・修正時は、以下 Step 1〜5 を必ず実行すること。

Step 1: 要件分析と情報設計

• コンポーネントの目的、画面内コンテキスト、利用ロケール（ja/en）を確認する
• 情報優先順位とセマンティック構造（main/section/article/nav）を決定する

Step 2: レイアウト設計（引き算 + 余白）

• 8px グリッドで要素を配置し、余白で情報構造を分離する
• 関連要素は gap-* で近接、非関連要素は mt-*/p-* で分離する
• 線ではなく余白を優先し、角丸は rounded-md/lg に限定する
• 既知のサービス・操作に紐づく要素にはアイコン（Lucide）を併記し、図表は HTML/SVG のどちらで実装するかを内容に応じて判断する（§3 準拠）

Step 3: スタイル適用（Typography / Color / i18n）

• タイポグラフィ（見出し階層・フォント・行間・字間・行長）は [[ame-ui-typography]]
  Skill の規定に従って適用する
• --color-primary と dark: を使い、ライト/ダーク双方でコントラストを満たす
• 文字列を翻訳キー経由へ統一し、日時/数値をロケール形式にする

Step 4: アクセシビリティとモーション検証

• focus-visible、label、aria-*、aria-live を確認する
• アニメーションは規定 duration/easing 内に収める
• motion-reduce:* を適用し、色だけに依存した状態表現を排除する

Step 5: 禁止事項と品質ゲート最終確認

• 禁止事項（シャドウ、グラデーション、任意値、過剰角丸、ハードコード文言）を全点検する
• 既知の操作・サービスに紐づく要素にアイコン抜けがないか、図表の実装手段（HTML/SVG）が内容に見合っているかを確認する
• ja/en の表示崩れと読みやすさを確認し、問題なければ最終コードを出力する