docs: add tutorial for customizing themes (opening early for reference)

docs/tutorials/theming.mdx

@@ -0,0 +1,119 @@
+---
+sidebar_position: 99
+title: "✨ Customizing Themes"
+---
+
+:::warning
+This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
+:::
+
+# Customizing and Adding New Themes
+
+Open WebUI supports a variety of themes to customize your experience. This guide explains how you can contribute your own themes, particularly animated themes powered by [Particle.js](https://vincentgarreau.com/particles.js/) or custom animations.
+
+## For Users: Proposing New Themes
+
+If you are not a developer but have a great idea for a new animated theme, we'd love to hear it! The best way to contribute is to:
+
+1.  Find a cool Particle.js configuration you like. You can explore examples on sites like [CodePen](https://codepen.io/tag/particles.js).
+2.  Open a "Feature Request" issue on our [GitHub repository](https://github.com/open-webui/open-webui/issues).
+3.  In your request, include a link to the Particle.js configuration you'd like to see added as a theme.
+
+## For Developers: Adding a New Theme
+
+If you are a developer, you can add new themes directly to the project. The process has been streamlined to be as simple as possible.
+
+### Step 1: Create Your Theme File
+
+Every theme is defined in a single TypeScript file.
+
+1.  **Create the Theme File:**
+    *   Navigate to `src/lib/themes/definitions/`.
+    *   Create a new file named after your theme (e.g., `my-cool-theme.ts`).
+
+2.  **Define Your Theme:**
+    *   In your new file, import the `Theme` type and define your theme object.
+    *   The theme object should have the following properties:
+        *   `id`: A unique identifier for your theme (e.g., `'my-cool-theme'`).
+        *   `name`: A user-friendly name for your theme (e.g., `'My Cool Theme'`).
+        *   `emoji`: An emoji to represent your theme in the UI.
+        *   `metaThemeColor`: The hex color for the browser's UI elements (e.g., `'#000000'`).
+        *   `particleConfig` (optional): The `particles.js` configuration object. Use this for standard particle-based themes.
+        *   `animation` (optional): An object with `start` and `stop` functions for custom canvas animations.
+        *   `css`: A string containing the CSS for your theme.
+
+### Example: Particle.js Theme
+
+Here is an example of a simple `particles.js` theme:
+
+```typescript
+import type { Theme } from '$lib/types';
+
+export const myCoolTheme: Theme = {
+  id: 'my-cool-theme',
+  name: 'My Cool Theme',
+  emoji: '😎',
+  metaThemeColor: '#000000',
+  particleConfig: {
+    particles: {
+      number: { value: 80, density: { enable: true, value_area: 800 } },
+      color: { value: '#ffffff' },
+      shape: { type: 'circle' },
+      opacity: { value: 0.5, random: false },
+      size: { value: 3, random: true },
+      line_linked: { enable: true, distance: 150, color: '#ffffff', opacity: 0.4, width: 1 },
+      move: { enable: true, speed: 1, direction: 'none', random: false, straight: false, out_mode: 'out' }
+    }
+  },
+  css: `
+    #main-container.my-cool-theme-bg {
+      background-color: #000 !important;
+      isolation: isolate;
+      position: relative;
+    }
+
+    #particles-js {
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      z-index: -1;
+    }
+  `
+};
+```
+
+### Example: Custom Animation Theme
+
+Here is an example of a theme with a custom canvas animation:
+
+```typescript
+import type { Theme } from '$lib/types';
+
+const startAnimation = (canvas: HTMLCanvasElement) => {
+  // Your animation logic here
+};
+
+const stopAnimation = () => {
+  // Your cleanup logic here
+};
+
+export const myCustomAnimationTheme: Theme = {
+  id: 'my-custom-animation-theme',
+  name: 'My Custom Animation',
+  emoji: '🎨',
+  metaThemeColor: '#123456',
+  animation: {
+    start: startAnimation,
+    stop: stopAnimation
+  },
+  css: `
+    #main-container.my-custom-animation-theme-bg {
+      background-color: #123456 !important;
+    }
+  `
+};
+```
+
+That's it! The application will automatically discover and register your new theme. It will appear in the theme dropdown in the settings.