ダークモードロールアウトプレイブック
このプレイブックは、各チームが自分たちの責任範囲でダークモードを実装・維持するための期待値、ワークフロー、ガイダンスをまとめたものです。
ダークモードは一般提供されており、機能成熟度ガイドラインに沿った正式なサポートが必要です。このプレイブックは、採用を継続するチーム、ロングテールの課題を修正するチーム、今後の作業でも互換性を確保するチームのリファレンスとして機能します。プロダクトチームは、モードを使ったデザインの方法を理解し、ダークモードのデザイン原則を適用することで、自身の領域が一貫性のあるダークモード体験を提供することに最終的な責任を負います。
このプレイブックに従うことで、チームは今日の高品質なダークモード体験に貢献できるだけでなく、今後それを維持・強化し、他のモードにも対応するために必要な専門知識を構築できます。
はじめに
まずは、次の定義と概念に慣れることから始めましょう。ダークモードは、カラーデザイントークン、Pajamas デザインシステムコンポーネント、色使いのデザイン原則などの概念を正しく一貫して使用した実装に基づいてこそ、最も成功します。目標は、何かが間違っているか欠落しているかを見つけられるようになるだけでなく、自分の担当プロダクト領域でいつ・どのように独自のソリューションを設計・実装するかを知ることです。
ダークモード
ダークモードは、ユーザーインターフェース（UI）デザインの重要な機能となり、暗い背景に明るいコンテンツを配置することで眼の疲労を軽減し、可読性を高め、システム全体の設定との連続性を保ちます。私たちのダークモードビジョンを紹介する ブログ記事 を参照してください。
デザイントークン
デザイントークン は、デザイン判断とデザインシステムのオプションを対応付ける方法論です。ダークモードのロールアウトでは、特にセマンティックデザイントークンに焦点を当てます。具体的には、デザイン判断を表現するために定数のカラーデザイントークンを参照するセマンティックカラーデザイントークンです。これらが特に価値があるのは次の理由からです:
- 定数デザイントークンを参照して、テキスト、アイコン、ボーダー、サーフェスなどの要素に対してグローバルなデザイン判断を定義する。
- 具体的な値ではなくデザイン意図と適切な使用法を伝える命名戦略を採用しており、生の値と実装の間に抽象化レイヤーを作り出す。
- ライトモードとダークモードの両方の値を持つため、異なるコンテキストにプロパティを適応させても一貫した意味を保つ。
このセマンティックなアプローチにより、特定のビジュアル値が変わっても本来の目的を保ちながら、どのモードでもデザイン判断が一貫して適用されることが保証されます。
Pajamas デザインシステム
Pajamas は GitLab のデザインシステムであり、GitLab プロダクト全体で一貫したユーザーインターフェースを構築するための標準化されたコンポーネント（モード切り替え機能を含む）、パターン、ガイドラインを提供します。タイポグラフィ、色、スペーシング、インタラクティブコンポーネントなどの要素に関する詳細な仕様を含み、デザイナーと開発者が一貫したプロダクト体験を作成しながらデザインの複雑さを軽減できるようにします。
GitLab のダークモード設定
認証後、https://gitlab.com/-/profile/preferences にアクセスしてダークモード体験をオンにします。Appearance 見出しの下で、Dark (Experiment) または（システム設定としてダークモードを使用している場合は）Auto (Experiment) を選択してください。
ヘルプを得る
Design System Group がサポートを提供しています。プロダクト内でメンションするか、Slack の #g_pajamas-design-system チャンネルで連絡できます。
評価
プロダクトページを評価する核となる目的は二つあります:
主目的: 最もよく使われるページがダークモードに対して適切に設定され、今後のテーマ変更にも最小限の介入でスムーズに対応できることを保証する。これには、ビジュアルデザインの選択とその技術的実装の両方を検証する必要があります。
副次目的: テーマ設定の概念に対する理解を深め、デザインシステムに沿った情報に基づくデザインおよび実装判断ができるようになる。
これらの目標を達成すると、いくつかの利点が得られます:
- より統一感のある、一貫したプロダクト体験。
- デザインシステムの更新がシームレスに伝播する。
- ダークモードをベータから一般提供に移行する自信。
評価の過程で、ダークモードに直接影響しない改善機会も発見する可能性があります。一部の変更はユーザーにすぐには見えないかもしれませんが、アクセシビリティを高め、コンポーネントやデザインシステムの遵守を改善し、デザインシステムを拡張すべき領域やカスタムソリューションのガイダンスが必要な領域を特定するのに役立ちます。
ツール
Chrome、Figma、GDK、GitLab Duo などの日常的なツールに加えて、以下のツールが特に役立ち、以下のステップで主に取り上げられます。なお、自分やチームがより慣れているツールや方法をいつでも使うことができますが、結果は同じであるべきです。
- Hot pink ブックマークレット: ルートレベルで定義されたすべての色関連 CSS 変数（「
--gl」で始まるものを除く）を見つけて hotpink に変更するブラウザブックマークレットです。デザイントークンを使用していない要素を簡単に視覚化できます。 - Highlighter Chrome 拡張機能: 指定された CSS クラス、クラスプレフィックス、クラスサフィックスに一致する UI 要素をハイライトする Chrome 拡張機能です。有効化すると、一致する要素を赤（色はカスタマイズ可能）でアウトラインし、ページ上で見やすくします。
- Claude AI: さまざまなプロンプトを使用してコードを検査するのに役立つ AI アシスタントです。
- Vue.js devtools ブラウザ拡張機能: Vue コンポーネントを簡単に検査し、ボタンをワンクリックで好みの IDE（例: VSCode）で直接開けるため、対応するファイルを素早く見つけられます。
ステップ
前提条件として、プロダクト領域内で最もよく使われる/重要なページとその UI 状態のリスト（例は下記の参照セクションを参照）を記述に含めたエピックを作成してください。このリストは、すべてのロールがすべてのステップで使用します。プロダクトや GDK 内でページや UI にアクセスするために必要なリンク、手順、設定要件を含めてください。エピックから始めることで、後から発見事項を個別の Issue として追跡できるため便利です。
スクリーンショットに注釈を付けるために複製・使用できるテンプレートが Figma と FigJam の両方に用意されています。Figma にアクセスできない場合は、GitLab の Design Management 機能を使用してスクリーンショットをアップロード・注釈付けしてください。
1. ビジュアルレビュー
担当者: プロダクトデザイナーとフロントエンドエンジニア 成果: 色にデザイントークンを使用していないことが目に見える UI 部分を特定し、必要に応じて修正案を提示します。
- ブラウザで Hot pink ブックマークレット を有効にした状態で、リストのページを表示します。ブックマークレットを有効にするには開いているページを更新する必要がありますが、今後のページ読み込みでは不要です。
- ページのスクリーンショットを撮ります。ドロップダウン、ツールチップ、折りたたまれたコンテナ、エラー状態などの隠れた要素を表示することを忘れないでください。ページによっては、空の状態と入力済みの状態、レスポンシブレイアウトの変化などさまざまな条件をテストする必要があるかもしれません。実際の見た目と発見事項を比較するため、ホットピンクのハイライトありとなしの両方のスクリーンショットを撮影すると便利です。
ホットピンクのハイライトなしとありの UI - Figma、FigJam、または GitLab Issue でスクリーンショットに注釈を付け、要素を以下のカテゴリーのいずれかに関連付けます（例は Figma および FigJam ファイルで確認できます）:
- 特にダークモードに関連する既存の Pajamas ソリューションのアイデア。 これらの注釈は、ハードコードされた色や定数の代わりにセマンティックカラーデザイントークンの使用を提案するか、セマンティクスと意図に合わせて現在適用されているものとは異なるデザイントークンの使用を提案するものです。
- 独自のダークモードまたはデザインシステムソリューションに関する議論。 これには、既存のデザイントークンが適合しない UI 部分や、新しい何かが必要な場所が含まれます。また、カスタムソリューションを既存の Pajamas コンポーネントに置き換える議論も含まれます。
- 他の人へのメモ。例: デザインシステムチームのソリューション候補や修正すべき小さな問題。 デザインシステムで上流側で修正できる項目や、軽微なリファクタリングでダークモード実装をよりシームレスにできる項目に気付いたらメモを残します。
Figma 上で注釈付けされたスクリーンショット
- エピックの下で、各発見事項ごとに Issue を作成します。
よくある発見:
- アイコン専用のものではなく、テキスト用のデザイントークンを使用しているアイコン。
- セマンティックデザイントークンの代わりにハードコードされた色や色の定数を使用している要素。
- ステータス、フィードバック、アクションなど、現在のセマンティックデザイントークンカテゴリーに当てはまらないカスタム要素。
- ビジュアル表現に影響するスタイルオーバーライドを持つ要素。
- テキストで 4.5:1、グラフィック要素で 3:1 を下回るカラーコントラストの問題。
2. 要素検査
担当者: プロダクトデザイナーとフロントエンドエンジニア 成果: コード内でデザイントークンを正しく使用していない一般的な要素（例: テキスト、アイコン、ボーダー）を特定し、修正案を提示します。
- ページ上のさまざまな要素とその使われ方に慣れます。開発者ツールで要素を検査し、ビジュアル表現が目的と意図に合致していることを確認します。例:
- アイコンがある場合、ステータス、ヘルプ、フィードバック、静的なビジュアル要素など、何に使われていますか? 使われているデザイントークンはデザイン意図に一致すべきです。
- ボーダーは区切り線として使われていますか、それともコンテナを囲むために使われていますか? 期待される組み合わせと一致していますか? （ボーダーと背景の使用についてより明確にするこの マージリクエスト を参照してください。）
- コンポーネントのように見えるけれど本当にそうですか? もしそうなら、正しく使用されていますか? そうでなければ、コンポーネントに移行できますか?
- Highlighter 拡張機能を有効にした状態で、クラス名、プレフィックス、サフィックスを入力して一致する要素をハイライトします。
Highlighter 拡張機能とハイライトされた要素
ハイライト されていない ものも、ハイライトされているものと同じくらい重要であり、見た目はあるものだが実際は別物であるものを示す可能性があることに留意してください。このような要素は、モード変更に期待どおりに反応しないか、将来のデザイン変更に従わない可能性が高いです。CSS の カスケーディング 部分のため、すべてが期待どおりにハイライトされるわけではなく、計算されたスタイルを判断するためには開発者ツールが引き続き役立ちます。クエリの例:- 「gl-link」と入力してすべてのリンクをハイライト。
- 「gl-form-*」と入力してフォーム要素のように見えるすべての要素が本当にフォーム要素であるかを確認。
- 「gl-text-*」と入力してアイコンがテキストスタイルを使用していないかを確認。
- ページソースをコピーして Claude に貼り付け、プロンプトを実行します。プロンプト例:
- 「.gl-」を含まない CSS クラスを使用するすべての要素をリストアップする。
- 「gl-text-」で始まるクラスを持つ要素の下にネストされた SVG 要素はあるか?
- ビジュアルレビューのスクリーンショットに、以前に記載されていなかった項目の注釈を追加します。
- エピックの下で、新しい各発見事項ごとに Issue を作成します。
よくある発見:
- アイコン専用のものではなく、テキスト用のデザイントークンを使用しているアイコン。
- 期待される組み合わせと一致しない背景とボーダーのデザイントークンのペアリング。
- 見出しデザイントークンを使用していない見出しや、それを使用している見出しでないテキスト。
- コンポーネントのように見えるがそうでない要素。
- コンポーネントだが、オーバーライドによって期待どおりに表示されない要素。
3. コードレビュー
担当者: エンジニア 成果: 移行が必要なコンポーネント、コンポーネントではないがコンポーネントであるべきもの、コンポーネントを誤って使用しているか持続不可能なオーバーライドを持つものを特定します。
- ページのコードベース構造とコンポーネント使用をレビュー:
- コンポーネントが Pajamas デザインシステム（@gitlab/ui）からインポートされているか、カスタム実装かを確認。
- Pajamas に同等品があり移行すべきレガシーコンポーネントを特定。
- 開発者ツールと自動分析を使ってコンポーネント実装を検査:
- デザインシステムでの誤用や欠落を示唆する可能性のある、広範な CSS オーバーライドを持つコンポーネントを確認。
- テーマ継承の問題を引き起こす可能性のあるネストされたコンポーネントを探す。
- コンポーネントが適切な props を受け取り、デザインシステムのテーマコンテキストを正しく使用していることを検証。
- Claude や GitLab Duo を使って、次のようなプロンプトでコードベースを分析:
- 3 階層を超える CSS クラスオーバーライドを持つコンポーネントを見つける。
- ダークモードをサポートするデザイントークンではなく、直接的な色の値（hex コード、rgb など）を使用しているコンポーネントや SVG を見つける。
- コンポーネントが他のコンポーネント内にネストされ、ダークモードの継承を壊す可能性のあるインスタンスを見つける。
- ビジュアルレビューのスクリーンショットに、以前に記載されていなかった項目の注釈を追加します。
- エピックの下で、新しい各発見事項ごとに Issue を作成します。
よくある発見:
- 直接的な Pajamas 同等品があるが移行されていないレガシーコンポーネント。
- 広範なオーバーライドを持つコンポーネントで、再考すべきもの。
- 予期しないテーマ継承を引き起こすネストされたコンポーネント。
- デザイントークンの代わりにハードコードされた色の値を使用するコンポーネント。
追加の発見
前述のとおり、このプロセスを進めると、アクセシビリティ、デザインシステム遵守を改善する他の機会や、デザインシステムを拡張すべきまたはガイダンスを提供すべきギャップを発見する可能性が高いです。これらの発見も他の注釈と一緒に記録できます。関連する AI プロンプトとともに、追加で探すべきこともいくつかあります:
- 順序が崩れている、または欠落している見出しを見つける: 見出しを順に列挙し、レベルを含める。
- アクセスできないフォーム要素を特定する: ラベルが欠落または問題があるフォーム要素をリストアップする。
- Pajamas コンポーネントを使用するインスタンスを見つける: 既存の Pajamas コンポーネントと類似の機能を実装するカスタムコンポーネントをリストアップする。
- パターンを抽象化する機会を探す: 共有コンポーネントに抽象化できる繰り返しのスタイルパターンを特定する。
発見事項への対応
はじめに のコンテンツとリファレンスに慣れ、ページの優先順位付けを行い、各発見事項に対する Issue を作成し終えたら、これらの発見事項への対応への道のりを順調に進んでいます。
- 既存の Pajamas ソリューションが利用できる場合はそれを使用してください。適切なトークンの選び方については Pajamas のデザイントークンドキュメント を参照してください。
- 既存のソリューションが適用されない UI のカスタム部分がある場合、または既存のデザインシステムソリューションへの移行方法や可否がわからない場合は、議論を始めてください。
- ダークモードがプロダクト領域に適用されるのを妨げる、デザインシステムの上流修正や単純な小さな修正を手伝ってください。
途中で行き詰まったり、セカンドオピニオンやレビューが必要になった場合は、Design System グループに連絡してください。
参照
bfd74782)