Documentation

smartwebUI in one page

Semantic HTML is the public API, CSS custom properties are the customization API, and one optional script adds interactive behavior. Everything on this page applies to version 1.2.0.

Getting started

Copy smartwebui.css into your project and link it. Add smartwebui.js when you need interactive behaviors such as tabs, the custom select, dialogs, menus, and toasts. There is no installation, build step, compiler, or dependency.

<link rel="stylesheet" href="/assets/smartwebui.css">
<script defer src="/assets/smartwebui.js"></script>

Components are ordinary semantic HTML with class names. The library works with any server stack. PHP can emit the same markup as any other host — there is no Composer package, PHP extension, or compiler. An optional single-file renderer, smartwebui-surface.php, is included for agent surfaces (PHP 8.0+, no dependencies). Styling holds up before JavaScript loads.

Design choices & tradeoffs

smartwebUI is not a React replacement. It is a trusted UI layer for applications where HTML stays authoritative and agents compose within a catalog — not arbitrary markup.

HTML is the runtime; JSON is the agent wire format

Humans, server templates, and agents can all write semantic HTML with smart-* classes. Alternatively, agents can emit validated JSON surfaces that render to the same HTML through the DOM API — the wire format rejects HTML strings inside JSON, not HTML as a medium. There is no third API — the catalog is a subset of what you can hand-author.

When smartwebUI fits

PHP or server-rendered apps that want polished components without a JS framework
Admin tools, internal dashboards, and agent-built operator interfaces
Progressive enhancement: server first paint → adopt() → live patches
Teams that accept a 36-month browser window in exchange for modern APIs and less legacy weight

When to reach for something else

Rich client-side SPAs with complex shared state — React, Vue, or Svelte component ecosystems will feel more natural
Mandated support for legacy browsers or locked-down corporate WebViews — Bootstrap or heavily polyfilled stacks may be required
Teams that need maximum Stack Overflow density and hiring familiarity above agent contracts

Dependency-free means you own the bugs

There is no npm dependency tree to absorb fixes — every picker, upload flow, and patch path is maintained in this website. Release gates and contrast requirements are documented in QUALITY.md; accessibility scope in ACCESSIBILITY.md.

Comparison at a glance

	smartwebUI	Bootstrap	React + UI kit
Public API	HTML + design tokens	CSS classes + JS plugins	Components + JSX
Agent contract	Catalog + surfaces	None	Ad hoc per app
Build step	None	None	Yes (bundler)
Browser window	Last 36 months	Broad legacy support	Depends on bundler targets
Best for	Agent UI, PHP-first, progressive enhancement	General marketing sites	Rich client applications

FAQ

Is this a framework?: No compile step. Optional JavaScript hydrates hand-written HTML. Agent JSON is an optional layer on top — the entire showcase works without it.
Can agents write HTML?: Yes. Agents can output semantic smart-* markup the same way humans do — that is the library’s public API. They can also compose through validated surface JSON, which the agent runtime renders to the same HTML via the DOM API. What surfaces reject is raw HTML strings inside JSON declarations; that boundary keeps generative UI fail-closed. Trusted application code may still use update(..., { html: true }) for its own markup.
Does it work without agents?: Yes. Link smartwebui.css and optionally smartwebui.js. Every component in the showcase is plain markup.
Why only modern browsers?: The library uses the Popover API, native <dialog>, cascade layers, color-mix(), light-dark(), and :has() without polyfills. See browser policy.
Can I use it inside React or Vue?: Possible — mount HTML islands and call hydrate() after render. That is not the primary integration story; expect to manage lifecycle yourself.
What changed in 1.0.2 for validation APIs?: SmartWebUI.validate(form, rules) is the form helper (core). Surface declarations use SmartWebUI.validateSurface(surface) (agent). The 1.0.1 validate(surface) alias was removed — see changelog.
Where is the security model documented?: SECURITY.md — agent threat model, CSP guidance, and e-commerce boundaries. Summarized under agent security.

Canonical inventory

HTML is the public API. The agent catalog is a subset of that HTML: every catalog type has a documented snippet, and every showcase family agents may emit maps to one catalog type. There is no third API.

Two lists both happen to total 38. They are not the same 38 items.

HTML families (38). The component reference numbers 38 families. The showcase shows every family except Payment: foundations 01–15, application patterns 16–36, and Carousel 38 (Payment is family 37, shown in the reference and agent demo). Combobox, File, Date & time, Search, Tags, and Confirm keep their own snippets even though they map onto Field or Dialog. Split actions stay in Button; advanced Field controls stay in Fields; circular progress stays in Progress; groups stay in Avatar; structured feeds and attachments stay in List; consent stays in Alert; Chart is one family with five marks; the lightbox viewer stays in Carousel.
Catalog types (34 + 4). The agent catalog has 34 component types plus 4 layout primitives (Stack, Cluster, Grid, Text). That set includes Icon, which is a documented foundation rather than a numbered HTML family, plus FormErrors, AppHeader, Footer, CommandPalette, Payment, Chart, and Carousel. It does not give Combobox or Confirm their own type names.

#	HTML family	Catalog type
—	Icons (foundation, not a numbered family)	`Icon`
01	Buttons (includes split actions)	`Button`
02	Fields	`Field` `control`: `input`, `textarea`, `select`, `range`, `otp`, `quantity`, `multiselect`, `numericrange`, `rating`, `color` (mask is a property, not a control)
03–05	Choices, Switches, Segmented	`Choice`, `Switch`, `SegmentedControl`
06–15	Cards through Progress	Matching catalog names
16–20	Table, Pagination, Alerts, Form errors, Breadcrumbs	`Table`, `Pagination`, `Alert`, `FormErrors`, `Breadcrumbs`
21	Combobox	`Field` `control: "combobox"`
22–24	Empty, Avatar, List	`Empty`, `Avatar`, `List`
25–26	File, Date & time	`Field` `control: "file"` / `"date"` / `"daterange"` / `"time"`
27	Confirm dialog	`Dialog` `variant: "confirm"`
28–31	Page header, App shell, Chips, Search	`PageHeader`, `AppShell`, `Chip`, `Field` `control: "search"`
32–33	Tags, Stepper	`Field` `control: "tags"`, `Stepper`
34	Header / Footer	`AppHeader`, `Footer`
35	Command palette	`CommandPalette`
36	Chart	`Chart`
37	Payment (reference and agent demo)	`Payment`
38	Carousel & lightbox (strip, gallery grid, zoomable viewer)	`Carousel` `variant: "carousel"` / `"gallery"`, `lightbox`

Icons

smartwebui-icons.svg is a curated, dependency-free SVG sprite built from Lucide plus 17 popular social-network brands. Its 516 stable names are indexed in smartwebui-icons.json. No npm, icon font, custom element, or build step is required for consumers.

<svg class="smart-icon" style="--smart-icon-size: 37px" aria-hidden="true">
  <use href="/assets/smartwebui-icons.svg#smart-icon-sparkles"></use>
</svg>

--smart-icon-size accepts any valid CSS size: 17px, 2.4em, 10vw, or clamp(1rem, 4vw, 5rem). Set --smart-icon-stroke to tune line weight. The optional helper creates safe DOM nodes:

const icon = SmartWebUI.icon("arrow-right", {
  size: "clamp(1rem, 4vw, 5rem)",
  stroke: 1.75,
  label: "Continue"
});

Omit label for decorative icons next to visible text; provide it for a meaningful standalone icon. Directional icons flip automatically in right-to-left layouts. External SVG sprites should be served from the same origin for the most reliable browser behavior. A different trusted path can be configured with SmartWebUI.setIconSource().

Use sprite icons—not font glyphs—for interface actions and status marks such as close, search, previous/next, add/remove, overflow, warnings, and ratings. Keep punctuation, mathematical notation, keyboard characters, and prose symbols as text. Icon-only controls still require a textual aria-label; their SVG remains aria-hidden="true".

Customizing

Override design tokens after the stylesheet. Every component reads the same variables, so one override updates the whole interface immediately.

:root {
  --smart-accent: #ff3b30;
  --smart-radius-control: 999px;
  --smart-font-sans: "Avenir Next", sans-serif;
  --smart-motion-duration: 180ms;
  --smart-control-height: 3rem;
}

Theme colors are written as light-dark() pairs resolved through color-scheme. Light and dark themes follow the operating system preference automatically; <html data-theme="dark"> forces a theme. Density (data-density="compact") and the Liquid material (data-material="liquid") are opt-in the same way.

Library CSS lives in cascade layers. Unlayered host CSS wins. See the token reference for the public variable list and the layer order.

Token reference

Public custom properties on :root. Override these after loading smartwebui.css. Names that start with --_ are private to a component and are not part of the API.

Host CSS should stay unlayered so it wins over every @layer smart.* rule, including Liquid (smart.materials). If you use layers, declare them after the library list: smart.reset, smart.tokens, smart.base, smart.layout, smart.components, smart.materials, smart.utilities.

Token	Default	Used by
Typography
`--smart-font-sans`	Inter, system UI stack	All text
`--smart-font-mono`	SFMono, Consolas	Code, metrics
`--smart-font-size-0` … `7`	0.75rem … clamp display	Labels through hero type
`--smart-font-weight-regular` … `bold`	400 / 560 / 650 / 740	Body, labels, titles
`--smart-letter-spacing-tight` / `--smart-letter-spacing-label`	-0.035em / 0.015em	Headings, uppercase labels
Spacing and shape
`--smart-space-1` … `12`	0.25rem … 7rem	Layout, stacks, sections
`--smart-container-sm` / `--smart-container-md` / `--smart-container-lg`	40rem / 56rem / 76rem	`.smart-container--*` width caps
`--smart-radius-control`	`--smart-radius-sm`	Buttons, fields, segmented
`--smart-radius-surface`	`--smart-radius-lg`	Cards, dialogs, customizer
Color
`--smart-accent`	light-dark indigo	Primary actions, focus, links
`--smart-on-accent`	white / near-black	Text on accent fills
`--smart-danger` / `--smart-on-danger`	red pair	Destructive actions
`--smart-success` / `--smart-warning` / `--smart-info`	status pairs	Badges, alerts, toasts
`--smart-canvas` / `--smart-surface`	page and card fills	Surfaces
`--smart-text` / `--smart-text-secondary` / `--smart-text-tertiary`	primary / muted	Copy hierarchy
`--smart-border` / `--smart-divider`	12% / 9% ink	Controls and rules
`--smart-focus-color`	accent mix	Focus rings
Controls and motion
`--smart-control-height`	3rem	Buttons, inputs, selects
`--smart-control-padding-x`	1rem	Horizontal padding inside controls
`--smart-form-gap`	`--smart-space-5`	Row spacing in forms and form stacks
`--smart-field-gap`	`--smart-space-3`	Label-to-control spacing inside `.smart-field`
`--smart-motion-duration`	220ms	Standard transitions, view transitions
Layering
`--smart-z-raised` / `--smart-z-sticky`	4 / 10	Shell sidebar, sticky regions
`--smart-z-tooltip` / `--smart-z-toast` / `--smart-z-banner`	20 / 40 / 50	Tooltips, toasts, compat banner
`--smart-overlay`	34% / 62% ink	Dialog backdrop, shell scrim
Liquid
`--smart-liquid-opacity`	56%	Surface transparency
`--smart-liquid-accent-opacity`	84%	Primary / danger fills
`--smart-liquid-blur` / `--smart-liquid-saturate`	38px / 190%	Backdrop material
`--smart-liquid-glow-size`	8rem	Pointer highlight

When overriding --smart-accent or --smart-danger, also set --smart-on-accent and --smart-on-danger so contrast stays AA.

Utilities

Single-purpose classes in @layer smart.utilities — the last layer, so they win over components. Spacing steps reference the --smart-space-* scale, which means compact density and token overrides apply automatically.

Spacing

.smart-p-0….smart-p-8 — padding; .smart-px-* / .smart-py-* for inline / block axes; .smart-pt-* / .smart-pb-* / .smart-ps-* / .smart-pe-* for logical start/end sides. Steps 9–12 remain token-only for page-level spacing.
.smart-m-0….smart-m-8 — margin; .smart-mx-* / .smart-my-* for axes; .smart-mt-* / .smart-mb-* / .smart-ms-* / .smart-me-* for logical sides; .smart-m-auto / .smart-mx-auto / .smart-my-auto for centering
.smart-gap-0….smart-gap-8 — gap for .smart-stack, .smart-cluster, .smart-grid, or any flex/grid host

Layout

