diff --git a/docs/framework/builder-basics.mdx b/docs/framework/builder-basics.mdx
index 6c215d857..8b5f97151 100644
--- a/docs/framework/builder-basics.mdx
+++ b/docs/framework/builder-basics.mdx
@@ -2,134 +2,178 @@
title: "Builder basics"
---
-Framework Builder works as an overlay of the running app; you edit your app while it's running. It gives you an accurate representation of what the app will look like and how it'll behave, without the need to constantly preview it. Changes to the user interface are automatically saved into `.wf/` folders.
+Writer Framework Builder’s interface is an overlay on top of the running app, which allows you to edit your app while it’s running. This approach gives you an accurate representation of how the app will look and behave without the need to constantly preview it.
-## Modes
+## Writer Framework Builder’s modes
-You can switch modes between _User Interface_, _Code_ and _Preview_ using the buttons on the top bar.
+Writer Framework Builder has two modes:
-### User Interface
+1. **UI mode:** This is the default mode, which provides an overlay of tools for building and editing the user interface. The app still runs in UI mode, allowing to you test its functionality while you’re building it. You can also edit the app’s code and view its log.
-
+
-The default mode. Allows you to focus on building the interface.
+2. **Preview mode:** This mode lets you preview the application, experiencing it almost as your end users would. The tool overlay is hidden, but you can still edit the app’s code and view its log in this mode.
-### Code
+
-
+You can switch between UI mode and Preview mode by using the **UI**/**Preview** selector near the upper left corner of the page.
-This mode displays the **code editor** and the **application log**, while still allowing you to access the _Component Tree_ and _Settings_.
+
-
-
-
- Code changes are automatically detected. The application will reload whenever a change to a `.py` file inside the app folder is detected. This feature only works in Framework Builder i.e. `edit` mode, not when running the app in `run` mode.
-
- The built-in code editor for `main.py`, the entry point of your application. This editor is provided for convenience and is ideal for quick edits — but you don't need to rely on it. If you need a more powerful editor or if your codebase is distributed across several files, use a local editor.
-
-
- Exceptions raised by your application are shown here, as log entries. Standard output from your application is also captured and displayed as log entries.
-
-
+## Building your app in UI mode
+
+### The different areas of UI mode
+
+In UI mode, Writer Framework Builder’s page is divided into these areas:
+
+
+
+1. **Canvas:** This is where you lay out components to build your app’s user interface. It displays the UI as your users will see it.
+2. **Core toolkit:** A “palette” of UI components that can be added to your app’s user interface. To add a component to your app’s UI, drag it onto the Canvas or into the Component tree.
+3. **Component tree:** This provides an alternative way to view your app’s user interface: as a hierarchical tree structure. It’s useful for ensuring that UI components are located in the right place or in the correct container object, and is handy for selecting UI components in complex layouts.
+4. **Component settings:** This panel lets you view and edit the settings for the currently selected UI component. You can hide the Component settings panel if you need more screen space to work on the Canvas.
+5. **Top bar:** Contains the “high level” editing controls: switching between UI and Preview mode, undoing and redoing the most recent change to the UI, and viewing the application’s state.
+6. **Bottom bar:** Contains the “low level” editing controls, which toggle the Code and Log panels.
-### Preview
+### Defining your app’s user interface
-
+Writer Framework Builder provides a selection of over 50 UI components that you can use to build your app’s user interface:
-The _Preview_ mode shows the application exactly like the user will see it. It allocates the whole width of the viewport to the app.
+
-## Adding and moving components
-You can create new components in your app by dragging and dropping items from the Toolkit. Some components, like Sections, can act as parents, while others, such as Text, cannot. Additionally, certain components have placement restrictions—for instance, a Column must be added to a Column Container, and a Sidebar can only be added to a Page.
+You define your app’s user interface by dragging components from the Core toolkit and dropping them either onto the Canvas or into the Component tree (remember, the Canvas and Component tree provide different ways to look at your app’s user interface). If you simply drag and drop a UI component onto an empty spot on the Canvas, it will be placed at the “end,” below all other UI components in the user interface. To place a UI component at a specific location, drag them over the desired location or parent component until you see the insertion lines.
-By default, components are positioned at the end, but if you need to place them specifically, simply drag them over the desired parent until you see the insertion lines. You can also reorganize existing components by moving them between parents or within the same parent. For more flexibility, the Component Tree can serve both as a source or a destination for your drag and drop actions.
+
-## Selecting a component
-Select a component by clicking on it. If you click on a component that's already selected, the click will be treated as an interaction with the app. Two things will happen when a component is selected:
+It can sometimes be difficult to find the component you’re looking for, so the Core toolkit has a search field. You can use it to find the narrow down the list of components or find a specific one.
-
-
- The _Component Settings_ panel will open on the right. Depending on available screen real estate, the panel may open on top of the app or next to it.
-
-
- A set of component-specific actions, _Component Shortcuts_, will be displayed on top of the component.
-
-
+
-## Component settings
+Some UI components, such as Section, can act as “parents,” which are UI components that can contain other UI components. Others, such as Text, cannot. Additionally, certain components have placement restrictions — for instance, a Column must be added to a Column Container, and a Sidebar can only be added to a Page.
-Settings are divided into the following sections. Changes to settings can be undone and redone using the buttons on the top bar.
+
-
+The Component tree provides a hierarchical view of your app’s user interface. It shows the top-down layout of UI components in your app, as well as the parent-child relationships between components, making it easier to understand your app’s structure and ensure that components are correctly nested.
+
+You will find the Component tree useful when trying to reorganize the order of components in the UI, especially those located inside a parent UI component. For more flexibility and finer control, you can use the Component tree as a source or a destination for your drag and drop actions.
+
+### Discovering components
+
+The Builder is designed to allow easy discoverability of components. Rather than scouring specifications every time you need to use a component, you can rely on the visual editor to guide you.
+
+1. **Short description:** You can hover on the component type to get a tooltip with a short description.
+2. **Available properties and events:** Looking at _Settings_ will allow you to see which of its properties are configurable.
+3. **Built-in docs:** Components have short docs built into them. You can expand it by clicking the help icon in Settings.
+4. **Event handler stub code:** Different events need to be handled differently. The built-in stub handlers, which can be found next to each event, can help you get started when writing event handlers.
+
+### Selecting and editing components
+
+To move or edit a component in your UI, you need to select it first. You can do this by clicking on the component either in the Canvas or in the Component tree. The selected component will be highlighted in both the Canvas and Component tree.
+
+
+
+Selecting a UI component will allow you to view and edit its settings in the Component settings panel on the right side of the page.
+
+
+
+To hide the Component settings panel to get a better view of the Canvas, click on **»** in the button bar. To show the panel, click on **⚙** in the button bar.
+
+
+
+The settings in the Component settings panel are divided into the following sections:
-
- Divided into _General_ and _Style_ categories. Values can include:
+
+ 
+
+ These settings are divided into two categores:
+
+ 1. **General**, which specifies the component’s content
+ 2. **Style**, which defines the component’s appearance.
+
+ Values for these settings can include:
1. Literals, e.g. `monkey`
2. References to application state using the template syntax `@{}`, e.g. `@{my_favourite_animal}`.
3. A combination of both, e.g. `My favourite animal is @{my_favourite_animal}`.
4. Nested states can be accessed with `.` (dot), e.g. `@{building.height}`.
5. Nested elements can be dynamically accessed with `[]`, e.g. `@{building[dynamic_prop]}` will be equivalent to `@{building.height}` when `dynamic_prop` equals `height`.
- Properties are of different types, such as _Text_, _Color_ and _Number_. All property values are stored as text values, then casted when being evaluated.
+
+ The values for these settings can be of different types, such as _Text_, _Color_ and _Number_. The values are stored as text and are cast to the correct type when evaluated.
- 
- Input components can be bound, in a two-way fashion, to a state element.
- For example, a _Slider Input_ component can be bound to `my_var`. If the value of the slider changes, so does the value of `my_var`. Similarly, if the value of `my_var` changes, the slider is moved automatically to reflect the change.
+ 
+
+ Only input components have a **Binding** section, whose settings are used to bind the component to a variable in the application’s state. The binding is two-way; if the user changes the component’s value, the state variable will change to match, and any change the code makes to the bound state variable will also change the component’s value.
+
+ For example, a _Slider Input_ component can be bound to a state variable `my_var`. If the value of the slider changes, so does the value of `my_var`. Similarly, if the value of `my_var` changes, the slider is moved automatically to reflect the change.
+
To bind an input component, specify the state element. For example, `my_var` or `building.height`. Note that this field should not contain the template syntax, e.g. `my_var` and not `@{my_var}`.
- The events generated by this component, with the option of setting event handlers for those. Event handlers are explained in more detail in a separate section of this guide.
+ 
+
+ The **Events** section lists all the events generated by the selected component, with the option of setting event handlers for them. For example, one of the events that the Text Input component generates is the `wf-change` event, which occurs whenever the user changes the contents of the component.
+
+ For more about event handlers, consult the [_Event handlers_](/framework/event-handlers) section of the Writer Framework documentation.
- Whether the component should be displayed. There are three visibility options:
- 1. Yes. The component is displayed.
- 2. No. The component isn't displayed. Note that hidden components are still part of the HTML code but aren't shown.
- 3. Custom. Whether the component is displayed or not depends on the value of a state or context element. For example, if set to `my_var`, visibility will depend on the value of the `my_var` state element. Note that this field, similarly to Binding, should only contain the state element, e.g. `my_var` and not `@{my_var}`.
+ 
+
+ The **Visibility** settings control Whether the component should be displayed. There are three visibility options:
+
+ 1. **Yes**: The component is displayed.
+ 2. **No**: The component is _not_ displayed. Note that hidden components are still part of the HTML code but aren't shown.
+ 3. **Custom**: The component’s visibility depends on the value of a given state or context element. For example, if set to `my_var`, visibility will depend on the value of the `my_var` state element. Note that this field, similarly to Binding, should only contain the state element, e.g. `my_var` and not `@{my_var}`.
-## Component shortcuts
+### Component shortcuts
-Perform a variety of operations on existing components. Options will be grayed out when they're not applicable to the relevant component. Most shortcuts can be triggered using the keyboard; hover on them to show the appropriate combination.
+The Component shortcuts bar contains a set of options to perform various operations that are often performed on components.
-
+
-
-
- Adds a child of a specified type to this component.
-
-
- Decrements the position index of the component, used to sort children within the parent container.
-
-
- Increments the position index of the component.
-
-
- Cuts the component and places it into Builder’s internal clipboard.
-
-
- Copies the component and places it into the internal clipboard.
-
-
- Pastes the content of the internal clipboard using the selected component as a parent.
-
-
- Selects the parent of the selected component.
-
-
- Deletes this component.
-
-
+Options will be grayed out when they're not applicable to the relevant component. Most shortcuts can also be activated using the keyboard; hover the cursor over a shortcut to see its keyboard shortcut.
+The shortcuts are:
-Just like with changes to settings, these operations can be undone and redone.
+
-## Discovering components
+- **Add**: Adds a child of a specified type to the selected component.
+- **Move up**: Decrements the position index of the selected component, used to sort children within the parent container.
+- **Move down**: Increments the position index of the selected component.
+- **Cut**: Cuts the selected component and places it in the clipboard.
+- **Copy**: Copies the selected component to the clipboard.
+- **Paste**: Pastes the content of the internal clipboard using the selected component as a parent.
+- **Go to parent**: Selects the parent of the selected component.
+- **Delete**: Deletes the selected component.
+
+### The Code editor and the Log
+
+Writer Framework Builder provides a built-in Code editor for the `main.py` file, which defines the behavior of the app. You can toggle the Code panel by clicking the **Code** control near the lower left corner of the page:
+
+
+
+Any changes made to the code do not take effect until you click the **Save and run** button, located at the upper right corner of the code editor.
+
+The log is a useful debugging tool that displays any messages sent to standard output via the `print()` function, as well as any error messages. You can toggle the Log panel by clicking the **Log** control near the lower right corner of the page:
+
+
+
+Note that both the Code editor and Log panes can be displayed at the same time:
+
+
+
+
+## Testing your app in Preview mode
+
+In Preview mode, the overlays that let you build the user interface — the Core toolkit, Component tree, and Component settings — are invisible and unavailable. You see the app _almost_ as your users would see it; the Top bar and Bottom bar, which your users would not see, are still available to you in Preview mode.
+
+
+
+You can still use the Code editor and Log in Preview mode:
+
+
-The Builder is designed to allow easy discoverability of components. Rather than scouring specifications every time you need to use a component, you can rely on the visual editor to guide you.
-1. **Short description:** You can hover on the component type to get a tooltip with a short description.
-2. **Available properties and events:** Looking at _Settings_ will allow you to see which of its properties are configurable.
-3. **Built-in docs:** Components have short docs built into them. You can expand it by clicking the help icon in Settings.
-4. **Event handler stub code:** Different events need to be handled differently. The built-in stub handlers, which can be found next to each event, can help you get started when writing event handlers.
diff --git a/docs/framework/images/builder-basics.basic-settings.png b/docs/framework/images/builder-basics.basic-settings.png
new file mode 100644
index 000000000..8c39b141b
Binary files /dev/null and b/docs/framework/images/builder-basics.basic-settings.png differ
diff --git a/docs/framework/images/builder-basics.binding.png b/docs/framework/images/builder-basics.binding.png
index 79fd15e5e..22bbfabae 100644
Binary files a/docs/framework/images/builder-basics.binding.png and b/docs/framework/images/builder-basics.binding.png differ
diff --git a/docs/framework/images/builder-basics.code-and-log.png b/docs/framework/images/builder-basics.code-and-log.png
new file mode 100644
index 000000000..5c576fbd9
Binary files /dev/null and b/docs/framework/images/builder-basics.code-and-log.png differ
diff --git a/docs/framework/images/builder-basics.code.png b/docs/framework/images/builder-basics.code.png
index 01071e7a6..add6aa829 100644
Binary files a/docs/framework/images/builder-basics.code.png and b/docs/framework/images/builder-basics.code.png differ
diff --git a/docs/framework/images/builder-basics.component-search.png b/docs/framework/images/builder-basics.component-search.png
new file mode 100644
index 000000000..2f3e91c44
Binary files /dev/null and b/docs/framework/images/builder-basics.component-search.png differ
diff --git a/docs/framework/images/builder-basics.component-settings-show.png b/docs/framework/images/builder-basics.component-settings-show.png
new file mode 100644
index 000000000..822e5a85c
Binary files /dev/null and b/docs/framework/images/builder-basics.component-settings-show.png differ
diff --git a/docs/framework/images/builder-basics.component-settings.png b/docs/framework/images/builder-basics.component-settings.png
index dd5416d73..b0d32e524 100644
Binary files a/docs/framework/images/builder-basics.component-settings.png and b/docs/framework/images/builder-basics.component-settings.png differ
diff --git a/docs/framework/images/builder-basics.component-shortcuts-guide.png b/docs/framework/images/builder-basics.component-shortcuts-guide.png
new file mode 100644
index 000000000..9a35b521c
Binary files /dev/null and b/docs/framework/images/builder-basics.component-shortcuts-guide.png differ
diff --git a/docs/framework/images/builder-basics.component-shortcuts.png b/docs/framework/images/builder-basics.component-shortcuts.png
index 5ff4e51fb..dafee3712 100644
Binary files a/docs/framework/images/builder-basics.component-shortcuts.png and b/docs/framework/images/builder-basics.component-shortcuts.png differ
diff --git a/docs/framework/images/builder-basics.components.png b/docs/framework/images/builder-basics.components.png
new file mode 100644
index 000000000..6e6b93cdd
Binary files /dev/null and b/docs/framework/images/builder-basics.components.png differ
diff --git a/docs/framework/images/builder-basics.drag-drop-components.png b/docs/framework/images/builder-basics.drag-drop-components.png
new file mode 100644
index 000000000..e16cb695c
Binary files /dev/null and b/docs/framework/images/builder-basics.drag-drop-components.png differ
diff --git a/docs/framework/images/builder-basics.events.png b/docs/framework/images/builder-basics.events.png
new file mode 100644
index 000000000..2b4e8b19f
Binary files /dev/null and b/docs/framework/images/builder-basics.events.png differ
diff --git a/docs/framework/images/builder-basics.log.png b/docs/framework/images/builder-basics.log.png
new file mode 100644
index 000000000..e94623004
Binary files /dev/null and b/docs/framework/images/builder-basics.log.png differ
diff --git a/docs/framework/images/builder-basics.parent-components.png b/docs/framework/images/builder-basics.parent-components.png
new file mode 100644
index 000000000..80bcdbcc3
Binary files /dev/null and b/docs/framework/images/builder-basics.parent-components.png differ
diff --git a/docs/framework/images/builder-basics.preview-code-and-log.png b/docs/framework/images/builder-basics.preview-code-and-log.png
new file mode 100644
index 000000000..aa724267b
Binary files /dev/null and b/docs/framework/images/builder-basics.preview-code-and-log.png differ
diff --git a/docs/framework/images/builder-basics.preview-mode.png b/docs/framework/images/builder-basics.preview-mode.png
new file mode 100644
index 000000000..c376b2efa
Binary files /dev/null and b/docs/framework/images/builder-basics.preview-mode.png differ
diff --git a/docs/framework/images/builder-basics.preview.png b/docs/framework/images/builder-basics.preview.png
index 9bedc03db..e735f2391 100644
Binary files a/docs/framework/images/builder-basics.preview.png and b/docs/framework/images/builder-basics.preview.png differ
diff --git a/docs/framework/images/builder-basics.select-components.png b/docs/framework/images/builder-basics.select-components.png
new file mode 100644
index 000000000..c9e32a04a
Binary files /dev/null and b/docs/framework/images/builder-basics.select-components.png differ
diff --git a/docs/framework/images/builder-basics.tree-search.png b/docs/framework/images/builder-basics.tree-search.png
new file mode 100644
index 000000000..fd21e1bef
Binary files /dev/null and b/docs/framework/images/builder-basics.tree-search.png differ
diff --git a/docs/framework/images/builder-basics.ui-mode-with-labels.png b/docs/framework/images/builder-basics.ui-mode-with-labels.png
new file mode 100644
index 000000000..5a27f63ef
Binary files /dev/null and b/docs/framework/images/builder-basics.ui-mode-with-labels.png differ
diff --git a/docs/framework/images/builder-basics.ui-mode.png b/docs/framework/images/builder-basics.ui-mode.png
new file mode 100644
index 000000000..292a7233e
Binary files /dev/null and b/docs/framework/images/builder-basics.ui-mode.png differ
diff --git a/docs/framework/images/builder-basics.ui-preview-selector.png b/docs/framework/images/builder-basics.ui-preview-selector.png
new file mode 100644
index 000000000..38e37cdde
Binary files /dev/null and b/docs/framework/images/builder-basics.ui-preview-selector.png differ
diff --git a/docs/framework/images/builder-basics.visibility.png b/docs/framework/images/builder-basics.visibility.png
new file mode 100644
index 000000000..30b641b76
Binary files /dev/null and b/docs/framework/images/builder-basics.visibility.png differ