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.
Add your own elements
A site adds an element by putting its template at `site/views/@ui/name.latte`, then calls it with `{ui name}`. The same path with a built-in's name replaces that element. Style it with a class named like the element, so the site's UnoCSS build finds it.
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.
Theming
Change the base theme's tokens, or add a theme of your own.
UI Elements
The basic building blocks, called with the {ui} tag.
Components
Larger parts built from the elements, called with the {component} tag.
Base
A reset that follows the theme, and the .prose class that styles plain HTML tags.
Patterns
Common layouts built from the elements, with the code to copy.