デザインシステム103: 導入を促進するドキュメント

Razorpayのチームが細部を見落とした際、デザイン部長のSaurabh Soni氏は、それが品質の問題ではなく、コミュニケーションの問題であると気づきました。「Blade (当社のデザインシステム)を導入する前、チームはさまざまなボタンの状態やテキストフィールド内のエラーの処理方法など、多くの小さなニュアンスを簡単に見落としていました」と彼は言います

。「チームはハードコード化してすべてをカスタムにしようとしていました。そうすることで、何かを誤って見逃していたかもしれません。」

このような課題は、組織全体で共通しています。「デザイナーと開発者が話す言語は、少し異なっているのです」と、GitHubのスタッフシステムデザイナー、Lukas Oppermann氏は説明

します。この言語的なギャップは、命名規則の不一致、コンポーネントプロパティの不整合、製品の見た目や雰囲気に対する期待の不一致を引き起こすことがよくあります。良いドキュメントは、このギャップを埋め、意図と実装を繋ぐ役割を果たします。しかし、コンポーネントをカタログ化するだけでは不十分であり、デザイン上の決定の背後にある経緯と理由を捉える必要があります。この包括的なガイダンスがなければ、慎重にデザインされたシステムでさえもデジタルの埃をかぶってしまうのです。

良いドキュメントを作成すれば、チームは以下を実現できます。

• デザイン原則と実装の詳細を理解する
• 製品およびプラットフォーム全体で一貫した意思決定を行う
• 新しいチームメンバーを効率的に迎え入れる
• デザイナーと開発者のコミュニケーションをつなぐ

信頼できる情報源を特定する方法

最初の問題は、何を書くかではなく、それをどこに配置するかです。「一貫性を保つ際に最も難しいことの一つは、信頼できる情報源を特定することです」とBumbleのデザインシステムエンジニア兼プラットフォームエンジニア、Raul Menezes氏は説明

します。デザインシステムが成熟し、チームが成長するにつれて、この課題はさらに深刻化します。静的なPDFが共有ドライブ内ですぐに使われなくなる時代は終わりました。現代のチームには、専用のドキュメントサイトからワークスペースまで、これまで以上に多くのオプションがあります。

ゼロから始める

カスタムドキュメントサイトは、デザインシステムをツールやプロセスと深く統合する必要がある大規模な組織において際立ちます。GoogleのMaterial Design、IBMのCarbon、eBayのEvoはすべて、内外のユーザーに向けたカスタムドキュメントサイトを使用しており、ゲートコンテンツや異なるユーザーグループ向けに特化した経路を提供しています。

「人々は単に、可能な限り最善の仕事をしたいと考えています」と、eBayのスタッフプロダクトデザイナーであるRyan Tinsley氏は説明します。「当社で作成したドキュメントを参照することで、チームが作業の質を劇的に向上させるのを目の当たりにしてきました。現在の勤務時間をプレイブック導入前と比べると雲泥の差です。何を参照し、ベストプラクティスに沿ってブランドを示す方法を理解できているのです。」

eBayは、ブランド用と製品用のドキュメントを別々の場所に保存するのではなく、統一されたプレイブックを構築しました。「ガイダンスを1か所にまとめ、あちこちにアクセスする必要がないようにしたかったのです」とTinsley氏は述べています。これを実現するため、eBayチームは、変更内容をFigmaから直接CMSにエクスポートするカスタムツールを開発しました。これにより、デザイナーや他のチームは、最新版のプレイブックが承認され次第、すぐに入手できます。

既存のプラットフォームを活用する

すべてのチームにこのレベルの複雑さが必要とは限りません。小規模なチームは、 多くの場合、NotionやConfluenceなどのコラボレーションツールから始め、迅速なセットアップと簡単なメンテナンスを優先します。多くのチームは、Storybookで技術仕様を、よりアクセスしやすい形式でデザインガイドラインを作成し、カスタムプラグインで補完するアプローチを組み合わせています。Razorpayのチームは、ドキュメントで実体を説明するだけでは不十分であることに気づきました。つまり、さまざまなチームがそれぞれの立場で対応する必要があったのです。そこで、デザインドキュメントと実装の間のギャップを埋めるカスタムプラグイン、RazorSharp

を開発しました。ここで重要なのは、現在のニーズを満たしつつ、将来的な成長を見据えたツールを選ぶことです。

