UI

Plain, neutral elements and the components built on them, as Latte partials.

On this page

The ui addon holds two kinds of part. Elements are the basic building blocks, called with {ui}. Components are larger parts built on them, called with {component}. This page covers what both share: calling, setup, size, colour, looks and tokens.

Elements and components

Elements are the core: the simple, common pieces every site needs, at a standard level, like a button, a card and a field. Each does one thing, and they combine by nesting. A component is a larger or more specific part built on elements, like tabs and the panel they load. Components use elements, and elements never use components.

Every param is optional and has a default. The CSS stays inside a rolling five-year browser floor: no nesting, no cascade layers, no color-mix, oklch or :has().

Calling an element

{ui button, title: 'Save' /}

{ui card, title: 'Plan'}
	{ui field, name: 'email', label: 'Email'}
		{ui input, name: 'email' /}
	{/ui}
	{block footer}
		{ui button, title: 'Save' /}
	{/block}
{/ui}

{ui name} renders @ui/name.latte (a site override at site/views/@ui/ first) with only the args it is given, never the caller's params. A button inside a card never picks up the card's class or a controller's title.

An element with no content closes with /}. Content inside a paired {ui} fills the element's {block default}, and {block footer} and the like override its other blocks. That content sees the page's variables, except where the element has a param of the same name: $title inside a card is the card's.

Every element takes class, added to its base class, and attrs, any other attributes such as ['hx-get' => $url]. Both go on the root element, except on a field, where they go on the control.

Setup

A site builds its stylesheet with UnoCSS and this addon's preset. The preset brings the reset, the tokens and the element CSS, then the site's own utilities after them:

import { defineConfig } from 'unocss';
import ui from '../../phlat/addons/ui/assets/preset.mjs';

export default defineConfig({
	presets: [ui()],
});

The layout loads that stylesheet and p('@ui')->file('ui.js') for the shared script behind what CSS cannot do: closing dropdowns, arrow keys between tabs, the exclusive accordion, modals, toasts, and the data-filter, data-select, data-vars, data-pad, data-scroll and data-drag behaviors. It is driven by data attributes and has nothing to re-initialise after an HTMX swap.

Size, colour and looks

Size is the text size. Buttons, inputs, badges, spinners, status dots and avatars are measured in em, so one text-* class resizes the whole element: text-xs, text-sm, text-base, text-lg, text-xl. The box, its padding and its icon grow together, and a responsive prefix changes it by breakpoint (md:text-lg). Buttons, inputs and badges start at their own default size, so a button inside small text is still a normal button. Spinners, status dots and avatars follow the text around them.

Colour is a utility. A token fill such as bg-primary, bg-destructive or bg-well also sets the text colour that sits on it, and a text-* class on the same element still wins: {ui button, title: 'Delete', class: 'bg-destructive' /}.

A look that is more than a colour is a short class passed as class: button-outline, button-ghost, button-link, button-icon, badge-outline, alert-success, toast-warning and so on. Every element rule has no specificity, so any utility on the same element beats it.

Every other data attribute is UI state, except data-gap on .stack and .row, which picks a step of the gap scale.

Tokens

Token names (--canvas, --primary, --primary-contrast, --muted, --card, --border, --ring, --radius and the rest) hold HSL channels: --primary: 0 0% 9%. Alpha is hsl(var(--primary) / 0.9), and utilities get the same names: bg-primary, text-muted, rounded-lg (from --radius). Dark values apply under [data-theme=dark], or with the system preference unless [data-theme=light] is set.

Elements are sized in em and read the tokens directly, so a site restyles one with a plain rule or with utilities on the element.