ガイドライン概要
GunjoUI を使う時、作る時、docs に残す時の判断基準をまとめます。はじめにが導入の入口なら、ガイドラインは実装とレビューの基準です。
Information architecture
はじめにとガイドラインの分担
近い内容に見えますが、読む目的を分けます。はじめには GunjoUI を理解して採用するための入口、ガイドラインは日々の実装判断を揃えるための基準です。
はじめに
プロジェクト概要、導入、AI 連携、採用ガイド、移行手順、依存関係、変更履歴など、使い始めるための情報を置きます。
ガイドライン
コンポーネント選定、文言、アクセシビリティ、docs preview、SSOT、レビュー時の確認など、品質判断に使う基準を置きます。
判断例
抽象的な原則を、実装・レビュー時の具体的な判断に落とします。
| 場面 | 避ける | 推奨 | 理由 |
|---|---|---|---|
| 新しく使い始める人 | ガイドラインから読み始める | はじめに、導入、テーマ、採用ガイドを読む | 先に前提と導入手順を揃える必要があるため。 |
| 実装で迷っている人 | 近い見た目を app 側で作る | ガイドラインで責務を確認し、既存コンポーネントを compose する | GunjoUI と docs の品質を同じ基準で保つため。 |
Decision flow
判断の順番
迷った時は、見た目の近さではなく、責務・再利用範囲・検証可能性の順に判断します。
1. 既存コンポーネントで表現できるか
`@gunjo/ui` 本体、近い docs、patterns の利用例を確認します。既存で成立するなら compose して使います。
2. 本体に戻すべき挙動か
tooltip、disabled 理由、overlay containment、mobile input など複数箇所で必要な挙動は本体で直します。
3. SSOT と同期できているか
variant、docs registry、export、design sync の対象かを確認します。手で見た目だけ増やして終わりにしません。
4. preview と code が同じことを伝えるか
表示データ、状態変更、ツールチップ、トースト、エラー、空状態まで、コピーして再現できるコードにします。
判断フロー
上から順に確認し、途中で判断できる場合はそこで決めます。
- 1
目的を分類する
導入情報なのか、実装判断なのか、ユーザー向け文言なのか、検証基準なのかを先に分けます。
- 2
責務のあるページへ置く
導入ははじめに、判断は設計思想、選定はコンポーネント選定、表示文言は文言設計へ寄せます。
- 3
ページ内で使える形まで具体化する
抽象論で終わらせず、判断例、チェックリスト、コードや preview の確認観点まで落とします。
Guide map
各ページの役割
設計思想
GunjoUI 全体の優先順位、SSOT、どこに直すか、issue に分ける判断を扱います。
コンポーネント選定
似ているコンポーネントの責務を分け、Button / Link / Dialog / Drawer / Tooltip などを選ぶ基準を扱います。
アクセシビリティ
キーボード、フォーカス、支援技術、モバイル実機、コントラスト、状態伝達の確認基準を扱います。
ドキュメント基準
docs preview、状態とバリエーション、コード例、SSOT、言語、検証コマンドの基準を扱います。
文言設計
操作文言、エラー、空状態、無効化、日英の粒度、画像代替テキストなど、実際に画面へ出る言葉を扱います。
確認チェック
PR 前、または人間の目視確認前に見る項目です。
読み手が次に読むページを判断できる
概要だけ読んでも、導入・設計思想・文言・docs 基準のどこへ進むべきか分かる状態にします。
各ページが説明だけで終わっていない
判断フロー、判断例、確認チェックのいずれかを持ち、レビュー時に参照できる形にします。