UI Migration Plan for Bevy Examples

[viridia]

Goal Description

Migrate the Bevy examples away from bevy_ui::widgets and to either bevy_feathers or bevy_ui_widgets.

Goal Status

This is a potential Bevy Project Goal. Its state on the Project Goals Board determines if it is Proposed, Postponed, Blocked (Approved), Inactive (Approved), Active (Approved), Completed, or Declined.

• Staffing SMEs: @viridia
• Working Group Link: Working Group not yet formed
• Design Documents: See below.

[alice-i-cecile]

Lovely! Blocked until the release candidate is out :)

[viridia]

Disclaimer: this document was generated using an LLM based on an analysis of the Bevy source code. It has also been lightly edited.

Overview

The Button (and related Interaction-based pattern) from bevy_ui::widgets is being deprecated. All examples that use it need to migrate to one of two new systems:

• bevy_ui_widgets — Headless widgets with no built-in styling. Best for examples that teach game UI patterns, because users need to learn how to style their own buttons, sliders, etc.
• bevy_feathers — Opinionated, styled widgets for tool/editor-style UI. Best for examples that use UI incidentally to control a demo (e.g., toggle a rendering feature). All feathers migrations also require a BSN (Bevy Scene Notation) migration as a prerequisite.

---

Decision Criteria

Example type	Target
The example is about UI — it teaches how to build game UI	bevy_ui_widgets (headless)
The example is not about UI — UI is just a control panel for a demo	bevy_feathers (styled, requires BSN first)

---

Affected Examples

Already Migrated ✅

These examples in widgets already use the new APIs and are not part of this migration:

• standard_widgets.rs — already uses bevy_ui_widgets::Button
• standard_widgets_observers.rs — already uses bevy_ui_widgets::Button
• feathers_gallery.rs — already uses bevy_feathers
• feathers_counter.rs — already uses bevy_feathers
• large_scenes/bevy_city/src/settings.rs — already uses bevy_feathers

---

Phase 1 — Low-Complexity UI Examples → bevy_ui_widgets

These examples are about UI and are small enough to be quick wins. Migration involves replacing the bare Button marker + manual Interaction polling with bevy_ui_widgets::Button and its Activate event.

Example	Lines	Notes
ui/styling/transparency_ui.rs	80	Two buttons with transparent labels; nearly mechanical substitution
ui/images/ui_texture_slice.rs	95	Texture-sliced button; button is the whole point
ui/widgets/button.rs	113	The canonical button example; must demonstrate the new API clearly
ui/images/ui_texture_atlas_slice.rs	114	Texture atlas sliced button variant of above
ui/layout/ghost_nodes.rs	124	Button is a convenient interactive node; mostly structural
ui/widgets/tab_navigation.rs	150	Buttons used as tab-navigable focusable elements

Complexity: Low. These are nearly mechanical substitutions.

---

Phase 2 — Low-Complexity Non-UI Examples → bevy_feathers + BSN

These examples use buttons only as demo controls. They are small and straightforward.

Example	Lines	Widget usage	Notes
remote/app_under_test.rs	113	Single button, test target	Also used as a BRP integration test target; verify test still works
state/states.rs	161	Two buttons for state transitions
3d/split_screen.rs	204	One button to switch active camera
mobile/src/lib.rs	210	One button, plays sound	Simple but needs mobile-platform testing
state/sub_states.rs	233	A few state buttons
state/custom_transitions.rs	279	A few buttons

Complexity: Low–Medium.

---

Phase 3 — Medium-Complexity UI Examples → bevy_ui_widgets

These examples are about teaching UI and have more involved button interaction logic.

Example	Lines	Notes
usage/cooldown.rs	179	Cooldown overlay on a button; teaches ability-cooldown UI pattern
usage/context_menu.rs	197	Right-click context menu built from buttons; game UI pattern
ui/styling/gradients.rs	299	Gradient demo with hover observers on buttons
ui/ui_transform.rs	302	~9 buttons used to demonstrate UI translation/rotation/scale
ui/layout/size_constraints.rs	360	Buttons trigger constraint changes; UI teaching example
ui/layout/display_and_visibility.rs	456	Buttons toggle Display/Visibility on target nodes
ui/navigation/directional_navigation.rs	473	Complex navigation; many buttons with name-based focus tracking

Complexity: Medium. These have hand-rolled interaction systems that need to be refactored around events.

---

Phase 4 — helpers/widgets.rs → bevy_feathers (High Leverage)

