frontend-ui-standards

フロントエンド UI の標準

目的

このスキルを使って、UI 作業を体系的なフロントエンド実装へとつなげます。目標は、ピクセル単位で調整することではありません。コードでデザインシステムを維持し、今後の変更も予測しやすく、再利用可能で、視覚的に一貫性のある状態に保つことです。

このスキルは特定のフレームワークに依存しません。ルールを各プロジェクトの技術スタックに合わせて適用してください。

• SwiftUI：デザイン トークンを列挙型や静的定数として定義し、再利用可能な View とセマンティックな寸法を使います。
• React/Web：CSS 変数、デザイン トークンのモジュール、コンポーネントの props／バリアントを使います。
• React Native/Flutter：テーマオブジェクト、共有コンポーネント、セマンティックな寸法を使います。

使用するタイミング

次のような作業で UI に手を加える前に、このスキルを使ってください。

• 画面、コンポーネント、レイアウト、インタラクションを新規作成または変更する。
• Figma、SVG、スクリーンショット、ビジュアル仕様をコードに反映する。
• 位置ずれ、テキストの切り詰め、間隔の不統一、フォントの誤り、ボタンサイズの誤り、セーフエリアの問題など、見た目の不具合を修正する。
• ボタン、カード、チップ、タブ、ナビゲーションバー、シート、ダイアログ、リスト、進捗インジケーター、入力フィールド、読書用画面を新規作成または変更する。
• フロントエンドのコードが本番運用に適しているか、デザインに一貫性があるかをレビューする。
• 重複した UI や、あちこちに散在するハードコード値をリファクタリングする。

ユーザー向け UI に影響しない限り、純粋なバックエンド、データモデル、プロンプト、インフラストラクチャの作業には使わないでください。

基本原則

UI コードは次の 3 つのレイヤーで構成されます。

1. デザイン トークン：色、タイポグラフィ、間隔、角丸、エレベーション、セーフエリアのオフセット、コンテンツ幅などのグローバルな基本値やセマンティックな値。
2. コンポーネントの寸法：チップの高さ、アイコンサイズ、内側のパディング、カードヘッダーの間隔、ボタンのバリアントなど、コンポーネント固有の構造。
3. 画面レイアウトの寸法：ヒーローカードの位置、セクション間の間隔、繰り返し行の位置合わせ、装飾アセットの配置など、画面固有の構成。

View のコードでは構造と状態を表現してください。View 本体に生のデザイン計算を埋め込まないでください。

実装ワークフロー

1. 既存パターンを調べる

   • 新しい UI を追加する前に、最も近い既存コンポーネントと画面を探します。
   • プロジェクト内のデザイン トークン、テーマ、コンポーネントライブラリ、レイアウトヘルパーを特定します。
   • 同じ視覚要素がほかの場所ですでに使われていないか確認します。

2. すべての視覚的な値を分類する

   • グローバルで再利用可能：デザイン トークンに追加します。
   • コンポーネント固有：コンポーネントの寸法オブジェクトまたは列挙型に追加します。
   • 画面固有で、その画面内で繰り返し使う値：画面レイアウトの寸法に追加します。
   • 一度限りの装飾的な位置指定：View 本体に直接記述せず、名前を付けた画面の寸法として独立させます。

3. 再利用を基本に構築する

   • 新しいコンポーネントを作るより、既存コンポーネントのバリアントを拡張することを優先します。
   • 同じ視覚的役割を持つ要素を 2 か所で使う場合は、同じコンポーネントまたは寸法を共有します。
   • 新しいコンポーネントがすぐに繰り返し使われるようになったら、ただちに切り出します。

4. レイアウトの関係性をコード化する

   • 数値を重複させるより、導出した値を優先します。
   • 例：無関係な幅を 3 つ定義するのではなく、authorChipWidth = rowWidth - sourceChipWidth - rowGap とします。
   • 関連する要素は、コンテナ、グリッド、レイアウトガイド、または名前を付けた寸法を共有して位置を合わせます。
   • そのオフセットが名前を付けた装飾上の例外でない限り、1 つの要素だけを局所的にずらして位置ずれを直さないでください。

