docs(xml): LVGL Pro best practices (#9878)

docs/src/xml/best_practices.rst

@@ -0,0 +1,264 @@
+.. _editor_best_practices:
+
+=======================
+LVGL Pro Best Practices
+=======================
+
+These guidelines help keep projects organized, maintainable, and easier to scale when working with the LVGL Pro Editor.
+
+1. Project Naming
+=================
+
+Avoid project names that may conflict with libraries or frameworks.
+
+**Do NOT use:**
+
+- ``lvgl``
+
+**Recommended:**
+
+- Use a unique project name specific to your project.
+
+This prevents naming conflicts and keeps the build system clean.
+
+
+2. Asset Organization
+=====================
+
+Use clear and consistent prefixes for generated assets.
+
+**Images**
+
+- ``icon_``
+- ``image_``
+
+**Fonts**
+
+Use structured naming to handle different sizes and styles:
+
+- ``font_<name>_<size>``
+- ``font_<name>_<size>_<format>``
+
+**Examples:**
+
+- ``font_roboto_14_regular``
+- ``font_roboto_16_bold``
+
+This is especially important when managing multiple font sizes and formats such as bold, italic, or medium.
+
+
+3. Raw Resource Separation
+==========================
+
+Keep raw resources separate from generated resources.
+
+**Recommended structure:**
+
+::
+
+   images/
+   images/raw/
+
+**Example:**
+
+::
+
+   images/raw/icon_home.png
+   images/icon_home.c
+
+For assets with multiple sizes, include the size in the filename:
+
+- ``icon_home_20dp.png``
+- ``icon_home_40dp.png``
+
+**Benefits:**
+
+- Generated files remain easy to locate
+- Raw assets are not mixed with generated files
+- Project structure remains clean and predictable
+
+
+4. Subject Naming
+=================
+
+Use a consistent prefix for subjects.
+
+- ``subject_settings``
+- ``subject_home``
+
+This improves readability and ensures naming consistency across the project.
+
+
+5. Style Naming
+===============
+
+Always prefix styles.
+
+**Base styles:**
+
+- ``style_button``
+- ``style_container``
+- ``style_text``
+
+**Theme variants:**
+
+If multiple themes are used (e.g., dark and light), include a theme prefix:
+
+- ``style_dark_button``
+- ``style_light_button``
+
+This approach simplifies theme management and scaling.
+
+
+6. Screens, Components, and Widgets
+===================================
+
+Create screens, components, and widgets using their respective folders.
+
+**Recommended approach:**
+
+Use:
+
+- *Add New → Component*
+- *Add New → Widget*
+- *Add New → Screen*
+
+This automatically organizes them into subfolders, improving navigation and maintainability.
+
+
+7. Widget Naming
+================
+
+Use a prefix for widgets:
+
+- ``wd_menu``
+- ``wd_statusbar``
+- ``wd_clock``
+
+This makes widgets easy to identify and avoids naming conflicts.
+
+
+8. Do Not Edit Generated Files
+==============================
+
+Files generated by the editor are overwritten during regeneration.
+
+**Do not modify them directly.**
+
+**Instead:**
+
+- Modify the source XML
+- Use styles
+- Use components or widgets
+
+Direct edits to generated files will be lost.
+
+
+9. Avoid Inline Styles in XML
+=============================
+
+Minimize the use of inline style attributes.
+
+**Avoid:**
+
+.. code-block:: xml
+
+   <lv_obj style_bg_color="0x000000" style_bg_opa="255" />
+
+**Recommended:**
+
+.. code-block:: xml
+
+   <styles>
+      <style name="style_obj" bg_color="0x000000" bg_opa="255" />
+   </styles>
+
+   <lv_obj>
+      <style name="style_obj" />
+   </lv_obj>
+
+**Benefits:**
+
+- Styles are reusable
+- XML remains clean and readable
+- Easier maintenance and updates
+
+
+10. Avoid API Properties in Components/Widgets
+==============================================
+
+Avoid defining API properties that may conflict with editor-specific behavior.
+
+**Avoid:**
+
+.. code-block:: xml
+
+   <prop name="name" type="text" />
+
+Also avoid unnecessary API overrides:
+
+.. code-block:: xml
+
+   <api>
+      <prop name="width" type="int" />
+   </api>
+
+   <view width="$width" />
+
+**Recommended:**
+
+Use the ``help`` property to document API usage:
+
+.. code-block:: xml
+
+   <api name="text" type="string" help="Sets the label text of the component" />
+
+
+11. Avoid Overriding Default Flags or State
+===========================================
+
+Avoid overriding default states or flags on the root object unless necessary.
+
+**Avoid:**
+
+.. code-block:: xml
+
+   <component>
+      <view checked="true" />
+   </component>
+
+**Recommended:**
+
+Set such properties when the component is used within a screen.
+
+This ensures components remain flexible and reusable.
+
+
+12. Component Sizing Best Practices
+===================================
+
+Avoid combining fixed component sizes with fixed child sizes.
+
+**Not recommended:**
+
+.. code-block:: xml
+
+   <view width="content">
+      <lv_dropdown width="420" />
+   </view>
+
+This prevents proper resizing when the component is reused.
+
+**Recommended:**
+
+.. code-block:: xml
+
+   <view width="420">
+      <lv_dropdown width="100%" />
+   </view>
+
+**Benefits:**
+
+- Child elements resize automatically
+- Components can be reused at different sizes
+- Layout behavior remains predictable

docs/src/xml/index.rst

@@ -17,3 +17,4 @@ LVGL Pro and XML
     assets/index
     features/index
     tools/index
+    best_practices