Add THEMING.md

docs/PCN.md

@@ -1,8 +1,8 @@
 # PCN File Format
 
-Config and theme files are written in the PCN (Python Config Notation) format,
-which are organized in a hierarchy of sections and properties.
-PCN files can also contain usual Python code, such as imports and
+This document explains in details the PCN (Python Config Notation) format.
+PCN files are organized in a hierarchy of sections and properties.
+PCN files can also contain normal Python code, such as imports and
 custom functions.
 
 - [Overview](#overview)

docs/THEMING.md

@@ -0,0 +1,54 @@
+# Theming
+
+A default theme from this repository can be copied to use as a base and edit,
+for example:
+
+```sh
+    cp mirage/src/themes/Midnight.qpl \
+       "${XDG_DATA_HOME:-$HOME/.local/share}/mirage/themes/MyTheme.qpl"
+```
+
+Or for Flatpak users:
+
+```sh
+    cp mirage/src/themes/Midnight.qpl \
+       ~/.var/app/io.github.mirukana.mirage/data/mirage/themes/MyTheme.qpl
+```
+
+The `theme` property in [`settings.py`](CONFIG.md#settingspy) would need
+to be set to `MyTheme.qpl` in this case.
+
+Theme files are nested-by-indentations sections of properties and values.  
+Properties are declared as `<type> <name>: <value>`.  
+Values can be any JavaScript (ECMAScript 7) expressions.
+
+Most of the properties are of type `color`.
+Their values, if not just refering to another property,
+can be expressed with a:
+
+- [SVG/CSS color name](https://www.december.com/html/spec/colorsvg.html)
+  string, e.g. `"blue"`
+- Hexadecimal code string, e.g. `"#fff"` or `"#cc0000"`
+- RGBA value, using the `Qt.rgba(0-1, 0-1, 0-1, 0-1)` function
+- HSLA value, using the `Qt.hsla(0-1, 0-1, 0-1, 0-1)` function
+- HSVA value, using the `Qt.hsva(0-1, 0-1, 0-1, 0-1)` function
+- [HSLUV](https://www.hsluv.org/) value, using the
+  `hsluv(0-360, 0-100, 0-100, 0-1)` function. This is the prefered method 
+  used throughout the default theme files
+  (why? see [this](https://www.hsluv.org/comparison/#rainbow-hsluv) and
+  [that](https://www.boronine.com/2012/03/26/Color-Spaces-for-Human-Beings/#hsl-is-a-lemon))
+
+If you just want to change the background picture,
+or use a gradient/simple color instead, search for the `ui:` section in your
+text editor.
+
+When an in-use theme file is saved while the application is running, it 
+will automatically be reloaded and changes will be seen immediatly.
+
+**Warnings**: 
+
+- API currently unstable: theme properties are often renamed, added or deleted.
+- The file format for themes will soon change
+- The current file format forces all theme to have all properties
+  defined, instead of being able to only specify the ones to override from the
+  default theme.