Prior study: ui primitives taxonomy — enumerate and normalize the certain set

[k08200]

Premise (decide first)

From team discussion, ui splits into two systems:

• use uhura::ui; — unstyled primitives, essentially html. Behavior-purposeful, things anyone can agree on (button).
• Styled kits as separate opt-in modules (use uhura::shadcnui; as an example). Styled/opinionated components (attachment) are effectively themes, not primitives — attachment appears nowhere in the checked catalog today.

Proposed constraint that keeps this safe: a kit composes and skins primitives but cannot introduce new checked elements — aria, event payloads, and determinism stay in the core, and normalization happens once instead of per kit. Kits mirror onto primitives, so they are not a one-day job; the one-day scope below is primitives only.

Scope fence: this issue stays at the primitive vocabulary layer. The reusable presentation / component contract is #27's "UI composition" question; the kit constraint above touches that boundary and should be decided consistently with it.

Enumeration (the current checked vocabulary, ui_catalog/elements.rs)

element	content	interactive	events (payload)	html counterpart
button	children	yes	press (Unit)	<button>
input	void	yes	input (TextField), change (BoundaryNumberField)	<input>
textfield	void	yes	change (TextField), submit (Unit)	<input>
text	children	no	—	span/p
view	children	no	—	div
scroll	children	yes	near-end (Unit)	overflow div
img	void	no	—	<img>
video	void	yes	—	<video>
icon	void	no	—	— (convention)
region	children	yes	activate, activate-double (Unit)	section + button semantics
progress	children	no	—	<progress>
fieldset	children	no	—	<fieldset>
pager	children	yes	page-change (Unit)	none
Link	children	yes	follow (Unit)	<a>
Surface	children	no	—	dialog-ish, spec gap

Decisions this study should make

1. input vs textfield overlap. Two input-shaped primitives coexist with different event contracts (typed input/change vs change + submit). One should be canonical, or the split needs a stated rule.
2. pager. The only interactive element with no html counterpart (scroll snap is a CSS mechanic, not an element). Its page-change payload is Unit — a machine learns that the page changed, never which — and it owns an indicator. Certain set, or does it wait with the compositions (carousel = pager + button, Prior study: Uhura element and widget candidate landscape #19 / docs(studies): carousel and pager candidate study #25)?
3. Conditional display. <match> (the svg <switch> role) was proposed instead of tabs. Worth enumerating as a candidate; the element name collides with the core match expression keyword, so the markup/expression namespace question needs a call.
4. Event payload rule. Payload kinds already exist (Unit, TextField, BoundaryNumberField). When is Unit enough (notify) and when must an event carry a value? pager is the current outlier.
5. Aria ownership. Realizations live in the renderer today (pager → role=group, region → role=button). Is the aria mapping part of the primitive's contract (kits may not override), or renderer discretion?

Out of scope: surfaces/modality. That contract is explicitly undecided in #27, and the play comment-modal misplacement comes from the same gap — it deserves its own track rather than a corner of this one.

Deliverable

One page: primitive × {name + required attributes, event payload, aria realization, static preview pose} — direct input for the ui sub-specification.

[k08200]

Recording from team discussion: the two-system premise in this issue (unstyled primitives in use uhura::ui;, styled kits as separate opt-in modules) is to be settled here, so the decision has a durable home outside chat.

[k08200]

Deliverable: the one-page table. Every cell below is measured from main (ui_catalog/elements.rs for attributes/events, web/src/renderer/primitives/* for the aria realization); the pose column is proposal, marked accordingly.

primitive	required attrs	event payload	aria realization today (renderer)	static preview pose
button	—	press: Unit	aria-pressed, aria-busy, aria-label	—
input	—	input: TextField, change: BoundaryNumberField	generic (no adapter refinement)	draft text (proposed)
textfield	label	change: TextField, submit: Unit	aria-label from label	draft text (proposed)
text	—	—	none (plain text)	—
view	—	—	role pass-through (list handled)	—
scroll	—	near-end: Unit	none	position 0..1 (#31 already proposes this)
img	src + exactly-one(alt, decorative)	—	alt/decorative constraint at check time	—
video	src, label	—	aria-label from label	poster frame (proposed)
icon	name	—	aria-hidden (decorative glyph)	—
region	label	activate, activate-double: Unit	role=button + aria-label	—
progress	—	—	generic	value (proposed)
fieldset	—	—	generic	—
pager	label	page-change: Unit	role=group + aria-label, dots aria-hidden	current page (proposed)
Link	routes, to	follow: Unit	anchor semantics	—
Surface	key	—	none — the spec gap (#30, #31)	mounted/dismissed (blocked on the surface contract)

Readings the table makes concrete:

1. Payload asymmetry is visible in one column: input/textfield events carry values, every other interactive event is Unit — including pager.page-change, the one case where the machine plainly needs the value (docs(studies): carousel and pager candidate study #25). An event-payload rule would make this column derivable instead of historical.
2. The aria column is renderer fact, not contract: nothing in the catalog forces region to be role=button or dots to be aria-hidden. If kits may not override aria (Proposal: make HTML the UI baseline and keep only a minimal intrinsic core #31 discussion), this column needs to move into the contract.
3. Under Proposal: make HTML the UI baseline and keep only a minimal intrinsic core #31's disposition most rows collapse to HTML identity and the table shrinks to: intrinsics (scroll, icon), the day-one refinement list (label/alt enforcement, which this table now records), and the pose column.

[softmarshmallow]

Surface/modality now has a dedicated RFD: #41. This issue remains the primitive-vocabulary study; continue Modal/Dialog/Sheet lifecycle, focus, dismissal, accessibility, and renderer-owned motion in #41.