ux

UX — Design Values & Execution Checklists

How LobeHub products should feel, and concrete rules to get there. Use this when building or reviewing any user-facing flow.

This file is the index: the design values and interaction principles below are the conceptual layer; the execution checklists live in per-module reference files (see Checklist modules). Each checklist item is tagged with the design value(s) it serves.

What lives where: DESIGN.md vs this skill

Two documents, two jobs — don't duplicate; cross-reference.

• DESIGN.md — the design system: what the product looks and sounds like. Themeable tokens (color, typography, elevation, radius), the component inventory, and Voice & Content (wording, tone). Reach for it when you need a token value, a component, or copy tone.
• this ux skill — interaction behavior: how a flow should behave over time. Empty / loading / error states, lists at scale, selection visibility, pickers, number formatting, draft safety, action flow & momentum, button hierarchy, entity lifecycle, capability guardrails, progressive disclosure.

Rule of thumb: static look & wording → DESIGN.md; dynamic behavior → this skill. For component/styling choices see react; for imperative modal wiring see modal.

Design values

LobeHub follows four product design values — Natural・Meaningful・Certainty・Growth. Read them before designing: references/design-values.md (definitions + conflict priority).

Interaction principles

Use these before the execution checklists when a flow has multiple plausible interaction patterns.

Preserve the surface contract・Meaningful・Natural

Every surface carries a task promise: chat keeps the user in a working conversation, a document page supports focused reading / editing, a settings page supports configuration, and so on. Default interactions should continue that promise instead of unexpectedly moving the user into another mode. Prefer in-context surfaces (portal / panel / drawer) for reference and auxiliary work; reserve full-page navigation for committed focus or explicit mode switches.

Consistency is semantic, not mechanical・Certainty・Meaningful

Consistency means the same user intent behaves the same way in the same surface. It does not mean the same component must do the same thing everywhere. When a component is reused across surfaces, let the parent surface provide the interaction strategy so behavior follows intent rather than implementation convenience.

Layout communicates role・Natural・Certainty

Element placement is part of the interface language. Identity and location (breadcrumbs, titles, object labels) should read separately from state and actions (save status, sharing, panel toggles, overflow menus). When these roles are mixed, users have to infer whether an element describes the current object or acts on it.

Compose the canonical surface component, don't re-derive it・Certainty・Natural

When a surface class already has a canonical component in this codebase — a sidebar row → NavItem, a collapsible group → Accordion / GroupedAccordion, an active surface → Block variant='filled' — compose it, don't rebuild the chrome from raw <div>/<button>/<input> + a bespoke createStaticStyles block. A hand-rolled parallel re-derives padding, hover/active states, alignment, and reveal-on-hover by hand, and drifts from its siblings on each one — the aggregate reads as "unpolished" even when every single gap is tiny. Before building a list / nav / master-detail panel, find the primitive the sibling surface uses (grep NavItem, Accordion) and compose it; fall to raw elements only for a genuinely novel row. See Read §1.10 for the full pattern; the react component-priority rule covers the mechanics.

ページ内のコンテキストにおけるレビューのメッセージ・確実性

通常の説明と操作を妨げる状態を区別し、役割の異なる警告バナーを同じ目立ち方で重ねて表示しないでください。制限に関する文言では、現在の状態と次のアクションを明示し、正確なプロダクト上のエンティティを使ってください（たとえば、モデルとそのプロバイダーを区別します）。変更したコンポーネントだけでなく、ページ全体を確認してください。

チェックリストのモジュール

インタラクションの種類、つまりユーザーが行っている操作ごとに分類されています。構築する画面に合うモジュールを確認してください。画面によっては複数のモジュールにまたがる場合があります（編集可能なリストは Read + Edit + Act に該当します）。該当するすべてのモジュールを確認してください。

• Read — データとリストの表示：空／読み込み中／エラーの状態、大規模なリスト、選択状態の可視性、ピッカーの網羅性、数値の書式、デフォルト表示。
• Edit — コンテンツの入力と変更：作業中の下書きを保護し、入力内容を失わないこと。
• Act — 操作、フロー、ボタン：操作を前進させること、主ボタンを1つにすること、エンティティのライフサイクルを網羅すること。
• Feedback — 読み込み時の表示と機能上のガードレール。
• Grow — 見つけやすさと段階的な情報開示。

クイックレビュー用チェックリスト

この一覧を使って該当するチェック項目を特定し、詳細な要件と例についてはリンク先のモジュールを参照してください。実装の詳細や事例は各モジュールに記載し、ここに重複して記載しないでください。

Read — データとリストの表示（read.md）

