trykeyline 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,195 @@
+# Glass Colour
+
+> **Glass preset.** This is the colour system running on [modimihir.com](https://modimihir.com), with its real values, meant to be copied whole. Read it beside `domains/color/guide.md`: the laws and their reasons are there, and this guide holds only what Glass decides — its ramps, its tokens, its recipes and why it chose them. Under any other preset, the domain guide leads and this guide is only a worked example.
+
+Monochrome, built on [Geist](https://vercel.com/geist)'s grayscale semantics under Apple-style translucent materials. Each step of the grey ramp is a job, not a lightness (domain law 1): `gray-400` is *the colour a border is*, and dark mode re-tints the same indices.
+
+## 1. The intent-indexed ramp
+
+| Step | Intent | Light | Dark |
+|---|---|---|---|
+| 100 | Raised element's surface | `#f2f2f2` | `#1a1a1a` |
+| 200 | Surface, hovered | `#ebebeb` | `#212121` |
+| 300 | Surface, active/pressed | `#e6e6e6` | `#282828` |
+| 400 | **Border** | `#eaeaea` | `#2e2e2e` |
+| 500 | Border, hovered — and decorative marks | `#c9c9c9` | `#707070` |
+| 600 | Border, active | `#a8a8a8` | `#7d7d7d` |
+| 700 | Solid fill (button, marker) | `#8f8f8f` | `#8f8f8f` |
+| 800 | Solid fill, hovered | `#7d7d7d` | `#a0a0a0` |
+| 900 | **Secondary text** | `#4d4d4d` | `#c4c4c4` |
+| 1000 | **Primary text** | `#171717` | `#ededed` |
+
+Two surfaces sit apart; a page background is not a component surface:
+
+| Token | Intent | Light | Dark |
+|---|---|---|---|
+| `background-100` | Page / card surface | `#ffffff` | `#0b0b0b` |
+| `background-200` | Subtle secondary surface | `#fafafa` | `#161616` |
+
+**400 is lighter than 300 in the light theme** (`#eaeaea` vs `#e6e6e6`): intent wins over monotonicity (domain law 1).
+
+**Steps 500–800 are borders and fills, never text** (§4).
+
+→ Each step and its misuse: `glass/color/intent-ramp.md`
+
+## 2. The parallel translucent ramp
+
+Glass's translucent set (domain law 4), for borders on glass, dividers, hairlines and overlays:
+
+```css
+--color-gray-alpha-100: #0000000d;   /*  5% */
+--color-gray-alpha-200: #00000015;   /*  8% */
+--color-gray-alpha-300: #0000001a;   /* 10% */
+--color-gray-alpha-400: #00000014;   /*  8% */
+--color-gray-alpha-500: #00000036;   /* 21% */
+--color-gray-alpha-600: #0000003d;   /* 24% */
+```
+
+In dark mode it inverts to **white**-based:
+
+```css
+:root[data-theme="dark"] {
+  --color-gray-alpha-100: #ffffff0d;
+  --color-gray-alpha-400: #ffffff17;
+  /* … */
+}
+```
+
+**Solid ramp for opaque surfaces, alpha ramp for anything layered:** a solid `gray-400` border on a translucent panel ignores what's behind it; `gray-alpha-400` sits *on* it, white page or photograph.
+
+## 3. One accent for focus — and at most one deliberate exception
+
+```css
+--color-blue-700: #006bff;   /* light */
+--color-blue-700: #3b82f6;   /* dark */
+```
+
+One accent, for the focus ring only, the editorial setting of the accent dial. Links stay monochrome; blue ones read as unstyled defaults and dull a blue ring.
+
+```css
+:focus-visible {
+  outline: 2px solid var(--color-blue-700);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+a:focus-visible { outline-offset: 3px; }
+```
+
+Why `:focus-visible`, the offset and the wider link offset: domain law 5. The dark value is brighter (`#3b82f6` vs `#006bff`), re-picked rather than reused (domain law 8).
+
+### The second exception, if you allow one
+
+Glass spends its one exception on a collapsed "short version" panel atop a long case study: **the panel is an offer rather than content** ("do you want the three-line version?"), and nothing else on the site is an offer, so the reason can't spread (domain law 7).
+
+```css
+:root {
+  --sv-edge-top: #16276b;      /* navy, top of the stroke */
+  --sv-edge-mid: #2f5ac4;
+  --sv-edge-bottom: #6d97ea;   /* lighter blue, bottom */
+  --sv-fill-top: #f4f6fc;
+  --sv-fill-bottom: #eef2fa;
+  --sv-accent: #2f5ac4;        /* the mark only */
+}
+```
+
+Only the mark takes `--sv-accent`; the text stays in the page's ink (domain law 7). In dark mode every stop moves (domain law 8):
+
+```css
+:root[data-theme="dark"] {
+  --sv-edge-top: #24407f;   /* was #16276b */
+  --sv-edge-mid: #3f6ed0;
+  --sv-edge-bottom: #86adf7;
+  --sv-fill-top: #171d2a;   /* tinted, not darkened */
+  --sv-fill-bottom: #1b2230;
+  --sv-accent: #86adf7;
+}
+```
+
+A `#16276b` stop on a `#0b0b0b` page loses the stroke's darker half, so the whole ramp lifts, not just that end. The fill is *tinted* to `gray-100`'s weight, not darkened, so it doesn't punch a hole in the page (the glass-tint rule, §6). The material — a 1px gradient stroke, a side-weighted glow, no wrapper — belongs to `glass/depth/guide.md`.
+
+### Status colour is not an exception
+
+Nothing on the site reports state, so Glass ships no status pair; if you add one, it follows domain law 6 and `domains/color/status-and-exceptions.md` (`glass/color/intent-ramp.md` has Glass's notes). Every destructive or session-ending action (delete, clear, sign out) shares one red treatment, wherever it sits.
+
+## 4. Text is a five-tier ladder — and it is *not* the grey ramp
+
+The lower three tiers are **their own tokens**, set by contrast (domain laws 2 and 3):
+
+| Tier | Token | Light | Dark | Job |
+|---|---|---|---|---|
+| Primary | `gray-1000` | 17.93:1 | 16.81:1 | Body copy, headings, active state |
+| Secondary | `gray-900` | 8.45:1 | 11.28:1 | Emphasis short of primary, ancestor rows |
+| Muted | `muted` `#5e5e5e` / `#a0a0a0` | 6.48:1 | 7.53:1 | Deks, supporting copy, `<em>` |
+| Quiet | `quiet` `#696969` / `#878787` | 5.49:1 | 5.48:1 | Resting icons, state labels, `<cite>` |
+| Faint | `faint` `#757575` / `#7a7a7a` | 4.61:1 | 4.59:1 | Dates, read times, meta |
+
+In a light theme only 900 and 1000 of the grey ramp read as text; the site shipped mid steps as text until an audit caught it (the failure table and fix: `glass/color/intent-ramp.md`).
+
+**Icons go on `quiet`, not a tier of their own.** They need only 3:1, but usually sit beside a label at the same colour, and two tokens kept matched is more coupling than it saves. An icon rests a tier *below* its label (domain law 2); both go to primary on hover.
+
+**Decorative marks stay on the grey ramp**: `bg-gray-500` for a bullet, a 3px dot or an inactive rail marker (domain law 2's `mark`).
+
+**`<em>` maps to *muted*.** Italics are off globally (`glass/type/guide.md`), so `*em*` recedes to `muted` and `**strong**` advances to `gray-1000` + weight 500.
+
+## 5. Theming: one attribute, one set of tokens
+
+`data-theme` on `<html>` drives dark mode, not `prefers-color-scheme`, so a toggle can override the OS (domain law 9):
+
+```css
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+```
+
+The dark theme is one block re-tinting the same names:
+
+```css
+:root[data-theme="dark"] {
+  color-scheme: dark;
+  --color-gray-100: #1a1a1a;      /* low steps become dark surfaces */
+  --color-gray-1000: #ededed;     /* high steps become light text */
+  --color-gray-alpha-100: #ffffff0d;
+  --color-background-100: #0b0b0b;
+  /* … */
+}
+```
+
+Utilities read the variables, so most of the site needs **no per-component `dark:` classes**. Dark surfaces are `#0b0b0b`, not `#000000` (domain law 8).
+
+### No flash of wrong theme
+
+A blocking `<head>` script sets the attribute before paint (domain law 9): `glass/color/assets/theme.ts`. → Two states, Light by default, and the toggle's 400ms plain-`ease` crossfade: `glass/color/theming.md`
+
+## 6. Some colours are runtime, not build-time
+
+The ramps and surfaces are vocabulary, in `@theme`; the **glass tints** are plain `:root` properties (domain law 10):
+
+```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));
+}
+```
+
+Runtime because the reduced-transparency fallback swaps them, after both theme blocks (`glass/depth/guide.md` §8), and one isn't a colour at all; the `--sv-*` gradients sit in `:root` too.
+
+The nav tint is `#f2f2f2` (`gray-100`), not white: grey chrome reads as an object, not a hole in the page. Dark tints are *lighter* than the dark page (domain law 8).
+
+## Assets
+
+- `glass/color/assets/color-tokens.css` — ramps, themes, glass tints and their fallback swap, focus ring; pairs with `glass/depth/assets/glass.css` (material classes).
+- `glass/color/assets/theme.ts` — persistence, toggle crossfade, no-flash head script.
+
+## Checklist
+
+The domain checklist, plus Glass's values:
+
+- [ ] Steps used for their intent: borders at 400, surfaces at 100–300, the page on `background-100`.
+- [ ] **No step from 500 to 800 as text**; text is `gray-900`/`gray-1000` or muted/quiet/faint.
+- [ ] Resting icons on `quiet`; decorative marks on `gray-500`.
+- [ ] `gray-alpha-*` for anything layered, white-based in dark.
+- [ ] `blue-700` for focus only, `#006bff` light and `#3b82f6` dark; links monochrome.
+- [ ] At most the one `--sv-*` exception, every stop re-picked for dark.
+- [ ] `data-theme` on `<html>`, set by the head script; dark page `#0b0b0b`.
+- [ ] Glass tints and `--sv-*` in `:root`, not `@theme`; the reduced-transparency swap last.
+- [ ] Contrast checked in both themes; muted text on a subtle surface is what fails.
+- [ ] Glass surfaces audited against the `glass/depth/guide.md` checklist.

package/plugins/keyline/skills/keyline/glass/color/intent-ramp.md

@@ -0,0 +1,136 @@
+# The intent-indexed ramp
+
+Each Glass step, what it's for and how it was misused. Why a ramp indexed by job beats one indexed by lightness: domain law 1 in `domains/color/guide.md`.
+
+## The steps
+
+### 100 · 200 · 300 — surface and its states
+
+A raised element's background, hover and pressed state: three states, one step apart, so the progression stays even.
+
+- **100** is also a general subtle surface — an image wall's backdrop, a cover placeholder, a hover bar in a list.
+- **200** also fills a small static thing that should read as an inert placeholder (faux body lines in a preview card).
+- **300** also fills a small structural mark, such as a preview card's title bar.
+
+### 400 — border
+
+The default border, one of the two most-used steps.
+
+**In light mode, 400 (`#eaeaea`) is lighter than 300 (`#e6e6e6`)** (domain law 1). The two are never adjacent in practice, so nothing looks wrong.
+
+On anything translucent, use `gray-alpha-400` instead (§2 of `glass/color/guide.md`).
+
+### 500 · 600 — border states (and where icons used to go)
+
+500 is a hovered border, 600 an active one.
+
+**600 used to be the resting colour of an icon, and that was a bug.** An icon should rest a tier below the label beside it, so `hover:text-gray-1000` gives both the same perceived jump — but 600 is 2.38:1 on white in the light theme, under even the 3:1 non-text floor (table below). Icons now rest on `quiet`, keeping the one-tier-below relationship on a token picked for contrast; see §4 of `glass/color/guide.md`.
+
+500 was where the reference implementation put its **faint text** tier — timestamps, dates, read times. `#c9c9c9` on white is 1.66:1: illegible, below even the 3:1 non-text floor. Text tiers are now separate tokens (below).
+
+500 keeps its border-hover intent and its use as the fill for *decorative* marks (list bullets, a 3px dot, an inactive rail marker).
+
+### 700 · 800 — solid fill
+
+A filled element that isn't the primary action: a small marker, a filled chip.
+
+The reference implementation also used **800 as its muted text tier** — deks, secondary paragraphs, `<em>`, supporting copy. `#7d7d7d` on white is **4.12:1**, which **fails** WCAG AA for normal text (4.5:1). It was the site's most-used text colour, and it failed everywhere in the light theme. An earlier version of this file put it at "about 4.6:1"; computed, it's 4.12:1 (domain law 3).
+
+### 900 — secondary text
+
+Emphasised but not primary: a role title above its description, an ancestor row in a table of contents (the section you're inside while a child row is active), body copy where primary would be too heavy.
+
+The gap between 900 (`#4d4d4d`) and 1000 (`#171717`) is deliberately large: secondary should be clearly a step down, not almost-primary.
+
+### 1000 — primary text
+
+Body copy, headings, active states, `<strong>`. `#171717`, not `#000000` (domain law 8).
+
+Also the *fill* for an inverted element: a tooltip is `bg-gray-1000` with `text-background-100`.
+
+**Not for a ticked box in a long list** (`domains/color/status-and-exceptions.md`, **Done, and where the reader is**). Glass's ticked box is a `gray-100` square on its 400 border with a `gray-1000` tick; a switch keeps the inverted fill.
+
+### background-100 · background-200
+
+Held out of the ramp because a page background is categorically different from a component surface. 100 is the page and card surface; 200 a subtle secondary surface.
+
+`background-100` is also the **text** colour for anything inverted, which is why it's a token rather than a hardcoded white: a tooltip's text has to become near-black in the dark theme, and does so for free.
+
+## Dark-mode re-tinting
+
+```css
+:root[data-theme="dark"] {
+  --color-gray-100: #1a1a1a;   /* 100–400: dark surfaces, rising slowly */
+  --color-gray-200: #212121;
+  --color-gray-300: #282828;
+  --color-gray-400: #2e2e2e;
+  --color-gray-500: #707070;   /* 500–800: the mid greys jump */
+  --color-gray-600: #7d7d7d;
+  --color-gray-700: #8f8f8f;
+  --color-gray-800: #a0a0a0;
+  --color-gray-900: #c4c4c4;   /* 900–1000: light text */
+  --color-gray-1000: #ededed;
+}
+```
+
+**It's not an inversion** (domain law 8). Inverting the light ramp would put 100 at `#0d0d0d` and 1000 at `#e8e8e8`, evenly spaced. The real dark ramp is *compressed at the bottom* (100→400 spans only `#1a1a1a`→`#2e2e2e`, twenty units) and *expanded in the middle* (400→500 jumps forty units), because dark surfaces must stay distinguishable at very low lightness, where the eye is more sensitive to small differences, while mid-greys need a big jump to separate "border" from "text."
+
+**700 is identical in both themes** (`#8f8f8f`): a mid-grey solid fill needs the same value either way, the one step where semantic and value coincide.
+
+**The step order stays monotonic in dark mode** (400 `#2e2e2e` > 300 `#282828`). No contradiction: the constraint is the *intent*, and in dark mode a slightly lighter border also happens to be the right lightness order.
+
+Low steps are surfaces and high steps are text in both themes, so `border-gray-400` is a border in light and dark, with no `dark:` variant.
+
+## Borders and text are different jobs
+
+The hardest-won rule here (domain law 2), from auditing the reference implementation against this guide's own checklist. In the light theme:
+
+| Step | Light value | As text on white | Verdict |
+|---|---|---|---|
+| 500 | `#c9c9c9` | 1.66:1 | illegible |
+| 600 | `#a8a8a8` | 2.38:1 | fails even the 3:1 non-text floor |
+| 700 | `#8f8f8f` | 3.23:1 | fails |
+| 800 | `#7d7d7d` | 4.12:1 | fails |
+| 900 | `#4d4d4d` | 8.45:1 | passes |
+| 1000 | `#171717` | 17.93:1 | passes |
+
+Against the near-black page the same indices pass — 800 is 7.53:1, 700 is 6.09:1 — so a system reviewed in dark ships this light theme.
+
+### The fix: text tiers as their own tokens
+
+```css
+:root {
+  --color-muted: #5e5e5e;   /* 6.48:1 — deks, supporting copy, <em> */
+  --color-quiet: #696969;   /* 5.49:1 — resting icons, state labels, <cite> */
+  --color-faint: #757575;   /* 4.61:1 — dates, read times, meta */
+}
+:root[data-theme="dark"] {
+  --color-muted: #a0a0a0;   /* 7.53:1 */
+  --color-quiet: #878787;   /* 5.48:1 */
+  --color-faint: #7a7a7a;   /* 4.59:1 */
+}
+```
+
+**Every tier clears 4.5:1 in both themes**, including the worst real pairing: muted on `gray-100`, a subtle surface, at 5.79:1.
+
+**The ladder stays strictly descending** (domain law 3) — 17.93 / 8.45 / 6.48 / 5.49 / 4.61 in light, 16.81 / 11.28 / 7.53 / 5.48 / 4.59 in dark.
+
+**Only `faint` moved much in dark mode.** `muted` keeps the old 800 value, which already passed there: the failure was overwhelmingly a light-theme one.
+
+## Common failures
+
+**A surface step as a border.** `border-gray-200` looks fine in light mode and vanishes in dark, where 200 is a dark surface nearly flush with 100.
+
+**A text step as an icon.** `text-gray-900` on a 20px icon reads as heavy as primary text and pulls focus off the label. Use `quiet`.
+
+**A border step as text.** The one this guide got wrong for a whole revision (above).
+
+**"Something between 500 and 600"**, and **auditing contrast in dark mode only**: domain laws 1 and 3. Here the worst surface is a subtle `gray-100`, not `background-100`.
+
+## Adding a semantic colour
+
+The reference implementation has none, because nothing on the site reports state. Check that before you add them. If you do, they get their own pairs outside the grey ramp, kept out of the focus ring's territory, and follow domain law 6 and `domains/color/status-and-exceptions.md`: shape carries the state, red means loss and never a live state, destructive actions take a red ground (solid danger with `background-100` text when highlighted), and small marks clear 3:1 on every ground in each theme.
+
+## Spending your one chromatic exception
+
+Glass spends it once, on the collapsed summary panel: an offer, not content (domain law 7). Its containment rules — only the mark takes the accent; every stop re-picked for dark — are in §3 of `glass/color/guide.md`.

package/plugins/keyline/skills/keyline/glass/color/theming.md

@@ -0,0 +1,106 @@
+# Theming
+
+Glass's theme switch, persistence and crossfade, with the values it ships. The mechanism, the head script's four requirements, persistence, `color-scheme`, two states or three, and theme islands are in `domains/color/theming-mechanics.md`; this file holds what Glass does and why.
+
+## A data attribute, not `prefers-color-scheme`
+
+```css
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+```
+
+Tailwind v4 drives `dark:` off the OS media query by default; Glass has a toggle, so `data-theme` on `<html>` is the mechanism (domain law 9). For a permanently-light region inside a dark page, re-declare the custom properties on its container rather than nesting the attribute (`domains/color/theming-mechanics.md`, **Theme islands**).
+
+## No flash of wrong theme
+
+```html
+<head>
+  <!-- Before the stylesheet. Blocking on purpose. -->
+  <script>
+    (function () {
+      try {
+        document.documentElement.dataset.theme =
+          localStorage.getItem("theme") === "dark" ? "dark" : "light";
+      } catch (e) {}
+    })();
+  </script>
+  <link rel="stylesheet" href="…" />
+</head>
+```
+
+Inline, blocking, before the stylesheet, in `try/catch`; it duplicates a few lines of the theme module, with a comment in each place pointing at the other (`domains/color/theming-mechanics.md`, **No flash of wrong theme**).
+
+## Persistence and the crossfade
+
+```ts
+export type ThemeChoice = "light" | "dark";
+
+const KEY = "theme";
+
+export function getThemeChoice(): ThemeChoice {
+  try {
+    if (localStorage.getItem(KEY) === "dark") return "dark";
+  } catch { /* localStorage unavailable */ }
+  return "light";
+}
+
+export function applyTheme(choice: ThemeChoice): void {
+  document.documentElement.dataset.theme = choice;
+}
+
+export function setThemeChoice(choice: ThemeChoice): void {
+  try {
+    localStorage.setItem(KEY, choice);
+  } catch { /* preference just won't persist */ }
+
+  // Crossfade only on explicit toggles.
+  const root = document.documentElement;
+  root.classList.add("theme-transition");
+  applyTheme(choice);
+  window.setTimeout(() => root.classList.remove("theme-transition"), 440);
+}
+```
+
+Three functions for three callers — `getThemeChoice` for initial React state, `applyTheme` for the DOM write, `setThemeChoice` for the user action (`domains/color/theming-mechanics.md`, **Persistence**). The comparison is `=== "dark"`, so anything unrecognised falls through to light.
+
+### The 440ms class
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  :root.theme-transition,
+  :root.theme-transition *,
+  :root.theme-transition *::before,
+  :root.theme-transition *::after {
+    transition: background-color 400ms ease, color 400ms ease, border-color 400ms ease,
+      fill 400ms ease, stroke 400ms ease, box-shadow 400ms ease !important;
+  }
+}
+```
+
+Why it's temporary, `!important`, inside `no-preference` and lists the pseudo-elements: `domains/color/theming-mechanics.md`, **The crossfade on toggle**. Glass's values:
+
+- **440ms**: 400ms plus a 40ms margin so nothing is cut off. For those 440ms it has to beat every component's own `transition-colors duration-150`.
+- **400ms**: the longest duration in the system, for its largest change — every surface, text colour, border, icon fill and shadow at once.
+- **Plain `ease`, not the house curve.** The house easing overshoots, and on a colour that sends the background past its target and back — a wobble in the light.
+
+## `color-scheme`
+
+```css
+:root { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+```
+
+What it re-tints, and the white scrollbar track that shows it's missing: `domains/color/theming-mechanics.md`, **`color-scheme`**.
+
+## Two states, not three
+
+The reference implementation ships **two** explicit modes, Light and Dark, with Light as the default. No "System": a theme control should be predictable, and "System" changes the theme when the OS crosses a sunset threshold, which surprises someone who picked it from the site's own menu. Two `aria-pressed` buttons are also simpler to build and explain than a tri-state. What three would cost — the head script resolving `system`, and a live listener — is in `domains/color/theming-mechanics.md`, **Two states or three**.
+
+## Where `dark:` variants are still needed
+
+Most components need no theme branching; the test for when one does is in `domains/color/theming-mechanics.md`. Glass's cases:
+
+**Multi-layer shadows.** A shadow whose *structure* changes between themes (the inset highlight weakening while the ambient shadows strengthen 10×) can't live in one colour token, but Glass keeps it out of `dark:` too: it's one class, `.dock-shadow`, with its `:root[data-theme="dark"]` twin beside it (`glass/depth/depth-cues.md`, §2), not a JS constant.
+
+**Ring/border colours as alpha of a specific hue.** `ring-black/[0.06] dark:ring-white/[0.08]` encodes what the alpha ramp does, where the utility won't take a token. Prefer `gray-alpha-*` where you can; use the pair where you can't.
+
+**Anything two-toned by design.** The frosted folder pocket uses `border-white/60 dark:border-white/[0.08]`: a bright top edge that must nearly vanish on dark, where it would read as a glowing line.

package/plugins/keyline/skills/keyline/glass/depth/assets/GlassPanel.tsx

@@ -0,0 +1,171 @@
+/**
+ * The glass surface, as a component — every depth cue in one place.
+ *
+ * The point of this file is the wrapper/surface split and the depth cues in
+ * one place. (The elevation stack itself is better as the `.dock-shadow`
+ * class in glass/depth/assets/glass.css — see the note on the SHADOW constant below.)
+ * Glass is four properties plus three depth cues, and the cues are the part
+ * people skip: a blurred tinted rectangle with no hairline and no shadow is a
+ * patch, not a floating panel.
+ *
+ * Pairs with glass/depth/assets/glass.css (the materials) and
+ * glass/color/assets/color-tokens.css (the tints and the ramps).
+ */
+
+import type { ReactNode } from "react";
+
+/* ── Elevation ────────────────────────────────────────────────────────────
+   Four layers modelling one light source above the element:
+
+     inset 1px white   the specular catch where a raised surface faces the
+                       light. Contributes more to the floating impression
+                       than any of the shadows, and is the one most often
+                       omitted — remove it and the surface looks printed on.
+     1px/1px @ 2%      contact shadow: resting on something, not pasted over.
+     8/16 @ 4%         near ambient.
+     24/32 @ 6%        far ambient. Two layers rather than one because a
+                       single large shadow reads as fog; two fall off like
+                       real penumbra.
+
+   Negative spread (-4px, -8px) contracts the shadow before blurring, keeping
+   it tucked under the element instead of haloing past its edges. This is the
+   detail most hand-written shadows miss, and why stock box-shadow presets
+   often look like a glow.
+
+   Opacities are 2-6%. Elevation should be felt, not seen.
+
+   Dark mode is a DIFFERENT shadow, not the same one re-tinted:
+     · shadows go up ~10x   — 4% black on #0b0b0b is mathematically
+                              invisible; dark needs 30-60% to register at all
+     · highlight drops ~6x  — 0.6 white on a dark surface reads as a glowing
+                              edge rather than a catch light
+
+   Because the STRUCTURE changes and not just the values, elevation cannot be
+   a single token — it needs a per-theme pair, and this is the one place raw
+   rgba() outside the token file is acceptable.
+
+   PREFER THE CLASS. `.dock-shadow` in glass/depth/assets/glass.css is the same four
+   layers in a form you can actually read and diff against its dark twin.
+   The reference implementation started with the constant below and moved
+   to the class, for three reasons:
+
+     · it's ~400 characters either way, and four CSS lines beat one string
+     · a constant still gets imported and interpolated at every call site,
+       so a grep for the shadow finds five hits rather than one definition
+     · the arbitrary-value escaping is a live hazard — underscores for
+       spaces, no spaces inside the parens, and a typo produces a class the
+       build silently drops: no shadow, no error
+
+   The constant is kept here for codebases that can't add a stylesheet. */
+export const SHADOW =
+  "shadow-[inset_0_1px_0_rgba(255,255,255,0.6),0_1px_1px_rgba(0,0,0,0.02),0_8px_16px_-4px_rgba(0,0,0,0.04),0_24px_32px_-8px_rgba(0,0,0,0.06)] " +
+  "dark:shadow-[inset_0_1px_0_rgba(255,255,255,0.10),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)]";
+
+/** Hover cards and other briefly-floating panels. One ambient layer, no
+    contact shadow — it's hovering, not resting. */
+export const SHADOW_PANEL =
+  "shadow-[0_8px_24px_-8px_rgba(0,0,0,0.12)] dark:shadow-[0_8px_24px_-8px_rgba(0,0,0,0.6)]";
+
+/** Tooltips. 30% black in BOTH themes — it sits on bg-gray-1000, which is
+    near-black in light and near-white in dark, so the SURFACE sets the
+    requirement rather than the page. Elevation is relative to what's
+    immediately behind, not to the theme. */
+export const SHADOW_TIP = "shadow-[0_4px_10px_-4px_rgba(0,0,0,0.3)]";
+
+/* ── The hairline ─────────────────────────────────────────────────────────
+   From the TRANSLUCENT ramp, not a 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, this 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 to the next weight rather than disappearing. */
+const HAIRLINE = "border-[0.5px] border-gray-alpha-400";
+
+export type GlassTier = "nav" | "panel";
+
+/**
+ * A glass surface with all three depth cues attached.
+ *
+ * `tier` picks the material — and the choice is about how little you know
+ * about the backdrop, not about size or importance:
+ *
+ *   nav    20px blur, 72% tint. Fixed chrome that arbitrary content scrolls
+ *          under.
+ *   panel  24px blur, 97% tint. A floating menu that must stay legible over
+ *          anything — including over other glass.
+ *
+ * `isolate` is on by default because these surfaces usually contain a sliding
+ * highlight at -z-10 (`glass/motion/guide.md`). Without it, -z-10
+ * would drop the highlight behind the container's own tint instead of just
+ * behind the icons.
+ */
+export function GlassSurface({
+  tier = "panel",
+  as: Tag = "div",
+  isolate = true,
+  className = "",
+  children,
+}: {
+  tier?: GlassTier;
+  as?: "div" | "ul" | "nav" | "aside";
+  isolate?: boolean;
+  className?: string;
+  children: ReactNode;
+}) {
+  const material = tier === "nav" ? "glass-nav" : "glass-panel";
+
+  return (
+    <Tag
+      className={`${material} ${HAIRLINE} ${SHADOW} relative ${
+        isolate ? "isolate" : ""
+      } rounded-2xl ${className}`}
+    >
+      {children}
+    </Tag>
+  );
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   THE WRAPPER / SURFACE SPLIT — the one structural rule to internalise.
+
+   A transform on an ancestor weakens or breaks backdrop-filter in its
+   subtree: the blur samples the wrong region, or nothing. So an animating
+   menu must be TWO elements — the wrapper animates, the surface blurs, and
+   they are never the same node:
+
+     <DropMenu open={open}>              // animates scale + y. No filter.
+       <GlassSurface tier="panel">       // filters. Never transformed.
+         …
+       </GlassSurface>
+     </DropMenu>
+
+   Where you can't split them (a surface that must animate itself), fall back
+   to glass-panel's 97% tint and treat the blur as decoration.
+
+   This is also a performance win, not just a correctness one: the wrapper
+   animates on the compositor (transform and opacity only), and the glass
+   child's filter isn't being recomputed against a moving containing block
+   every frame.
+
+   Same root cause, second symptom: a transform also makes an element the
+   containing block for position: fixed descendants. In the reference
+   implementation the fixed nav strip deliberately carries NO transform, so
+   the mobile sheet's w-screen full-bleed overlay can span the viewport
+   instead of being trapped inside the strip's bounds.
+
+   When something filtered or positioned behaves inexplicably, check every
+   ancestor for: transform, filter, perspective, contain, will-change.
+
+   ── And close menus by UNMOUNTING them ─────────────────────────────────
+   A backdrop-filter element still pays its full filter pass when it's
+   transparent — visibility is decided at composite time, after the filter has
+   already run. opacity: 0 and visibility: hidden do NOT save you; unmounting
+   (or display: none) is the only thing that does.
+
+     <AnimatePresence>
+       {open && <m.div …>{children}</m.div>}
+     </AnimatePresence>
+
+   Which also keeps a closed menu out of the tab order.
+   ───────────────────────────────────────────────────────────────────────── */