1 files changed, 130 insertions, 0 deletions
diff --git a/docs/guide/lua/theming.md b/docs/guide/lua/theming.md
new file mode 100644
index 0000000..502e8e9
--- /dev/null
+++ b/docs/guide/lua/theming.md
@@ -0,0 +1,130 @@
+# Theming
+
+Since the widget toolkit is **GTK3** theming is done with **CSS**.
+
+- [CSS tutorial](https://www.w3schools.com/css/)
+- [GTK CSS Overview wiki](https://docs.gtk.org/gtk3/css-overview.html)
+- [GTK CSS Properties Overview wiki](https://docs.gtk.org/gtk3/css-properties.html)
+
+:::warning GTK is not the web
+While most features are implemented in GTK,
+you can't assume anything that works on the web will work with GTK.
+Refer to the [GTK docs](https://docs.gtk.org/gtk3/css-overview.html)
+to see what is available.
+:::
+
+So far every widget you made used your default GTK3 theme.
+To make them more custom, you can apply stylesheets to them.
+
+## From file at startup
+
+You can pass a path to a file or css as a string in `App:start`
+
+:::code-group
+
+```lua [init.lua]
+local inline_css = [[
+    window {
+        background-color: transparent;
+    }
+]]
+
+App:start({
+    css = inline_css,
+    css = "/path/to/style.css",
+    css = "./style.css",
+})
+```
+
+:::
+
+:::warning
+When using relative paths, so for example `./style.css` keep in mind that they
+will be relative to the current working directory.
+:::
+
+## Css Property on Widgets
+
+```lua
+Widget.Label({
+    css = "color: blue; padding: 1em;",
+    label = "hello"
+})
+```
+
+:::info
+The `css` property of a widget will not cascade to its children.
+:::
+
+## Apply Stylesheets at Runtime
+
+You can apply additional styles at runtime.
+
+```lua
+App:apply_css("/path/to/file.css")
+```
+
+```lua
+App:apply_css([[
+    window {
+        background-color: transparent;
+    }
+]])
+```
+
+```lua
+App:reset_css() -- reset if need
+```
+
+:::warning
+`App:apply_css` will apply on top of other stylesheets applied before.
+You can reset stylesheets with `App:reset_css`
+or by passing `true` as a second parameter to `App:apply_css`.
+:::
+
+## Inspector
+
+If you are not sure about the widget hierarchy or any CSS selector,
+you can use the [GTK inspector](https://wiki.gnome.org/Projects/GTK/Inspector)
+
+```sh
+# to bring up the inspector run
+astal --inspector
+```
+
+## Using SCSS
+
+Gtk's CSS only supports a subset of what the web offers.
+Most notably nested selectors are unsupported by Gtk, but this can be
+workaround by using preprocessors like [SCSS](https://sass-lang.com/).
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu dart-sass
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+npm install -g sass # not packaged on Fedora
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+npm install -g sass # not packaged on Ubuntu
+```
+
+:::
+
+:::code-group
+
+```lua [init.lua]
+local scss = "./style.scss"
+local css = "/tmp/style.css"
+
+astal.exec(string.format("sass %s %s", scss, css))
+
+App:start({
+    css = css,
+})
+```
+
+:::