trykeyline 0.0.0-stage → 0.1.0

package/plugins/keyline/skills/keyline/glass/layout/radius-and-elevation.md

@@ -0,0 +1,102 @@
+# Radius, corners, and stacking
+
+Glass's values for layout laws 5–7; the rules themselves, and the nesting worked through in general, are in `domains/layout/radius-lines-and-layers.md`.
+
+## The nesting rule, through the site
+
+Layout law 5, in the reference implementation's dock:
+
+```
+Dock:          rounded-2xl      (16px)   p-1  (4px padding)
+  Icon button: rounded-[12px]   (12px)            16 − 4 = 12  ✓
+    Avatar:    rounded-[10px]   (10px)   inset ~2px   12 − 2 = 10  ✓
+```
+
+Three levels, each derived. The avatar is `h-9 w-9` inside an `h-10 w-10` button — a 2px inset all round, so 10px.
+
+The mobile sheet snaps to the ladder:
+
+```
+Sheet:  rounded-2xl   (16px)   p-1.5 (6px)
+  Row:  rounded-xl    (12px)          16 − 6 = 10, rounded up to 12
+```
+
+## The ladder
+
+| Radius | Class | For |
+|---|---|---|
+| full | `rounded-full` | Pills, tags, dots, markers |
+| 2px | — | The focus ring's own radius |
+| 5px | `rounded-[5px]` | A lettermark box (tiny, so a small radius) |
+| 6px | `rounded-md` | Tooltips, the skip link |
+| 9px | `rounded-[9px]` | Small cards in a stack |
+| 10px | `rounded-[10px]` | Avatar inside a button; a list highlight bar |
+| 12px | `rounded-xl` / `rounded-[12px]` | Cards, hover panels, disclosures, icon buttons |
+| 16px | `rounded-2xl` / `rounded-[16px]` | Outer containers — a dock, a sheet, a pocket |
+
+Radius scales with size, not importance (layout law 5): a 40px icon button gets 12px; a 300px panel gets 16px.
+
+## Continuous corners
+
+The rule is in §4 of the guide: `superellipse(1.5)` on every element and pseudo-element. **1.5 rather than 2** because a full squircle is noticeable — at small sizes it looks like a slightly swollen rectangle. Halfway reads as a well-drawn corner rather than an effect.
+
+## Hairline weights
+
+| Weight | Class | For |
+|---|---|---|
+| 0.5px | `border-[0.5px]`, `h-[0.5px]` | Chrome borders, dividers, glass edges |
+| 1px | `border`, `ring-1`, `h-px` | Card borders, TOC markers |
+| 2px | `border-l-2` | Quote rules, focus rings |
+
+By job (layout law 6): two groups of icons within one dock, 0.5px; where a card ends, 1px; a blockquote's left rule, 2px.
+
+Vertical dividers use `w-[0.5px]` with an explicit height and `self-center`:
+
+```tsx
+<span aria-hidden className="mx-0.5 h-6 w-[0.5px] self-center bg-gray-alpha-300" />
+```
+
+A 24px line in a 40px-tall row, one step lighter than the dock's `alpha-400` edge, because it's an internal articulation, not a boundary.
+
+**The box form is a gap the reference implementation still has.** `h-[0.5px]` and `w-[0.5px]` with a background are boxes, which layout law 6 says a 1x screen can drop. Draw every hairline as a border instead: `border-t-[0.5px]` on the element, or an empty span carrying `border-l-[0.5px]` for a vertical divider, the same weight and colour by the more reliable route.
+
+## Elevation tiers
+
+Glass's shadow tiers — chrome, pocket, panel, card, transient — are depth's: `glass/depth/depth-cues.md`.
+
+## The z-index ladder
+
+The ladder is in §8 of the guide. **The 40/50 pair** in code:
+
+```tsx
+{open && (
+  <div aria-hidden onClick={() => setOpen(false)}
+       className="pointer-events-auto fixed inset-0 z-40 sm:hidden" />
+)}
+<div className="pointer-events-auto relative z-50 sm:hidden">
+  {/* the menu */}
+</div>
+```
+
+**`z-index: 10` for a hover lift:**
+
+```tsx
+<Link className="group relative block transition-[z-index] hover:z-10 focus-within:z-10">
+```
+
+Folder cards rising out of a pocket would otherwise be clipped by the next folder; `focus-within:z-10` gives keyboard focus the same lift.
+
+## Stacking-context techniques
+
+The general techniques are in `domains/layout/radius-lines-and-layers.md`. Glass's cases:
+
+- **`isolate` plus negative z** scopes the dock's sliding highlight behind its icons but in front of the glass: the code is in `glass/depth/depth-cues.md`.
+- **The nav strip** passes clicks through and carries no transform (§8 of the guide); a transform would trap the mobile sheet's full-bleed `w-screen` overlay inside the strip.
+
+### `transform-origin` for menus
+
+```tsx
+const anchor = placement === "up" ? "origin-bottom" : "origin-top";
+```
+
+A menu scales **from its trigger's edge**, or it seems to detach and drift; off one side, use the corner: `origin-top-left`.

