feat: add theming docs

docs/plugin-api.md

@@ -212,3 +212,5 @@ OpenSCD core sets the following CSS variables on the plugin:
   --oscd-icon-font: var(--oscd-theme-icon-font, 'Material Icons');
 }
 ```
+
+For more details on theming, please see [Theming Guide](theming.md)

docs/theming.md

@@ -0,0 +1,115 @@
+Each Plugin should set the default values for any oscd-ui (material) components used in their plugin and never set `oscd-theme-*` variables directly within the plugin.
+
+# How OpenSCD Theming works
+
+When a distro is created, the developer will most likely want to brand their distro with the appropriate corporate theming. If plugins ignore theming, those plugins may appear badly in some distros.
+The general convention is to initialize your own set of internal `oscd-*`variables from the equivalent theme values `--oscd-theme-*` with a fall back defaults. This means, without any theme values being applied to the distro, the plugin appears as designed. By referencing `--oscd-theme-*` variables, the distro developers can override these defaults when needed.
+
+# Do's and Don'ts
+
+## Don't
+
+- Don't hardcode values. E.g. `* { --md-sys-color-primary: #33FFFF; }`, this makes your plugin unthemable.
+- Don't set `--oscd-theme-*` variables inside your plugin - this is basically the same as hardcoding your own values
+- Don't rely on `oscd-theme-*` being set for you. The distro will likely set these but it isn't required - always have a fallback default value.
+
+## Do
+
+- Set default values for the Material (oscd-ui) components used in the plugin.
+- Initialize "internal" theme colours (`--oscd-*`) by referencing the theme variable (if set), falling back to the reasonable default.
+  E.g. `* { --oscd-primary: var(--oscd-theme-primary, #0b335b); }`
+  Then, in sub-components, just reference the internal pallet (`--oscd-*`). You could reference `--oscd-them-*` but then you need to repeatedly set the same defaults everywhere too.
+- Conventionally, the root component of the plugin would be the single place where variables are set, such that sub-components inherit these values. E.g.:
+
+  ```css
+  * {
+    --oscd-primary: var(--oscd-theme-primary, #0b335b);
+    --oscd-base2: var(--oscd-theme-base2, #f3f5f6);
+    --oscd-font: var(--oscd-theme-font, 'Roboto');
+  }
+
+  /* root component specific styling... */
+  * {
+    /* For illustration purposes only. These could of course be placed in the block above.
+       * It can be helpful to set in each component only what you need, so you know what your
+       * influencing in that component and not assuming its set elsewhere. 
+       */
+    --md-sys-color-primary: var(--oscd-primary);
+    --md-sys-color-on-primary: var(--oscd-base2);
+    font-family: var(--oscd-font);
+  }
+  ```
+
+  # Supported OpenSCD Variables
+
+  The following can be dropped in to the top of your plugins root component, then remove what isn't being used.
+
+  ```css
+
+  ```
+
+* {
+  --oscd-primary: var(--oscd-theme-primary, #2aa198);
+  --oscd-secondary: var(--oscd-theme-secondary, #6c71c4);
+  --oscd-error: var(--oscd-theme-error, #dc322f);
+
+  --oscd-base03: var(--oscd-theme-base03, #002b36);
+  --oscd-base02: var(--oscd-theme-base02, #073642);
+  --oscd-base01: var(--oscd-theme-base01, #586e75);
+  --oscd-base00: var(--oscd-theme-base00, #657b83);
+  --oscd-base0: var(--oscd-theme-base0, #839496);
+  --oscd-base1: var(--oscd-theme-base1, #93a1a1);
+  --oscd-base2: var(--oscd-theme-base2, #eee8d5);
+  --oscd-base3: var(--oscd-theme-base3, #fdf6e3);
+
+  --oscd-shape: var(--oscd-theme-shape, 8px);
+
+  --oscd-text-font: var(--oscd-theme-text-font, 'Roboto');
+  --oscd-text-font-mono: var(--oscd-theme-text-font-mono, 'Roboto Mono');
+  --oscd-icon-font: var(--oscd-theme-icon-font, 'Material Icons');
+  }
+
+````
+## Shape
+
+The `--oscd-shape` variable controls the corner radius used throughout the application.
+
+OpenSCD derives the Material Design shape scale from this value and maps it to the following Material shape tokens:
+
+```css
+--md-sys-shape-corner-none;
+--md-sys-shape-corner-extra-small;
+--md-sys-shape-corner-small;
+--md-sys-shape-corner-medium;
+--md-sys-shape-corner-large;
+````
+
+The shape scale is derived from `--oscd-shape`, which represents the Material `small` corner size.
+
+| Token         | Value                |
+| ------------- | -------------------- |
+| `none`        | `0`                  |
+| `extra-small` | `0.5 × --oscd-shape` |
+| `small`       | `1 × --oscd-shape`   |
+| `medium`      | `1.5 × --oscd-shape` |
+| `large`       | `2 × --oscd-shape`   |
+
+For example:
+
+```css
+:root {
+  --oscd-shape: 8px;
+}
+```
+
+Results in:
+
+```css
+--md-sys-shape-corner-none: 0;
+--md-sys-shape-corner-extra-small: 4px;
+--md-sys-shape-corner-small: 8px;
+--md-sys-shape-corner-medium: 12px;
+--md-sys-shape-corner-large: 16px;
+```
+
+These values follow the Material Design 3 shape scale rather than a fixed proportional relationship. Increasing or decreasing `--oscd-shape` adjusts the overall roundness of components while preserving the relative differences between shape categories.