zgui
Architecture

The crate map

Every crate in the workspace with its layer and publication status, the external dependencies, the ledger checks that keep the graph layered, feature flags, and how a release is made.

The workspace has 64 crates under crates/, plus the xtask gate runner. 53 of them are published to crates.io at version 0.1.0; the other 11 are tooling or the experimental Linux console stack. An application depends on zgui and usually nothing else (see What an application depends on).

Layers

Every crate belongs to one of nine layers, from L0 (foundation) to L8 (product). The architecture overview describes what each layer holds. A crate may depend on crates in its own layer or a lower one, never on a crate in a higher layer.

Each manifest declares its layer in a comment above [dependencies]:

crates/zgui-layout/Cargo.toml
[package]
name = "zgui-layout"
version.workspace = true
edition.workspace = true
# ... the other shared package keys

# L4 — engines. Every dependency is inherited: `foo.workspace = true`.
[dependencies]
zgui-css = { path = "../zgui-css", version = "0.1.0" }
cephal.workspace = true

cargo xtask new-crate <name> --layer L4 writes such a manifest and a crate root with #![deny(missing_docs)] and #![forbid(unsafe_code)]. It accepts L0 to L8 only.

The rule keeps each part replaceable and testable on its own:

  • A backend upgrade reaches one crate. A breaking winit release touches zgui-platform-winit and nothing else.
  • Every stage is testable without the one below it. The style engine runs without layout, layout runs with fixed-metrics text and no fonts, paint runs without a GPU, and the frame loop runs without a display server.
  • A second implementation is not a fork. There are four platform backends, two vector rasterisers, two text metric sources, and a capture renderer beside the real one.

When a dependency would point upward

A stage that needs a fact from a higher stage must be handed it. Use one of three moves:

  1. Invert the dependency. The lower crate declares a trait; the higher crate implements it and passes it in.
  2. Push the type down. zgui-vocab exists for this.
  3. Add a facade. zgui-css is the facade for the style engine.

A feature flag that enables an upward edge does not help: the layers check reads normal and build dependencies, optional or not.

All crates

"Published" means the crate is on crates.io. Unpublished crates have publish = false in their manifest.

CrateLayerPublishedPurpose
zgui-geomL0yesCoordinate spaces and units (CssPx, DevicePx, Au) and plain geometry types.
zgui-colorL0yesCSS colour: fourteen colour spaces, conversion, and interpolation.
zgui-arenaL0yesArena storage with stable addresses and typed handles.
zgui-internedL0yesInterned strings, compared by pointer.
zgui-bitsL0yesInvalidation primitives: dirty flags and damage sets.
zgui-profileL0yesFrame stages as tracing spans, work counters, and the latency trace.
zgui-vocabL1yesTypes shared by the view layer and the document: events, keys, modifiers, roles, states.
zgui-cssL1yesThe computed-style facade. The one place the style engine's types are named for other crates.
zgui-sceneL1yesThe renderer-independent display list. See Paint and the scene.
zgui-renderL1yesThe Renderer and VectorRaster contracts. No implementation. See The renderer.
zgui-atlasL1yesTexture-atlas placement, eviction, reference counts, and the upload queue. No GPU.
zgui-platformL1yesThe contract a windowing backend implements. See The platform layer.
zgui-reactiveL1yesSignals, memos, stores, owners, and the UI-thread executor.
zgui-imageL1yesRaster image decoding, decode limits, and registered in-memory image bytes.
zgui-wgslL1yesShared WGSL building blocks and the rules that assemble built-in and application shader modules.
zgui-render-wgpuL2yesThe wgpu renderer: device, pipelines, batching, and the persistent target a frame is composed into.
zgui-render-vector-velloL2yesVector rasterisation on compute shaders, built on Vello.
zgui-render-vector-coverageL2yesVector rasterisation for devices without compute shaders.
zgui-platform-waylandL2yesThe native Wayland backend. Compiles to an empty crate off Linux and the BSDs.
zgui-platform-winitL2yesThe portable backend for X11, Windows, macOS, and Wayland on request.
zgui-platform-headlessL2yesA platform with no window system: a virtual clock, scripted input, recording surfaces.
zgui-tokioL2yesOptional Tokio backend for background work and UI tasks.
zgui-drmL2noLinux DRM/KMS: modes, planes, framebuffers, page flips. Console stack.
zgui-evdevL2noLinux evdev input devices and events. Console stack.
zgui-libinputL2noInput device configuration through libinput, loaded at run time. Console stack.
zgui-xkbL2noKeyboard layouts through libxkbcommon, loaded at run time. Needs nightly. Console stack.
zgui-seatL2noSession and device access through libseat, loaded at run time. Console stack.
zgui-platform-drmL2noThe platform backend for a bare Linux console. Console stack.
zgui-domL3yesThe document: one arena of nodes, safe to read from many threads during the cascade.
zgui-styleL4yesThe style engine, built on Stylo.
zgui-layoutL4yesThe box tree and layout (block, flex, grid, inline), built on Cephal.
zgui-textL4yesText contracts, with no font engine behind them.
zgui-text-styleL4yesText properties lowered from the cascade, split into shaping and non-shaping halves.
zgui-text-parleyL4yesThe text engine: shaping, font resolution, metrics, glyph rasterisation, bidi. Built on Parley.
zgui-paintL4yesComputed style and fragments into scene primitives.
zgui-svgL4yesSVG documents read into outlines, paints and clips.
zgui-canvasL4yesRetained shape lists that applications draw into.
zgui-inputL5yesHit testing, interaction state, focus, and event dispatch.
zgui-scrollL5yesScroll offsets, chaining, overscroll and momentum.
zgui-a11yL5yesThe accessibility tree, published through AccessKit, and incoming actions.
zgui-animL5yesTransitions and keyframe animations.
zgui-editL5yesText editing: caret, selection, undo, IME composition, platform text keys.
zgui-viewL6yesThe view layer: views, components, children, and the seams they are written against.
zgui-view-domL6yesThe view layer over a real document.
zgui-view-macroL6yesview!, #[component], #[slot], variants!, css! and style!.
zgui-shader-macroL6yesThe shader! macro. Validates and compiles application WGSL at build time.
zgui-elementsL6yesThe element vocabulary: sixteen names, each a typed builder.
zgui-customL6yesThe custom-element trait and the registry that connects it to layout and paint.
zgui-runtimeL7yesThe frame pipeline: dispatch, restyle, layout, paint, draw, and the window set.
zguiL7yesThe umbrella crate an application depends on.
zgui-shaderL7yesApplication shader declarations, typed parameters, and paint integration.
zgui-wgpuL7yesSurface elements that show textures from another wgpu renderer.
zgui-testkit-viewL7yesComponent tests: a recording tree, a scripted host, synthesised input, a virtual clock.
zgui-testkit-sceneL7yesFrame tests without a GPU or font files: a capture renderer, fixed-metrics text, counters.
zgui-conformanceL7noThe CSS property coverage report, backed by tests.
zgui-uiL8yesThe component library.
zgui-ui-primitivesL8yesHeadless interaction behaviours the components are built from.
zgui-ui-tokensL8yesDesign tokens and themes as CSS custom properties.
zgui-ui-iconsL8yesA vector icon set drawn by the vector element.
zgui-devtoolsL8yesThe inspector: document, styles, layout, and frame statistics.
zgui-benchL8noBenchmarks and reference workloads.
zgui-examplesL8noThe example applications in examples/.
zgui-consoleL8noRunDrm::run_drm, the entry point that runs an App on a Linux console. Console stack.
probenonenoBuild canary: links every pinned external engine together.
xtasknonenoThe build, test, gate and release runner. Lives beside crates/.

The console stack is experimental. It stays in the repository, is not published, and is not reachable through zgui. Its entry point lives in zgui-console, which an application names beside zgui. See the platform layer.

What an application depends on

An application names zgui. The examples package shows this: every example depends on zgui only. There are three exceptions:

CrateWhen an application names it
zgui-imageTo register encoded image bytes from memory (ImageBytes). File paths need only zgui.
zgui-devtoolsTo mount the inspector. zgui does not re-export it, so a release build does not link it by accident.
zgui-consoleTo run on a Linux console with run_drm. Not published.

Test crates name zgui-testkit-view, zgui-testkit-scene or zgui-platform-headless in [dev-dependencies]. None of them is re-exported by zgui.

