From cbb9ca724bd36de9c3186ff69f9fceae512b0a39 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Wed, 14 Apr 2021 15:45:40 -0400
Subject: [PATCH 01/15] Initial UI Building Blocks RFC

Moved from https://github.com/alice-i-cecile/bevy-temp-rfc/pull/4
---
 rfcs/ui-building-blocks.md | 413 +++++++++++++++++++++++++++++++++++++
 1 file changed, 413 insertions(+)
 create mode 100644 rfcs/ui-building-blocks.md

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
new file mode 100644
index 00000000..0bf88224
--- /dev/null
+++ b/rfcs/ui-building-blocks.md
@@ -0,0 +1,413 @@
+# Feature Name: `ui_building_blocks`
+
+## Summary
+
+This RFC establishes a common vocabulary, and basic data structures for UI.
+It is combined with a design pattern to manipulate UI styles ergonomically using Bevy's ECS, to tangibly demonstrate the feasibility of the approach.
+
+## Motivation
+
+UI is the next big challenge for Bevy, with a complex set of data structures that need to be stored and manipulated.
+In particular, the ability to style elements (by setting) in a reusable fashion is central to a polished, easy-to UI, but there's no immediately obvious approach to handling them.
+What makes a "style" in Bevy? How do we represent the individual style parameters? How are widgets represented? How are styles composed? How are they applied?
+
+None of these questions are terribly challenging to implement on their own, but taking the first-seen path is particularly dangerous here, due to the risk of proliferation of non-local configuration and similar-but-not-identical style parameters, as seen in CSS.
+
+We need to settle on a common standard, in order to enable interop between and establish basic building blocks that more complex UI decisions can build off of.
+
+## Guide-level explanation
+
+User interfaces in Bevy are made out of **widgets**, which are modified by the **styles** that are applied to them, and the aesthetic and functional behavior of is ultimately implemented through **UI systems**.
+
+A **widget** is a distinct part of the UI that needs its own data: be that its position, local state or any style parameters.
+Widgets in Bevy are represented by entities with a `Widget` marker component.
+
+Each widget has an associated `Styles` component, which contains a `Vec<Entity>` which points to some (possibly 0) number of **styles**, represented as entities with a `Style` marker component.
+
+Each style in that vector is applied, in order, to the widget, overriding the **style parameters** that already exist.
+Style parameters are stored as components, and serve to control some element of its presentation, such as the font, background color or text alignment.
+Style parameters can be reused across disparate widget types, with functionality achieved through systems that query for the relevant components.
+The type of the style parameter components determines which behavior it controls,
+while the value returned by `.get()` controls the final behavior of the widget.
+
+Every style parameter has both a `MyStyle<Base>` and a `MyStyle<Final>` variant, stored together on each entity.
+When creating a new style parameter, you must ensure that it implements `StyleParam`, typically achieved with `#[derive(StyleParam)]`.
+
+When working on complex games or applications, you're likely to want to group your styles into **themes**,
+automatically applying them to large groups of widgets at once.
+In Bevy, themes are applied by adding a generic system that corresponds to that theme to your app's schedule.
+Select a marker component type `W`, then add a theme system to your app with `W` as a type parameter:
+`app.add_startup_system(solarized_theme::<Button>.system())` will then create an entity that stores the solarized theme
+style parameters to your world, and adds the appropriate `Entity` reference to the end of each of the `Styles` components
+on all entities with `Widget` that have the `Button` marker component on them.
+
+Generally, you'll want to add these systems to a startup stage, but you may also find it useful to add them to various `State`s.
+This can work well for quickly toggling between various themes, like you might see in a light-dark mode.
+
+### Example: Building a Simple Widget
+
+```rust
+commands.spawn_bundle(ButtonBundle::default());
+```
+
+### Example: Building a Compound Widget
+
+```rust
+commands.spawn_bundle(ButtonBundle::default())
+  .with_children(|parent| {
+    parent.spawn_bundle(TextBundle::default())
+  });
+```
+
+### Example: Stacking Styles
+
+```rust
+// Adds two styles to `SpecialWidget` entities
+// SpecializedStyle will overwrite BaseStyle for any shared style parameters 
+// 
+// If we wanted to ensure that these styles were always associated with `SpecialWidget` 
+// even after its identity changed, we'd need to write a `Removed` system as well
+fn style_stacking(mut query: Query<&mut Styles, Added<SpecialWidget>>, 
+  base_style: Res<BaseStyle>, 
+  specialized_style: Res<SpecializedStyle>){
+  for mut styles in query.iter_mut(){
+    // styles.insert removes any matching style, then adds the style to the end of the vec
+    styles.insert(base_style.entity);
+    styles.insert(specialized_style.entity);
+  }
+}
+```
+
+### Example: Changing Style on Hover
+
+```rust
+struct Hovering(bool);
+
+fn on_hover(mut query: Query<(&IsHovered, &mut Styles), (With<OnHover>, Changed<IsHovered>)>, 
+  hover_style: Res<HoverStyle>){
+  for (is_hovered, mut styles) in query.iter_mut(){
+    match is_hovered.0 {
+      // Adds the hover style to the widget
+      true => styles.insert(hover_style.entity), 
+      // Removes the hover style from the widget, restoring its original appearance
+      false => styles.remove(hover_style.entity),
+    }
+  }
+}
+```
+
+## Reference-level explanation
+
+### Style data flow
+
+At the heart of the styling design is a data flow that propagates style parameters from the style to the end widget.
+Naively, you'd like to just overwrite the parameter in question, applying the first style's value if any, then the next and so on.
+Unfortunately, this causes issues with dynamically applying and reverting styles, because the original value is lost completely.
+
+In order to get around this, we need to somehow duplicate our data, storing both the original and final values.
+This is done by creating two variants of each style parameter component: `Foo::Base` and `Foo::Final`.
+
+This requires the `StyleParam` trait:
+
+```rust
+trait StyleParam {
+  type Inner: Clone;
+
+  type Base: Component + DerefMut + Deref<Target = Self::Inner>;
+  type Final: Component + DerefMut + Deref<Target = Self::Inner>;
+}
+```
+
+End users should use the #[style_param] attribute macro on `struct Foo(...)`, which implements the `StyleParam` trait on an ordinary-looking struct.
+Under the hood, this creates the following boilerplate:
+
+```rust
+// PhantomData and the Inner type are used to ensure Foo is !Component
+// This avoids a footgun for users trying to query for Foo directly
+struct Foo(PhantomData<*mut u8>);
+
+// Actual data goes here
+struct FooInnerStyle(...)
+
+struct FooBase(FooInnerStyle);
+struct FooFinal(FooInnerStyle);
+
+/* add impls for deref/mut for both FooBase and FooFinal */
+
+impl StyleParam for Foo {
+  // Both Base and Final should derefence to the same type of data
+  // Allowing us to convert between them
+  type Inner = FooInnerStyle;
+
+  type Base = FooBase;
+  type Final = FooFinal;
+}
+```
+
+In order for the data to be propagated from our styles to our widgets, we need a set of **style propagation systems**, that work like so:
+
+```rust
+/// Rebuilds the style parameter `S` for the widget
+///
+/// Styles need to be update if either
+/// a) the styles associated with the widget has changed or b) the style's style parameter values have changed
+/// Styles are rebuilt from scratch, working from their base value each time the styles are changed
+fn apply_styles<S:StyleParam>(mut widget_param: &mut S, style_params: Vec<Option<&S>>){  
+  // If the style is set in that style, use style_param.set() to apply it
+  // This replaces any previous values for the `final` field
+}
+
+/// Automatically updates the styling for all style parameter components of type `S` whose Styles changed
+///
+/// End users should register this system in your app using `app.add_style::<S>()
+pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S::Final, &Styles), 
+  (With<Widget, Without<Style>, Changed<Styles>>)>,
+  style_query: Query<Option<&S::Base>, With<Style>>){
+ 
+ for (widget_param, styles) in widget_query.iter_mut(){
+    let mut style_params = Vec<Option<&S::Base>>;
+
+    for style in style.iter(){
+      style_params.push(style_query.get_component::<S>());
+    }
+
+   *widget_param = apply_styles(widget_param, style_params);
+ }
+}
+
+
+/// Automatically updates the styling for all style parameter components of type `S` whose underlying style entity changed
+///
+/// End users should register this system in your app using `app.add_style::<S>()
+pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S::Final, &Styles), 
+  (With<Widget, Without<Style>>)>,
+  style_query: Query<Option<&S::Base>, (With<Style>, Changed<S::Base>>)){
+ 
+ // Implementation note: we can narrow our queries by splitting this work into two systems, despite shared logic
+ for (widget_param, styles) in widget_query.iter_mut(){
+    let mut style_params = Vec<Option<&S::Base>>;
+
+    for style in style.iter(){
+      if style_query.get(style).is_some(){
+        style_params.push(style_query.get_component::<S::Base>());
+      }
+    }
+
+   *widget_param = apply_styles(widget_param, style_params);
+ }
+}
+
+
+```
+
+Style propagation systems run every loop;
+the `Changed<Styles>` filter will prevent us from doing unnecessary work.
+
+When we call `app.add_style::<S::Base, S::Final>()`, the following steps occur:
+
+1. We add a `maintain_style::<S::Base, S::Final>` system to `CoreStage::PreUpdate`, which adds and removes the `Base` and `Final` variants of `S` to entities as needed.
+2. We add a `propagate_style_changes::<S::Base, S::Final>` system to `CoreStage::Update`.
+3. We add a `propagate_style::<S::Base, S::Final>` system to `CoreStage::Update`, which runs after the corresponding `propagate_style_changes`.
+
+This is done under the hood for all of the built-in style parameters as part of `DefaultPlugins`.
+
+### Theming systems
+
+Themes are applied to the app using **theming system**, which, when run, adds the appropriate style to the widgets with the correct component.
+Users can control the priority of the themes by controlling the relative run order of their theming systems in the usual fashion.
+
+These should be constructed ad hoc following a pair of simple examples.
+
+```rust
+pub MyTheme {
+ pub style_entity: Entity
+}
+
+/// Adds an instantiated style to all widgets with the component `M`
+pub fn my_theme<M: Component>(widget_query: Query<&mut Styles, (With<M::Final>, With<Widget>)>, theme: Res<MyTheme>){
+  for styles in widget_query.iter_mut(){
+    styles.push(theme.style_entity);
+  }
+}
+
+/// Adds the style stored in the `style_scene` to all widgets with the component `M`
+pub fn my_stored_theme<M: Component>(mut commands: Commands, 
+  widget_query: Query<Entity, (With<Styles>, With<M::Final>, With<Widget>)>, 
+  style_scene: Handle<DynamicScene>){
+
+  let widget_entities = widget_query.iter().collect();
+ 
+  // Loads in the style scene and create an entity out of it
+  // Then, pushes that entity onto the end of the `Styles` component on each of those entities 
+  commands.apply_stored_theme(style_scene, entities);
+}
+```
+
+We can apply this to construct a simple light-dark mode toggle, by combining this with app-level states:
+
+```rust
+enum LightDarkMode{
+  Light,
+  Dark
+}
+
+fn main{
+  App::build()
+    // These are automatically constructed using a FromWorld implementation that creates the appropriate entity 
+    // and stores a reference to the correct entity
+    .init_resource::<LightTheme>()
+    .init_resource::<DarkTheme>()
+    // Controls the starting state
+    .add_state(LightDarkMode::Dark)
+    .add_system_set(SystemSet::on_enter(LightDarkMode::Light).with_system(toggle_light_dark::<Widget>.system()))
+    .add_system_set(SystemSet::on_enter(LightDarkMode::Dark).with_system(toggle_light_dark::<Widget>.system()))
+}
+
+pub fn toggle_light_dark<M: Component>(
+  widget_query: Query<&mut Styles, (With<M::Final>, With<Widget>)>, 
+  light_theme: Res<LightTheme>,
+  dark_theme: Res<DarkTheme>,
+  state: Res<State<LightDarkMode>>
+){
+  let (searched, replace) = match state.active() {
+    LightDarkMode::Light => (dark_theme.style_entity, light_theme.style_entity),
+    LightDarkMode::Dark => (light_theme.style_entity, dark_theme.style_entity),
+  }
+
+  for styles in widget_query.iter_mut(){
+    // The `Styles::replace` method replaces the specified style with a new style in the same position
+    styles.replace(searched, replace);
+  }
+}
+```
+
+## Drawbacks
+
+1. Applying stored themes relies on hand-crafted `Commands` magic due to timing issues, rather than being implementable in transparent vanilla Bevy.
+2. Every style parameter component needs its own `propagate_style` and `maintain_style` systems.
+3. The type-system macro magic around `#[style_param]` is complex and mildly cursed.
+4. Implementing traits on `StyleParam` structs doesn't work in the obvious way.
+Instead of `impl MyTrait for Foo { ... }`, users must do:
+
+```rust
+impl MyTrait for FooInnerStyle { /* ... */ }
+impl MyTrait for FooBase { /* just call into FooInnerStyle */ }
+impl MyTrait for FooFinal { /* just call into FooInnerStyle */ }
+```
+
+## Rationale and alternatives
+
+### Why put your UI in the ECS?
+
+UI is not terribly performance sensitive, and often involves complex hierarchies that can be a nuisance to fit into an ECS paradigm.
+So why put it there?
+
+1. UI is a complex, but reasonably well-understood problem domain.
+By solving the problems presented for our ECS here, we can make it more useful for other gameplay patterns.
+2. Bevy's ECS is a particularly ergonomic and familiar tool for accessing specific data. Why reinvent what works?
+3. UIs will often need to change dynamically, and integrate with the game in complex ways that are hard to predict.
+By making our UI out of vanilla ECS, we can ensure that interoperability and extension are easy.
+4. The ECS provides a great tool for pre-made objects: Scenes.
+Keeping the UI in the ECS ensures we can take advantage of its features and improvements,
+enabling a data-driven workflow for UI designers and artists.
+
+### Approaches to styling
+
+Pick up a UI framework, and you'll find a new approach to styling.
+So why *this* approach?
+Let's look at some of the alternatives we should *not* take:
+
+1. **In-line styles only:** you can only configure widgets locally.
+This is, in effect, the current approach of `bevy_ui`.
+It's very explicit, but also very tedious and impossible to synchronize across a large UI.
+If we do not provide a styling solution, users will invent their own ad-hoc, forcing them to think through this design on their own and fragmenting the ecosystem.
+2. **Inherited styles:** rather than allowing for multiple styles on each widget with overwriting, we could have a single style per widget,
+and define styles in terms of inheritance from other styles.
+This results in complex inheritance trees, and results in a proliferation of styles, each of which must be named and can be reused.
+Fundamentally, this is a bad pattern because it obscures the underlying end-user logic of "like X, except...".
+3. **Cascading styles:** a widget's styles could cascade down to all other child widgets.
+This leads to more complex non-local behavior,
+requires that all widgets live within a tree,
+and is fragile if you want to move a widget out of the tree it currently lives in.
+Users can also replicate this behavior easily enough with custom systems when it is desired.
+4. **Global style priorities:** rather than defining which styles overwrite the others on each entity,
+we could give each one a "priority", and always apply them in that order.
+This is fiddly to tweak (the same challenge emerges with z-ordering in 2D applications), is harder to debug,
+and can make it very hard to get the exact behavior in special cases.
+Furthermore, this is very easily replicated by simply applying themes via systems that run in a specified order.
+5. **Widget-to-widget inheritance:** we could allow widgets to mirror the styles of other widgets.
+While conceptually simple, this will very quickly result in long and tangled web of inheritance.
+This fragile and complex anti-feature, incidentally, is a large part of the value of the `Style` marker component: to ensure that users are not presented with easy tools to tangle themselves up.
+
+In the end, this approach to styles allows for complex but ergonomic customization with the use of custom systems (ala the themes proposal),
+but still allows for simple, local reasoning about the final results.
+Simply examine the `Styles` on the entity you're attempting to debug, examine the style entities that it points to,
+and you have a complete understanding of why your widget looks the way it does.
+No endless chains or inheritance trees to walk!
+
+### Storing original style parameter values
+
+While storing old data about the style parameters complicates our design significantly,
+it is critical for managing dynamic changes in style (such as light/dark mode or hover behavior).
+Without automatically caching the value for our users on the component itself, the users (or the engine) are left to cache the state of the widgets before applying the theme on their own, then reset it.
+
+Instead of our current approach, we could instead cache the previous value of the style parameter components in a resource or a component of its own,
+using trait objects (`Box<dyn StyleParameter>`), then refer to these when restoring the original components.
+This keeps our components simpler, but is more technically challenging and dramatically more magical for end users (who will no longer be able to simply check the original value on their own).
+
+Instead of the generics pattern described in the *Reference-Level Explanation*,
+we could use getter and setter methods on the `StyleParam` trait:
+
+```rust
+trait StyleParam: Component {
+  /// The underlying value of the style parameter, unique to this particular widget
+  ///
+  /// Modifying this value is akin to applying an in-line style to your widget
+  pub fn base(&self) -> Self;  
+  /// The final value of the style parameter, which will be displayed in your app
+  ///
+  /// Obtained by succesively applying the styles found in this widget's `Styles` component,
+  /// with later styles overwriting earlier styles
+  pub fn final(&self) -> Self;  
+  /// Sets the private `final` field to val
+  ///
+  /// In typical usage, this is done automatically for you in the corresponding [propagate_style] system,
+  /// registered using `app.add_style::<S>()
+  pub fn set(&mut self, val: Self);
+}
+```
+
+This pattern is clear, and doesn't involve any fancy generics shenanigans.
+However, it makes our components larger (reducing cache efficiency), and is a shift away from Plain Old Data,
+which makes the components more complex to work with as an end user.
+
+The only other obvious existing tools we have to do so are entity (or relevant component) cloning (very hard to implement, see [#1515](https://github.com/bevyengine/bevy/issues/1515)) or scenes.
+Scenes require a large amount of boilerplate to get working right now, including on every component, and are likely to be relatively expensive.
+
+## Unresolved questions
+
+1. Can / should we use trait queries to reduce the boilerplate involved in adding new style parameters?
+2. Does the `#[style_param]` magic work? Particularly with derive macros.
+3. Should we just use two generics in `add_style`, `propagate_style` and `maintain_style` and spare the macro magic?
+4. If we're using macro magic, do we care about the `Inner` trait type to avoid the querying footgun?
+5. Do we want to hold off on implementing this until after `min_relations` to get a substantially cleaner solution?
+
+## Future work
+
+1. Eventually, we can use the `Widget` and `Style` marker components to enforce appropriate `Entity` keys in both engine and user code using [kinded entities](https://github.com/bevyengine/bevy/issues/1634).
+2. Following the introduction of [archetype invariants](https://github.com/bevyengine/bevy/issues/1481),
+an archetype invariant should be added as part of `add_style`,
+which ensures that `Base` and `Final` variants of each component always coexist on `Widget` entities.
+3. Once we have fairly advanced [relations](https://github.com/bevyengine/bevy/pull/1627) features, we should look at using them in place of `Vec<Entity>` in `Styles`.
+This is not as trivial as it might appear: `Styles` very much wants an ordered list of entity references (rather than an unordered set or numbered priority list).
+4. As alternative to the mildly cursed `#[style_param]` solution, we could use [relations](https://github.com/bevyengine/bevy/pull/1627) to duplicate the data.
+The base version of the style parameter data will be a relation with a target of a unique dummy entity, whose identity is stored in a resource.
+Then, the final version of the data is a vanilla component (a relation with no target) of the same type,
+allowing end users to query for style parameter components directly to receive the current value after all styles have been applied.
+5. Finally, in order to fully move forward on the second rendition of `bevy_ui`, we also need to solve the following other UI focus areas:
+
+   1. Widget composition.
+   2. Layout.
+   3. Wiring: call-backs, message passing.
+
+This RFC defines the underlying UI data structures, so should be settled first.

From 6d48a4772c711dedea8f507442ff3ee0e1d414ad Mon Sep 17 00:00:00 2001
From: Alice <alice.i.cecile@gmail.com>
Date: Wed, 14 Apr 2021 20:29:41 -0400
Subject: [PATCH 02/15] Fixed mismatched argument number

---
 rfcs/ui-building-blocks.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 0bf88224..94568f3e 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -164,14 +164,14 @@ pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S
   (With<Widget, Without<Style>, Changed<Styles>>)>,
   style_query: Query<Option<&S::Base>, With<Style>>){
  
- for (widget_param, styles) in widget_query.iter_mut(){
+ for (s_base, s_final, styles) in widget_query.iter_mut(){
     let mut style_params = Vec<Option<&S::Base>>;
 
     for style in style.iter(){
       style_params.push(style_query.get_component::<S>());
     }
 
-   *widget_param = apply_styles(widget_param, style_params);
+   *s_final = apply_styles(s_base, style_params);
  }
 }
 
@@ -184,7 +184,7 @@ pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base,
   style_query: Query<Option<&S::Base>, (With<Style>, Changed<S::Base>>)){
  
  // Implementation note: we can narrow our queries by splitting this work into two systems, despite shared logic
- for (widget_param, styles) in widget_query.iter_mut(){
+ for (s_base, s_final, styles) in widget_query.iter_mut(){
     let mut style_params = Vec<Option<&S::Base>>;
 
     for style in style.iter(){
@@ -193,7 +193,7 @@ pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base,
       }
     }
 
-   *widget_param = apply_styles(widget_param, style_params);
+   *s_final = apply_styles(s_base, style_params);
  }
 }
 

From 867732cd741de33316f0a26ce7ce3adada3850ed Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Thu, 15 Apr 2021 21:00:59 -0400
Subject: [PATCH 03/15] Wording cleanup

---
 rfcs/ui-building-blocks.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 94568f3e..0f595480 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -2,18 +2,18 @@
 
 ## Summary
 
-This RFC establishes a common vocabulary, and basic data structures for UI.
+This RFC establishes a common vocabulary and basic data structures for UI.
 It is combined with a design pattern to manipulate UI styles ergonomically using Bevy's ECS, to tangibly demonstrate the feasibility of the approach.
 
 ## Motivation
 
 UI is the next big challenge for Bevy, with a complex set of data structures that need to be stored and manipulated.
-In particular, the ability to style elements (by setting) in a reusable fashion is central to a polished, easy-to UI, but there's no immediately obvious approach to handling them.
+In particular, the ability to style elements in a reusable fashion is central to a polished, easy-to UI, but there's no immediately obvious approach to handling this.
 What makes a "style" in Bevy? How do we represent the individual style parameters? How are widgets represented? How are styles composed? How are they applied?
 
 None of these questions are terribly challenging to implement on their own, but taking the first-seen path is particularly dangerous here, due to the risk of proliferation of non-local configuration and similar-but-not-identical style parameters, as seen in CSS.
 
-We need to settle on a common standard, in order to enable interop between and establish basic building blocks that more complex UI decisions can build off of.
+We need to settle on a common standard, in order to enable interop between UI crates and establish the basic building blocks that more complex UI decisions can build off of.
 
 ## Guide-level explanation
 

From 85e6267d84cf29f48e2ab51dd2b4d1a66b8002c5 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Fri, 16 Apr 2021 16:53:07 -0400
Subject: [PATCH 04/15] Sticking to .insert for now

---
 rfcs/ui-building-blocks.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 0f595480..8e39e39b 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -168,7 +168,7 @@ pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S
     let mut style_params = Vec<Option<&S::Base>>;
 
     for style in style.iter(){
-      style_params.push(style_query.get_component::<S>());
+      style_params.insert(style_query.get_component::<S>());
     }
 
    *s_final = apply_styles(s_base, style_params);
@@ -189,7 +189,7 @@ pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base,
 
     for style in style.iter(){
       if style_query.get(style).is_some(){
-        style_params.push(style_query.get_component::<S::Base>());
+        style_params.insert(style_query.get_component::<S::Base>());
       }
     }
 

From a72c0a9c02cf1f2591cffb4d8dc6629c84d88c3a Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Fri, 16 Apr 2021 16:55:57 -0400
Subject: [PATCH 05/15] Added commands convenience API

Credit to @jihiggins for the suggestion
---
 rfcs/ui-building-blocks.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 8e39e39b..9663192b 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -33,6 +33,12 @@ while the value returned by `.get()` controls the final behavior of the widget.
 Every style parameter has both a `MyStyle<Base>` and a `MyStyle<Final>` variant, stored together on each entity.
 When creating a new style parameter, you must ensure that it implements `StyleParam`, typically achieved with `#[derive(StyleParam)]`.
 
+Styles can be modified directly, by modifying the `Styles` component of the widgets you wish to modify.
+When spawning entities, you may find it convenient to work with the relevant `EntityCommands` methods instead
+to reduce the number of function parameters your systems need.
+Pass in the type of your resource(s) that implements the `StyleResource` trait as type parameters, and the next time commands are processed,
+the entity stored in that resource will be added to (or removed from) the `Styles` component of your widget entity.
+
 When working on complex games or applications, you're likely to want to group your styles into **themes**,
 automatically applying them to large groups of widgets at once.
 In Bevy, themes are applied by adding a generic system that corresponds to that theme to your app's schedule.
@@ -47,15 +53,15 @@ This can work well for quickly toggling between various themes, like you might s
 ### Example: Building a Simple Widget
 
 ```rust
-commands.spawn_bundle(ButtonBundle::default());
+commands.spawn_bundle(ButtonBundle::default()).add_style::<BoldStyle>();
 ```
 
 ### Example: Building a Compound Widget
 
 ```rust
-commands.spawn_bundle(ButtonBundle::default())
+commands.spawn_bundle(ButtonBundle::default()).add_style::<BoldStyle>()
   .with_children(|parent| {
-    parent.spawn_bundle(TextBundle::default())
+    parent.spawn_bundle(TextBundle::default()).replace_style::<BoldStyle, SubtleStyle>()
   });
 ```
 

From 76239d441aa873975e80f3a7931850096709c3e2 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Fri, 16 Apr 2021 17:00:23 -0400
Subject: [PATCH 06/15] Noted fragmentation issue of UI

---
 rfcs/ui-building-blocks.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 9663192b..fe44e7e8 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -305,7 +305,8 @@ impl MyTrait for FooFinal { /* just call into FooInnerStyle */ }
 
 ### Why put your UI in the ECS?
 
-UI is not terribly performance sensitive, and often involves complex hierarchies that can be a nuisance to fit into an ECS paradigm.
+UI is not terribly performance sensitive, tends to be deeply fragmented,
+and often involves complex hierarchies that can be a nuisance to fit into an ECS paradigm.
 So why put it there?
 
 1. UI is a complex, but reasonably well-understood problem domain.

From 7cbc9a160932b77b234257cc7da94795d5c58e8e Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Fri, 16 Apr 2021 17:00:43 -0400
Subject: [PATCH 07/15] Linked to #11

---
 rfcs/ui-building-blocks.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index fe44e7e8..f508ceda 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -415,6 +415,6 @@ allowing end users to query for style parameter components directly to receive t
 
    1. Widget composition.
    2. Layout.
-   3. Wiring: call-backs, message passing.
+   3. Wiring: call-backs, message passing (see #11).
 
 This RFC defines the underlying UI data structures, so should be settled first.

From d02b39ad0b863d4d991c3caef9b5e68537f36712 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Tue, 20 Apr 2021 17:54:10 -0400
Subject: [PATCH 08/15] Added "Why not just integrate another UI solution"?

---
 rfcs/ui-building-blocks.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index f508ceda..eadace57 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -318,6 +318,32 @@ By making our UI out of vanilla ECS, we can ensure that interoperability and ext
 Keeping the UI in the ECS ensures we can take advantage of its features and improvements,
 enabling a data-driven workflow for UI designers and artists.
 
+### Why not just integrate another UI solution?
+
+Many other game engines and similar GUI tools simply integrate directly into an existing UI framework, commonly the web stack of CSS / HTML / JS.
+This has obvious advantages, namely:
+
+1. It is already built: we could hypothetically save a lot of development effort rather than reimplementing all of the various algorithms and widgets.
+2. It's already proven: such an approach is already used in other engines and AAA games.
+3. Many developers already know how to use the tools, and great learning materials exist.
+
+However, it also comes with serious disadvantages:
+
+1. When designing UIs for games, it is often *very* unclear where gameplay ends and UI begins. Using an external UI library would force a hard separation between the two, resulting in users attempting to do UI-like tasks in the ECS anyways but with minimal support or guidance.
+2. Translating data in and out of the ECS is very common. While a model-view separation may be a useful architecture for maintainability, this translation process is necessarily fairly challenging, resulting in an extended API surface area to learn and maintain and creating boilerplate whenever the boundary is crossed.
+3. Ensuring interoperability is a serious development cost, both upfront and on an ongoing basis.
+4. It greatly increases our dependencies, increasing the churn we must deal with, risking cross-platform compatibility, worsening compile times and possibly increasing binary sizes.
+5. We are beholden to the whims of the larger UI framework we are depending on, and cannot adapt it to fit our needs without forking.
+6. The most commonly known UI framework (the web stack) has serious issues with its spec due to backwards compatibility demands and messy inheritance.
+7. Adding a separate UI solution increases the burden of learning a new tool for all users who are *not* familiar with it already. These users are typically more novice than those coming from an established development career, and can be easily overwhelmed by trying to navigate a complex integration.
+
+Overall, we feel that the disadvantages of doing so outweigh the advantages, even in the short-term.
+Of course, we will be learning and borrowing from existing frameworks aggressively, on both a conceptual and implementation level.
+Like with the rest of Bevy's development, if you feel there are important conceptual lessons we've missed, please join the conversation!
+
+Finally, there's nothing inherent about `bevy_ui` due to Bevy's modular design.
+Integration with other UI frameworks (like the popular nascent [`bevy_egui`](https://crates.io/crates/bevy_egui) crate) is fully possible from an external perspective; we should ensure that this remains feasible for others who wish to use a different stack.
+
 ### Approaches to styling
 
 Pick up a UI framework, and you'll find a new approach to styling.

From c9d5cf20adc98087128d1fa3ba44895b5f0c1544 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Tue, 20 Apr 2021 18:24:57 -0400
Subject: [PATCH 09/15] Added a section to record drawbacks of tightly coupling
 UI and logic

---
 rfcs/ui-building-blocks.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index eadace57..218d617d 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -289,6 +289,14 @@ pub fn toggle_light_dark<M: Component>(
 
 ## Drawbacks
 
+Conceptual concerns:
+
+1. Tightly integrating UI and game state make it harder to split out alternative declarative versions of the UI.
+This is valuable for handling alternative resolutions, input devices and languages.
+We need to carefully design for this from the start, and ensure that as much of this can be handled automatically as possible.
+
+Implementation concerns:
+
 1. Applying stored themes relies on hand-crafted `Commands` magic due to timing issues, rather than being implementable in transparent vanilla Bevy.
 2. Every style parameter component needs its own `propagate_style` and `maintain_style` systems.
 3. The type-system macro magic around `#[style_param]` is complex and mildly cursed.

From 884629e917e15d731c8d94c5f7396ab2d977593f Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Tue, 20 Apr 2021 23:54:03 -0400
Subject: [PATCH 10/15] Not using web stack as a competitive advantage

---
 rfcs/ui-building-blocks.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 218d617d..67ad557d 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -344,6 +344,7 @@ However, it also comes with serious disadvantages:
 5. We are beholden to the whims of the larger UI framework we are depending on, and cannot adapt it to fit our needs without forking.
 6. The most commonly known UI framework (the web stack) has serious issues with its spec due to backwards compatibility demands and messy inheritance.
 7. Adding a separate UI solution increases the burden of learning a new tool for all users who are *not* familiar with it already. These users are typically more novice than those coming from an established development career, and can be easily overwhelmed by trying to navigate a complex integration.
+8. Not using an external UI framework (and in particular not using HTML + CSS) is a serious differentiator and competitive advantage for Bevy. The web stack is a polarizing topic, but users who prefer it have many other fine options. We should target the underserved niche, much as we do by writing Bevy in Rust, rather than C++.
 
 Overall, we feel that the disadvantages of doing so outweigh the advantages, even in the short-term.
 Of course, we will be learning and borrowing from existing frameworks aggressively, on both a conceptual and implementation level.

From f188e9015cc7595218647e44a18a33665039ad58 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Wed, 21 Apr 2021 00:10:03 -0400
Subject: [PATCH 11/15] Three marker components that define UI

Screenspace, Layout, Widget
---
 rfcs/ui-building-blocks.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 67ad557d..89e06a1a 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -17,6 +17,20 @@ We need to settle on a common standard, in order to enable interop between UI cr
 
 ## Guide-level explanation
 
+At heart, user interfaces (UI) in Bevy are "just another part of the game".
+It's built out of the same core primitives that you'll see when building your game logic: entities, components, systems, scenes, events and so on.
+That however doesn't mean it's a complete free-for-all: `bevy_ui` defines several built-in components, systems and design patterns
+to make working with UI ergonomic, maintainable and interoperable without making it any harder to extend or hook into.
+
+Commonly, UI is defined by three core components, each controlling a certain type of behavior:
+
+1. `ScreenSpace`, which dictates that an entity's transform should be drawn relative to the player's screen, rather than the world.
+2. `Layout`, which when present controls exactly how Bevy's built-in layout systems will control the details of its positioning relative to other `Layout` entities.
+3. `Widget`, a general purpose marker component that designates an entity as "part of the UI".
+
+Each of these can be added separately, although every entity that makes up a classical UI will have all three.
+For example, if you wanted to have a world-space UI as commonly seen in XR applications, you'd remove the `ScreenSpace` marker component while keeping the others.
+
 User interfaces in Bevy are made out of **widgets**, which are modified by the **styles** that are applied to them, and the aesthetic and functional behavior of is ultimately implemented through **UI systems**.
 
 A **widget** is a distinct part of the UI that needs its own data: be that its position, local state or any style parameters.
@@ -334,6 +348,7 @@ This has obvious advantages, namely:
 1. It is already built: we could hypothetically save a lot of development effort rather than reimplementing all of the various algorithms and widgets.
 2. It's already proven: such an approach is already used in other engines and AAA games.
 3. Many developers already know how to use the tools, and great learning materials exist.
+4. If we closely followed an existing spec we could allow the use of other design tools to create UIs for Bevy with a data-driven workflow.
 
 However, it also comes with serious disadvantages:
 

From 7f7cd807d3c892ad15dce6a9177fbecc8c722c3f Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Wed, 21 Apr 2021 00:15:19 -0400
Subject: [PATCH 12/15] Improved marker component explanations

---
 rfcs/ui-building-blocks.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 89e06a1a..5ac62fbb 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -25,11 +25,13 @@ to make working with UI ergonomic, maintainable and interoperable without making
 Commonly, UI is defined by three core components, each controlling a certain type of behavior:
 
 1. `ScreenSpace`, which dictates that an entity's transform should be drawn relative to the player's screen, rather than the world.
-2. `Layout`, which when present controls exactly how Bevy's built-in layout systems will control the details of its positioning relative to other `Layout` entities.
+Entities with the `ScreenSpace` component are drawn by the UI camera; all others are drawn with ordinary cameras.
+2. `Layout`, which tells Bevy's built-in layout systems to control its positioning relative to other `Layout` entities.
+The values of this component's fields determine exactly how this is done.
 3. `Widget`, a general purpose marker component that designates an entity as "part of the UI".
 
 Each of these can be added separately, although every entity that makes up a classical UI will have all three.
-For example, if you wanted to have a world-space UI as commonly seen in XR applications, you'd remove the `ScreenSpace` marker component while keeping the others.
+For example, if you wanted to have a world-space UI as commonly seen in XR applications, you'd remove the `ScreenSpace` marker component while keeping `Layout` and `Widget`.
 
 User interfaces in Bevy are made out of **widgets**, which are modified by the **styles** that are applied to them, and the aesthetic and functional behavior of is ultimately implemented through **UI systems**.
 

From 19887673e932ab677a6031f03d094f6f4bfedeb8 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Wed, 21 Apr 2021 00:21:48 -0400
Subject: [PATCH 13/15] Opened up styling to arbitrary use cases

Credit to @anchpop for this idea!
---
 rfcs/ui-building-blocks.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index 5ac62fbb..b01a3ffa 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -183,7 +183,7 @@ fn apply_styles<S:StyleParam>(mut widget_param: &mut S, style_params: Vec<Option
 ///
 /// End users should register this system in your app using `app.add_style::<S>()
 pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S::Final, &Styles), 
-  (With<Widget, Without<Style>, Changed<Styles>>)>,
+  (Without<Style>, Changed<Styles>)>,
   style_query: Query<Option<&S::Base>, With<Style>>){
  
  for (s_base, s_final, styles) in widget_query.iter_mut(){
@@ -202,8 +202,8 @@ pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S
 ///
 /// End users should register this system in your app using `app.add_style::<S>()
 pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S::Final, &Styles), 
-  (With<Widget, Without<Style>>)>,
-  style_query: Query<Option<&S::Base>, (With<Style>, Changed<S::Base>>)){
+  Without<Style>)>,
+  style_query: Query<Option<&S::Base>, (With<Style>, Changed<S::Base>)>{
  
  // Implementation note: we can narrow our queries by splitting this work into two systems, despite shared logic
  for (s_base, s_final, styles) in widget_query.iter_mut(){
@@ -218,8 +218,6 @@ pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base,
    *s_final = apply_styles(s_base, style_params);
  }
 }
-
-
 ```
 
 Style propagation systems run every loop;
@@ -463,10 +461,10 @@ This is not as trivial as it might appear: `Styles` very much wants an ordered l
 The base version of the style parameter data will be a relation with a target of a unique dummy entity, whose identity is stored in a resource.
 Then, the final version of the data is a vanilla component (a relation with no target) of the same type,
 allowing end users to query for style parameter components directly to receive the current value after all styles have been applied.
-5. Finally, in order to fully move forward on the second rendition of `bevy_ui`, we also need to solve the following other UI focus areas:
+5. Nothing in the styling system limits its use to widgets alone. This opens up opportunities to use the same code and design patterns to game logic, meshes and so on. It hasn't been discussed above due to scope, but it's a powerful tool for end users.
+6. Finally, in order to fully move forward on the second rendition of `bevy_ui`, we also need to solve the following other UI focus areas:
 
-   1. Widget composition.
-   2. Layout.
-   3. Wiring: call-backs, message passing (see #11).
+   1. Layout.
+   2. Wiring: call-backs, message passing (see #11).
 
 This RFC defines the underlying UI data structures, so should be settled first.

From 086c3c8a6b34350b77651cab0833f9796f1b37b0 Mon Sep 17 00:00:00 2001
From: Alice Cecile <alice.i.cecile@gmail.com>
Date: Wed, 21 Apr 2021 01:17:57 -0400
Subject: [PATCH 14/15] Clarified what the `Widget` marker should do

---
 rfcs/ui-building-blocks.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index b01a3ffa..dff6865d 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -29,6 +29,8 @@ Entities with the `ScreenSpace` component are drawn by the UI camera; all others
 2. `Layout`, which tells Bevy's built-in layout systems to control its positioning relative to other `Layout` entities.
 The values of this component's fields determine exactly how this is done.
 3. `Widget`, a general purpose marker component that designates an entity as "part of the UI".
+All entities that make up the UI should have this marker, whether it's visual (like a button) or abstract (like a layout box).
+This has no innate behavior; instead it serves as an easy hook for user code and an identifier for the editor.
 
 Each of these can be added separately, although every entity that makes up a classical UI will have all three.
 For example, if you wanted to have a world-space UI as commonly seen in XR applications, you'd remove the `ScreenSpace` marker component while keeping `Layout` and `Widget`.

From 2bdb2c0cf0eeeeb5da1afce338ab9805d69a6638 Mon Sep 17 00:00:00 2001
From: Alice <alice.i.cecile@gmail.com>
Date: Sat, 24 Apr 2021 17:09:35 -0400
Subject: [PATCH 15/15] Renamed style parameters to attributes

Credit to @ColePorier
---
 rfcs/ui-building-blocks.md | 60 +++++++++++++++++++-------------------
 1 file changed, 30 insertions(+), 30 deletions(-)

diff --git a/rfcs/ui-building-blocks.md b/rfcs/ui-building-blocks.md
index dff6865d..8a880198 100644
--- a/rfcs/ui-building-blocks.md
+++ b/rfcs/ui-building-blocks.md
@@ -9,9 +9,9 @@ It is combined with a design pattern to manipulate UI styles ergonomically using
 
 UI is the next big challenge for Bevy, with a complex set of data structures that need to be stored and manipulated.
 In particular, the ability to style elements in a reusable fashion is central to a polished, easy-to UI, but there's no immediately obvious approach to handling this.
-What makes a "style" in Bevy? How do we represent the individual style parameters? How are widgets represented? How are styles composed? How are they applied?
+What makes a "style" in Bevy? How do we represent the individual attributes? How are widgets represented? How are styles composed? How are they applied?
 
-None of these questions are terribly challenging to implement on their own, but taking the first-seen path is particularly dangerous here, due to the risk of proliferation of non-local configuration and similar-but-not-identical style parameters, as seen in CSS.
+None of these questions are terribly challenging to implement on their own, but taking the first-seen path is particularly dangerous here, due to the risk of proliferation of non-local configuration and similar-but-not-identical attributes, as seen in CSS.
 
 We need to settle on a common standard, in order to enable interop between UI crates and establish the basic building blocks that more complex UI decisions can build off of.
 
@@ -37,19 +37,19 @@ For example, if you wanted to have a world-space UI as commonly seen in XR appli
 
 User interfaces in Bevy are made out of **widgets**, which are modified by the **styles** that are applied to them, and the aesthetic and functional behavior of is ultimately implemented through **UI systems**.
 
-A **widget** is a distinct part of the UI that needs its own data: be that its position, local state or any style parameters.
+A **widget** is a distinct part of the UI that needs its own data: be that its position, local state or any attributes.
 Widgets in Bevy are represented by entities with a `Widget` marker component.
 
 Each widget has an associated `Styles` component, which contains a `Vec<Entity>` which points to some (possibly 0) number of **styles**, represented as entities with a `Style` marker component.
 
-Each style in that vector is applied, in order, to the widget, overriding the **style parameters** that already exist.
-Style parameters are stored as components, and serve to control some element of its presentation, such as the font, background color or text alignment.
-Style parameters can be reused across disparate widget types, with functionality achieved through systems that query for the relevant components.
-The type of the style parameter components determines which behavior it controls,
+Each style in that vector is applied, in order, to the widget, overriding the **attributes** that already exist.
+attributes are stored as components, and serve to control some element of its presentation, such as the font, background color or text alignment.
+attributes can be reused across disparate widget types, with functionality achieved through systems that query for the relevant components.
+The type of the attribute components determines which behavior it controls,
 while the value returned by `.get()` controls the final behavior of the widget.
 
-Every style parameter has both a `MyStyle<Base>` and a `MyStyle<Final>` variant, stored together on each entity.
-When creating a new style parameter, you must ensure that it implements `StyleParam`, typically achieved with `#[derive(StyleParam)]`.
+Every attribute has both a `MyStyle<Base>` and a `MyStyle<Final>` variant, stored together on each entity.
+When creating a new attribute, you must ensure that it implements `StyleParam`, typically achieved with `#[derive(StyleParam)]`.
 
 Styles can be modified directly, by modifying the `Styles` component of the widgets you wish to modify.
 When spawning entities, you may find it convenient to work with the relevant `EntityCommands` methods instead
@@ -62,7 +62,7 @@ automatically applying them to large groups of widgets at once.
 In Bevy, themes are applied by adding a generic system that corresponds to that theme to your app's schedule.
 Select a marker component type `W`, then add a theme system to your app with `W` as a type parameter:
 `app.add_startup_system(solarized_theme::<Button>.system())` will then create an entity that stores the solarized theme
-style parameters to your world, and adds the appropriate `Entity` reference to the end of each of the `Styles` components
+attributes to your world, and adds the appropriate `Entity` reference to the end of each of the `Styles` components
 on all entities with `Widget` that have the `Button` marker component on them.
 
 Generally, you'll want to add these systems to a startup stage, but you may also find it useful to add them to various `State`s.
@@ -87,7 +87,7 @@ commands.spawn_bundle(ButtonBundle::default()).add_style::<BoldStyle>()
 
 ```rust
 // Adds two styles to `SpecialWidget` entities
-// SpecializedStyle will overwrite BaseStyle for any shared style parameters 
+// SpecializedStyle will overwrite BaseStyle for any shared attributes 
 // 
 // If we wanted to ensure that these styles were always associated with `SpecialWidget` 
 // even after its identity changed, we'd need to write a `Removed` system as well
@@ -124,12 +124,12 @@ fn on_hover(mut query: Query<(&IsHovered, &mut Styles), (With<OnHover>, Changed<
 
 ### Style data flow
 
-At the heart of the styling design is a data flow that propagates style parameters from the style to the end widget.
-Naively, you'd like to just overwrite the parameter in question, applying the first style's value if any, then the next and so on.
+At the heart of the styling design is a data flow that propagates attributes from the style to the end widget.
+Naively, you'd like to just overwrite the attribute in question, applying the first style's value if any, then the next and so on.
 Unfortunately, this causes issues with dynamically applying and reverting styles, because the original value is lost completely.
 
 In order to get around this, we need to somehow duplicate our data, storing both the original and final values.
-This is done by creating two variants of each style parameter component: `Foo::Base` and `Foo::Final`.
+This is done by creating two variants of each attribute component: `Foo::Base` and `Foo::Final`.
 
 This requires the `StyleParam` trait:
 
@@ -171,17 +171,17 @@ impl StyleParam for Foo {
 In order for the data to be propagated from our styles to our widgets, we need a set of **style propagation systems**, that work like so:
 
 ```rust
-/// Rebuilds the style parameter `S` for the widget
+/// Rebuilds the attribute `S` for the widget
 ///
 /// Styles need to be update if either
-/// a) the styles associated with the widget has changed or b) the style's style parameter values have changed
+/// a) the styles associated with the widget has changed or b) the style's attribute values have changed
 /// Styles are rebuilt from scratch, working from their base value each time the styles are changed
 fn apply_styles<S:StyleParam>(mut widget_param: &mut S, style_params: Vec<Option<&S>>){  
   // If the style is set in that style, use style_param.set() to apply it
   // This replaces any previous values for the `final` field
 }
 
-/// Automatically updates the styling for all style parameter components of type `S` whose Styles changed
+/// Automatically updates the styling for all attribute components of type `S` whose Styles changed
 ///
 /// End users should register this system in your app using `app.add_style::<S>()
 pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S::Final, &Styles), 
@@ -200,7 +200,7 @@ pub fn propagate_styles<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S
 }
 
 
-/// Automatically updates the styling for all style parameter components of type `S` whose underlying style entity changed
+/// Automatically updates the styling for all attribute components of type `S` whose underlying style entity changed
 ///
 /// End users should register this system in your app using `app.add_style::<S>()
 pub fn propagate_style_changes<S: StyleParam>(mut widget_query: Query<(&S::Base, &mut S::Final, &Styles), 
@@ -231,7 +231,7 @@ When we call `app.add_style::<S::Base, S::Final>()`, the following steps occur:
 2. We add a `propagate_style_changes::<S::Base, S::Final>` system to `CoreStage::Update`.
 3. We add a `propagate_style::<S::Base, S::Final>` system to `CoreStage::Update`, which runs after the corresponding `propagate_style_changes`.
 
-This is done under the hood for all of the built-in style parameters as part of `DefaultPlugins`.
+This is done under the hood for all of the built-in attributes as part of `DefaultPlugins`.
 
 ### Theming systems
 
@@ -314,7 +314,7 @@ We need to carefully design for this from the start, and ensure that as much of
 Implementation concerns:
 
 1. Applying stored themes relies on hand-crafted `Commands` magic due to timing issues, rather than being implementable in transparent vanilla Bevy.
-2. Every style parameter component needs its own `propagate_style` and `maintain_style` systems.
+2. Every attribute component needs its own `propagate_style` and `maintain_style` systems.
 3. The type-system macro magic around `#[style_param]` is complex and mildly cursed.
 4. Implementing traits on `StyleParam` structs doesn't work in the obvious way.
 Instead of `impl MyTrait for Foo { ... }`, users must do:
@@ -404,26 +404,26 @@ Simply examine the `Styles` on the entity you're attempting to debug, examine th
 and you have a complete understanding of why your widget looks the way it does.
 No endless chains or inheritance trees to walk!
 
-### Storing original style parameter values
+### Storing original attribute values
 
-While storing old data about the style parameters complicates our design significantly,
+While storing old data about the attributes complicates our design significantly,
 it is critical for managing dynamic changes in style (such as light/dark mode or hover behavior).
 Without automatically caching the value for our users on the component itself, the users (or the engine) are left to cache the state of the widgets before applying the theme on their own, then reset it.
 
-Instead of our current approach, we could instead cache the previous value of the style parameter components in a resource or a component of its own,
-using trait objects (`Box<dyn StyleParameter>`), then refer to these when restoring the original components.
+Instead of our current approach, we could instead cache the previous value of the attribute components in a resource or a component of its own,
+using trait objects (`Box<dyn StyleAttribute>`), then refer to these when restoring the original components.
 This keeps our components simpler, but is more technically challenging and dramatically more magical for end users (who will no longer be able to simply check the original value on their own).
 
 Instead of the generics pattern described in the *Reference-Level Explanation*,
-we could use getter and setter methods on the `StyleParam` trait:
+we could use getter and setter methods on the `StyleAttribute` trait:
 
 ```rust
 trait StyleParam: Component {
-  /// The underlying value of the style parameter, unique to this particular widget
+  /// The underlying value of the attribute, unique to this particular widget
   ///
   /// Modifying this value is akin to applying an in-line style to your widget
   pub fn base(&self) -> Self;  
-  /// The final value of the style parameter, which will be displayed in your app
+  /// The final value of the attribute, which will be displayed in your app
   ///
   /// Obtained by succesively applying the styles found in this widget's `Styles` component,
   /// with later styles overwriting earlier styles
@@ -445,7 +445,7 @@ Scenes require a large amount of boilerplate to get working right now, including
 
 ## Unresolved questions
 
-1. Can / should we use trait queries to reduce the boilerplate involved in adding new style parameters?
+1. Can / should we use trait queries to reduce the boilerplate involved in adding new attributes?
 2. Does the `#[style_param]` magic work? Particularly with derive macros.
 3. Should we just use two generics in `add_style`, `propagate_style` and `maintain_style` and spare the macro magic?
 4. If we're using macro magic, do we care about the `Inner` trait type to avoid the querying footgun?
@@ -460,9 +460,9 @@ which ensures that `Base` and `Final` variants of each component always coexist
 3. Once we have fairly advanced [relations](https://github.com/bevyengine/bevy/pull/1627) features, we should look at using them in place of `Vec<Entity>` in `Styles`.
 This is not as trivial as it might appear: `Styles` very much wants an ordered list of entity references (rather than an unordered set or numbered priority list).
 4. As alternative to the mildly cursed `#[style_param]` solution, we could use [relations](https://github.com/bevyengine/bevy/pull/1627) to duplicate the data.
-The base version of the style parameter data will be a relation with a target of a unique dummy entity, whose identity is stored in a resource.
+The base version of the attribute data will be a relation with a target of a unique dummy entity, whose identity is stored in a resource.
 Then, the final version of the data is a vanilla component (a relation with no target) of the same type,
-allowing end users to query for style parameter components directly to receive the current value after all styles have been applied.
+allowing end users to query for attribute components directly to receive the current value after all styles have been applied.
 5. Nothing in the styling system limits its use to widgets alone. This opens up opportunities to use the same code and design patterns to game logic, meshes and so on. It hasn't been discussed above due to scope, but it's a powerful tool for end users.
 6. Finally, in order to fully move forward on the second rendition of `bevy_ui`, we also need to solve the following other UI focus areas: