mirror of
https://github.com/vercel/components.build.git
synced 2026-09-14 20:06:39 +08:00
Hayden Bleasel
55fae375a4
* Update Geistdocs * Update geistdocs.tsx * Run translation script * Delete toc.tsx * Update route.ts * Update route.ts
140 lines
8.1 KiB
Plaintext
140 lines
8.1 KiB
Plaintext
---
|
||
title: ドキュメント
|
||
description: コンポーネントのドキュメント化方法。
|
||
---
|
||
|
||
良いドキュメントはコンポーネントを利用しやすく、アクセスしやすくするために不可欠です。本ガイドは、各コンポーネントのドキュメントページに含めるべき主要な要素を概説します。
|
||
|
||
## ドキュメントフレームワーク
|
||
|
||
ドキュメントをスケールさせるには、ドキュメントフレームワークを使用できます。プロジェクトの言語やニーズに応じて多くの選択肢があります。一般的な選択肢は次のとおりです:
|
||
|
||
- [Fumadocs](https://fumadocs.dev/) - Next.js向けの高速で機能豊富なドキュメントフレームワーク
|
||
- [Nextra](https://nextra.site/) - 検索機能とテーマ機能を内蔵したMarkdownベースのドキュメント
|
||
- [Content Collections](https://content-collections.dev/) - ドキュメント用の型安全なコンテンツ管理
|
||
- [Docusaurus](https://docusaurus.io/) - バージョン管理に対応した機能豊富なドキュメントサイト
|
||
- [VitePress](https://vitepress.dev/) - ドキュメントに最適化されたVueベースの静的サイトジェネレータ
|
||
|
||
望ましくは、選んだフレームワークが構文ハイライト、カスタムコンポーネントをサポートし、全般的に設計が良好であることです。
|
||
|
||
## 必須のドキュメントセクション
|
||
|
||
### 概要
|
||
|
||
コンポーネントが何をするか、いつ使用するべきかを説明する簡潔な導入から始めてください。
|
||
|
||
### デモ、ソースコード、およびプレビュー
|
||
|
||
開発者に良い第一印象を与えるために、コンポーネントの動作を示すデモと、そのデモを作成するためのコードを含めてください。
|
||
|
||
オープンソースの[レジストリ](/registry)を使用している場合、コンポーネントを作成するために使用されたソースコードのプレビューも含めることができます。
|
||
|
||
構文ハイライトとクリップボードコピー機能を備えたコードブロックを使用してください。ページを散らかさずにこれらのビューを切り替えるために、タブ式インターフェースの利用を検討してください。
|
||
|
||
### インストール
|
||
|
||
コンポーネントのインストール方法を明確に示してください。望ましくは、ターミナルにコピー＆ペーストできる単一のコマンドにしてください。
|
||
|
||
If you're building on shadcn/ui, you can use the [shadcn CLI](https://ui.shadcn.com/docs/cli) to install the component e.g.
|
||
|
||
```package-install
|
||
npx shadcn@latest add <your-component-url>
|
||
```
|
||
|
||
If you're publishing to a [マーケットプレイス](/marketplaces), you can use the marketplace's CLI to install the component e.g.
|
||
|
||
```package-install
|
||
npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>
|
||
```
|
||
|
||
If you're not using shadcn/ui but you are building a [レジストリ](/registry), you could build your own CLI to install the component, e.g.
|
||
|
||
```package-install
|
||
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.
|
||
|
||
```package-install
|
||
npm install <your-component-name>
|
||
```
|
||
|
||
<Callout>
|
||
複数のインストールオプションを上記のように表示するには、Fumadocsの[`package-install` syntax](https://fumadocs.dev/docs/headless/mdx/install)のようなものを使用できます。
|
||
</Callout>
|
||
|
||
### 機能
|
||
|
||
コンポーネントの主要な機能をリストアップして、ユーザーがその能力と利点を迅速に理解できるようにします。例えば:
|
||
|
||
- **カスタマイズ可能** – スタイル、サイズ、動作を容易に調整してニーズに合わせられます。
|
||
- **デフォルトでアクセシブル** – キーボードナビゲーション、ARIA属性、およびスクリーンリーダー対応のベストプラクティスに従います。
|
||
- **組み合わせ可能** – 他のコンポーネントやパターンとシームレスに連携するよう設計されています。
|
||
- **型安全** – 包括的なTypeScript型定義を同梱し、最大限の安全性とオートコンプリートを提供します。
|
||
- **テーマサポート** – デザイントークンやテーマシステムと統合します。
|
||
- **軽量** – 依存関係が最小限で、パフォーマンスに最適化されています。
|
||
- **SSR/SSG対応** – サーバーサイドレンダリングおよび静的レンダリングフレームワークで動作します。
|
||
- **十分にドキュメント化されている** – 明確な使用例とAPIリファレンスを含みます。
|
||
|
||
このリストは特定のコンポーネントに合わせて調整してください。開発者にとってどの点がユニークで特に有用かを強調してください。
|
||
|
||
### 例
|
||
|
||
実用的な例でコンポーネントの柔軟性を示してください:
|
||
|
||
- **バリエーション** - 利用可能な異なる視覚スタイルやサイズ
|
||
- **状態** - 読み込み中、無効、エラー、または成功状態
|
||
- **高度な使用法** - 複雑なシナリオとエッジケース
|
||
- **コンポジション** - 他のコンポーネントとの連携方法
|
||
- **レスポンシブ動作** - さまざまな画面サイズにどのように適応するか
|
||
|
||
各例にはレンダリングされた出力と対応するコードの両方を含めてください。
|
||
|
||
### PropsとAPIリファレンス
|
||
|
||
使用可能なすべてのprops、メソッド、および設定オプションを文書化してください。関連するpropsをグループ化し、よく使われるものを強調することを検討してください。各propについて、次を含めてください:
|
||
|
||
- **名前** - プロップの識別子
|
||
- **型** - TypeScriptの型定義
|
||
- **デフォルト** - 指定しなかった場合のデフォルト値
|
||
- **必須** - そのpropが必須かどうか
|
||
- **説明** - プロップが何をするか、いつ使用するか
|
||
|
||
<Callout>
|
||
Fumadocsを使用している場合、正確性を確保しメンテナンス負荷を軽減するために[Auto Type Table](https://fumadocs.dev/docs/ui/components/auto-type-table)を使用することを検討してください。
|
||
</Callout>
|
||
|
||
### アクセシビリティ
|
||
|
||
コンポーネントがアクセシビリティ機能をどのようにサポートしているかを文書化してください:
|
||
|
||
- キーボードナビゲーションパターン
|
||
- ARIA属性とロール
|
||
- スクリーンリーダー対応
|
||
- フォーカス管理
|
||
- 色コントラストに関する考慮点
|
||
|
||
### 変更履歴とバージョニング
|
||
|
||
各コンポーネントのドキュメントページで変更履歴を維持することは有用です。カバーすべき項目:
|
||
|
||
- セマンティックバージョニングに従ったバージョン番号
|
||
- 新機能と拡張
|
||
- バグ修正
|
||
- 破壊的変更
|
||
- メジャーバージョンアップのためのマイグレーションガイド
|
||
|
||
ユーザーがバージョン間で何が変わったか、そして安全にアップグレードする方法を理解できるようにしてください。破壊的変更については、ビフォー/アフターのパターンを示すコード例を含めてください。
|
||
|
||
<Callout>
|
||
もし構文ハイライトのフレームワークが対応していれば（Shikiのように）、バージョン間の変更を示すために[diff transformer notation](https://shiki.style/packages/transformers#transformernotationdiff)を使用することを検討してください。
|
||
</Callout>
|
||
|
||
## ベストプラクティス
|
||
|
||
- ドキュメントをコードの変更に合わせて最新の状態に保つ
|
||
- 実際の問題を解決する実用的な例を使用する
|
||
- 一般的な落とし穴とトラブルシューティングのヒントを含める
|
||
- 関連する場合はパフォーマンスに関する考慮点を提供する
|
||
- 関連するコンポーネントやパターンへのリンクを提供する
|
||
- すべてのコード例を実行可能かつテスト済みにする |