The component library follows the same rule: zgui-ui-tokens, zgui-ui-icons and zgui-ui-primitives depend on zgui only, and zgui-ui depends on those three and zgui.

crates/zgui/src/lib.rs re-exports the lower crates under short names:

crates/zgui/src/lib.rs
pub use crate::app::{App, app};
pub use crate::error::Error;

pub use zgui_view_macro::{component, css, slot, style, variants, view};
pub use zgui_elements::expansion;

pub use zgui_atlas as atlas;
pub use zgui_bits as bits;
pub use zgui_canvas as canvas;
pub use zgui_custom as custom;
pub use zgui_elements as elements;
pub mod desktop {
    pub use zgui_platform::{AppMenu, MenuAction, MenuEntry, MenuId, MenuRole, Shortcut, Submenu};
    pub use zgui_runtime::desktop::{AppHookGuard, on_exit, on_menu, on_reopen};
}
pub use zgui_geom as geom;
pub use zgui_platform as platform;
pub use zgui_reactive as reactive;
pub use zgui_reactive::task;
pub use zgui_render as render;
pub use zgui_runtime as runtime;
pub use zgui_scene as scene;
pub use zgui_shader as shader;
pub use zgui_text as text;
#[cfg(feature = "tokio")]
pub use zgui_tokio as tokio;
pub use zgui_view as view;
pub use zgui_vocab as vocab;
pub use zgui_wgpu as surface;

zgui::expansion

view! expands to calls into zgui-view and zgui-elements. A macro cannot know what the caller named those crates, so the expansion always goes through ::zgui::expansion::view::… and ::zgui::expansion::elements::…. That lets a crate that writes views depend on zgui alone.

A crate that writes views without zgui supplies the root itself:

extern crate zgui_elements as zgui;

Replacing a backend

ReplaceDepend onImplementInstall with
The rendererzgui-renderRendererApp::with_renderer, which takes a zgui_runtime::RendererFactory
The vector rasteriserzgui-render, zgui-render-wgpuVectorRaster, zgui_render_wgpu::VectorSourceWgpuRenderer::set_vector_factory_for, usually through zgui_render_vector_vello::attach
The platformzgui-platformPlatformCx, Surface, Clock, Waker, ClipboardA driver FnOnce(Box<dyn AppHandler>) -> Result<(), PlatformError> passed to App::run_on
The text enginezgui-textFontSource, FontMetricsSource, ParagraphShaper, GlyphRasterzgui_runtime::App::with_text_engine, with_metrics, with_glyph_raster
  • Renderer. A renderer with no vector rasteriser attached draws general vector items as empty space, with no error. See Vello and coverage rasterisers and, for a host that already owns a wgpu device, Adopting a host-opened device.
  • Platform. A platform backend does not implement AppHandler; it calls one. zgui_runtime::Runtime is the implementation. See Drivers and backend selection.
  • Text engine. The umbrella App does not expose the three text factories. It installs them from zgui::app::Fonts, so a face registered once serves every window. To replace the text engine, build with zgui_runtime::App directly. See The text engine.

Feature flags

All feature flags are off by default.

CrateFeatureEffect
zguitokioRuns background work and UI tasks on a Tokio runtime (zgui::tokio).
zguiinstrumentForwards to zgui-view/instrument.
zgui-viewinstrumentRecords which component produced each part of the document. zgui-devtools turns it on.
zgui-viewstub-backendzgui_view::stub: an in-memory tree and host for the crate's own tests and doc tests.
zgui-profilecountersKeeps frame counters in release builds. They are always on with debug assertions. zgui-testkit-scene enables it as a normal dependency feature.
zgui-bitsloomBuilds the atomics from loom for model checking. Panics outside loom::model.
zgui, zgui-layout, zgui-platform-waylandwall-clockCompiles the wall-clock budget test target, which the gate runs in release mode.
zgui-examplesdrmBuilds the tty example against zgui-console.

External dependencies

Every external dependency is declared once in [workspace.dependencies] and inherited with foo.workspace = true, so each version, feature set and default-features choice exists in one place. cargo xtask ledger versions reports any member that spells its own version.

The table lists the crates that name each dependency outside development dependencies.

