Update theming docs after #9698

changelog/unreleased/change-theme-handling

@@ -12,7 +12,9 @@ https://github.com/owncloud/web/issues/8424
 https://github.com/owncloud/web/issues/9403
 https://github.com/owncloud/web/issues/9885
 https://github.com/owncloud/web/issues/9939
+https://github.com/owncloud/web/issues/10146
 https://github.com/owncloud/web/pull/8855
 https://github.com/owncloud/web/pull/9396
 https://github.com/owncloud/web/pull/9401
 https://github.com/owncloud/web/pull/9698
+https://github.com/owncloud/web/pull/10151

docs/theming/_index.md

@@ -25,41 +25,69 @@ To reference your theme, you have two options:
 - Using a URL, e.g. `"theme": "https://externalurl.example.com/theme-name/theme.json",`. To avoid CORS issues, please make sure that you host the URL on the same URL as your ownCloud web hosting.
 - For development and testing purposes, you can store your `theme.json` inside `packages/web-runtime/themes/{theme-name}/` and reference it in the `config.json`. However, this isn't recommended for production use since your changes may get lost when updating oCIS or the `web` app in OC10.
 
-**Hint:** If no theme is provided or the loading of your custom theme fails, the standard ownCloud theme will be loaded as a fallback. However, this doesn't stop you from correctly loading a theme that is wrongly formatted, so please read the instructions below carefully.
+**Hint:** If no theme is provided, the loading of your custom theme fails or the theme can't be parsed correctly, the standard ownCloud theme will be loaded as a fallback and an error with further information will be logged on the browser console.
 
 ## Configuring a theme
 
-Inside your `theme.json`, you can provide multiple themes as first-level objects. Currently, only the one called `"default"` gets applied when the frontend application is started. In the future, we'll provide functionality to dynamically switch between those themes.
+Inside your `theme.json`, there is a `common` key, which is explained in the next section, and a `clients` key: Here, you can find the available ownCloud clients - please note that the documentation below focuses on `web` and check the respective documentation for other clients for details on their themability.
 
-You can use the snippet below as a base for writing your own theme by replacing the strings and image file paths accordingly. Also, make sure to delete the comments from the file.
+The general top-level structure of a valid `theme.json` is outlined below:
+
+```json
+{
+  "common": {},
+  "clients": {
+    "android": {},
+    "desktop": {},
+    "ios": {},
+    "web": {}
+  }
+}
+```
+
+### Common section
+
+The `common` section provides a set of information that is designed to be available for all clients. It gets merged "down" to the final themes and aims to reduce duplication, but can be overwritten by more specific information inside both the clients' defaults and actual themes.
+
+The structure of a valid `comon` section is outlined below:
+
+```json
+"common": {
+  "name": "ownCloud",
+  "slogan": "ownCloud – A safe home for all your data",
+  "logo": "themes/owncloud/assets/logo.svg",
+  "urls": {
+    "accessDeniedHelp": "",
+    "imprint": "",
+    "privacy": ""
+  }
+}
+```
+
+## Web Theme
+
+The structure of a valid `web` client section is outlined below:
 
 ```json
 {
-  "common": {
-    "name": "ownCloud",
-    "slogan": "ownCloud – A safe home for all your data",
-    "logo": "themes/owncloud/assets/logo.svg"
-  },
-  "ios": {},
   "web": {
-    "default": {
-      "general": {
-        "name": "ownCloud",
-        "slogan": "ownCloud – A safe home for all your data"
+    "defaults": {
+      "appBanner": {
+        // Please see below for details
       },
       "logo": {
-        "topbar": "https://externalurl.example.com/url/for/remote/theme/assets/logo.svg",
-        "favicon": "https://externalurl.example.com/url/for/remote/theme/assets/favicon.jpg",
-        "login": "relative/path/for/local/theme/logo.svg"
+        // Please see below for details
       },
       "loginPage": {
-        "autoRedirect": true,
-        "backgroundImg": "relative/path/for/local/theme/background.jpg"
+        // Please see below for details
       },
-      "designTokens": {}
+      "designTokens": {
+        // Please see below for details
+      }
     },
-    "alternative": {},
-    "dark": {}
+    "themes": [
+      // Your custom web themes go here, see below for details
+    ]
   }
 }
 ```