package/plugins/keyline/skills/keyline/glass/motion/assets/DropMenu.tsx

@@ -0,0 +1,106 @@
+/**
+ * The squash-and-stretch floating menu — the shared open/close motion for
+ * every menu in the system (a phone nav sheet, a settings drop-up, a socials
+ * pill). All of them grow out of a trigger sitting against one edge, so all
+ * of them stretch from that edge.
+ *
+ * The effect comes from letting two springs DISAGREE. See motion-presets.ts
+ * for the numbers and the reasoning.
+ *
+ * Two structural decisions worth keeping:
+ *
+ * 1. The panel mounts only while open, so a closed menu is out of the tab
+ *    order and off the paint. That matters here because the panel carries
+ *    backdrop-filter, which is expensive even when invisible.
+ *
+ * 2. The wrapper is ALWAYS present, so a trigger's aria-controls still
+ *    resolves to a real element when the menu is closed.
+ *
+ * Note this component animates a bare m.div and expects its child to carry
+ * the glass. A transform on an ancestor weakens backdrop-filter in its
+ * subtree — the wrapper scales, the child blurs, and they must be different
+ * elements.
+ */
+
+import { AnimatePresence, LazyMotion, domAnimation, m, useReducedMotion } from "motion/react";
+import type { CSSProperties, ReactNode } from "react";
+import { GROW, CROSS, CLOSE } from "./motion-presets";
+
+export type DropPlacement = "up" | "down";
+
+export function DropMenu({
+  open,
+  placement = "up",
+  origin,
+  id,
+  className = "",
+  style,
+  onMouseEnter,
+  onMouseLeave,
+  children,
+}: {
+  open: boolean;
+  placement?: DropPlacement;
+  /** transform-origin class — defaults to the edge the menu grows from. */
+  origin?: string;
+  id?: string;
+  className?: string;
+  style?: CSSProperties;
+  onMouseEnter?: () => void;
+  onMouseLeave?: () => void;
+  children: ReactNode;
+}) {
+  const reduce = useReducedMotion();
+
+  // Start nudged back toward the trigger, so it reads as coming out of it.
+  const away = placement === "up" ? 4 : -4;
+
+  // Scale from the anchored edge, or the caller's corner for a menu that
+  // hangs off one side of its trigger (e.g. origin-top-left).
+  const anchor = origin ?? (placement === "up" ? "origin-bottom" : "origin-top");
+
+  return (
+    <div
+      id={id}
+      style={style}
+      onMouseEnter={onMouseEnter}
+      onMouseLeave={onMouseLeave}
+      // Empty and inert when closed, so it can't sit over the page as a trap.
+      className={`${className} ${open ? "" : "pointer-events-none"}`}
+    >
+      <LazyMotion features={domAnimation} strict>
+        <AnimatePresence>
+          {open && (
+            <m.div
+              className={anchor}
+              /* Open squashes from a real offset; exit only travels part of
+                 the way back, because it's disappearing anyway. */
+              initial={
+                reduce ? { opacity: 0 } : { opacity: 0, scaleY: 0.82, scaleX: 0.94, y: away }
+              }
+              animate={reduce ? { opacity: 1 } : { opacity: 1, scaleY: 1, scaleX: 1, y: 0 }}
+              exit={
+                reduce
+                  ? { opacity: 0, transition: CLOSE }
+                  : { opacity: 0, scaleY: 0.9, scaleX: 0.97, y: away, transition: CLOSE }
+              }
+              transition={
+                reduce
+                  ? { duration: 0.15 }
+                  : {
+                      scaleY: GROW,  // the grow axis overshoots
+                      y: GROW,       // travel rides the same spring, or the
+                                     // anchored edge detaches mid-overshoot
+                      scaleX: CROSS, // the cross axis arrives late
+                      opacity: { duration: 0.14, ease: "easeOut" },
+                    }
+              }
+            >
+              {children}
+            </m.div>
+          )}
+        </AnimatePresence>
+      </LazyMotion>
+    </div>
+  );
+}

