デザインシステム構築入門｜コンポーネントライブラリの作り方と運用

プロダクトが成長するにつれて、UIの一貫性が失われていく——多くの開発チームが経験する問題です。ページごとにボタンのデザインが微妙に異なったり、同じ機能なのに画面によって操作方法が違ったりすると、ユーザー体験が損なわれるだけでなく、開発効率も低下します。

デザインシステムは、この問題を体系的に解決するアプローチです。本記事では、デザインシステムの基本概念から、デザイントークンの設計、コンポーネントライブラリの構築、Storybookを使った開発フロー、チームでの運用方法までを実践的に解説します。

デザインシステムとは？なぜ必要なのか

デザインシステムとは、UIの設計原則、ビジュアルスタイル、再利用可能なコンポーネント、それらの使用ガイドラインを体系化したものです。単なるUIコンポーネント集ではなく、デザインの意思決定を標準化するための「仕組み」です。

デザインシステムがもたらすメリット

UIの一貫性
すべての画面で統一されたデザインが適用され、ユーザーは一貫した体験を得られます。ブランドの信頼感も向上します。

開発速度の向上
新しい画面を作る際、既存のコンポーネントを組み合わせるだけで大部分が完成します。ゼロからUIを設計・実装する時間を大幅に短縮できます。

品質の均一化
アクセシビリティ、レスポンシブ対応、エラーハンドリングなどをコンポーネントレベルで担保できるため、開発者のスキルレベルによる品質のばらつきを軽減します。

コミュニケーションの効率化
デザイナーとエンジニアが共通のコンポーネント名と仕様を参照できるため、デザインの意図が正確に伝わります。「このボタン、もうちょっと大きく」といった曖昧な指示が減少します。

デザインシステムの構成要素

デザインシステムは通常、以下の要素で構成されます。

デザイン原則
UIデザインの根底にある価値観や判断基準です。「シンプルさを最優先する」「操作は3ステップ以内で完結させる」など。

デザイントークン
色、フォントサイズ、スペーシング、角丸など、デザインの基本値を変数として定義したものです。

コンポーネントライブラリ
再利用可能なUIコンポーネントの実装です。React、Vue、Angular用のコードとして提供されます。

ドキュメント
各コンポーネントの使い方、do/don't、デザインパターンなどを記述したガイドラインです。

デザイントークンの設計

デザイントークンは、デザインシステムの基盤となる最小単位の設計値です。色、タイポグラフィ、スペーシングなどを変数として一元管理します。

カラートークン

カラートークンは、プリミティブトークンとセマンティックトークンの2層構造で設計するのが効果的です。

プリミティブトークン（基本色）
色のパレットそのものを定義します。blue-500: #3B82F6、gray-100: #F3F4F6 のように、色名とスケールで管理します。

セマンティックトークン（意味的な色）
用途に基づいた名前を付けます。color-primary: blue-500、color-error: red-500、color-background: gray-100 のように、プリミティブトークンを参照します。

コンポーネントではセマンティックトークンを使用します。こうすることで、ブランドカラーの変更やダークモード対応の際に、セマンティックトークンの参照先を変更するだけで全体のテーマを切り替えられます。

タイポグラフィトークン

フォントファミリー、フォントサイズ、行間、フォントウェイトを定義します。使いすぎを防ぐため、サイズのバリエーションは5〜8段階程度に絞りましょう。

各サイズに用途を紐づけておくと迷いが減ります。たとえば、text-xs（キャプション用）、text-sm（補助テキスト）、text-base（本文）、text-lg（セクション見出し）、text-xl（ページ見出し）のように定義します。

スペーシングトークン

余白やパディングの値を、4pxまたは8pxの倍数で定義するのが一般的です。space-1: 4px、space-2: 8px、space-3: 12px、space-4: 16px、space-6: 24px、space-8: 32px のように一貫したスケールを持たせます。

CSSカスタムプロパティ（CSS変数）やJavaScriptの定数として管理し、コンポーネント内ではハードコードされた数値ではなくトークンを参照します。

コンポーネント設計の原則

コンポーネントライブラリの品質は、個々のコンポーネントの設計方針に大きく左右されます。以下の原則を意識しましょう。

単一責任の原則

1つのコンポーネントは1つの役割だけを担います。Buttonコンポーネントはボタンの描画とクリックイベントの処理だけを担当し、データの取得やビジネスロジックは含めません。

コンポーネントの階層設計

コンポーネントは、原子（Atoms）から分子（Molecules）、有機体（Organisms）へと組み合わせていくAtomic Designの考え方が参考になります。

Atoms（原子）
Button、Input、Label、Iconなど、これ以上分解できない最小のUI要素です。

Molecules（分子）
Atomsを組み合わせた複合コンポーネントです。SearchBar（Input + Button + Icon）、FormField（Label + Input + ErrorMessage）など。

Organisms（有機体）
Moleculesを組み合わせた、特定のビジネス機能を持つセクションです。NavigationBar、UserProfileCard、ProductListなど。

すべてのコンポーネントをAtomic Designに厳密に分類する必要はありませんが、粒度の基準として参考にすると、コンポーネントの責務が明確になります。

Props設計のベストプラクティス

バリアント（Variant）パターン
見た目のバリエーションはvariant propsで管理します。Buttonなら、variant="primary"、variant="secondary"、variant="ghost"などです。

サイズ（Size）パターン
サイズのバリエーションはsize propsで管理します。size="sm"、size="md"、size="lg"を基本とし、3〜4段階に抑えましょう。