widgets.rs is a shared module included as mod widgets by approximately 10 rendering examples. It implements a custom RadioButton + WidgetClickEvent + WidgetClickSender pattern on top of the old Button widget.

Migrating this one file to use bevy_feathers::controls::FeathersRadio (and bevy_ui_widgets::RadioButton for the headless equivalent if needed) will cascade across all of the following examples simultaneously:

Example	Lines	Notes
3d/contact_shadows.rs	457	Uses RadioButton, RadioButtonText
3d/clustered_decal_maps.rs	450	Uses RadioButton, RadioButtonText
3d/pcss.rs	416	Uses RadioButton, RadioButtonText
3d/mixed_lighting.rs	524	Uses RadioButton, RadioButtonText
3d/mirror.rs	677	Uses RadioButton, WidgetClickEvent
2d/dynamic_mip_generation.rs	852	Uses RadioButton, option_buttons helper
3d/light_probe_blending.rs	~?	Uses WidgetClickEvent, WidgetClickSender
3d/pccm.rs	~?	Uses WidgetClickEvent, WidgetClickSender

Complexity: Medium for the helper itself; the cascade to individual examples should be low-complexity.

---

Phase 5 — Medium–High Complexity Non-UI Examples → bevy_feathers + BSN

Example	Lines	Notes
animation/animation_masks.rs	488	Buttons toggle animation mask layers
state/computed_states.rs	608	Many buttons driving complex state transitions
3d/clustered_decals.rs	545	Radio buttons + drag interaction
3d/light_textures.rs	684	Multiple radio groups
3d/color_grading.rs	606	Has both a raw Button and a complex ColorGradingOptionWidgetType::Button enum
3d/ssr.rs	881	Uses both helpers/widgets AND spawns its own buttons

Complexity: High. These are large examples with non-trivial UI structures.

---

Phase 6 — Large / Special Cases

Example	Lines	Target	Notes
ui/styling/box_shadow.rs	635	bevy_ui_widgets	Buttons control shadow settings; this is a UI styling example
ui/navigation/directional_navigation_overrides.rs	866	bevy_ui_widgets	Largest navigation example, multi-page
showcase/game_menu.rs	727	bevy_ui_widgets	Intentional game menu showcase; headless to show game-style patterns
stress_tests/many_buttons.rs	400	bevy_ui_widgets	Benchmarks UI rendering; keep headless so it tests raw performance
testbed/ui.rs	2041	Mixed	Testbed covers many scenarios; needs case-by-case evaluation

Complexity: High–Very High.

---

Missing Framework Features / Gaps

The following features would benefit the migration and should be tracked:

bevy_feathers

• FeathersRadioGroup helper pattern — The helper option_buttons() function creates a labeled group of radio buttons from a slice of (value, label) pairs. This pattern is used in ~10 examples and would benefit from a first-class feathers equivalent (e.g. a FeathersOptionGroup or FeathersRadioGroup component/scene). Currently FeathersRadio exists but the group-layout scaffolding is manual.
• Context menu semantics — bevy_feathers has FeathersMenu but there is no positioning support for spawning it at a pointer location (i.e. right-click context menus). This is needed before usage/context_menu.rs can be migrated to feathers.
• Cooldown/disabled overlay pattern — usage/cooldown.rs uses a custom shrinking overlay clip on a button to show cooldown remaining. There is no standard way to do this with feathers today.

bevy_ui_widgets

• Scrollbar integration example — bevy_ui_widgets has Scrollbar but no example demonstrates it as part of a real UI pattern.
• Focus styling API — Many game UI examples need to show a focused button state. A utility API or documentation pattern for applying focus ring styling in headless widgets would reduce boilerplate in migrated examples.

BSN / General

• helpers/widgets.rs BSN equivalent — A feathers-native equivalent of the option_buttons() / handle_ui_interactions() helper pattern should be established before batch-migrating the 3D rendering examples.

---

Summary Table

Phase	Count	Target	Blocker
1 — Simple UI examples	6	bevy_ui_widgets	None
2 — Simple non-UI examples	6	bevy_feathers + BSN	BSN readiness
3 — Medium UI examples	7	bevy_ui_widgets	None
4 — helpers/widgets.rs cascade	1 (+8)	bevy_feathers + BSN	BSN readiness
5 — Complex non-UI examples	6	bevy_feathers + BSN	BSN readiness
6 — Large/special cases	5	Mixed	Varies
Total	~39