From cdbb6f1f42896f00ec04a92f902b97725549cdb8 Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Thu, 6 Aug 2026 16:09:22 +0200
Subject: [PATCH 1/6] basic docs, needs review

---
 AGENTS.md                    |  66 +++++++++++++++--
 docs/syntax/animations.mdx   |  43 +++++++++++
 docs/syntax/data-binding.mdx |  93 +++++++++++++++++++++++
 docs/syntax/evaluate.mdx     |  68 ++++++++++++++---
 docs/syntax/index.mdx        |   6 ++
 docs/syntax/meta.json        |   1 +
 docs/syntax/styles.mdx       |  79 ++++++++++++++++++++
 docs/syntax/variants.mdx     | 138 +++++++++++++++++++++++++++++++++++
 8 files changed, 480 insertions(+), 14 deletions(-)
 create mode 100644 docs/syntax/variants.mdx

diff --git a/AGENTS.md b/AGENTS.md
index df3a4009..577eaca6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -62,15 +62,16 @@ my_project/
 </component>
 ```
 
-### The three sigils
+### The sigils
 
 | Prefix | Means | Example |
 | --- | --- | --- |
 | `$name` | An `<api>` property of this element | `<lv_label text="$title"/>` |
 | `#name` | A constant from `<consts>` or `globals.xml` | `pad="#space_md"` |
 | `{ ... }` | An expression, evaluated once at creation | `hidden="{!icon}"` |
+| `@{ ... }` | The same expression as a binding: re-evaluated whenever a subject or variant in it changes | `hidden="@{subject_count == 0}"` |
 
-Inside `{ }` you write bare identifiers, no `$` or `#`.
+Inside `{ }` and `@{ }` you write bare identifiers, no `$` or `#`.
 
 ### `view` and `extends`
 
@@ -123,6 +124,12 @@ Three ways, in order of preference:
 
 <!-- 3. Bound style, applied when a subject matches -->
 <bind_style name="style_dark" subject="subject_dark_theme_on" ref_value="1"/>
+
+<!-- 3b. Bound style, applied while an expression is true (no @{} wrapper) -->
+<bind_style name="style_warning" if="subject_temp > 10 and subject_temp &lt;= 30"/>
+
+<!-- 2b. Computed local style property -->
+<lv_label style_text_color-pressed="@{subject_error ? 0xf00 : 0xaaa}"/>
 ```
 
 Prefix style names with `style_`. Selectors combine parts and states with `|`.
@@ -140,6 +147,19 @@ But constants can be used:
 
 Pass the property to a *local* style property instead: `<lv_slider style_border_width-knob="$thickness"/>`.
 
+A `<transition>` child animates a style's properties on state changes. It animates *into* the state of the style holding it, so for both directions add one to the default style too:
+
+```xml
+<style name="style_card" bg_color="#color_panel">
+  <transition props="bg_color" duration="300" easing="ease_out"/>
+</style>
+<style name="style_card_pressed" bg_color="#color_panel_pressed">
+  <transition props="bg_color" duration="80"/>
+</style>
+```
+
+One transition per style, numeric and color properties only, and `<bind_style>` never animates.
+
 ## Data binding
 
 Subjects are the interface between the UI and the application. Define them in `globals.xml`:
@@ -161,6 +181,10 @@ Only `int`, `string` and `float` are supported.
 <!-- Conditional: child element binding -->
 <bind_flag_if_eq  subject="subject_mode" flag="hidden"  ref_value="0"/>
 <bind_state_if_gt subject="subject_temp" state="checked" ref_value="30"/>
+
+<!-- Generic: any widget attribute bound to any expression -->
+<lv_label text="@{'Battery: ' . subject_battery . '%'}"/>
+<lv_obj width="@{subject_columns * 100}" style_bg_color="@{subject_on ? 0x0f0 : 0x333}"/>
 ```
 
 `bind_flag_*` takes a `flag`, `bind_state_*` takes a `state`. Both come in `_eq`, `_not_eq`, `_gt`, `_ge`, `_lt`, `_le`. The `lv_obj-` prefix is optional.
@@ -168,8 +192,35 @@ Only `int`, `string` and `float` are supported.
 States: `default`, `checked`, `focused`, `focus_key`, `edited`, `hovered`, `pressed`, `scrolled`, `disabled`.
 Common flags: `hidden`, `clickable`, `checkable`, `scrollable`, `floating`, `ignore_layout`.
 
+`@{ }` is `{ }` that re-runs whenever a referenced subject or variant changes. It works on **widget** attributes (including `style_*` locals) and on a component instance's **variant** attributes — not in `<styles>` (initialized once) and not on a component's own props or slots. It must reference at least one subject or variant, and inside it only `type="subject"` props may appear; other props are an error. A failed re-evaluation (e.g. `/0`) keeps the previous value.
+
+To give each instance its own data, declare `<prop name="temp" type="subject"/>` and pass a subject name at the call site: `<room_card temp="subject_kitchen"/>`.
+
 **Binding beats callbacks.** A radio group, a theme switch, or a value readout needs no C at all: write the subject with `subject_set_int_event`, read it with `bind_state_if_eq`.
 
+## Variants
+
+A component's named visual states, declared in `<api>`. Per-instance and reactive, so they are the component-scoped counterpart of global subjects.
+
+```xml
+<api>
+  <variants>
+    <variant name="size" options="small large" default="small"/>
+    <variant name="tone" options="normal danger" default="normal"/>
+  </variants>
+</api>
+<view extends="lv_button">
+  <style name="style_normal"/>
+  <bind_style name="style_danger" subject="tone" ref_value="danger"/>
+  <bind_style name="style_large"  subject="size" ref_value="large"/>
+  <lv_label text="Subtitle" hidden="@{size == small}"/>
+</view>
+```
+
+Read a variant with `<bind_style subject="<variant>" ref_value="<option>">` (preferred for anything visual) or in `@{ }`, where the variant name is the current option and an option name is a constant.
+
+Pick an option on the instance — `<my_badge size="large" tone="@{subject_level > 100 ? danger : normal}"/>` — or from C with `lv_xml_set_variant(obj, "size", "large")`. Unknown option → `default` + warning. Option names must be unique across a component's variants, a variant name shadows a same-named prop/const/subject, and reordering `options` breaks already exported C.
+
 ## Events
 
 All are children of a widget, all take `trigger` (`clicked`, `long_pressed`, `value_changed`, ...):
@@ -196,14 +247,16 @@ Evaluated **once at creation**, not reactive. For anything that changes at runti
 <lv_obj style_bg_color="{is_on ? 0x00ff00 : 0x333333}"/>
 ```
 
-`.` concatenates. Strings use single quotes. There is no `&&` or `||`, comparisons cannot be chained, and ternaries cannot be nested.
+`.` concatenates. Strings use single quotes. Comparisons cannot be chained (`a < b < c`) and ternaries cannot be nested.
+
+`&&` and `||` exist, but `&` and `<` must be XML-escaped in an attribute value, so prefer the `and` / `or` keywords: `hidden="{a > 10 and a &lt;= 30}"`. Both sides are always evaluated — there is no short-circuiting.
 
 ## Animations
 
 ```xml
 <animations>
   <timeline name="timeline_load">
-    <animation prop="translate_x" target="self" start="-30" end="0" duration="500"/>
+    <animation prop="translate_x" target="self" start="-30" end="0" duration="500" easing="ease_out"/>
     <animation prop="opa" target="label" start="0" end="255" duration="500" delay="200"/>
     <include_timeline target="icon" timeline="show_up" delay="300"/>
   </timeline>
@@ -212,6 +265,8 @@ Evaluated **once at creation**, not reactive. For anything that changes at runti
 
 `target="self"` is the `view`; anything else is matched against a child's `name`. Play with `<play_timeline_event>`.
 
+`easing` (on `<animation>` and `<transition>`) is `linear` (default), `ease_in`, `ease_out`, `ease_in_out`, `overshoot`, `bounce`, `step`, `bezier(x1 y1 x2 y2)` with `x` in `0..1`, or a callback registered with `lv_xml_register_easing_cb()`.
+
 ## Slots
 
 Expose an internal object as a place where the caller can add children:
@@ -237,7 +292,8 @@ The slot target is `<component_name-slot_name>`, and you can set normal object p
 
 - Inventing an attribute instead of reading `lvgl_widgets_xml/`.
 - Putting `$prop` into a `<style>`. Use a local style property.
-- Expecting `{ }` to update at runtime. It does not, that's data binding.
+- Expecting `{ }` to update at runtime. It does not — write `@{ }` for that.
+- Putting a non-subject `$prop` inside `@{ }`, or `@{ }` on a component's own prop or in a `<style>`. None of them can update.
 - Using `bind_state_*` with a `flag=` attribute, or `bind_flag_*` with `state=`.
 - `screen_load_event` on a screen that isn't `permanent="true"`.
 - Hard-coding `pad="8"` and `bg_color="0x1E232E"` when `#space_md` and `#color_dark_panel` already exist in `globals.xml`.
diff --git a/docs/syntax/animations.mdx b/docs/syntax/animations.mdx
index 907a22aa..5c0c8177 100644
--- a/docs/syntax/animations.mdx
+++ b/docs/syntax/animations.mdx
@@ -66,7 +66,50 @@ Within each `timeline`, add individual `<animation>` elements to describe each s
 - `duration` - Duration of the animation in milliseconds.
 - `delay` - Delay before starting in milliseconds. Default is 0.
 - `early_apply` - If `true`, the start value is applied immediately, even during the delay. Default is `false`.
+- `easing` - The animation path, e.g. `ease_out`. See below. Default is `linear`.
 
