From e4a989046f066e9cd4aaa231da1a71e09221ef36 Mon Sep 17 00:00:00 2001
From: Falkan <falkan@openclaw.local>
Date: Tue, 17 Mar 2026 18:01:12 -0400
Subject: [PATCH] =?UTF-8?q?docs:=20correct=20ghost=20button=20hover=20gotc?=
 =?UTF-8?q?ha=20=E2=80=94=20must=20override=20CSS=20vars,=20not=20just=20c?=
 =?UTF-8?q?olor?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 PICO_CSS.md | 37 +++++++++++++++++++++----------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/PICO_CSS.md b/PICO_CSS.md
index 6f9e7a4..67fea7b 100644
--- a/PICO_CSS.md
+++ b/PICO_CSS.md
@@ -24,33 +24,38 @@ In light mode, `--pico-primary-inverse` is `#fff`. This means **any element with
 
 **Alternative:** Remove `role="button"` and use `tabindex="0"` + keyboard handlers only, avoiding the Pico button rule entirely. Only do this if button semantics aren't needed for accessibility.
 
-## Plain buttons disappear on hover in light/Dan mode
+## Plain/ghost buttons disappear on hover in light/Dan mode
 
-Pico's button hover rule sets `--pico-color: var(--pico-primary-inverse)` (i.e. `#fff`) on hover, making the text white. If your button has a transparent or white background — e.g. a "plain" / ghost-style button — the text becomes invisible.
-
-This affects any `<button>` element, not just `[role=button]`. The `plain` class (or similar resets) strips Pico's background/border, but **does not prevent Pico from overriding the text color on hover**.
-
-**Symptom:** button text vanishes on hover in light or Dan mode, visible in dark mode (where the background is already dark).
-
-**Fix:** Use `!important` on hover to override Pico's specificity, and also explicitly reset the background so you're sure nothing sneaks in:
+Pico's button hover rule sets **both** CSS custom properties **and** computed values:
 
 ```css
-.my-plain-button:not(:disabled):hover {
-  color: var(--pico-color) !important;
-  background: transparent;
+button:is(:hover,:active,:focus) {
+  --pico-background-color: var(--pico-primary-hover-background);
+  --pico-border-color:     var(--pico-primary-hover-border);
+  --pico-color:            var(--pico-primary-inverse);  /* #fff in light mode */
 }
 ```
 
-Or, if you want a specific non-body text color on hover:
+If your button has a transparent or white background — e.g. a ghost/plain-style button — the text becomes invisible because `--pico-primary-inverse` is `#fff` in light mode.
+
+**Important:** Overriding only `color: ... !important` is **not enough**, because Pico sets `--pico-color` as a CSS variable that other rules may read. You must override all three custom properties *and* the corresponding computed properties simultaneously.
+
+**Symptom:** ghost button text vanishes on hover in light or Dan mode (background goes blue, text goes white). Works fine in dark mode because the dark background makes white text readable.
+
+**Fix:** Override all Pico button hover variables explicitly:
 
 ```css
-.my-plain-button:not(:disabled):hover {
-  color: var(--pico-contrast) !important; /* always legible */
-  background: transparent;
+.my-ghost-button:not(:disabled):hover {
+  --pico-color:            var(--pico-contrast) !important; /* near-black in light, near-white in dark */
+  --pico-background-color: transparent !important;
+  --pico-border-color:     var(--pico-contrast) !important;
+  color:                   var(--pico-contrast) !important;
+  background:              transparent !important;
+  border-color:            var(--pico-contrast) !important;
 }
 ```
 
-**Do not** rely on Pico's hover cascade for plain/ghost buttons — always override explicitly.
+Use `--pico-contrast` (not `--pico-color`) as the hover text color — it's `#181c25` in light mode and `#dfe3eb` in dark mode, so it's always legible against the page background regardless of theme.
 
 ## Palette overrides must be scoped to light mode