5. 類似する画面要素を確認する

   • 1 つのボタン、カード、ヘッダーを修正したら、同じラベル、コンポーネント、アセット、パターンが使われている箇所を検索します。
   • 可能であれば共有コンポーネントを更新します。
   • 一度限りの実装を残す場合は、わかりやすい寸法名または短いコメントで理由を記録します。

6. ビルドし、見た目を簡単に確認する

   • 該当するビルドや型チェックを実行します。
   • モバイル UI の場合、ユーザーが見た目を検証しているときは、シミュレーターまたはデバイスにインストールして実行します。
   • テキストの切り詰め、セーフエリア、タッチターゲット、動的テキストによるリスク、ナビゲーションや戻る操作の挙動を確認します。

トークンとメトリクスのルール

視覚的な座標より、意味のある名前を優先します。

• 良い例：primaryActionWidth、screenHorizontalInset、cardVerticalSpacing、metadataRowWidth、sourceChipWidth。
• 悪い例：width: 271、padding(.leading, 12)、ビュー本体内で繰り返されるoffset(y: 37)。

許可される数値：

• トークンやメトリクスの定義内では、数値を使用できます。
• 名前付きメトリクスのセクションにまとめている場合、単発のアセットのジオメトリには数値を使用できます。
• リテラル値が必要なプラットフォーム API を使用し、その値がビジュアルデザインに関係しない場合は、数値を使用できます。

避けること：

• 生の16進カラー値をあちこちに記述する。
• タイプスケールがあるのに、フォントサイズをインラインで指定する。
• スペーシングスケールから取得すべき間隔をインラインで指定する。
• 同じボタン、チップ、トップバー、カード、ボトム CTA のローカル版を複数作る。
• 共通コンポーネントの問題を、1つの呼び出し箇所だけで修正する。

コンポーネントの再利用ルール

UI を作成する前に、次の点を確認してください。

• 新しいビジュアル上の役割ですか、それとも既存の役割のバリエーションですか？
• 既存のコンポーネントですでに、操作、サイズ、影、角丸、タイポグラフィが定義されていますか？
• 別の画面にも表示されますか？
• 新しいファイルではなく、コンポーネントのプロパティやバリアントにするべきですか？

次の場合は、コンポーネントのバリアントを作成してください。

• 構造は同じで、色や状態が異なる場合。
• ボタンの形は同じで、テキストやアイコンが異なる場合。
• カードの枠は同じで、内容が異なる場合。
• チップは同じで、ラベルやアイコンが異なる場合。

次の場合に限り、新しいコンポーネントを作成してください。

• 構造、動作、またはレイアウト上の役割が明確に異なる場合。
• 既存のコンポーネントを拡張すると、わかりにくくなったり壊れやすくなったりする場合。

Figma からコードへのルール

Figma、SVG、スクリーンショット、ビジュアル仕様を使用する場合：

• Figma の数値は入力の根拠として扱い、最終的なコード構造とはみなしません。
• まず、繰り返し使われているプリミティブ（色、タイポグラフィ、角丸、影、間隔、コンテンツ幅）を特定します。
• 繰り返し使われているプリミティブを既存のトークンに対応付けるか、新しいセマンティックトークンを追加します。
• 繰り返し使われている UI 要素を、既存のコンポーネントまたはコンポーネントのバリアントに対応付けます。
• デザインが本当にイラスト的・装飾的な場合や、プラットフォームのレイアウトモデルで必要な場合に限り、絶対配置を使用します。
• 座標をそのままコピーするのではなく、階層と要素間の関係を維持します。

Figma で2つの要素の位置がそろっている場合は、共通のコンテナ、グリッド、幅、または派生メトリクスを使用して、コード上でも同じ位置合わせを表現します。

タイポグラフィのルール