DependencyVersionNamed byPurpose
stylo, stylo_dom, stylo_atoms, stylo_static_prefs, selectors, servo_arc, web_atoms, cssparser, app_units, euclidstylo =0.19.0zgui-css, zgui-dom, zgui-style (each a subset)The style engine: parsing, selector matching, the cascade. app_units and euclid appear in trait signatures the document implements.
cephal0.1.0 (crates.io)zgui-layoutRetained, incremental block, flex and grid layout.
parley, fontique0.11 (resolves to 0.11.1)zgui-text-parleyParagraph shaping and font resolution. fontique is patched from vendor/fontique inside the workspace.
skrifa, swash0.44.0, 0.2.10zgui-text-parleyFont metrics and glyph rasterisation.
zeno0.3.3zgui-paintSmall vector coverage masks.
wgpu29.0.4zgui-render-wgpu, both vector rasterisersThe graphics API.
naga, bincode29.0.4, 1.3zgui-render-wgpu, zgui-shader-macroParse and validate WGSL at build time, serialise the result, load it in the renderer.
vello0.9.0zgui-render-vector-velloCompute-shader path rasterisation.
usvg0.46.0zgui-svgParses SVG into paths, paints and clips. Text support is disabled.
image0.25zgui-imagePNG, JPEG, WebP, and the first frame of GIF.
winit, accesskit_winit, arboard0.30.13, 0.33.2, 3.6zgui-platform-winitPortable event loop, windows, accessibility and clipboard.
smithay-clipboard0.7zgui-platform-winit (Linux, BSD)The Wayland clipboard on the portable backend.
muda, objc2, block2, objc2-foundation, objc2-app-kit0.21.0, 0.6.x, 0.3.2zgui-platform-winit (macOS)The application menu, reopen requests, title-bar buttons, key and scroll monitors.
smithay-client-toolkit, wayland-client, wayland-backend, wayland-protocols, calloop, calloop-wayland-source0.20.0, 0.31.15, 0.3.16, 0.32.13, 0.14.4, 0.4.1zgui-platform-waylandThe native compositor connection, protocols, and event loop.
accesskit_unix, zbus0.22.1, 5.18zgui-platform-waylandNative Wayland accessibility and the settings portal.
accesskit0.24.1zgui-vocab, zgui-platform, zgui-a11y, zgui-text, the four platform backendsThe accessibility tree as plain data.
raw-window-handle0.6.2zgui-platform and the Wayland, winit and DRM backendsWindow handles for the graphics API, confined to the GpuSurface sub-trait.
reactive_graph, reactive_stores, any_spawner, send_wrapper=0.2.14, =0.4.3, =0.3.0, 0.6zgui-reactiveThe reactive engine and the executor slot.
futures (thread-pool)0.3zgui-reactive, zgui-render-wgpuThe default background pool.
tokio1zgui-tokioThe optional runtime.
kurbo, peniko0.13.1, 0.6.1zgui-scene, zgui-svg, zgui-canvas, both vector rasterisers; kurbo also zgui-elements, zgui-text, zgui-text-parleyCurves and paint descriptions as plain data.
etagere0.3zgui-atlasShelf allocation inside an atlas.
bytemuck1.25zgui-geom, zgui-scene, zgui-render-wgpu, zgui-render-vector-coveragePlain-data structs as GPU buffer bytes.
syn, quote, proc-macro22.0, 1.0, 1.0zgui-view-macro, zgui-shader-macroThe procedural macros.
rayon1.12zgui-style, zgui-layoutParallel selector matching and layout batches.
ash0.38zgui-platform-drmVulkan images a display can scan out. Console stack.
rustix1.1zgui-drm, zgui-evdev, zgui-platform-drm, zgui-platform-waylandKernel calls without libc; the monotonic clock.
bindgen0.72zgui-drm, zgui-evdev (build)Kernel uapi bindings generated from vendored headers.
libloading0.8zgui-xkb, zgui-seat, zgui-libinputLoad libxkbcommon, libseat and libinput at run time.
thiserror, tracing, bitflags, rustc-hash, smallvec, tomlmanyUtilities. Not ledgered, because none is an engine.
proptest, criterion, trybuild, loom, tracing-subscriber, accesskit_consumer, wayland-protocols-wlrtests and toolsProperty tests, benchmarks, compile-fail tests, the concurrency model checker, test logging, reading published accessibility trees, virtual Wayland input.

Pins that fail silently

cargo xtask ledger versions (xtask/src/ledger/check/versions.rs) enforces these, because a wrong value produces wrong behaviour rather than a build error:

PinReason
stylo, reactive_graph, reactive_stores, any_spawner pinned to an exact patch releaseA drift to another release would otherwise go unnoticed. Moving a pin is a deliberate change.
reactive_graph enables effectsWithout it, the interface compiles and runs but never updates.
reactive_graph does not enable nightlyThe workspace's nightly toolchain must not switch it on.
cephal has default-features = false and exactly block, flex, gridparallel would add a second worker pool; zgui drives its own pool through Cephal's batching seam. Each algorithm is a formatting context the box tree dispatches to.
wgpu is 29.x, one copy in Cargo.lockVello 0.9 links wgpu 29.0.4 and shares one device, queue and target texture with the renderer.
ash has one copy in Cargo.lockThe console backend passes vk::Image to wgpu-hal; two copies would be two unrelated types.
linebender_resource_handle has one copyIt makes the text engine's and the rasteriser's font-data types the same type.
skrifa has at most two copiesThe text engine and Vello are on different releases.

Ledger checks

cargo xtask ledger runs thirteen checks. Any violation fails the gate. cargo xtask ledger <name> runs one check, and cargo xtask ledger --self-test runs every check against a fixture with a planted violation, to prove that the check can fail.

CheckWhat it asserts
enginesEach external engine is named only by the crates permitted to name it.
unsafeunsafe is forbidden outside an allowlist, and every unsafe impl Send/Sync has a // SAFETY: comment.
attributionAdapted code carries its licence header and a matching NOTICE row.
versionsExact version pins, one copy of wgpu, and feature sets that fail silently.
pinnedTwo crates have exact dependency lists, and no crate below the view layer names zgui-view.
layersEvery dependency points at the crate's own layer or a lower one.
ignoredNo test is #[ignore]d.
countersEvery frame counter is incremented somewhere, or listed as waiting for its stage.
skipsEvery counter of avoided work names its pair and has a non-vacuity test.
clockEvery wall-clock assertion lives in a target the gate runs in release mode.
mutationA document is changed only through its batch API, never through the arena.
inertEvery enum variant that code branches on is constructed somewhere.
tag-syntaxNo view, in code or docs, uses the old tag syntax.

layers check

The check reads the # L<n> — header of every member manifest and compares each edge in [dependencies] and [build-dependencies]. A member without a header fails, so a new crate cannot skip the rule. probe and xtask are the only members with no layer.

Development dependencies are not checked. Several crates drive their own tests through a higher layer, for example taking zgui-testkit-scene (L7) for golden-image comparisons. Test binaries are not linked into a consumer's build, so these edges do not change the shipped graph.

pinned check

Two crates have exact dependency lists, because other backends are substituted underneath them:

CrateNormal dependencies, exactly
zgui-viewzgui-geom, zgui-interned, zgui-reactive, zgui-vocab
zgui-vocabaccesskit, zgui-geom, zgui-interned

Neither crate may see stylo, stylo_dom, selectors, cephal, parley, wgpu, vello, winit, zgui-dom, zgui-layout, zgui-style, zgui-render, zgui-scene or zgui-platform in any section, including development dependencies.

No crate below the view layer may depend on zgui-view. The check lists thirteen such crates by name: zgui-input, zgui-scroll, zgui-a11y, zgui-anim, zgui-edit, zgui-layout, zgui-style, zgui-dom, zgui-text, zgui-paint, zgui-scene, zgui-render and zgui-platform. Event dispatch is the usual temptation: the input layer decides which listeners an event reaches, and the view layer calls them.

engines check

xtask/src/ledger/check/engines.rs lists, for each external engine, the crates that may name it. Replacing or patching an engine is therefore a change to a known set of manifests. External dependencies shows which crates name each engine today. Any dependency whose name starts with gpui is rejected outright.

Lints and unsafe

[workspace.lints] denies missing_docs, unsafe_code and broken intra-doc links, and warns on unreachable_pub, private intra-doc links, all of clippy, and undocumented unsafe blocks. Every member sets [lints] workspace = true.

