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. For component/styling choices see
**react**, for wording see **microcopy**, 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).

> The checklists below are the execution layer. Each item is tagged with the
> value(s) it serves; for what those values mean, see the file above.

## Interaction principles

Use these principles 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.

## How this is organized

The checklists are grouped by **interaction type** — the kind of thing the user
is doing. Jump to the module that matches the surface you're building (reading a
list, editing content, running an action, …); each module collects the rules
specific to that interaction. The same surface often spans several modules (an
editable list is Read + Edit + Act) — walk each that applies.

---

## 1. Read — viewing data & lists

Any surface that **displays** records, lists, or detail. Covers the states a data
view can be in, behavior at scale, and keeping the user's place visible.

### 1.1 Data states: empty / loading / error・Meaningful・Certainty

Every data surface has **four** states — design all of them, not just "has data".

- [ ] **Empty state is a purpose-built page, not a blank screen.** It explains what
      this is, why it's empty, and gives a clear next action (CTA + value props).
      ✅ Devices: an empty "Connect your first device" page with primary/secondary
      connect paths and "what you can do once connected" cards — ❌ not a bare title
      over skeleton rows or a blank body. _(Meaningful)_
- [ ] **Distinguish the empty variants** — "no data yet" (onboarding CTA) vs
      "no match for filters" (clear-filters affordance) are different screens. _(Certainty)_
- [ ] **Always-rendered chrome still needs a body empty state.** When a surface
      keeps its toolbar / header mounted even with no data (so a create / `+`
      affordance stays reachable), the **body** below it must still render an empty
      placeholder — persistent chrome is not an excuse to leave the content area
      blank. ✅ The agent **Documents** tab keeps its new-folder / new-doc toolbar
      and renders an `Empty` below it when there are no documents — ❌ not a toolbar
      over dead space. _(Meaningful)_
- [ ] **Loading state** designed (skeleton / NeuralNetworkLoading), not a flash of
      blank or layout shift. _(Natural)_
- [ ] **Error state** designed — surface the reason and a retry/back path. _(Meaningful)_

### 1.2 Lists at scale・Certainty・Natural

A list/data page must be designed for its **whole range of sizes**, not just the
demo data.

- [ ] **Walk the scale: 1 / 2 / 5 / 20 / 100 / 1k–10k rows.** Pick the right
      mechanism per range — plain render → load-more / pagination → virtual scroll;
      add batch-select / bulk actions once counts get large. _(Certainty)_
- [ ] **Co-design empty / loading / error with the data state** (see §1.1). A list
      isn't done until all four render well. _(Natural)_

### 1.3 Selection visibility in scrolled lists・Certainty・Natural

A capped / scrollable / virtualized list mounts at `scrollTop = 0`. If the
active item sits below the fold, the user lands on a valid selection that is
**off-screen** — and reads it as "nothing is selected" or a broken page. Any
list that can open with a pre-selected item must **scroll that item into view**.
This is an easy case to miss: it only shows up once the list is long enough and
the selection is restored rather than freshly clicked.

- [ ] **Scroll the active item into view on mount / restore.** When the selection
      is restored from a URL query, deep link, or persisted state (not a fresh
      click), bring it into view — the container starts at the top otherwise. ✅
      The nested thread list is capped to \~9 rows; a thread restored from
      `?thread=` below the fold is scrolled into view on mount. _(Certainty)_
- [ ] **Hardest when the selection has no other anchor.** If the parent/container
      row isn't highlighted while a child is active (no breadcrumb, no header
      echo), an off-screen active row means **zero** visible feedback — design
      for exactly this case. _(Meaningful)_
- [ ] **Use `block: 'nearest'` (or equivalent).** Only scroll when the row is
      actually off-screen; an already-visible selection must not jump. _(Natural)