PUI UI Composition Context

PUI is the UI composition context for Phoenix LiveView applications. It provides reusable primitives for presentation, accessibility, interaction, and form feedback while leaving application business meaning and persistence to the host application.

Toolkit Language

PUI: The reusable UI toolkit and its shared vocabulary. PUI describes how an interface is composed and behaves, not what a host application's business concepts mean. Avoid: application domain, business context

Host application: The Phoenix LiveView application that supplies business meaning, server events, and application state to PUI components. Avoid: client application, consumer domain

Primitive: A small composable UI unit with a focused responsibility, such as a button, trigger, content region, item, field control, or layout shell. Avoid: widget, page component

Component family: A group of primitives that share one interaction or presentation concept, such as a trigger with its popup, or tabs with their panels. Avoid: component bundle, module group

Composition: Combining PUI primitives through attributes and slots to form an interface while keeping each primitive's semantics and interaction contract. Avoid: nesting, assembly

Canonical component module: A public PUI namespace whose primary responsibility is one component family and its composition primitives. Avoid: utility module, catch-all component module

Shared helper: A reusable function that supports multiple component families without defining a standalone visual primitive, such as form-error translation. Avoid: component family, primitive

Icon language

Icon token: A stable semantic name for a visual affordance owned by PUI, independent of any icon library. Avoid: icon class, provider name

Icon provider: The host application's rendering boundary that turns an icon token into the markup or presentation used by its icon system. Avoid: icon library, icon helper

Application-owned icon: An icon selected by the host application to communicate its navigation, business meaning, or brand vocabulary. Avoid: PUI icon, default icon

Presentation Modes

Styled component: A PUI primitive that supplies default visual treatment while still accepting consumer customization. Avoid: default component, opinionated widget

Primitive module: A per-family PUI.<Family>.Primitive module that keeps a component's structure, semantics, and hook contract but adds no visual classes, so the host application owns presentation. Avoid: unstyled component, bare component, styleless widget

Headless path: The PUI usage path where consumers keep PUI's interaction semantics while controlling markup and presentation themselves. It includes the .Primitive modules and direct hook usage. Avoid: custom component, CSS-only mode

Low-level hook: A directly consumed browser behavior that expects the host application to provide the surrounding markup and the hook's required semantic and data attributes. Avoid: JavaScript component, client component

Semantic contract: The roles, states, relationships, focus behavior, and native elements that make a primitive understandable and operable to users and assistive technologies. Avoid: accessibility metadata, ARIA config

State and Interaction

Server-owned state: State that must participate in LiveView rendering, form submission, validation, or application events, such as a selected form value or a dialog's server-controlled visibility. Avoid: backend state, persistent state

Browser-owned state: Ephemeral interaction state that belongs in the browser, such as focus, open animations, popup placement, keyboard position, and resize measurements. Avoid: client state, frontend state

Hook contract: The stable agreement between server-rendered markup and a PUI hook about identity, semantics, interaction state, and synchronization. Avoid: DOM implementation, JavaScript API

Synchronization: The deliberate movement of state across the LiveView/browser boundary through rendered state and interaction signals. Avoid: two-way binding, DOM syncing

Progressive enhancement: The practice of using native HTML behavior where it is sufficient, then adding PUI hooks or LiveView coordination only for richer interaction. Avoid: JavaScript fallback, client-first rendering

Form Language

Field-backed control: A PUI form control bound to a host application's form field, from which it derives identity, submitted value, and validation state. Avoid: bound input, model input

Direct-value control: A PUI form control configured with explicit identity, value, and error attributes instead of a Phoenix.HTML.FormField. Avoid: manual field, uncontrolled input

Validation feedback: The error presentation associated with a form control after the host application's form state marks the field as used or supplies explicit errors. Avoid: form error, validation state

Feedback Language

Feedback surface: A UI primitive that communicates status or progress without owning the business event that caused it, such as an alert, flash message, loading bar, progress indicator, or badge. Avoid: notification system, status domain

Flash message: A transient feedback message supplied by the host application and rendered by PUI, optionally streamed, auto-dismissed, updated, or manually dismissed. Avoid: toast, notification

Layout shell: The structural page frame around application content, including navigation, sidebar state, and content headers. Avoid: dashboard, page layout

Data table: A presentation surface that organizes a collection into labeled columns and rows while leaving data loading and row meaning to the host application. Avoid: query table, grid controller