docs: document plain button hover invisibility gotcha in PICO_CSS.md

PICO_CSS.md

@@ -24,6 +24,34 @@ 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
+
+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:
+
+```css
+.my-plain-button:not(:disabled):hover {
+  color: var(--pico-color) !important;
+  background: transparent;
+}
+```
+
+Or, if you want a specific non-body text color on hover:
+
+```css
+.my-plain-button:not(:disabled):hover {
+  color: var(--pico-contrast) !important; /* always legible */
+  background: transparent;
+}
+```
+
+**Do not** rely on Pico's hover cascade for plain/ghost buttons — always override explicitly.
+
 ## Palette overrides must be scoped to light mode
 
 Pico defines its palette twice: once for light (`:root:not([data-theme=dark])`) and once for dark (`@media (prefers-color-scheme: dark)` + `[data-theme=dark]`). If you override Pico vars at bare `:root`, you'll clobber the dark mode values.