package/plugins/keyline/skills/keyline/glass/motion/assets/motion-presets.ts

@@ -0,0 +1,210 @@
+/**
+ * Motion presets — every spring and tween in the system, with the
+ * reduced-motion substitutes.
+ *
+ * Two vocabularies appear here on purpose:
+ *   bounce + duration          — a designer's controls; predictable arrival
+ *   stiffness + damping + mass — needed when the RELATIONSHIP between two
+ *                                springs is the effect (see GROW / CROSS)
+ *
+ * The one rule that applies to all of them: opacity never springs. Position
+ * wants physics, opacity wants a curve. A spring on opacity overshoots past
+ * its clamp and hitches on the way back — a visible flicker at the tail of
+ * every fade.
+ */
+
+/* ── Shared element re-targeting ─────────────────────────────────────────
+   A highlight or tooltip sliding to a new item. bounce is near the floor of
+   "perceptibly springy" on purpose: this is a thing MOVING, not a thing
+   ARRIVING. Bounce implies a moment of settling, and a highlight that
+   settles at every stop draws attention to itself instead of to the item
+   it's marking. */
+export const SLIDE = {
+  type: "spring",
+  bounce: 0.2,
+  duration: 0.4,
+  opacity: { duration: 0.16, ease: "easeOut" },
+} as const;
+
+/* ── The one playful moment ──────────────────────────────────────────────
+   Cards rising out of a folder on hover. 40% more bounce and 25% more
+   duration than anything else in the system. That it's the ONLY such moment
+   is why it works: against a baseline of restraint, one exuberant
+   interaction reads as craft. Three of them read as a template. */
+export const LIFT = { type: "spring", bounce: 0.28, duration: 0.5 } as const;
+
+/* ── Squash and stretch, out of physics ──────────────────────────────────
+   Two springs of deliberately different character, applied to the two axes
+   of one panel. Every difference pushes the same direction — GROW is fast
+   and loose, CROSS is slow and controlled:
+
+     stiffness  620 vs 380   GROW pulls harder, moves sooner
+     damping     19 vs  30   GROW resists less, overshoots
+     mass      0.85 vs   1   GROW is lighter, accelerates faster
+
+   Through the overshoot the panel is briefly TALLER and NARROWER than it
+   ends up, then settles. Squash and stretch emerging from physics rather
+   than a hand-authored timeline — interruptible and velocity-aware for free.
+
+   Generalises: when two axes of one element move together, giving them
+   different springs creates deformation, and deformation reads as mass. */
+export const GROW = { type: "spring", stiffness: 620, damping: 19, mass: 0.85 } as const;
+export const CROSS = { type: "spring", stiffness: 380, damping: 30 } as const;
+
+/* ── Closing ─────────────────────────────────────────────────────────────
+   A tween, not a spring. easeIn, so it accelerates away rather than
+   decelerating in. 130ms, well under the state tier.
+
+   A bounce on the way out reads as the interface being reluctant, and it
+   stands between the user and whatever they're reaching for next.
+   Entrances can have character; exits should get out of the way. */
+export const CLOSE = { duration: 0.13, ease: "easeIn" } as const;
+
+/* ── Reduced motion ──────────────────────────────────────────────────────
+   Substitute, don't subtract. The preference exists because large-area or
+   accelerating motion is physically unpleasant for some users — it is not a
+   preference for a static interface. A user who sets it still needs to know
+   that a menu opened.
+
+   Flat, state-tier, no overshoot. The state change stays legible; the
+   physics goes away. */
+export const FLAT = { duration: 0.15 } as const;
+
+/** Pick the spring or its flat substitute. `reduce` from useReducedMotion(). */
+export function motionOr<T>(reduce: boolean | null, animated: T) {
+  return reduce ? FLAT : animated;
+}
+
+/* ── Duration ladder, for inline JS use ──────────────────────────────────
+   Mirrors motion-tokens.css. Seconds, because that's what Motion takes. */
+export const DURATION = {
+  micro: 0.1,
+  state: 0.15,
+  popover: 0.2,
+  route: 0.26,
+  overlay: 0.3,
+  theme: 0.4,
+} as const;
+
+/* ── Off the ladder, deliberately ────────────────────────────────────────
+   The ladder is for STATE: something changed and the user has to follow it.
+   Two categories aren't state, and squeezing them onto the ladder makes
+   them worse rather than tighter.
+
+   THE SUBJECT OF THE MOMENT. When the thing animating IS the content, the
+   user is looking directly at it and the motion has to read in its own
+   right. Note the discipline in the pair below: same component, two
+   durations, decided by whether the motion is the subject or the report. */
+export const SUBJECT = {
+  /** Stepping between images — a noise-thresholded dissolve, not a cut. */
+  dissolve: 0.62,
+  /** The same image moving between two layouts. On screen at both ends, so
+      it only has to be followable — back inside the overlay tier. */
+  flight: 0.42,
+} as const;
+
+/* A SET PIECE gets its own budget by never appearing again: once per tab,
+   never blocking a deep link, never played under reduced motion. See §14 of
+   glass/motion/guide.md for the gating. */
+export const SET_PIECE = {
+  /** The first open of a disclosure, per line. */
+  theatreLine: 0.34,
+  /** Every subsequent open of the same thing. */
+  quietLine: 0.16,
+  /** Between staggered children on the first open only. */
+  stagger: 0.09,
+} as const;
+
+/* ── The curve for a track that also drives a filter ─────────────────────
+   NOT --ease-geist. The house curve overshoots past 1, and a blur animating
+   to 0px would have to pass through a NEGATIVE radius to settle back.
+   Browsers clamp rather than crash, so the symptom isn't an error — it's a
+   value stuck at zero for the tail while everything else is still moving,
+   which reads as the animation stalling right at the end.
+
+   Applies to any property with a hard floor: blur, brightness, a radius
+   going to 0, a scale you've promised won't invert. Expo-out has the same
+   "arrives decisively" character without ever leaving [0, 1]. */
+export const EASE_FILTER = [0.16, 1, 0.3, 1] as const;
+
+/* ── Blur crossfade ──────────────────────────────────────────────────────
+   Text swapping in place — a wordmark revealing its tagline on hover, say.
+   Note the asymmetry (280 in / 180 out): same principle as the springs.
+
+   Blur is the vestibular trigger; the fade isn't. So reduced motion swaps
+   only the blur amount to 0px and keeps the crossfade. Animating
+   blur(0px) → blur(0px) is a no-op the browser optimises away, so this needs
+   no second code path. */
+export function blurCrossfade(reduce: boolean | null) {
+  const blur = reduce ? "blur(0px)" : "blur(4px)";
+  return {
+    initial: { opacity: 0, filter: blur },
+    animate: { opacity: 1, filter: "blur(0px)", transition: { duration: 0.28, ease: "easeOut" } },
+    exit: { opacity: 0, filter: blur, transition: { duration: 0.18, ease: "easeIn" } },
+  } as const;
+}
+
+/* ── First-open theatre ──────────────────────────────────────────────────
+   Staggered lines behind a blur, on the FIRST open only; every subsequent
+   open is a quick fade. `theatre` comes from sessionStorage, so it is false
+   on the server for everyone and true on the client for most.
+
+   Which is why the shut state below is a CONSTANT. Branch a rendered style
+   on a client-only flag and React hands you two different first paints and
+   says so in the console. Only the transition reads the flags — a transition
+   isn't a style, so there's nothing for hydration to disagree about, and a
+   reader who asked for less motion gets a zero-length transition to the same
+   end state rather than a different starting position.
+
+   Record "seen" on animation COMPLETE, not on start: setting it earlier
+   lands in the same render batch as the open and cancels the very animation
+   it's recording. */
+export function theatreLine(reduce: boolean | null, theatre: boolean) {
+  return {
+    shut: { opacity: 0, y: 6, filter: "blur(4px)" },
+    open: {
+      opacity: 1,
+      y: 0,
+      filter: "blur(0px)",
+      transition: {
+        duration: reduce ? 0 : theatre ? SET_PIECE.theatreLine : SET_PIECE.quietLine,
+        // A blur is on this track — see EASE_FILTER above.
+        ease: EASE_FILTER,
+      },
+    },
+  } as const;
+}
+
+/** The parent's stagger. Zero after the first open, so a re-open is instant. */
+export function theatreList(theatre: boolean) {
+  return {
+    open: {
+      transition: {
+        staggerChildren: theatre ? SET_PIECE.stagger : 0,
+        delayChildren: theatre ? 0.06 : 0,
+      },
+    },
+  } as const;
+}
+
+/* ── Icon fill ───────────────────────────────────────────────────────────
+   Fill means CHOSEN — the page you're on, or the one you're pointing at.
+   Nothing is filled because it looks better.
+
+   The filled variant is not a second drawing: it's the same outline with its
+   interior painted in, layered OVER the stroke at the same coordinates. The
+   silhouette never moves, so the two crossfade in place — no pop, no reflow.
+
+   ease-out, not the house curve: the overshoot is right for travel and wrong
+   for a fade. Same split the springs make between position and opacity. */
+export const fillFade = (on: boolean) =>
+  `transition-opacity duration-200 ease-out motion-reduce:transition-none ${
+    on ? "opacity-100" : "opacity-0"
+  }`;
+
+/** The inverse — interior lines a solid shape swallows (a briefcase's
+    divider, a document's rules) have to leave as the fill arrives. */
+export const detailFade = (on: boolean) =>
+  `transition-opacity duration-200 ease-out motion-reduce:transition-none ${
+    on ? "opacity-0" : "opacity-100"
+  }`;

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

