evolving-design-system-components

デザインシステムコンポーネントの進化

このスキルでは、Bitwarden のガバナンスに関する次の 2 つのページに基づいて、コンポーネントライブラリの作業を進めます。 新しいデザインパターンの作成 および 既存のデザインシステムコンポーネントの変更。 実際の提案を進める前に、get_confluence_page を使って正式なページを確認してください。このスキルよりも速いペースで更新されるほか、以下で参照するテンプレートの Figma ファイルやエンジニアリングプロセスへのリンクが掲載されています。Figma の規約（プロパティの順序、命名規則）は references/figma-conventions.md にあります。

2 つの進め方

ガバナンスのフローは 2 種類あります。共通の開始部分の後、分岐します。

• 新しいパターンの作成。 まだ存在しないパターンです。ユースケースと複雑さに基づき、「コアコンポーネント」か「レシピ／スノーフレーク」かの判断で分岐します。
• 既存コンポーネントの変更。 すでに存在するパターンです。製品内の各インスタンスに影響するため、必ず UI Foundation チームを通します。

このスキルでは両方の進め方を説明します。必要な手順を提案する前に、どちらに該当するか確認してください。レビューのゲートが異なります。

ステップ 1：まず検索してから提案する

どちらの進め方でも、パターンがすでに存在するか確認します。「新しいコンポーネントが必要だ」という判断で最もよくある誤りは、「実はライブラリに存在しているのに、デザイナーが見つけていない」ことです。

using-figma の search_design_system と get_libraries を使います。類似するものが見つかった場合は、そのまま使うのか、変更するのか（進め方 B）、それともその下に新しいバリエーションを提案するのかを検討します。一致するものがなければ、次に進みます。

ステップ 2：チームとニーズを特定する

どちらの進め方でも、エンジニアリングが関わる前に、まずデザインチーム内で合意します。Confluence のページによると、手順は次のとおりです。

• デザイナーがニーズを特定し、機能ファイル内に新規または変更するパターンのドラフトを作成します。
• デザイナーがデザインチームと共有します。スケジュールに応じて、チームで反復するか、個別にドラフトを作成した後でチームが批評します。
• デザインチームは、進め方に応じて次の 3 つまたは 4 つの質問に基づいてレビューします。

新しいパターンの場合：

• どの既存パターンを検討しましたか？それらが適さないのはなぜですか？
• 新しいパターンはどのような価値をもたらしますか？
• 既存のデザイン／ブランドガイドラインに沿っていますか？
• 他にどのようなユースケースがありますか？複数の場所で使用できますか？

変更の場合：

• 見た目は改善されますか？
• コンポーネントのユースケースは広がりますか？
• 他の UI パターンと一貫していますか？
• 製品内のコンポーネントの各インスタンスにどのような影響がありますか？
• 他に影響を受ける可能性のあるコンポーネントやパターンはありますか？

チーム内で、提案をさらに進める前に合意します。「新しいデザインパターンの作成」ページには 新しいパターンの検討用 Figma テンプレート へのリンクがあります。提案者が独自の検討構成を用意していない場合は、このテンプレートを案内してください。

ステップ 3（新しいパターンのみ）：コアかレシピ／スノーフレークか

この判断は UI Foundation チームと行います。提案するデザイナーが単独で決めることはありません。

• コアコンポーネントライブラリの候補。 多くのユースケースがある場合、または単一の機能チームでは保守が難しいほど複雑な場合です。UI Foundation が所有する、ライブラリの正式なコンポーネントになります。
• レシピ／スノーフレーク。 ユースケースが少ない場合、または特定の機能領域に固有の場合です。作成した機能チームが所有します。他のデザイナーが見つけられるよう、Figma ライブラリには追加します。

UI Foundation との話し合いを設定し、ユースケースを確認します。所有権については UI Foundation の判断に従ってください。Confluence ページでは、エンジニアリング側の手順として 新しいコンポーネントの作成 が参照されています。コアの進め方を選んだ場合は、このページを読んでください。

ステップ 4：Figma ライブラリで構築する

Figma 側のプロセスには、あらかじめ定められた方針があります。プロパティの順序、命名、必須の状態、ドキュメントのパターンといった規約は、references/figma-conventions.md に記載されています。大まかな手順は次のとおりです。

