taffybar: add comments explaining recent CSS additions

Document the @import url() requirement, per-widget color variables,
workspace label positioning via padding (not margin, which GTK
overlays ignore), asymmetric workspace padding, active workspace
outline targeting, and bar border-radius.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

dotfiles/config/taffybar/taffybar.css

@@ -1,6 +1,8 @@
 /* Widget/layout styling for taffybar.
  *
  * Colors live in `theme.css` (loaded via `palette.css`).
+ * IMPORTANT: use `@import url("...")` — bare `import` is silently ignored
+ * by GTK's CSS parser.
  */
 @import url("theme.css");
 
@@ -18,6 +20,8 @@
 }
 
 
+/* The main bar container. border-radius matches the widget squircles (6px)
+   so the bar itself has softly rounded corners. */
 .taffy-box {
 	border-width: 0px;
 	padding: 0px;
@@ -28,6 +32,10 @@
 	background-image: none;
 }
 
+/* Each widget is wrapped in outer-pad > inner-pad > contents by
+   buildContentsBox (Haskell).  The outer-pad draws the squircle
+   background pill.  border-radius kept low (6px) for a more squared
+   "squircle" shape rather than a fully rounded pill. */
 .outer-pad {
 	background-color: @pill-background;
 	border: 0px;
@@ -61,7 +69,10 @@
 	background-color: transparent;
 }
 
-/* Right side widget palette overrides */
+/* Per-widget colored squircle overrides.
+   decorateWithClassAndBox "name" (in taffybar.hs) adds the widget class to
+   the same element that has .outer-pad, so `.outer-pad.audio` etc. target
+   each widget's pill.  Colors come from @widget-*-bg/fg/border in theme.css. */
 .outer-pad.audio {
 	background-color: @widget-audio-bg;
 	border-color: @widget-audio-border;
@@ -138,6 +149,8 @@
 
 /* Workspaces styling */
 
+/* Asymmetric padding: 10px left leaves room for the overlaid workspace number
+   label; 3px right keeps the pill tight against the trailing icon edge. */
 .workspaces .inner-pad {
 	box-shadow: none;
 	border-width: 0;
@@ -176,6 +189,10 @@
 	padding: 0px;
 }
 
+/* Position the workspace number inside the squircle pill.  GTK overlays ignore
+   CSS margin for child positioning, so we use padding on the label itself:
+   padding-bottom pushes the text up from the bottom edge, padding-left pushes
+   it inward from the left corner to clear the border-radius. */
 .workspaces .overlay-box .workspace-label {
 	background-color: transparent;
 	border: none;
@@ -183,6 +200,10 @@
 	color: rgba(255, 255, 255, 0.92);
 }
 
+/* White inset outline on the active workspace's squircle pill.
+   .active is set on the GtkOverlay (by setWorkspaceWidgetStatusClass in
+   Haskell), and .outer-pad is a child of that overlay, so
+   `.workspaces .active .outer-pad` correctly targets the pill. */
 .workspaces .active .outer-pad {
 	box-shadow:
 		inset 0 0 0 2px rgba(255, 255, 255, 0.75),

dotfiles/config/taffybar/theme.css

@@ -6,7 +6,7 @@
 
 @define-color accent #f1b2b2;
 
-/* Bar chrome */
+/* Bar chrome — low alpha so the desktop wallpaper shows through. */
 @define-color bar-background rgba(0, 0, 0, 0.35);
 @define-color bar-gradient-start rgba(20, 26, 40, 0.68);
 @define-color bar-gradient-end rgba(12, 18, 30, 0.68);
@@ -21,35 +21,48 @@
 @define-color pill-highlight rgba(255, 255, 255, 0.10);
 @define-color pill-shadow rgba(0, 0, 0, 0.28);
 
-/* Per-widget backgrounds — distinct tinted squircles */
+/* Per-widget backgrounds — each widget gets a distinct tinted squircle so they
+   are visually distinguishable at a glance.  Each group defines:
+     *-bg     : pill background color (semi-transparent, dark-tinted)
+     *-fg     : text/icon color (light, tinted to complement the background)
+     *-border : subtle border stroke color */
+
+/* PulseAudio volume widget — purple */
 @define-color widget-audio-bg      rgba(110, 45, 160, 0.92);
 @define-color widget-audio-fg      #e8d5f8;
 @define-color widget-audio-border  rgba(155, 85, 210, 0.60);
 
+/* NetworkManager wifi/ethernet widget — teal */
 @define-color widget-network-bg     rgba(20, 120, 140, 0.92);
 @define-color widget-network-fg     #d0f2f8;
 @define-color widget-network-border rgba(50, 175, 200, 0.60);
 
+/* MPRIS2 now-playing widget — rose/crimson */
 @define-color widget-mpris-bg      rgba(160, 40, 70, 0.92);
 @define-color widget-mpris-fg      #f8d5e0;
 @define-color widget-mpris-border  rgba(210, 80, 115, 0.60);
 
+/* Clock widget — indigo/royal blue */
 @define-color widget-clock-bg      rgba(50, 60, 160, 0.92);
 @define-color widget-clock-fg      #d5d8f8;
 @define-color widget-clock-border  rgba(90, 100, 210, 0.60);
 
+/* Disk-usage widget — emerald green */
 @define-color widget-disk-bg       rgba(25, 130, 75, 0.92);
 @define-color widget-disk-fg       #c8f5e0;
 @define-color widget-disk-border   rgba(55, 190, 115, 0.60);
 
+/* StatusNotifierItem system tray — neutral dark slate */
 @define-color widget-tray-bg       rgba(65, 70, 100, 0.92);
 @define-color widget-tray-fg       #d8dae8;
 @define-color widget-tray-border   rgba(110, 115, 160, 0.60);
 
+/* Battery (icon and text) — amber/gold */
 @define-color widget-battery-bg    rgba(160, 115, 20, 0.92);
 @define-color widget-battery-fg    #f8ecc5;
 @define-color widget-battery-border rgba(210, 165, 50, 0.60);
 
+/* Backlight/brightness widget — warm golden */
 @define-color widget-backlight-bg    rgba(170, 120, 15, 0.92);
 @define-color widget-backlight-fg    #f8efc5;
 @define-color widget-backlight-border rgba(220, 170, 45, 0.60);