@@ -0,0 +1,176 @@
+/* ─────────────────────────────────────────────────────────────────────────
+   Interface motion — tokens and CSS-driven effects
+   Drop-in for Tailwind v4 (@theme) or plain CSS (the :root fallback below).
+   ───────────────────────────────────────────────────────────────────────── */
+
+@theme {
+  /* ── One curve for the whole system ─────────────────────────────────────
+     The 1.1 end control point overshoots ~10% and settles back — enough to
+     feel physical, not enough to read as bounce. A single shared curve is
+     why unrelated elements moving at once still feel like one mechanism.
+
+     Do NOT add a second bezier "because this needs a different feel." If an
+     element needs distinct character it needs a spring — that's the axis
+     where character belongs without fragmenting the system. */
+  --ease-geist: cubic-bezier(0.175, 0.885, 0.32, 1.1);
+
+  /* ── Duration ladder ────────────────────────────────────────────────────
+     Set by how much of the screen changes, not by how important the element
+     feels. Three numbers carry almost everything: 150 / 200 / 300. */
+  --duration-micro: 100ms;    /* one property, no position — link opacity  */
+  --duration-state: 150ms;    /* colour, background, small transform, icon */
+  --duration-popover: 200ms;  /* chevron, hover card, compound glyph       */
+  --duration-route: 260ms;    /* whole viewport, on the critical path      */
+  --duration-overlay: 300ms;  /* large region entering or collapsing       */
+  --duration-theme: 400ms;    /* literally everything, at once            */
+
+  /* ── Off the ladder, deliberately ───────────────────────────────────────
+     The ladder is for STATE. Two things aren't state, and squeezing them
+     onto it makes them worse rather than tighter.
+
+     THE SUBJECT OF THE MOMENT — the thing animating IS the content, so the
+     user is looking directly at it and the motion has to read in its own
+     right. Note the pair: the dissolve is the subject, the flight is a
+     report about it, so the flight stays inside the overlay tier. */
+  --duration-dissolve: 620ms; /* stepping between images                   */
+  --duration-flight: 420ms;   /* one image moving between two layouts      */
+
+  /* A SET PIECE earns its budget by never appearing again — once per tab,
+     never blocking a deep link, never played under reduced motion. */
+  --duration-setpiece-in: 560ms;
+  --duration-setpiece-out: 320ms;
+
+  /* ── The curve for a track that also drives a filter ────────────────────
+     NOT --ease-geist. The house curve overshoots past 1, and a blur
+     animating to 0px would have to pass through a NEGATIVE radius to settle
+     back. Browsers clamp rather than crash, so the symptom is a value stuck
+     at zero for the tail of the transition — which reads as the animation
+     stalling right at the end, and is very hard to attribute.
+
+     Applies to any property with a hard floor: blur, brightness, a radius
+     going to 0, a scale you've promised won't invert. Expo-out has the same
+     "arrives decisively" character without ever leaving [0, 1]. */
+  --ease-filter: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* Plain-CSS fallback if you're not on Tailwind v4. */
+:root {
+  --ease-geist: cubic-bezier(0.175, 0.885, 0.32, 1.1);
+}
+
+@layer components {
+  /* ── Reveal on scroll ────────────────────────────────────────────────────
+     CSS animates; JS only sets `data-in` (see useReveal.ts). 8px of travel —
+     enough to register, small enough that a page of revealing paragraphs
+     doesn't feel like it's sliding around. */
+  .reveal {
+    opacity: 0;
+    transform: translateY(8px);
+    transition: opacity var(--duration-overlay) var(--ease-geist),
+                transform var(--duration-overlay) var(--ease-geist);
+  }
+  /* An attribute, not a class — see useReveal.ts for why a class can't survive. */
+  .reveal[data-in] {
+    opacity: 1;
+    transform: translateY(0);
+  }
+
+  /* Off entirely — the animation IS the effect, so there's nothing to
+     degrade to. Note it resolves to opacity: 1; the danger with any
+     reveal-on-scroll is leaving content stuck at opacity: 0. */
+  @media (prefers-reduced-motion: reduce) {
+    .reveal {
+      opacity: 1;
+      transform: none;
+      transition: none;
+    }
+  }
+
+  /* Print is a real presentation, and scroll-triggered content prints blank
+     without this. The most-forgotten line in the file. */
+  @media print {
+    .reveal {
+      opacity: 1;
+      transform: none;
+    }
+  }
+
+  /* THE THIRD GUARD IS NOT CSS. A feature check can't catch "JavaScript
+     never ran at all": the rules above ship, `.reveal` applies, and nothing
+     arrives to add `.in`. The reader gets a correct document they cannot
+     see — a blank page rather than a plain one. Put this in the head:
+
+       <noscript>
+         <style>.reveal { opacity: 1 !important; transform: none !important; }</style>
+       </noscript>
+
+     The general rule: any CSS that hides content pending JavaScript needs a
+     <noscript> reset. */
+
+  /* ── Route transition ───────────────────────────────────────────────────
+     Opacity only — no slide, no scale. Directional motion implies a spatial
+     relationship between routes; in a flat site map there isn't one.
+
+     260ms rather than 300: a page transition sits directly between "I
+     clicked" and "I can read," and that latency reads as the site being
+     slow. 260 is the shortest crossfade that isn't mistaken for a flicker.
+
+     `both` holds the from-state before the animation starts, preventing a
+     one-frame flash of opaque content. Key the wrapper on the pathname to
+     replay it on each navigation. */
+  .route-fade {
+    animation: routeFade var(--duration-route) var(--ease-geist) both;
+  }
+  @keyframes routeFade {
+    from { opacity: 0; }
+    to   { opacity: 1; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .route-fade { animation: none; }
+  }
+
+  /* ── Theme crossfade ────────────────────────────────────────────────────
+     Added by the theme setter for ~440ms on an explicit toggle only, then
+     removed. Left in permanently it would make EVERY hover state on the site
+     400ms and sluggish — the !important is what lets it beat each
+     component's own duration-150 for those 440ms, and the removal is what
+     stops it poisoning everything else.
+
+     400ms because this is the largest possible change: every surface, text
+     colour, border, icon fill and shadow simultaneously.
+
+     Plain `ease`, not the house curve — overshoot on a position is momentum;
+     overshoot on a colour interpolation means the background travels past
+     its target and comes back, which reads as a wobble in the light.
+
+     The whole rule sits inside no-preference, so it's opt-in. Reduced-motion
+     users still get the theme change, just instantly. */
+  @media (prefers-reduced-motion: no-preference) {
+    :root.theme-transition,
+    :root.theme-transition *,
+    :root.theme-transition *::before,
+    :root.theme-transition *::after {
+      transition: background-color var(--duration-theme) ease,
+                  color var(--duration-theme) ease,
+                  border-color var(--duration-theme) ease,
+                  fill var(--duration-theme) ease,
+                  stroke var(--duration-theme) ease,
+                  box-shadow var(--duration-theme) ease !important;
+    }
+  }
+
+  /* ── Skip link ──────────────────────────────────────────────────────────
+     Parked off-screen with a transform (not display:none, which would take
+     it out of the tab order) and slid in on focus at the state tier. */
+  .skip {
+    position: absolute;
+    left: 16px;
+    top: 16px;
+    z-index: 100;
+    transform: translateY(-200%);
+    transition: transform var(--duration-state) var(--ease-geist);
+  }
+  .skip:focus {
+    transform: translateY(0);
+  }
+}

package/plugins/keyline/skills/keyline/glass/motion/assets/useReveal.ts

@@ -0,0 +1,65 @@
+import { useEffect } from "react";
+
+/**
+ * Marks any `.reveal` element as arrived, with `data-in`, when it scrolls into
+ * view. The CSS does all the animating (see motion-tokens.css); this only sets
+ * an attribute.
+ *
+ * An attribute rather than a class, and that is not a style choice. `class` is a
+ * prop React owns: the moment any `.reveal` element gets a className that depends
+ * on state, React rewrites the whole attribute from its own value and a class
+ * added out here is gone. The element then has `.reveal` with nothing to say it
+ * arrived, so it fades to `opacity: 0` — and the observer has already unobserved
+ * it, so it never comes back. React doesn't render `data-in`, so it leaves it be.
+ *
+ * Pass a value that changes on navigation (e.g. the pathname) so the observer
+ * re-attaches to the new page's `.reveal` elements after a route change —
+ * without it, a client-side navigation leaves the incoming page's content
+ * permanently at opacity: 0.
+ *
+ * THE THIRD GUARD IS NOT IN THIS FILE, and it's the one people miss. A feature
+ * check can't catch "JavaScript never ran at all": the CSS ships, `.reveal`
+ * applies, and nothing arrives to set `data-in`. The reader gets a correct document
+ * they cannot see. Put this in the document head, beside where you load the app:
+ *
+ *   <noscript>
+ *     <style>.reveal { opacity: 1 !important; transform: none !important; }</style>
+ *   </noscript>
+ *
+ * The general rule: any CSS that hides content pending JavaScript needs a
+ * <noscript> reset. This is a correctness bug, not a nicety — the failure mode
+ * is a blank page rather than a plain one.
+ */
+export function useReveal(dep?: unknown) {
+  useEffect(() => {
+    // No IntersectionObserver → show everything immediately. Never leave
+    // content invisible behind a feature check.
+    if (typeof IntersectionObserver === "undefined") {
+      document.querySelectorAll(".reveal").forEach((el) => el.setAttribute("data-in", ""));
+      return;
+    }
+
+    const io = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            entry.target.setAttribute("data-in", "");
+            // A reveal is one-shot. Re-animating on scroll-back is nauseating,
+            // and unobserving keeps the observer's element list shrinking.
+            io.unobserve(entry.target);
+          }
+        }
+      },
+      // No fractional threshold, deliberately. An element's intersection ratio
+      // can never exceed the viewport's height divided by its own, so anything
+      // more than ten screens tall can't reach 0.1 however far you scroll, and
+      // it sits at opacity 0 for the whole page. The bottom margin does the job
+      // the threshold was doing: reveal once the element is 40px inside the
+      // viewport, at any height.
+      { threshold: 0, rootMargin: "0px 0px -40px 0px" }
+    );
+
+    document.querySelectorAll(".reveal").forEach((el) => io.observe(el));
+    return () => io.disconnect();
+  }, [dep]);
+}