Update docs

Author: ThomasFarstrike

docs/architecture/frameworks.md

@@ -213,16 +213,32 @@ class MyActivity(Activity):
 
 See [FileExplorerActivity](../frameworks/file-explorer-activity.md) for details.
 
-### Focus Borders
-Provides a single helper, `add_focus_border`, for drawing a focus border around any widget. It replaces the duplicated `FOCUSED`/`DEFOCUSED` handlers that used to exist in many apps.
+### Focus Highlight
+Provides a single helper, `add_focus_highlight`, for drawing a focus border or background tint around any widget. It replaces the duplicated `FOCUSED`/`DEFOCUSED` handlers that used to exist in many apps.
 
 ```python
-from mpos import add_focus_border
+from mpos import add_focus_highlight
 
-add_focus_border(button, width=2)
+# Border mode (default)
+add_focus_highlight(button, width=2)
+
+# Background mode (keep existing border intact)
+add_focus_highlight(button, mode="bg")
+```
+
+See [Focus Highlight](../frameworks/focus.md) for details.
+
+### LightsManager
+Controls NeoPixel RGB LEDs on supported hardware. Provides buffered LED control, predefined notification colors, and frame-based animation support.
+
+```python
+from mpos import lights
+
+lights.set_all(0, 0, 255)
+lights.write()
 ```
 
-See [Focus Borders](../frameworks/focus.md) for details.
+See [LightsManager](../frameworks/lights-manager.md) for details.
 
 ### CameraManager
 Provides access to camera hardware.

docs/frameworks/focus.md

@@ -1,69 +1,73 @@
-# Focus Borders
+# Focus Highlight
 
 MicroPythonOS provides a single, reusable helper for focus highlighting so that apps and framework screens do not have to duplicate the same `FOCUSED`/`DEFOCUSED` event handlers.
 
 ## Overview
 
-`add_focus_border` registers two LVGL event callbacks on a widget:
+`add_focus_highlight` registers two LVGL event callbacks on a widget:
 
-- **`FOCUSED`**: draw a border around the widget and scroll it into view.
-- **`DEFOCUSED`**: hide the border again.
+- **`FOCUSED`**: draw a border around the widget (or tint its background) and scroll it into view.
+- **`DEFOCUSED`**: remove the highlight again.
 
 The helper is re-exported from the top-level `mpos` module, so apps can import it directly.
 
+Two highlight modes are available:
+
+| Mode | Effect |
+|------|--------|
+| `"border"` (default) | Draws a border around the widget on focus. |
+| `"bg"` | Tints the widget's background on focus, leaving border styles intact. |
+
 ## API
 
 ```python
-from mpos import add_focus_border
+from mpos import add_focus_highlight
+
+# Border mode (default)
+add_focus_highlight(widget)
+add_focus_highlight(widget, width=2)
+add_focus_highlight(widget, width=2, color=lv.color_hex(0xFFFFFF))
+add_focus_highlight(widget, width=2, opacity=lv.OPA._50, radius=5)
 
-add_focus_border(widget)
-add_focus_border(widget, width=2)
-add_focus_border(widget, width=2, color=lv.color_hex(0xFFFFFF))
-add_focus_border(widget, width=2, opacity=lv.OPA._50, radius=5)
+# Background mode
+add_focus_highlight(widget, mode="bg")
+add_focus_highlight(widget, mode="bg", color=lv.color_hex(0x444444))
 ```
 
 ### Parameters
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
 | `widget` | required | The LVGL object that should receive focus highlighting. |
-| `width`  | `1`      | Border width in pixels when focused. |
-| `color`  | theme primary color | Border color. Falls back to `lv.theme_get_color_primary(None)` when omitted. |
-| `opacity`| `None`   | Optional `lv.OPA.*` value for the focused border. |
-| `radius` | `None`   | Optional corner radius for the focused border. |
-
-### Requirements
-
-For the callbacks to fire, the widget must be part of the default LVGL focus group:
+| `mode` | `"border"` | Highlight mode: `"border"` draws a border, `"bg"` tints the background. |
+| `width` | `1` | Border width in pixels when focused (ignored in `"bg"` mode). |
+| `color` | theme primary color | Highlight color. Falls back to `lv.theme_get_color_primary(None)` when omitted. |
+| `opacity` | `None` | Optional `lv.OPA.*` value for the focused border (ignored in `"bg"` mode). |
+| `radius` | `None` | Optional corner radius for the focused border (ignored in `"bg"` mode). |
 