コンポジション
childrenやslotを活用し、コンポーネントの内部構造を柔軟にカスタマイズできるようにします。すべてをpropsで制御しようとすると、propsの数が爆発的に増えてしまいます。

Storybookを使ったコンポーネント開発

Storybookは、UIコンポーネントを独立して開発・テスト・ドキュメント化するためのツールです。デザインシステムの構築には欠かせません。

Storybookの基本的な使い方

Storybookでは、各コンポーネントの「ストーリー」を記述します。ストーリーとは、コンポーネントの特定の状態（props、データ）を表すスナップショットです。

Buttonコンポーネントなら、「Primary（プライマリ）」「Secondary（セカンダリ）」「Disabled（無効）」「Loading（読み込み中）」といったストーリーを作成します。これにより、コンポーネントの全バリエーションを一覧で確認できます。

コンポーネントドリブン開発

Storybookを活用したコンポーネントドリブン開発では、以下の流れで作業を進めます。

1. ストーリーの作成
コンポーネントの仕様をストーリーとして先に記述します。どのようなpropsを受け取り、どのような見た目になるかをStorybook上で定義します。

2. コンポーネントの実装
ストーリーを満たすようにコンポーネントを実装します。Storybookのホットリロードで即座に結果を確認しながら開発できます。

3. ビジュアルリグレッションテスト
Chromatic（Storybookのクラウドサービス）やreg-suitなどのツールを使い、コンポーネントのビジュアルの変化を自動検出します。意図しない見た目の変更をPRレビューで確認できます。

4. インタラクションテスト
Storybookのplay関数を使い、ユーザーの操作（クリック、入力、ホバーなど）をシミュレートするテストをストーリー内に記述できます。

ドキュメントの自動生成

StorybookのDocsアドオンを使うと、コンポーネントのpropsの型定義から自動的にドキュメントが生成されます。TypeScriptの型情報、デフォルト値、各propsの説明がテーブル形式で表示されます。追加のマークダウンを記述してデザインのガイドラインやDo/Don'tも記載しましょう。

アクセシビリティへの対応

デザインシステムのコンポーネントにアクセシビリティ（a11y）を組み込むことで、プロダクト全体のアクセシビリティを底上げできます。

基本的なアクセシビリティ対応

セマンティックなHTML
ボタンには<button>、リンクには<a>、見出しには<h1>〜<h6>を正しく使用します。divやspanでボタンを作るのは避けましょう。

キーボード操作のサポート
すべてのインタラクティブな要素がキーボードのみで操作できるようにします。フォーカスの視覚的なインジケーターを明確に表示し、フォーカス順序が論理的であることを確認します。

ARIAの適切な使用
WAI-ARIA属性を適切に設定します。aria-label、aria-describedby、aria-expanded、roleなどを使い、スクリーンリーダーに正しい情報を伝えます。ただし、ネイティブなHTML要素で表現できる場合はARIAよりもセマンティックHTMLを優先します。

色のコントラスト
テキストと背景のコントラスト比がWCAG 2.1のAA基準（4.5:1以上）を満たすことを確認します。デザイントークンの段階でコントラスト比を検証しておきましょう。

StorybookでのA11yチェック

Storybookのa11yアドオンを導入すると、各ストーリーに対してaxe-coreによるアクセシビリティ監査を自動実行できます。違反項目がパネルに表示されるため、開発中に問題を発見・修正できます。

チームでの運用とガバナンス

デザインシステムは作って終わりではなく、継続的な運用が成功の鍵です。

コントリビューションモデル

デザインシステムへの貢献モデルとして、主に3つのアプローチがあります。

中央集権型
専任のデザインシステムチームが開発・メンテナンスを行います。品質の一貫性は高いですが、チームのリソースがボトルネックになりがちです。

連邦型（Federated）
各プロダクトチームから代表者がデザインシステムの開発に参加します。多様なニーズを取り込みやすく、所有感も高まります。

オープンソース型
誰でもプルリクエストを出せるオープンな運用です。コントリビューションガイドラインを整備し、レビュープロセスを確立することが重要です。

バージョニングとリリース

コンポーネントライブラリはnpmパッケージとして公開し、セマンティックバージョニング（SemVer）で管理します。破壊的変更はメジャーバージョンアップで告知し、移行ガイドを提供します。

CHANGELOGの自動生成、リリースノートの公開、バージョンごとのStorybookのデプロイにより、利用者が変更内容を把握しやすい環境を整えましょう。

採用率の計測

デザインシステムの効果を客観的に示すために、採用率を計測しましょう。各プロダクトでデザインシステムのコンポーネントがどの程度使われているか、カスタムコンポーネントの割合はどの程度かを定期的に分析します。ESLintルールでデザイントークンの直接的な値のハードコードを検出することも有効です。

まとめ

デザインシステムは、UIの一貫性と開発効率を両立するための体系的なアプローチです。デザイントークンでビジュアルの基盤を定義し、再利用可能なコンポーネントライブラリを構築し、Storybookで開発・テスト・ドキュメント化を一体化することで、効率的な開発ワークフローが実現します。

小さく始めることが重要です。まずは頻出するコンポーネント（Button、Input、Card）とデザイントークン（カラー、タイポグラフィ）から着手し、プロダクトの成長に合わせて拡充していきましょう。チームの合意を得ながら運用体制を整え、デザインシステムを「生きたドキュメント」として育てていくことが成功への道です。