cargo xtask ledger unsafe requires #![forbid(unsafe_code)] in every crate root outside this allowlist:

CrateAllowed unsafe for
zgui-arenaChunk initialisation that hands out address-stable references.
zgui-domThe cell discipline and the mutation cell.
zgui-geomPlain-old-data impls for types sent to the GPU.
zgui-render-wgpuLoading a pipeline cache from a blob; creating a device through wgpu-hal with requested Vulkan extensions.
zgui-render-vector-velloCreating a pipeline cache from a blob.
zgui-platform-winitThe Wayland clipboard constructor; AppKit calls for the macOS menu, reopen request and title-bar buttons.
zgui-platform-waylandBorrowing the compositor's display and surface pointers as window handles.
zgui-drmioctls, mapping dumb buffers, owning dma-buf descriptors.
zgui-evdevioctls and reading event records from a byte buffer.
zgui-xkb, zgui-seat, zgui-libinputLoading the library at run time and calling into it.
zgui-platform-drmReporting a surface's DRM handles; the Vulkan calls that create scanout images.

Every hand-written unsafe impl Send or unsafe impl Sync needs a // SAFETY: comment directly above it.

Publishing and releases

The published crates are on crates.io at 0.1.0, tagged v0.1.0. An application adds them with cargo add zgui or:

Cargo.toml
[dependencies]
zgui = "0.1"

Toolchains

  • Published crates build on stable Rust 1.90 or later. rust-version = "1.90" is set in [workspace.package]. The CI job "Check stable 1.90" runs cargo +1.90.0 check over every published crate.
  • The repository is developed on a pinned nightly (rust-toolchain.toml, currently nightly-2026-04-16). Miri needs nightly, and so does zgui-xkb in the console stack. The console crates do not inherit rust-version.

Package contents

[workspace.package] include limits every package to src/, build/, build.rs, README.md, LICENSE and NOTICE. Tests, fixtures and test fonts are not shipped. Each published crate has its own README.

The repository patches fontique (the font collection under Parley) from vendor/fontique, so that a font query keeps resolved families between paragraphs. [patch.crates-io] applies only inside the workspace. A crates.io build uses the released fontique: the text is the same, but font resolution is slower. An application can opt into the patched copy:

[patch.crates-io]
fontique = { git = "https://github.com/zortax/zgui", tag = "v0.1.0" }

One version for all crates

Every member inherits version from [workspace.package], and all crates are released together. zgui 0.1.0 therefore always sits on zgui-render 0.1.0, and there is no compatibility matrix between the framework's own crates.

xtask/src/release/lockstep.rs checks that:

  • every member writes version.workspace = true;
  • every dependency of a published crate that has a path also has a version requirement, whether it is an internal crate or an external one, and whether it is written in the member or inherited from the workspace;
  • no published crate depends on an unpublished member, including optional and target-specific dependencies.

The release gate

cargo xtask release runs three steps:

  1. Lockstep, as above.
  2. Packaging. cargo package --workspace --locked, excluding unpublished members, then builds every published crate from its package. This catches files the package leaves out and builds that read outside their own directory.
  3. Compatibility. cargo semver-checks check-release against the newest v* tag that does not contain the checked commit. Before the first tag, it reports "no baseline" instead of passing.

cargo xtask ci runs the same gate but only packages the crates, without building them.

The release itself has two parts. The crates are published from a local checkout with cargo publish --workspace. Pushing a vX.Y.Z tag runs .github/workflows/release.yml, which checks that the tag is on main and matches the workspace version, runs the full CI workflow, and creates the GitHub release with generated notes.

API stability rules

  • #[non_exhaustive] marks enums that are expected to grow without a breaking change: error enums, frame outcomes, host-hook answers, and platform enums. (A unit test in zgui-platform rejects any public enum there without it.) Enums that list the framework's own content, such as PrimitiveKind, Batch and Filter in zgui-scene, are exhaustive on purpose: adding a member must update every match in the tree.
  • Traits grow with default methods. A method added later has a default body, so existing implementations keep compiling. Every method of zgui_runtime::HostBinding has one.
  • #[doc(hidden)] hides items that exist only so one crate can reach another, such as the typestate markers behind required-prop errors. The macro-expansion roots stay visible.

Next

On this page