デザインシステムのドキュメント設計：Storybook・Figma・使用ガイドラインの作り方

デザインシステムの価値は、コンポーネントの品質だけでなく「ドキュメントの質」で決まると言っても過言ではありません。誰でも正しく使えるドキュメントがあることで、デザイナーとエンジニアが独自の解釈で勝手にUIを作ることを防ぎ、一貫したUIが全チームに展開されます。本記事では、デザインシステムのドキュメント設計の実践方法を解説します。

デザインシステムドキュメントに必要な要素

コンポーネントドキュメントの基本構成：

各コンポーネントのドキュメントには以下が必要です：

1. 概要（Overview）: このコンポーネントは何で、どんな目的に使うか
2. いつ使うか（When to Use）: 適切な使用場面・NGな使い方
3. バリアント（Variants）: 種類・サイズ・状態の一覧とビジュアルサンプル
4. プロパティ（Props/API）: 設定できるパラメータと型・デフォルト値
5. コードサンプル: コピー可能なインポート・使用例
6. アクセシビリティ: ARIA属性・キーボード操作・コントラスト要件
7. デザインファイル: Figmaへのリンク

Storybookによるコンポーネントカタログ

Storybookとは：

UIコンポーネントを独立した環境でブラウザ上に表示・テストするツールです。React・Vue・Angular・Web Components等に対応し、コンポーネントカタログの事実上の標準ツールです。

Storiesの作成：

各コンポーネントの.stories.tsxファイルで、すべてのバリアント・状態をStoryとして定義します：

// Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./Button";

const meta: Meta<typeof Button> = {
  component: Button,
  title: "Components/Button",
};
export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { variant: "primary", children: "Click me" } };
export const Secondary: Story = { args: { variant: "secondary", children: "Click me" } };
export const Disabled: Story = { args: { disabled: true, children: "Disabled" } };

Storybookのドキュメントページ：

@storybook/addon-docs を使うと、コンポーネントのTypeScriptの型定義・JSDocコメントからプロパティテーブルが自動生成されます。MarkdownでのリッチなドキュメントページをStorybookに直接記述できます。

Figmaのコンポーネントドキュメント

Figmaのコンポーネント説明：

Figmaのコンポーネントパネルに説明（Description）・リンクを追加できます。コンポーネントの説明、Storybookへのリンク、使用上の注意事項を記載します。

コンポーネントの整理：

Figmaのページを「Components」「Foundations」「Templates」に分け、デザインシステムの構造を明確にします。各ページにはタイトルとブリーフな説明を冒頭に記載します。

使用ガイドライン（Design Guidelines）のドキュメント

Foundationsのドキュメント：

• カラーシステム（パレット・トークン・使用ルール）
• タイポグラフィ（フォントスケール・ウェイト・使用ルール）
• スペーシング（グリッド・スペーシングスケール）
• シャドウ・ボーダーラジアス

これらのFoundationsページでは、「やってはいけないこと（Dont's）」と「良い例（Do）」を視覚的に対比させることが重要です。

使い方の「Do's と Don'ts」：

抽象的なルールより、具体的なビジュアル対比（NGな使い方 × ← → ○ 正しい使い方）の方が記憶に残りやすく、実際の業務で参照しやすくなります。

バージョン管理とChangelog

セマンティックバージョニング：

デザインシステムもコードと同様にSemantic Versioning（MAJOR.MINOR.PATCH）でバージョンを管理します：

• MAJOR: 破壊的変更（コンポーネントの削除・大幅な変更）
• MINOR: 後方互換の新機能追加（新コンポーネント・新プロパティ）
• PATCH: バグ修正・微小な変更

Changelog：

各バージョンでの変更内容を記録したChangelogを必ず公開します。「何が変わったか」「マイグレーション方法」を明記することで、採用チームが安心してアップデートできます。

コントリビューションガイド

コンポーネント追加のプロセス：

1. Discussionでの提案（Why・What・Who）
2. デザインレビュー（Figmaで複数バリアントのデザイン）
3. 実装・ストーリー作成
4. ドキュメント作成
5. デザインシステムチームのレビュー
6. リリース・Changelog更新

命名規則・コードスタイルガイド：

コントリビューターが一貫したスタイルで開発できるよう、命名規則・ファイル構成・テストの書き方のガイドを提供します。

まとめ

デザインシステムのドキュメントは、システムを実際に使ってもらうための最重要要素です。Storybookによるコンポーネントカタログ・Figmaの整理・使用ガイドライン・バージョン管理を整備することで、デザイナーとエンジニアが自信を持って活用できるデザインシステムが完成します。UI ZUKANではデザインシステムの実装事例を紹介しています。