refac: more docs

Author: silentoplayz

docs/tutorials/theming.mdx

@@ -75,6 +75,11 @@ A theme is a single JSON object with the following properties. Only `id`, `name`
 | `animationScript`    | `string`                                       | A string of JavaScript code to be run in a web worker for custom canvas animations.                     |
 | `css`                | `string`                                       | A string of custom CSS rules to be injected.                                                            |
 | `sourceUrl`          | `string`                                       | A URL pointing to the raw `theme.json` file, allowing for automatic update checks.                      |
+| `systemBackgroundImageUrl` | `string` | URL for an image to be used as the main background for the entire UI. |
+| `systemBackgroundImageDarken`| `number` | A value from 0 to 1 to control the darkness of the system background image. |
+| `chatBackgroundImageUrl` | `string` | URL for an image to be used as the background for the chat message area. |
+| `chatBackgroundImageDarken` | `number` | A value from 0 to 1 to control the darkness of the chat background image. |
+| `toggles` | `object` | An object to selectively enable or disable theme features. See the "Advanced Theming" section for details. |
 | `codeMirrorTheme`    | `string`                                       | The name of a [CodeMirror theme](https://codemirror.net/5/demo/theme.html) for the text editor.         |
 
 ### Creating a Theme
@@ -86,6 +91,41 @@ The easiest way to start is using the built-in Theme Editor:
 3.  Modify the properties. The editor provides a live preview as you make changes.
 4.  Once you're happy, click **Save**.
 
+### Advanced Theming
+
+#### Using Custom Fonts
+You can embed custom fonts in your theme using the `css` property. By using the `@font-face` rule, you can load fonts from external services like Google Fonts. For best performance, you should link directly to the font file (e.g., a `.woff2` file).
+
+```css
+@font-face {
+  font-family: 'Roboto';
+  src: url('https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu4mxK.woff2') format('woff2');
+}
+body, button, input, textarea {
+  font-family: 'Roboto', sans-serif;
+}
+```
+
+#### Controlling Features with Toggles
+The Theme Editor modal includes toggles for all major features (like gradients, custom CSS, animations, etc.). These toggles are always visible, allowing users to see the full range of customization options.
+
+When you create a theme, you can define which of these features are active by default. For example, if you include a `gradient` object in your `theme.json`, the "Gradient" toggle will be enabled and switched on. If you omit the `gradient` property, the toggle will be switched off.
+
+The `toggles` property in your `theme.json` gives you explicit control. By setting a feature's corresponding key to `true` or `false` in the `toggles` object, you can define its default on/off state in the editor. This is useful for creating themes with optional features that you want to be explicitly enabled or disabled by default.
+
+Here are the available toggles:
+
+- `cssVariables`
+- `customCss`
+- `animationScript`
+- `tsParticles`
+- `gradient`
+- `systemBackgroundImage`
+- `chatBackgroundImage`
+
+### The Documentation Tab
+The Theme Editor includes a "Documentation" tab, which is a valuable resource when creating themes. It contains a table of all available CSS variables with their default values and descriptions, as well as the full theme schema.
+
 ### Example 1: Simple Color Theme
 
 This theme creates a "Forest" look by overriding the default CSS color variables.
@@ -164,6 +204,23 @@ For complete control, you can provide JavaScript for a custom canvas animation.
 }
 ```
 
+### Example 5: Background Image Theme
+
+This theme adds a background image to the chat and the overall system.
+
+```json
+{
+  "id": "galaxy-explorer",
+  "name": "Galaxy Explorer",
+  "base": "oled-dark",
+  "emoji": "🚀",
+  "systemBackgroundImageUrl": "https://example.com/path/to/galaxy.jpg",
+  "systemBackgroundImageDarken": 0.5,
+  "chatBackgroundImageUrl": "https://example.com/path/to/space.jpg",
+  "chatBackgroundImageDarken": 0.3
+}
+```
+
 ### Sharing Your Theme
 
 To make your theme easily shareable and updatable, host the `theme.json` file somewhere with a raw file link (like GitHub Gist or a public repository) and set the `sourceUrl` property to that link. This allows others to install your theme with one click and receive updates automatically.