.smart-container with .smart-container--sm / --md / --lg — width cap + auto margins (40rem / 56rem / 76rem)
.smart-grid--2 / --3 / --4 — fixed column grids that collapse under 50rem; .smart-span-2, .smart-span-full for cell spans
.smart-span-desktop-2 / .smart-span-desktop-full apply spans only on desktop; .smart-sticky and .smart-sticky-top use the library sticky z-index.
.smart-z-raised, .smart-z-sticky, .smart-z-tooltip, .smart-z-toast, and .smart-z-banner expose the public z-index token scale without hard-coded numbers.
.smart-divider and .smart-divider--vertical create token-driven separators with consistent spacing.
.smart-ratio-1x1 / -4x3 / -16x9 / -21x9 — media boxes; children are stretched to cover. Override the crop with .smart-object-contain / -cover / -fill / -scale-down on the child (logos, screenshots).
Native <figure> / <figcaption> are styled in the base layer — caption tone, size, and spacing come free, no classes.
.smart-w-auto / -25 / -33 / -50 / -66 / -75 / -full and .smart-h-full — Bootstrap-style dimension utilities; thirds are exact calc() fractions.
.smart-control-sm / .smart-control-lg — size any form control by overriding --smart-control-height locally: inputs, selects, date pickers, segmented controls, tabs and buttons all consume the same token, so one class aligns a whole row. Density still applies on top.
Form spacing tokens — override --smart-form-gap (row spacing in form.smart-stack, card bodies, and dialogs) and --smart-field-gap (label-to-control spacing) without touching markup.
.smart-reveal — fade-slide in on first scroll into view; stagger with --smart-reveal-delay. Content stays visible if JS never runs.
.smart-animate plus an effect class — opt-in .smart-enter-fade, --up, --down, --start, --end, or .smart-enter-scale entrances; matching .smart-leave-* exits; and one-shot .smart-attention-pulse, --shake, or --flash cues. Tune a single element with --smart-animation-duration, --smart-animation-delay, --smart-animation-ease, and --smart-animation-iterations. Start/end mirror in RTL and all effects stop under reduced motion.

Typography

Semantic scale: h1 through h6 use the token scale automatically; h2 is the display/section size, while h5 and h6 cover supporting and eyebrow headings.
Sizes: .smart-text-xs, .smart-text-sm, .smart-text-base, .smart-text-lg, .smart-text-xl
Tones: .smart-text-secondary, .smart-text-tertiary, .smart-text-success, .smart-text-warning, .smart-text-danger (and .smart-muted)
Alignment: .smart-text-start, .smart-text-center, .smart-text-end — logical, RTL-safe
.smart-truncate (one line), .smart-line-clamp-2/3/4 (multi-line), .smart-balance, .smart-mono, and font-weight helpers.
.smart-kbd styles shortcut hints such as ⌘ K.

Visibility

