フロントエンドスタイルガイド & コーディング規約
このドキュメントは、Guessimate Angular フロントエンドのコーディング規約、アーキテクチャパターン、およびデザインシステムを定義します。
1. 技術スタック
- フレームワーク: Angular 20+
- スタイリング: Tailwind CSS 4
- 状態管理: Angular Signals & RxJS
- ビルドシステム: Angular CLI (Esbuild)
2. プロジェクト構造
フィーチャーベースのディレクトリ構造を採用します。コードは技術タイプではなくドメインフィーチャーごとに整理されます。
src/app/
├── core/ # グローバルシングルトン (Guards, Interceptors, グローバルサービス)
├── layout/ # レイアウトコンポーネント (ナビゲーション, フッター, シェル)
├── features/ # フィーチャーモジュール (ドメインロジック)
│ ├── home/
│ ├── session/
│ │ ├── components/ # ダム/プレゼンテーショナルコンポーネント
│ │ ├── pages/ # スマート/コンテナコンポーネント (ルーティング対象)
│ │ ├── services/ # フィーチャー固有の状態/ロジック
│ │ └── models/ # フィーチャー固有の型
│ └── ...
├── websocket/ # WebSocket インフラ
└── shared/ # 共有ユーティリティ (パイプ, ディレクティブ, 汎用 UI)
命名規則
- ファイル: ケバブケース (例:
session-page.component.ts,auth.service.ts)。 - クラス: パスカルケース (例:
SessionPageComponent,AuthService)。 - セレクタ:
app-プレフィックス、ケバブケース (例:app-user-profile)。 - シグナル: 接尾辞なし、説明的な名詞/動詞 (例:
user(),isLoading())。 - Observables:
$接尾辞 (例:user$)。
3. コンポーネント標準
定義
- スタンドアロンコンポーネントを使用します (
standalone: trueは v19+ でデフォルト)。 - ほとんどのコンポーネントでは、ロジックとビューを同じ場所に配置するために インラインテンプレート を推奨します。
- 外部 CSS ファイルは避け、テンプレートで Tailwind CSS ユーティリティクラスを直接使用します。
@Component({
selector: 'app-example',
imports: [CommonModule, RouterLink], // 明示的なインポート
template: `
<div class="p-4 bg-surface-100 rounded-lg">
<h1 class="text-2xl font-bold text-gray-900">{{ title() }}</h1>
</div>
`
})
export class ExampleComponent {
title = signal('Hello World');
}
制御フロー
新しい組み込み Angular 制御フロー構文を使用します。
<!-- Good -->
@if (isLoading()) {
<app-spinner/>
} @else {
@for (item of items(); track item.id) {
<app-item [data]="item"/>
}
}
依存性注入
型推論とコードの明確さを向上させるため、コンストラクター注入よりも inject() 関数を推奨します。
// Good
private readonly
route = inject(ActivatedRoute);
private readonly
store = inject(SessionStore);
// 可能な限り避ける
constructor(private
route: ActivatedRoute
)
{
}
4. 状態管理
- ローカル状態: プリミティブ状態には
signal()を使用します。 - 共有状態: 適切なレベル (ルートまたはコンポーネント) で提供される Signal Store (シグナルを使用するサービス) を使用します。
- リアクティブデータ: 派生状態には
computed()を、副作用にはeffect()を控えめに使用します。
@Injectable()
export class SessionStore {
// 状態
private readonly _state = signal<SessionState>(initialState);
// セレクター
readonly lobby = computed(() => this._state().lobby);
readonly connection = computed(() => this._state().connection);
// アクション
setLobby(lobby: Lobby) {
this._state.update(s => ({...s, lobby}));
}
}
5. スタイリング & デザインシステム
styles.css で定義されたセマンティックカラーパレットを持つ Tailwind CSS 4 を使用します。
使用ルール
- ユーティリティファースト: クラスを HTML に直接記述します。
- マジックナンバー禁止: テーマ値を使用します (例:
p-4、p-[16px]は不可)。 - ダークモード: すべての色関連クラスには
dark:修飾子を使用します。
カラーパレット
アプリケーションは、Tailwind カラーにマッピングされたセマンティック命名規則を使用します。
コアカラー
| カテゴリ | セマンティック名 | ライトモード | ダークモード | 使用目的 |
|---|---|---|---|---|
| 背景 | background | gray-50 | gray-950 | メインアプリケーション背景 |
| サーフェス | surface | white | gray-900 | カード、モーダル、セクション |
| 代替サーフェス | surface-alt | gray-100 | gray-800 | セカンダリ背景、入力フィールド |
| プライマリ | brand | blue-600 | blue-600 | プライマリアクション、ボタン、ハイライト |
| プライマリミュート | brand-muted | blue-50 | blue-900/30 | 選択状態、薄いハイライト |
| 成功 | success | emerald-500 | emerald-600 | 成功状態、確認 |
| 成功ミュート | success-muted | emerald-50 | emerald-900/30 | 成功背景 |
| 危険 | danger | red-600 | red-600 | エラー、破壊的アクション |
| 危険ミュート | danger-muted | red-50 | red-900/30 | エラー背景 |
| 警告 | warning | amber-500 | amber-600 | 警告、保留状態 |
| 警告ミュート | warning-muted | amber-50 | amber-900/30 | 警告背景 |
タイポグラフィ & ボーダー
| カテゴリ | ライトモード | ダークモード | 使用目的 |
|---|---|---|---|
| プライマリ | gray-900 | white | 主要見出しと本文テキスト |
| セカンダリ | gray-500 | gray-400 | サブタイトル、ラベル、補足情報 |
| ミュート | gray-400 | gray-500 | 無効テキスト、プレースホルダー |
| ボーダー | gray-200 | gray-800 | 標準区切り線とカード境界線 |
styles.css での実装
色は @theme ブロック内の CSS 変数を使用して定義されます:
@theme {
--color-brand-600: var(--color-blue-600);
--color-surface-100: var(--color-stone-100);
/* ... */
}
6. 共通コンポーネントパターン
カード & コンテナ
コンテンツコンテナ (見積もりカード、リストなど) の標準スタイリング:
<div class="flex flex-col bg-surface-100/60 border border-surface-200 dark:bg-gray-900/40 dark:border-gray-800/60 rounded-md shadow-sm">
<!-- コンテンツ -->
</div>
- 背景:
bg-surface-100/60(ライト) /dark:bg-gray-900/40(ダーク) - ボーダー:
border border-surface-200(ライト) /dark:border-gray-800/60(ダーク) - 角丸:
rounded-md(標準) - 区切り線:
divide-y divide-surface-300 dark:divide-gray-800
タイポグラフィヘッダー
<div class="flex flex-col gap-1">
<h2 class="text-2xl font-semibold leading-none text-gray-900 dark:text-white">タイトル</h2>
<span class="text-sm font-normal text-gray-600 dark:text-gray-400">サブタイトル説明</span>
</div>