+### Easing
+
+The `easing` property tells how the value should progress from `start` to `end` during the `duration`. Besides `<animation>`, style [`<transition>`](./styles#transitions)s support it too.
+
+These built-in paths can be used:
+
+- `linear` - Constant speed. This is the default.
+- `ease_in` - Slow start.
+- `ease_out` - Slow end.
+- `ease_in_out` - Slow start and end.
+- `overshoot` - Goes above the end value and settles back.
+- `bounce` - Bounces back a few times at the end.
+- `step` - Stays at the start value and jumps to the end value at the very end.
+
+```xml
+<animation prop="translate_y" target="self" start="-30" end="0" duration="500" easing="ease_out"/>
+```
+
+For full control, `bezier(x1 y1 x2 y2)` describes a cubic bezier curve with its two control points, just like `cubic-bezier()` in CSS:
+
+```xml
+<animation prop="translate_y" target="self" start="-30" end="0" duration="500"
+           easing="bezier(0.34 1.56 0.64 1)"/>
+```
+
+`x1` and `x2` need to be in the `0..1` range, while `y1` and `y2` can be outside it to overshoot. Ready to use curves can be picked from e.g. [easings.net](https://easings.net).
+
+Finally, an animation path implemented in C can be registered by name and then referenced in `easing`:
+
+```c
+static int32_t my_easing(const lv_anim_t * a)
+{
+    return lv_map(a->act_time, 0, a->duration, a->start_value, a->end_value);
+}
+
+/* `NULL` registers it globally. It can be a component's scope as well. */
+lv_xml_register_easing_cb(NULL, "my_easing", my_easing);
+```
+
+```xml
+<animation prop="translate_y" target="self" start="-30" end="0" duration="500" easing="my_easing"/>
+```
 
 ### Include External Timelines
 
diff --git a/docs/syntax/data-binding.mdx b/docs/syntax/data-binding.mdx
index bef1184a..43a64d16 100644
--- a/docs/syntax/data-binding.mdx
+++ b/docs/syntax/data-binding.mdx
@@ -154,6 +154,99 @@ The most commonly bound `LV_OBJ_FLAG_*` flags, exposed by the same names without
 
 For the full list of states and flags see LVGL's [Object basics](https://lvgl.io/docs/open/intro/basics) and [Style states](https://lvgl.io/docs/open/main-modules/style#states) reference.
 
+## Expression binding
+
+The `bind_*` attributes and elements can bind only what they were designed for. To bind **any** widget attribute to **any** expression of subjects, wrap the expression in `@{ }`:
+
+```xml
+<lv_label text="@{'Battery: ' . subject_battery . '%'}"/>
+<lv_obj width="@{subject_column_count * 100}"/>
+<lv_obj hidden="@{subject_unread == 0}"/>
+<lv_obj style_bg_color="@{subject_temp > 30 ? 0xff0000 : 0x00ff00}"/>
+```
+
+The expression is evaluated when the widget is created, and **re-evaluated whenever any subject it references changes**. The result is applied to the attribute exactly as if you had typed the computed value there.
+
+`@{ }` and `{ }` share the same syntax, operators, and type rules — see [Evaluate expressions](./evaluate). The difference is only *when* they run:
+
+```xml
+<!-- Updates whenever subject_volume changes -->
+<lv_label text="@{'Volume: ' . subject_volume}"/>
+
+<!-- Evaluated once, when the label is created -->
+<lv_label text="{'Volume: ' . subject_volume}"/>
+```
+
+### What can be referenced
+
+Inside `@{ }` names are written as **bare identifiers**, without `$` or `#`:
+
+- **Subjects** - defined in `globals.xml`. An expression should reference at least one subject (or variant), else it could never update, and it's skipped with a warning.
+- **Variants** - the Component's own reactive state. A variant name reads the currently selected option, and the option names can be used as constants. See [Variants](./variants).
+- **Constants** - they are inlined as literals.
+- **`type="subject"` properties** - see below.
+
+Properties of any other type **cannot** be used, because they exist only while the element is being created. Such a binding is skipped with a warning, but the widget is still created normally.
+
+Several subjects can be used in one expression, and a change of any of them re-evaluates it:
+
+```xml
+<lv_obj width="@{subject_cell_width * subject_column_count}"/>
+```
+
+### Per-instance subjects
+
+A binding written in a Component is shared by all of its instances, so referencing a subject by name makes every instance follow the *same* subject. To let each instance follow a *different* one, declare a `type="subject"` property and pass the subject's name where the Component is used:
+
+```xml
+<!-- room_card.xml -->
+<component>
+  <api>
+    <prop name="temperature" type="subject"/>
+  </api>
+
+  <view extends="lv_obj">
+    <lv_label text="@{temperature . ' °C'}"/>
+    <lv_obj style_bg_color="@{temperature > 25 ? 0xff8800 : 0x0088ff}"/>
+  </view>
+</component>
+```
+
+```xml
+<!-- screen -->
+<room_card temperature="subject_kitchen_temp"/>
+<room_card temperature="subject_bedroom_temp"/>
+```
+
+### Where it can be used
+
+`@{ }` works on the attributes of **widgets**: on the `<view>` itself, on any widget inside it, and on local style properties (`style_bg_color`, `style_pad_all-pressed`, ...). It also works on a Component instance's [variant](./variants) attributes.
+
+It can't be used in the `<styles>` section, as [styles](./styles) are initialized only once, nor on the normal properties of a Component instance:
+
+```xml
+<!-- ❌ A style is initialized once, so it can't be bound -->
+<style name="style_main" bg_color="@{subject_theme_color}"/>
+
+<!-- ❌ `title` is a property of the my_card Component -->
+<my_card title="@{subject_user_name}"/>
+
+<!-- ✅ Bind inside the Component, and pass the subject to it -->
+<my_card title_subject="subject_user_name"/>
+```
+
+To switch a whole style at runtime, use [`<bind_style>`](./styles#style-binding), which takes the same kind of expression in its `if` attribute:
+
+```xml
+<bind_style name="style_warning" if="subject_temp > 10 and subject_temp &lt;= 30"/>
+```
+
+### Errors
+
+An expression that can't be parsed is reported with a warning and the binding is skipped, so the attribute keeps its default value. The widget itself is always created.
+
+If the evaluation fails only later — a division by zero after a subject became `0`, for example — a warning is logged and the attribute **keeps its previous value** instead of being set to something meaningless.
+
 ## Selection groups via a shared subject
 
 A common pattern is to express "exactly one of these widgets is active" with a single integer subject and one `ref_value` per option. Combining `subject_set_int_event` (writes the subject on click) with `bind_state_if_eq` (reads it to drive the `checked` state) produces a runtime-driven radio group with no application code.
diff --git a/docs/syntax/evaluate.mdx b/docs/syntax/evaluate.mdx
index a664d749..3a9905fb 100644
--- a/docs/syntax/evaluate.mdx
+++ b/docs/syntax/evaluate.mdx
@@ -22,7 +22,7 @@ Expressions are useful whenever a value is *derived* from other values: a width
 A few important properties to keep in mind:
 
 - **Creation-time only.** An expression is evaluated **once**, when the UI element is created. The result is then handed to the normal attribute parser exactly as if you had typed the computed value yourself.
-- **Not data binding.** Expressions do *not* react to changes. If you need a value that updates at runtime when a subject changes, use [data binding](./data-binding) instead.
+- **Not reactive.** A `{ }` expression does *not* react to changes. For a value that follows a subject or a variant at runtime, write the very same expression as a binding — `@{ }` instead of `{ }` — see [Expression binding](./data-binding#expression-binding).
 - **The result type is inferred from the terms.** You never declare the type — it follows from the literals and variables you use (see [Value types](#value-types)).
 
 <Callout type="info">
@@ -39,9 +39,12 @@ An expression is the whole attribute value, wrapped in a single pair of braces:
 
 Inside the braces you can use literals, operators, and **variable names**. A variable name is written as a **bare identifier** — without the `$` or `#` prefixes used elsewhere in XML. The name is resolved, in order, against:
 
-1. **Parameters** declared in the element's [`<api>`](./api) — the value comes from the instance (or the parameter's `default`), and the type from the declared `type`.
-2. **Constants** from [`<consts>`](./constants) — the type is inferred from the constant's value.
-3. **Other named items** the XML processor resolves later (a font, image, subject, or screen name). These are passed through as plain strings.
+1. **Variants** declared in the element's [`<api>`](./api) — the currently selected option of that [variant](./variants).
+2. **Parameters** declared in the element's [`<api>`](./api) — the value comes from the instance (or the parameter's `default`), and the type from the declared `type`.
+3. **Constants** from [`<consts>`](./constants) — the type is inferred from the constant's value.
+4. **Variant option names** — an integer constant, the option's index in its variant.
+5. **Subjects** from `globals.xml` — their current value, read once (use `@{ }` to follow them).
+6. **Other named items** the XML processor resolves later (a font, image, or screen name). These are passed through as plain strings.
 
 ```xml
 <component>
@@ -101,7 +104,7 @@ Notes:
 <lv_obj checked="{mode == 'dark'}"/>
 ```
 
-Only **one** comparison is allowed per expression — comparisons cannot be chained (`a < b < c` is invalid).
+Comparisons cannot be **chained**: `a < b < c` is invalid. Each operand of a logical `and`/`or` may contain one comparison, so a range check is written as `a > 10 and a <= 30`.
 
 ### Logical not
 
@@ -111,7 +114,29 @@ The unary `!` accepts a number, bool, or string and returns a bool. An empty or
 <lv_obj clickable="{!locked}"/>
 ```
 
-There are intentionally **no** `&&`, `||`, or `^^` operators.
+### Logical and / or
+
+`&&` and `||` combine two conditions and return a bool. Their operands can be anything that has a truthiness: a bool, a number (non-zero is true), or a string (non-empty is true). A color has none, so it's a type error.
+
+Because `&` must be escaped in an XML attribute value, both operators also have a keyword spelling — `and` and `or` — which is usually the readable choice:
+
+```xml
+<!-- These two are identical -->
+<lv_obj hidden="{temperature > 10 and temperature &lt;= 30}"/>
+<lv_obj hidden="{temperature > 10 &amp;&amp; temperature &lt;= 30}"/>
+```
+
+`&&` binds tighter than `||`, and both bind tighter than the ternary, so a range check reads naturally as a condition:
+
+```xml
+<lv_label text="{level > 80 or charging ? 'OK' : 'Low'}"/>
+```
+
+<Callout type="warn">
+Both sides are **always evaluated** — there is no short-circuiting (same as with the two ternary branches). So `count != 0 and total / count > 5` still fails on a division by zero when `count` is 0.
+</Callout>
+
+`and`/`or` are keywords, so a constant, property, or subject cannot be named `and` or `or`. There is no `^^` operator.
 
 ### Ternary
 
@@ -141,13 +166,38 @@ From highest to lowest:
 2. `*`, `/`, `%`
 3. `+`, `-`
 4. Comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`)
-5. Concatenation (`.`)
-6. Ternary (`? :`)
+5. `&&` (`and`)
+6. `||` (`or`)
+7. Concatenation (`.`)
+8. Ternary (`? :`)
 
-Parentheses `( )` group **arithmetic and comparison** sub-expressions. They cannot contain a concatenation or a ternary.
+Parentheses `( )` group **arithmetic, comparison, and logical** sub-expressions. They cannot contain a concatenation or a ternary.
 
 ```xml
 <lv_obj width="{(a + b) * 2}"/>
+<lv_obj hidden="{(a or b) and c}"/>
+```
+
+## XML escaping
+
+An expression lives in an XML attribute value, where a few characters are reserved. This is a property of XML itself, not of the expression syntax:
+
+| Character | Write it as | Note |
+|---|---|---|
+| `<` | `&lt;` | Never allowed in an attribute value |
+| `&` | `&amp;` | So `&&` becomes `&amp;&amp;` — or use `and` |
+| `'` | `&apos;` | Only inside a `'…'` delimited value |
+| `>` | `>` | Allowed as-is |
+
+```xml
+<!-- ❌ not well-formed XML: the file won't load -->
+<lv_obj hidden="{count < 10 && locked}"/>
+
+<!-- ✅ -->
+<lv_obj hidden="{count &lt; 10 and locked}"/>
+
+<!-- ✅ or turn the comparison around and avoid the escape entirely -->
+<lv_obj hidden="{10 > count and locked}"/>
 ```
 ## Error handling
 
diff --git a/docs/syntax/index.mdx b/docs/syntax/index.mdx
index 429e5243..513271ac 100644
--- a/docs/syntax/index.mdx
+++ b/docs/syntax/index.mdx
@@ -116,6 +116,12 @@ This section covers everything from basic building blocks to advanced styling an
     Define custom APIs for widgets and components with properties, parameters, enums, and elements.
   </Card>
 
+  <Card href="./variants" icon={<Blocks />}>
+    **Variants**
+
+    Declare a Component's named visual states, like size or tone, and switch between them at runtime.
+  </Card>
+
   <Card href="./events" icon={<Zap />}>
     **Events in XML**
 
diff --git a/docs/syntax/meta.json b/docs/syntax/meta.json
index 3b7aec08..7fef27cb 100644
--- a/docs/syntax/meta.json
+++ b/docs/syntax/meta.json
@@ -23,6 +23,7 @@
 
     "---Interaction & Configuration---",
     "api",
+    "variants",
     "events",
     "data-binding",
     "evaluate",
diff --git a/docs/syntax/styles.mdx b/docs/syntax/styles.mdx
index caa3173f..bfea2fd8 100644
--- a/docs/syntax/styles.mdx
+++ b/docs/syntax/styles.mdx
@@ -56,6 +56,49 @@ As shown in the example, parts and states can be set using `selector`.
     It's recommended to prefix style names with `style_` to avoid name collisions.
 </Callout>
 
+### Transitions
+
+By default the properties of a style are applied immediately when the widget's state changes. A `<transition>` child of a `<style>` animates the listed properties instead:
+
+```xml
+<styles>
+    <style name="style_button" bg_color="0x0088ff" transform_scale_x="256">
+        <transition props="bg_color transform_scale_x" duration="300"/>
+    </style>
+
+    <style name="style_button_pressed" bg_color="0x004488" transform_scale_x="230">
+        <transition props="bg_color transform_scale_x" duration="80"/>
+    </style>
+</styles>
+
+<view extends="lv_button">
+    <style name="style_button"/>
+    <style name="style_button_pressed" selector="pressed"/>
+</view>
+```
+
+`<transition>` supports these properties:
+
+- `props` - Space separated list of the style properties to animate. Use `remove` to delete a previously set transition.
+- `duration` - Duration of the animation in milliseconds. Mandatory.
+- `delay` - Delay before the animation starts in milliseconds. Default is `0`.
+- `easing` - The animation path, e.g. `ease_out`. See [Easing](./animations#easing). Default is `linear`.
+
+A transition describes how to animate **into** the state of the style that contains it. In the above example pressing the button uses the 80 ms transition of `style_button_pressed`, and releasing it uses the 300 ms transition of `style_button`.
+
+This means that to animate in both directions, a `<transition>` needs to be added to the default state's style too. If only the pressed style has one, the button animates when it's pressed, but snaps back when it's released.
+
+<Callout>
+Only state changes (`pressed`, `checked`, `disabled`, `focused`, ...) start a transition. `<bind_style>` enables and disables styles instead of changing the state, so its styles are applied without animation.
+</Callout>
+
+Keep these limitations in mind:
+
+- A style can store only one transition. To use different durations for different properties, split them into two styles.
+- Only numeric (including opacity) and color properties can be animated. Properties referencing other data (`text_font`, `bg_image_src`, `bg_grad`, ...) and most enums and booleans (`flex_flow`, `text_align`, `clip_corner`, ...) are ignored with a warning.
+- The composite names are expanded, so e.g. `props="pad_all"` transitions all the four paddings.
+- Like in any other style property, `#constants` can be used, but `$api_properties` can't.
+
 ## Style Binding
 
 Instead of directly adding styles to UI elements, you can add them conditionally when a subject's value equals a reference value. This enables dynamic styling at runtime, allowing you to change appearance or layout based on conditions.
@@ -85,6 +128,35 @@ Here is an example:
 </component>
 ```
 
+`<bind_style>` accepts the same `selector` as `<style>`, so a bound style can target a part or a state as well.
+
+### Conditional style binding
+
+`subject` and `ref_value` cover the "equals a value" case. For anything more complex, describe the condition with an [expression](./evaluate) in the `if` attribute:
+
+```xml
+<styles>
+  <style name="style_warning" bg_color="0xff8800"/>
+</styles>
+
+<view extends="lv_obj">
+  <bind_style name="style_warning" if="subject_temp > 10 and subject_temp &lt;= 30"/>
+</view>
+```
+
+The style is applied while the expression is true, and removed while it's false. It is re-evaluated whenever any subject or [variant](./variants) referenced in the expression changes.
+
+- Write the expression **directly**, without the `@{ }` wrapper.
+- Any number of subjects and variants can be used, and the whole [expression syntax](./evaluate) is available, including `and` / `or`.
+- The condition doesn't have to be a comparison. Any value with a truthiness works, so `if="subject_error"` is enough for an int subject.
+- Use `if` **or** `subject`+`ref_value`, not both. If both are given, `if` wins and `subject` is ignored with a warning.
+- A condition referencing no subject at all (e.g. only constants) is evaluated once, at creation.
+- An invalid expression is reported and the style is **not added**, so a typo can't leave a style stuck on the widget.
+
+<Callout type="info">
+Under the hood the style is added once and only *enabled* or *disabled* as the condition changes. Its priority relative to the other styles of the widget therefore stays the same, no matter how often the condition flips.
+</Callout>
+
 ## Local Styles
 
 ### Simple Usage 
@@ -113,6 +185,13 @@ Instead of setting local style properties directly, you can bind them to subject
 </component>
 ```
 
+`<bind_style_prop>` copies a subject's value into the property as-is. To compute the value, write an [expression binding](./data-binding#expression-binding) on the local style property itself — selectors included:
+
+```xml
+<lv_label style_text_color-pressed="@{subject_error_mode ? 0xff0000 : 0xaaaaaa}"/>
+<lv_slider style_bg_opa-knob="@{subject_brightness * 2}"/>
+```
+
 ## Relation to Constants
 
 In the values of style properties constants can be used as well.
diff --git a/docs/syntax/variants.mdx b/docs/syntax/variants.mdx
new file mode 100644
index 00000000..5de16e6b
--- /dev/null
+++ b/docs/syntax/variants.mdx
@@ -0,0 +1,138 @@
+---
+title: Variants
+description: Declare a Component's visual variations, like size or tone, and switch between them at runtime.
+---
+
+Most Components exist in a few flavors: a button that is `small` or `large`, a badge that is `normal` or `danger`. A **variant** declares such a dimension once, and every instance can pick an option from it — statically, from a subject, or from C at runtime.
+
+```xml
+<my_badge size="large" tone="danger"/>
+```
+
+## Overview
+
+A variant is a named list of options, declared in the Component's [`<api>`](./api):
+
+```xml
+<component>
+  <api>
+    <variants>
+      <variant name="size" options="small large" default="small"/>
+      <variant name="tone" options="normal danger" default="normal"/>
+    </variants>
+  </api>
+  ...
+</component>
+```
+
+- `name` - The name of the variant. It becomes a property of the Component.
+- `options` - Space separated list of the option names.
+- `default` - The option to use when the instance doesn't set one. If it's missing or unknown, the first option is used.
+
+Each variant is **per-instance reactive state**: ten instances of the same Component can be in ten different states, and switching one of them updates only that instance. This makes variants the Component-level counterpart of [subjects](./data-binding), which are global.
+
+<Callout type="info">
+Variants are useful when a Component's *appearance* has a fixed set of named states. For free-form data (a temperature, a user name) use a subject or an [`<api>`](./api) property instead.
+</Callout>
+
+## Reacting to a variant
+
+A variant is meaningless until something reads it. There are two ways, and they are usually combined.
+
+### Switching styles
+
+`<bind_style>` attaches a style while a variant has a given option. Use the variant's name as `subject` and an option name as `ref_value`:
+
+```xml
+<component>
+  <api>
+    <variants>
+      <variant name="size" options="small large" default="small"/>
+      <variant name="tone" options="normal danger" default="normal"/>
+    </variants>
+  </api>
+
+  <styles>
+    <style name="style_normal" bg_color="0x0000ff"/>
+    <style name="style_danger" bg_color="0xff0000"/>
+    <style name="style_small" height="40"/>
+    <style name="style_large" height="100"/>
+  </styles>
+
+  <view extends="lv_button">
+    <style name="style_normal"/>
+    <bind_style name="style_danger" subject="tone" ref_value="danger"/>
+    <bind_style name="style_small" subject="size" ref_value="small"/>
+    <bind_style name="style_large" subject="size" ref_value="large"/>
+
+    <lv_label name="title" text="Title"/>
+  </view>
+</component>
+```
+
+This is the recommended way to express the *visual* difference between options: the styles stay declarative, and only the option selection changes at runtime.
+
+### In expressions
+
+A variant can also be used in [`@{ }` bindings](./data-binding#expression-binding), where:
+
+- a **variant name** reads the currently selected option,
+- an **option name** is a constant that can be compared against it.
+
+```xml
+<!-- Show the subtitle only in the large size -->
+<lv_label name="subtitle" text="Subtitle" hidden="@{size == small}"/>
+
+<!-- A variant and a global subject in one expression -->
+<lv_label text="@{mode == on ? 'n=' . subject_count : 'off'}"/>
+```
+
+Because `@{ }` re-evaluates on every change, switching the variant updates these attributes immediately. In a plain [`{ }` expression](./evaluate) a variant works too, but it's read only once, when the element is created.
+
+## Selecting an option
+
+### On the instance
+
+A variant behaves like a normal property where the Component is used:
+
+```xml
+<my_badge size="large" tone="danger"/>
+```
+
+An unknown option name falls back to the variant's `default` and logs a warning.
+
+The value can also be a [binding](./data-binding#expression-binding), so a variant can follow a subject:
+
+```xml
+<my_badge tone="@{subject_level > 100 ? danger : normal}"/>
+```
+
+Note that such a binding is evaluated in the **surrounding** element's scope: `subject_level` needs to be visible there, while `danger` and `normal` need to be options of `my_badge`'s `tone` variant.
+
+### From C
+
+```c
+lv_xml_set_variant(badge, "size", "large");
+```
+
+The variant is searched on the given widget and then up along its parents, so passing any widget inside a Component instance works too. Every `bind_style` and `@{ }` expression referencing the variant updates immediately.
+
+## Name resolution
+
+Inside expressions a bare identifier is resolved in this order:
+
+1. **variant name**
+2. `<api>` property
+3. constant
+4. variant option name
+5. subject
+6. anything else is kept as a plain string (a font or image name, for example)
+
+Two consequences worth remembering:
+
+- A variant **shadows** a property, constant, or subject of the same name. Avoid such collisions.
+- **Option names have to be unique across a Component's variants**, otherwise a bare option name in an expression is ambiguous — the first declared variant wins, and registration logs a warning. `<bind_style>` is exempt, since its `subject` attribute already tells which variant the `ref_value` belongs to.
+
+<Callout type="warn">
+The order of `options` defines the integer value of each option in the exported C code. Reordering them is a breaking change for code that was already generated; adding new options at the end is safe.
+</Callout>

From 7c3acef9f62675a9efde1c3ac7fff4f7812b5314 Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Sat, 8 Aug 2026 14:53:18 +0200
Subject: [PATCH 2/6] docs fixes

---
 AGENTS.md                    |  8 +++----
 docs/syntax/animations.mdx   | 11 +++++++---
 docs/syntax/api.mdx          |  2 ++
 docs/syntax/data-binding.mdx | 15 ++++++++-----
 docs/syntax/evaluate.mdx     | 33 +++++++++++++++++------------
 docs/syntax/styles.mdx       |  4 ++--
 docs/syntax/variants.mdx     | 41 ++++++++++++++++++++++++++----------
 7 files changed, 75 insertions(+), 39 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 577eaca6..82b0c80f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -192,7 +192,7 @@ Only `int`, `string` and `float` are supported.
 States: `default`, `checked`, `focused`, `focus_key`, `edited`, `hovered`, `pressed`, `scrolled`, `disabled`.
 Common flags: `hidden`, `clickable`, `checkable`, `scrollable`, `floating`, `ignore_layout`.
 
-`@{ }` is `{ }` that re-runs whenever a referenced subject or variant changes. It works on **widget** attributes (including `style_*` locals) and on a component instance's **variant** attributes — not in `<styles>` (initialized once) and not on a component's own props or slots. It must reference at least one subject or variant, and inside it only `type="subject"` props may appear; other props are an error. A failed re-evaluation (e.g. `/0`) keeps the previous value.
+`@{ }` is `{ }` that re-runs whenever a referenced subject or variant changes. It works on **widget** attributes (including `style_*` locals) and on a component instance's **variant** attributes. Not in `<styles>` (initialized once) and not on a component's own props or slots. It must reference at least one subject or variant, and inside it only `type="subject"` props may appear; other props are an error. A failed re-evaluation (e.g. `/0`) keeps the previous value.
 
 To give each instance its own data, declare `<prop name="temp" type="subject"/>` and pass a subject name at the call site: `<room_card temp="subject_kitchen"/>`.
 
@@ -219,7 +219,7 @@ A component's named visual states, declared in `<api>`. Per-instance and reactiv
 
 Read a variant with `<bind_style subject="<variant>" ref_value="<option>">` (preferred for anything visual) or in `@{ }`, where the variant name is the current option and an option name is a constant.
 
-Pick an option on the instance — `<my_badge size="large" tone="@{subject_level > 100 ? danger : normal}"/>` — or from C with `lv_xml_set_variant(obj, "size", "large")`. Unknown option → `default` + warning. Option names must be unique across a component's variants, a variant name shadows a same-named prop/const/subject, and reordering `options` breaks already exported C.
+Pick an option on the instance, `<my_badge size="large" tone="@{subject_level > 100 ? danger : normal}"/>`, or from C with the exported `my_badge_set_size(obj, MY_BADGE_SIZE_LARGE)` (`lv_xml_set_variant(obj, "size", "large")` at runtime). An unknown option on the instance falls back to `default` with a warning; in `lv_xml_set_variant()` it's refused and the option is left unchanged. Option names must be unique across a component's variants, a variant name shadows a same-named prop/const/subject, and reordering `options` breaks already exported C.
 
 ## Events
 
@@ -249,7 +249,7 @@ Evaluated **once at creation**, not reactive. For anything that changes at runti
 
 `.` concatenates. Strings use single quotes. Comparisons cannot be chained (`a < b < c`) and ternaries cannot be nested.
 
-`&&` and `||` exist, but `&` and `<` must be XML-escaped in an attribute value, so prefer the `and` / `or` keywords: `hidden="{a > 10 and a &lt;= 30}"`. Both sides are always evaluated — there is no short-circuiting.
+`&&` and `||` exist, but `&` and `<` must be XML-escaped in an attribute value, so prefer the `and` / `or` keywords: `hidden="{a > 10 and a &lt;= 30}"`. Both sides are always evaluated, there is no short-circuiting.
 
 ## Animations
 
@@ -292,7 +292,7 @@ The slot target is `<component_name-slot_name>`, and you can set normal object p
 
 - Inventing an attribute instead of reading `lvgl_widgets_xml/`.
 - Putting `$prop` into a `<style>`. Use a local style property.
-- Expecting `{ }` to update at runtime. It does not — write `@{ }` for that.
+- Expecting `{ }` to update at runtime. It does not, write `@{ }` for that.
 - Putting a non-subject `$prop` inside `@{ }`, or `@{ }` on a component's own prop or in a `<style>`. None of them can update.
 - Using `bind_state_*` with a `flag=` attribute, or `bind_flag_*` with `state=`.
 - `screen_load_event` on a screen that isn't `permanent="true"`.
diff --git a/docs/syntax/animations.mdx b/docs/syntax/animations.mdx
index 5c0c8177..8f00844f 100644
--- a/docs/syntax/animations.mdx
+++ b/docs/syntax/animations.mdx
@@ -63,7 +63,7 @@ Within each `timeline`, add individual `<animation>` elements to describe each s
 - `target` - Name of the UI element to animate. `self` refers to the root element of the Component (the `view`).
 - `start` - Start value (integer only).
 - `end` - End value (integer only).
-- `duration` - Duration of the animation in milliseconds.
+- `duration` - Duration of the animation in milliseconds. Default is `1000`.
 - `delay` - Delay before starting in milliseconds. Default is 0.
 - `early_apply` - If `true`, the start value is applied immediately, even during the delay. Default is `false`.
 - `easing` - The animation path, e.g. `ease_out`. See below. Default is `linear`.
@@ -93,7 +93,7 @@ For full control, `bezier(x1 y1 x2 y2)` describes a cubic bezier curve with its
            easing="bezier(0.34 1.56 0.64 1)"/>
 ```
 
-`x1` and `x2` need to be in the `0..1` range, while `y1` and `y2` can be outside it to overshoot. Ready to use curves can be picked from e.g. [easings.net](https://easings.net).
+`x1` and `x2` need to be in the `0..1` range, while `y1` and `y2` can be outside it to overshoot. At most four decimals are used from each value. Ready to use curves can be picked from e.g. [easings.net](https://easings.net).
 
 Finally, an animation path implemented in C can be registered by name and then referenced in `easing`:
 
@@ -103,14 +103,19 @@ static int32_t my_easing(const lv_anim_t * a)
     return lv_map(a->act_time, 0, a->duration, a->start_value, a->end_value);
 }
 
-/* `NULL` registers it globally. It can be a component's scope as well. */
+/* `NULL` registers the name globally, so every XML file can use it.
+ * Pass `lv_xml_component_get_scope("my_component")` to keep it local. */
 lv_xml_register_easing_cb(NULL, "my_easing", my_easing);
 ```
 
+The callback returns the value to apply at the current moment, so it interpolates between `start_value` and `end_value` itself.
+
 ```xml
 <animation prop="translate_y" target="self" start="-30" end="0" duration="500" easing="my_easing"/>
 ```
 
+Register the callback **before** the XML that uses it, as the name is resolved while the XML is being parsed. In the exported code the name is emitted as a plain C function reference, so the function has to be visible to the generated file.
+
 ### Include External Timelines
 
 The `include_timeline` element can be used in a `<timeline>` to reference animations from another timeline. For example, if `my_icon` defines a `"show_up"` timeline that fades in and enlarges the icon, you can include that timeline in other animations without duplicating the code.
diff --git a/docs/syntax/api.mdx b/docs/syntax/api.mdx
index a54facf1..80331afe 100644
--- a/docs/syntax/api.mdx
+++ b/docs/syntax/api.mdx
@@ -45,6 +45,8 @@ lv_obj_t * my_component_create(lv_obj_t * parent, int32_t prop1, const char * pr
 
 These properties are set once at creation time, and there are no specific `set` functions to modify the property later. LVGL's general API can still be used to modify any widget in the component, but no dedicated API functions are generated.
 
+For a value that has to change after creation, use a [variant](./variants) (a named set of options declared in `<api>`, with a generated setter) or a [subject](./data-binding).
+
 ### Slots
 
 With the help of a "slot," any UI element in the component can be easily exposed as a parent where children can be created later.
diff --git a/docs/syntax/data-binding.mdx b/docs/syntax/data-binding.mdx
index 43a64d16..b1e99a2f 100644
--- a/docs/syntax/data-binding.mdx
+++ b/docs/syntax/data-binding.mdx
@@ -167,7 +167,7 @@ The `bind_*` attributes and elements can bind only what they were designed for.
 
 The expression is evaluated when the widget is created, and **re-evaluated whenever any subject it references changes**. The result is applied to the attribute exactly as if you had typed the computed value there.
 
-`@{ }` and `{ }` share the same syntax, operators, and type rules — see [Evaluate expressions](./evaluate). The difference is only *when* they run:
+`@{ }` and `{ }` share the same syntax, operators, and type rules, see [Evaluate expressions](./evaluate). The difference is only *when* they run:
 
 ```xml
 <!-- Updates whenever subject_volume changes -->
@@ -181,10 +181,12 @@ The expression is evaluated when the widget is created, and **re-evaluated whene
 
 Inside `@{ }` names are written as **bare identifiers**, without `$` or `#`:
 
-- **Subjects** - defined in `globals.xml`. An expression should reference at least one subject (or variant), else it could never update, and it's skipped with a warning.
+- **Subjects** - defined in `globals.xml`.
 - **Variants** - the Component's own reactive state. A variant name reads the currently selected option, and the option names can be used as constants. See [Variants](./variants).
 - **Constants** - they are inlined as literals.
-- **`type="subject"` properties** - see below.
+- **`type="subject"` properties** - see [Per-instance subjects](#per-instance-subjects) below.
+
+An expression has to reference at least one subject or variant. Otherwise it could never update, so it's skipped with a warning.
 
 Properties of any other type **cannot** be used, because they exist only while the element is being created. Such a binding is skipped with a warning, but the widget is still created normally.
 
@@ -218,6 +220,8 @@ A binding written in a Component is shared by all of its instances, so referenci
 <room_card temperature="subject_bedroom_temp"/>
 ```
 
+The value has to name an existing subject. If it doesn't, the binding is skipped with a warning. In the exported code such a property becomes an `lv_subject_t *` argument of the Component's create function.
+
 ### Where it can be used
 
 `@{ }` works on the attributes of **widgets**: on the `<view>` itself, on any widget inside it, and on local style properties (`style_bg_color`, `style_pad_all-pressed`, ...). It also works on a Component instance's [variant](./variants) attributes.
@@ -231,7 +235,8 @@ It can't be used in the `<styles>` section, as [styles](./styles) are initialize
 <!-- ❌ `title` is a property of the my_card Component -->
 <my_card title="@{subject_user_name}"/>
 
-<!-- ✅ Bind inside the Component, and pass the subject to it -->
+<!-- ✅ Bind inside the Component, and pass the subject to it
+     (`title_subject` is a `type="subject"` property of my_card) -->
 <my_card title_subject="subject_user_name"/>
 ```
 
@@ -245,7 +250,7 @@ To switch a whole style at runtime, use [`<bind_style>`](./styles#style-binding)
 
 An expression that can't be parsed is reported with a warning and the binding is skipped, so the attribute keeps its default value. The widget itself is always created.
 
-If the evaluation fails only later — a division by zero after a subject became `0`, for example — a warning is logged and the attribute **keeps its previous value** instead of being set to something meaningless.
+If the evaluation fails only later, for example on a division by zero after a subject became `0`, a warning is logged and the attribute **keeps its previous value** instead of being set to something meaningless.
 
 ## Selection groups via a shared subject
 
diff --git a/docs/syntax/evaluate.mdx b/docs/syntax/evaluate.mdx
index 3a9905fb..eeeb8cf5 100644
--- a/docs/syntax/evaluate.mdx
+++ b/docs/syntax/evaluate.mdx
@@ -22,7 +22,7 @@ Expressions are useful whenever a value is *derived* from other values: a width
 A few important properties to keep in mind:
 
 - **Creation-time only.** An expression is evaluated **once**, when the UI element is created. The result is then handed to the normal attribute parser exactly as if you had typed the computed value yourself.
-- **Not reactive.** A `{ }` expression does *not* react to changes. For a value that follows a subject or a variant at runtime, write the very same expression as a binding — `@{ }` instead of `{ }` — see [Expression binding](./data-binding#expression-binding).
+- **Not reactive.** A `{ }` expression does *not* react to changes. For a value that follows a subject or a variant at runtime, write the very same expression as a binding: `@{ }` instead of `{ }`. See [Expression binding](./data-binding#expression-binding).
 - **The result type is inferred from the terms.** You never declare the type — it follows from the literals and variables you use (see [Value types](#value-types)).
 
 <Callout type="info">
@@ -39,11 +39,11 @@ An expression is the whole attribute value, wrapped in a single pair of braces:
 
 Inside the braces you can use literals, operators, and **variable names**. A variable name is written as a **bare identifier** — without the `$` or `#` prefixes used elsewhere in XML. The name is resolved, in order, against:
 
-1. **Variants** declared in the element's [`<api>`](./api) — the currently selected option of that [variant](./variants).
-2. **Parameters** declared in the element's [`<api>`](./api) — the value comes from the instance (or the parameter's `default`), and the type from the declared `type`.
-3. **Constants** from [`<consts>`](./constants) — the type is inferred from the constant's value.
-4. **Variant option names** — an integer constant, the option's index in its variant.
-5. **Subjects** from `globals.xml` — their current value, read once (use `@{ }` to follow them).
+1. **Variants** declared in the element's [`<api>`](./api): the currently selected option of that [variant](./variants).
+2. **Parameters** declared in the element's [`<api>`](./api): the value comes from the instance (or the parameter's `default`), and the type from the declared `type`.
+3. **Constants** from [`<consts>`](./constants): the type is inferred from the constant's value.
+4. **Variant option names**: an integer constant, the option's index in its variant.
+5. **Subjects** from `globals.xml`: their current value, read once (use `@{ }` to follow them).
 6. **Other named items** the XML processor resolves later (a font, image, or screen name). These are passed through as plain strings.
 
 ```xml
@@ -118,7 +118,7 @@ The unary `!` accepts a number, bool, or string and returns a bool. An empty or
 
 `&&` and `||` combine two conditions and return a bool. Their operands can be anything that has a truthiness: a bool, a number (non-zero is true), or a string (non-empty is true). A color has none, so it's a type error.
 
-Because `&` must be escaped in an XML attribute value, both operators also have a keyword spelling — `and` and `or` — which is usually the readable choice:
+Because `&` must be escaped in an XML attribute value, both operators also have a keyword spelling, `and` and `or`, which is usually the readable choice:
 
 ```xml
 <!-- These two are identical -->
@@ -126,14 +126,14 @@ Because `&` must be escaped in an XML attribute value, both operators also have
 <lv_obj hidden="{temperature > 10 &amp;&amp; temperature &lt;= 30}"/>
 ```
 
-`&&` binds tighter than `||`, and both bind tighter than the ternary, so a range check reads naturally as a condition:
+`&&` binds tighter than `||`, and both bind tighter than concatenation and the ternary. So a combined condition can be written directly as a ternary condition, without parentheses:
 
 ```xml
 <lv_label text="{level > 80 or charging ? 'OK' : 'Low'}"/>
 ```
 
 <Callout type="warn">
-Both sides are **always evaluated** — there is no short-circuiting (same as with the two ternary branches). So `count != 0 and total / count > 5` still fails on a division by zero when `count` is 0.
+Both sides are **always evaluated**. There is no short-circuiting, just like with the two ternary branches. So `count != 0 and total / count > 5` still fails on a division by zero when `count` is 0.
 </Callout>
 
 `and`/`or` are keywords, so a constant, property, or subject cannot be named `and` or `or`. There is no `^^` operator.
@@ -185,8 +185,8 @@ An expression lives in an XML attribute value, where a few characters are reserv
 | Character | Write it as | Note |
 |---|---|---|
 | `<` | `&lt;` | Never allowed in an attribute value |
-| `&` | `&amp;` | So `&&` becomes `&amp;&amp;` — or use `and` |
-| `'` | `&apos;` | Only inside a `'…'` delimited value |
+| `&` | `&amp;` | So `&&` becomes `&amp;&amp;`. Or use `and` |
+| `'` | `&apos;` | Only if the attribute value itself is delimited by `'` |
 | `>` | `>` | Allowed as-is |
 
 ```xml
@@ -199,18 +199,23 @@ An expression lives in an XML attribute value, where a few characters are reserv
 <!-- ✅ or turn the comparison around and avoid the escape entirely -->
 <lv_obj hidden="{10 > count and locked}"/>
 ```
+
 ## Error handling
 
-If an expression is malformed — an unknown identifier, a type mismatch, a missing `)` or `:`, division by zero, and so on — evaluation fails. A warning describing the exact problem and the offending expression is logged, and the attribute is left unset.
+If an expression is malformed, for example a type mismatch, a missing `)` or `:`, or a division by zero, evaluation fails. A warning naming the exact problem and the offending expression is logged, and the raw `{ … }` text is left in the attribute, which the normal attribute parser then reads as `0` or as literal text.
 
 Common messages include:
 
-- *unknown identifier* — the name is not a const, or prop.
 - *the two ternary branches must have the same type*.
-- *`< <= > >=` need numeric operands* — use `==`/`!=` for strings, colors, and bools.
+- *the two sides of `==`/`!=` have different types*.
+- *`< <= > >=` need numeric operands (use `==`/`!=` for strings, colors, bools)*.
 - *arithmetic `+ - * / %` needs numeric operands*.
+- *`%` needs integer operands*.
+- *division or modulo by zero*.
 - *unexpected character (note: use `==` to compare, `.` to concatenate)*.
 
+A name that is not a variant, parameter, constant, variant option, or subject is **not** an error: it's kept as a plain string, as [Writing expressions](#writing-expressions) describes. A typo in a name therefore shows up as a type error, or later as a "not found" warning from whatever resolves the value (a font, an image, and so on).
+
 ## Examples
 
 ```xml
diff --git a/docs/syntax/styles.mdx b/docs/syntax/styles.mdx
index bfea2fd8..28586500 100644
--- a/docs/syntax/styles.mdx
+++ b/docs/syntax/styles.mdx
@@ -79,7 +79,7 @@ By default the properties of a style are applied immediately when the widget's s
 
 `<transition>` supports these properties:
 
-- `props` - Space separated list of the style properties to animate. Use `remove` to delete a previously set transition.
+- `props` - Space separated list of the style properties to animate. Mandatory. Use `remove` to delete a previously set transition.
 - `duration` - Duration of the animation in milliseconds. Mandatory.
 - `delay` - Delay before the animation starts in milliseconds. Default is `0`.
 - `easing` - The animation path, e.g. `ease_out`. See [Easing](./animations#easing). Default is `linear`.
@@ -185,7 +185,7 @@ Instead of setting local style properties directly, you can bind them to subject
 </component>
 ```
 
-`<bind_style_prop>` copies a subject's value into the property as-is. To compute the value, write an [expression binding](./data-binding#expression-binding) on the local style property itself — selectors included:
+`<bind_style_prop>` copies a subject's value into the property as-is. To compute the value, write an [expression binding](./data-binding#expression-binding) on the local style property itself, selectors included:
 
 ```xml
 <lv_label style_text_color-pressed="@{subject_error_mode ? 0xff0000 : 0xaaaaaa}"/>
diff --git a/docs/syntax/variants.mdx b/docs/syntax/variants.mdx
index 5de16e6b..2e5c7b7f 100644
--- a/docs/syntax/variants.mdx
+++ b/docs/syntax/variants.mdx
@@ -3,7 +3,7 @@ title: Variants
 description: Declare a Component's visual variations, like size or tone, and switch between them at runtime.
 ---
 
-Most Components exist in a few flavors: a button that is `small` or `large`, a badge that is `normal` or `danger`. A **variant** declares such a dimension once, and every instance can pick an option from it — statically, from a subject, or from C at runtime.
+Most Components exist in a few flavors: a button that is `small` or `large`, a badge that is `normal` or `danger`. A **variant** declares such a dimension once, and every instance can pick an option from it: statically, from a subject, or from C at runtime.
 
 ```xml
 <my_badge size="large" tone="danger"/>
@@ -25,10 +25,12 @@ A variant is a named list of options, declared in the Component's [`<api>`](./ap
 </component>
 ```
 
-- `name` - The name of the variant. It becomes a property of the Component.
+- `name` - The name of the variant. It becomes an attribute of the Component, set like a property where the Component is used.
 - `options` - Space separated list of the option names.
 - `default` - The option to use when the instance doesn't set one. If it's missing or unknown, the first option is used.
 
+A variant is not an [`<api>`](./api) property, so it can't be read with `$name`. Read it with [`<bind_style>`](./styles#style-binding) or in an expression, as shown below.
+
 Each variant is **per-instance reactive state**: ten instances of the same Component can be in ten different states, and switching one of them updates only that instance. This makes variants the Component-level counterpart of [subjects](./data-binding), which are global.
 
 <Callout type="info">
@@ -84,7 +86,7 @@ A variant can also be used in [`@{ }` bindings](./data-binding#expression-bindin
 <lv_label name="subtitle" text="Subtitle" hidden="@{size == small}"/>
 
 <!-- A variant and a global subject in one expression -->
-<lv_label text="@{mode == on ? 'n=' . subject_count : 'off'}"/>
+<lv_label text="@{tone == danger ? 'Alert: ' . subject_error_count : 'All good'}"/>
 ```
 
 Because `@{ }` re-evaluates on every change, switching the variant updates these attributes immediately. In a plain [`{ }` expression](./evaluate) a variant works too, but it's read only once, when the element is created.
@@ -111,27 +113,44 @@ Note that such a binding is evaluated in the **surrounding** element's scope: `s
 
 ### From C
 
+Each variant becomes an enum plus a typed setter and getter in the exported code:
+
+```c
+/* my_badge.h */
+typedef enum {
+    MY_BADGE_SIZE_SMALL = 0,
+    MY_BADGE_SIZE_LARGE = 1
+} my_badge_size_t;
+
+void my_badge_set_size(lv_obj_t * obj, my_badge_size_t size);
+my_badge_size_t my_badge_get_size(lv_obj_t * obj);
+```
+
+When the XML is loaded at runtime instead (in the Editor's preview, or with `lv_xml_create()`), select an option by name:
+
 ```c
 lv_xml_set_variant(badge, "size", "large");
 ```
 
-The variant is searched on the given widget and then up along its parents, so passing any widget inside a Component instance works too. Every `bind_style` and `@{ }` expression referencing the variant updates immediately.
+Both look the variant up on the given widget and then on its parents, so any widget inside a Component instance can be passed. Every `bind_style` and `@{ }` expression referencing the variant updates immediately.
+
+An option name `lv_xml_set_variant()` doesn't recognize is refused with a warning, and the variant keeps its current option. This also applies to a variant binding whose expression returns something that is not an option name.
 
 ## Name resolution
 
 Inside expressions a bare identifier is resolved in this order:
 
-1. **variant name**
-2. `<api>` property
-3. constant
-4. variant option name
-5. subject
-6. anything else is kept as a plain string (a font or image name, for example)
+1. **Variant name**
+2. **`<api>` property**
+3. **Constant**
+4. **Variant option name**
+5. **Subject**
+6. Anything else is kept as a plain string (a font or image name, for example)
 
 Two consequences worth remembering:
 
 - A variant **shadows** a property, constant, or subject of the same name. Avoid such collisions.
-- **Option names have to be unique across a Component's variants**, otherwise a bare option name in an expression is ambiguous — the first declared variant wins, and registration logs a warning. `<bind_style>` is exempt, since its `subject` attribute already tells which variant the `ref_value` belongs to.
+- **Option names have to be unique across a Component's variants**, otherwise a bare option name in an expression is ambiguous. The first declared variant wins, and registration logs a warning. `<bind_style>` is exempt, since its `subject` attribute already tells which variant the `ref_value` belongs to.
 
 <Callout type="warn">
 The order of `options` defines the integer value of each option in the exported C code. Reordering them is a breaking change for code that was already generated; adding new options at the end is safe.

From af4f8b7d651796041a272ff46b26210bc195f318 Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Sat, 8 Aug 2026 17:49:09 +0200
Subject: [PATCH 3/6] cleanup

---
 docs/syntax/animations.mdx   |  41 +++---
 docs/syntax/api.mdx          |  61 +++++++--
 docs/syntax/data-binding.mdx | 253 +++++++++++------------------------
 docs/syntax/evaluate.mdx     |  87 ++++++------
 docs/syntax/styles.mdx       |   2 +-
 docs/syntax/variants.mdx     |  52 ++-----
 6 files changed, 202 insertions(+), 294 deletions(-)

diff --git a/docs/syntax/animations.mdx b/docs/syntax/animations.mdx
index 8f00844f..aaa0aadd 100644
--- a/docs/syntax/animations.mdx
+++ b/docs/syntax/animations.mdx
@@ -7,15 +7,17 @@ Create smooth, professional animations for your UI components using LVGL's timel
 
 ## Overview
 
-XML animations are built on timeline animations that organize multiple animation steps into coordinated sequences.
+XML animations are used to animate one or more widgets and their properties. They are built from timeline animations that organize multiple animation steps into coordinated sequences.
 
 Timelines are composed of simple animations. For example: *"change the `bg_opa` of `my_button_2` from 0 to 255 in 500 ms."*
 
 Each Component can define its own timeline animations, which can then be played by the Component itself or by any parent Components.
 
+Style [`<transition>`](./styles#transitions)s can animate widgets too. The difference is what starts them: a timeline is played on demand, while a transition runs when the widget's state changes, for example from default to pressed.
+
 ## Defining Timelines
 
-Timelines can be defined inside [`<screen>`](./screens)s and [`<component>`](./components)s. 
+Timelines can be defined inside [`<screen>`](./screens)s and [`<component>`](./components)s.
 
 Example:
 
@@ -31,9 +33,9 @@ Example:
 
   <!-- Shake horizontally -->
   <timeline name="shake" repeat_count="infinite" repeat_delay="200">
-   <animation prop="translate_x" target="self" start="0" end="-30" duration="150"/>
-   <animation prop="translate_x" target="self" start="-30" end="30" duration="300" delay="150"/>
-   <animation prop="translate_x" target="self" start="30" end="0" duration="150" delay="450"/>
+   <animation prop="translate_x" target="self" start="0" end="-30" duration="150" easing="ease_in_out"/>
+   <animation prop="translate_x" target="self" start="-30" end="30" duration="300" delay="150" easing="ease_in_out"/>
+   <animation prop="translate_x" target="self" start="30" end="0" duration="150" delay="450" easing="ease_in_out"/>
   </timeline>
  </animations>
 
@@ -54,7 +56,7 @@ Inside `<animations>`, you can define `<timeline>`s with unique names that you c
 - `repeat_count` - How many times the whole timeline repeats. Use a number, or `infinite` to loop forever. Default is `1`.
 - `repeat_delay` - Delay in milliseconds between repetitions. Default is `0`.
 
-### Simple Animations 
+### Simple Animations
 
 Within each `timeline`, add individual `<animation>` elements to describe each step. The following properties are supported:
 
@@ -70,9 +72,7 @@ Within each `timeline`, add individual `<animation>` elements to describe each s
 
 ### Easing
 
-The `easing` property tells how the value should progress from `start` to `end` during the `duration`. Besides `<animation>`, style [`<transition>`](./styles#transitions)s support it too.
-
-These built-in paths can be used:
+The `easing` property tells how the value should progress from `start` to `end` during the `duration`. These built-in paths can be used:
 
 - `linear` - Constant speed. This is the default.
 - `ease_in` - Slow start.
@@ -95,26 +95,21 @@ For full control, `bezier(x1 y1 x2 y2)` describes a cubic bezier curve with its
 
 `x1` and `x2` need to be in the `0..1` range, while `y1` and `y2` can be outside it to overshoot. At most four decimals are used from each value. Ready to use curves can be picked from e.g. [easings.net](https://easings.net).
 
-Finally, an animation path implemented in C can be registered by name and then referenced in `easing`:
+Finally, an animation path implemented in C can be referenced by its function name:
+
+```xml
+<animation prop="translate_y" target="self" start="-30" end="0" duration="500" easing="my_easing"/>
+```
 
 ```c
-static int32_t my_easing(const lv_anim_t * a)
+int32_t my_easing(const lv_anim_t * a)
 {
+    /*Return the value to apply now, interpolating between start_value and end_value*/
     return lv_map(a->act_time, 0, a->duration, a->start_value, a->end_value);
 }
-
-/* `NULL` registers the name globally, so every XML file can use it.
- * Pass `lv_xml_component_get_scope("my_component")` to keep it local. */
-lv_xml_register_easing_cb(NULL, "my_easing", my_easing);
-```
-
-The callback returns the value to apply at the current moment, so it interpolates between `start_value` and `end_value` itself.
-
-```xml
-<animation prop="translate_y" target="self" start="-30" end="0" duration="500" easing="my_easing"/>
 ```
 
-Register the callback **before** the XML that uses it, as the name is resolved while the XML is being parsed. In the exported code the name is emitted as a plain C function reference, so the function has to be visible to the generated file.
+The exported code calls this function directly, so it can't be `static` and it has to be visible where the generated file is compiled.
 
 ### Include External Timelines
 
@@ -144,4 +139,4 @@ The created timeline instances and their names are saved in the Component's inst
 
 When a `play_timeline_event` is added to a UI element, the target and timeline names are saved as strings. Pointers cannot be used because the event can reference UI elements that will be created only later in the `view`.
 
-Finally, when the play timeline event is triggered, the selected timeline is retrieved by its name from the target and started according to the other parameters (reverse, delay, and so on).
\ No newline at end of file
+Finally, when the play timeline event is triggered, the selected timeline is retrieved by its name from the target and started according to the other parameters (reverse, delay, and so on).
diff --git a/docs/syntax/api.mdx b/docs/syntax/api.mdx
index 80331afe..e716141e 100644
--- a/docs/syntax/api.mdx
+++ b/docs/syntax/api.mdx
@@ -61,8 +61,7 @@ Slots are very useful for creating components like screen templates where users
 
 It's also possible to change the basic `lv_obj` properties on the slots, such as `hidden="true"`, `style_bg_color-pressed="0xff0000"`, `checked="true"`, `width="100"`, etc.
 
-
-#### Slots Example
+The example below shows it in the practice:
 
 ```xml
 <!-- simple_screen.xml -->
@@ -81,7 +80,7 @@ It's also possible to change the basic `lv_obj` properties on the slots, such as
 <!-- main_screen.xml -->
 <component>
   <styles>
-    <styles name="style_thin_border" border_width="1" border_color="0x800"/>
+    <style name="style_thin_border" border_width="1" border_color="0x800"/>
   </styles>
   <view extends="simple_screen" width="100%">
 
@@ -100,6 +99,46 @@ It's also possible to change the basic `lv_obj` properties on the slots, such as
 </component>
 ```
 
+### Variants
+
+Besides `<prop>`s, a Component can declare **variants**: named lists of options that can be changed after creation. Unlike properties, a variant keeps its value per instance, so `<bind_style>` and [data bindings](./data-binding) can follow it at runtime.
+
+`badge.xml`
+
+```xml
+<component>
+  <api>
+    <variants>
+      <variant name="tone" options="normal danger" default="normal"/>
+    </variants>
+  </api>
+
+  <styles>
+    <style name="style_danger" bg_color="0xff0000" text_color="0xffffff"/>
+  </styles>
+
+  <view extends="lv_obj" width="content" height="content">
+    <bind_style name="style_danger" if="tone == danger"/>
+    <lv_label name="label" text="Ready"/>
+    <lv_image name="alert_icon" src="img_alert" hidden="@{tone == normal}"/>
+  </view>
+</component>
+```
+
+`screen1.xml`
+
+```xml
+<screen>
+  <view flex_flow="row">
+    <badge/>                 <!-- `normal`, the default -->
+    <badge tone="danger"/>
+    <badge tone="@{subject_alarm_count > 0 ? danger : normal}"/>
+  </view>
+</screen>
+```
+
+Learn more about variants on their [dedicated page](./variants).
+
 ### Limitations
 
 Component APIs support only simple properties that are forwarded. The following Widget API features cannot be used for Components:
@@ -246,7 +285,7 @@ Used in a view:
   <my_widget width="100px">
     <my_widget-indicator name="indic1" color="0xff0000" max_value="120" value="30"/>
   </my_widget>
-</view>  
+</view>
 ```
 
 LVGL's UI Editor generates:
@@ -272,11 +311,11 @@ Used for internal or implicit elements:
 Used in a view:
 
 ```xml
-<view>  
+<view>
   <my_widget width="100px">
     <my_widget-control_button name="btn1" index="3" title="Hello"/>
   </my_widget>
-</view>  
+</view>
 ```
 
 LVGL's UI Editor generates:
@@ -303,11 +342,11 @@ Used for indexed access, like setting values in a table:
 Used in a view:
 
 ```xml
-<view>  
+<view>
   <my_widget width="100px">
     <my_widget-item index="3" icon="image1" color="0xff0000"/>
   </my_widget>
-</view>  
+</view>
 ```
 
 LVGL's UI Editor generates:
@@ -332,15 +371,15 @@ Used to describe custom API functions with a custom name. Custom elements can ha
 Used in a view:
 
 ```xml
-<view>  
+<view>
   <my_widget width="100px">
     <my_widget-bind_color subject="subject_1" new_color="0xff0000" ref_value="15"/>
   </my_widget>
-</view>  
+</view>
 ```
 
 LVGL's UI Editor generates:
 
 ```c
 void my_widget_bind_color(lv_obj_t * parent, lv_subject_t * subject, lv_color_t color, int32_t ref_value);
-```
\ No newline at end of file
+```
diff --git a/docs/syntax/data-binding.mdx b/docs/syntax/data-binding.mdx
index b1e99a2f..21b5d584 100644
--- a/docs/syntax/data-binding.mdx
+++ b/docs/syntax/data-binding.mdx
@@ -6,12 +6,12 @@ faqs:
     answer: "Integer, string, and float types are supported for subjects. You define them in globals.xml using <int>, <string>, or <float> tags with a name and initial value."
   - question: "How do I update a subject value from my C code?"
     answer: "Use the generated setter functions in your application code. For a subject named 'battery_power', call set_battery_power(value) to update it. All widgets bound to that subject will automatically update."
-  - question: "What's the difference between simple and complex binding?"
-    answer: "Simple binding directly binds a subject to a widget property using attributes like bind_text or bind_value. Complex binding uses child elements to add conditional logic with multiple subjects and parameters, like bind_flag_if_eq or bind_state_if_gt."
+  - question: "What's the difference between a generic and a widget specific binding?"
+    answer: "A generic binding wraps an expression in @{ } and works on any widget property, with any number of subjects and variants. A widget specific binding is a dedicated bind_* property, like bind_text or bind_value, that takes a single subject without an expression and is often two-way."
   - question: "Can multiple widgets bind to the same subject?"
     answer: "Yes! Multiple widgets can bind to the same subject. When the subject's value changes (either from code or user interaction), all bound widgets automatically update to reflect the new value."
   - question: "How do I use data binding to show or hide a widget?"
-    answer: "Use complex binding with the 'hidden' flag. For example: <lv_obj-bind_flag_if_eq subject=\"some_value\" flag=\"hidden\" ref_value=\"0\"/> will hide the widget when some_value equals 0."
+    answer: "Bind the 'hidden' property to a condition. For example: <lv_obj hidden=\"@{some_subject == 0}\"/> will hide the widget when some_subject equals 0."
 ---
 
 ## Overview
@@ -23,7 +23,7 @@ application or the UI, and whose value can be bound to widget
 properties.
 
 <Callout type="info">
-Designing in Figma? You can bind layers to subjects directly in the plugin, no code required. See [Subjects & Data Binding in Figma Flow](../figma/subjects).
+Designing in Figma? You can bind layers to subjects directly in the Figma plugin, no code required. See [Subjects & Data Binding in Figma Flow](../figma/subjects).
 </Callout>
 
 For example, a `room1_temperature` subject's value can be set in the
@@ -31,9 +31,12 @@ application when the temperature is measured, and can be bound to a
 label like this:
 
 ```xml
-<lv_label bind_text="room1_temperature"/>
+<!-- Wrap subjects and expressions in @{ } to create a binding. -->
+<lv_label text="@{room1_temperature}"/>
 ```
 
+Some widgets also define dedicated `bind_*` properties, for example `<lv_slider bind_value="subject_1"/>`. They take a single subject without an expression, and most of them are two way. See [Widget specific bindings](#widget-specific-bindings).
+
 ## Defining subjects
 
 Subjects can be created in `globals.xml` like this:
@@ -55,150 +58,59 @@ value. Integer, string, and float types are supported.
 Float subjects require `LV_USE_FLOAT` to be enabled in `lv_conf.h`. Without it, the generated code fails to compile.
 </Callout>
 
-## Simple binding
-
-Some widgets (e.g., label, slider) support binding the subject's value
-directly to the widget. These bindings use attributes that start with
-`bind_*` and reference a subject.
-
-```xml
-<lv_slider bind_value="some_subject"/>
-<lv_label bind_text="some_subject"/>
-```
-
-Once a binding is created, if the subject's value changes (e.g., by
-adjusting the slider), all bound widgets will be updated automatically.
-
-## Complex binding
-
-In more complex cases---when a binding requires multiple
-parameters---the binding can be added as a child element of a widget.
-This allows binding multiple subjects with different parameters. For
-example:
-
-```xml
-<lv_label text="Hello world">
-  <lv_obj-bind_flag_if_eq subject="subject1" flag="hidden" ref_value="10"/>
-  <lv_obj-bind_flag_if_gt subject="subject1" flag="clickable" ref_value="20"/>
-</lv_label>
-```
-
-Explanation of complex bindings:
-
-| Binding Type | Condition | Description |
-| --- | --- | --- |
-| `bind_flag_if_eq` | Equals | Set a flag if the subject's value equals the reference value |
-| `bind_flag_if_not_eq` | Not equals | Set a flag if the subject's value does not equal the reference value |
-| `bind_flag_if_gt` | Greater than | Set a flag if the subject's value is greater than the reference value |
-| `bind_flag_if_ge` | Greater or equal | Set a flag if the subject's value is greater than or equal to the reference value |
-| `bind_flag_if_lt` | Less than | Set a flag if the subject's value is less than the reference value |
-| `bind_flag_if_le` | Less or equal | Set a flag if the subject's value is less than or equal to the reference value |
-| `bind_state_if_eq` | Equals | Set a state if the subject's value equals the reference value |
-| `bind_state_if_not_eq` | Not equals | Set a state if the subject's value does not equal the reference value |
-| `bind_state_if_gt` | Greater than | Set a state if the subject's value is greater than the reference value |
-| `bind_state_if_ge` | Greater or equal | Set a state if the subject's value is greater than or equal to the reference value |
-| `bind_state_if_lt` | Less than | Set a state if the subject's value is less than the reference value |
-| `bind_state_if_le` | Less or equal | Set a state if the subject's value is less than or equal to the reference value |
-
-Note: The `lv_obj-` prefix can be omitted. For example, you can simply
-write `bind_state_if_gt` instead.
+## Binding widget properties
 
-### Choosing the right attribute
+### Generic bindings with expressions
 
-`bind_flag_*` and `bind_state_*` look almost identical but expect a different attribute and a different set of values:
-
-- `bind_flag_*` toggles a widget **flag** — use the `flag` attribute.
-- `bind_state_*` toggles a widget **state** — use the `state` attribute.
+The simplest way to create bindings is to wrap subjects and optional expressions into `@{ }`. For example:
 
 ```xml
-<!-- Set the "hidden" flag while subject_mode != 1 -->
-<lv_obj>
-  <bind_flag_if_not_eq subject="subject_mode" flag="hidden" ref_value="1"/>
-</lv_obj>
-
-<!-- Enter the "checked" state while subject_lamp == 2 -->
-<lv_obj>
-  <bind_state_if_eq subject="subject_lamp" state="checked" ref_value="2"/>
-</lv_obj>
+<lv_label text="@{'My name is ' . subject_first_name . ' ' . subject_last_name}"
+          hidden="@{variant_mode == no_details}"/>
 ```
 
-### Valid state values
-
-These match LVGL's `LV_STATE_*` constants. The same names are used as style selectors and in `bind_state_*` bindings.
-
-| Value | Meaning |
-|---|---|
-| `default` | Widget is in its base state |
-| `checked` | Widget is toggled on (e.g. a checkable button) |
-| `focused` | Widget has focus from any input device |
-| `focus_key` | Widget has focus from a keypad/encoder |
-| `edited` | Widget is being edited (e.g. encoder edit mode) |
-| `hovered` | Pointer is over the widget |
-| `pressed` | Widget is currently pressed |
-| `scrolled` | Widget is being scrolled |
-| `disabled` | Widget rejects input |
+These expressions support
 
-### Valid flag values
+- multiple subjects
+- variants
+- basic arithmetic, ternaries, and logic operators
 
-The most commonly bound `LV_OBJ_FLAG_*` flags, exposed by the same names without the prefix:
+Inside `@{ }` names are written as **bare identifiers** (without `$` or `#`). The following symbols can be used:
 
-| Value | Effect when set |
-|---|---|
-| `hidden` | Widget is not drawn and ignores input |
-| `clickable` | Widget can be pressed/clicked |
-| `checkable` | Click toggles the `checked` state |
-| `scrollable` | Widget can be scrolled |
-| `scroll_on_focus` | Parent scrolls so the focused child is visible |
-| `floating` | Excluded from the parent's layout |
-| `ignore_layout` | Ignored by the parent's layout |
+- **Subjects** - defined in `globals.xml`.
+- **Variants** - the Component's own reactive state. A variant name reads the currently selected option, and the option names can be used as constants. See [Variants](./variants).
+- **Constants** - they are inlined as literals.
+- **`type="subject"` properties** - see [Per-instance subjects](#per-instance-subjects) below.
 
-For the full list of states and flags see LVGL's [Object basics](https://lvgl.io/docs/open/intro/basics) and [Style states](https://lvgl.io/docs/open/main-modules/style#states) reference.
+Properties (`<prop>`) of types other than subject cannot be used, because they exist only while the element is being created. Such a binding is skipped with a warning, but the widget is still created normally.
 
-## Expression binding
+`@{ }` works on the attributes of **widgets**: on the `<view>` itself, on any widget inside it, and on local style properties (`style_bg_color`, `style_pad_all-pressed`, ...). On a Component instance only its [variant](./variants) attributes can be bound.
 
-The `bind_*` attributes and elements can bind only what they were designed for. To bind **any** widget attribute to **any** expression of subjects, wrap the expression in `@{ }`:
+It can't be used in the `<styles>` section, as [styles](./styles) are initialized only once, and not on the attributes of a Component instance either:
 
 ```xml
-<lv_label text="@{'Battery: ' . subject_battery . '%'}"/>
-<lv_obj width="@{subject_column_count * 100}"/>
-<lv_obj hidden="@{subject_unread == 0}"/>
-<lv_obj style_bg_color="@{subject_temp > 30 ? 0xff0000 : 0x00ff00}"/>
-```
+<!-- ❌ A style is initialized once, so it can't be bound -->
+<style name="style_main" bg_color="@{subject_theme_color}"/>
 
-The expression is evaluated when the widget is created, and **re-evaluated whenever any subject it references changes**. The result is applied to the attribute exactly as if you had typed the computed value there.
+<!-- ❌ `title` is a property of the my_card Component -->
+<my_card title="@{subject_user_name}"/>
 
-`@{ }` and `{ }` share the same syntax, operators, and type rules, see [Evaluate expressions](./evaluate). The difference is only *when* they run:
+<!-- ✅ `tone` is a variant of my_card -->
+<my_card tone="@{subject_alarm == 1 ? danger : normal}"/>
 
-```xml
-<!-- Updates whenever subject_volume changes -->
-<lv_label text="@{'Volume: ' . subject_volume}"/>
+<!-- ✅ `tone` is a variant of my_card -->
+<my_card tone="@{subject_alarm == 1 ? danger : normal}"/>
 
-<!-- Evaluated once, when the label is created -->
-<lv_label text="{'Volume: ' . subject_volume}"/>
+<!-- ✅ Bind inside the Component, and pass the subject to it
+     (`title_subject` is a `type="subject"` property of my_card) -->
+<my_card title_subject="subject_user_name"/>
 ```
 
-### What can be referenced
-
-Inside `@{ }` names are written as **bare identifiers**, without `$` or `#`:
-
-- **Subjects** - defined in `globals.xml`.
-- **Variants** - the Component's own reactive state. A variant name reads the currently selected option, and the option names can be used as constants. See [Variants](./variants).
-- **Constants** - they are inlined as literals.
-- **`type="subject"` properties** - see [Per-instance subjects](#per-instance-subjects) below.
-
-An expression has to reference at least one subject or variant. Otherwise it could never update, so it's skipped with a warning.
-
-Properties of any other type **cannot** be used, because they exist only while the element is being created. Such a binding is skipped with a warning, but the widget is still created normally.
-
-Several subjects can be used in one expression, and a change of any of them re-evaluates it:
-
-```xml
-<lv_obj width="@{subject_cell_width * subject_column_count}"/>
-```
+Learn more about the details on the [Evaluate expressions](./evaluate) page.
 
 ### Per-instance subjects
 
-A binding written in a Component is shared by all of its instances, so referencing a subject by name makes every instance follow the *same* subject. To let each instance follow a *different* one, declare a `type="subject"` property and pass the subject's name where the Component is used:
+Referencing a subject by name in the component makes every instance follow the *same* subject. To let each instance follow a *different* one, declare a `type="subject"` property and pass the subject's name where the Component is used:
 
 ```xml
 <!-- room_card.xml -->
@@ -220,85 +132,72 @@ A binding written in a Component is shared by all of its instances, so referenci
 <room_card temperature="subject_bedroom_temp"/>
 ```
 
-The value has to name an existing subject. If it doesn't, the binding is skipped with a warning. In the exported code such a property becomes an `lv_subject_t *` argument of the Component's create function.
-
-### Where it can be used
+The value has to name an existing subject. If it doesn't, the binding is skipped with a warning.
 
-`@{ }` works on the attributes of **widgets**: on the `<view>` itself, on any widget inside it, and on local style properties (`style_bg_color`, `style_pad_all-pressed`, ...). It also works on a Component instance's [variant](./variants) attributes.
+### Widget specific bindings
 
-It can't be used in the `<styles>` section, as [styles](./styles) are initialized only once, nor on the normal properties of a Component instance:
+Some widgets (e.g., label, slider) support binding the subject's value
+directly to the widget. These bindings use attributes that start with
+`bind_*` and reference a subject.
 
 ```xml
-<!-- ❌ A style is initialized once, so it can't be bound -->
-<style name="style_main" bg_color="@{subject_theme_color}"/>
+<lv_slider bind_value="some_subject"/>
+<lv_label bind_text="some_subject" bind_text-fmt="%03d Volts"/>
+```
 
-<!-- ❌ `title` is a property of the my_card Component -->
-<my_card title="@{subject_user_name}"/>
+Most of these are two way bindings: the widget can set the subject and the subject can set the widget too. If the subject's value changes (for example because the user dragged the slider), every widget bound to it is updated automatically.
 
-<!-- ✅ Bind inside the Component, and pass the subject to it
-     (`title_subject` is a `type="subject"` property of my_card) -->
-<my_card title_subject="subject_user_name"/>
-```
+`lv_label` also accepts a format string, which `@{ }` cannot do, so `bind_text` is the way to control the number of digits or decimals.
 
-To switch a whole style at runtime, use [`<bind_style>`](./styles#style-binding), which takes the same kind of expression in its `if` attribute:
+### Old syntax
+
+Before `@{ }` existed, flags and states were bound like this:
 
 ```xml
-<bind_style name="style_warning" if="subject_temp > 10 and subject_temp &lt;= 30"/>
+<lv_label text="Hello world">
+  <lv_obj-bind_flag_if_eq subject="subject1" flag="hidden" ref_value="10"/>
+  <lv_obj-bind_state_if_gt subject="subject1" state="checked" ref_value="20"/>
+</lv_label>
 ```
 
-### Errors
+`bind_flag_*` takes a `flag`, `bind_state_*` takes a `state`, and both come in `_eq`, `_not_eq`, `_gt`, `_ge`, `_lt`, and `_le` variants. The `lv_obj-` prefix is optional.
 
-An expression that can't be parsed is reported with a warning and the binding is skipped, so the attribute keeps its default value. The widget itself is always created.
+These still work, but `@{ }` is more powerful and replaces all of them, so it's recommended to migrate:
 
-If the evaluation fails only later, for example on a division by zero after a subject became `0`, a warning is logged and the attribute **keeps its previous value** instead of being set to something meaningless.
+```xml
+<lv_label text="Hello world" hidden="@{subject1 == 10}" checked="@{subject1 > 20}"/>
+```
 
-## Selection groups via a shared subject
+## Variants
 
-A common pattern is to express "exactly one of these widgets is active" with a single integer subject and one `ref_value` per option. Combining `subject_set_int_event` (writes the subject on click) with `bind_state_if_eq` (reads it to drive the `checked` state) produces a runtime-driven radio group with no application code.
+A subject is global, but a Component often needs reactive state of its own, for example whether a badge is `normal` or `danger`. That is what a [variant](./variants) is: a named list of options declared in the Component's `<api>`, with its own value in every instance.
+
+Variants are used in bindings exactly like subjects:
 
 ```xml
-<!-- globals.xml -->
-<subjects>
-  <int name="subject_lamp" value="0"/>
-</subjects>
+<!-- Inside the Component that declares the `tone` variant -->
+<bind_style name="style_danger" if="tone == danger"/>
+<lv_label text="@{tone == danger ? 'Alert' : 'All good'}"/>
 ```
 
 ```xml
-<!-- lamp_cell.xml — one cell instantiated per option -->
-<component>
-  <api>
-    <prop name="label" type="string" default="Lamp"/>
-    <prop name="ref_value" type="int" default="0"/>
-  </api>
-
-  <view extends="lv_obj" width="content" height="content" flex_flow="column">
-    <lv_label text="$label"/>
+<!-- Where the Component is used, the variant can follow a subject -->
+<my_badge tone="@{subject_alarm == 1 ? danger : normal}"/>
+```
 
-    <lv_button style_bg_color-checked="0xed7d31">
-      <lv_image src="img_lightbulb"/>
+Inside an expression a variant name reads the currently selected option, and an option name acts as a constant. See [Variants](./variants) for declaring them and for setting an option from C.
 
-      <!-- Read: this button is checked iff subject_lamp == ref_value -->
-      <bind_state_if_eq subject="subject_lamp" state="checked" ref_value="$ref_value"/>
+## Bind styles
 
-      <!-- Write: clicking this button stores ref_value in subject_lamp -->
-      <subject_set_int_event subject="subject_lamp" trigger="clicked" value="$ref_value"/>
-    </lv_button>
-  </view>
-</component>
-```
+To switch a whole style at runtime, use [`<bind_style>`](./styles#style-binding), which takes the same kind of expression in its `if` attribute:
 
 ```xml
-<!-- screen — each cell carries a unique ref_value -->
-<lamp_cell label="Lamp 1" ref_value="0"/>
-<lamp_cell label="Lamp 2" ref_value="1"/>
-<lamp_cell label="Lamp 3" ref_value="2"/>
+<bind_style name="style_warning" if="subject_temp > 10 and subject_temp &lt;= 30"/>
 ```
 
-When the user taps a cell, `subject_lamp` is written to that cell's `ref_value`; every other cell's `bind_state_if_eq` re-evaluates and drops out of the `checked` state automatically. The same subject can also be set from C (`lv_subject_set_int(&subject_lamp, …)`) to drive the selection from application code.
-
-## Subject Related Events
+## Subject related events
 
 Besides binding properties to subjects, it's also possible to add
 events that change the value of a subject on pressed, release, etc.
 
-Learn more about these in the [events documentation](./events).
\ No newline at end of file
+Learn more about these in the [events documentation](./events).
diff --git a/docs/syntax/evaluate.mdx b/docs/syntax/evaluate.mdx
index eeeb8cf5..2643a168 100644
--- a/docs/syntax/evaluate.mdx
+++ b/docs/syntax/evaluate.mdx
@@ -7,7 +7,7 @@ description: Compute attribute values from arithmetic, comparisons, ternaries, a
 This feature requires [LVGL Pro Editor v2.0](https://github.com/lvgl/lvgl_pro/releases) or higher.
 </Callout>
 
-Any XML attribute value can be an **expression** wrapped in `{ }`. Instead of writing a fixed value, you let the Editor compute it from numbers, colors, strings, constants, and parameters.
+Any XML attribute value can be an **expression** wrapped in `{ }`. Instead of writing a fixed value, you let the Editor compute it from numbers, colors, strings, constants, and parameters **when the instance is created**.
 
 ```xml
 <lv_obj width="{base_width * 2}"/>
@@ -15,36 +15,51 @@ Any XML attribute value can be an **expression** wrapped in `{ }`. Instead of wr
 <lv_obj hidden="{item_count == 0}"/>
 ```
 
+Wrapping the same expression in `@{ }` creates a dynamic data binding instead, **re-evaluated whenever a subject or variant in it changes**.
+
+```xml
+<lv_obj width="@{variant_size == large ? large_width : small_width}"/>
+<lv_label text="@{'Hello, ' . subject_user_name . '!'}"/>
+<lv_obj hidden="@{subject_item_count == 0}"/>
+```
+
 ## Overview
 
 Expressions are useful whenever a value is *derived* from other values: a width that is twice a parameter, a label that joins a prefix with a name, a flag that depends on a count, and so on. Keeping the calculation in the XML means you don't have to duplicate or pre-compute values by hand.
 
 A few important properties to keep in mind:
 
-- **Creation-time only.** An expression is evaluated **once**, when the UI element is created. The result is then handed to the normal attribute parser exactly as if you had typed the computed value yourself.
-- **Not reactive.** A `{ }` expression does *not* react to changes. For a value that follows a subject or a variant at runtime, write the very same expression as a binding: `@{ }` instead of `{ }`. See [Expression binding](./data-binding#expression-binding).
-- **The result type is inferred from the terms.** You never declare the type — it follows from the literals and variables you use (see [Value types](#value-types)).
+- **`{ }` is creation-time only.** An expression is evaluated **once**, when the UI element is created. The result is then handed to the normal attribute parser exactly as if you had typed the computed value yourself.
+- **`@{ }` is reactive.** An `@{ }` expression is re-evaluated as the connected subjects or variants change.
+- **The result type is inferred from the terms.** You never declare the type, it follows from the literals and variables you use (see [Value types](#value-types)).
 
 <Callout type="info">
-    Expressions are exported into the generated C code, not pre-computed to a fixed literal. They are re-evaluated every time the element is created — including when you create a component manually from C — using the parameter values passed at that moment.
+    Expressions are exported into the generated C code, not pre-computed to a fixed literal. They are re-evaluated every time the element is created, including when you create a component manually from C, using the parameter values passed at that moment.
 </Callout>
 
-## Writing expressions
+The same expression engine is used in `<bind_style if="...">` too. There no `@{ }` wrapping is needed, as that attribute is always treated as a binding.
 
-An expression is the whole attribute value, wrapped in a single pair of braces:
+## Basic syntax
+
+An expression is the whole attribute value, wrapped into `{ }` (one time evaluated) or `@{ }` (reactive binding):
 
 ```xml
 <lv_obj width="{10 + 20}"/>   <!-- becomes width="30" -->
 ```
 
-Inside the braces you can use literals, operators, and **variable names**. A variable name is written as a **bare identifier** — without the `$` or `#` prefixes used elsewhere in XML. The name is resolved, in order, against:
+Inside the braces you can use the following data:
+
+- In a `{ }` one time evaluation: literals, operators, constants, API `<prop>`s, subjects, and variants. Subjects and variants are read once, so their later changes are ignored.
+- In an `@{ }` binding: the same, except that API `<prop>`s cannot be used. They are not stored per instance, they only exist during creation. The one exception is a `type="subject"` `<prop>`, which names a subject the binding can follow.
 
-1. **Variants** declared in the element's [`<api>`](./api): the currently selected option of that [variant](./variants).
-2. **Parameters** declared in the element's [`<api>`](./api): the value comes from the instance (or the parameter's `default`), and the type from the declared `type`.
+Names are written as **bare identifiers**, without the `$` or `#` prefixes used elsewhere in XML. They are resolved in this order:
+
+1. **Variants** declared in the element's [`<api>`](./api), the value is the currently selected option of that [variant](./variants).
+2. **Parameters** declared in the element's [`<api>`](./api) as `<prop>`.
 3. **Constants** from [`<consts>`](./constants): the type is inferred from the constant's value.
 4. **Variant option names**: an integer constant, the option's index in its variant.
-5. **Subjects** from `globals.xml`: their current value, read once (use `@{ }` to follow them).
-6. **Other named items** the XML processor resolves later (a font, image, or screen name). These are passed through as plain strings.
+5. **Subjects** from `globals.xml`.
+6. **Other named items** the XML processor resolves later (a font, image, or screen name).
 
 ```xml
 <component>
@@ -62,7 +77,9 @@ Inside the braces you can use literals, operators, and **variable names**. A var
 </component>
 ```
 
+<Callout type="warn">
 Note that `$` and `#` are not used in expressions to reference properties and constants.
+</Callout>
 
 ## Value types
 
@@ -81,8 +98,8 @@ Each term has a type, inferred from how it is written:
 Notes:
 
 - **Colors** accept both the full `0xRRGGBB` form and the `0xRGB` shorthand, which expands like CSS (`0xf00` → `0xff0000`).
-- **Strings** use **single quotes** (`'…'`), since double quotes already delimit the XML attribute.
-- **Floats** require `LV_USE_FLOAT`. Without it, a float degrades to its integer part. Float results are serialized with two decimals (e.g. `3.50`).
+- **Strings** use **single quotes** (`'...'`), since double quotes already delimit the XML attribute.
+- **Floats** require `LV_USE_FLOAT`. Without it, a float degrades to its integer part. Float results are serialized with two decimals in texts (e.g. `3.50`).
 
 ## Operators
 
@@ -101,7 +118,7 @@ Notes:
 
 ```xml
 <lv_obj hidden="{count == 0}"/>
-<lv_obj checked="{mode == 'dark'}"/>
+<lv_obj checked="{mode != 'dark'}"/>
 ```
 
 Comparisons cannot be **chained**: `a < b < c` is invalid. Each operand of a logical `and`/`or` may contain one comparison, so a range check is written as `a > 10 and a <= 30`.
@@ -138,26 +155,26 @@ Both sides are **always evaluated**. There is no short-circuiting, just like wit
 
 `and`/`or` are keywords, so a constant, property, or subject cannot be named `and` or `or`. There is no `^^` operator.
 
-### Ternary
+### String concatenation
 
-`cond ? a : b` chooses between two values. The condition must be a bool, a number, or a string (a non-empty string is truthy); it **cannot** be a color. Both branches must have the same type (int and float mix freely).
+The `.` operator joins values into a single string. Each operand is automatically stringified — integers and floats as decimals, bools as `true`/`false`, colors as `0xRRGGBB`.
 
 ```xml
-<lv_label text="{count == 0 ? 'Empty' : 'Has items'}"/>
-<lv_obj style_bg_color="{is_on ? 0x00ff00 : 0x333333}"/>
+<lv_label text="{'Battery: ' . level . '%'}"/>
+<lv_label text="{first_name . ' ' . last_name}"/>
 ```
 
-Ternaries **cannot be nested**, but each branch may itself be a string concatenation.
-
-### String concatenation
+### Ternary
 
-The `.` operator joins values into a single string. Each operand is automatically stringified — integers and floats as decimals, bools as `true`/`false`, colors as `0xRRGGBB`.
+`cond ? a : b` chooses between two values. The condition must be a bool, a number, or a string (a non-empty string is truthy); it **cannot** be a color. Both branches must have the same type (int and float mix freely).
 
 ```xml
-<lv_label text="{'Battery: ' . level . '%'}"/>
-<lv_label text="{first_name . ' ' . last_name}"/>
+<lv_label text="@{subject_count == 0 ? 'Empty' : 'Has ' . subject_count . ' items'}"/>
+<lv_obj style_bg_color="{is_on ? 0x00ff00 : 0x333333}"/>
 ```
 
+Ternaries **cannot be nested**, but each branch may itself be a string concatenation.
+
 ## Precedence and grouping
 
 From highest to lowest:
@@ -200,22 +217,6 @@ An expression lives in an XML attribute value, where a few characters are reserv
 <lv_obj hidden="{10 > count and locked}"/>
 ```
 
-## Error handling
-
-If an expression is malformed, for example a type mismatch, a missing `)` or `:`, or a division by zero, evaluation fails. A warning naming the exact problem and the offending expression is logged, and the raw `{ … }` text is left in the attribute, which the normal attribute parser then reads as `0` or as literal text.
-
-Common messages include:
-
-- *the two ternary branches must have the same type*.
-- *the two sides of `==`/`!=` have different types*.
-- *`< <= > >=` need numeric operands (use `==`/`!=` for strings, colors, bools)*.
-- *arithmetic `+ - * / %` needs numeric operands*.
-- *`%` needs integer operands*.
-- *division or modulo by zero*.
-- *unexpected character (note: use `==` to compare, `.` to concatenate)*.
-
-A name that is not a variant, parameter, constant, variant option, or subject is **not** an error: it's kept as a plain string, as [Writing expressions](#writing-expressions) describes. A typo in a name therefore shows up as a type error, or later as a "not found" warning from whatever resolves the value (a font, an image, and so on).
-
 ## Examples
 
 ```xml
@@ -229,8 +230,8 @@ A name that is not a variant, parameter, constant, variant option, or subject is
 <lv_label text="{'Room ' . room_id . ': ' . temperature . ' °C'}"/>
 
 <!-- Boolean flag from a comparison -->
-<lv_obj hidden="{progress >= 100}"/>
+<lv_obj hidden="@{subject_progress >= 100}"/>
 
 <!-- Color chosen by a flag -->
-<lv_obj style_bg_color="{active ? 0x2e7d32 : 0x9e9e9e}"/>
+<lv_obj style_bg_color="@{variant_mode == active ? 0x2e7d32 : 0x9e9e9e}"/>
 ```
diff --git a/docs/syntax/styles.mdx b/docs/syntax/styles.mdx
index 28586500..be77cb12 100644
--- a/docs/syntax/styles.mdx
+++ b/docs/syntax/styles.mdx
@@ -185,7 +185,7 @@ Instead of setting local style properties directly, you can bind them to subject
 </component>
 ```
 
-`<bind_style_prop>` copies a subject's value into the property as-is. To compute the value, write an [expression binding](./data-binding#expression-binding) on the local style property itself, selectors included:
+`<bind_style_prop>` copies a subject's value into the property as-is. To compute the value, write an [expression binding](./data-binding#generic-bindings-with-expressions) on the local style property itself, selectors included:
 
 ```xml
 <lv_label style_text_color-pressed="@{subject_error_mode ? 0xff0000 : 0xaaaaaa}"/>
diff --git a/docs/syntax/variants.mdx b/docs/syntax/variants.mdx
index 2e5c7b7f..ffa2d5ab 100644
--- a/docs/syntax/variants.mdx
+++ b/docs/syntax/variants.mdx
@@ -3,7 +3,7 @@ title: Variants
 description: Declare a Component's visual variations, like size or tone, and switch between them at runtime.
 ---
 
-Most Components exist in a few flavors: a button that is `small` or `large`, a badge that is `normal` or `danger`. A **variant** declares such a dimension once, and every instance can pick an option from it: statically, from a subject, or from C at runtime.
+Most Components exist in a few flavors: a button that is `small` or `large`, a badge that is `normal` or `danger`. A **variant** declares these once, and every instance can pick an option from it: statically, from a subject, or at runtime from C.
 
 ```xml
 <my_badge size="large" tone="danger"/>
@@ -34,16 +34,16 @@ A variant is not an [`<api>`](./api) property, so it can't be read with `$name`.
 Each variant is **per-instance reactive state**: ten instances of the same Component can be in ten different states, and switching one of them updates only that instance. This makes variants the Component-level counterpart of [subjects](./data-binding), which are global.
 
 <Callout type="info">
-Variants are useful when a Component's *appearance* has a fixed set of named states. For free-form data (a temperature, a user name) use a subject or an [`<api>`](./api) property instead.
+Variants are useful when a Component's *appearance* has a fixed set of named states. For free-form data (a temperature, a user name) use a subject as an [`<api>`](./api) property instead.
 </Callout>
 
 ## Reacting to a variant
 
-A variant is meaningless until something reads it. There are two ways, and they are usually combined.
+A variant is meaningless until something reads it. There are two ways to do it.
 
 ### Switching styles
 
-`<bind_style>` attaches a style while a variant has a given option. Use the variant's name as `subject` and an option name as `ref_value`:
+`<bind_style>` attaches a style while a condition is true, so a variant can select the styles of an option:
 
 ```xml
 <component>
@@ -63,20 +63,20 @@ A variant is meaningless until something reads it. There are two ways, and they
 
   <view extends="lv_button">
     <style name="style_normal"/>
-    <bind_style name="style_danger" subject="tone" ref_value="danger"/>
-    <bind_style name="style_small" subject="size" ref_value="small"/>
-    <bind_style name="style_large" subject="size" ref_value="large"/>
+    <bind_style name="style_danger" if="tone == danger"/>
+    <bind_style name="style_small" if="size == small"/>
+    <bind_style name="style_large" if="size == large"/>
 
     <lv_label name="title" text="Title"/>
   </view>
 </component>
 ```
 
-This is the recommended way to express the *visual* difference between options: the styles stay declarative, and only the option selection changes at runtime.
+This is the recommended way to express the **visual difference** between options. The styles stay declarative, and only the selection changes at runtime.
 
 ### In expressions
 
-A variant can also be used in [`@{ }` bindings](./data-binding#expression-binding), where:
+A variant can also be used in [`@{ }` bindings](./data-binding#generic-bindings-with-expressions), where:
 
 - a **variant name** reads the currently selected option,
 - an **option name** is a constant that can be compared against it.
@@ -86,7 +86,7 @@ A variant can also be used in [`@{ }` bindings](./data-binding#expression-bindin
 <lv_label name="subtitle" text="Subtitle" hidden="@{size == small}"/>
 
 <!-- A variant and a global subject in one expression -->
-<lv_label text="@{tone == danger ? 'Alert: ' . subject_error_count : 'All good'}"/>
+<lv_label text="@{tone == danger ? 'Alert: ' . subject_error_text : 'All good'}"/>
 ```
 
 Because `@{ }` re-evaluates on every change, switching the variant updates these attributes immediately. In a plain [`{ }` expression](./evaluate) a variant works too, but it's read only once, when the element is created.
@@ -103,7 +103,7 @@ A variant behaves like a normal property where the Component is used:
 
 An unknown option name falls back to the variant's `default` and logs a warning.
 
-The value can also be a [binding](./data-binding#expression-binding), so a variant can follow a subject:
+The value can also be a [binding](./data-binding#generic-bindings-with-expressions), so a variant can follow a subject:
 
 ```xml
 <my_badge tone="@{subject_level > 100 ? danger : normal}"/>
@@ -126,32 +126,6 @@ void my_badge_set_size(lv_obj_t * obj, my_badge_size_t size);
 my_badge_size_t my_badge_get_size(lv_obj_t * obj);
 ```
 
-When the XML is loaded at runtime instead (in the Editor's preview, or with `lv_xml_create()`), select an option by name:
+When calling the `set` function, every style and data binding that reads the variant is re-evaluated automatically.
 
-```c
-lv_xml_set_variant(badge, "size", "large");
-```
-
-Both look the variant up on the given widget and then on its parents, so any widget inside a Component instance can be passed. Every `bind_style` and `@{ }` expression referencing the variant updates immediately.
-
-An option name `lv_xml_set_variant()` doesn't recognize is refused with a warning, and the variant keeps its current option. This also applies to a variant binding whose expression returns something that is not an option name.
-
-## Name resolution
-
-Inside expressions a bare identifier is resolved in this order:
-
-1. **Variant name**
-2. **`<api>` property**
-3. **Constant**
-4. **Variant option name**
-5. **Subject**
-6. Anything else is kept as a plain string (a font or image name, for example)
-
-Two consequences worth remembering:
-
-- A variant **shadows** a property, constant, or subject of the same name. Avoid such collisions.
-- **Option names have to be unique across a Component's variants**, otherwise a bare option name in an expression is ambiguous. The first declared variant wins, and registration logs a warning. `<bind_style>` is exempt, since its `subject` attribute already tells which variant the `ref_value` belongs to.
-
-<Callout type="warn">
-The order of `options` defines the integer value of each option in the exported C code. Reordering them is a breaking change for code that was already generated; adding new options at the end is safe.
-</Callout>
+The option order in `options` defines the value of each enum field, so reordering them changes the exported C API. Adding new options at the end is safe.

From 3a2dbd75741cf852d3ac27cb94884ebba410200d Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Sun, 9 Aug 2026 00:34:51 +0200
Subject: [PATCH 4/6] follow core changes

---
 docs/syntax/data-binding.mdx | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/syntax/data-binding.mdx b/docs/syntax/data-binding.mdx
index 21b5d584..ba2410a6 100644
--- a/docs/syntax/data-binding.mdx
+++ b/docs/syntax/data-binding.mdx
@@ -95,6 +95,13 @@ It can't be used in the `<styles>` section, as [styles](./styles) are initialize
 <!-- ❌ `title` is a property of the my_card Component -->
 <my_card title="@{subject_user_name}"/>
 
+<!-- ✅ Simple bindings to common widget properties -->
+<lv_slider hidden="@{!subject_settings_show}" disabled="@{!subject_settings_active}"/>
+
+<!-- ✅ `text` comes from `lv_label` that `h3` extends. 
+     It means a binding can be used on it.-->
+<h3 text="@{'Hi ' . subject_name}"/>
+
 <!-- ✅ `tone` is a variant of my_card -->
 <my_card tone="@{subject_alarm == 1 ? danger : normal}"/>
 

From f0d9cc2029009edbecdfffc5a5afcbf0e220829d Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Sun, 9 Aug 2026 20:15:09 +0200
Subject: [PATCH 5/6] support {} in style props, anim props, const values and
 subject init value

---
 docs/syntax/animations.mdx   | 12 ++++++++++
 docs/syntax/api.mdx          |  2 +-
 docs/syntax/components.mdx   |  4 ++--
 docs/syntax/constants.mdx    | 17 ++++++++-----
 docs/syntax/data-binding.mdx |  2 ++
 docs/syntax/evaluate.mdx     | 36 ++++++++++++++++++++++++++++
 docs/syntax/fonts.mdx        |  2 +-
 docs/syntax/images.mdx       |  4 ++--
 docs/syntax/overview.mdx     | 46 ++++++++++++++++++++++++++++++++----
 docs/syntax/screens.mdx      |  2 +-
 docs/syntax/styles.mdx       | 28 ++++++++++++++++------
 docs/syntax/variants.mdx     |  2 +-
 12 files changed, 132 insertions(+), 25 deletions(-)

diff --git a/docs/syntax/animations.mdx b/docs/syntax/animations.mdx
index aaa0aadd..b49661e8 100644
--- a/docs/syntax/animations.mdx
+++ b/docs/syntax/animations.mdx
@@ -70,6 +70,18 @@ Within each `timeline`, add individual `<animation>` elements to describe each s
 - `early_apply` - If `true`, the start value is applied immediately, even during the delay. Default is `false`.
 - `easing` - The animation path, e.g. `ease_out`. See below. Default is `linear`.
 
+`start`, `end`, `duration` and `delay` accept constants and [expressions](./evaluate#outside-the-view) of them:
+
+```xml
+<consts>
+  <int name="slide_ms" value="500"/>
+  <int name="slide_dist" value="30"/>
+</consts>
+
+<animation prop="translate_x" target="self" start="{-slide_dist}" end="0"
+           duration="{slide_ms}" delay="{slide_ms / 2}"/>
+```
+
 ### Easing
 
 The `easing` property tells how the value should progress from `start` to `end` during the `duration`. These built-in paths can be used:
diff --git a/docs/syntax/api.mdx b/docs/syntax/api.mdx
index e716141e..e89634ce 100644
--- a/docs/syntax/api.mdx
+++ b/docs/syntax/api.mdx
@@ -24,7 +24,7 @@ When a component's XML is converted to C files, only a `create` function is gene
 
 ### Referencing Properties
 
-Props are simply forwarded to Widget or Component APIs. For example, if a component has `<prop name="button_label" type="string"/>`, it can be used in a label child as `<lv_label text="$button_label"/>`.
+Props are simply forwarded to Widget or Component APIs. For example, if a component has `<prop name="button_label" type="string"/>`, it can be used in a label child as `<lv_label text="{button_label}"/>`.
 
 In the code generated by LVGL's UI Editor, these are passed as arguments in create/set functions.
 
diff --git a/docs/syntax/components.mdx b/docs/syntax/components.mdx
index c9a418a0..b1d5de3f 100644
--- a/docs/syntax/components.mdx
+++ b/docs/syntax/components.mdx
@@ -99,7 +99,7 @@ However, you can also define custom properties in the [`api` tag](./api). These
   </api>
 
   <view extends="lv_button">
-    <lv_label text="$btn_text"/>
+    <lv_label text="{btn_text}"/>
   </view>
 </component>
 ```
@@ -160,7 +160,7 @@ The following examples demonstrate parameter passing, styles, and constants in C
   <view extends="lv_button" style_radius="0" style_bg_color="0xff0000">
     <style name="pressed_style" selector="pressed"/>
     <h3 text="Some text"/>
-    <h3 text="$btn_text" y="40"/>
+    <h3 text="{btn_text}" y="40"/>
   </view>
 </component>
 ```
\ No newline at end of file
diff --git a/docs/syntax/constants.mdx b/docs/syntax/constants.mdx
index 3bff1518..2af20ae5 100644
--- a/docs/syntax/constants.mdx
+++ b/docs/syntax/constants.mdx
@@ -42,7 +42,7 @@ Constants can be used in:
 - Widget properties
 - Component properties
 
-Constant values are referenced using the `#` symbol followed by the constant name. For example:
+A constant is referenced by its name in `{ }`, where it can also be part of a larger [expression](./evaluate). This works in the `view` and in the `<consts>`, `<styles>`, `<subjects>`, `<animations>` and `<gradients>` sections alike:
 
 ```xml
 <components>
@@ -50,15 +50,20 @@ Constant values are referenced using the `#` symbol followed by the constant nam
     <color name="red" value="0xff0000" help="A pure red color"/>
     <int name="long" value="200" help="Just large number"/>
     <string name="greeting" value="Hi There!" help="Just be nice"/>
+
+    <!-- A constant computed from another one -->
+    <int name="half" value="{long / 2}"/>
   </consts>
-  
+
   <styles>
-    <style name="style_1" bg_color="#red"/>
+    <style name="style_1" bg_color="{red}" pad_all="{half}"/>
   </styles>
 
-  <view width="#long">
+  <view width="{long}">
     <style name="style_1"/>
-    <lv_label text="#greeting"/>
+    <lv_label text="{greeting}"/>
   </view>
 </components>
-```
\ No newline at end of file
+```
+
+`#const_name` is the legacy syntax for referencing a constant. It takes a single name only, so `{ }` is the recommended form.
\ No newline at end of file
diff --git a/docs/syntax/data-binding.mdx b/docs/syntax/data-binding.mdx
index ba2410a6..e726d7d5 100644
--- a/docs/syntax/data-binding.mdx
+++ b/docs/syntax/data-binding.mdx
@@ -54,6 +54,8 @@ Subjects can be created in `globals.xml` like this:
 As the example shows, a subject consists of a type, name, and initial
 value. Integer, string, and float types are supported.
 
+The initial value can be a constant or an [expression](./evaluate#outside-the-view) of constants, e.g. `<int name="battery_power" value="{full_charge / 2}"/>`.
+
 <Callout type="info">
 Float subjects require `LV_USE_FLOAT` to be enabled in `lv_conf.h`. Without it, the generated code fails to compile.
 </Callout>
diff --git a/docs/syntax/evaluate.mdx b/docs/syntax/evaluate.mdx
index 2643a168..8627c168 100644
--- a/docs/syntax/evaluate.mdx
+++ b/docs/syntax/evaluate.mdx
@@ -81,6 +81,42 @@ Names are written as **bare identifiers**, without the `$` or `#` prefixes used
 Note that `$` and `#` are not used in expressions to reference properties and constants.
 </Callout>
 
+`{ }` is the general way to reference anything by name. `$param_name` and `#const_name` are the legacy syntax for the same thing: they reference a single name, so they can't be part of a larger expression.
+
+### Outside the view
+
+`<consts>`, `<styles>`, `<subjects>`, `<animations>` and `<gradients>` are processed once, when the component is registered, before any instance of it exists. Expressions work there too, but they can only use **constants and literals**, with every operator, including `and` / `or` and the ternary:
+
+```xml
+<consts>
+  <int name="gap" value="8"/>
+  <!-- A constant computed from another one -->
+  <int name="gap_large" value="{gap * 3}"/>
+  <int name="anim_ms" value="150"/>
+  <bool name="dark_theme" value="true"/>
+</consts>
+
+<styles>
+  <style name="style_card" pad_all="{gap_large}" bg_color="{dark_theme ? 0x101010 : 0xf0f0f0}">
+    <transition props="bg_color" duration="{anim_ms * 2}"/>
+  </style>
+</styles>
+
+<subjects>
+  <int name="subject_page" value="{gap - 8}"/>
+</subjects>
+
+<animations>
+  <timeline name="timeline_load">
+    <animation prop="translate_y" target="self" start="{-gap_large}" end="0" duration="{anim_ms}"/>
+  </timeline>
+</animations>
+```
+
+A **property**, **subject** or **variant** has no value at that point: a property has no instance to take it from, and a subject or variant would have to be read again later, which these sections can't do. Using one is reported.
+
+An `if_target` block is filtered before its content is processed, so an expression there sees the constants of the current target.
+
 ## Value types
 
 Each term has a type, inferred from how it is written:
diff --git a/docs/syntax/fonts.mdx b/docs/syntax/fonts.mdx
index a3873a18..44003ea1 100644
--- a/docs/syntax/fonts.mdx
+++ b/docs/syntax/fonts.mdx
@@ -86,7 +86,7 @@ even `api` properties:
  </styles>
 
  <view flex_flow="column">
-    <lv_label style_text_font="$title_font" text="Title"/>
+    <lv_label style_text_font="{title_font}" text="Title"/>
     <lv_label text="I'm the subtitle">
        <style name="subtitle"/>
     </lv_label>
diff --git a/docs/syntax/images.mdx b/docs/syntax/images.mdx
index 048c2f86..f46d1d3c 100644
--- a/docs/syntax/images.mdx
+++ b/docs/syntax/images.mdx
@@ -151,7 +151,7 @@ Black is the practical choice: the alpha channel carries the shape, so a single
 asset can be tinted anywhere it's used and one icon set serves every theme.
 
 ```xml
-<lv_image src="icon_home" style_image_recolor="#color_accent" style_image_recolor_opa="100%"/>
+<lv_image src="icon_home" style_image_recolor="{color_accent}" style_image_recolor_opa="100%"/>
 ```
 
 ## Using the Images
@@ -178,7 +178,7 @@ In custom properties:
   </api> 
 
   <view>
-    <lv_image src="$icon_src"/>
+    <lv_image src="{icon_src}"/>
   </view>
 </component>
 ```
diff --git a/docs/syntax/overview.mdx b/docs/syntax/overview.mdx
index 97a51356..e3b6211d 100644
--- a/docs/syntax/overview.mdx
+++ b/docs/syntax/overview.mdx
@@ -15,9 +15,26 @@ LVGL Pro Editor uses standard XML syntax with special conventions for property n
   - Hex without prefix: `112233`
   - Short hex: `0x123`, `#123`, or `123` (all equivalent to `#112233`)
 - **LVGL API alignment**: Follow LVGL naming conventions (e.g., `align="center"`, `bg_color="0xff0000"`)
-- **Property references**: Use `$` prefix (e.g., `$param_name`)
-- **Constant references**: Use `#` prefix (e.g., `#const_name`)
-- [**Expressions**](./evaluate): Use `{ }`. When referencing properties or constants inside, no `$` or `#` is needed
+- **References**: Use `{ }` to reference anything by name: a `<prop>`, a constant, a subject, or a variant (e.g. `width="{card_width}"`). Inside the braces the name is written plain, and it can be part of a larger [expression](./evaluate)
+- **Legacy references**: `$param_name` for a `<prop>` and `#const_name` for a constant. Each takes a single name, so it can't be part of an expression
+
+## Names and Scopes
+
+Styles, constants, subjects, and animation timelines are all referenced **by name**. Every Component, Widget, and Screen has its own **local scope**, and `globals.xml` holds the **global scope**.
+
+A name is looked up in the local scope first, and in the global scope only after that. Two consequences:
+
+- Two Components can use the same local name freely. Their scopes never see each other.
+- A local name **hides** a global one. If a Component defines `style_card` and `globals.xml` defines `style_card` too, that Component always gets its own.
+
+Keeping names unique **within one scope is your responsibility**. Nothing reports a collision, so give every style, constant, subject, timeline, and widget `name="..."` a distinct name. Two cases make a collision easy to miss:
+
+- In an [expression](./evaluate) a bare name is resolved in a fixed order: variant, property, constant, variant option, subject. The first match wins, so a constant named `temperature` hides a subject of the same name.
+- A `name="..."` is found by searching the widget tree and the first match is used, so two widgets with the same name make animation targets and `lv_obj_find_by_name()` ambiguous.
+
+A prefix per kind keeps them apart: `style_card`, `subject_temperature`, `timeline_load`.
+
+Component, Widget, and Screen names come from their file names and are kept separately, so `h3.xml` never collides with a style, constant, or subject named `h3`.
 
 ## Property Names
 
@@ -84,7 +101,28 @@ The same names can also be used as `<prop>` types so a Component can accept an a
 | **subject** | A subject registered under `<subjects>` | `<prop name="subject" type="subject" default="subject_dimmer1"/>` |
 | **style** | A style defined in `<styles>` or `globals.xml` | `<prop name="extra_style" type="style"/>` |
 
-These props are typically forwarded into a child element with the `$` prefix, e.g. `<lv_image src="$src"/>` or `<lv_slider bind_value="$subject"/>`.
+These props are typically forwarded into a child element by name, e.g. `<lv_image src="{src}"/>` or `<lv_slider bind_value="{subject}"/>`.
+
+A **style** prop names a style of the Component that passes it, and it is resolved there:
+
+```xml
+<!-- card.xml -->
+<component>
+    <api>
+        <prop name="outline" type="style"/>
+    </api>
+    <view extends="lv_obj">
+        <style name="$outline"/>
+    </view>
+</component>
+
+<!-- The style belongs to the file that uses the card -->
+<card outline="style_focus_ring"/>
+```
+
+<Callout type="warn">
+A `name` is always a literal or a single `$param_name` / `#const_name` reference, never an expression. The Editor has to resolve it to check that the style, font, image, and so on exists.
+</Callout>
 
 **Automatic binding** occurs for:
 - Styles, fonts, images, animations
diff --git a/docs/syntax/screens.mdx b/docs/syntax/screens.mdx
index 8bbd739e..249e3980 100644
--- a/docs/syntax/screens.mdx
+++ b/docs/syntax/screens.mdx
@@ -37,7 +37,7 @@ This example illustrates a screen in XML using `my_header` and `my_main_cont` co
  </styles>
 
  <view>
-  <my_header label="#title"/>
+  <my_header label="{title}"/>
   <my_main_cont>
    <style name="dark"/>
    <button text="Weather" icon="cloudy"/>
diff --git a/docs/syntax/styles.mdx b/docs/syntax/styles.mdx
index be77cb12..35bed4ab 100644
--- a/docs/syntax/styles.mdx
+++ b/docs/syntax/styles.mdx
@@ -97,7 +97,7 @@ Keep these limitations in mind:
 - A style can store only one transition. To use different durations for different properties, split them into two styles.
 - Only numeric (including opacity) and color properties can be animated. Properties referencing other data (`text_font`, `bg_image_src`, `bg_grad`, ...) and most enums and booleans (`flex_flow`, `text_align`, `clip_corner`, ...) are ignored with a warning.
 - The composite names are expanded, so e.g. `props="pad_all"` transitions all the four paddings.
-- Like in any other style property, `#constants` can be used, but `$api_properties` can't.
+- Like in any other style property, constants and `{ }` expressions of them can be used, but API `<prop>`s can't.
 
 ## Style Binding
 
@@ -211,9 +211,9 @@ In the values of style properties constants can be used as well.
 ```
 
 
-## Relation to API Properties
+## Relation to API `<prop>`s
 
-Since styles are initialized only once, it's not possible to pass API properties to them when the instances ar created. So this is invalid:
+Since styles are initialized only once, it's not possible to pass API `<prop>`s to them when the instances are created. So this is invalid:
 
 ```xml
 <component>
@@ -222,14 +222,28 @@ Since styles are initialized only once, it's not possible to pass API properties
     </api>
 
     <styles>
-       <!-- ❌ CAN'T DO THIS -->
+       <!-- ❌ CAN'T DO THIS. `{thickness}` doesn't work either: a style is
+            initialized before any instance exists, so a <prop> has no value -->
        <style name="style_main" border_width="$thickness"/>
     </styles>
     
 </component>
 ```
 
-However you can pass [`<api>`](./api) properties to local style properties:
+[Constants](./constants) do have a value there, so a style property can be computed from them with an [expression](./evaluate#outside-the-view):
+
+```xml
+<consts>
+    <int name="thin" value="2"/>
+</consts>
+
+<styles>
+    <!-- ✅ Constants and literals work -->
+    <style name="style_main" border_width="{thin * 2}"/>
+</styles>
+```
+
+And you can pass [`<api>`](./api) `<prop>`s to local style properties:
 
 ```xml
 <component>
@@ -238,9 +252,9 @@ However you can pass [`<api>`](./api) properties to local style properties:
         <prop name="bg_color" type="color"/>
     </api>
 
-    <view style_bg_color="$bg_color">
+    <view style_bg_color="{bg_color}">
        <!-- ✅ Passing api properties to local styles work -->
-       <lv_slider style_border_width-knob="$thickness"/>
+       <lv_slider style_border_width-knob="{thickness}"/>
     </view>
 </component>
 ```
diff --git a/docs/syntax/variants.mdx b/docs/syntax/variants.mdx
index ffa2d5ab..b0301b19 100644
--- a/docs/syntax/variants.mdx
+++ b/docs/syntax/variants.mdx
@@ -29,7 +29,7 @@ A variant is a named list of options, declared in the Component's [`<api>`](./ap
 - `options` - Space separated list of the option names.
 - `default` - The option to use when the instance doesn't set one. If it's missing or unknown, the first option is used.
 
-A variant is not an [`<api>`](./api) property, so it can't be read with `$name`. Read it with [`<bind_style>`](./styles#style-binding) or in an expression, as shown below.
+A variant is not an [`<api>`](./api) `<prop>`, so `$variant_name` doesn't read it. Use `{variant_name}` or `@{variant_name}`, or [`<bind_style>`](./styles#style-binding), as shown below.
 
 Each variant is **per-instance reactive state**: ten instances of the same Component can be in ten different states, and switching one of them updates only that instance. This makes variants the Component-level counterpart of [subjects](./data-binding), which are global.
 

From c95bb2dfcb7b89ddf6a588afbe8f50c5ed90b66f Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Mon, 10 Aug 2026 19:29:53 +0200
Subject: [PATCH 6/6] Apply suggestions from code review

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
---
 docs/syntax/api.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/syntax/api.mdx b/docs/syntax/api.mdx
index e89634ce..1193c28f 100644
--- a/docs/syntax/api.mdx
+++ b/docs/syntax/api.mdx
@@ -61,7 +61,7 @@ Slots are very useful for creating components like screen templates where users
 
 It's also possible to change the basic `lv_obj` properties on the slots, such as `hidden="true"`, `style_bg_color-pressed="0xff0000"`, `checked="true"`, `width="100"`, etc.
 
-The example below shows it in the practice:
+The example below shows it in practice:
 
 ```xml
 <!-- simple_screen.xml -->