trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/glass/layout/adaptive-presentations.md

@@ -0,0 +1,231 @@
+# Adaptive presentations
+
+Glass's forks, views and breakpoints, for layout laws 8, 9 and 11; the fork test, capability queries, the touch audit and container breakpoints in general are in `domains/layout/forks-gating-and-disclosures.md`.
+
+## Case 1: the navigation dock
+
+```tsx
+export function BottomNav() {
+  return (
+    <nav aria-label="Primary"
+         className="pointer-events-none fixed inset-x-0 bottom-5 z-50 flex justify-center">
+      <MobileDock />    {/* sm:hidden  */}
+      <DesktopDock />   {/* hidden sm:block */}
+    </nav>
+  );
+}
+```
+
+**`DesktopDock`** — icon buttons with a shared sliding highlight and tooltip; hovering an arrow opens a settings drop-up. Scrolling down collapses it to the avatar; hovering, scrolling up, or reaching either end of the page expands it.
+
+**`MobileDock`** — the avatar and a menu button opening a drop-up sheet: pages as text rows, then socials, sound and theme. Toggling a preference leaves the sheet open; navigating or tapping outside closes it.
+
+Almost nothing is shared, because every desktop interaction is hover-driven and touch fires none of them:
+
+| Behaviour | Desktop | Mobile |
+|---|---|---|
+| Reveal pages | Always visible, collapse on scroll | Inside a sheet |
+| Reveal settings | Hover an arrow | A row in the sheet |
+| Item feedback | Sliding highlight + tooltip | `active:bg-highlight` |
+| Labels | Tooltip on hover | Text in the row |
+| Collapse on scroll | Yes | No — nothing brings it back |
+| Press feedback | `active:scale-[0.92]` | `active:scale-[0.92]` |
+
+What *is* shared is extracted — the destinations array, the icons, the preferences hook:
+
+```tsx
+function useNavPrefs() {
+  const [soundOn, setSoundOn] = useState(true);
+  const [theme, setTheme] = useState<ThemeChoice>(getThemeChoice);
+  // …
+  return { soundOn, setSound, theme, pickTheme, sync };
+}
+```
+
+The collapse-on-scroll effect bails out entirely unless `(hover: hover) and (pointer: fine)` matches, so touch never attaches the listener (layout law 8).
+
+### The `sync` subtlety
+
+Both docks are always mounted (hidden by CSS), each with its own copy of the preferences, so a change in the desktop settings box before the viewport crossed the breakpoint would leave the mobile sheet showing a stale toggle.
+
+```tsx
+const toggle = () => {
+  if (!open) sync();     // re-read the stored values as the sheet opens
+  setOpen((o) => !o);
+};
+```
+
+The desktop panel needs no equivalent: it *mounts fresh* on open and reads the values then, whereas the mobile trigger lives in the always-present dock, so its state outlives the panel.
+
+## Case 2: the table of contents
+
+Same tree, two containers, shared row rendering.
+
+```tsx
+/** Shared — used by both presentations. */
+function Rows({ nodes, active, parents, onJump }) { … }
+
+/** The sticky rail, in the left margin on wide screens. */
+export function SectionNav({ nodes, active, onJump }) {
+  return (
+    <nav aria-label="On this page">
+      <ul className="flex flex-col">
+        <Rows … />
+      </ul>
+    </nav>
+  );
+}
+
+/** The narrow-screen disclosure — one line above the article. */
+export function SectionNavCompact({ nodes, active, onJump }) {
+  const [open, setOpen] = useState(false);
+  const jump = (id: string) => { setOpen(false); onJump(id); };
+  return (
+    <details open={open} onToggle={(e) => setOpen(e.currentTarget.open)}
+             className="group rounded-xl border border-gray-alpha-300">
+      <summary className="… [&::-webkit-details-marker]:hidden">
+        On this page
+        <span className="… group-open:rotate-180 motion-reduce:transition-none">
+          <ChevronDownIcon />
+        </span>
+      </summary>
+      <ul className="… border-t border-gray-alpha-300">
+        <Rows … onJump={jump} />
+      </ul>
+    </details>
+  );
+}
+```
+
+Both are rendered; CSS picks one:
+
+```tsx
+<div className="absolute inset-y-0 left-8 hidden w-[196px] xl:block">
+  <div className="sticky top-28 max-h-[calc(100dvh-11rem)] overflow-y-auto">
+    <SectionNav {...nav} />
+  </div>
+</div>
+
+<div className="reveal mt-8 xl:hidden">
+  <SectionNavCompact {...nav} />
+</div>
+```
+
+The props are memoised so both get a stable object:
+
+```tsx
+const nav = useMemo(() => ({ nodes: toc, active, onJump: jump }), [active, jump]);
+```
+
+The compact version is a `<details>` (layout law 11); `open` is mirrored into React state only so it can close itself after a jump. `[&::-webkit-details-marker]:hidden` plus `list-none` removes the default triangle so the chevron can be styled, and `group-open:rotate-180` reads the parent's `open` attribute, so the rotation needs no state. It costs **one line** above the article, which is what makes a nav in the reading flow acceptable.
+
+## Case 3: two views of one collection, chosen by the reader
+
+The first two cases fork on a *device* capability; the gallery's **wall** and **roll** fork on a preference. The interaction model changes, not just the arrangement (layout law 8).
+
+### The state can't live in either component
+
+The control and what it controls are siblings, so a third party owns the value:
+
+```ts
+export type GalleryLayout = "grid" | "roll";
+let current: GalleryLayout = "grid";
+
+const listeners = new Set<(layout: GalleryLayout) => void>();
+export function onGalleryLayoutChange(fn: (l: GalleryLayout) => void) {
+  listeners.add(fn);
+  return () => { listeners.delete(fn); };
+}
+export function setGalleryLayout(layout: GalleryLayout) {
+  current = layout;
+  for (const fn of listeners) fn(layout);
+}
+```
+
+The shape of a theme or sound store, for the same reason: neither consumer can be the other's parent without distorting the layout.
+
+```ts
+// Mirror it in a hook. Read in an EFFECT, not during render: on a
+// server-rendered page the module and the server agree on "grid" for a fresh
+// load, but arriving from another gallery with "roll" already picked would
+// have the client's first paint disagree with the markup.
+export function useGalleryLayout() {
+  const [layout, setLayout] = useState<GalleryLayout>("grid");
+  useEffect(() => {
+    setLayout(getGalleryLayout());
+    return onGalleryLayoutChange(setLayout);
+  }, []);
+  return { layout, pickLayout: setGalleryLayout };
+}
+```
+
+### The choice doesn't persist
+
+The theme persists to `localStorage` forever; the gallery layout lives in module memory, so a fresh load, a reload and a move between galleries all open on the wall (layout law 9; the reason is in §6 of the guide).
+
+### The switch carries the position
+
+Find the item nearest the viewport's centre before the outgoing layout unmounts and open the incoming one there — the measurement is `centreFrame` in `glass/motion/shared-element.md`.
+
+### Each tile declares its own aspect ratio
+
+```tsx
+<figure style={{ aspectRatio: `${photo.w} / ${photo.h}` }}>
+```
+
+Nothing is cropped, so `object-cover` has nothing to do; nothing shifts on load; and one image travels between layouts undistorted, because both ends compute to the same shape.
+
+## Hover in Tailwind
+
+Tailwind v4's `hover:` variant already compiles to a `(hover: hover)` guard, so utility hover states are safe by default. Imperative JavaScript needs the explicit check.
+
+## The touch-versus-hover audit
+
+Glass's answers to the audit in `domains/layout/forks-gating-and-disclosures.md`:
+
+| Hover behaviour | Touch equivalent |
+|---|---|
+| Icon label as a tooltip | Text label in the sheet |
+| Settings box on hover | A row in the sheet |
+| Company card on row hover | Sits below the row instead of beside it, at a wider breakpoint |
+| Folder cards rising | Not available — but the folder is still a link to the same page |
+| Dock collapse on scroll | Doesn't happen |
+
+The folder-card lift is the honest case: a delight beat carrying no information, so touch users lose nothing they need.
+
+## Where responsive utilities are still right
+
+Arrangement, not interaction:
+
+```tsx
+"grid gap-4 sm:gap-6 grid-cols-3"           // grid density
+"columns-3 gap-1 sm:columns-4"              // masonry columns
+"pt-28 sm:pt-20"                            // page padding under fixed chrome
+"absolute left-3 right-3 top-full … xl:left-full xl:top-1/2 xl:ml-6 xl:w-60"
+```
+
+The last is a hover card *below* its row on narrow screens and *beside* it at `xl`, where there's finally margin: only position moves, so it's correctly a breakpoint.
+
+## Breakpoints in use
+
+| Breakpoint | Width | What changes |
+|---|---|---|
+| `sm` | 640px | Mobile dock ↔ desktop dock. Page padding. Masonry columns. Stack columns. |
+| `xl` | 1280px | The TOC rail appears. The hover card moves beside its row. |
+
+Two for the whole site, both derived from content. Both are viewport breakpoints only because here the column *is* the page. `sm` coincides with the reading measure: below it the column is padding-limited, the natural place for the layout to change character. `xl` is where a 640px column finally leaves margin for a 196px rail. Type size is *not* on the list: a 30px article title once stepped to 26px below `sm`, until an 18px type ceiling removed the need (`glass/layout/measure-and-rhythm.md`; the Glass type guide, `glass/type/guide.md`).
+
+## Breakpoints on the container
+
+Where a pane shares the screen with something that opens and closes, it breaks on its own width (layout law 8). In Tailwind:
+
+```tsx
+<section className="@container">                  {/* the pane, not the page */}
+  <div className="grid @2xl:grid-cols-[minmax(240px,1fr)_2fr]">
+    <List />
+    <Detail className="@container" />            {/* sizes its own insides */}
+  </div>
+</section>
+```
+
+Tailwind v4 ships `@container` and the `@sm:`…`@7xl:` variants; plain CSS is `container-type: inline-size` and `@container (min-width: …)`. The list is clamped with `minmax` so it narrows before the detail does, and the nested `@container` lets the detail size its own gutters, rail and labels.

