Entity preview — accessibility
Keyboard
- The card opens on focus as well as on hover (300 ms
delay), so tabbing through references in text shows the same information a mouse user gets. - Everything inside is reachable: the clickable values (
.eref-hc-act) and the footer (<a>or<button>) are real controls. - The card closes when focus leaves the reference and its card, or when the pointer leaves both.
pinnedkeeps it open while a menu opened from it is up. - Escape is not handled by the card itself; moving focus away closes it.
ARIA
- The card is announced as a dialog-like layer named by
ariaLabel(defaulting to the record name), so a screen reader says whose card this is before reading it. - Rows are icon + value with no label text, so the icon must not be the only carrier of meaning: the value has to read on its own ("+420 605 123 456", "Jednání"). This is canon K1 and an accessibility requirement at the same time.
- The loading skeleton is decorative; the
unavailablestate is a sentence in the card, not a role change. - The trigger keeps its own semantics (
EntityRefis a button or a link); the card does not change them.
Focus
- Foundation ring from
ds.csson the clickable value and the footer control. - Opening the card does not move focus — the reference keeps it, and Tab then enters the card because it is portalled after the trigger only in DOM order; where it lands depends on the page. (Same portal caveat as Popover.)
- The card has no focus trap and does not need one; it is not modal.
Contrast
Computed from packages/ui/src/tokens/tokens.css:
- Name
.eref-hc-nm--ink-900on--surface-100= 17.59:1 light, 14.53:1 dark. - Row value
.eref-hc-cv--fg= 17.59:1 light, 14.53:1 dark. - Row icon
.eref-hc-riand the facts strip--fg-muted= 2.85:1 light, 3.63:1 dark — below AA for text and below the 3:1 non-text minimum in light theme. unavailablestate adds.is-dim, which lowers the whole card further — acceptable only because the state carries no data.- Footer link
--accenton--surface-100= 4.44:1 light, 3.83:1 dark. - Card border: hairline, below the 3:1 non-text minimum;
--shadow-popdoes the separating.
Known limits
- The facts strip and the row icons sit at 2.85:1 in light theme.
- The 300 ms delay plus the hover-out close makes the card hard to use with a tremor or a coarse pointer; there is no click-to-pin from the reference itself.
- No touch path: on a phone there is no hover, and the reference opens the record instead.
- The card grows with its content — there is no max height and no internal scroll, so an over-filled card can exceed a short viewport.
Source: docs/popover/entity-preview.a11y.md · GitLab