ドキュメント基準
コンポーネント docs を作る時に毎回確認する、preview、code、SSOT、言語、モバイル表示の基準です。
Template
ページ構成を揃える
docs preview
ページ上部の preview は、そのコンポーネントの標準利用を示します。コンパクトすぎる幅や、実利用と違うデータで見せません。
状態とバリエーション
1項目ずつタイトル、説明、preview、code を持たせます。横並びで詰めたり、タイトルだけの列に戻したりしません。
プロパティ / 使い方
props は型だけでなく、何に使うか、初期値、注意点が伝わるようにします。使い方では責務と使い分けを説明します。
使用コンポーネント / 関連コンポーネント
そのページで compose している GunjoUI コンポーネントと、迷いやすい近いコンポーネントを明示します。
判断フロー
上から順に確認し、途中で判断できる場合はそこで決めます。
- 1
ページ上部で標準利用を見せる
docs preview は、そのコンポーネントを初めて見る人が用途を理解できる標準例にします。
- 2
状態とバリエーションで例外を分ける
empty、disabled、loading、mobile、compact、danger など、標準例に詰め込まない状態を個別に見せます。
- 3
使い分けを本文で説明する
似たコンポーネントとの違い、どこまでが責務か、上位コンポーネントへ任せる範囲を明記します。
Preview
docs preview を独立して確認する
embed と本文 preview は別物
上部の `/embed/<slug>` と本文内の states / variants は別の表示面です。片方が正しくても、もう片方の幅・高さ・overflow が正しいとは限りません。
FIT 幅を中身まで確認する
外側の iframe ではなく、preview 内の wrapper、直接の子、component root が意図した幅で広がっているか確認します。
高さで overlay を逃がさない
Popover、Tooltip、Dropdown、Dialog が見切れる時は、overflow、portal、collision、container を確認します。固定高さ追加は最後の選択です。
preview 内で完結させる
モーダルやトーストなどは、ページ全体ではなく preview 内の体験として表示します。ユーザーがコンポーネントの一部と誤解しないようにします。
判断例
抽象的な原則を、実装・レビュー時の具体的な判断に落とします。
| 場面 | 避ける | 推奨 | 理由 |
|---|---|---|---|
| Dropdown が見切れる | preview に固定高さを足す | portal、collision、overflow、container を確認する | 高さで逃げると別 preview で同じ問題が再発するため。 |
| FIT が中身幅に合わない | 個別 demo の `max-w-*` だけを触る | embed wrapper、direct child、component root の幅を確認する | docs preview と states preview は別の表示面だから。 |
Code
コピーして使えるコードにする
表示データをコードに含める
チャート、テーブル、カード、リストは、preview に出ている値や配列を code に含めます。データがないコードは再利用できません。
状態変更を反映する
シナリオ、入力、トグル、選択で preview が変わるなら、code もその状態管理を示します。
disabled 理由や tooltip も含める
UX に関わる補足説明は見た目の飾りではありません。tooltip、aria-label、エラー文言も code に含めます。
内部 demo だけで成立させない
docs 専用の隠れたデータや helper に依存しすぎると、コピーした利用者が再現できません。
判断例
抽象的な原則を、実装・レビュー時の具体的な判断に落とします。
| 場面 | 避ける | 推奨 | 理由 |
|---|---|---|---|
| チャートの preview | `<Chart />` だけのコード例 | 表示している data、legend、tooltip、state を含める | 数値を変えられないコードはコピーしても使えないため。 |
| 削除アクションの preview | クリック後に削除済み toast だけ出す | 操作前の AlertDialog と danger action を code に含める | 取り消せない操作は、消す前の確認が UX の一部だから。 |
Review
完了前の確認
日本語と英語の混在
title、description、preview、code、tooltip、toast、empty state を locale ごとに確認します。
スマホ実機
折り返し、横スクロール、input focus、overlay、toast、tooltip、チャート tooltip はスマホ実機で確認します。
SSOT と export
`src/components/**` を変更したら、SSOT、generated variant keys、docs registry、public export の同期対象として扱います。
検証コマンド
`design:verify`、`docs:audit:components`、`type-check`、`git diff --check` を変更範囲に応じて通します。
確認チェック
PR 前、または人間の目視確認前に見る項目です。
上部 preview と states preview を別々に見た
`/embed/<slug>` と本文内 preview の両方で、幅、高さ、overflow、overlay の出方を確認しています。
code が preview を再現できる
表示データ、状態、aria-label、tooltip、toast、disabled 理由が code に含まれています。
ローカルな逃げ道で直していない
固定高さ、固定幅、隠し overflow で見た目だけを成立させていないか確認しています。
日英とスマホ実機を確認した
日本語と英語、スマホ実機、タブレット幅、長い文字列、ツールチップの見切れを確認しています。