ドキュメントに含める内容

ドキュメントを保存する場所もさることながら、ドキュメントに含める内容も大切です。ここでは、重要な要素を説明します。

デザイン原則

すべてのデザインシステムには、大局的な戦略から細部に至るまでの意思決定を導く、明確に定義されたデザイン原則が必要です。意思決定の背後にある「理由」を文書化することで、チームはその根拠をより深く理解し、一貫して実行する方法を把握できます。

コンポーネントライブラリ

各コンポーネントには以下を含めます。

• 使用ガイドラインとベストプラクティス
• 構造、寸法、動作を含むデザイン仕様
• 実際の例とユースケース
• コードスニペットと実装の詳細
• 状態とバリエーションを示すインタラクティブプロトタイプ

ビジュアルスタイルガイド

ブランドの美学を定義する重要なデザインの意思決定を文書化します。

• 使用ガイドライン付きのカラーパレット
• 階層とベストプラクティスを指定するタイポグラフィーシステム
• デザイン仕様を備えたアイコンライブラリ
• アクセシビリティガイドラインを含む画像およびイラストの基準

技術的な実装

以下を用意することで、開発者によるシステムの実装を支援します。

• コンポーネントAPIとプロパティのドキュメント
• アクセシビリティ要件とテスト手順
• パフォーマンスに関する考慮事項
• 異なるフレームワークの統合ガイド
• 明確な命名規則とトークンに関するドキュメント

アクセシビリティガイドライン

アクセシビリティ要件を明確に示します。

• コンポーネントのWCAG準拠レベル
• スクリーンリーダーの動作
• キーボードナビゲーションパターン
• カラーコントラストの要件
• タッチターゲットサイズ

eBayのデザインシステムチームは、詳細な情報を提供するほど良い結果が得られることに気づきました。「誰もがドキュメントを求めています」とTinsley氏。「当社の包括的なシステムをもってしても、『このエッジケースについてはどうですか?』や『このシナリオの文書化を検討しましたか?』と質問されることがよくあります。この継続的なフィードバックループが、当社のリソースの改善と拡大の原動力になっています。パートナーは、ドキュメントを受動的に利用するだけでなく、当社によるドキュメントを作成を積極的に支援してくれています。」

ドキュメントを維持・進化させる方法

チームの進化に合わせてドキュメントを最新の状態に保つ方法は、ドキュメントの作成において最も一般的な課題の1つです。ドキュメントが古いとデザインの一貫性を欠き、結果としてデザインシステムの信頼性を損なう可能性があります。ドキュメントの更新には労力が必要ですが、オンボーディングの迅速化、方向性の違いの減少、エクスペリエンスにおける一貫性の向上など、大きなメリットがあります。

ドキュメントを最新の状態に保つ方法

「デザインで見たものがそのままコードに反映されます」とRazorpayのKamlesh氏は述べています。この配列は、文書の構造、維持、発展の仕方を意図的に選択したことによるものです。Saurabh氏はこう説明します。「当社には約70人のデザイナーと100人のフロントエンド開発者がおり、その中のデザイナー3人とエンジニア5人が当社のデザインシステムに専念しています。」このメインチームは、毎日の勤務時間やフォーカスグループ、さまざまなチームのデザイナーが参加するアドボカシープログラムを通じて、コミュニティを育成しています。

デザインシステムが進化すると、更新や貢献を管理するための明確なプロセスを確立することが重要になってきます。このプロセスでは、一元的なガバナンスとコミュニティの意見のバランスを取り、標準を維持しながら柔軟に対応できるようにする必要があります。ここでは、導入すべきツールとプロセスをいくつか紹介します。

• コントリビューションガイドライン: テンプレート、スタイルガイド、レビュープロセスなど、チームメンバーが変更や追加を提案する方法について、明確なガイドラインを確立します。
• バージョン管理:セマンティックバージョニングを使用して、各更新の範囲と影響を伝えます。これにより、チームは各バージョンがどのように異なり、アップグレード時に何を期待すべきかを理解できます。
• 変更ログ: 新機能、バグの修正、重大な変更、移行手順など、各リリースにおける詳細な変更のリストを管理します。
• 品質保証: フィードバックループ、定期的なレビュー、リンティングシステムなど、複数のチェックポイントを実装して品質をチェックします。

