Installation

Add lotusui to a Go module and start a native desktop or mobile app.

lotusui is a themeable Go UI library for native desktop and mobile apps — a semantic token palette, an embedded font, and the components that make an app read as one product. Built on Gio. Every demo on this site is the real component running in your browser.

Install

lotusui is a normal Go module. The runtime stack brings its own platform requirements (see the Gio install docs); on macOS, Windows and js/wasm it works out of the box, Linux needs a few dev packages. When a component must diverge from stock, you can also own its source — lotusui add vendors it into your app and keeps it mergeable (see Registry).

go get github.com/ikaito-com/lotusui

Scaffold an app

The lotusui CLI is the library's build-time companion: it scaffolds, fetches icons, and generates themes — always via go run, so it needs no install and its version is locked to the lotusui in your go.mod. init writes a minimal themed app with the go:generate workflow already wired.

go mod init myapp
go get github.com/ikaito-com/lotusui
go run github.com/ikaito-com/lotusui/cmd/lotusui init
go mod tidy && go run .

Keep generated code honest

Everything the CLI generates (icon constants, themes) is guarded by two standard mechanisms, so "someone forgot to regenerate" can't ship. First, typed constants make most drift a compile error: an unfetched icon has no constant to call. Second, lotusui verify is an offline, sub-second check — manifest ↔ SVGs ↔ constants, and a hash stamp proving your generated theme matches its theme.json — safe in every make check and in CI, no network. The scaffolded AGENTS.md teaches AI coding agents the same rules, so assistants working in your repo regenerate instead of hand-editing.

# Makefile
generate:   ## all build-time codegen
	go generate ./...

verify:     ## offline drift check — wire into make check and CI
	go run github.com/ikaito-com/lotusui/cmd/lotusui verify \
	    -manifest icons/manifest.txt -out icons -gen icons_gen.go \
	    -theme-config theme.json -theme-gen theme_gen.go

Versioning and upgrades

lotusui follows SemVer through Go modules: it lives at v0.x while the component catalog is still filling out — breaking changes may land in minor versions — and becomes v1.0.0 when the parity ledger is clean, after which breaking changes mean a /v2 module path. Every API change is recorded in CHANGELOG.md with exact symbols and old→new forms — written specifically so an AI agent (or you) can migrate a consuming app from the changelog alone. An exported-API baseline (api.txt) is checked in CI, so no API change can ship undocumented.

go get github.com/ikaito-com/lotusui@latest
# read CHANGELOG.md for the versions you crossed, apply it, then:
go build ./...   # the compiler catches anything missed

Runtime versions move deliberately

Go's minimal version selection takes the maximum gioui.org requirement across lotusui and your app, so a casual go mod tidy can silently upgrade the UI runtime. Treat those bumps as deliberate changes, verified in lotusui and its consumers together.