AGENTS.md — Theming repo guide for AI agents

This is a Makepad 2.0 demo of runtime theme swapping. Read this before editing the codebase.

What this repo is

A small desktop app that shows how to push Rust-side state (theme + i18n) into a Makepad 2.0 ScriptVm and have the whole UI re-skin live. It is not a Makepad Studio plugin — it's a standalone Cargo binary that depends on makepad-widgets from git.

Key files

File	Role
`src/main.rs`	`App` struct, `MatchEvent`, `AppMain`, and the `script_mod!` UI
`src/theme.rs`	`ThemeState` enum, system detection, JSON persistence
`src/i18n.rs`	`LanguageState` enum + `apply_to_vm`
`src/streem_theme/mod.rs`	The four theme palettes + `s_themes` slot
`src/streem_theme/{colors,shapes,typography}.rs`	Token vocabularies registered on the VM
`src/streem_i18n/mod.rs`	EN + SW string tables + `s_i18n` slot
`splash/theme_gallery.splash`	Standalone Splash script using the same palette

The runtime swap pattern

The Rust side never touches widget properties directly. Instead:

ThemeState::apply_to_vm(vm) reassigns mod.streem_theme.s_themes via script_eval!.
App::reload_ui_from_rust_state re-runs script_mod and applies it with Apply::Reload, which re-evaluates every draw_bg.color: color_bg etc. in the tree.
self.ui.redraw(cx) triggers a repaint.

The same pattern is used for LanguageState → mod.streem_i18n.s_i18n.

Common edits

Add a new theme

Add a variant to ThemeState in src/theme.rs.
Add a palette to mod.streem_theme in src/streem_theme/mod.rs.
Add a themes.<name> alias in the same file.
Add a Self::Variant => script_eval!(...) arm in ThemeState::apply_to_vm.
Update ThemeState::toggled() to include the new variant in the cycle.
Update the tests in src/theme.rs.

Add a new i18n key

Add the key to both en and sw blocks in src/streem_i18n/mod.rs.
Use it in the UI via text: <key> (with use mod.streem_i18n.s_i18n.* at the top of the script_mod! block).
If the key name collides with a widget := name, rename the i18n key (prefix with btn_, section_, etc.).

Change a theme color

Edit the palette in src/streem_theme/mod.rs. If the same color appears in splash/theme_gallery.splash, update it there too.

Gotchas

script_mod! blocks in submodule files must be registered. The v0.1 bug was that colors.rs, shapes.rs, and typography.rs declared script_mod! blocks but were never called from AppMain::script_mod. v0.2 fixes this by giving each a pub fn script_mod(vm) that runs script_eval!, called from the top-level streem_theme::script_mod.
System must be resolved before apply_to_vm. The Splash side never sees a System value — only the resolved Light or Dark palette.
new_batch: true is required on any View with show_bg: true that contains text children. Without it, text renders behind the background.
Default text color is white. For light themes, set draw_text.color to a dark color on every text widget.
Hex colors containing e adjacent to digits need the #x prefix inside script_mod! to avoid parse errors. E.g. #x1E293B not #1E293B.

Running

just run          # or: cargo run
just test         # runs the ThemeState and LanguageState unit tests
just ci           # fmt-check + clippy + test (what CI runs)

The Makepad git dependency requires a recent Rust toolchain and, on Linux, the usual X11/ALSA/pkg-config dev packages (see README).

Splash reference

For the full Makepad 2.0 Splash scripting manual, see the splash.md file in the Makepad monorepo at tools/splash.md or the Makepad docs. The key rules: height: Fit on every container, width: Fill on the root, := for named children, no commas between properties.

3.8 KiB Raw Permalink Blame History