ドキュメントとスタイルガイドの統合

ドキュメントがなければ、開発者はどの見出し順を使うか、どのクラス名が存在するか、モーダルとドロワーをいつ使うかといった規約を毎回作り直すことになります。文書化されたスタイルガイドがあれば、正しい答えを見つけやすくなり、大規模な開発での推測や迷いをなくせます。

Storybook、Histoire（Vue）、Ladleなどのツールは、ドキュメントとともにコンポーネントを分離した状態でレンダリングします。そのため、例は実際のコードと常に同期します。Wikiやリポジトリに置いた静的なドキュメントファイルは必ず次第に実装とずれていきますが、リビングドキュメントではそのずれを防げます。

各コンポーネントについて、使用に必要な最小限のHTMLを示します。<app-button variant="primary">Save</app-button>。variant（primary、secondary、danger）、状態（loading、disabled）、エッジケース（長いテキスト、アイコン付き、全幅）も示します。実際のページにそのままコピーして貼り付けられる例こそ、チームが実際に利用するものです。

優れたドキュメントでは、ソースコードの隣に例のレンダリング結果を表示します。Storybookはこれを標準で実行でき、mdx-deck、Docusaurus、Astro StarlightはライブJSXを含むMDXに対応しています。マークアップを読みながら実際の結果を確認できるため、「これは動くのか？」という疑念をすぐに解消できます。

各コンポーネントに組み込まれたアクセシビリティの動作を文書化します。どのキーボード操作に対応するか、どのARIAロールを使うか、フォーカスをどのように管理するかを記載します。コンポーネントを採用する利用側はアクセシビリティ対応をそのまま利用でき、レビュアーは契約を壊していないことを確認できます。

明確なアンチパターンを示します。「重要な一時的フィードバックにModalを使わず、代わりにToastを使います」。否定的な例は、肯定的な例より記憶に残ることがあります。すべての推奨事項に明確な禁止事項を組み合わせ、失敗につながる条件を明らかにします。

BEM、atomic CSS、CSS Modules、Tailwindのユーティリティ合成など、命名パターンを文書化します。クラス名、カスタムプロパティ名、ファイルパスの規則を明文化します。一貫した命名は認知負荷を下げますが、一貫性のない命名はすべての開発者から永続的に時間を奪います。

決定事項だけでなく、なぜその決定に至ったのかを記録します。「VueではなくReactを選んだ理由は……」と残しておけば、将来のコントリビューターが背景を理解できます。ADRs（Architecture Decision Records）をコードの近くにMarkdownで置く方法は、チームのメンバーが入れ替わっても残る軽量な形式です。

新しいチームメンバーは、1日で最初のコンポーネントをリリースできる状態にするべきです。チェックリストには、リポジトリのセットアップ、依存関係のインストール、Storybookの起動、適切なコンポーネントテンプレートの確認、ドキュメントの作成、PRの作成を含めます。最初のPRまでにかかる時間を指標として追跡し、短いほどよいと考えます。

優れたドキュメントは、初めて検索する人にも熟練者にも簡単に見つけられます。検索機能付きのドキュメントサイトを使います（DocusaurusならAlgolia、Starlightなら組み込み検索）。コンポーネントには複数の別名を付けます。たとえば、Dialog、Popup、Overlayで検索しても「Modal」が見つかるようにします。

ドキュメントをビジュアルリグレッションテストと組み合わせます。ChromaticはすべてのPRで各Storybook storyのスナップショットを取得し、視覚的な差分を表示します。意図せずButtonのスタイルをドキュメント全体で変更したPRは、その変更自体で検出できます。これにより、ドキュメントとデザインシステムの継続的なテストを組み合わせられます。

メンテナーだけが知っていることを記録します。落とし穴、作りかけの抽象化、整理を待つハックなどです。将来の自分や後任者は、忘れてしまう前にこうした組織の知識を記録しておいた現在の自分に感謝するでしょう。

コードと並べてレンダリングされるリビングドキュメントが、静的なドキュメントファイルより好まれるのはなぜですか？

ドキュメントは、デザインシステムの価値を増幅します。実際のコンポーネントコードを読み込むリビングドキュメント（Storybook、Histoire、Ladle）を使います。実用最小限の例を示し、アクセシビリティを文書化し、意思決定を記録し、推奨事項と禁止事項の組み合わせを記述し、ビジュアルリグレッションテストと組み合わせます。ドキュメントを後回しにせず、第一級の成果物として扱います。