package/plugins/keyline/skills/keyline/glass/layout/assets/SectionNav.tsx

@@ -0,0 +1,244 @@
+/**
+ * Two presentations of one tree — the canonical "fork the container, share
+ * the data" example.
+ *
+ *   SectionNav         the sticky rail that lives in the left margin
+ *   SectionNavCompact  the disclosure that replaces it when there's no margin
+ *
+ * Both render the same nodes through the same `Rows` component. Only the
+ * container differs, because only the container's interaction model differs.
+ *
+ * Rows are real in-page anchors, so they work without JavaScript and can be
+ * copied as links; the click handler takes over to scroll smoothly and keep
+ * the URL in step.
+ *
+ * Pair with useActiveSection (`glass/motion/guide.md`) for the scroll spy, and
+ * give every heading a scroll-margin-top just under its READING_LINE.
+ */
+
+import { useMemo, useState } from "react";
+
+export type TocNode = {
+  /** Id of the heading this row jumps to. */
+  id: string;
+  label: string;
+  children?: TocNode[];
+};
+
+/** Flattens the tree into document order — what the scroll spy measures. */
+export function tocIds(nodes: TocNode[]): string[] {
+  return nodes.flatMap((n) => [n.id, ...tocIds(n.children ?? [])]);
+}
+
+/** child id → parent id, so the section an active row belongs to stays lit. */
+function parentMap(nodes: TocNode[]): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const n of nodes) for (const c of n.children ?? []) map.set(c.id, n.id);
+  return map;
+}
+
+type RowState = "active" | "ancestor" | "rest";
+
+function ChevronDownIcon() {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+      className="h-3.5 w-3.5"
+    >
+      <path d="M6 9l6 6 6-6" />
+    </svg>
+  );
+}
+
+/**
+ * One row.
+ *
+ * Top-level rows sit flush and carry no marker — they read as the headings
+ * they are, and the active one takes a heavier WEIGHT so its state isn't
+ * signalled by colour alone (WCAG 1.4.1). Weight is a genuine second channel:
+ * it survives greyscale, colour-blindness and low-contrast displays, and it's
+ * cheaper than a background pill in a list that's meant to be quiet.
+ *
+ * Nested rows carry a horizontal marker that extends and darkens when active,
+ * and which doubles as their indent. It sits in a FIXED-WIDTH box so growing
+ * it never nudges the label.
+ *
+ * Three tiers of tone and marker, not two: `ancestor` (the section you're
+ * inside, when a child is active) sits between active and rest, so you never
+ * lose the larger context.
+ */
+function Row({
+  node,
+  state,
+  nested,
+  onJump,
+}: {
+  node: TocNode;
+  state: RowState;
+  nested?: boolean;
+  onJump: (id: string) => void;
+}) {
+  const tone =
+    state === "active"
+      ? "text-gray-1000"
+      : state === "ancestor"
+        ? "text-gray-900"
+        : "text-quiet hover:text-gray-1000";
+
+  const marker =
+    state === "active"
+      ? "w-4 bg-gray-1000"
+      : state === "ancestor"
+        ? "w-2.5 bg-gray-600"
+        : "w-2 bg-gray-500";
+
+  return (
+    <a
+      href={`#${node.id}`}
+      aria-current={state === "active" ? "true" : undefined}
+      onClick={(e) => {
+        e.preventDefault();
+        onJump(node.id);
+      }}
+      className={`flex items-start gap-2.5 py-[3px] text-[13px] leading-[1.4] transition-colors duration-150 ease-geist ${tone} ${
+        !nested && state === "active" ? "font-medium" : ""
+      }`}
+    >
+      {nested && (
+        <span aria-hidden className="mt-[9px] w-4 shrink-0">
+          <span
+            className={`block h-px transition-[width,background-color] duration-150 ease-geist motion-reduce:transition-none ${marker}`}
+          />
+        </span>
+      )}
+      {node.label}
+    </a>
+  );
+}
+
+/** Shared tree rendering. Both presentations go through this. */
+function Rows({
+  nodes,
+  active,
+  parents,
+  onJump,
+}: {
+  nodes: TocNode[];
+  active: string;
+  parents: Map<string, string>;
+  onJump: (id: string) => void;
+}) {
+  const state = (id: string): RowState =>
+    id === active ? "active" : parents.get(active) === id ? "ancestor" : "rest";
+
+  return (
+    <>
+      {nodes.map((n) => (
+        <li key={n.id}>
+          <Row node={n} state={state(n.id)} onJump={onJump} />
+          {n.children && (
+            <ul className="flex flex-col">
+              {n.children.map((c) => (
+                <li key={c.id}>
+                  <Row node={c} state={state(c.id)} nested onJump={onJump} />
+                </li>
+              ))}
+            </ul>
+          )}
+        </li>
+      ))}
+    </>
+  );
+}
+
+/**
+ * The sticky rail. Mount it as an absolute child of the wider frame, so it
+ * sits outside the reading column:
+ *
+ *   <div className="relative mx-auto max-w-[1280px]">
+ *     <div className="absolute inset-y-0 left-8 hidden w-[196px] xl:block">
+ *       <div className="sticky top-28 max-h-[calc(100dvh-11rem)] overflow-y-auto">
+ *         <SectionNav {...nav} />
+ *       </div>
+ *     </div>
+ *     <div className="col">…</div>
+ *   </div>
+ *
+ * The absolute wrapper spans the section's full height so the sticky child
+ * has a track to travel. The dvh cap plus overflow-y-auto means a long
+ * contents scrolls inside itself rather than running off the screen.
+ */
+export function SectionNav({
+  nodes,
+  active,
+  onJump,
+}: {
+  nodes: TocNode[];
+  active: string;
+  onJump: (id: string) => void;
+}) {
+  const parents = useMemo(() => parentMap(nodes), [nodes]);
+
+  return (
+    <nav aria-label="On this page">
+      <ul className="flex flex-col">
+        <Rows nodes={nodes} active={active} parents={parents} onJump={onJump} />
+      </ul>
+    </nav>
+  );
+}
+
+/**
+ * The narrow-screen contents: collapsed to a single row, so it costs one line
+ * above the article — which is the constraint that makes putting a nav in the
+ * reading flow acceptable at all. Closes itself once you've jumped.
+ *
+ * <details> rather than a div and state, because it brings keyboard behaviour,
+ * aria-expanded, and find-in-page (browsers open a closed <details> to reveal
+ * a match) for free, and it works with JS disabled. Mirroring `open` into
+ * state is only so the disclosure can close itself after a jump.
+ *
+ * group-open:rotate-180 reads the parent's `open` attribute directly — no
+ * state needed for the chevron.
+ */
+export function SectionNavCompact({
+  nodes,
+  active,
+  onJump,
+}: {
+  nodes: TocNode[];
+  active: string;
+  onJump: (id: string) => void;
+}) {
+  const parents = useMemo(() => parentMap(nodes), [nodes]);
+  const [open, setOpen] = useState(false);
+
+  const jump = (id: string) => {
+    setOpen(false);
+    onJump(id);
+  };
+
+  return (
+    <details
+      open={open}
+      onToggle={(e) => setOpen(e.currentTarget.open)}
+      className="group rounded-xl border border-gray-alpha-300"
+    >
+      <summary className="flex cursor-pointer list-none items-center justify-between gap-3 px-3.5 py-2.5 text-[13px] text-gray-1000 [&::-webkit-details-marker]:hidden">
+        On this page
+        <span className="text-quiet transition-transform duration-200 ease-geist group-open:rotate-180 motion-reduce:transition-none">
+          <ChevronDownIcon />
+        </span>
+      </summary>
+      <ul className="flex flex-col border-t border-gray-alpha-300 px-3.5 py-2">
+        <Rows nodes={nodes} active={active} parents={parents} onJump={jump} />
+      </ul>
+    </details>
+  );
+}

