| name | ply-engine |
| description | Complete implementation and design guide for Ply. Use this skill whenever a task involves ply-engine APIs, plyx workflows, or building UI in Rust with Ply.
|
Ply Engine
This part is the ultimate guide for writing Ply applications.
Part 1: Non-Negotiable Rules
- Never hallucinate Ply APIs. If a method is not listed in this skill, do not invent it.
- Always make sure you do:
use ply_engine::prelude::*;
- Respect feature gates. If an API requires a feature, make sure the feature is enabled before using it.
- Indentation policy for generated code:
- First, detect the existing indentation style and preserve it.
- If style is unclear or you are generating a fresh snippet, default to 2-space indentation.
- Never mix tabs and spaces in the same block.
- Prefer explicit IDs for interactive elements and list items.
- Every element should have explicit sizing configured.
- Builder closures must use chain-return style by default.
- DO THIS:
.layout(|l| l
.direction(TopToBottom)
.align(CenterX, Top)
.gap(12)
.padding(14)
)
- DO NOT DO THIS:
.layout(|l| {
l.direction(TopToBottom)
.align(CenterX, Top)
.gap(12)
.padding(14);
l
})
- The same rule applies to other builder closures such as
overflow, border, scrollbar, floating, effect, shader, text_input, and accessibility.
Part 2: Feature Matrix
Ply crate features:
a11y (default): accessibility supporttext-styling: inline styling and animation tagstinyvg: TinyVG vector renderingshader-build: shader build pipeline utilities for build.rsbuilt-in-shaders: built-in shader assetsnet: HTTP + WebSocket APIsnet-json: JSON deserialization helpers for net responsesaudio: macroquad audio re-exportsstorage: cross-platform persistent storage API
Part 3: App Skeleton
This is the default project structure generated by plyx init:
use ply_engine::prelude::*;
fn window_conf() -> macroquad::conf::Conf {
macroquad::conf::Conf {
miniquad_conf: miniquad::conf::Conf {
window_title: "Hello Ply!".to_owned(),
window_width: 800,
window_height: 600,
high_dpi: true,
sample_count: 4,
platform: miniquad::conf::Platform {
webgl_version: miniquad::conf::WebGLVersion::WebGL2,
..Default::default()
},
..Default::default()
},
draw_call_vertex_capacity: 100000,
draw_call_index_capacity: 100000,
..Default::default()
}
}
#[macroquad::main(window_conf)]
async fn main() {
static DEFAULT_FONT: FontAsset = font!("assets/fonts/MyFont.ttf");
let mut ply = Ply::new(&DEFAULT_FONT).await;
loop {
clear_background(BLACK);
let mut ui = ply.begin();
ui.element()
.width(grow!())
.height(grow!())
.layout(|l| l.align(CenterX, CenterY))
.children(|ui| {
ui.text("Hello, Ply!", |t| t.font_size(32).color(0xFFFFFF));
});
ui.show().await;
next_frame().await;
}
}
Of course this is often expanded with different files that contain different functionality and components.
Part 4: Prelude
Everything below is re-exported from ply_engine::prelude in this repository.
4.1 Core Types
PlyUiElementBuilderNoIdWithIdIdGraphicAssetFontAssetShaderAssetLerpPointerDataPointerState- all easing functions from
crate::easing::*
4.2 Utilities
render_to_textureset_shader_source
4.3 Sizing Macros
grow!fit!fixed!percent!ratio!
4.4 Globbed Enums
AlignX::{Left, CenterX, Right}AlignY::{Top, CenterY, Bottom}BorderPosition::{Outside, Middle, Inside}LayoutDirection::{LeftToRight, TopToBottom}
4.5 Type-Only Re-exports
WrapModeAccessibilityRole
4.6 Feature-Gated Re-exports
built-in-shaders: *net: net, WsMessagestorage: Storagetext-styling: stylingaudio: *
4.7 Always Re-exported Modules and Helpers
jobs module- full
macroquad::prelude::*
- Ply
Color
MacroquadColor alias for macroquad colormacroquad crateCursorIcon
Important: because full macroquad::prelude::* is re-exported, any macroquad-prelude function/type is also in scope when using Ply prelude.
Part 5: Full API Reference (Ply, Ui, Builders)
5.1 Ply Core Methods
Construction and lifecycle:
Ply::new(default_font).awaitPly::new_headless(dimensions)begin() -> Uieval() -> Vec<RenderCommand>show().await
Pointer, focus, and cursor:
pointer_over(id) -> boolpointer_over_ids() -> Vec<Id>focused_element() -> Option<Id>set_focus(id)clear_focus()is_pressed(id) -> boolis_just_pressed(id) -> boolis_just_released(id) -> boolset_cursor(CursorIcon)get_cursor() -> CursorIcon
Text input state by ID:
get_text_value(id) -> &strset_text_value(id, value)get_cursor_pos(id) -> usizeset_cursor_pos(id, pos)get_selection_range(id) -> Option<(usize, usize)>set_selection(id, anchor, cursor)
Layout, bounds, scroll:
set_layout_dimensions(dimensions)pointer_state(position, is_down)update_scroll_containers(drag_scrolling_enabled, scroll_delta, delta_time)bounding_box(id) -> Option<BoundingBox>scroll_container_data(id) -> Option<ScrollContainerData>set_scroll_position(id, position)
Debug and performance:
set_debug_mode(bool)set_debug_view_width(f32)is_debug_mode() -> boolset_culling(bool)max_element_count(u32)max_measure_text_cache_word_count(u32)set_measure_text_function(|text, config| -> Dimensions)
5.2 Ui Methods
element() -> ElementBuildertext(text, |TextConfig| ... )scroll_offset() -> Vector2- inline-state queries for current open element context:
hovered()pressed()just_pressed()just_released()focused()
Ui dereferences to Ply, so all Ply methods are callable from ui too.
5.3 ElementBuilder Methods (Complete)
Layout and sizing:
width(Sizing)height(Sizing)contain(f32)cover(f32)layout(|LayoutBuilder| ...)
Visuals:
background_color(color)corner_radius(f32 | (f32, f32, f32, f32))border(|BorderBuilder| ...) (multiple possible)overflow(|OverflowBuilder| ...)image(ImageSource)effect(shader_asset, |ShaderBuilder| ...)shader(shader_asset, |ShaderBuilder| ...)rotate_visual(|VisualRotationBuilder| ...)rotate_shape(|ShapeRotationBuilder| ...)
Structure and identity:
id(id_like) (NoId -> WithId)get_id() -> &Idfloating(|FloatingBuilder| ...)children(|ui| ...) -> Idempty() -> Id
Interactivity:
with(|&mut Ui, ElementBuilder<WithId>| ...)capture()on_hover(|Id, PointerData| ...)on_press(|Id, PointerData| ...)on_release(|Id, PointerData, bool| ...)on_focus(|Id| ...)on_unfocus(|Id| ...)preserve_focus()
Text input and accessibility:
text_input(|TextInputBuilder| ...)accessibility(|AccessibilityBuilder| ...)
Part 6: Sizing and Layout APIs
6.1 Sizing and Macros
fit!() or fit!(min, max) or named args (min:, max:)grow!() or grow!(min, max, weight) or named args (min:, max:, weight:)fixed!(px)percent!(fraction)ratio!(aspect_ratio)
Notes:
grow!(weight: 0.0) behaves as fit internally.- negative grow weight is invalid.
ratio!(r) derives the dimension from the opposite axis (height = width / ratio on height, width = height * ratio on width). Setting ratio! on both axes panics during layout.contain(ratio) and cover(ratio) adjust the element's resolved bounding box to fit or cover its allocated slot to respect the aspect ratio.
6.2 LayoutBuilder
gap(u16)align(AlignX, AlignY)direction(LayoutDirection)wrap()wrap_gap(u16)padding(u16 | (top, right, bottom, left))
6.3 OverflowBuilder
- clipping:
clip_x(), clip_y(), clip()
- scrolling:
scroll_x(), scroll_y(), scroll()
no_drag_scroll()scrollbar(|ScrollbarBuilder| ...)
6.4 ScrollbarBuilder
width(f32)corner_radius(f32)thumb_color(color)track_color(color)min_thumb_size(f32)hide_after_frames(u32)
6.5 FloatingBuilder
offset(Vector2-like)z_index(i16)anchor((AlignX, AlignY), (AlignX, AlignY))attach_parent()attach_root()attach_id(id)clip_by_parent()passthrough()
6.6 BorderBuilder
color(color)all(u16)left(u16)right(u16)top(u16)bottom(u16)between_children(u16)position(BorderPosition)
6.7 Rotation Builders
Visual rotation (rotate_visual):
degrees(f32)radians(f32)pivot((x, y)) normalized in [0,1]flip_x()flip_y()
Shape rotation (rotate_shape):
degrees(f32)radians(f32)flip_x()flip_y()
Part 7: Text APIs
7.1 ui.text + TextConfig
Text configuration methods:
color(color)font(&'static FontAsset)font_size(u16)letter_spacing(u16)line_height(u16)wrap_mode(WrapMode)alignment(AlignX)effect(shader_asset, |ShaderBuilder| ...)accessible()
WrapMode variants:
7.2 Color Inputs
Ply Color accepts:
0xRRGGBB integers(u8, u8, u8)(u8, u8, u8, u8)(f32, f32, f32)(f32, f32, f32, f32)
Important: float channels are in 0..255 space, not 0..1.
Part 8: Text Input APIs
8.1 TextInputBuilder
placeholder(&str)max_length(usize)password()multiline()drag_select()font(&'static FontAsset)font_size(u16)text_color(color)placeholder_color(color)cursor_color(color)selection_color(color)line_height(u16)scrollbar(|ScrollbarBuilder| ...)no_styles_movement()on_changed(|&str| ...)on_submit(|&str| ...)
8.2 text_input::styling module (feature: text-styling)
Important public functions:
escape_str(s): Escapes all style delimiters in a stringstrip_styling(s): Removes all style tags, returning plain contentcursor_to_content(s, pos): Converts cursor pos to content character indexcontent_to_cursor(s, pos, snap_to_content): Converts content character index to cursor pos. When snap_to_content is true, the cursor skips structural positions like } and lands on the next visible character.cursor_to_raw(s, pos): Converts styled cursor pos to raw index in the stringraw_to_cursor(s, pos): Converts raw string index to cursor position in the styled string
Different types of positions:
raw position: index in the full styled string, including markup such as {color=...|...} and escape characters.cursor position: visual cursor index used by text input editing. This includes visible characters and styling structure positions that the cursor can pass through.content position: index in plain visible content after styling is stripped.
Part 9: IDs, Interactivity, and State
9.1 Id
Id::new(label)Id::new_index(label, index)Id::new_index_seed(label, index, seed)From<&'static str> and From<(&str, u32)>
9.2 Inline State Queries
Inside the active .children(|ui| ...) scope:
ui.hovered()ui.pressed()ui.just_pressed()ui.just_released()ui.focused()
9.3 Callback Events
.on_hover(|id, pointer| ...).on_press(|id, pointer| ...).on_release(|id, pointer, hovered| ...).on_focus(|id| ...).on_unfocus(|id| ...)
PointerData:
pointer.position: Vector2pointer.state: PointerState (Idle, PressedThisFrame, Pressed, ReleasedThisFrame)pointer.pressed() -> bool: checks if pointer is currently pressed (Pressed or PressedThisFrame)pointer.released() -> bool: checks if pointer is currently released (Idle or ReleasedThisFrame)pointer.just_pressed() -> bool: checks if pointer was just pressed this frame (PressedThisFrame)pointer.just_released() -> bool: checks if pointer was just released this frame (ReleasedThisFrame)
Use .capture() on interactive elements (e.g. buttons inside a larger clickable area) to capture pointer input and prevent it from propagating to parent elements.
Use .preserve_focus() on toolbar-like controls that should not steal text-input focus.
9.4 State Queries by ID
is_pressed(id)is_just_pressed(id)is_just_released(id)pointer_over(id)pointer_over_ids()bounding_box(id)scroll_container_data(id)
Part 10: Rendering, Assets, and Shader APIs
10.1 Assets
GraphicAsset:
graphic!("assets/images/logo.png") (macro embeds bytes relative to crate manifest)GraphicAsset { id, data }
FontAsset:
font!("assets/fonts/lexend.ttf") (macro embeds bytes relative to crate manifest)FontAsset { id, data }
Image inputs accepted by .image(...):
&'static GraphicAssetTexture2Dtinyvg::format::Image (feature: tinyvg)
10.2 Shader APIs
ShaderAsset variants:
shader!("assets/shaders/custom.frag.glsl") (macro embeds shader source)Source { id, fragment }Stored(&'static str)
ShaderBuilder:
.uniform(name, value) where value is one of:
f32[f32; 2][f32; 3][f32; 4]i32[[f32; 4]; 4]
Runtime shader source updates:
set_shader_source(name, fragment_source)- then reference through
ShaderAsset::Stored(name)
10.3 Render Utility
render_to_texture(width, height, || { draw calls }) -> Texture2D
10.4 Built-in Shader Constants (feature: built-in-shaders)
FOIL: u_time (required), u_speed (default 1.0), u_intensity (default 0.3)HOLOGRAPHIC: u_time (required), u_speed (default 1.0), u_saturation (default 0.7)DISSOLVE: u_threshold (required), u_edge_color (required), u_edge_width (default 0.05), u_seed (default 0.0)GLOW: u_glow_color (required), u_glow_radius (default 0.05), u_glow_intensity (default 1.0)CRT: u_line_count (default 100.0), u_intensity (default 0.3), u_time (recommended)GRADIENT_LINEAR: u_color_a (required), u_color_b (required), u_angle (default 0.0, radians)GRADIENT_RADIAL: u_color_a (required), u_color_b (required), u_center (default [0.5, 0.5]), u_radius (default 0.5)GRADIENT_CONIC: u_color_a (required), u_color_b (required), u_center (default [0.5, 0.5]), u_offset (default 0.0), u_hardness (default 0.0)
Part 11: Accessibility APIs
11.1 AccessibilityRole variants
NoneButtonLinkHeading { level }LabelStaticTextTextInputTextAreaCheckboxRadioButtonSliderGroupListListItemMenuMenuItemMenuBarTabTabListTabPanelDialogAlertDialogToolbarImageProgressBar
11.2 AccessibilityBuilder methods
- role shortcuts:
button(label: &str)heading(label: &str, level: u8)link(label: &str)static_text(label: &str)checkbox(label: &str)slider(label: &str)image(alt: &str)
- generic fields:
role(role: AccessibilityRole)label(text: &str)description(text: &str)value(text: &str)value_min(min: f32)value_max(max: f32)checked(checked: bool)
- focus and order:
focusable()tab_index(index: i32)
- directional focus:
focus_right(target: impl Into<Id>)focus_left(target: impl Into<Id>)focus_up(target: impl Into<Id>)focus_down(target: impl Into<Id>)
- focus ring:
disable_ring()ring_color(color: impl Into<Color>)ring_width(width: u16)
- live regions:
live_region_polite()live_region_assertive()
Part 12: Feature Modules (Net, Storage, Jobs, Audio)
12.1 Networking (net)
HTTP:
net::get(id, url, |HttpConfig| ...)net::post(...)net::put(...)net::delete(...)net::request(id) -> Option<Request>
HttpConfig methods:
header(key, value)body(&str)body_bytes(Vec<u8>)
Request methods:
response() -> Option<Result<Arc<Response>, String>>cancel()
Response methods:
status() -> u16text() -> &strbytes() -> &[u8]json<T>() (feature: net-json)
WebSocket:
net::ws_connect(id, url, |WsConfig| ...)net::ws(id) -> Option<WebSocket>
WsConfig methods:
header(key, value)insecure()
WebSocket methods:
send(&[u8])send_text(&str)recv() -> Option<WsMessage>close()
WsMessage variants:
ConnectedText(String)Binary(Vec<u8>)Error(String)Closed
12.2 Storage (storage)
Storage::new(path).awaitsave_string(path, data).awaitsave_bytes(path, data).awaitload_string(path).awaitload_bytes(path).awaitremove(path).awaitexport(path).await
12.3 Jobs (jobs)
jobs::spawn(id, || async move { ... }, |result| { ... })jobs::running(id)jobs::is_running(id)jobs::list()
12.4 Audio (audio)
When audio feature is enabled, macroquad audio APIs are in prelude.
Typical calls:
load_sound(path).awaitload_sound_from_bytes(bytes).awaitplay_sound_once(&sound)play_sound(&sound, PlaySoundParams { .. })stop_sound(&sound)set_sound_volume(&sound, volume)
Part 13: Lerp and Easing APIs
13.1 Lerp trait
Implemented for:
f32u16Vector2macroquad::prelude::Vec2(f32, f32, f32, f32)(u16, u16, u16, u16)Color
Color-specific helpers:
Color::lerp_srgb(...)Color::lerp_oklab(...)
13.2 Easing functions in prelude
ease_in_quad, ease_out_quad, ease_in_out_quadease_in_cubic, ease_out_cubic, ease_in_out_cubicease_in_quart, ease_out_quart, ease_in_out_quartease_in_sine, ease_out_sine, ease_in_out_sineease_in_expo, ease_out_expo, ease_in_out_expoease_in_back, ease_out_back, ease_in_out_backease_in_elastic, ease_out_elastic, ease_in_out_elasticease_out_bounce, ease_in_bounce, ease_in_out_bounce
Part 14: Shader Build Pipeline API
Use in build.rs with feature shader-build in build-dependencies.
Main API:
ShaderBuild::new().source_dir("...").output_dir("...").slangc_path("...").override_file_type_handler(ext, handler).build()
Defaults:
- source:
shaders/
- output:
assets/build/shaders/
- SPIR-V temp:
build/shaders/spirv/
Part 15: plyx CLI Reference for AI
If plyx is available, prefer it for setup and platform builds.
plyx initplyx add [args]plyx skill [--install]plyx apk [--native] [--install] [--auto]plyx webplyx ios [--device] [--actions] [--auto]plyx completions <shell> [--install]
15.1 plyx init
Creates a project, selects a font from Google Fonts, and selects feature flags.
Generates:
- Cargo.toml
- src/main.rs
- assets/fonts/.ttf
- optional build.rs and shaders/ if shader pipeline is selected
- optional
.claude/skills/ply-engine/SKILL.md
15.2 plyx add
Interactive mode (no args) or non-interactive forms:
plyx add <feature-key>plyx add font <font name>
Feature keys recognized by plyx templates:
tinyvgbuilt-in-shadersshader-pipelinetext-stylingnetnet-json (depends on net)audiostorageskill
skill and shader-pipeline are plyx concepts, not feature keys in [dependencies]. shader-pipeline adds build-dependencies and build.rs. skill installs .claude/skills/ply-engine/SKILL.md into the project.
15.3 plyx web
Builds release wasm and outputs to build/web/:
build/web/app.wasmbuild/web/index.htmlbuild/web/ply_bundle.js- copies
assets/ if present
15.4 plyx apk
Modes:
- Docker (default)
- native (
--native)
Useful flags:
--install to install with adb--auto non-interactive mode
APK output location:
target/android-artifacts/release/apk/<crate>.apk
15.5 plyx ios
Modes:
- simulator build by default
- real device with
--device
- workflow generation with
--actions
Requirements:
- macOS + Xcode tools (
xcrun)
- proper Rust iOS target
- for
--device: signing identity, provisioning profile, and entitlements
15.6 plyx skill
plyx skill prints the bundled skill text to stdout.plyx skill --install installs to ~/.claude/skills/ply-engine/SKILL.md.
Part 16: Common Patterns
This section shows some common patterns that emerge when building with Ply. These are just examples, not requirements. You should feel free to deviate from these patterns when the situation calls for it and use appropriate values and variations. We show this with a lot of constants and default values like 24 that you would replace in a real app.
16.1 Cursor
Ply provides engine-managed cursor handling via ui.set_cursor(CursorIcon) and ui.get_cursor() -> CursorIcon:
ui.set_cursor(CursorIcon::Pointer);
let current: CursorIcon = ui.get_cursor();
- The default cursor is
CursorIcon::Pointer.
ui.set_cursor(...) persists across frames until explicitly changed, and overwrites ui.get_cursor() immediately.- The cursor is automatically applied to the window during
ui.eval() / ui.show() (when not headless).
16.2 Styling Function Pattern
Reusable styling should be plain Rust functions that take and return ElementBuilder.
fn rounded<'ply, S>(el: ElementBuilder<'ply, S>) -> ElementBuilder<'ply, S> {
el.corner_radius(12.0)
}
fn dark_bg<'ply, S>(el: ElementBuilder<'ply, S>) -> ElementBuilder<'ply, S> {
el.background_color(0x2E2A28)
}
dark_bg(rounded(ui.element()))
.width(grow!())
.height(fixed!(60.0))
.children(|ui| {
ui.text("Styled with functions", |t| t.font_size(20).color(0xFFFFFF));
});
For parameterized styles:
fn my_style<'ply, S>(el: ElementBuilder<'ply, S>, bg: u32, radius: f32) -> ElementBuilder<'ply, S> {
el.background_color(bg).corner_radius(radius)
}
my_style(ui.element(), 0x181515, 10.0)
.width(fit!())
.height(fit!())
.empty();
16.3 Button Example
You might want your buttons to use something like this with .with():
fn button(ui: &mut Ui, label: &str, mut on_click: impl FnMut() + 'static) {
ui.element().width(fit!()).height(fit!())
.corner_radius(SOME_RADIUS)
.layout(|l| l.padding(SOME_PADDING).align(CenterX, CenterY))
.accessibility(|a| a.button(label))
.on_press(move |_, _| on_click())
.with(|ui, el| {
let bg = if ui.pressed() {
LIGHT_PRIMARY_COLOR
} else if ui.hovered() || ui.focused() {
DARK_PRIMARY_COLOR
} else {
PRIMARY_COLOR
};
el.background_color(bg)
})
.children(|ui| {
ui.text(label, |t| t.font_size(24).color(0xFFFFFF));
});
}
.with() executes after the element's ID has been established in .empty() or .children(), so queries like ui.pressed(), ui.hovered(), and ui.focused() accurately refer to this element and el.get_id() is available without needing an extra wrapper element.
16.4 Polling HTTP Example
if user_data.is_none() {
net::get("user_data", "https://example.com/", |r| r
.header("Authorization", "Bearer token")
);
}
// ...
if user_data.is_none() {
if let Some(req) = net::request("user_data") {
match req.response() {
None => {
ui.text("{swing|Loading...}", |t| t.font_size(24).color(0xFFFFFF));
}
Some(Ok(resp)) => {
if resp.status() == 200 {
let data: UserData = resp.json().unwrap_or_else(|e| {
eprintln!("failed to parse user data: {e}");
UserData::default()
});
user_data = Some(data);
}
}
Some(Err(err)) => {
eprintln!("request failed: {err}");
}
}
}
}
16.5 Storage + Jobs Example
jobs::spawn(
"save_game",
|| async move {
Storage::new("my_app").await?
.save_string("save.json",
serde_json::to_string(&game_state).map_err(|e| e.to_string())?
).await
},
|result| {
if let Err(e) = result {
eprintln!("Failed to save game: {e}");
}
},
)?;
Using Storage on the main thread will cause frame skips on the web. It's best to use it inside a job like this to avoid blocking the main thread.
16.6 Render To Texture + Shader Example
Use a static shader asset for normal rendering flows.
static TINT_SHADER: ShaderAsset = ShaderAsset::Source {
id: "tint.frag.glsl",
fragment: r#"#version 100
precision mediump float;
varying vec2 uv;
uniform sampler2D Texture;
uniform vec4 u_tint_color;
uniform float u_tint_strength;
void main() {
vec4 base = texture2D(Texture, uv);
vec3 mixed_rgb = mix(base.rgb, u_tint_color.rgb, clamp(u_tint_strength, 0.0, 1.0));
gl_FragColor = vec4(mixed_rgb, base.a);
}"#,
};
let chart = render_to_texture(400.0, 200.0, || {
clear_background(BLANK);
draw_line(0.0, 180.0, 400.0, 40.0, 3.0, GREEN);
draw_circle(200.0, 110.0, 8.0, RED);
});
ui.element()
.width(fixed!(400.0))
.height(fixed!(200.0))
.image(chart)
.effect(&TINT_SHADER, |s| s
.uniform("u_tint_color", [1.0, 0.85, 0.75, 1.0])
.uniform("u_tint_strength", 0.25f32)
)
.empty();
16.7 Accessibility Example
ui.element().id("first").width(fit!()).height(fit!())
.layout(|l| l.padding(SOME_PADDING))
.background_color(FIRST_BUTTON_COLOR)
.accessibility(|a| a.button("First").tab_index(1).focus_right("second"))
.on_press(|_, _| println!("first pressed"); )
.children(|ui| {
ui.text("First", |t| t.font_size(24).color(0xFFFFFF).accessible());
});
ui.element().id("second").width(fit!()).height(fit!())
.layout(|l| l.padding(SOME_PADDING))
.background_color(SECOND_BUTTON_COLOR)
.accessibility(|a| a.button("Second").tab_index(2).focus_left("first"))
.on_press(|_, _| println!("second pressed"); )
.children(|ui| {
ui.text("Second", |t| t.font_size(24).color(0xFFFFFF));
});
16.8 Text Input + Text Styling Cursor Helpers
ui.element().id("editor").width(fixed!(400.0)).height(fixed!(120.0))
.layout(|l| l.padding(BACKGROUND_PADDING))
.background_color(BACKGROUND_COLOR)
.text_input(|t| t
.multiline()
.font_size(24)
.drag_select()
.no_styles_movement()
.on_changed(|text| println!("changed: {text}"))
);
let raw = ui.get_text_value("editor").to_string();
let plain = styling::strip_styling(&raw);
let highlighted = plain.replace("TODO", "{color=#FFC32C|TODO}");
if raw != highlighted {
let cursor = ui.get_cursor_pos("editor");
let content_pos = styling::cursor_to_content(&raw, cursor);
ui.set_text_value("editor", &highlighted);
let new_cursor = styling::content_to_cursor(&highlighted, content_pos, true);
ui.set_cursor_pos("editor", new_cursor);
}
.text_input() is a terminal method on ElementBuilder (returning Id), allowing developers to configure layout modifiers like .padding() directly on the housing element itself. The scrollable area includes the padding and scrollbars extend to include the padded perimeter. Also note how the .text_input closure is styled with the letter t on the first line and then the .arguments() on the following lines. This is how you should style builders that stretch across multiple lines.
16.9 Floating Tooltip
ui.element().id("tooltip_target").width(fit!()).height(fit!())
.layout(|l| l.padding(5))
.corner_radius(6.0)
.background_color(BUTTON_COLOR)
.children(|ui| {
ui.text("Hover me", |t| t.font_size(24).color(0xE8E0DC));
if ui.hovered() {
ui.element().width(fit!()).height(fit!())
.floating(|f| f
.attach_parent()
.anchor((CenterX, Top), (CenterX, Bottom))
.offset((0.0, -4.0))
)
.background_color(TOOLTIP_COLOR)
.corner_radius(6.0)
.layout(|l| l.padding(5))
.children(|ui| {
ui.text("Tooltip text", |t| t.font_size(16).color(0xFFFFFF));
});
}
});
16.10 Wrap Layout and Scrollbar
ui.element().width(grow!()).height(grow!())
.layout(|l| l.wrap().wrap_gap(8).gap(8).padding(8))
.overflow(|o| o
.scroll_y()
.scrollbar(|s| s
.width(4.0)
.thumb_color(0xFFFFFF)
.track_color(0x222222)
.hide_after_frames(60)
)
)
.children(|ui| {
for i in 0..200 {
ui.element().id(("chip", i)).width(fit!()).height(fit!())
.layout(|l| l.padding(6))
.background_color(0x333333)
.corner_radius(6.0)
.children(|ui| {
ui.text(&format!("Chip {i}"), |t| t.font_size(16).color(0xFFFFFF));
});
}
});
16.11 GraphicAsset and FontAsset Pattern
Declare graphic and font assets as static using graphic! and font! macros.
static LOGO: GraphicAsset = graphic!("assets/images/logo.png");
static ICON_TVG: GraphicAsset = graphic!("assets/images/icon.tvg");
static BODY_FONT: FontAsset = font!("assets/fonts/lexend.ttf");
// ...
ui.element().width(fixed!(96.0)).height(fixed!(96.0)).image(&LOGO).empty();
ui.element().width(fixed!(96.0)).height(fixed!(96.0)).image(&ICON_TVG).empty();
ui.text("Body", |t| t.font(&BODY_FONT).font_size(24).color(0xFFFFFF));
UI/UX Playbook
This part is the definitive reference for producing interfaces and visuals that are both rigorously functional and genuinely memorable. It covers design thinking, aesthetic direction, foundational principles, common failure modes, advanced UX strategy, motion design, and game UI.
Part 1: Design Thinking
Before touching anything visual, understand the context and commit to a direction.
1.1 Understand the Brief
- Purpose: What problem does this interface solve? Who uses it, and when?
- Tone: Pick a clear aesthetic extreme and commit to it. Options include: brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian. These are starting points, design something true to the context, not a template.
- Constraints: Platform, performance needs, accessibility requirements.
- Differentiation: What is the one thing someone will remember about this interface? Name it before you build it.
1.2 Commit, Don't Hedge
The single biggest failure mode in design is timidity, making choices that offend no one and inspire no one. Bold maximalism and refined minimalism are both valid. What fails is the middle: generic layouts, safe fonts, and evenly-distributed palettes that look like every other product.
Match execution depth to aesthetic vision. A maximalist design needs elaborate layering, rich animation, and complex composition. A minimalist design needs razor-sharp spacing, perfect type, and restraint exercised with intention.
Part 2: Foundations
2.1 Signifiers & Affordances
- Self-Explanatory UI: Use containers to signal relationships. If items share a container, they are perceived as related.
- Visual States: Always define all four interaction states if they exist: Hover, Active, Disabled, Loading. An incomplete state system is an incomplete design.
- Cursor Icons: Explicitly define cursor changes. A static cursor is a broken signifier.
- Show, Don't Tell: The UI should communicate how it works through visual cues alone, not instructional text.
2.2 Visual Hierarchy & Contrast
- Scanning Priority: Place high-priority information at the top. Use size, weight, and color to direct the eye.
- The Contrast Engine: Contrast creates hierarchy. Juxtapose big/small, colorful/monochrome, heavy/light. Everything cannot be equally important.
- Flow Indicators: Use visual indicators to demonstrate relationships and flow without requiring text.
2.3 The 4-Point Grid
- Standard Spacing: Use multiples of 4 for all spacing: 4, 8, 16, 24, 32, 48, 64, unless when your UI should stay the same when resizing.
- Section Breathing Room: Usually use at minimum 32px between visually distinct sections.
- Proximity as Meaning: Group related elements tightly. Separate unrelated ones clearly. If a label and its input are far apart, the relationship breaks.
2.4 Color & Depth
- Semantic Color: Assign meaning consistently: Blue (action/interactive), Red (error/danger), Green (success/confirmation), Yellow (warning/caution). Never reverse these expectations.
- Dark Mode Depth: Represent depth by making foreground surfaces lighter than the background, not darker. This mirrors how light physically works.
- Dominant + Accent: Dominant colors with sharp accent colors outperform evenly-distributed palettes. Pick a position and commit to it.
2.5 Typography
Typography is communication architecture.
Font Personality by Category:
- Serif: Traditional, classic, editorial. Best for print contexts or brands that lean into heritage.
- Sans-Serif: Modern, legible, digital-native. The standard for screens.
- Display/Decorative: Expressive, high-impact. Use only for headlines or hero moments.
- Outdated Fonts: Avoid fonts with strong cultural baggage (Comic Sans, Papyrus, Courier). They undermine credibility regardless of context.
- Availibility: Usually use fonts that the user already has in their assets. If the user has no fitting fonts use
plyx add font NAME to download from Google Fonts.
Pairing & Palette:
- Usually use no more than three typefaces per project. One is often enough.
- Pair by contrast: a bold, characterful display face with a quiet, readable body face.
- If using a single typeface, create hierarchy through weight, size, and style variation.
- Avoid generic defaults. Reach for typefaces with genuine personality. The choice should feel considered, not defaulted to.
Part 3: Aesthetic Execution
3.1 Spatial Composition
Move beyond standard grid layouts. Explore:
- Asymmetry and overlap: Elements that cross boundaries or break the grid create dynamism.
- Diagonal flow: Leading the eye along a diagonal rather than straight down creates energy.
- Generous negative space OR controlled density: Both work. What fails is accidental clutter or accidental emptiness.
- Rule of Thirds: It's often good to divide the composition into a 3×3 grid. Place focal points near intersections. The eye naturally follows this path.
3.2 Shape Language
- Geometric: Circles and squares are dependable, structured and universal for components and UI containers.
- Organic: Free-form shapes are best for illustration, branding moments, or softening otherwise rigid layouts.
- Shapes organize, separate, and give content visual "weight." Use them intentionally.
3.3 Texture & Form
- Texture adds tactility and depth to flat designs. Use for backgrounds, icons, and accent areas - never everywhere at once.
- Form implies three-dimensionality through light, shadow, and perspective.
3.4 Repetition & Consistency
Repeat visual elements (color palette, header styles, icon library, corner radii, spacing patterns) throughout a design. Repetition is not laziness - it is branding. It lets users relax and engage with content rather than decode the interface.
Part 4: Anti-Patterns to Avoid
These are common failure modes that immediately mark a design as amateur.
4.1 Visual Noise
- Rainbow gradients: Multi-hue gradients almost always look unintentional. Limit gradients to tonal variations of a single color family.
- Unnecessary strokes/borders: Remove borders that don't serve a specific contrast or containment purpose. When in doubt, remove it.
- Effect overload: Each visual effect competes for attention. Use effects sparingly so meaningful ones land.
4.2 Inconsistency
- Corner radius chaos: Mixing 4px, 8px, 16px, and 24px radii across components without logic looks broken, not dynamic.
- Mismatched assets: Icons from different libraries, or illustrations with conflicting lighting and stroke styles, destroy visual coherence.
- Redundant affordances: Don't show swipe arrows on touch interfaces or label buttons that already have universal icons.
4.3 User Flow Gaps
- Missing escape routes: Every optional flow needs a "Skip" or "Not now" path. Trapping users is a trust violation.
- Blank search states: Never show an empty screen when a user opens search. Provide recent searches, suggestions, or categories.
4.4 Generic Aesthetics
Avoid the convergent defaults that make designs indistinguishable from each other:
- Overused typefaces that have become visual wallpaper
- Purple gradients on white backgrounds
- Predictable card-based layouts with no compositional tension
- Safe, forgettable color palettes that feel chosen by elimination rather than intention
Every design should feel like it was made for this specific context.
Part 5: Advanced UX Strategy
5.1 User Bases
Design for different user bases:
- New users: Prioritize simplicity and clear "getting started" pathways. Reduce cognitive load.
- Returning users: Surface current progress, quick-access features, and continuations of prior sessions.
- Power users: Expose advanced stats, shortcuts, and optimization tools. Don't hide capability behind beginner guardrails.
5.2 Progress & Trust
- Visual timelines: Use staged progress indicators (Processing → Shipped → Delivered) rather than raw dates or text status updates. People understand journey better than timestamp.
- Humanizing data: Include names, photos, or personal details for service providers or counterparties. It transforms transactions into interactions.
5.3 Input Method Selection
- Sliders: Use for casual, range-based, or exploratory input (age ranges, filters, approximate values).
- Text fields: Use for precise, repetitive, or high-accuracy input (weights, quantities, identifiers).
5.4 Alignment Discipline
Elements that are visually "almost" aligned create tension that reads as disorder.
Part 6: Motion Design
Motion is communication. All UI movement must justify itself against these five criteria:
- Responsiveness: Interactions must feel immediate and fluid. Latency in motion reads as lag even when performance is fine.
- Intention: Motion should guide focus; toward a key action, toward new content, away from what just resolved.
- Awareness: Elements should behave differently based on their position and context on screen. Motion is spatial.
- Consistency: Repeated motion patterns build familiarity. Users learn interface "physics".
- Physical Intuition: Movement should feel grounded. Paper-like physics for document metaphors. Elastic snap for playful UI. Parallax depth for epic scale. Match the motion vocabulary to the world of the product.
Practical priorities:
- One well-orchestrated entrance with staggered reveals creates more delight than dozens of scattered micro-interactions.
- Hover states and scroll-triggered reveals should surprise.
- Animate meaning, not decoration. If removing the animation loses nothing, remove it.
Part 7: Game UI & Immersive Interfaces
7.1 Diegetic vs. Non-Diegetic UI
- Diegetic: UI that exists within the game world (a holographic HUD inside a helmet visor, a health bar on a character). Creates immersion.
- Non-diegetic: Traditional overlay UI that floats above the world. Familiar and legible, but breaks fiction.
Choose deliberately. Mixed approaches require strong thematic justification.
7.2 Unified Thematics
Define a visual "world", a set of recurring motifs (shape language, texture, color temperature, typographic character), and enforce it across every element: icons, typography, backgrounds, particle effects, and transitions. If the UI could be lifted out and placed in a different product without looking wrong, it isn't themed.
7.3 Platform Adaptation
- Pointer interfaces: Support precision, density, and keyboard shortcuts. Small targets are acceptable.
- Touch interfaces: Minimum 44×44pt touch targets. Simplified layouts. Remove affordances that assume hover states.
7.4 Information Speed
In high-intensity contexts, layout must allow the user to extract critical information in milliseconds without conscious eye movement. Proximity encodes meaning: a bar next to a name reads as "health"; a counter next to a bar reads as "progress." Design these relationships deliberately.