Prefer the native hidden attribute — the reset guards it against display overrides. SmartWebUI.hide(el) / SmartWebUI.show(el) toggle it, and agent nodes accept a universal hidden: true property.
.smart-hidden (display: none) when a class toggle is easier; .smart-invisible hides without removing layout
.smart-hidden-mobile hides under 50rem; .smart-visible-mobile shows only under 50rem
.smart-hidden-tablet / .smart-visible-tablet target 50–74.99rem; .smart-hidden-desktop / .smart-visible-desktop target 75rem and wider.
.smart-visually-hidden keeps content available to assistive technology only
.smart-skip-link is visually hidden until focused, then appears at the start of the page. Point href at the main landmark (#main).

<a class="smart-skip-link" href="#main">Skip to content</a>
<main id="main">…</main>

Surface

.smart-elevated-0 / -1 / -2 — none, small, medium shadow
.smart-rounded-sm / -md / -lg / -full, .smart-bordered
.smart-w-full, .smart-min-w-0 (flex/grid overflow fix), .smart-overflow-x-auto

Scroll panes

.smart-scroll-y / .smart-scroll-x — self-scrolling regions with thin scrollbars and contained overscroll, for message lists and long feeds.
.smart-pane-fill, .smart-pane-tall (min(60vh, 32rem)), .smart-pane-screen (100svh minus --smart-pane-offset) — pane heights for messenger-style layouts where a header or composer stays fixed.

Application layout helpers

Optional classes for common product shells — page main columns, auth forms, reading-width content, card grids, and log output. They compose with .smart-stack, .smart-cluster, and .smart-grid.

Class	Purpose
`smart-page-main`	Default public page main spacing
`smart-shell-main`	App shell main column spacing
`smart-cluster--center`	Horizontally center a flex cluster
`smart-stack--tight`	Reduced vertical stack gap
`smart-auth-layout`	Narrow centered auth form column (max 44rem)
`smart-auth-logo`	Login/register logo sizing
`smart-reading-card`	Prose-width card container
`smart-tile-card`	Icon + title link tile (with `smart-card--interactive`)
`smart-card__feature-icon`	Large icon badge for tiles and pickers
`smart-grid--cards`	Equal-height card grid
`smart-grid--tiles`	Tile grid min width (combine with `--cards`)
`smart-grid--pickers`	Choice/picker card grid
`smart-card--picker`	Centered picker tile styling
`smart-log-panel`	Scrollable monospace log output

Print

.smart-no-print hides any element on paper; popovers, toasts, dialogs, and app-shell controls are hidden automatically in @media print.
.smart-print-document flattens a card into a print-ready document — shadows removed, black on white — for invoices, quotes, and receipts.

JavaScript API

The optional script exposes a frozen SmartWebUI global. Every method works on ordinary DOM elements, so it composes with any server-rendered or client-rendered page.

One global, two validation roles. SmartWebUI.validate(form, rules) validates form fields (core). SmartWebUI.validateSurface(surface) validates agent JSON (requires smartwebui-agent.js). Do not pass surface declarations to validate(). With the agent script loaded, the same SmartWebUI object extends the core API — one script tag pair for simplicity.

`SmartWebUI.update(target, content, options)`

Replaces the content of an element with a View Transition when the browser supports one, or an immediate accessible update otherwise. Strings are inserted as plain text by default. Pass { html: true } only for trusted application markup, and { replace: true, html: true } to replace the element itself. Pass a Node to insert structured DOM without parsing HTML.

Agent-produced content must go through render() and patch() — not HTML strings in update().

`SmartWebUI.toast({ title, message, duration, tone, placement })`

Shows a dismissible notification in the polite live region. tone is one of success, info, warning, or danger; duration: 0 keeps it until dismissed. placement accepts top-start, top-center, top-end, bottom-start, bottom-center, or bottom-end.

`SmartWebUI.setTheme(theme)` · `setDensity(density)` · `setMaterial(material)`

Apply light/dark/auto themes, comfortable/compact density, or the solid/liquid material. Choices persist to localStorage when available and dispatch a matching smart: event.

`SmartWebUI.setBusy(button, busy)`

Sets aria-busy on a button and disables it while a save or other in-flight action runs. Call setBusy(button, false) to restore the previous disabled state.

`SmartWebUI.validate(form, rules, options)`

Runs declarative rules against a form and wires the results into the Field pattern: aria-invalid on failing controls, linked .smart-error messages, .smart-field--invalid on wrappers, and an optional FormErrors summary ({ summary: "#form-errors" }). The summary is built with DOM text nodes — labels and messages are never interpolated into HTML. Rules per field name: required, email, minLength, maxLength, pattern, match, min, max, custom(value, form), plus label and message overrides. Returns and dispatches { valid, issues } via smart:validate.

`SmartWebUI.setLocale(strings)`

Overrides component chrome strings — placeholders, aria labels, picker buttons, upload and validation messages — for any subset of keys (SmartWebUI.t(key) reads one back). Dates and currency always format through Intl; RTL works via dir="rtl" as always. Dispatches smart:locale.

`SmartWebUI.upload(input, url, options)`

Uploads the file in a dropzone-enabled file input with a live progress bar, returning a promise for the server response. Options: method, fieldName, fields (extra form values), headers. Progress and completion arrive as smart:upload-progress, smart:upload-done, and smart:upload-error events on the input.

`SmartWebUI.countdown(target, seconds, options)`

Renders an m:ss countdown into any element, ticking once per second, and returns a controller with stop(), start(), and reset(seconds). Options: format, warnBelow (adds .smart-countdown--warn), onTick, onExpire. Declaratively, data-smart-countdown="180" (with optional data-countdown-warn) starts on hydration — the session-timeout pattern. Events: smart:countdown, smart:countdown-expire.

`copy()` · `confirm()` · formatters

copy(text) writes plain text to the clipboard and returns it. confirm(options) opens an accessible native dialog and resolves to a boolean. formatDate(), formatNumber(), formatCurrency(), and formatRelativeTime() provide dependency-free Intl-based display formatting with optional locale settings.

`debounce()` · `throttle()` · `shortcuts`

debounce(callback, delay) and throttle(callback, interval) handle search and scroll work. SmartWebUI.shortcuts.register("mod+k", handler, options) registers a normalized keyboard shortcut and returns an unregister function; mod maps to Command on macOS and Control elsewhere.

`observeBreakpoint()` · `observeLoadMore()` · `observeConnectivity()`

observeBreakpoint(query, callback) exposes a cleanup-friendly matchMedia observer. observeLoadMore(sentinel, callback, options) wraps IntersectionObserver for infinite lists. observeConnectivity(callback) reports navigator.onLine immediately and on browser online/offline events. Each returns a cleanup function.

`focusFirst()` · `trapFocus()`

focusFirst(target, options) moves focus to the first usable descendant. trapFocus(target, options) exposes the library's focus-loop behavior for custom host surfaces and returns a cleanup function that can restore prior focus. Native dialogs remain preferred when modal semantics apply.

`trackDirty()` · `queryState`

trackDirty(form, options) compares live form data with a resettable baseline, toggles data-smart-dirty, dispatches smart:dirty, and optionally guards beforeunload. queryState.read/write/apply/bind synchronizes named filter and table controls with URLSearchParams through replace-state by default.

`virtualize()` · `scrollToTop()`

virtualize(target, items, renderItem, options) windows fixed-height rows with configurable itemHeight and overscan, returning update, refresh, scroll, and destroy controls. scrollToTop() honors reduced motion; data-smart-scroll-top turns a .smart-scroll-top button into an automatically revealed affordance.

`SmartWebUI.hydrate(root)`

Initializes popovers, custom selects, comboboxes, multi-selects, date and time pickers, dual ranges, ratings, masks, color outputs, command palettes, app headers, attachment removal, table selection and expandable rows, app shells, steppers, search, file/dropzone, quantity, password strength, OTP, countdowns, tabs, segmented controls, ranges, tooltips, and charts inside any element. Call it after inserting smartwebUI markup dynamically so new components behave like static ones.

TypeScript types for the core and agent globals live in smartwebui.d.ts.

Markup behaviors

Common interactions need no JavaScript of your own — add a data attribute.

data-smart-open="#dialog-id" opens that <dialog> modally and returns focus on close.
data-smart-close closes the closest dialog from any button inside it.
data-smart-collapse="#region-id" toggles the hidden attribute on any region from a remote trigger, with aria-expanded / aria-controls managed for you.
data-smart-scrollspy on a table-of-contents nav highlights the link whose section is in view via aria-current="location" — this page's sidebar uses it.
data-smart-toast with optional data-toast-title, data-toast-message, and data-toast-placement fires a toast on click.
data-smart-breadcrumbs-collapse folds deep breadcrumb middles; data-smart-scroll-top provides an automatically revealed return-to-top button; data-smart-connectivity reflects browser online/offline state.
data-smart-theme, data-smart-density, and data-smart-material apply preferences on click.

Events

Components announce changes through bubbling custom events, so integration stays decoupled from markup.

smart:tab from tab activation, smart:select from the custom select, smart:combobox from filterable fields.
smart:date and smart:time from custom date and time pickers; range pickers include start and end.
smart:tags from tag fields, smart:multiselect from multi-select dropdowns, smart:range from dual ranges, and smart:rating from ratings.
smart:attachment-remove from removable file rows; smart:copy after a successful copy action.
smart:sort from table sort buttons, smart:table-select and smart:table-action from bulk selection, smart:step from steppers, smart:chip-remove from removable chips.
smart:confirm after a confirm dialog is accepted, smart:toast-action from toast action buttons, smart:accordion from disclosure toggles, and smart:breadcrumbs when a collapsed path expands.
smart:connectivity, smart:dirty, smart:query-state, and smart:virtualize expose host-level state changes.
smart:update after update() replaces a region.
smart:quantity from stepper buttons, smart:strength while typing scored passwords, smart:otp from OTP digit rows ({ value, complete, length }), smart:validate after validate().
smart:file when a pick or drop is accepted or rejected; smart:upload-progress, smart:upload-done, smart:upload-error around upload().
smart:board and smart:move from Kanban card drops ({ cardId, fromColumnId, toColumnId, fromIndex, toIndex }); smart:send from conversation composers ({ value, textarea }); RichText fields also emit smart:change with { value, control } (agent-bound controls use the surface smart:change shape instead).
smart:locale after setLocale() overrides chrome strings.
smart:theme, smart:density, smart:material when preferences change.
smart:action and smart:change from agent-rendered controls (below).
smart:surface and smart:patch after agent rendering and patching; smart:adopt after server-rendered markup is registered; smart:agent-ready when the agent runtime loads.
smart:compat with the missing feature list when data-smart-compat detects an unsupported browser; smart:stripe-ready and smart:payment-ready from the payment companion.

Agent surfaces

The optional agent runtime (smartwebui-agent.js, loaded after smartwebui.js) lets generative systems compose interfaces from a declarative JSON contract. Agents can also write hand-authored smart-* HTML directly — surfaces are the fail-closed path when JSON is the wire format.

const surface = {
  surface: "project-summary",
  root: {
    type: "Stack", id: "summary", gap: "medium",
    children: [
      { type: "Card", id: "revenue", label: "Monthly revenue", value: "$48.2k", change: "+12.4%" },
      { type: "Button", id: "report", label: "View report", variant: "primary", action: "open-report" }
    ]
  }
};

SmartWebUI.render("#agent-surface", surface);

The renderer builds elements through the DOM API and never accepts HTML strings, JavaScript, classes, or inline styles inside a surface declaration. Each node is validated against its catalog property map — unknown keys fail closed. href and src accept only http(s), mailto:, relative paths, and in-page hashes. Surface data is otherwise structurally validated: plain objects only, unique IDs, and depth, node-count, and text-length limits. Buttons emit smart:action events; the runtime never executes agent-provided code.

Stable IDs support live updates with four patch operations — data.patch, node.upsert, node.remove, and node.append — and focus is preserved across patches when possible. node.append (or SmartWebUI.append(target, { parent, node | nodes })) grows a container as items arrive, the streaming shape for SSE and WebSocket token flows.

SmartWebUI.patch("#agent-surface", {
  type: "data.patch",
  id: "revenue",
  changes: { value: "$51.7k", change: "+14.1%" }
});

SmartWebUI.validateSurface(surface) checks a declaration before rendering, returning { valid, errors } plus structured issues: [{ path, message }] that agents can self-correct from.
SmartWebUI.snapshot(target) reads a live surface back: { capturedAt, nodes: { [id]: { type, value?, checked?, selected?, expanded?, step?, open?, hidden? } } } — field values, date ranges, switch states, tab selection, accordion panels, stepper progress, table selections, dialog state, all keyed by stable id.
SmartWebUI.loadCatalog() fetches smartwebui.catalog.json, the machine-readable contract of components, properties, composition rules, and accessibility expectations.
SmartWebUI.history(target) records every patch applied to a surface with its precise inverse — undo(), redo(), clear() — so agents and users can roll back interface changes safely.
Server-side rendering: smartwebui-surface.php (a dependency-free PHP class) emits the same semantic HTML with stable IDs and an embedded declaration via SmartWebUISurface::container($surface). In the browser, SmartWebUI.adopt("#target") registers that markup without a rebuild — dispatching smart:adopt — after which patch(), snapshot(), and history() behave exactly as on client-rendered surfaces.
/llms.txt summarizes the whole library — conventions, utilities, catalog, events — in the format coding agents look for.
Dialogs and drawers accept open: true to open modally once the surface mounts; toasts are announced through the standard toast region.

Server-first workflow

The recommended path for PHP and other server stacks:

Agent or application produces a validated surface JSON object.
Server renders first paint with SmartWebUISurface::container($surface, ["id" => "report"]) — same HTML, stable data-smart-id attributes, embedded declaration.
Browser loads smartwebui.js + smartwebui-agent.js, then SmartWebUI.adopt("#report") registers the DOM without a client rebuild.
Live updates use patch(), append(), snapshot(), and history() on the adopted surface.

<?php echo SmartWebUISurface::container($surface, ["id" => "report"]); ?>
<script defer src="/assets/smartwebui.js"></script>
<script defer src="/assets/smartwebui-agent.js"></script>
<script>document.addEventListener("DOMContentLoaded", () => SmartWebUI.adopt("#report"));</script>

See the agent demo for a live server-rendered surface with adopt, streaming append, and undo/redo. A conformance test suite for ports in other languages is planned.

Streaming & concurrency

node.append / SmartWebUI.append() is for growing lists and feeds as tokens arrive — not replacing whole trees mid-edit.
Concurrent patches to the same node are last-write-wins unless the host serializes an operation queue.
Focus is preserved across data.patch when possible; streaming append does not move focus — announce critical updates with your own live region if needed.
Use history() to roll back mistaken agent patches during development and operator workflows.

Agent security

The agent runtime validates every surface before render and refuses HTML strings in JSON, scripts, classes, and unsafe URLs. Actions are events — your application executes them; the library never runs agent code. Agent-generated markup outside the surface protocol is the same HTML API humans use — the host decides whether to trust or sanitize it.

Threat	Mitigation
XSS via agent HTML	Surfaces use typed nodes only — no HTML strings in JSON
Open redirect	`href` / `src` allowlist
Payment spoofing	`Payment` amounts are display-only; charge server-side
Malicious patch	Validate before render; host may reject operations
Misleading copy	Agent `text` is not verified — treat like user-generated content

Full threat model, CSP guidance, and reporting: SECURITY.md in the repository root.

E-commerce scope

In scope: checkout UI slot (Payment node), token-aware Stripe Elements via smartwebui-stripe.js, Address and Express Checkout element types, print styles for invoices and receipts.

Out of scope: cart logic, tax calculation, inventory, webhooks, PCI scope — the host application owns commerce rules and secrets.

“E-commerce ready” means checkout UI hooks and agent-safe payment intent — not a Shopify alternative.

Component reference

Thirty-eight HTML families for product screens. HTML is the public API. The agent catalog is a different list of 34 component types plus 4 layout primitives (also 38 entries, including Icon, which is not a numbered family). Variations stay with their parent family instead of inflating the inventory. See the inventory, the foundation showcase, and application patterns.

01 Buttons

Initiate an immediate user action with clear hierarchy and tactile feedback.

Classes: .smart-button, modifiers --primary, --quiet, --link, --danger, --small, --large, --icon, --full; group with .smart-button-group; attach a menu with .smart-split-button
Data attributes: data-smart-toast, data-toast-title, data-toast-message on triggers; use aria-pressed for toggle groups; aria-busy="true" for a saving spinner
Events: Native click; optional toast via data-smart-toast; agent buttons emit smart:action
Agent catalog: Button — label, variant (including link), size, fullWidth, pressed, action, disabled, busy; add splitItems[] and menuLabel for the attached-menu variation
Accessibility: Visible label or aria-label on icon buttons; one primary action per decision area

Markup

<button class="smart-button smart-button--primary" type="button">Continue</button>
<button class="smart-button smart-button--primary" type="button" aria-busy="true" disabled>Save</button>
<button class="smart-button smart-button--danger smart-button--small" type="button"
  data-smart-toast data-toast-title="Deleted" data-toast-message="Item removed.">Delete</button>
<div class="smart-button-group" role="group" aria-label="Alignment">
  <button class="smart-button smart-button--small" type="button" aria-pressed="true">Left</button>
</div>
<div class="smart-split-button">
  <button class="smart-button smart-button--primary" type="button">Save</button>
  <button class="smart-button smart-button--primary smart-split-button__menu" type="button" id="save-menu-trigger"
    popovertarget="save-menu" aria-haspopup="menu" aria-expanded="false" aria-label="More actions">
    <span class="smart-button__menu-indicator" aria-hidden="true"></span>
  </button>
  <div class="smart-popover" id="save-menu" popover data-smart-anchor="save-menu-trigger">
    <div class="smart-menu" role="menu">
      <button type="button" role="menuitem">Save &amp; review</button>
      <button type="button" role="menuitem">Save as template</button>
    </div>
  </div>
</div>

smartwebUI in one page

Getting started

Design choices & tradeoffs

HTML is the runtime; JSON is the agent wire format

When smartwebUI fits

When to reach for something else

Dependency-free means you own the bugs

Comparison at a glance

FAQ

Canonical inventory

Icons

Customizing

Token reference

Utilities

Spacing

Layout

Typography

Visibility

Surface

Scroll panes

Application layout helpers

Print

JavaScript API

SmartWebUI.update(target, content, options)

SmartWebUI.toast({ title, message, duration, tone, placement })

SmartWebUI.setTheme(theme) · setDensity(density) · setMaterial(material)

SmartWebUI.setBusy(button, busy)

SmartWebUI.validate(form, rules, options)

SmartWebUI.setLocale(strings)

SmartWebUI.upload(input, url, options)

SmartWebUI.countdown(target, seconds, options)

copy() · confirm() · formatters

debounce() · throttle() · shortcuts

observeBreakpoint() · observeLoadMore() · observeConnectivity()

focusFirst() · trapFocus()

trackDirty() · queryState

virtualize() · scrollToTop()

SmartWebUI.hydrate(root)

Markup behaviors

Events

Agent surfaces

Server-first workflow

Streaming & concurrency

Agent security

E-commerce scope

Component reference

Markup

Markup

Validation

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Markup

Toolbar variation

Markup

Markup

Markup

Markup

`SmartWebUI.update(target, content, options)`

`SmartWebUI.toast({ title, message, duration, tone, placement })`

`SmartWebUI.setTheme(theme)` · `setDensity(density)` · `setMaterial(material)`

`SmartWebUI.setBusy(button, busy)`

`SmartWebUI.validate(form, rules, options)`

`SmartWebUI.setLocale(strings)`

`SmartWebUI.upload(input, url, options)`

`SmartWebUI.countdown(target, seconds, options)`

`copy()` · `confirm()` · formatters

`debounce()` · `throttle()` · `shortcuts`

`observeBreakpoint()` · `observeLoadMore()` · `observeConnectivity()`

`focusFirst()` · `trapFocus()`

`trackDirty()` · `queryState`

`virtualize()` · `scrollToTop()`

`SmartWebUI.hydrate(root)`