ドキュメント

良いドキュメントはコンポーネントを利用しやすく、アクセスしやすくするために不可欠です。本ガイドは、各コンポーネントのドキュメントページに含めるべき主要な要素を概説します。

ドキュメントフレームワーク

ドキュメントをスケールさせるには、ドキュメントフレームワークを使用できます。プロジェクトの言語やニーズに応じて多くの選択肢があります。一般的な選択肢は次のとおりです:

• Fumadocs - Next.js向けの高速で機能豊富なドキュメントフレームワーク
• Nextra - 検索機能とテーマ機能を内蔵したMarkdownベースのドキュメント
• Content Collections - ドキュメント用の型安全なコンテンツ管理
• Docusaurus - バージョン管理に対応した機能豊富なドキュメントサイト
• VitePress - ドキュメントに最適化されたVueベースの静的サイトジェネレータ

望ましくは、選んだフレームワークが構文ハイライト、カスタムコンポーネントをサポートし、全般的に設計が良好であることです。

必須のドキュメントセクション

概要

コンポーネントが何をするか、いつ使用するべきかを説明する簡潔な導入から始めてください。

デモ、ソースコード、およびプレビュー

開発者に良い第一印象を与えるために、コンポーネントの動作を示すデモと、そのデモを作成するためのコードを含めてください。

オープンソースのレジストリを使用している場合、コンポーネントを作成するために使用されたソースコードのプレビューも含めることができます。

構文ハイライトとクリップボードコピー機能を備えたコードブロックを使用してください。ページを散らかさずにこれらのビューを切り替えるために、タブ式インターフェースの利用を検討してください。

インストール

コンポーネントのインストール方法を明確に示してください。望ましくは、ターミナルにコピー＆ペーストできる単一のコマンドにしてください。

If you're building on shadcn/ui, you can use the shadcn CLI to install the component e.g.

npx shadcn@latest add <your-component-url>

If you're publishing to a マーケットプレイス, you can use the marketplace's CLI to install the component e.g.

npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>

If you're not using shadcn/ui but you are building a レジストリ, you could build your own CLI to install the component, e.g.

npx your-registry-cli@latest add <your-component-url>

Lastly, if you're publishing to npm, you can use the npm CLI to install the component e.g.

npm install <your-component-name>

機能

コンポーネントの主要な機能をリストアップして、ユーザーがその能力と利点を迅速に理解できるようにします。例えば:

• カスタマイズ可能 – スタイル、サイズ、動作を容易に調整してニーズに合わせられます。
• デフォルトでアクセシブル – キーボードナビゲーション、ARIA属性、およびスクリーンリーダー対応のベストプラクティスに従います。
• 組み合わせ可能 – 他のコンポーネントやパターンとシームレスに連携するよう設計されています。
• 型安全 – 包括的なTypeScript型定義を同梱し、最大限の安全性とオートコンプリートを提供します。
• テーマサポート – デザイントークンやテーマシステムと統合します。
• 軽量 – 依存関係が最小限で、パフォーマンスに最適化されています。
• SSR/SSG対応 – サーバーサイドレンダリングおよび静的レンダリングフレームワークで動作します。
• 十分にドキュメント化されている – 明確な使用例とAPIリファレンスを含みます。

このリストは特定のコンポーネントに合わせて調整してください。開発者にとってどの点がユニークで特に有用かを強調してください。

例

実用的な例でコンポーネントの柔軟性を示してください:

• バリエーション - 利用可能な異なる視覚スタイルやサイズ
• 状態 - 読み込み中、無効、エラー、または成功状態
• 高度な使用法 - 複雑なシナリオとエッジケース
• コンポジション - 他のコンポーネントとの連携方法
• レスポンシブ動作 - さまざまな画面サイズにどのように適応するか

各例にはレンダリングされた出力と対応するコードの両方を含めてください。

PropsとAPIリファレンス

使用可能なすべてのprops、メソッド、および設定オプションを文書化してください。関連するpropsをグループ化し、よく使われるものを強調することを検討してください。各propについて、次を含めてください:

• 名前 - プロップの識別子
• 型 - TypeScriptの型定義
• デフォルト - 指定しなかった場合のデフォルト値
• 必須 - そのpropが必須かどうか
• 説明 - プロップが何をするか、いつ使用するか

アクセシビリティ

コンポーネントがアクセシビリティ機能をどのようにサポートしているかを文書化してください:

• キーボードナビゲーションパターン
• ARIA属性とロール
• スクリーンリーダー対応
• フォーカス管理
• 色コントラストに関する考慮点

変更履歴とバージョニング

各コンポーネントのドキュメントページで変更履歴を維持することは有用です。カバーすべき項目:

• セマンティックバージョニングに従ったバージョン番号
• 新機能と拡張
• バグ修正
• 破壊的変更
• メジャーバージョンアップのためのマイグレーションガイド

ユーザーがバージョン間で何が変わったか、そして安全にアップグレードする方法を理解できるようにしてください。破壊的変更については、ビフォー/アフターのパターンを示すコード例を含めてください。

ベストプラクティス

• ドキュメントをコードの変更に合わせて最新の状態に保つ
• 実際の問題を解決する実用的な例を使用する
• 一般的な落とし穴とトラブルシューティングのヒントを含める
• 関連する場合はパフォーマンスに関する考慮点を提供する
• 関連するコンポーネントやパターンへのリンクを提供する
• すべてのコード例を実行可能かつテスト済みにする