eBayのデザインシステムチームとデザインテクノロジーチームは、さまざまなプラットフォームにわたる実装ステータスを示すコンポーネントステータステーブルを管理しています。eBayのスタッフデザインテクノロジストであるCordelia McGee-Tubb氏はこう説明します。「当社の開発者の多くは、このコンポーネントステータスAPIを使用して、各自が構築しているフレームワークにコンポーネントが存在するかどうか、Figmaのバージョンや戦略ドキュメントが最新であるかを確認しています。これは、大きな成果です。」また、ドキュメントを検証するためのカスタムリンターも開発しました。これにより、コンポーネントの使用状況をガイドラインに照らしてチェックし、アクセシビリティ情報が完全であること、すべての画像に代替テキストが含まれていることを確認して、名前や構造の不一致にフラグを立てることができます。

誰もが使いやすいようにする

チームメンバーが異なれば、ドキュメントに必要なものは異なります。成功するには、対象者ごとに異なるニーズを理解する必要があります。アラスカ航空では

、デザイナーがピクセルパーフェクトな実装に苦労する一方で、開発者はちぐはぐなデザインを受け取っていました。プロダクトデザイナーのJune Lee氏は、AuroのデザインシステムをFigmaに移行する際、重要な機能を文書化することに力を注ぎました。彼女はこう説明します。「Figmaの機能をデザイナーに理解してもらうため、教育に力を注ぎました。デザイナーがFigmaをより効果的に活用していることがわかり、デザイナーとエンジニアの間の対立が減りました。」各コラボレーターが最も役立つと感じているものを以下に示します。

デザイナー向け

• 視覚的な例と使用パターン
• コンポーネントのバリアントと状態
• デザイントークンの実装
• グリッドシステムとスペーシング
• アセットライブラリとリソース

開発者向け

• 技術仕様書
• APIドキュメンテーション
• 統合ガイド
• テスト要件
• パフォーマンスに関する考慮事項

プロダクトマネージャー向け

• 大まかなシステムの概要
• コンポーネントの選択ガイダンス
• 機能のロードマップ
• リリースノートとアップデート

フィードバックを集めて影響を測定する

Razorpayでは、導入数だけで成功を測るのではなく、ワークフローとコラボレーションへの具体的な影響を重要視しています。Razorpayが設定した具体的な目標は、新機能を構築するチームが設計作業の70％で自社のシステムを使用し、既存の製品で50％のカバレッジを実現することでした。スタッフデザイナーのSaurav Rastogi氏は次のように述べています。「デザイナーと開発者にアンケートを実施した結果、80%がBladeデザインシステムを使用した方が生産性が向上したと感じると回答しました。」

使用しているシステムに関するフィードバックや実証ポイントを集めるときは、簡単なページの閲覧だけでなく、ドキュメントが動作にどのように影響するかを理解する必要があります。包括的なフィードバックを収集するため、ユーザーテストやインタビューを行うことを検討してください。継続的な改善とイテレーションを優先することで、製品やプロセスが進化しても、デザインシステムがチームにとって価値があり効果的なツールであり続けることを保証できます。

拡張性を考慮した計画

最も効果的なドキュメントは、実体を詳述するだけでなく、協力してより良い体験を構築する力をチームに与えます。ドキュメントを最新の状態に保つツールやプロセスに投資することで、導入と一貫性が向上します。独自のドキュメントを構築し、発展させるには、以下の点を考慮してください。

• 統合されたツールやカスタムソリューションを活用し、各チームが働く場所で交流する
• GitHubのLukas Oppermann氏が「第3の言語」と呼ぶ、デザイナーと開発者がコミュニケーションをとれるツールを作り、分野間の橋渡しをする
• 専任チームやコミュニティとの定期的な交流を通じて明確なコントリビューションパスを作る
• チームの生産性とコラボレーションの向上を追跡して効果を測定する

将来的には、作業と並行して文書化を行う、より統合されたアプローチが求められます。ドキュメントがシステムと共に進化すれば、導入は自然に進みます。目標は完璧なドキュメントを作ることではなく、チームが最善の仕事をすることです。

他に質問や学びたいトピックがある場合は、Xで@figmaにツイートしてください。Figmaのデザインシステム機能を活用することで、どのようにチームが一貫性を確保し、デザインを拡張し、開発との整合を維持することができるかについて詳しく学び、デモをリクエストしましょう。