Documentation

Kwapso UI

A web-first, cross-platform component & collection library you build entire apps on top of. This whole page is built from the library itself.

Dashboard Gallery
For everyone

What is this?

Kwapso UI is a box of ready-made building blocks for apps — like LEGO for software. There are primitives (the small pieces: buttons, inputs, dialogs) and collections (data views: lists, tables, boards, calendars, charts). You snap them together to build a real app, on the web today and on desktop & mobile later — without rebuilding anything.

Everything you see — the headings, cards, tabs, badges, and the searchable catalog below — is the library showing itself off.

The big ideas

Four rules keep it lean

For developers

Get started

Install straight from GitHub (no npm account needed) along with its peer dependencies. Not on main yet — this points at the review branch, since a bare github:Kwapso/kwapso_ui (no branch) resolves to an empty main and installs nothing:

npm install github:Kwapso/kwapso_ui#swift-struck-ui-reskin react react-dom

The package ships TypeScript source, so your bundler tree-shakes it and Tailwind can see the class names. To pull later updates, re-run that same install — it re-fetches the latest from GitHub.

The catalog

Every component, searchable

InputInputs
A text field — text, email, phone, or number.
TextareaInputs
A multi-line text box.
ChoiceInputs
Pick one or many — as a searchable dropdown, chips, or pills. Clearable shows a ✕ to drop the whole selection; creatable lets a user type a value that isn't in the list and use it.
CheckboxInputs
A single on/off tick box.
SwitchInputs
A toggle switch (on/off).
Radio GroupInputs
Pick exactly one from a small set.
SliderInputs
Drag to choose a number — one thumb per value, so it covers a single value or a two-thumb range.
Date PickerInputs
Pick a date from a calendar.
File UploadInputs
Choose images or files to upload.
RatingInputs
A row of stars to give or show a score.
SignatureInputs
Draw a signature with a finger, mouse, or stylus.
NotesInputs
A lightweight rich-text editor (bold, lists, highlight…).
Page 1 of 8
Per page:See them live in the gallery
Under the hood

The configuration model

BaseConfig
On every component: visible + visibility rules (show/hide by data conditions).
FieldConfig
Inputs: label, help text, required, and validation (min/max, length, pattern).
CollectionConfig
Data views: title, filter, sort, search, pagination, total limit.
ActionConfig
Actions: what a tap does (default: open the detail screen) + show-disabled.

That's the shape every component shares. For the exhaustive, field-by-field reference — every component, every option, and what each value does — see CONFIG-REFERENCE.md on GitHub.

How it's organised

Two parts, one repo

repo root the library
registry/ + lib/ at the repo root are @kwapso/ui — exactly what a GitHub install delivers. Layered tokens → primitives → collections, one folder per component.
www/ the showcase
This site — dashboard, gallery, and these docs. A real app that consumes the library, deployed to Cloudflare Pages.

A fix in the library reaches every app that depends on it — instantly in this repo, and on the next GitHub install for anyone consuming it. Pinning to a commit or tag is the safety hatch.

Confidence

Quality & guardrails

Enforced layering
A build-time referee fails the build if a layer reaches the wrong way — the architecture can't rot.
Typed & required
Strict TypeScript; every config field is required, so no setting is ever hidden.
Tested in CI
100+ tests cover the rule engine, the collection pipeline, component rendering, interactions, and security regressions — on every push.
Token-pure
No hardcoded colors or sizes — only theme tokens, so re-skinning is one edit.
Lean by mandate
Variants over new files; ~3% duplication; reuse before adding.
Accessible base
Built on Radix primitives for keyboard and screen-reader support.
Hardened
Links are scheme-guarded and rich-text is sanitized — untrusted content can't smuggle in scripts (no raw HTML injection).
Shipping

Live & staging

Staging test here first
staging.kwapso-ui.pages.dev — where a change lands before it's public. Click around and confirm it's right.
Live the public site
kwapso-ui.pages.dev — promoted from the verified staging build. What everyone sees.

Apps pull library updates the same controlled way: re-run the GitHub install to fetch the latest, or pin to a specific commit or tag so a change only reaches you when you choose — a breaking change never surprise-breaks a running app.

Reach

One build, every device

Web today · desktop & mobile next

The same web build is wrapped natively with Tauri (desktop) and Capacitor (mobile). No rewrite.