diff --git a/docs/configs/services.md b/docs/configs/services.md
index 86970b92a..fc5b75c2f 100644
--- a/docs/configs/services.md
+++ b/docs/configs/services.md
@@ -118,6 +118,43 @@ Each widget can optionally provide a list of which fields should be visible via
       key: apikeyapikeyapikeyapikeyapikey
 ```
 
+### Block Highlighting
+
+Widgets can tint their metric blocks automatically based on rules defined alongside the service. Attach a `highlight` section to the widget configuration and map each block (use the translation key from the widget, or the explicit `field` prop if it is present) to one or more numeric or string rules. The first matching rule wins and its level controls the colours.
+
+```yaml
+- Sonarr:
+    icon: sonarr.png
+    href: http://sonarr.host.or.ip
+    widget:
+      type: sonarr
+      url: http://sonarr.host.or.ip
+      key: ${SONARR_API_KEY}
+      highlight:
+        fields:
+          sonarr.queued:
+            numeric:
+              - level: danger
+                when: gte
+                value: 20
+              - level: warn
+                when: gte
+                value: 5
+              - level: good
+                when: eq
+                value: 0
+          sonarr.status:
+            string:
+              - level: danger
+                when: regex
+                value: "(failed|import) pending"
+              - level: good
+                when: equals
+                value: "All good"
+```
+
+Supported numeric operators for the `when` property are `gt`, `gte`, `lt`, `lte`, `eq`, `ne`, `between`, and `outside`. String rules support `equals`, `includes`, `startsWith`, `endsWith`, and `regex`. Each rule can be inverted with `negate: true`, and string rules may pass `caseSensitive: true` or custom regex `flags`. If you format values before passing them into `<Block>`, also pass the unformatted number or string via the `valueRaw` prop so the highlight engine can evaluate correctly.
+
 ## Descriptions
 
 Services may have descriptions,
diff --git a/docs/configs/settings.md b/docs/configs/settings.md
index c24793df3..e1863b8d7 100644
--- a/docs/configs/settings.md
+++ b/docs/configs/settings.md
@@ -109,6 +109,20 @@ color: slate
 
 Supported colors are: `slate`, `gray`, `zinc`, `neutral`, `stone`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `red`, `white`
 
+## Block Highlight Levels
+
+You can override the default Tailwind classes applied when a widget highlight rule resolves to the `good`, `warn`, or `danger` level. Only the `levels` map is read from `settings.yaml`; all highlight rules themselves are defined per widget in `services.yaml`.
+
+```yaml
+blockHighlights:
+  levels:
+    good: "bg-emerald-400/30 text-emerald-900 dark:bg-emerald-900/30 dark:text-emerald-100"
+    warn: "bg-amber-300/30 text-amber-900 dark:bg-amber-900/30 dark:text-amber-100"
+    danger: "bg-rose-400/30 text-rose-900 dark:bg-rose-900/30 dark:text-rose-100"
+```
+
+Any unspecified level falls back to the built-in defaults.
+
 ## Layout
 
 You can configure service and bookmarks sections to be either "column" or "row" based layouts, like so: