Architecture

#Workspace

guise/
├── Cargo.toml            # workspace manifest (plain crates.io gpui)
├── docs/                 # human docs (this directory)
├── site/                 # docs-website generator (Bun; one page per docs/*.md, via render/nav.ts)
├── scripts/              # the icon-font generator
└── crates/
    ├── guise/            # the library — published as `guise-ui`, lib name `guise`
    └── gallery/          # a live showcase (cargo run -p gallery)

Only crates/guise is published; the gallery is publish = false and is in the workspace so CI builds it against every change.

Tailor, the visual interface builder that draws with these components, used to live here too. It is its own project now, and depends on guise-ui from crates.io like any other consumer — which is what keeps the library honest about what it actually exposes.

The version lives once, in [workspace.package]. Cargo.lock is committed and CI builds --locked, so bumping the version means regenerating the lockfile in the same commit.

#The gpui dependency

Everything builds against crates.io gpui = "0.2.2" — no git pins and no [patch.crates-io] section, so guise-ui installs as a plain registry dependency and publishes cleanly. The few style/scroll APIs the crates.io snapshot lacks are shimmed in style.rs (FlexExt) via gpui's raw StyleRefinement. (thirdparty/block/ is a leftover vendored crate; no manifest references it.)

The library package is guise-ui — the guise name was taken on crates.io — with [lib] name = "guise". Cargo commands address the package as -p guise-ui, while code imports stay use guise::....

#Library module map (crates/guise/src)

#Conventions

• One component per file, lowercase names, no -/_/spaces; group with directories (input/select.rs), not concatenated names.
• Read everything from the theme via guise::theme::theme(cx) — never hardcode a color or size. This is what makes light/dark switching free.
• Builder methods take mut self and return Self (chainable).
• Container components implement ParentElement (just extend); .child / .children come for free.
• Resolve all theme values into locals before any cx.listener(...) or content-builder call — theme(cx) borrows cx immutably and those need it mutably, so a late theme(cx) read overlaps the borrow and won't compile.
• Closures stored on elements (.hover, .on_click) must be 'static — capture resolved Hsla/f32 values, not the &Theme borrow.

#Adding a component

1. Create a file under the right module (or the crate root for a loose one).
2. Define a #[derive(IntoElement)] builder + impl RenderOnce, or a Render + EventEmitter entity if it owns state. Resolve visuals from theme(cx).
3. End render with .probe("Name") — or .probe_any when the root is already a composed component rather than a styled element — plus an .attr(..) per meaningful Copy prop. Without it the component is invisible in the DevTools Elements tree.
4. Re-export it from the module's mod.rs, then from lib.rs, then add it to the prelude.
5. Add a showcase to crates/gallery/.
6. Write the component's docs section on the right docs/ page — and if that page is new, register it in site/render/nav.ts so the website picks it up.
7. For pure logic (parsing, range math, an editing model), add #[cfg(test)] tests next to the code. For wiring that needs a live app — signals, bindings, entity events, the theme global — use the gpui test harness in src/apptests.rs.
8. If Tailor should be able to place it, catalogue it there. Its coverage test reads a record of what this library ships and fails on a component that is neither catalogued nor excluded with a reason, so the gap shows up as a failing build on its side rather than as silent drift.

See the component model for the two patterns in detail.

#Commands

cargo run -p gallery        # launch the showcase
cargo check -p guise-ui     # fast type-check (package is guise-ui; lib name is guise)
cargo test -p guise-ui      # the library's tests: inline #[cfg(test)] + src/apptests.rs
cargo build --workspace --locked   # what CI builds
cd site && bun run build.ts        # docs/ -> site/dist