設計思想
GunjoUI をどう判断して使うかの上位方針です。はじめにが導入・採用の入口だとすると、このページは実装やレビューで迷った時の判断軸です。
Scope
はじめにとガイドラインの役割
はじめには、GunjoUI が何で、どう導入し、どの内部資料へ進むかを示します。ガイドラインは、実装時に何を優先し、どのコンポーネントを選び、どこまでを本体に戻すかを決めるための場所です。
はじめに: 採用と入口
インストール、テーマ、AI 連携、採用ガイド、移行手順、依存関係など、プロジェクトを理解して使い始めるための情報を置きます。
ガイドライン: 判断とレビュー
Button と TextLink の違い、overlay の扱い、docs preview の基準、アクセシビリティの確認など、実装品質を揃えるための考え方を置きます。
Priority
優先順位
GunjoUI はデザインシステムなので、その場の見た目よりも、再利用できる責務と検証できる状態を優先します。
既存コンポーネントを先に使う
新しい UI を作る前に、`src/components/**`、近い docs page、patterns の利用例を確認します。既存で表現できるなら compose して使います。
一時的な見た目合わせを避ける
app 側で似た CSS を書いて終わると、SSOT と実装がずれます。足りない挙動は本体コンポーネント、slot、variant、または issue に戻します。
コードとプレビューを仕様として扱う
表示だけ整っていても、コード例がコピーして使えないなら docs として不十分です。preview、code、SSOT、export が同じ意図を示す必要があります。
モバイルと長い文言を先に疑う
狭い幅、長いラベル、フォーカス、スクロール、ツールチップ、オーバーレイは破綻しやすいので、標準状態だけで完了にしません。
判断例
抽象的な原則を、実装・レビュー時の具体的な判断に落とします。
| 場面 | 避ける | 推奨 | 理由 |
|---|---|---|---|
| 見た目だけ似た UI が必要 | app 側で一回限りの CSS を書く | 既存コンポーネントで compose し、足りない責務は本体に戻す | docs / patterns / downstream app で同じ品質を保つため。 |
| preview だけ崩れている | そのページだけ高さや幅を足す | embed、preview helper、component root のどこで縮んでいるか確認する | 同じ問題が別ページで再発するのを防ぐため。 |
Ownership
どこに直すか
再利用される挙動は `src/components`
tooltip、disabled 理由、overlay の containment、input のフォーカスなど、複数ページで必要なものは GunjoUI 本体で直します。
表示面の問題は docs helper
FIT 幅、embed preview、states / variants の wrapper、preview 内 toast などは page-local ではなく docs helper の責務を疑います。
情報設計は navigation / docs content
サイドバー、パンくず、カテゴリ名、overview の内容はコンポーネント本体ではなく、navigation と docs content の設計として扱います。
大きい判断は issue に残す
カラー再設計、カテゴリ整理、pattern の公開範囲など、1 PR で閉じない判断は issue 化し、暫定対応の範囲を明記します。
判断フロー
上から順に確認し、途中で判断できる場合はそこで決めます。
- 1
利用箇所が複数あるか確認する
複数ページで必要なら本体コンポーネント、1ページ固有なら docs / pattern 側の composition として扱います。
- 2
SSOT の変更対象か確認する
variant、props、export、docs registry に影響する場合は、手作業だけでなく sync / verify の対象にします。
- 3
分けるべき作業は issue にする
カラー再設計やカテゴリ IA のように広範囲へ波及する作業は、暫定対応と本対応を分けます。
確認チェック
PR 前、または人間の目視確認前に見る項目です。
page-local fix で終わっていない
再利用される挙動は `src/components/**`、表示面の共通問題は docs helper に戻しています。
SSOT と export の影響を確認した
コンポーネント本体を触った場合、design sync、generated keys、docs registry、public export を確認しています。