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`](../../../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](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](references/read.md)** for the full pattern; the
**react** component-priority rule covers the mechanics.

## Checklist modules

Grouped by **interaction type** — the kind of thing the user is doing. Jump to the module
matching the surface you're building; a surface often spans several (an editable list is
Read + Edit + Act) — walk each that applies.

- **[Read](references/read.md)** — viewing data & lists: empty / loading / error states,
  lists at scale, selection visibility, picker completeness, number formatting, default
  view.
- **[Edit](references/edit.md)** — entering & changing content: protect in-progress
  drafts, never lose input.
- **[Act](references/act.md)** — operations, flows & buttons: forward momentum, one
  primary button, entity lifecycle completeness.
- **[Feedback](references/feedback.md)** — loading visuals & capability guardrails.
- **[Grow](references/grow.md)** — discoverability & progressive disclosure.

## Quick review checklist

The one-screen scan. Each line links back to a module above for the full rule + examples.

**Read — viewing data & lists** ([read.md](references/read.md))

- [ ] Empty / loading / error states are all designed; empty is a real page with a CTA. Always-rendered chrome (toolbar/header) still gets a body empty state. If the `Empty` component ships a `search`/no-match variant, **wire it** — don't render `<Empty/>` bare so a zero-result search shows the first-run onboarding.
- [ ] Error is checked before the empty branch — a failed fetch never renders as empty (read `error`, don't coerce `data ?? [] → Empty`); a detail page reads `error` before falling to `NotFound` (failed-to-load ≠ deleted/404). On a **metrics/dashboard** surface the failure default is a zero-valued object (`?? {…:0}`) that renders as a confident `$0` — read `error` before any aggregate, don't fall through to zeros. A list **merged from a fetched set + a static/frontend set** (`[...fetched, ...placeholders]`) branches `error` before merging — the static half keeps `length > 0`, so a failed fetch renders a plausible partial catalog neither the empty guard nor an error-unread call site catches (channel).
- [ ] List designed across 1 → 10k rows (virt