gpui-kit-material

Material 3 / M3 Expressive tokens, motion and components for Longbridge GPUI Kit.

Components are thin Material adapters over Kit's gpui-component controls (gpui_kit::component): Kit owns behavior (input, focus, accessibility, overlays, windows), this crate owns Material visuals and motion. Icons come from gpui-material-symbols.

Status: pre-release (0.1). The APIs below work and are tested, but no component has passed visual/motion conformance review yet. Per-component status lives in conformance/md3.json; the plan is in docs/ROADMAP.md.

What's included

• Color & theme — semantic ColorRoles, all 20 md3.io reference themes (light/dark × standard/medium/high contrast, 52 roles each), 10 legacy palettes (Paper/Ink, Nord, Tokyo Night, Catppuccin), animated theme transitions and a 100–200% text scale. Dynamic seed/HCT schemes are pending.
• Tokens — shape, type scale (15 roles), layout metrics, elevation, state layers.
• Motion — Expressive (default) and Standard schemes, spatial/effects curves, entrances, retargetable values, per-transition reduced motion.
• Components — MaterialButton (5 variants × 5 sizes × round/square, toggle, loading, ripple, shape morph), ConnectedButtonGroup, dividers, linear/circular progress, switch, slider, search field, side sheet, snackbar, focus ring/reveal and a custom title bar with caption buttons. Tiles, choice tiles, status badges, chips, notices and cards come from course2md and do not yet follow M3 geometry.

Quick start

[dependencies]
gpui-kit = { git = "https://github.com/longbridge/gpui-kit", branch = "main" }
gpui-kit-material = { git = "https://github.com/mizorewww/gpui-kit-material" }

The workspace patches GPUI, GPUI Base and GPUI Fast (see [patch] in Cargo.toml and docs/ARCHITECTURE.md). Downstream workspaces need the same patches until they land upstream.

use gpui_kit_material::{icons::Assets, prelude::*, theme};

gpui_kit::application()
    .with_assets(Assets::new())
    .run(|cx| {
        gpui_kit::init(cx);
        gpui_kit_material::init(cx);
        // Project the initial scheme into Kit's theme before the first Root render.
        theme::init_component_theme(initial_scheme, 1.0, cx);
        // Open windows with gpui_kit::open_window; Kit supplies the Root.
    });

Paint with semantic roles, never stored colors:

div().bg(color(ColorRole::SURFACE_CONTAINER)).text_color(color(ColorRole::ON_SURFACE))

Switch theme from an input event (it animates on the slow effects spring; keep calling advance_component_theme from a next-frame callback while it returns true, never from render), or switch the motion scheme:

let ocean = ThemeId::Ocean.scheme(ThemeMode::Dark, Contrast::High);
let running = theme::advance_component_theme(ocean, 1.0, window, cx);
gpui_kit_material::motion::set_motion_scheme(gpui_kit_material::motion::MotionScheme::Standard);

A controlled toggle button (the caller owns selected; the button never stores it):

use gpui_kit_material::icons::IconName;

let view = cx.entity();
material_button("save", ButtonVariant::Tonal)
    .button_size(ButtonSize::Medium)
    .icon(IconName::Check)
    .toggle(true)
    .selected(self.saved)
    .on_change(move |selected, _click, _window, cx| {
        view.update(cx, |this, cx| { this.saved = selected; cx.notify(); });
    })
    .child(label)

Labels and accessible names always come from the caller. See the rustdoc (cargo doc --open -p gpui-kit-material) for the full contracts of each component.

Gallery

One gallery module runs on desktop and in the browser.

cargo run -p gpui-kit-material --example gallery          # desktop (GPUI Fast backend)
./scripts/build-gallery-web.sh --release                   # browser, then:
python3 -m http.server 8080 --bind 127.0.0.1 --directory crates/gallery-web/www

The title bar shows FPS of newly drawn frames; Settings → Vertical sync toggles Metal display sync on macOS. Headless capture, profiling and fixture tooling are described in docs/DEVELOPMENT.md.

Develop

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

CI runs these on macOS, Linux and Windows, plus both GPUI backends and the WASM gallery build. Project rules for contributors and agents — Kit reuse, conformance acceptance and the performance gates (every gallery CPU frame ≤ 2 ms, scrolling ≥ 500 FPS) — are in AGENTS.md.

License

MIT. Palette sources and licenses: crates/color/PALETTES.md. Material Symbols assets are Apache-2.0, retained in the pinned Symbols repository. Roboto and IBM Plex Sans gallery fonts are SIL OFL, bundled with their licenses.