1 files changed, 135 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0a37bd5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,135 @@
+# waybar-theme-udt
+
+A waybar bar for DP-3: pill clusters, icons from the desktop's own icon theme
+instead of font glyphs, and colours driven by
+[unified-desktop-theme](../unified-desktop-theme).
+
+    [◆] [📅 Wed 15/09] [🕑 14:32] [1..8] [●●]   [ open apps ]   [🔊] [tray] [⏻] [🇮🇹]
+
+Each bracket is a pill. Pills group into clusters with gaps between them, so
+the bar reads as a few objects rather than one strip. Hover cross-fades
+background and text over 0.3s; taskbar buttons underline in the accent.
+
+## Install
+
+    ./install.sh
+
+Installs to `~/.config/waybar-udt/` and prints the command to run it. **The
+existing bar at `~/.config/waybar/` is left alone**, so DP-1 keeps working
+while this one is tried on DP-3.
+
+Needs `unified-desktop-theme` checked out next to this repo: the palette comes
+from there, and `install.sh` fails clearly if it is missing.
+
+## No glyphs
+
+Every symbol on this bar is a real icon from `Material-Black-Plum-Suru`, the
+theme GTK already uses. Icons keep their own colours, matching every other
+application on the desktop.
+
+waybar offers three ways to draw one, and this bar uses all three because no
+single one covers everything:
+
+| Mechanism | Used by | Why |
+| --- | --- | --- |
+| `icon-theme` config key | taskbar, tray | Native support, nothing else needed. |
+| `image` module | volume, microphone, presentation mode, language | Runs a script that resolves a state to an icon path. |
+| CSS `background-image` | workspaces, clock, launcher | `format-icons` takes text, not paths. |
+
+The consequence worth knowing: **the workspace icons live in
+`styles/modules.css`, not in the module config.** Changing one means editing
+CSS. The alternative was eight `custom` modules faking a workspace strip,
+which would have cost click-to-switch and the active and urgent states.
+
+The language flag went the other way. `hyprland/language` styles as
+`#language` and nothing else, with no per-language class, so the flag could
+not be picked by a selector; it is an `image` module driven by `wb-lang`
+instead.
+
+`wb-icon --selftest` checks every icon name the bar asks for, CSS ones
+included, and `install.sh` runs it. A missing icon renders as an empty pill
+with nothing to say why, so it fails while someone is watching instead.
+
+### Why the icons do not follow the accent
+
+2466 of the 5169 panel icons in `Material-Black-Plum-Suru` carry a hardcoded
+gradient and are not recolourable. That is intended here: icons match the rest
+of the desktop rather than the bar.
+
+The two icons this repo ships are the exception, because the icon theme has
+neither. `icons/slackware.svg` (Simple Icons, CC0) is single-path monochrome
+and takes the udt accent at install time. The two flags keep their national
+colours.
+
+## Layout
+
+| Cluster | Modules |
+| --- | --- |
+| left | launcher, date, time, workspaces, VM dots |
+| center | open applications |
+| right | privacy dots, volume drawer, tray, presentation mode, language |
+
+No battery, temperature, CPU, memory or backlight: this is a desktop.
+
+The clock is the only text on the bar. An icon cannot say 14:32, so the icon
+sits before the text, which is what makes the pair match the icon-only pills
+around it.
+
+### Workspaces
+
+| WS | Icon | |
+| --- | --- | --- |
+| 1 | `web-browser` | 5 | `document-edit` |
+| 2 | `utilities-terminal` | 6 | `applications-graphics` |
+| 3 | `text-editor` | 7 | `internet-chat` |
+| 4 | `network-server` | 8 | `input-gaming` |
+
+Workspace 4 uses the same icon as the quickshell drawer's VM tile. Names are
+generic, so the bar does not lie when the application on a workspace changes.
+
+## Colours
+
+This repo holds the bar; udt holds the palette. `styles/theme.css` is
+generated by `udt-palette` and gitignored, like every other generated file in
+that project.
+
+The dot scripts are bash and cannot read `@define-color`, so `install.sh`
+writes `~/.config/waybar-udt/dots.colors` for them to source. Both fall back to
+Macchiato values when it is missing, so they still run standalone.
+
+## Layout of this repo
+
+    config.jsonc          entry point; `include`s every module file
+    modules/              one file per module, by source
+    styles/               style.css imports the rest in order
+    icons/                the two icons the icon theme lacks
+    bin/                  wb-icon, wb-idle, and the two dot scripts
+
+Wildcard `include` has been broken since waybar v0.14.0, so `config.jsonc`
+lists every module file explicitly.
+
+`bin/vms_dots.sh` and `bin/privacy_dots.sh` used to live only in `~/bin`, in no
+repository. They are versioned here now and symlinked back; `install.sh` keeps
+any real file it finds there as `.pre-udt` first.
+
+## Reload
+
+    killall -SIGUSR2 waybar
+
+`reload_style_on_change` is on, so CSS edits apply by themselves.
+
+Visual changes are measured, not reasoned about:
+
+    grim -o DP-3 /tmp/shot.png
+
+## License
+
+GPLv2 only. See `LICENSE`.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.