Installation

Add lotusui to a Go module and check the Gio prerequisites.

lotusui is a single Go package on top of Gio: a semantic token palette, an embedded font, and the card/hairline/badge primitives that make an app read as one product. Every demo on this site is the real component, compiled to WebAssembly.

Install

lotusui is a normal Go module. Gio 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

Gio moves 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 Gio. Treat Gio bumps as deliberate changes, verified in lotusui and its consumers together.