trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/glass/depth/assets/glass.css

@@ -0,0 +1,322 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   Glass materials — three tiers, with every fallback.
+
+   PAIRS WITH glass/color/assets/color-tokens.css, which declares the
+   --glass-*-bg tints and their dark-theme values. This file holds the
+   material classes; that file holds the tints. Both are needed.
+
+   Why the tints live there and not here: they change per theme AND get
+   replaced wholesale by the reduced-transparency fallback, so they have to be
+   runtime :root custom properties rather than build-time tokens. (One of them
+   is also a gradient, which no colour-token system accepts.)
+
+   Three tiers, not four. The reference implementation also defines a
+   `glass-menu` (16px / 1.8 / 72%) for "a menu over a known surface" — and
+   nothing uses it. Every menu turned out to need glass-panel's defensive
+   tint, either because its wrapper animates or because it opens over other
+   glass. Dead CSS in a design system is worse than absent CSS: the next
+   person assumes it's load-bearing.
+   ───────────────────────────────────────────────────────────────────────── */
+
+@layer components {
+  /* ── Opaque baselines ──────────────────────────────────────────────────
+     What a browser without backdrop-filter gets. Progressive enhancement in
+     the correct direction: the opaque version is the DEFAULT and the glass is
+     layered on top. Invert it and the non-supporting path never gets tested.
+
+     Support is good (Firefox unflagged since 103), so this is insurance
+     rather than a live concern — but it's cheap insurance. */
+  .glass-nav {
+    background: var(--color-gray-100);
+  }
+  .glass-panel {
+    background: var(--color-gray-100);
+  }
+  .folder-glass {
+    background: var(--color-background-100);
+  }
+
+  /* ── The materials ─────────────────────────────────────────────────────
+     Test BOTH conditions — Safari shipped only the prefixed version for
+     years, and Safari is where glass matters most.
+
+     Only the standard `backdrop-filter` is written below, on purpose. Let the
+     build add `-webkit-backdrop-filter` (Lightning CSS in Tailwind v4, or
+     Autoprefixer). Lightning CSS keeps only the LAST of a hand-written pair,
+     so writing both, standard first, ships the prefixed one alone — and
+     Firefox, which only reads the standard property, loses every blur. With
+     no build step, write the prefixed line first and the standard one last. */
+  @supports (backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px)) {
+    /* Fixed chrome that arbitrary page content scrolls under — a paragraph, a
+       photograph, a full-bleed image wall. 20px because the less you know
+       about the backdrop, the more of it has to be suppressed so the
+       surface's own icons can be read.
+
+       saturate() is NOT decoration. Blur is a convolution, averaging colours
+       moves them toward grey, so a blurred backdrop is ALWAYS desaturated —
+       more so at larger radii. Without the boost you get the cloudy
+       "glassmorphism" wash. This one line is the difference between
+       translucent and dirty, and it costs nothing: same filter pass. */
+    .glass-nav {
+      background: var(--glass-nav-bg);
+      backdrop-filter: blur(20px) saturate(1.8);
+    }
+
+    /* Near-opaque (97%) on purpose, and for three reasons at once:
+
+       1. Its wrapper ANIMATES. A transform on an ancestor weakens
+          backdrop-filter in its subtree — the blur samples the wrong region,
+          or nothing, for the duration. So the TINT carries the legibility and
+          the blur is a bonus once it settles. General rule: when you can't
+          rely on the blur, thicken the tint.
+
+       2. It opens over OTHER GLASS (the nav dock). Two surfaces at the same
+          tint read as one object — the panel would look like the dock had
+          grown taller. The heavy tint buys tier separation.
+
+       3. At 97% you can actually COMPUTE text contrast against the tint. At
+          72% the effective background is whatever happens to be behind it,
+          and the ratio is not computable.
+
+       Where you have the choice, fix it structurally instead: animate the
+       wrapper, put the glass on a static child. */
+    .glass-panel {
+      background: var(--glass-panel-bg);
+      backdrop-filter: blur(24px) saturate(1.8);
+    }
+
+    /* A frosted pocket with cards peeking out behind it. 8px because here you
+       WANT the backdrop recognised — blur is softening, not obscuring. And
+       1.4 rather than 1.8 because those cards are the subject; pushing their
+       saturation would make the pocket louder than its own contents.
+
+       Its tint is a gradient (brighter at the top, where the light hits)
+       rather than a flat fill — the same idea as a 1px inset catch light, at
+       a scale where a 1px line would be lost. */
+    .folder-glass {
+      background: var(--folder-glass-bg);
+      backdrop-filter: blur(8px) saturate(1.4);
+    }
+  }
+
+  /* ── prefers-reduced-transparency ──────────────────────────────────────
+     Two reasons users set this: blur is expensive on low-powered devices,
+     and translucent surfaces are harder to read. One response serves both —
+     replace the material with an opaque one.
+
+     BOTH halves are mandatory and each is useless alone:
+       · filter only → a 72% tint over live content with no blur to suppress
+                       it. WORSE than the glass was; text overlaps text.
+       · tint only   → you still pay the whole cost of the blur, which was
+                       half the reason for the preference.
+
+     The tint half lives in color-tokens.css (it re-declares the :root
+     variables and must come after both theme blocks). This is the other half.
+
+     Useful side effect: with a solid tint, text contrast becomes real and
+     computable — for exactly the users most likely to need it. */
+  @media (prefers-reduced-transparency: reduce) {
+    .glass-nav,
+    .glass-panel,
+    .folder-glass {
+      backdrop-filter: none;
+    }
+  }
+
+  /* ── prefers-contrast: more ────────────────────────────────────────────
+     A translucent surface leans on its hairline to define its edge, and an
+     8%-alpha hairline is the first thing to disappear under a contrast
+     preference. Promote it to primary text colour.
+
+     Note what is NOT changed: the surface itself. High contrast is about
+     edges and text, not about removing the material. Composes correctly with
+     reduced-transparency if the user has both — solid surface, strong
+     border. */
+  @media (prefers-contrast: more) {
+    .glass-nav,
+    .glass-panel,
+    .folder-glass {
+      border-color: var(--color-gray-1000);
+    }
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   REFERENCE — glass is only half of it. A blurred, tinted rectangle is a
+   PATCH. Three non-transparency cues turn it into an object, and every glass
+   surface needs all three. See glass/depth/depth-cues.md.
+
+   1 · A HAIRLINE, from the TRANSLUCENT ramp:
+
+         border-[0.5px] border-gray-alpha-400
+
+       Not solid grey — a solid border doesn't participate in what's behind
+       it, so over a photograph it reads as a pasted-on frame. And because
+       the alpha ramp inverts to white-based in dark mode, the border is
+       automatically lighter than its surface there and darker here.
+
+       0.5px renders as a true sub-pixel hairline on retina and rounds UP to
+       1px elsewhere — it degrades rather than disappears.
+
+   2 · A LAYERED SHADOW. Four layers, one light source above:
+
+         inset 0 1px 0 rgba(255,255,255,0.6)   top-edge catch light
+         0 1px 1px rgba(0,0,0,0.02)            contact
+         0 8px 16px -4px rgba(0,0,0,0.04)      near ambient
+         0 24px 32px -8px rgba(0,0,0,0.06)     far ambient
+
+       The inset highlight contributes more than any of the shadows and is
+       the one most often omitted — remove it and the surface looks printed
+       on rather than raised. Negative spread contracts before blurring, so
+       the shadow stays tucked under instead of haloing out. Opacities are
+       2–6%: if you can identify the shadow as a shadow, it's too strong.
+
+       Dark mode is a DIFFERENT shadow, not a re-tint — shadows ~10x stronger
+       (4% black on #0b0b0b is mathematically invisible), inset highlight ~6x
+       weaker (0.6 white on dark reads as a glowing edge). Because the
+       structure changes, this can't be one token — it's a per-theme pair,
+       and it belongs in the .dock-shadow class at the foot of this file
+       rather than repeated inline at every use.
+
+   3 · CONTINUOUS CORNERS:
+
+         *, *::before, *::after { corner-shape: superellipse(1.5); }
+
+       And nest radii by: INNER = OUTER − the padding between them.
+         Dock rounded-2xl (16) p-1 (4) → button rounded-[12px] → avatar 10px
+
+   ── Performance, briefly ──────────────────────────────────────────────
+   Cost scales with AREA and re-runs whenever anything behind it changes —
+   including every frame of every scroll. Keep surfaces small, keep them few,
+   UNMOUNT closed menus (a hidden backdrop-filter element still pays its
+   filter pass; opacity: 0 does not save you), never animate blur(), and
+   never put glass over video or a flat background.
+   ───────────────────────────────────────────────────────────────────────── */
+
+/* ─────────────────────────────────────────────────────────────────────────
+   The elevation stack, as a class.
+
+   Every floating surface takes this alongside its material class:
+
+     <div class="glass-nav dock-shadow rounded-2xl border-[0.5px] …">
+
+   It is NOT a design token, because it isn't a colour — no token system
+   takes a four-layer box-shadow (see §6 of the Glass colour guide (`glass/color/guide.md`)).
+   And it can't be one value, because dark mode changes the structure and
+   not just the numbers. A class is the only place it can live, and putting
+   it in one is what stops a ~400-character string being copied into five
+   components with a dark twin each.
+   ───────────────────────────────────────────────────────────────────────── */
+
+@layer components {
+  .dock-shadow {
+    box-shadow:
+      inset 0 1px 0 rgba(255, 255, 255, 0.6), /* top-edge catch light */
+      0 1px 1px rgba(0, 0, 0, 0.02),          /* contact                */
+      0 8px 16px -4px rgba(0, 0, 0, 0.04),    /* near ambient           */
+      0 24px 32px -8px rgba(0, 0, 0, 0.06);   /* far ambient            */
+  }
+
+  /* Shadows ~10x stronger; the inset highlight ~6x weaker. */
+  :root[data-theme="dark"] .dock-shadow {
+    box-shadow:
+      inset 0 1px 0 rgba(255, 255, 255, 0.1),
+      0 1px 1px rgba(0, 0, 0, 0.3),
+      0 8px 16px -4px rgba(0, 0, 0, 0.5),
+      0 24px 32px -8px rgba(0, 0, 0, 0.6);
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   A gradient 1px stroke — no wrapper element, no mask.
+
+   Two background layers on one box: the fill clipped to the padding edge,
+   the gradient clipped to the border edge, with a transparent border to
+   show it through.
+
+   background-origin: border-box IS THE LOAD-BEARING LINE. Without it the
+   gradient is SIZED to the padding box while being clipped to the border
+   box, so the stroke gets the wrong end of the ramp on all four sides — a
+   one-word omission that produces a result which looks almost right.
+
+   AND THE STOPS ARE IN PIXELS, NOT PERCENTAGES. Percentages are relative to
+   the box, so the ramp rescales whenever the box resizes: a 46px closed bar
+   ran the entire sweep inside its own height, came out louder than the
+   250px panel it opened into, and shimmered through the open animation as
+   the ramp re-fitted frame by frame. Anchored in pixels the top of the
+   stroke holds still and the colour simply grows downward.
+
+   Colours come from the Glass colour guide's --sv-* family, which is
+   that system's one chromatic exception. Delete this block if you don't
+   have such an element.
+   ───────────────────────────────────────────────────────────────────────── */
+
+@layer components {
+  .sv-panel {
+    border: 1px solid transparent;
+    background-image:
+      linear-gradient(var(--sv-fill-top), var(--sv-fill-bottom)),
+      linear-gradient(
+        180deg,
+        var(--sv-edge-top) 0px,
+        var(--sv-edge-mid) 120px,
+        var(--sv-edge-bottom) 240px
+      );
+    background-origin: border-box;
+    background-clip: padding-box, border-box;
+
+    /* Four shadows, not one. A single centred blur reads as a drop shadow
+       that happens to be blue; the two HORIZONTAL casts are what make it
+       read as light coming off the panel. Same negative spread as the
+       elevation stack, so the glow stays tucked rather than haloing. */
+    box-shadow: var(--sv-glow);
+    transition: box-shadow 220ms var(--ease-geist);
+  }
+
+  /* Lifts on hover and STAYS lifted while open, so the colour reports the
+     same state the chevron does. */
+  .sv-panel:hover,
+  .sv-panel[data-open="true"] {
+    box-shadow: var(--sv-glow-lift);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .sv-panel {
+      transition: none;
+    }
+  }
+
+  /* One pass of light across the label as it opens — never a loop. A
+     repeating shimmer claims the thing is still working, which it isn't.
+     Drop the class on animationend so the label goes back to painted text:
+     background-clip: text with color: transparent is a text-selection and
+     forced-colours hazard to leave in place. */
+  .sv-sheen {
+    background-image: linear-gradient(
+      100deg,
+      var(--sv-accent) 40%,
+      var(--sv-sheen-hi) 50%,
+      var(--sv-accent) 60%
+    );
+    background-size: 250% 100%;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent;
+    animation: svSheen 700ms var(--ease-geist) both;
+  }
+  @keyframes svSheen {
+    from {
+      background-position: 140% 0;
+    }
+    to {
+      background-position: -40% 0;
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .sv-sheen {
+      animation: none;
+      background-image: none;
+      color: var(--sv-accent);
+    }
+  }
+}

package/plugins/keyline/skills/keyline/glass/depth/blur-and-tint.md

@@ -0,0 +1,50 @@
+# Blur, saturation, and tint
+
+Glass's values for depth laws 7–10; why blur greys, what the tint does and how to composite text are in `domains/depth/translucent-materials.md`.
+
+## Saturation
+
+| Saturate | When |
+|---|---|
+| 1.4 | Only *softening* a backdrop you want recognised |
+| 1.8 | *Suppressing* a backdrop (the default) |
+| >2.0 | Almost never — colours look radioactive |
+| 1.0 | Never; this is just omitting it |
+
+The reference implementation uses 1.4 on the folder pocket, deliberately: the cards behind it are the subject, and pushing their saturation would make the pocket louder than its contents. The three chrome surfaces use 1.8. Roughly, the more you blur, the more saturation you need: 8px / 1.4 and 20px / 1.8 both come out "colour preserved".
+
+## The tint values
+
+```css
+:root {
+  --glass-nav-bg:    rgba(242, 242, 242, 0.72);
+  --glass-panel-bg:  rgba(243, 243, 243, 0.97);
+  --folder-glass-bg: linear-gradient(to bottom, rgba(255,255,255,0.55), rgba(255,255,255,0.34));
+}
+
+:root[data-theme="dark"] {
+  --glass-nav-bg:    rgba(26, 26, 26, 0.72);
+  --glass-panel-bg:  rgba(22, 22, 22, 0.97);
+  --folder-glass-bg: linear-gradient(to bottom, rgba(48,48,48,0.5), rgba(30,30,30,0.34));
+}
+```
+
+The three tint rules in `domains/depth/translucent-materials.md`, at these values:
+
+- **The nav tint is `#f2f2f2`, not white**, matching `gray-100`, the "raised surface" token.
+- **The dark tints are lighter than the dark page**: `#1a1a1a` and `#161616` against `#0b0b0b`.
+- **The pocket is a gradient**, brighter at the top, and **its dark gradient is grey-based**, not white-based. Its inset highlight is also brighter than the chrome's (`rgba(255,255,255,0.8)` vs `0.6`): a bigger, more decorative surface gets more pronounced light modelling.
+
+They live in `:root`, not `@theme`, because the reduced-transparency fallback replaces them and one is a gradient (colour law 10; `glass/color/guide.md`).
+
+## The 97% panel, in full
+
+The stated reason in the reference implementation:
+
+> Its own animating transform weakens `backdrop-filter`, so the tint carries the opacity rather than the blur.
+
+Two more reasons. **The settings box opens directly above the nav dock**, glass over glass: at 72% each it would look like the dock had grown taller, so the heavy tint buys tier separation as well as legibility (depth law 11). And at 97% the backdrop contributes ~3%, so you can *compute* text contrast against the tint, which you cannot at 72%.
+
+## Text over glass, worked
+
+A 72% `#f2f2f2` tint composites to about `#f5f5f5` over a white page and around `#b8b8b8` over a dark photograph. Text at `gray-800` (`#7d7d7d`) clears AA on the first and fails on the second, and the same pixel does both as the page scrolls — hence §7 of the guide. The reduced-transparency fallback helps as a side effect, swapping in a solid token so contrast is real for the users most likely to need it.

package/plugins/keyline/skills/keyline/glass/depth/depth-cues.md

@@ -0,0 +1,87 @@
+# Depth cues
+
+Glass's edges, shadows and tiers, for depth laws 1–5; the bundle and the shadow derivation in general are in `domains/depth/elevation-recipes.md`. Corners and the nesting rule are layout's: `glass/layout/radius-and-elevation.md`.
+
+## 1. The hairline
+
+Every glass surface here pairs blur with a border:
+
+```tsx
+className="glass-nav rounded-2xl border-[0.5px] border-gray-alpha-400 p-1"
+```
+
+**Why the alpha ramp.** Because it inverts to white-based in dark mode (the Glass colour guide, `glass/color/guide.md`), the border is automatically lighter than its surface in dark mode and darker in light — "one step more contrast than the surface" in both directions.
+
+**Why 0.5px.** On a small floating dock, 1px reads as heavy; 0.5px reads as an edge.
+
+**The exception.** The decorative folder pocket uses a solid `border-white/60` with `dark:border-white/[0.08]`. A literal white works because it's a *decorative* material over content it controls, and the bright edge is part of the effect. The dark value drops to `0.08` from `0.6` because on a dark surface a bright edge reads as a glowing line, not a catch light.
+
+Vertical dividers inside the dock are layout's (`glass/layout/radius-and-elevation.md`).
+
+## 2. The shadow stack
+
+`.dock-shadow` is in §5 of the guide; depth law 4 gives each layer's job. In dark mode:
+
+```
+inset 0 1px 0 rgba(255,255,255,0.10),     /* highlight:  0.6  → 0.10 */
+0 1px 1px rgba(0,0,0,0.3),                /* shadows:    0.02 → 0.3  */
+0 8px 16px -4px rgba(0,0,0,0.5),          /*             0.04 → 0.5  */
+0 24px 32px -8px rgba(0,0,0,0.6)          /*             0.06 → 0.6  */
+```
+
+A 4%-black shadow on a `#0b0b0b` surface is invisible; dark mode needs 30–60% black before a shadow registers. It's also why the dark page is `#0b0b0b`, not `#000000` (depth law 5).
+
+Because the structure changes and not just the values, elevation **cannot be a single token**. It needs a per-theme pair — the one place raw `rgba()` outside the token file is acceptable — and it belongs in a **CSS class**, not a JS constant:
+
+```tsx
+<div className="glass-nav dock-shadow rounded-2xl border-[0.5px] border-gray-alpha-400 p-1">
+```
+
+The reference implementation started with an exported constant and moved to the class:
+
+- **It's ~400 characters of arbitrary-value syntax either way**, but in a class it's four readable lines you can compare against the four in the dark block.
+- **A shared constant is still imported and interpolated at every site**, so a `grep` for the shadow finds five hits rather than one definition.
+- **The escaping is a hazard** (`domains/depth/elevation-recipes.md`, one definition per level).
+
+## 3. Elevation tiers
+
+**More layers as the element floats higher and persists longer** (depth law 4).
+
+| Tier | Recipe | Radius | For |
+|---|---|---|---|
+| **Chrome** | 4 layers (inset + contact + 2 ambient) | 16px | Fixed docks, floating menus, sheets |
+| **Pocket** | `inset 0 1px 0 rgba(255,255,255,0.8)` + `0 10px 28px -12px rgba(0,0,0,0.22)` | 16px | A large decorative material |
+| **Panel** | `0 8px 24px -8px rgba(0,0,0,0.12)` / dark `0.6` | 12px | Hover cards |
+| **Card** | `0 4px 12px -4px rgba(0,0,0,0.22)` + `ring-1 ring-black/[0.06]` / dark `ring-white/[0.08]` | 9px | Cards in a stack |
+| **Transient** | `0 4px 10px -4px rgba(0,0,0,0.3)` | 6px | Tooltips |
+
+**A tooltip's shadow is 30% black in *both* themes.** It sits on `bg-gray-1000`, near-black in light mode and near-white in dark, so the surface sets its requirement (depth law 4).
+
+**The stacked card uses a `ring`, not a `border`.** A ring doesn't affect layout, so it can't shift a card positioned by transform mid-animation. `ring-black/[0.06] dark:ring-white/[0.08]` carries the alpha ramp's information in a utility that doesn't take a token.
+
+### A confirmation takes an existing tier
+
+A destructive confirmation takes the panel the rest of the system floats (depth law 1), in the pattern patterns law 4 sets out. Its focus returns to the opener, held on open:
+
+```tsx
+const opener = useRef<HTMLElement | null>(null);
+const open = () => { opener.current = document.activeElement as HTMLElement; setOpen(true); };
+const close = () => { setOpen(false); requestAnimationFrame(() => opener.current?.focus()); };
+```
+
+## 4. Stacking inside a glass surface
+
+A sliding highlight must sit **behind** the icons but **in front of** the surface's own tint:
+
+```tsx
+<ul className="glass-nav relative isolate flex items-center …">
+  <m.div className="pointer-events-none absolute left-0 top-0 -z-10 rounded-[12px] bg-highlight" />
+  {/* icons, in normal flow, above the bar */}
+</ul>
+```
+
+`-z-10` alone would drop the bar behind the container, tint included; `isolate` scopes it, so the bar goes behind the icons but not behind the glass (layout law 7).
+
+`bg-highlight` is a token, white in light mode and `#2c2c2c` in dark: an elevated surface within an elevated surface, lighter than the glass in light mode and lighter again in dark, so it can't be a fixed colour.
+
+The enclosing fixed strip carries **no transform**: it would weaken the `backdrop-filter` in its subtree *and* trap the mobile sheet's full-bleed overlay (depth law 9).

package/plugins/keyline/skills/keyline/glass/depth/guide.md

@@ -0,0 +1,216 @@
+# Glass and Depth
+
+> **Glass preset.** This is the glass material running on [modimihir.com](https://modimihir.com), with its real values, meant to be copied whole. Read it beside `domains/depth/guide.md`, which holds the laws; this guide holds glass's values, recipes and decisions for them, and says where glass differs. Under any other preset, `domains/depth/guide.md` leads and this guide is only a worked example.
+
+Glass is the preset built around translucency, so it spends depth law 6's ceiling: the material in four places, all floating chrome — the nav dock, the settings drop-up, the mobile sheet and one decorative pocket. Everything else is opaque. The material is the five parts in `domains/depth/translucent-materials.md` plus continuous corners (`glass/layout/guide.md`, §4).
+
+## 1. Three tiers
+
+Depth law 7, at glass's values:
+
+| Tier | Blur | Saturate | Tint | Backdrop | Used for |
+|---|---|---|---|---|---|
+| `folder-glass` | **8px** | 1.4 | gradient, 55%→34% | Content you *want* recognised | A frosted pocket, cards peeking behind |
+| `glass-nav` | **20px** | 1.8 | 72% | Arbitrary page content | Fixed chrome that content scrolls under |
+| `glass-panel` | **24px** | 1.8 | **97%** | Anything, including other glass | A floating menu that must stay legible |
+
+The pocket's cards should stay recognisable: 8px softens rather than obscures, and 1.4 saturation keeps the pocket quieter than its contents. Paragraphs, photographs and image walls scroll under fixed chrome; 20px leaves less to compete with its icons. The panel, least in control of its backdrop, gets the most defensive 24px.
+
+> **A finding from the reference implementation:** a fourth material, `glass-menu` (16px / 1.8 / 72%), for "a menu over a surface you already know", is dead CSS: every menu needed `glass-panel`'s defensive tint, because its wrapper animates or it opens over other glass. Copy three tiers (depth law 1).
+
+## 2. Saturation: 1.8 suppressing, 1.4 softening
+
+Depth law 8:
+
+```css
+backdrop-filter: blur(20px) saturate(1.8);
+```
+
+**1.8 where you're suppressing the backdrop, 1.4 where you're only softening it.**
+
+## 3. The 97% panel
+
+`glass-panel` pairs a 24px blur with **97% opacity** because its menus' wrappers *scale open*, and a transform on an ancestor weakens `backdrop-filter` beneath it (depth law 9): for the whole animation the tint does the work. Where you can, the animating wrapper and the glass surface are different elements:
+
+```tsx
+<DropMenu open={open}>            {/* animates scale + y */}
+  <ul className="glass-panel …">  {/* carries the blur, never transformed */}
+```
+
+## 4. Glass over glass
+
+Depth law 11, on the site: the settings box (`glass-panel`) opens right above the dock (`glass-nav`). At 72% the drop-up would look like the dock growing taller; at 97% it's a separate panel.
+
+## 5. Edge and shadow
+
+### The hairline
+
+```tsx
+className="glass-nav rounded-2xl border-[0.5px] border-gray-alpha-400 p-1"
+```
+
+Depth law 3's translucent edge is the alpha ramp (`glass/color/guide.md`): `gray-alpha-400` sits *on* whatever's there, white page or photograph, where a solid `gray-400` reads as a pasted-on frame.
+
+### The shadow stack
+
+Four layers, one light source above (depth law 4), in **one class**, not inline:
+
+```css
+.dock-shadow {
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.6),   /* top-edge catch light */
+    0 1px 1px rgba(0, 0, 0, 0.02),            /* contact */
+    0 8px 16px -4px rgba(0, 0, 0, 0.04),      /* near ambient */
+    0 24px 32px -8px rgba(0, 0, 0, 0.06);     /* far ambient */
+}
+:root[data-theme="dark"] .dock-shadow {
+  box-shadow:
+    inset 0 1px 0 rgba(255, 255, 255, 0.1),
+    0 1px 1px rgba(0, 0, 0, 0.3),
+    0 8px 16px -4px rgba(0, 0, 0, 0.5),
+    0 24px 32px -8px rgba(0, 0, 0, 0.6);
+}
+```
+
+Opacities are 2–6% in light. Dark is a different shadow, not a re-tint (depth law 5): shadows ~10× stronger (4% black on `#0b0b0b` is invisible), highlight ~6× weaker (0.6 white on dark is a glowing edge, not a catch light).
+
+**Extracted the moment it appeared twice.** This ~400-character string was once inline in five places here, each with a dark twin. Not being a colour, it *can't* be a design token (colour law 10), so a class is its only home.
+
+→ Every elevation tier, the pocket's edge, and stacking inside a glass surface: `glass/depth/depth-cues.md`
+
+## 6. A gradient edge, without a wrapper or a mask
+
+Depth law 13, on the one chromatic panel, whose edge runs deep navy to pale blue:
+
+```css
+.sv-panel {
+  border: 1px solid transparent;
+  background-image:
+    linear-gradient(var(--sv-fill-top), var(--sv-fill-bottom)),      /* the fill */
+    linear-gradient(180deg,                                          /* the stroke */
+      var(--sv-edge-top) 0px,
+      var(--sv-edge-mid) 120px,
+      var(--sv-edge-bottom) 240px);
+  background-origin: border-box;
+  background-clip: padding-box, border-box;
+}
+```
+
+**The stops are in pixels** because the panel opens from a 46px bar to 250px. With percentages it ran the whole navy-to-pale sweep inside 46px, *louder* than the panel it became, and shimmered as the ramp re-fitted each frame; at `0px / 120px / 240px` the top holds still and the colour grows downward.
+
+### The glow
+
+Depth law 14:
+
+```css
+box-shadow:
+  0 1px 2px rgba(22, 39, 107, 0.05),          /* contact */
+  -10px 0 20px -18px rgba(47, 90, 196, 0.38), /* left */
+  10px 0 20px -18px rgba(47, 90, 196, 0.38),  /* right */
+  0 10px 24px -16px rgba(47, 90, 196, 0.3);   /* below */
+```
+
+It lifts on hover **and stays lifted while open** (`.sv-panel:hover, .sv-panel[data-open="true"]`), so the colour reports the chevron's state. Transition at 220ms, off under `prefers-reduced-motion`.
+
+### The sheen
+
+A label shimmers once as the panel opens:
+
+```css
+.sv-sheen {
+  background-image: linear-gradient(100deg,
+    var(--sv-accent) 40%, var(--sv-sheen-hi) 50%, var(--sv-accent) 60%);
+  background-size: 250% 100%;
+  background-clip: text;
+  color: transparent;
+  animation: svSheen 700ms var(--ease-geist) both;
+}
+```
+
+The class drops on `animationend`; under reduced motion, plain accent colour.
+
+## 7. Text over glass
+
+**Contrast on a translucent surface can't be computed**: the effective background is whatever is behind it. Glass's answers to depth law 10, in order:
+
+1. **Raise the tint until it's effectively opaque behind text.** Hence `glass-panel` at 97%, where contrast against the tint *is* computable.
+2. **Only high-contrast text on glass:** icons at `quiet`→`gray-1000` (not `gray-600`, 2.38:1 on white) and 13–14px rows at `gray-900`/`gray-1000`. Nothing muted, nothing small.
+3. **No reading copy on glass.** No paragraph on the site sits on a translucent surface.
+
+→ The tint values and a worked composite: `glass/depth/blur-and-tint.md`
+
+## 8. Fallbacks
+
+Depth law 15, at glass's tokens.
+
+### `prefers-reduced-transparency`
+
+```css
+/* AFTER both theme blocks — it re-declares the same properties. */
+@media (prefers-reduced-transparency: reduce) {
+  :root, :root[data-theme="dark"] {
+    --glass-nav-bg: var(--color-gray-100);
+    --glass-panel-bg: var(--color-gray-100);
+    --folder-glass-bg: var(--color-background-100);
+  }
+  .glass-nav, .glass-panel, .folder-glass {
+    backdrop-filter: none;
+  }
+}
+```
+
+### `prefers-contrast: more`
+
+```css
+@media (prefers-contrast: more) {
+  .glass-nav, .glass-panel, .folder-glass { border-color: var(--color-gray-1000); }
+}
+```
+
+### `@supports` — the gap in the reference implementation
+
+The reference implementation has **no `@supports` guard**, so without `backdrop-filter` it gets a bare 72% tint: legible, but weak. `glass/depth/assets/glass.css` ships with the guard:
+
+```css
+.glass-nav { background: var(--color-gray-100); }   /* opaque baseline */
+
+@supports (backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px)) {
+  .glass-nav {
+    background: var(--glass-nav-bg);
+    backdrop-filter: blur(20px) saturate(1.8);
+  }
+}
+```
+
+**Don't hand-write `-webkit-backdrop-filter`.** Tailwind v4's Lightning CSS adds it and keeps only the last of a hand-written pair, so the site ships the prefix alone and Firefox loses every blur (`glass/depth/performance-and-fallbacks.md`).
+
+## 9. Performance
+
+Depth law 16, within glass's budget: three or four surfaces at most, each small — a dock a few hundred pixels wide, not a full-viewport overlay — and closed menus unmount.
+
+→ What keeps it affordable here, and the prefix bug in detail: `glass/depth/performance-and-fallbacks.md`
+
+## 10. Confirmations
+
+A destructive confirmation takes `glass-panel` with the same hairline and shadow as every other floating panel (depth law 1; patterns law 4). The action carries the red (`glass/color/guide.md`). → The focus-return code: `glass/depth/depth-cues.md`
+
+## Assets
+
+- `glass/depth/assets/glass.css` — the three materials, all fallbacks, the missing `@supports` guard, `.dock-shadow`, the gradient-stroke panel. Pairs with `glass/color/assets/color-tokens.css` (tints, `--sv-*` stops).
+- `glass/depth/assets/GlassPanel.tsx` — wrapper/surface split, hairline and stacking, as a component.
+
+## Checklist
+
+The domain checklist applies in full; these are glass's values for it.
+
+- [ ] Three tiers only: `folder-glass` 8px / 1.4, `glass-nav` 20px / 1.8 / 72%, `glass-panel` 24px / 1.8 / 97%.
+- [ ] Glass in the four places only: dock, settings drop-up, mobile sheet, pocket.
+- [ ] Anything that animates or opens over glass is `glass-panel`, its wrapper apart from the surface.
+- [ ] Edges `border-[0.5px] border-gray-alpha-400`; the pocket alone takes `border-white/60`.
+- [ ] `.dock-shadow` as one class with its dark twin beside it.
+- [ ] Gradient strokes stopped at `0px / 120px / 240px`; the glow holds while open; the sheen runs once.
+- [ ] Icons at `quiet`→`gray-1000` and rows at `gray-900`/`gray-1000` on glass; no reading copy.
+- [ ] Reduced transparency swaps the tints to `gray-100` / `background-100` and drops the filter, after both theme blocks.
+- [ ] `prefers-contrast: more` turns the edge `gray-1000`.
+- [ ] `@supports` guard with the `gray-100` baseline; source has only `backdrop-filter`, compiled CSS both.
+- [ ] Destructive confirmations take `glass-panel`; focus returns to the opener.