Merge pull request #1674 from future-architect/feature

Web Frontend Guidelines

Author: ma91n

source/_posts/2025/20250911a_Webフロントエンド設計ガイドラインを公開しました_at_10：00.md

@@ -0,0 +1,170 @@
+---
+title: "Webフロントエンド設計ガイドラインを公開しました"
+date: 2025/09/11 00:00:00
+postid: a
+tag:
+  - ガイドライン
+  - React
+  - Vue.js
+  - 設計
+category:
+  - Frontend
+thumbnail: /images/2025/20250911a/thumbnail.jpg
+author: 谷川寛
+lede: "フューチャー社内の有志メンバーでWebフロントエンド設計ガイドラインを作成し公開しました！本ガイドラインではガイドライン策定の背景やガイドラインの特徴に加えて、内容の一部をピックアップしてご紹介します。"
+---
+
+<img src="/images/2025/20250911a/top.jpg" alt="" width="615" height="615">
+
+# はじめに
+
+こんにちは。TIGの長谷川です。
+
+フューチャー社内の有志メンバーで[Webフロントエンド設計ガイドライン](https://future-architect.github.io/arch-guidelines/documents/forWebFrontend/web_frontend_guidelines.html)を作成し公開しました！
+
+本ガイドラインではガイドライン策定の背景やガイドラインの特徴に加えて、内容の一部をピックアップしてご紹介します。
+
+# 本ガイドラインの背景
+
+昨今のWebフロントエンド領域は、単なるHTML、CSS、JavaScriptでのページ制作から大きく変化しました。React、Vue.jsなどのモダンなフレームワークを活用した大規模かつ動的なWebアプリケーションの構築が主流となっています。
+
+これにより開発の効率化とユーザー体験（UX）が向上しています。しかし一方で、設計の考慮点も多様化し、セキュリティやアクセシビリティなど、より多面的な品質も求められるようになりました。
+
+本ガイドラインでは、Webフロントエンド設計における考慮点・設計パターン・推奨手法を提示し、**開発チームが設計方針を決めるための土台を提供**します。
+
+# 前提
+
+本ガイドラインの対象読者は、Webフロントエンドの開発者・アーキテクトです。基本的なWeb技術（HTML、CSS、JavaScript、HTTP通信など）やReact、Vue.jsなどのフレームワークの基礎知識は前提としています。
+
+適用範囲はブラウザ上で動作するWebフロントエンドのみです。サーバーサイドやCDN、BFF（Backend For Frontend）などは対象外です。
+
+Web APIの設計については、別途公開している[Web API設計ガイドライン](https://future-architect.github.io/arch-guidelines/documents/forWebAPI/web_api_guidelines.html)と[その紹介記事](https://future-architect.github.io/articles/20250513b/)をぜひご参照ください！
+
+# ガイドラインの特徴
+
+本ガイドラインは、基本的に**業務アプリケーションの開発を想定**して作成しています。これらのアプリケーションは、大規模なtoC向けサービスとは異なる、以下のような特性を持ちます。
+
+- 権限管理が細かく所属部署や役職で表示内容が細かく変わる
+- 複雑なデータ入力フォームや多機能なテーブル表示など状態管理やUI制御が複雑
+- 利用するデバイスは比較的絞り込みやすい
+
+本ガイドラインは全体を通して読むことも、興味のあるセクションをピックアップして読むことも可能です。
+ガイドラインは以下の8つの流れで構成されており、Webフロントエンド設計における幅広い領域を体系的にカバーしています。
+
+- **構成方針**（ホスティング、レンダリング方式、コンポーネント設計など）
+- **要件**（対応ブラウザ、サポートバージョンなど）
+- **動作方針**（バリデーション、ルーティング、状態管理など）
+- **表示制御**（レスポンシブ、画像など）
+- **オフライン対応**（PWAやオフライン判定方式など）
+- **認証認可**（認証方式、認可方針など）
+- **開発**（静的解析など）
+- **テスト**（テスト方針など）
+
+# 一部コンテンツの抜粋
+
+ガイドラインは**かなりのボリューム**（A4のPDFで100ページ越え…!）となっています。
+ここでは、皆さんにとくに見ていただきたいコンテンツをいくつかピックアップしてご紹介します！
+
+## ホスティング方式
+
+レンダリング方式として、**CSR**（Client Side Rendering）と**SSR**（Server Side Rendering）の特徴を比較しています。
+
+その上で、以下のように使い分けることを推奨しています。
+
+- **CSR:** 高度なインタラクティブ性など表現力が強く要求される場合や、開発のシンプルさを重視する場合に推奨
+- **SSR:** SEO効果や初期表示速度（Core Web Vitals等）が強く要求されるtoC向けサービスで推奨
+
+複数のレンダリング手法を組み合わせるハイブリッドレンダリングについては、UXや性能の最適化を目指せる一方で、開発・保守・デバッグの複雑性とコストが増加するデメリットを考慮に入れる必要があります。
+
+また、CSRにおける具体的なホスティング方式を3パターンで比較検討しています。具体的には`CloudFront+S3`、`ALB+S3`、`LB+Webサーバー`について比較しました。
+閉域対応、性能、サーバー管理、運用費用、B/Gデプロイなど多角的な評価軸で比較し、要件に応じた推奨案を提示しています。
+
+上記の例ではAWSを前提としていますが、Google CloudやAzureなど他の主要なクラウドベンダーでも同様のアーキテクチャ設計が可能です。
+
+## コンポーネント設計
+
+コンポーネントを「共通コンポーネント」と「業務コンポーネント」に分類し、それぞれの特性と役割を整理しています。
+
+- **共通コンポーネント:** アプリケーション横断的に使用される、ビジネスロジックに依存しない汎用的なUI基盤
+- **業務コンポーネント:** 特定の機能やビジネスドメインに特化した、固有のロジックを含むコンポーネント
+
+共通コンポーネントの実装については3つのアプローチを比較しています。
+
+- **既存ライブラリ活用:** Material UI、Ant Designなどのサードパーティライブラリを利用
+- **ハイブリッドアプローチ:** 既存ライブラリを拡張したり、Radix UIなどヘッドレスUIライブラリに独自デザインを組み合わせて開発
+- **フルスクラッチ:** 完全に社内で共通コンポーネントを開発
+
+それぞれのPros/Consや適用ケースを示し　**「まず既存ライブラリの活用を第一に検討することを推奨」** としています。
+
+また、コンポーネント設計でよく発生するアンチパターンの具体例も挙げ、それらに対する解決策も併せて提示しています。
+
+- **神オブジェクト:** 単一責任原則に違反した過剰な処理を行なうコンポーネント
+- **密結合:** コンポーネントが互いに過度に依存している状態
+- **ビジネスロジックとUIロジックの混在:** UIコンポーネントに過度なビジネスロジックを埋め込む問題
+
+## バリデーション設計
+
+バリデーションは、ユーザーによる誤入力を防ぎ適切なメッセージで自己修正を促すことで、**ユーザー体験（UX）を向上させるために不可欠**です。
+
+**フロントエンドのバリデーションは、ユーザーへの即時フィードバックを通じたUX向上を主目的**とします。一方で、**システムのデータ整合性維持やセキュリティ対策（XSSなど）は、サーバーサイドでのバリデーションが必須**です。
+
+バリデーションの実施タイミングには複数の選択肢があり、それぞれUXへの影響と実装コストが異なります。
+UX要件・リリース速度・開発工数を総合的に考慮し、最適なバランスの実装を選択する必要があります。
+
+また、アクセシビリティも重要な考慮点です。`disabled`なボタンはスクリーンリーダーやキーボード操作でのアクセスに問題を生じさせるため、**非活性化することは推奨されません**。ボタンを活性化したままエラーメッセージで問題を指摘するなど、アクセシブルな状態を保つよう設計しましょう。
+
+## 状態管理の設計
+
+React、Vue.jsなどのモダンフレームワークでは、アプリケーションの複雑さに応じて適切な状態管理手法を選択することが重要です。
+
+本ガイドラインでは以下の観点で状態管理手法を整理しています。
+
+- **ローカル状態 vs グローバル状態:** コンポーネント固有の状態と、アプリケーション全体で共有すべき状態の適切な切り分け
+- **状態管理ライブラリの導入判断:** Redux、Zustand、Recoilなど、プロジェクト規模や要件に応じたライブラリ選択の基準
+- **サーバー状態とクライアント状態の分離:** API通信で取得するデータと、UI固有の状態を分離する設計方針
+
+グローバル状態の過剰な利用を避けたり、必要以上にファットなライブラリを利用しないなど、状態管理のベストプラクティスを示しています。
+
+## 認証・認可の設計
+
+セキュリティの中核となる認証・認可について、フロントエンド固有の考慮事項を詳しく解説しています。業務アプリケーションで一般的な認証方式は以下の4つに大別されます。
+
+- 外部のOpenID ConnectのIDプロバイダーを利用し、フロントエンドだけで行なう
+- 外部のOpenID ConnectなどのIDプロバイダーを利用し、コールバックをサーバーで受け、サーバーがセッションCookieを発行する
+- 外部のOpenID ConnectなどのIDプロバイダーを利用し、コールバックをサーバーで受け、サーバーがJWTトークンを発行する
+- 自前でID/パスワード入力を実装する
+
+これらの認証方式について、それぞれのメリット・デメリットを比較しています。
+
+**フロントエンドにおける認可制御は**、ユーザーが権限のない操作を誤って行なわないよう、行動を制限するなど、**UX向上を目的**とします。
+
+複雑性を抑えるために、画面内におけるコンポーネントの**認可制御が可能な限り最小限になるような画面単位で設計することを推奨**します。
+
+## ブラウザ対応戦略
+
+ブラウザ機能の採用について、[Web Platform Baseline](https://developer.mozilla.org/ja/docs/Glossary/Baseline/Compatibility)という客観的な指標を活用した判断基準を示しています。
+
+- **Widely Available:** 安心して利用できる（利用推奨）
+- **Newly Available:** 総合的判断で採用（Experimentalでなければ基本OK）
+- **Limited availability:** 本番環境での採用は見送り推奨
+
+また、サポートするブラウザに関しては、構築するシステムの要件を考慮したうえで、**ミニマムに絞ることを推奨**します。
+
+## テスト方針
+
+品質の高いWebアプリケーションを継続的に提供するため、適切なテスト戦略の策定が重要です。本ガイドラインでは、フロントエンド開発と相性が良いとされる **「テストトロフィー」の考えに基づき、テスト設計の方針を示して**います。
+
+テストピラミッド（高速なユニットテストを土台とする従来の考え方）に対して、テストトロフィーはコンポーネント/インテグレーションテスト（ユーザー視点での動作検証）をより重視します。ユニットテストは実装の詳細に依存し脆く、E2Eテストはコストが高いため、過度に依存しないバランスの取れたアプローチを推奨しています。
+
+# まとめ
+
+[Webフロントエンド設計ガイドライン](https://future-architect.github.io/arch-guidelines/documents/forWebFrontend/web_frontend_guidelines.html)は、現代の複雑化したフロントエンド開発における設計判断を支援し、知見共有を促進することを目的として作成しました。単なる技術Tips集ではなく、**ビジネス要件と技術選択のバランスを重視し、開発チームの状況に応じた実践的な指針を提供**しています。
+
+ぜひ一度ガイドラインをご覧いただき、皆さまのプロジェクトにお役立てください。
+
+また、本ガイドラインは公開後も継続的にアップデートしていく予定です。**社内外問わずPRは大歓迎**ですので、ぜひ[設計ガイドライン(GitHub)](https://github.com/future-architect/arch-guidelines)からご協力ください。
+
+他にもたくさんのガイドラインがございますので、ぜひご覧ください！
+
+- [ガイドラインの記事一覧](/tags/%E3%82%AC%E3%82%A4%E3%83%89%E3%83%A9%E3%82%A4%E3%83%B3/)
+- [ガイドラインのトップページ](https://future-architect.github.io/arch-guidelines/)