• まず、プロジェクトのタイプスケールまたはプラットフォームのテキストスタイルを使用します。
• テキストの階層は、サイズ、ウェイト、色、間隔によって視覚的に示します。
• モバイルの本文は読みやすさを保ち、意味のある内容に小さすぎるラベルを使用しないでください。
• ユーザーが読む必要のある内容には、折り返しを優先します。
• 省略表示は、メタデータ、ラベル、ユーザー名、著者名、または意図的にスペースが制限されているサイズ固定のチップに限って使用します。
• 省略表示を使う場合は、適切なコンポーネント内でテキストの範囲を制限します。テキストのサイズ変更や、周囲のレイアウトの押し出しが起きないようにしてください。

レイアウトと間隔のルール

• ページのインセットとコンテンツの最大幅を統一します。
• セーフエリア、ノッチ、ホームインジケーター、キーボードの挙動を考慮します。
• 画面下部の主要アクションは、プロダクト内で幅と垂直位置を統一します。
• 戻る、閉じる、通知、お気に入りなどの上部 UI 要素には、共通の配置方法を適用します。
• 同じファミリーのカードでは、幅、角丸、影、コンテンツのパディング、スペーシングのリズムといった枠のメトリクスを統一します。
• デザインで明示的に内包カードを使用していない限り、カードを入れ子にしないでください。

操作のルール

• タッチターゲットは、iOS では44pt以上、その他のプラットフォームでは同等のサイズにします。
• アイコンのみのボタンには、アクセシブルなラベルが必要です。
• 破壊的な操作には、明確な確認または取り消し手段が必要です。
• 読み込み中、再試行中、無効、空、エラーの各状態を明示します。
• 可能な場合は、戻る操作の挙動をユーザーの画面への遷移経路に合わせます。
• タップ可能な範囲をユーザーの期待に合わせます。行やカード全体が操作対象なのに、小さなアイコンだけにタップを限定しないでください。

レビューチェックリスト

UI の作業を終える前に、次の点を確認してください。

• 新しいコンポーネントを追加する前に、既存のコンポーネントを検索しましたか？
• 色、タイポグラフィ、間隔、角丸、シャドウはトークン化されていますか？
• コンポーネント内部の値は、インラインの本文値ではなく、コンポーネントのメトリクスに定義されていますか？
• 画面固有のレイアウト値は、まとめて名前が付けられていますか？
• 関連する幅や位置は、単一の信頼できる情報源から導出されていますか？
• 同じファミリーのコンポーネントをすべて更新しましたか？更新しなかった場合は、その理由を説明していますか？
• テキストは、意図しない省略なしに収まっていますか？
• タッチターゲットとセーフエリアを考慮していますか？
• 関連するビルド／型チェックを実行しましたか？
• ビジュアルの仕上げであれば、可能な場合にアプリをインストールして実行するか、スクリーンショットを撮りましたか？

よくあるアンチパターン

• 共有コンテナーを確認せずに、「ここを 8px 下に移動する」。
• この画面は「少し違う」という理由で、ボタンの実装を複製する。
• Figma の座標をそのままビューの本文にコピーする。
• あるラベルの見た目がおかしいという理由で、ローカルのフォントサイズを追加する。
• ある画面で幅を修正する一方、同じコンポーネントがほかの画面では壊れたままにする。
• 本番 UI で、モックだけに当てはまるレイアウト上の想定を使う。
• 文字数の上限や省略方法を決めずに、生成テキストやバックエンドのテキストに UI レイアウトを左右させる。

ローカルの例外が許容される場合

例外は、意図的で影響範囲が限定されている場合に許容されます。

• 1 つの画面だけで使う装飾アセット。
• その場限りのアートディレクションを伴う、マーケティングまたはエディトリアルのレイアウト。
• 現在の変更で完全なコンポーネント抽出を行うのはリスクが高すぎる場合の、移行中のリファクタリング。
• ローカルでの調整が必要となる、プラットフォーム固有の制約。

その場合も、値は名前付きのメトリクスオブジェクトに保持し、例外は最小限にしてください。