-```python
-focusgroup = lv.group_get_default()
-if focusgroup:
-    focusgroup.add_obj(my_widget)
-```
+### Widget and focus group
 
-`add_focus_border` only draws the visual feedback; it does **not** add the widget to the focus group.
+`add_focus_highlight` adds the widget to the default LVGL focus group automatically. You do not need to call `focusgroup.add_obj()` manually.
 
 ### Touch-aware behavior
 
-On devices that are primarily controlled with a touchscreen, the focus border is intentionally hidden until the user first navigates with a directional input (keyboard, hardware buttons, or a rotary encoder). This keeps touch-only screens clean while still making focused elements obvious once physical navigation begins.
+On devices that are primarily controlled with a touchscreen, the focus highlight is intentionally hidden until the user first navigates with a directional input (keyboard, hardware buttons, or a rotary encoder). This keeps touch-only screens clean while still making focused elements obvious once physical navigation begins.
 
-If you want a widget to reveal the focus border immediately, ensure it is added to the default focus group and focus it programmatically:
+If you want a widget to reveal the focus highlight immediately, focus it programmatically:
 
 ```python
 focusgroup = lv.group_get_default()
 if focusgroup:
-    focusgroup.add_obj(btn)
     focusgroup.focus_obj(btn)
 ```
 
 ## Examples
 
-### Basic usage
+### Basic usage (border mode)
 
 ```python
 import lvgl as lv
-from mpos import Activity, add_focus_border
+from mpos import Activity, add_focus_highlight
 
 class MyActivity(Activity):
     def onCreate(self):
@@ -74,38 +78,48 @@ class MyActivity(Activity):
         btn_label = lv.label(btn)
         btn_label.set_text("Focus me")
 
-        add_focus_border(btn)
-
-        focusgroup = lv.group_get_default()
-        if focusgroup:
-            focusgroup.add_obj(btn)
+        add_focus_highlight(btn)
 
         self.setContentView(screen)
 ```
 
+### Background mode
+
+Use `mode="bg"` when the widget already has a persistent border that shouldn't be overwritten:
+
+```python
+btn = lv.button(screen)
+btn.set_style_border_width(2, lv.PART.MAIN)
+btn.set_style_border_color(lv.color_hex(0x333333), lv.PART.MAIN)
+add_focus_highlight(btn, mode="bg")
+```
+
 ### Thicker, semi-transparent border
 
 ```python
-add_focus_border(btn, width=3, opacity=lv.OPA._50, radius=5)
+add_focus_highlight(btn, width=3, opacity=lv.OPA._50, radius=5)
 ```
 
 ### Focus highlight on a label
 
-Labels are not focusable by default, but they can be added to the focus group when they act as list rows:
+Labels are not focusable by default, but they can be made focusable when they act as list rows:
 
 ```python
 row = lv.label(screen)
 row.set_text("Setting row")
 row.add_flag(lv.obj.FLAG.CLICKABLE)
-add_focus_border(row, width=2)
-focusgroup.add_obj(row)
+add_focus_highlight(row, width=2)
 ```
 
+## Compatibility
+
+`add_focus_border` is kept as a compatibility wrapper for the pre‑0.15.0 API. It delegates to `add_focus_highlight` with `mode="border"`. New code should use `add_focus_highlight` directly.
+
 ## When to use it
 
-Use `add_focus_border` whenever you previously wrote a pair of `FOCUSED`/`DEFOCUSED` callbacks whose only job was to show or hide a border. It is used by the framework itself in places such as the launcher, settings screens, the top-menu drawer, `ImageView`, `MusicPlayer`, `ShowFonts`, `Connect4`, `About`, `HowTo`, and `WiFi Settings`.
+Use `add_focus_highlight` whenever you previously wrote a pair of `FOCUSED`/`DEFOCUSED` callbacks whose only job was to show or hide a border or background tint. It is used by the framework itself in places such as the launcher, settings screens, the top-menu drawer, `ImageView`, `MusicPlayer`, `ShowFonts`, `Connect4`, `About`, `HowTo`, and `WiFi Settings`.
 
-If you need additional behavior on focus (for example, starting a timer or loading data), keep your own callbacks and add `add_focus_border` alongside them.
+If you need additional behavior on focus (for example, starting a timer or loading data), keep your own callbacks and add `add_focus_highlight` alongside them.
 
 ## See Also