Entity preview

The hover card behind every record reference. Hover or focus a name and the record answers "who is this?" — contact details, state, the next step — without a page change. It opens after 300 ms, portals to <body> and is placed by the same place() logic as Popover (packages/ui/src/components/EntityPreview.tsx, .eref-hc* in apps/web/src/ds.css). Screens reach it through <EntityRefPreview>, which pairs it with an <EntityRef>.

When to use

  • Any reference to a record inside text, a row, a rail or a timeline: person, company, deal, task, meeting, note, document, order, product, user.
  • Where the reader needs two or three facts, not the whole record — the card ends with Otevřít detail, which leads to the one detail the record has.

When not to use

  • As a menu: the card shows facts and one way in, not a list of actions.
  • As a substitute for the record page or the drawer when the user needs to work with the record.
  • For a control's label — that is a Tooltip.
  • For data the user must compare across rows; that is a table column.

Anatomy

  • Card .eref-hc: fixed 280px, --surface-100, hairline, --shadow-pop, z-index: 101, positioned through --eref-hc-x / --eref-hc-y. Height is capped like Popover — max-height: min(60vh, 420px) with overflow: hidden for the rounded corners (acrm !3526, apps/web/src/ds/eref-hc-strop.css).
  • Head .eref-hc-head: the record mark <EntityMark> at its default size (24px box, 16px glyph — ACRM-379; avatar for a person, tile for company, deal, task…) and the name .eref-hc-nm in 500 14px (ACRM-380). The subtitle is the first row with its own icon — dropped when it equals the name (K4).
  • One grid (28 Sep 2026): the identity column --eref-hc-col is the width of the head mark (24px); row icons and 16px avatars sit centred in it, and every value, the facts strip, the excerpt and the unavailable sentence start on the edge of the name (--eref-hc-indent). The footer spans the full card width with its text on the edge of the mark.
  • Facts .eref-hc-facts: parts joined with " · " (value, date); a tone may be carried by a part, never by the strip.
  • Excerpt .eref-hc-excerpt: three-line clamp for a note or an e-mail.
  • Rows .eref-hc-crow: icon .eref-hc-ri or a 16px avatar, then the value .eref-hc-cv — icon + VALUE, never a field label (K1). A clickable value is .eref-hc-act.
  • Faces .eref-hc-faces: stacked avatars with .eref-hc-more for the rest.
  • States: loading = skeleton lines .eref-hc-sk; unavailable = .is-dim with one sentence .eref-hc-msg.
  • Footer .eref-hc-open: Otevřít detail — an <a> when openHref is given, otherwise a button.
  • Body .eref-hc-body: facts, skeleton, excerpt and rows sit in one scrolling column (min-height: 0, overflow-y: auto, gap: var(--sp-3)). The head and the Otevřít detail footer stay outside it with flex: none, so a long card scrolls in the middle and never pushes the action out of sight.

Best practices

Do

  • Send only the fields that have a value; an empty row is not drawn (K3) — the server decides, the card does not pad.
  • Carry a stage or a status as a row with the stage glyph and let the value carry the tone (K2: no pills).
  • Use pinned while a menu opened from the card is up, so the card does not vanish under the pointer.
  • Keep the footer label specific to the kind: Otevřít detail, Otevřít obchod.

Don't

  • Lines inside the card — no separator above or below the rows (ACRM-378). Head, rows and footer are separated by the card's gap only.
  • Field labels in rows ("Telefon: +420…") — the icon is the label.
  • A status pill, a badge or a second colour system inside the card.
  • Actions beyond the one way in; a card is not a menu.
  • A subtitle that repeats the name, or a type prefix in it ("Osoba — Josef Novák").

Content

  • Values as the user would read them aloud; dates follow the year convention (26. 8., 14. 11. 27).
  • The excerpt is the record's own text, cut by the clamp, never an editorial summary.
  • unavailableLabel says plainly why there is nothing: Na tenhle záznam nemáš přístup.
  • entity-reference — the reference that opens this card.
  • record-drawer — the bigger answer to the same question, next to a listing.
  • popover — for actions.
  • Stories: components--entity-preview--default, --variants, --states, --composition; legacy overview components--entity-preview-popover.

Source: docs/popover/entity-preview.usage.md · GitLab