• Tailwind Component Library の Figma ファイルを開きます。
• コンポーネント／パターンの名前を付けた新しいブランチを作成します。
• 新しい（または変更した）UI パターンを Figma コンポーネントとして追加します。新しいコンポーネントの場合は専用ページに、変更の場合は既存コンポーネントのページに配置します。
• インタラクティブなコンポーネントでは、少なくともデフォルト、ホバー、フォーカス、アクティブ（該当する場合）、無効（該当する場合）の状態を用意します。
• CL API design docs と既存の Figma プロパティのパターンに従って、Figma プロパティに名前を付けます。プロパティの順序は重要です。references/figma-conventions.md を参照してください。
• コンポーネントの隣に、使い方、動作、バリアント、アクセシビリティに関する注記を含むコンポーネントドキュメント用のフレームを作成します。ゼロから作成するのではなく、既存コンポーネントのドキュメントをコピーして調整するのが慣例です。
• 変更の場合は、変更点を記した Figma コメントを、変更した各コンポーネントに残します。

ステップ 5：レビューの承認条件

• 新しいパターン。 ブランチを Design チームに送り、レビューを依頼します。
• 変更。 ブランチを Design チームに送り、チームの同期会でもレビューします。マージする前に、少なくとも他のデザイナー 2 名の承認が必要です。
• チームの同期会で UI Foundation のエンジニアリングチームと変更をレビューします。
• まだ作成されていない場合は、Component Library ボードに Jira 課題を作成します。次回の同期会で UI Foundation のエンジニアリングチームと優先順位を決めます。

ステップ 6：マージのタイミング — Figma とコード

デフォルトでは、エンジニアリングによるコードの更新が完了するまで Figma ブランチのマージを待ちます。これにより、製品にはまだ存在しない UI が Figma に表示されるのを防げます。ただし、例外もあります。

• デザイナーが今すぐ変更を必要としている場合。 Figma でコンポーネントのドキュメントに、エンジニアリングの進捗状況を示す警告バッジを追加して Figma ブランチをマージし、#team-eng-ui-foundation でエンジニアリングチームに最新情報を伝えます。
• ブランチの保守が煩雑すぎる場合。 同じ例外が適用されます。警告を付けてマージし、周知してください。

基本は規律ある順序に従います。例外は必要な場合に限って使用してください。

他のスキルとの組み合わせ

• using-figma。 提案前の検索には search_design_system と get_libraries を、既存コンポーネントの調査には get_metadata と get_variable_defs を使用します。パターンを Core Component に昇格させる際のデザインとコードの連携には、Code Connect ツール（get_code_connect_map、add_code_connect_map、get_context_for_code_connect）を使用します。
• facilitating-design-critique。 ステップ 2 におけるデザインチームの合意形成は、単発のメッセージではなく、批評セッションで行います。提案者がセッションの進め方を組み立てるサポートを必要とする場合は、批評ファシリテーションのスキルに引き継ぎます。
• navigating-design-jira-process。 Component Library の Jira ボードは、より大きな Product and Design の Jira ワークフローの一部です。提案によってエンジニアリング作業が発生する場合は、適切なステータス変更について Jira プロセスのスキルに引き継ぎます。

よくある落とし穴

• 提案前の検索を省略する。 まず search_design_system を使います。必ず実行してください。
• Core／Recipe の判断をデザイナーだけで行う。 この判断には UI Foundation との協議が必要です。先走って決めないでください。
• CL API の規約に合わないプロパティ名。 命名が一貫していないと、チーム全体でのライブラリの使いやすさが損なわれます。独自に判断せず、CL API design doc を確認してください。
• 早期マージ時に警告バッジを省略する。 例外を適用する場合は、Figma の警告バッジと #team-eng-ui-foundation へのメッセージの両方が必須です。任意ではありません。
• 連絡せずに、エンジニアリングより先に Figma の変更をマージする。 後続のデザイナーは、製品にはまだ存在しない UI を目にし、それを土台に作業してしまいます。

出力形式

パターンの提案やコンポーネントの変更を求められた場合：

1. パス — 新しいパターンまたは変更内容。
2. 検索結果 — ライブラリ内にすでにある、関連または重複する項目。
3. デザインチームとの調整計画 — デザインレビューに持ち込む内容と、チームで検討する質問。
4. コアとレシピの判断（新しいパターンのみ） — UI Foundation での議論の進め方。
5. Figma の計画 — ブランチ名、ページの配置、必要な状態、プロパティの順序、ドキュメント用フレーム。
6. レビューの流れ — 必要なデザイナーの承認、UI Foundation のレビュー、Component Library の Jira 課題。
7. マージのタイミング — 通常または例外。例外の場合は、警告バッジと連絡の手順も記載します。