Shade the window frame, panel headers and file rows apart

Every surface was one flat shade. The window now reads in layers: a darker
frame (tab, transfer and status bars), a lighter header strip per file panel
(session strip, path bar, column headers), the file list, and popovers above
them all. The active panel's header carries a tint of the accent, and odd file
rows get a faint zebra stripe (per row, so it stays aligned at any interface
scale; the cursor and selection replace it).

Hover and selected states become a translucent overlay: an opaque hover
vanished on a surface of its own lightness (light's header strip). Dark cards
and badges step up so popovers never read darker than the strip they cover.
AMOLED is unchanged: every new layer collapses to black there.

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

docs/architecture.md

@@ -289,16 +289,23 @@ component; tokens → `ui/src/styles.css`.
 mode) — every dark token change goes in BOTH. Light is the zinc family; the
 dark neutrals are a **warm gray family (hue 107)** anchored on `#1a1a19`
 (`--background`) — retoning one dark neutral means retoning them all, or warm
-and cool surfaces clash. Surface elevation ramp, both themes: `--chrome`
-(frame strips) sits *below* `--background` (content panes) < `--card`
-(popovers/dialogs) < `--accent` (hover). Dark ramp `#151514` → `#1a1a19` →
-`#20201f` → `#2e2e2d`. The "darker" tone is true-black AMOLED: `--chrome` AND
-`--background` are both `#000` (the frame/content step collapses on purpose),
-elevation survives only via `--card`/`--accent`, and `--border`/`--input` go to
-16%/18% white because those lines then carry the whole layout.
-`bg-chrome` is on the tab bar, status bar, transfer bar, the editor/manager
-header+footer strips and the manager's connection sidebar; panel-internal
-toolbars deliberately stay on `--background`. Accent tones: one
+and cool surfaces clash. **Surface layers**, each its own shade: `--chrome`
+(frame — tab/transfer/status bars, editor/manager header+footer strips, the
+manager's connection sidebar), `--toolbar` (each file panel's header strip —
+session strip, path bar, column headers — and the editor's search bar; the
+ACTIVE panel's strip is `--toolbar-active`, a `color-mix` of `--primary` into
+`--toolbar`, so it follows the accent), `--background` (file lists, editor
+text, forms; `--row-alt` stripes odd file rows, skipped on the cursor/selected
+row so two `bg-*` utilities never fight) and `--card` (popovers, dialogs,
+toasts). Dark climbs frame 0.165 < list 0.218 < header 0.265 < card 0.285;
+light steps greys out from white content: frame 0.935 < header 0.965 < list =
+card 1. **`--accent` is translucent** (6% zinc-900 light, 9% white dark):
+hover/selected states sit on every layer, and an opaque hover vanishes on a
+surface of its own lightness. The "darker" tone is true-black AMOLED: chrome,
+background, toolbar (+active) and row-alt are all `#000` (the layers collapse
+on purpose), elevation survives only via `--card`/`--accent` (opaque there),
+and `--border`/`--input` go to 16%/18% white because those lines then carry the
+whole layout. Accent tones: one
 `--tone-h/--tone-c` line per tone + three formula blocks derive `--primary`,
 `--ring`, `--cursor-tint`; graphite = attribute removed = pristine zinc.
 `@theme inline` maps tokens to Tailwind utilities (`bg-primary`,

docs/gotchas.md

@@ -56,6 +56,21 @@ touching the adjacent code.
   anything poking out of a horizontally scrolling strip (a raised tab, an
   underline at `-bottom-px`) is silently clipped. Reserve padding instead.
 
+## Theming (`ui/src/styles.css`)
+
+- **A new surface token needs an AMOLED line, or AMOLED stops being
+  all-black.** The two `[data-dark-tone='darker']` blocks re-declare every
+  surface (`--chrome`, `--toolbar`, `--toolbar-active`, `--row-alt`, …) as
+  `#000`; a token added only to the dark blocks shows through in AMOLED.
+- **Never declare one token in both the AMOLED blocks and the accent dark
+  formula blocks.** Both are (0,3,0), so source order decides and the later
+  accent block wins. That is why `--toolbar-active` lives in the base theme
+  blocks — its `var(--primary)` resolves per accent on `:root` anyway.
+- **Hover/selected color is a translucent overlay (`--accent`).** An opaque
+  hover vanishes on a surface of its own lightness — light's old 0.967 hover
+  on the 0.965 header strip did exactly that. Keep `--accent` alpha-based when
+  retoning surfaces.
+
 ## The interface scale (root font-size lever)
 
 - **electrobun's native page zoom is a silent no-op on Linux — do not reach for