package/plugins/keyline/skills/keyline/glass/layout/assets/layout-tokens.css

@@ -0,0 +1,201 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   Layout and hierarchy — tokens and structural primitives
+   ───────────────────────────────────────────────────────────────────────── */
+
+@theme {
+  /* ── The measure ────────────────────────────────────────────────────────
+     640px outer, 32px padding → 576px of text. At the 14px prose size that's
+     ~90 characters per line (85–95): past the comfortable range, which is the
+     right place for a site that expects sustained reading (long lines are
+     efficient once the reader is committed, and 1.75 leading pays for the
+     longer return sweep).
+
+     EVERY page uses this. The payoff isn't visual consistency, it's
+     positional continuity: clicking from a summary into its detail view
+     doesn't move the text, so the transition reads as expansion rather than
+     as arriving at a different document. */
+  --container-col: 640px;
+
+  /* The outer frame that rails anchor to, alongside the column. Anchoring
+     both to the SAME frame is what makes the gap between them hold steady
+     from 1280px up — a rail positioned against the viewport instead drifts
+     away from the content it indexes as the window grows. */
+  --container-frame: 1280px;
+  --rail-width: 196px;
+}
+
+@layer base {
+  /* Apple-style continuous corners on every rounded element.
+
+     A standard border-radius is a quarter-circle: constant curvature that
+     drops abruptly to zero where it meets the straight edge. The eye reads
+     that discontinuity as a slight hardness. A superellipse varies curvature
+     continuously into the edge.
+
+     superellipse(k) uses exponent 2^k — k=1 is a normal round corner, k=2 a
+     full iOS squircle, so 1.5 lands about halfway. Not 2, because a full
+     squircle is noticeable at small sizes (it starts to look like a swollen
+     rectangle); halfway reads as "well-drawn corner" rather than as an
+     effect.
+
+     Unsupported browsers ignore it and fall back to normal rounding. Keep it
+     that way — nothing else in the layout should depend on it. */
+  *,
+  *::before,
+  *::after {
+    corner-shape: superellipse(1.5);
+  }
+}
+
+@layer components {
+  .col {
+    max-width: var(--container-col);
+    margin: 0 auto;
+    padding: 0 32px;
+  }
+
+  /* Skip link. Parked off-screen with a TRANSFORM, never display:none —
+     which would take it out of the tab order and defeat the point. Every
+     page needs a matching id="main". */
+  .skip {
+    position: absolute;
+    left: 16px;
+    top: 16px;
+    z-index: 100;
+    background: var(--color-gray-1000);
+    color: var(--color-background-100);
+    padding: 10px 14px;
+    font-size: 13px;
+    text-decoration: none;
+    border-radius: 6px;
+    transform: translateY(-200%);
+    transition: transform 150ms var(--ease-geist);
+  }
+  .skip:focus {
+    transform: translateY(0);
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   Print. A real presentation, not an afterthought.
+
+   The .reveal reset is the one people forget: scroll-triggered content is at
+   opacity: 0 until an IntersectionObserver fires, and printing never fires
+   it — so the page prints blank without this.
+   ───────────────────────────────────────────────────────────────────────── */
+@media print {
+  nav,
+  footer,
+  .skip {
+    display: none;
+  }
+
+  body {
+    background: #fff;
+    color: #000;
+    font-size: 11pt;
+  }
+
+  .reveal {
+    opacity: 1;
+    transform: none;
+  }
+
+  /* An underlined URL-less link is noise on paper. */
+  a {
+    color: inherit;
+    text-decoration: none;
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+   REFERENCE — apply these in components; they're documentation, not classes.
+
+   ── The radius ladder ──────────────────────────────────────────────────
+   Nesting rule: INNER = OUTER − the padding between them. Geometry, not
+   taste — two concentric rounded rectangles share a centre of curvature
+   only if their radii differ by exactly the gap between their edges.
+
+     rounded-full     pills, tags, dots, markers
+     rounded-[5px]    a lettermark box
+     rounded-md    6  tooltips, the skip link
+     rounded-[9px] 9  small cards in a stack
+     rounded-[10px]10 avatar inside a button · a list highlight bar
+     rounded-xl   12  cards, hover panels, disclosures, icon buttons
+     rounded-2xl  16  outer containers — a dock, a sheet, a pocket
+
+   Worked example:
+     Dock          rounded-2xl (16)  p-1 (4)
+       Icon button rounded-[12px]          16 − 4 = 12  ✓
+         Avatar    rounded-[10px]          12 − 2 = 10  ✓
+
+   Radius scales with SIZE, not importance — and sub-proportionally, because
+   a large element with a proportional radius reads as a lozenge.
+
+   ── Hairline weights ───────────────────────────────────────────────────
+   The choice is about what the line is DOING:
+
+     0.5px   internal articulation — a divider between icon groups inside
+             one dock. Renders as a true sub-pixel hairline on retina and
+             rounds UP to 1px elsewhere, so it degrades rather than vanishes.
+     1px     a real edge — where a card ends.
+     2px     a focus ring; imported Markdown's blockquote rule.
+     3px     the authored pull quote's bar — a rounded flex child, not a
+             border, since a border can't be rounded on its own.
+
+   On translucent surfaces use the ALPHA ramp (border-gray-alpha-400). A
+   solid border on glass doesn't participate in what's behind it and reads as
+   a pasted-on frame.
+
+   An <hr> needs border-0 before you give it a background, or you get the UA
+   border AND your line. Non-semantic dividers get aria-hidden.
+
+   ── The z-index ladder ─────────────────────────────────────────────────
+   Ordered by PERMANENCE, not importance. Gaps of 10 so something can be
+   inserted without renumbering.
+
+     100   skip link — must beat everything, including modals
+      60   a once-a-session overlay — over the dock, under the skip link
+      50   fixed navigation
+      40   tap-outside catcher — under the nav, over the page
+      30   a pocket front, above the cards it contains
+      20   hover cards, dropdowns
+      10   a hovered item lifting above its siblings
+     -10   a sliding highlight, behind content inside `isolate`
+
+   60 is what the gaps were for: a greeting overlay arrived long after this
+   ladder was set and slotted in without touching an existing value.
+
+   Two pairs to understand rather than copy. 40/50: a full-screen catcher
+   must be above the page (to catch the click) and below the menu it
+   dismisses (or it eats the menu's own clicks). 60/100: a splash overlay
+   covers the navigation — or it isn't covering the page — but must never
+   cover the skip link, because a keyboard user tabbing during a two-second
+   greeting has to be able to get past it.
+
+   ── Two techniques ─────────────────────────────────────────────────────
+   isolate + negative z: a highlight bar behind icons but in front of its
+   container's background. `-z-10` alone drops it behind the container;
+   `isolate` scopes the negative z inside.
+
+   pointer-events-none on a full-width strip, auto on the content: a fixed
+   nav strip spans the viewport for centring but must not swallow every click
+   along the bottom of the page.
+
+   And the strip carries NO TRANSFORM. A transform makes an element the
+   containing block for position:fixed descendants — a full-bleed w-screen
+   overlay inside it would be trapped in the strip's bounds. Same class of
+   problem as transforms weakening backdrop-filter: when something positioned
+   or filtered behaves inexplicably, check every ancestor for transform,
+   filter, perspective, contain, and will-change.
+
+   ── Viewport units ─────────────────────────────────────────────────────
+   Use dvh, never vh. `vh` refers to the viewport WITHOUT mobile browser
+   chrome, so a 100vh element extends under the address bar and its bottom is
+   unreachable. `dvh` tracks the actual visible area.
+
+   ── Bottom padding ─────────────────────────────────────────────────────
+   Anything with fixed bottom chrome needs pb-28 (112px) audited page by
+   page, or the last line sits under the nav. The most common "looks fine on
+   my long page" bug.
+   ───────────────────────────────────────────────────────────────────────── */