docs: dark mode docs

Author: sAleksovski

docs/docs/api/register-widget-task-handler.md

@@ -28,6 +28,11 @@ export async function widgetTaskHandler(props: WidgetTaskHandlerProps) {
   switch (props.widgetAction) {
     case 'WIDGET_ADDED':
       props.renderWidget(<Widget />);
+      // or
+      // props.renderWidget({
+      //   light: <Widget theme="light" />,
+      //   dark: <Widget theme="dark" />,
+      // });
       break;
 
     case 'WIDGET_UPDATE':

docs/docs/api/request-widget-update-by-id.md

@@ -33,6 +33,11 @@ export function CounterScreen() {
       widgetName: 'Counter',
       widgetId: 1,
       renderWidget: () => <CounterWidget count={count} />,
+      // or
+      // renderWidget: () => ({
+      //   light: <CounterWidget count={count} theme="light" />,
+      //   dark: <CounterWidget count={count} theme="dark" />,
+      // }),
       widgetNotFound: () => {
         // Called if no widget is present on the home screen
       },

docs/docs/api/request-widget-update.md

@@ -34,6 +34,11 @@ export function CounterScreen() {
     requestWidgetUpdate({
       widgetName: 'Counter',
       renderWidget: () => <CounterWidget count={count} />,
+      // or
+      // renderWidget: () => ({
+      //   light: <CounterWidget count={count} theme="light" />,
+      //   dark: <CounterWidget count={count} theme="dark" />,
+      // }),
       widgetNotFound: () => {
         // Called if no widget is present on the home screen
       }

docs/docs/tutorial/congratulations.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Congratulations!

docs/docs/tutorial/dark-mode-widget.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 7
+---
+
+# Dark Mode widget (Optional)
+
+This library supports using different colors for the widget when the system is in dark mode.
+It lets you provide separate widget UIs for light and dark system themes so your widget looks correct in both modes.
+
+## How it works
+
+When updating or rendering a widget you provide an object with `light` and/or `dark` React elements. The host system will choose the appropriate one based on the current theme. If only `light` is provided, it will be used for both modes as a fallback.
+
+## registerWidgetTaskHandler
+
+In a widget task handler call `props.renderWidget` and pass `light` and `dark` render trees.
+
+```tsx title="widget-task-handler.tsx"
+import React from 'react';
+import { WidgetTaskHandlerProps } from 'react-native-android-widget';
+import { Widget } from '../../widgets/Widget';
+
+export async function widgetTaskHandler(props: WidgetTaskHandlerProps) {
+  switch (props.widgetAction) {
+    case 'WIDGET_ADDED':
+    case 'WIDGET_UPDATED':
+      // props.renderWidget(<Widget />);
+      props.renderWidget({
+        light: <Widget theme="light" />,
+        dark: <Widget theme="dark" />,
+      });
+      break;
+      // handle other actions
+  }
+}
+```
+
+Provide both variants when colors or images need swapping for readability.
+
+## requestWidgetUpdate
+
+You can also request updates from anywhere in your app. The `renderWidget` callback should return the same `light`/`dark` object.
+
+```tsx title="SomeComponent.tsx"
+import React from 'react';
+import { requestWidgetUpdate } from 'react-native-android-widget';
+import { Widget } from '../widgets/Widget';
+
+function onSomeEvent() {
+  requestWidgetUpdate({
+    widgetName: 'Counter',
+    renderWidget: () => ({
+      light: <Widget theme="light" />,
+      dark: <Widget theme="dark" />,
+    }),
+  });
+}
+```
+
+## Limitations
+
+The light and dark variants must match in structure and interactivity — they should expose the same buttons, lists, and touch targets in the same positions. Only visual styling (colors, images, icons) should differ.
+
+- Structure: Keep layouts and element placement identical between variants so touch targets and spacing stay consistent.
+- Images and assets: If you swap images between themes, ensure they use the same intrinsic size and aspect ratio so the layout and touch regions remain unchanged.
+- Click handling: The native host uses the light variant for wiring click actions; the dark variant is used only for visual appearance. Make sure interactive elements in the dark variant mirror the light variant so interactions behave correctly.
+- Fallback: If you omit the `dark` render tree, the `light` variant will be shown in dark mode as a fallback.

docs/docs/tutorial/try-it-our.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Try it out