diff --git a/config.md b/config.md
new file mode 100644
index 0000000..7594798
--- /dev/null
+++ b/config.md
@@ -0,0 +1,155 @@
+## Configuration  
+
+### Configuration file  
+
+Popcorn loads a single TOML configuration file from:  
+```
+~/.config/candywidgets/popcorn/config.toml  
+```  
+If the file is missing or incomplete, built-in defaults are used.  
+
+Tip: You can maintain multiple config files for different themes and symlink the one you want active.  
+
+### General rules for config values  
+
+- Any missing or misconfigured field normally falls back to sane defaults.  
+- Values must be plain integers or strings.  
+  - No expressions or functions.  
+  - No unit suffixes like "px," "ms," etc.  
+- Dimensions and positions are positive integers in pixels.  
+- Colors are 8-digit `"AARRGGBB"` hex strings.  
+  - Leading '#' is ignored. So, `"#675f5f5f"` is equal to `"675f5f5f"`.  
+  - Alpha (`AA`) determines transparency (`00`: Invisible, `ff`: Solid)  
+  - Invalid or short hex strings may cause Popcorn to exit with errors.  
+- Font names are strings.  
+  - If the font is missing or misconfigured, your system may use a fallback.  
+- Time values are positive integers in milliseconds.  
+
+### Sections  
+
+The configuration file has 4 sections that control specific aspects of the popup:  
+
+- `[window]` - Popup placement and timeout settings.  
+- `[ui]` - Base UI geometry and colors.  
+- `[percent_value]` - Styling for percentage text.  
+- `[icon]` - Styling for icon glyph.  
+
+### Section 1: `[window]`  
+
+This section controls popup position and how long it stays visible.  
+
+##### `popup_timeout`  
+- Auto-hide timeout in milliseconds.  
+- Default: `1300`  
+
+##### `pos_x`  
+- Horizontal position of the popup.  
+- Default: `1146`  
+- Adjust based on your screen resolution.  
+- Example: 1366px wide screen - 200px popup width - 20px offset = 1146px  
+
+##### `pos_y`  
+- Vertical position of the popup.  
+- Default: `36`  
+
+Adjust `pos_x` and `pos_y` based on your screen resolution and popup width/height.  
+
+### Section 2: `[ui]`  
+
+Basic popup appearance styling. Set the dimensions according to your screen resolution.  
+
+##### `width`  
+- Width of the popup.  
+- Default: `200`  
+- If you resize the popup, you may need to update `pos_x` and `pos_y` to keep it where you expect.  
+
+##### `height`  
+- Height of the popup.  
+- Default: `50`  
+
+##### `border_radius`  
+- Border radius of the popup.  
+- Default: `5`  
+- Tip:  
+  - `0`: Sharp corners, rectangular  
+  - `height/2`: Circular sides, pill shape  
+  - Between `0` & `height/2`: Rounded corners  
+
+##### `padding`  
+- Distance from the sides to the icon and the percent value.  
+- Default: `7`  
+
+##### `bg_col`  
+- Background color of the popup.  
+- Default: `"675f5f5f"`  
+
+##### `default_fill_color`  
+- Fallback for no or invalid fill color is supplied via CLI arg `--color`  
+- Default: `"ff397979"`  
+
+### Section 3: `[percent_value]`  
+
+Controls the percentage text style (for volume, brightness, battery, etc).  
+
+##### `font_size`  
+- Font size for the percent value.  
+- Default: `35`  
+
+##### `font_color`  
+- Font color for the percentage value.  
+- Default: `"ffffffff"`  
+
+##### `font`  
+- Font family for the percentage value.  
+- Default: `"Iosevka Extrabold"`  
+
+### Section 4: `[icon]`  
+
+Icon glyph styling configuration.  
+
+##### `size`  
+- Font size for the icon glyph.  
+- Default: `35`  
+
+##### `color`  
+- Font color for the icon glyph.  
+- Default: `"ffffffff"`  
+
+##### `font`  
+- Font color for the icon glyph.  
+- Default: `"IosevkaTermSlab Nerd Font Mono"`  
+- Tip: Use Nerd Font icons or another icon font for best results.
+
+##### `default_icon`  
+- Default glyph used when no or invalid icon is suppliedvia CLI arg `--icon`  
+- Default: `""`  
+
+### Example  
+
+Here's a full working configuration example:  
+
+```toml  
+[window]
+popup_timeout = 1300
+pos_x = 1146
+pos_y = 36
+
+[ui]
+width = 200
+height = 50
+border_radius = 5
+padding = 7
+bg_col = "675f5f5f"
+default_fill_color = "ff397979"
+
+[percent_value]
+font_size = 35
+font_color = "ffffffff"
+font = "Iosevka Extrabold"
+
+[icon]
+size = 35
+color = "ffffffff"
+font = "IosevkaTermSlab Nerd Font Mono"
+default_icon = ""
+```