• 初回利用時の空状態、検索結果なし、読み込み中、失敗を区別し、常時表示される画面要素の下に有用な状態説明を表示する。
• 取得エラーを、空状態、見つからない状態、値がゼロの集計、静的なフォールバック項目より先に処理し、それらによってエラーが隠れないようにする。
• 必要に応じてページネーション、仮想化、バッチ操作を用い、1〜10k行のリストに対応する。
• 検索、フィルター、並べ替え、件数、バルク操作の対象範囲は、読み込み済みのページだけでなくデータセット全体を対象にする。
• 選択済みの行が存在する場合は、その項目をスクロールして表示する。ただし、すでに表示されている選択項目は移動させない。
• ピッカーには、デフォルトや受信箱の選択肢を含め、有効な対象をすべて含める。
• K/M/B/Tの桁上がりに対応した共通の数値フォーマッターを使用し、係数が1000以上の値は表示しない。
• 初期表示は、画面への遷移意図と確定したデータに基づいて選び、手動での選択やコレクションレベルの操作へのアクセスを維持する。
• ライブフィードでは更新を通知し、手動更新を可能にし、読み進めている位置を維持し、更新失敗を区別する。
• 条件付きポーリングが確実に開始されるようにする。ライブ状態が不明または失敗している項目を、破壊的なバルク操作の対象に含めない。
• 大規模なナビゲーション画面には、検索、フィルター、またはジャンプ機能を設ける。
• レジストリーカードでは所有済み／インストール済みの状態と信頼状態を一貫して表示し、投稿操作からアプリ内の送信フローに進めるようにする。
• 標準のリスト行とグループ化コンポーネントを再利用する。Read §1.10 と react スキルを参照。
• 常時表示されるコンポーザーの下に、項目が追加されたリストも表示し続ける。増え続けるエディターには上限を設けるか、折りたためるようにする。
• ステータスラベルは、対象となるすべての項目を正確に表す。
• 埋め込みドキュメントはタイトル付きの行に折りたたみ、展開すると全文を下位のタイポグラフィ階層で表示する。
• 画像のないエンティティには、共通の種類を示すグリフを使う。名前の頭文字やUIラベルを使ったアバターは使用しない。

Edit — コンテンツの入力と変更（edit.md）

• ページの再読み込み、保存失敗、項目の切り替え後も下書きを保持して復元する。破壊的な終了操作の前に警告するか、保存する。
• プレースホルダーは内容が変わらないようにし、意味のあるコンテンツをプレースホルダー以外から取得できるようにする。

Act — 操作、フロー、ボタン（act.md）

• 成功すると結果が表示され、終端画面では次に実行できる操作、または画面を離れる方法を提示します。
• 次のステップに影響する結果は保持し、一時的な確認メッセージはトーストで表示します。
• 一括操作と単一アイテム操作の両方の入口を用意します。
• 必要に応じて、確認、処理中の進捗、結果を表示します。時間のかかるアトミック操作では確認画面を閉じ、操作を開始した画面で進捗を表示します。
• 時間のかかる操作やコストのかかる操作では、実行中のキャンセルと、失敗後の再試行に対応します。
• 楽観的な変更やジョブ制御の失敗を明示し、黙ってロールバックしないでください。
• 編集後も、リストビューと詳細ビューの状態を同期します。
• 操作とステータスはスクロール可能なコンテンツの外に固定し、コンテンツがはみ出した状態も確認します。
• 各画面では、視覚的に最も目立つプライマリーアクションを1つにします。
• 各エンティティのソースに適したライフサイクル操作を用意し、削除のすべての経路でピン留め／保持／ロックの設定を尊重します。
• 操作中のユーザーの識別情報と、アカウント切り替えまたは再認証の方法を表示します。
• 元に戻せない操作や広範囲に影響する破壊的操作には、意図的なジェスチャーを必須とし、一部失敗も報告します。
• 新たに生成したシークレットは「コピー」とともに一度だけ表示してからマスクします。検証専用のシークレットはハッシュ化し、サーバーが平文で必要とするプロトコル認証情報は暗号化します。エンティティの認証情報は作成時ではなく、必要になったときにその行で生成します。
• ユーザーメモリー／プロフィールのストアでは、修正、使用せずに保持、エクスポート、取り消しまたはソフト削除に対応します。

フィードバック — 読み込みとシステムの応答（feedback.md）

• 読み込みフォームは、feedback §4.1 のシナリオ表に従います。
• プラットフォームやルートの違いも含め、計測したレンダリングレイアウトに合わせてスケルトンの構造を調整します。
• 読み込みや追加読み込みに失敗した場合は、画面上に復旧手段を提示します。失敗したアイテムは自動的に消さず、表示し続けます。
• 依存するデータ取得のゲートは、データの取得完了、データなし、またはエラーのいずれかで解除し、エラー／未検出の分岐にも到達できるようにします。
• 待機中の書き込みに失敗した場合は、ビジー状態のコントロールを解除します。自動保存では、保存中、保存済み、失敗の状態を示し、再試行できるようにします。
• ローカライズされた、人が理解しやすいエラーを表示します。内部 ID は構造化された検査用フィールドに保持し、原因が明確な失敗では解決策を先に示します。
• 機能に関する警告は設定の解決後に反応的に表示します。モデルの選択肢とプラットフォームの制限は区別します。

拡張 — 見つけやすさと段階的な情報開示（grow.md）

• 初心者向けの操作を煩雑にせず、役立つ場面で高度な機能を表示します。
• キーボードヒントは実際に動作するショートカットに対応させ、実行中の UI で確認します。
• 設定画面から、その機能のデータ領域または管理画面に移動できるようにします。
• 2ステップを超えるフローでは進捗を示し、必須ではないステップはスキップして画面を離れられるようにします。

関連スキル

• ux-audit — 1つの画面を対象に、Designing Interfaces をベンチマークとして監査する再現可能な手法です。ギャップを見つけ、チェックリストに反映するために実行します。
• modal — 確認／進捗／完了を扱う、命令型の createModal 状態マシンの配線です。
• DESIGN.md（Voice & Content）— 確認／完了／空／エラー状態の文言です。
• react — コンポーネントの優先度、Button の使い方、スタイル設定です。