01 — Start

Overview

Xubz ships as Web Components — standard Custom Elements plus a token stylesheet — so one implementation is consumed natively by every JS framework, and by any PHP or Java stack that renders to HTML, and by any Rust frontend that renders to a webview or the DOM. This entire site, including every live example below and on the Components page, is built with the real package — nothing here is a mockup.

Status

This documents the intended public API. Package names below (@xubz/elements, xubz/xubz-blade, org.xubz:xubz-thymeleaf, xubz-dioxus) are the proposed surface — nothing is published to npm, Packagist, Maven or crates.io yet.

02 — Install

Installation

1

Add the package

One install brings the tokens and every element.

npm / pnpm / yarn

npm install @xubz/elements

2

Load the tokens once

A single stylesheet defines every color, radius, spacing and motion token, in both themes.

import '@xubz/elements/tokens.css';
import '@xubz/elements';

3

Use a component

No wrapper, no adapter — the tag works anywhere HTML is rendered.

<xb-button variant="primary">Calibrate device</xb-button>

03 — Proof

Try it live

Not a screenshot — every tag on this page is the real custom element, defined once by the script this whole site loads.

Calibrate device

Secondary

In tolerance

Out of range

Frameworks

Vanilla HTML

Works with zero tooling — a script tag and the tags are live.

<link rel="stylesheet" href="/xubz/tokens.css">
<script type="module" src="/xubz/elements.js"></script>

<xb-tag variant="accent">In tolerance</xb-tag>

Frameworks

React

React 19 treats unknown lowercase-with-dash tags as custom elements and passes properties through directly. Earlier versions still work via standard DOM attributes/events.

import '@xubz/elements';

export function GaugePanel({ onSave }) {
  return (
    <xb-button variant="primary" onClick={onSave}>
      Calibrate device
    </xb-button>
  );
}

TypeScript

Ship a jsx.d.ts declaring JSX.IntrinsicElements['xb-button'] so attributes autocomplete and typecheck.

Frameworks

Vue

Tell the compiler once that xb-* tags aren't Vue components, then use them like any element.

vite.config.js

vue({
  template: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('xb-')
    }
  }
})

Component.vue

<script setup>
import '@xubz/elements';
function save() { /* ... */ }
</script>

<template>
  <xb-button variant="primary" @click="save">Calibrate device</xb-button>
</template>

Frameworks

Svelte

Svelte passes unknown elements straight through to the DOM — no configuration needed.

<script>
  import '@xubz/elements';
</script>

<xb-switch checked on:change={(e) => console.log(e.target.checked)} />

Server & backend

PHP — Laravel & Symfony

Blade and Twig only emit HTML strings — a custom element tag needs nothing special from the templating layer.

Laravel — resources/views/gauge.blade.php

@vite(['resources/css/xubz-tokens.css', 'resources/js/xubz-elements.js'])

<xb-tag variant="{{ $gauge->inTolerance ? 'accent' : 'danger' }}">
  {{ $gauge->status }}
</xb-tag>

Symfony — templates/gauge.html.twig

<link rel="stylesheet" href="{{ asset('build/xubz-tokens.css') }}">
<script type="module" src="{{ asset('build/xubz-elements.js') }}"></script>

<xb-switch {{ gauge.autoZero ? 'checked' : '' }}></xb-switch>

Livewire

Bind state with wire:model on the element's reflected attribute the same way you would a native input — the component doesn't know the difference.

Server & backend

Java — Spring & Thymeleaf

Any Java stack rendering server-side HTML — Spring MVC, JSF, plain JSP — includes the two static assets and writes the tag like any other element.

src/main/resources/templates/gauge.html

<script type="module" th:src="@{/js/xubz-elements.js}"></script>
<link rel="stylesheet" th:href="@{/css/xubz-tokens.css}">

<xb-button variant="primary" th:attr="data-id=${gauge.id}">
  Recalibrate
</xb-button>

This is also the path for Vaadin apps that render a client-side view — the elements register once in the page and are addressable from server-push updates like any other DOM node.

Rust

Dioxus & Leptos

Both compile to WebAssembly and render real DOM nodes, so a custom element tag is just a tag — this is the most underserved corner of the Rust ecosystem for a polished UI kit today.

Dioxus — rsx!

rsx! {
    script { src: "/xubz-elements.js", r#type: "module" }
    xb-button {
        variant: "primary",
        onclick: move |_| save(),
        "Calibrate device"
    }
}

Leptos — view!

view! {
    <xb-button variant="primary" on:click=save>"Calibrate device"</xb-button>
}

Rust

Tauri

A Tauri app's window is a webview — ship the same tokens.css and elements.js in your frontend's dist folder and it renders identically to a browser tab, with full access to native APIs from the same JS context.

Reference

Framework coverage

Ecosystem	Path	Works today
React / Vue / Svelte / Angular	Native custom element support	Direct
PHP — Laravel, Symfony	Server renders the tag as HTML	Direct
Java — Spring, JSF, Vaadin	Server renders the tag as HTML	Direct
Rust — Dioxus, Leptos	Compile to wasm, render real DOM	Direct
Rust — Tauri	Webview around the same web bundle	Direct
JavaFX / Swing (WebView)	Embed the bundle in a WebView node	Direct
JavaFX / Swing (native nodes)	Would need a JavaFX-CSS port	Not yet
Rust — egui, iced, Slint	Immediate-mode / native rendering, no DOM	Not yet

Reference

Theming

Every visual value — color, radius, spacing, motion — is a CSS custom property on :root, all prefixed --xb-* to avoid colliding with your own app's variables. Override them after importing tokens.css to re-theme the entire library, no rebuild required.

:root {
  --xb-ground: #EAEBE4;
  --xb-accent: #2E6E60;
  --xb-r-control: 7px;
  --xb-dur-3: 320ms;
}

The theme editor generates exactly this block: pick colors and shape on a live preview built from the real components, then paste its Copy CSS output straight after your tokens import.

Reference

Native desktop / roadmap

Out of scope for this release

JavaFX/Swing without a WebView, and native-render Rust GUI (egui, iced, Slint), draw their own pixels and can't load HTML or CSS. Reaching them means a second, independent implementation that shares only the token values from this spec — a separate project, not a wrapper, and not something to fake as "supported."