Registry

Own the code when you need to: vendor any component, keep updating it with real merges.

The default way to use lotusui is the module import — idiomatic Go, updated by go get. The registry is for the moment a component must diverge: lotusui add copies a component's source into your app, where it is yours to edit — and unlike a snapshot, it stays updatable. Every capability here is BUILD-time: registry.json is generated from the source, consumed by the CLI and by AI agents, and never read by app code at runtime.

Add a component

The copy still imports the lotusui core (theme, scales, icons): exported identifiers are qualified automatically by an AST pass, and unexported helpers are gathered once into a CLI-owned companion file. A vendored Button keeps taking *lotusui.Theme and drops into existing call sites. Components vendored side by side form a coherent SET — they reference each other's local copies, never a mix of local and qualified.

go run github.com/ikaito-com/lotusui/cmd/lotusui add button
go run github.com/ikaito-com/lotusui/cmd/lotusui add dialog -dir internal/ui

Update — a real three-way merge

Every vendored file carries a stamp: component, version, and the hash of its pristine form. On update, files you never touched are replaced cleanly. Files you customized go through diff3 — the merge base is reconstructed EXACTLY, because the vendoring transform is a pure function of (version, component set) and the Go module cache stores every version's pristine source. Your edits, and only your edits, surface as diffs; conflicts are standard markers, printed alongside the migration changelog sections between the two versions.

go run github.com/ikaito-com/lotusui/cmd/lotusui update            # everything under ./ui
go run github.com/ikaito-com/lotusui/cmd/lotusui update button -dry  # preview one component

Blocks

Blocks are ready-made compositions built only on the exported API — vendor them as starting points and shape them to your app.

go run github.com/ikaito-com/lotusui/cmd/lotusui add login-form

Skills — teach your agent lotusui

lotusui ships agent skills in the module itself: the registry catalog, the theming system, the add/update workflow and the changelog contract, as files the agent's harness discovers. Install them into the app and re-run after upgrades so the skill always matches the version you build against.

go run github.com/ikaito-com/lotusui/cmd/lotusui skills   # → .claude/skills/lotusui/

registry.json — the machine-readable catalog

Generated at build time from the source (lotusui registry, guarded by lotusui verify -registry): every component and block with its files, computed dependencies, carried helpers and pristine hash. Agents read it to know what exists and what vendoring involves — app code never does.

{
  "name": "lotusui",
  "components": [
    {"name": "button", "files": ["button.go"], "hash": "…"},
    {"name": "card", "files": ["card.go"], "carried": ["cardShadow"], "hash": "…"}
  ]
}