trykeyline 0.1.1 → 0.1.2

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

@@ -12,7 +12,7 @@
  * 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
+ * Pair with useActiveSection (`glass/motion/assets/useScrollTick.ts`) for the scroll spy, and
  * give every heading a scroll-margin-top just under its READING_LINE.
  */
 
@@ -59,11 +59,8 @@ function ChevronDownIcon() {
 /**
  * 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.
+ * Top-level rows sit flush and carry no marker; the active one takes weight
+ * 500 as well as colour, so state is never on colour alone (type law 5).
  *
  * 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

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

@@ -3,43 +3,15 @@
    ───────────────────────────────────────────────────────────────────────── */
 
 @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. */
+  /* 640px outer, 32px padding → 576px of text, on every page. Why:
+     glass/layout/measure-and-rhythm.md. */
   --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. */
+  /* Continuous corners on every rounded element. 1.5 sits halfway between a
+     round corner (1) and a full squircle (2), which swells at small sizes.
+     Unsupported browsers fall back to normal rounding; nothing depends on it. */
   *,
   *::before,
   *::after {
@@ -54,9 +26,8 @@
     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 link: parked with a transform, never display:none (which drops it
+     from the tab order). Every page needs a matching id="main". */
   .skip {
     position: absolute;
     left: 16px;
@@ -69,20 +40,14 @@
     text-decoration: none;
     border-radius: 6px;
     transform: translateY(-200%);
-    transition: transform 150ms var(--ease-geist);
+    transition: transform var(--duration-state) 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.
-   ───────────────────────────────────────────────────────────────────────── */
+/* Print. The .reveal reset lives in glass/motion/assets/motion-tokens.css. */
 @media print {
   nav,
   footer,
@@ -96,11 +61,6 @@
     font-size: 11pt;
   }
 
-  .reveal {
-    opacity: 1;
-    transform: none;
-  }
-
   /* An underlined URL-less link is noise on paper. */
   a {
     color: inherit;
@@ -108,94 +68,5 @@
   }
 }
 
-/* ─────────────────────────────────────────────────────────────────────────
-   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.
-   ───────────────────────────────────────────────────────────────────────── */
+/* The radius ladder, hairlines, z-index ladder, dvh and pb-28 are not classes:
+   glass/layout/guide.md and glass/layout/radius-and-elevation.md. */

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

@@ -229,17 +229,11 @@ Where a custom animation rules out `<details>`, glass collapses height to zero (
 
 The content stays in the served HTML, for crawlers, `llms.txt` and find-in-page.
 
-```css
-@media print {
-  nav, footer, .skip { display: none; }
-  .reveal { opacity: 1; transform: none; }
-  a { color: inherit; text-decoration: none; }
-}
-```
+Print: `glass/layout/assets/layout-tokens.css`, with the `.reveal` reset in `glass/motion/assets/motion-tokens.css`.
 
 ## Assets
 
-- `glass/layout/assets/layout-tokens.css` — column, spacing, radius ladder, continuous corners, hairlines, skip link, print.
+- `glass/layout/assets/layout-tokens.css` — column, continuous corners, skip link, print.
 - `glass/layout/assets/SectionNav.tsx` — two presentations of one tree, with shared row rendering.
 
 ## Checklist

package/plugins/keyline/skills/keyline/glass/layout/measure-and-rhythm.md

@@ -10,8 +10,6 @@ At the 14px prose size that's about 90 characters a line (85–95, measured in A
 
 The padding does double duty: on a 375px phone the column is `375 − 64 = 311px`, and on desktop the 32px keeps text off the edge of a maximised window.
 
-That 311px once forced a responsive type step (a 30px title wrapping to three lines) until an 18px type ceiling removed it: layout law 1's narrowest-measure check, settled in the scale.
-
 640px also equals Tailwind's `sm` breakpoint — convenient, not meaningful: below it the column is padding-limited, so the two coincide naturally.
 
 The summary and detail pairs it keeps still: home-page role summary → `/experience`, writing index → article.

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

@@ -49,7 +49,7 @@ The rule is in §4 of the guide: `superellipse(1.5)` on every element and pseudo
 | 2px | `outline-2`, `border-l-2` | Focus rings, an imported Markdown quote's rule |
 | 3px | `w-[3px] rounded-full` | The pull-quote bar |
 
-By job (layout law 6): two groups of icons within one dock, 0.5px; where a card ends, 1px; a focus ring, 2px. The authored pull quote's bar is 3px and rounded, so a flex child rather than a border (`glass/type/long-form-prose.md`, Quotes); imported Markdown, which can't take classes, keeps a 2px `gray-alpha-300` border.
+By job (layout law 6): two groups of icons within one dock, 0.5px; where a card ends, 1px; a focus ring, 2px. The authored pull quote's bar is 3px and rounded, so a flex child rather than a border (`glass/type/assets/prose.tsx`); imported Markdown, which can't take classes, keeps a 2px `gray-alpha-300` border.
 
 Vertical dividers use `w-[0.5px]` with an explicit height and `self-center`:
 

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

@@ -4,8 +4,8 @@
  * 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.
+ * The effect comes from letting two springs DISAGREE (motion-presets.ts;
+ * the reasoning is glass/motion/springs.md).
  *
  * Two structural decisions worth keeping:
  *
@@ -16,10 +16,8 @@
  * 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.
+ * It animates a bare m.div and expects its child to carry the glass
+ * (glass/depth/guide.md §3).
  */
 
 import { AnimatePresence, LazyMotion, domAnimation, m, useReducedMotion } from "motion/react";

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

@@ -1,24 +1,9 @@
 /**
- * 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.
+ * Motion presets — the springs and tweens glass uses. Why each number is what
+ * it is: glass/motion/springs.md. Opacity never springs (motion law 6).
  */
 
-/* ── 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. */
+/** Shared highlight or tooltip re-targeting: moving, not arriving. */
 export const SLIDE = {
   type: "spring",
   bounce: 0.2,
@@ -26,184 +11,25 @@ export const SLIDE = {
   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. */
+/** Cards rising out of a folder — the one playful moment. */
 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. */
+/** Squash and stretch: GROW on scaleY and y, CROSS on scaleX (glass/motion/guide.md §4). */
 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. */
+/** Closing: a flat tween that gets 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. */
+/* Icon fill: the filled layer sits over the outline at the same coordinates
+   and cross-fades in place (glass/motion/guide.md §13). ease-out, not the
+   house curve. */
 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. */
+/** The inverse — interior lines the fill swallows (a briefcase's divider). */
 export const detailFade = (on: boolean) =>
   `transition-opacity duration-200 ease-out motion-reduce:transition-none ${
     on ? "opacity-0" : "opacity-100"