trykeyline 0.0.0-stage → 0.1.1

package/plugins/keyline/skills/keyline/domains/motion/patterns.md

@@ -0,0 +1,196 @@
+# Patterns
+
+Code uses role placeholders (`<duration.state>`) and generic custom properties; swap in the names `DESIGN.md` maps them to.
+
+## The shared highlight
+
+One highlight per group, animating its position and size to whichever item is hovered or focused. It never remounts.
+
+```tsx
+// Motion. The same shape works with GSAP quickTo or React Spring's useSpring.
+const [hover, setHover] = useState<{ x: number; y: number; w: number; h: number } | null>(null);
+const enter = (el: HTMLElement) =>
+  setHover({ x: el.offsetLeft, y: el.offsetTop, w: el.offsetWidth, h: el.offsetHeight });
+
+<ul className="group-shell" onPointerLeave={() => setHover(null)}>  {/* position: relative; isolation: isolate */}
+  <m.div
+    aria-hidden
+    className="highlight"                                       /* absolute; z-index: -1; pointer-events: none */
+    initial={false}
+    animate={hover ? { x: hover.x, y: hover.y, width: hover.w, height: hover.h, opacity: 1 } : { opacity: 0 }}
+    transition={reduce ? { duration: <duration.state> } : { ...<spring.snappy>, opacity: { duration: <duration.micro> } }}
+  />
+  {items.map((it) => (
+    <a key={it.id} onPointerEnter={(e) => enter(e.currentTarget)} onFocus={(e) => enter(e.currentTarget)} … />
+  ))}
+</ul>
+```
+
+Six details, each a bug without it:
+
+- **`initial={false}`** (outside Motion, set the first position with no transition), or the highlight flies in from the corner on first paint.
+- **Offsets, not `getBoundingClientRect()`.** `offsetLeft` / `offsetTop` are relative to the positioned parent the highlight lives in; viewport rectangles need subtraction and break if the page scrolls between measure and render.
+- **`isolation: isolate` on the group, `z-index: -1` on the highlight**: behind the items but inside the group's stacking context, so it can't drop behind the group's own surface.
+- **`pointer-events: none`**: the highlight sits under the pointer by definition, and would otherwise steal the enter event and oscillate.
+- **Focus alongside hover**, so keyboard users get the same feedback.
+- **Leave on the group, not the items**: per-item leave fires in the gaps and blanks the highlight between items.
+
+A tooltip rides the same state on one axis: an outer element animates `x` to the item's centre; an inner one is statically `translate: -50% 0`. A plain coordinate animates cleanly; `calc(centre - 50%)` asks the library to interpolate mixed units.
+
+**Current versus hovered.** The current item's static surface drops while the group is hovered, so the travelling highlight owns the surface; two at once make the selection ambiguous. The current item keeps its label colour (colour law 7) throughout, so its place is never lost.
+
+## Layout switches and page-level shared elements
+
+For an element that persists across a DOM change — a card becoming a detail view, a thumbnail becoming the open image:
+
+```css
+/* CSS View Transitions — same-document via document.startViewTransition(update),
+   cross-document via @view-transition { navigation: auto; } */
+.card-image { view-transition-name: var(--vt-name); }  /* unique per element, e.g. set inline per card */
+::view-transition-group(*) { animation-duration: <duration.overlay>; animation-timing-function: <ease.standard>; }
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*), ::view-transition-old(*), ::view-transition-new(*) { animation: none; }
+}
+```
+
+- **Motion:** give both ends the same `layoutId`; the library measures and travels between them.
+- **GSAP:** `const state = Flip.getState(els); /* change the DOM */ Flip.from(state, { duration, ease });`
+
+Whichever tool, **measure the reading position while the outgoing layout is still rendered** — the item nearest the viewport's centre — and open the incoming layout on it. Where the ends differ in aspect ratio, cross-fade two elements, each at its own aspect and sharing a centre, rather than stretching one into the other's box.
+
+## Presence: open and close
+
+```css
+/* CSS only: a popover or dialog entering from display: none */
+.menu {
+  transition: opacity <duration.popover> <ease.colour>, translate <duration.popover> <ease.standard>,
+              display <duration.popover> allow-discrete, overlay <duration.popover> allow-discrete;
+  opacity: 1; translate: 0 0;
+}
+@starting-style { .menu:popover-open { opacity: 0; translate: 0 calc(var(--motion-travel) * -1); } }
+.menu:not(:popover-open) {
+  opacity: 0; translate: 0 calc(var(--motion-travel) * -0.5);   /* the exit travels half as far */
+  transition-duration: var(--motion-exit); transition-timing-function: <ease.exit>;
+}
+```
+
+```tsx
+// Motion: AnimatePresence keeps the element mounted for its exit.
+<AnimatePresence>
+  {open && (
+    <m.div
+      initial={reduce ? { opacity: 0 } : { opacity: 0, scale: 0.96, y: -4 }}
+      animate={{ opacity: 1, scale: 1, y: 0, transition: reduce ? { duration: <duration.state> } : <spring.soft> }}
+      exit={{ opacity: 0, ...(reduce ? {} : { scale: 0.98, y: -2 }), transition: { duration: <exit>, ease: <ease.exit> } }}
+    />
+  )}
+</AnimatePresence>
+```
+
+Scale from the edge the element is anchored to (`transform-origin` at the trigger): a menu growing from its own middle seems to come from nowhere. The wrapper moves; a child carries the translucent material.
+
+## Fill means chosen, in code
+
+The filled state is a second layer over the outline, at the same coordinates, cross-fading in place:
+
+```css
+.icon .fill   { opacity: 0; transition: opacity <duration.popover> <ease.colour>; }
+.icon .detail { opacity: 1; transition: opacity <duration.popover> <ease.colour>; }  /* interior lines a solid shape swallows */
+.is-current .icon .fill,   .item:hover .icon .fill   { opacity: 1; }
+.is-current .icon .detail, .item:hover .icon .detail { opacity: 0; }
+@media (prefers-reduced-motion: reduce) { .icon .fill, .icon .detail { transition: none; } }
+```
+
+Where the solid shape would swallow an interior line, knock it out with a mask rather than deleting it: the silhouette in white (fill and stroke, matching the outline exactly), the interior lines in black at the outline's stroke width. A solid chip chosen instead of fill follows the same rule: one treatment, one meaning.
+
+## Hover intent
+
+```ts
+const closeSoon = () => {
+  clearTimeout(timer.current);
+  timer.current = window.setTimeout(() => setOpen(false), 100);
+};
+const cancelClose = () => clearTimeout(timer.current);
+useEffect(() => () => clearTimeout(timer.current), []);   // unmount
+useEffect(() => setOpen(false), [pathname]);              // navigation
+```
+
+Bind `closeSoon` to leaving the trigger *and* the panel, `cancelClose` to entering either. Any `setTimeout` driving UI state is cleared on unmount and reset on navigation, or a menu opened on one page reappears 100ms into the next. Where they're adjacent, a hover bridge is cheaper: padding on the wrapper spanning the visual gap, so the pointer never leaves the hover region.
+
+## Hover on a card
+
+A wash, with the leave on the resting rule and the arrival on the hovered one, so each direction takes its own time:
+
+```css
+.card       { transition: background-color <hover out> <ease.colour>; }   /* the leave */
+.card:hover { background-color: var(--surface-hover); transition-duration: <hover in>; }
+```
+
+Why a wash, and the timings: `domains/motion/ladder-and-curves.md`.
+
+## Press
+
+`transform: scale(<press>)` on `:active`, `transition-duration: 0` in and `duration.state` back out, on `pointerdown`, not `click`. In `product`, prefer the `surface.pressed` step: a toolbar of twenty shrinking buttons is noise. Anything wider than about 200px presses with `scale(0.98)` or a 1px `translate` instead: at 0.92–0.95 a full-width button loses about 15px and reads as collapsing, not pressed.
+
+## Live indicators
+
+An indicator that reports a live state — level bars while recording, a stroke travelling round a card while something is generated — moves only while the state does, and turns into its action on demand.
+
+```css
+.live .bars span  { animation: level 900ms <ease.standard> infinite alternate; }
+.live[data-paused] .bars span { animation: none; transform: scaleY(0.25); }   /* settle low, don't freeze mid-peak */
+.live .stop, .live .bars { transition: opacity <duration.state> <ease.colour>; }
+.live .stop { opacity: 0; }
+.live:is(:hover, :focus-visible) .stop  { opacity: 1; }
+.live:is(:hover, :focus-visible) .bars  { opacity: 0; }
+@media (prefers-reduced-motion: reduce) { .live .bars span { animation: none; } }
+```
+
+- **Paused settles, it doesn't freeze.** A loop stopped mid-cycle leaves a peak that looks like a glitch; hold a low resting frame, or stop a travelling stroke and dim its glow. Bars driven by a real input level fall on their own; a decorative loop has to be told.
+- **The morph is in place.** Bars and stop square share one box and cross-fade, so the control never moves under the pointer.
+- **The name is the action throughout** — a button named "Stop recording" — because on touch nothing hovers and the tap is the stop.
+
+## Theme cross-fade
+
+A universal colour transition left in the stylesheet makes every hover on the site `duration.theme` and sluggish. Apply it only for the toggle:
+
+```ts
+root.classList.add("theme-transition");
+applyTheme(choice);
+setTimeout(() => root.classList.remove("theme-transition"), THEME_MS + 40);
+```
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  :root.theme-transition, :root.theme-transition *, :root.theme-transition *::before, :root.theme-transition *::after {
+    transition: background-color <duration.theme> <ease.colour>, color <duration.theme> <ease.colour>,
+                border-color <duration.theme> <ease.colour>, fill <duration.theme> <ease.colour>,
+                stroke <duration.theme> <ease.colour> !important;
+  }
+}
+```
+
+The `!important` beats each component's own transition for that window; removing the class stops it poisoning everything after. Pseudo-elements are listed because `*` doesn't match them, and decoration built with them would snap. The curve is `ease.colour`, never one that overshoots: an overshooting colour passes its target and returns. `duration.theme` runs only under this class, when the page itself switches.
+
+A theme that follows the OS by media query changes with no toggle to hook, and every control carrying its own colour transition fades at its own duration while the page around it snaps. So everyday colour transitions never include the page background, and a theme change suspends them: listen for the query's `change` and hold a class for one frame.
+
+```ts
+matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
+  if (readChoice() !== "system") return;   // the reader chose a theme: the OS doesn't override it
+  root.classList.add("theme-instant");   /* :root.theme-instant * { transition: none !important; } */
+  applyTheme(e.matches ? "dark" : "light");
+  requestAnimationFrame(() => requestAnimationFrame(() => root.classList.remove("theme-instant")));
+});
+```
+
+The theme mechanism and flash-free first paint belong to the colour guide.
+
+## Sound, if the preset allows it
+
+Sound is off wherever the user didn't choose to be there. Where it exists, synthesise it with Web Audio rather than shipping files — no request, no decode latency, so it lands with the input — and, non-negotiably:
+
+- **Arm the context on every activation gesture:** `pointerdown`, `keydown` and `touchstart`. Hover is activation in no engine, and a keyboard Enter dispatches `click`, not `pointerdown`, so a pointer-only unlock leaves keyboard users in silence for ever. `wheel` activates nothing; leave it out.
+- **Hover sounds for `pointerType === "mouse"` only**, deduplicated per element: a touch tap fires `pointerover` just before `click`, and plays both.
+- **Dense surfaces opt out of hover sound** with an attribute on the container; above about three ticks a second it stops being feedback.
+- **A visible, persisted mute**, checked at the top of playback rather than at the listener, so it applies to in-flight input; storage access wrapped so it can't throw.
+- **Two sounds is a texture; five is a soundtrack.** Press and, at most, hover.

package/plugins/keyline/skills/keyline/domains/motion/performance.md

@@ -0,0 +1,121 @@
+# Performance
+
+## The one scroll shape
+
+Every scroll-driven behaviour uses one structure. At its smallest, with `update` clearing the flag:
+
+```ts
+let ticking = false;
+const onScroll = () => { if (!ticking) { ticking = true; requestAnimationFrame(update); } };
+window.addEventListener("scroll", onScroll, { passive: true });
+```
+
+In full, with teardown:
+
+```ts
+function onScrollFrame(update: () => void): () => void {
+  let ticking = false;
+  const run = () => { ticking = false; update(); };
+  const onScroll = () => { if (!ticking) { ticking = true; requestAnimationFrame(run); } };
+  update();                                                   // correct on a page loaded already scrolled
+  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("resize", onScroll);                // a resize invalidates the same measurements
+  return () => {
+    window.removeEventListener("scroll", onScroll);
+    window.removeEventListener("resize", onScroll);
+  };
+}
+```
+
+- **`passive: true`**, as the handler never calls `preventDefault()`; without it every scroll event blocks on your JavaScript, the commonest cause of scroll jank.
+- **The `ticking` flag** makes a burst of events (a high-resolution trackpad fires many per frame) one measurement per painted frame.
+- **No `throttle` or `debounce`.** A time-based throttle is faster than the frame rate, wasting work, or slower, dropping frames.
+- **One listener per behaviour**, torn down on unmount. In a component, make the effect's dependency a value, not a fresh array — `ids.join("|")` — or the listener rebuilds every render.
+
+A purely visual effect can use CSS scroll-driven animations (`animation-timeline: scroll()` or `view()`), off the main thread with no listener, behind `@supports (animation-timeline: scroll())` with a static fallback and inside `prefers-reduced-motion: no-preference`.
+
+## Hysteresis
+
+Anything toggled by scroll *direction* needs a dead zone, or a pixel of jitter — trackpad noise, a rubber-band bounce, your own layout change — flips it for ever.
+
+```ts
+const update = () => {
+  const y = window.scrollY;
+  const atBottom = y + window.innerHeight >= document.documentElement.scrollHeight - 2;
+  if (y < 24 || atBottom) setCollapsed(false);   // always expanded at either end — checked first
+  else if (y > last + 6) setCollapsed(true);     // 6px of downward intent
+  else if (y < last - 6) setCollapsed(false);    // 6px of upward intent
+  last = y;
+};
+```
+
+The end zones come first, or a small upward scroll near the foot leaves a collapsed bar over the footer. The `- 2` absorbs sub-pixel rounding on fractional device pixel ratios.
+
+## Never hide an affordance where it can't come back
+
+Gate the effect before attaching anything — layout law 8, with the code in `domains/layout/forks-gating-and-disclosures.md`.
+
+## Scroll spies
+
+Tracking the section being read, for a contents rail:
+
+```ts
+const READING_LINE = 120;   // px below the viewport top
+const update = () => {
+  let current = ids[0];
+  for (const id of ids) {
+    const el = document.getElementById(id);
+    if (!el) continue;
+    if (el.getBoundingClientRect().top > READING_LINE) break;   // document order: stop at the first not yet passed
+    current = id;
+  }
+  if (window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2) current = ids.at(-1)!;
+  setActive((prev) => (prev === current ? prev : current));
+};
+```
+
+- **A reading line, not an `IntersectionObserver`**, because several sections are visible at once and the question is *which heading did I last pass?*
+- **The bottom clamp.** A short final section never crosses the line before the page ends, so the rail would mark the one before it.
+- **Match `scroll-margin-top` to the line**, a little smaller, within ~10px. A contents link that scrolls its heading to y = 0 puts it above the line, and the rail highlights the previous section.
+- **`history.replaceState` for the hash**, not router navigation, which runs the app's own scroll handling and cuts the smooth scroll short.
+
+## What to animate
+
+`width`, `height`, `top`, `left`, `margin` and `padding` lay out on every frame, for the element and possibly its siblings; `transform` and `opacity` don't.
+
+**Name every property.** `transition: all` picks up properties you never intended, including layout ones a parent adds later. The explicit list — `transition: color, background-color, translate` — also makes a hover's *leave* predictable: exactly the listed properties transition out.
+
+**A justified exception** looks like the shared highlight: one absolutely positioned, `pointer-events: none` element outside the flow, whose size change reflows nothing. If you can't say that about an element, scale it instead.
+
+**Animating to auto** without measuring:
+
+```css
+.region { display: grid; grid-template-rows: 0fr; transition: grid-template-rows <duration.overlay> <ease.standard>; }
+.region[data-open] { grid-template-rows: 1fr; }
+.region > * { min-height: 0; overflow: hidden; }
+```
+
+The same works on columns with `min-width: 0`. Where supported, `interpolate-size: allow-keywords` lets `height: auto` transition directly.
+
+**Transforms and `backdrop-filter`.** The moving wrapper and a translucent surface are different elements (depth law 9).
+
+**`will-change`** only on an element about to animate, removed after; left on everything, it pins memory for layers that never move.
+
+## Escalating to the GPU
+
+Some shared-element trips can't be done in the DOM: the ends differ in aspect ratio, so one image distorts all the way, or the view is too large to re-lay-out per frame. Then draw one element on a canvas above the view and animate four numbers — a rectangle — in a uniform.
+
+- **One decorative element, never the view.** A hundred tiles as textures costs hundreds of megabytes, and the tiles carry keyboard and screen-reader semantics a canvas can't. The drawn element has none of its own (`alt=""`, labels elsewhere).
+- **Setup returns `null`, never throws.** Inside an effect, an exception takes the view down instead of falling back. Check for the artefact that proves setup completed — a linked program — rather than trusting the constructor.
+- **`null` is the ordinary path:** the caller keeps its `<img>`, which also serves reduced motion, no WebGL, and a context lost later.
+- **Mipmaps, trilinear filtering**, or a large image drawn small shimmers as it moves sub-pixel.
+- **Soften the last pixel of the edge**, or a rectangle on fractional pixels crawls column by column. Fade alpha only, on a non-premultiplied context.
+- **Don't force-lose the context on teardown.** Frameworks reuse the canvas node across remounts, and a force-lost context silently poisons it.
+
+## Keeping the motion code small
+
+- **Motion:** `LazyMotion` with `domAnimation` and the `m` component; `strict` makes a stray full `motion.*` import a build error. Scope a `domMax` island to the one component that needs layout animations.
+- **GSAP:** register only the plugins in use; import `Flip` or `ScrollTrigger` where they're used, not in a global setup file.
+- **React Spring:** import from `@react-spring/web` only.
+- **CSS first.** A hover, a colour change, a reveal and most presence animations need no library; reach for one when something re-targets, is dragged, or must exit after unmounting.
+

package/plugins/keyline/skills/keyline/domains/patterns/actions-and-forms.md

@@ -0,0 +1,204 @@
+# Actions and forms
+
+## Destructive items in a menu
+
+Every destroying or session-ending item takes the same place and treatment: last, after a divider, no icon, the danger treatment from the colour guide.
+
+```tsx
+<Menu>
+  <MenuItem onSelect={rename}>Rename</MenuItem>
+  <MenuItem onSelect={duplicate}>Duplicate</MenuItem>
+  <MenuItem onSelect={openMoveTo}>Move to…</MenuItem>
+  <MenuSeparator />
+  <MenuItem tone="danger" onSelect={() => openConfirm(row, triggerRef)}>Delete</MenuItem>
+</Menu>
+```
+
+The same holds in the profile menu (Sign out last, alone), in settings (a "Delete workspace" section last on the page, its button in the same danger treatment), and in a bulk-action bar (Delete at the end, set apart).
+
+| Item | Destructive or session-ending? |
+|---|---|
+| Delete, Remove from project, Clear history, Revoke access, Leave workspace, Sign out | Yes — one treatment |
+| Archive (restorable), Mark as done, Hide | No — ordinary items, ideally with Undo |
+| Cancel (an unsaved form) | No — a ghost button, not danger |
+
+## Proof in proportion to the loss
+
+| Loss | Ask for | Example |
+|---|---|---|
+| Reversible | Nothing; Undo in a toast for 5–8s | Archive a task, move a card, remove a tag |
+| One item, irreversible | A dialog; the button repeats the verb | Delete a note |
+| Many items, or someone else's work | A dialog that counts what goes ("48 tasks, 12 notes") | Delete a folder |
+| An account, a project, a workspace | Type a word to confirm | Delete project, delete account |
+
+Escalate on what is lost, not on how serious the screen looks: a bulk delete of 200 rows deserves more than a delete of one project with nothing in it.
+
+## The type-to-confirm dialog
+
+One component, used for every large delete. It is the system's dialog with different contents, never a bespoke surface (depth law 1).
+
+```tsx
+export function ConfirmDestroy({ open, onOpenChange, title, consequence, word = "DELETE",
+                                 action, pendingLabel, onConfirm, returnFocusTo }) {
+  const [typed, setTyped] = useState("");
+  const [state, setState] = useState<"idle" | "pending" | "error">("idle");
+  const [error, setError] = useState("");
+  const inputRef = useRef<HTMLInputElement>(null);
+  const matches = typed.trim().toLowerCase() === word.toLowerCase();
+
+  async function confirm(e: React.FormEvent) {
+    e.preventDefault();
+    if (!matches || state === "pending") return;
+    setState("pending");
+    try {
+      await onConfirm();
+      onOpenChange(false);
+    } catch (err) {
+      setState("error");
+      setError(messageFor(err)); // words, not a code
+    }
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => state !== "pending" && onOpenChange(next)}
+      initialFocus={inputRef}
+      finalFocus={returnFocusTo}  /* the row or menu item that opened it */
+    >
+      <form onSubmit={confirm}>
+        <DialogTitle>{title}</DialogTitle>
+        <p>{consequence}</p>
+        <label htmlFor="confirm-word">Type {word} to confirm</label>
+        <input id="confirm-word" ref={inputRef} value={typed} autoComplete="off"
+               onChange={(e) => setTyped(e.target.value)}
+               aria-describedby={state === "error" ? "confirm-error" : undefined} />
+        {state === "error" && <p id="confirm-error" role="alert">{error}</p>}
+        <DialogFooter>
+          <Button variant="ghost" type="button" onClick={() => onOpenChange(false)}
+                  disabled={state === "pending"}>Cancel</Button>
+          <Button tone="danger" type="submit" disabled={!matches || state === "pending"}>
+            {state === "pending" ? pendingLabel : action}
+          </Button>
+        </DialogFooter>
+      </form>
+    </Dialog>
+  );
+}
+```
+
+- **The input takes focus, not Cancel.** The typed word is the guard; focusing it saves a click without weakening it.
+- **Case-insensitive**, trimmed: the reader proves intent, not typing accuracy.
+- **Held open while pending**: Escape and the scrim do nothing until it settles, so a failure has somewhere to be reported.
+- **Focus returns to what opened it**, the row's neighbour if the row is gone — depth law 12, with the code in `domains/depth/elevation-recipes.md`.
+
+## Undo instead of confirm
+
+For anything reversible, act at once and offer Undo:
+
+```ts
+async function archive(task: Task) {
+  const before = store.snapshot(task.id);
+  store.archive(task.id);
+  toast("Task archived", { action: { label: "Undo", onClick: () => store.restore(before) } });
+  try { await api.archive(task.id); }
+  catch { store.restore(before); toast.error("Couldn't archive task", { action: retry(() => archive(task)) }); }
+}
+```
+
+A confirm dialog in front of every reversible action trains the reader to click through dialogs, which is how the dangerous one gets clicked through too.
+
+## Field anatomy
+
+Label above, control, hint below; an error takes the hint's place rather than adding a line.
+
+```tsx
+<div className="field">
+  <label htmlFor={id}>{label}</label>
+  <Control id={id} aria-invalid={!!error || undefined}
+           aria-describedby={error || hint ? `${id}-note` : undefined} />
+  {(error || hint) && (
+    <p id={`${id}-note`} className={error ? "field-error" : "field-hint"}>
+      {error ?? hint}
+    </p>
+  )}
+</div>
+```
+
+Reserve the note's line height when a field has a hint, so the swap never moves the field below. Validate on blur and on submit, not on every keystroke; clear a field's error as soon as its value changes.
+
+**A form-level failure** — the server refused, the network dropped — is one line above the primary button, with an icon and `role="alert"`, saying what to do next. The fields keep what the reader typed.
+
+## The deciding field first
+
+Order a form by dependency, not by importance:
+
+| Instead of | Do |
+|---|---|
+| Description, then Category | Category (full width), then the fields it shapes, then Description |
+| Free text, then "Is this private?" | Private or shared first, if it changes who can be mentioned |
+| Every field shown, half disabled | Fields appear once the deciding answer allows them, in place, without reflowing what's above |
+
+The deciding field is full width because it is the one question every reader answers; the rest can sit in pairs.
+
+## The sign-in screen
+
+| Region | Holds |
+|---|---|
+| Form column, about 360px, unboxed | Title ("Sign in"), one muted line, fields, the one brand button, the secondary path as a link ("Create an account") |
+| Art panel, from a wide breakpoint | The depth guide's art panel on the other half (`domains/depth/elevation-recipes.md`); moving only if the auth routes are an `expressive` area in `## Profile`, otherwise one still frame |
+| Phone | The form alone; the art is decoration and goes first |
+
+- **No card around the form.** The page is the surface; a card on an otherwise empty page is a box around nothing.
+- **One primary button**, reading the verb: "Sign in", "Create account", "Send link".
+- **Errors**: field errors replace hints; "Wrong email or password" is a form-level line, never a field error that tells an attacker which half was right.
+- **Password managers** need `autocomplete="email"` / `"current-password"` / `"new-password"` and real `<form>` submission.
+- The panel's build and theme scope are the depth guide's art-panel recipe (`domains/depth/elevation-recipes.md`); its motion is the motion guide's ambient class, with a still frame under reduced motion; inputs at 16px on phones, so the browser doesn't zoom, are the type guide.
+
+## Pending states by how long the wait is
+
+| Wait | The reader sees | Where |
+|---|---|---|
+| Under 100ms | The control's own press state | On the control |
+| ≈ 400ms – 1s | The label turns to its progressive form ("Save" → "Saving…"), width held, the control disabled against a second press | In the button |
+| 1s – 10s | A skeleton of what's coming: the rows, the panel's shape, never a centred spinner over a blank region | In the region that will change |
+| Over 10s | Determinate progress — "Importing 340 of 1,200" — with Cancel, and a notice when it's done if the reader has left | In the region, then a toast off screen |
+
+Show the pending state only once the threshold passes, so a fast response never flashes it:
+
+```tsx
+function usePending(pending: boolean, after = 400) {
+  const [shown, setShown] = useState(false);
+  useEffect(() => {
+    if (!pending) return setShown(false);
+    const t = setTimeout(() => setShown(true), after);
+    return () => clearTimeout(t);
+  }, [pending, after]);
+  return shown;
+}
+
+// <button disabled={saving} style={{ minWidth }}>{usePending(saving) ? "Saving…" : "Save"}</button>
+```
+
+A skeleton, once shown, stays for at least ≈ 300ms, or a response that lands just after the threshold makes the region flicker twice.
+
+## Forgiving inputs
+
+Normalise on blur and on submit, and keep what was typed visible until then:
+
+| Field | Accept | Store |
+|---|---|---|
+| Email | Capitals, leading and trailing spaces | Trimmed, domain lower-cased |
+| Phone | Spaces, dashes, brackets, a leading `+` or `00` | E.164 (`+447700900123`) |
+| Card, IBAN, codes | Spaces and dashes, pasted in any grouping | Digits only; displayed back in groups of four |
+| Date | "12 Mar", "12/3", "tomorrow", a picker | ISO date; displayed in the reader's locale |
+| Amount | "1,200", "1200.00", a currency symbol | A number in minor units |
+
+`inputmode` and `autocomplete` do half the work — `inputmode="numeric"` for codes, `"email"`, `"tel"` — so the right keyboard arrives and the browser fills what it knows. An error names the fix ("Add the year"), not the rule broken ("Invalid format").
+
+## Progress through a flow, and its end
+
+- **Show position and what's left**: "Step 2 of 3" or a short list of named steps, the current one marked, earlier ones ticked and revisitable.
+- **Start with credit**: a setup checklist opens with the step the reader just finished already ticked.
+- **No step counter for one screen**, and none that changes length mid-flow; if a branch adds steps, show the new count when the branch is chosen.
+- **The end state** names what happened in the product's nouns ("Riverside project created"), shows the thing itself or a link to it, and offers the next action ("Invite your team"). It is a screen, not a toast that leaves the reader on the last form.

package/plugins/keyline/skills/keyline/domains/patterns/agents-and-live-states.md

@@ -0,0 +1,111 @@
+# Agents and live states
+
+Two patterns for output the reader didn't write and can't fully predict: an agent taking actions, and text arriving as it's produced. Both fail the same way — they ask for trust instead of showing their work.
+
+## The tool-call card
+
+Every tool call is one card in the conversation, in the order it happened.
+
+| Part | Holds |
+|---|---|
+| Header row | Status glyph · tool name in sentence case ("Search tasks", not `search_tasks`) · a one-line summary of the arguments ("Overdue, Riverside") · duration once done |
+| Arguments | Key–value pairs with labels from the glossary; long values truncated with "Show all" |
+| Result | A summary first ("12 tasks"), the raw result behind a disclosure |
+| Approval | Only when the step needs one — inline, under the card |
+
+**Open or closed.** A running step is open, so the reader can watch it; a finished one collapses to its header; a failed one stays open with the error in words and a Retry where retrying is safe. The reader's own open or closed choice wins over all three until the conversation reloads.
+
+**Status shape, not just colour.** The glyph changes shape between running, done, failed and waiting for approval (shape carries state, colour confirms it: the colour guide); a spinner inside the glyph is fine, a spinner instead of the card is not.
+
+```tsx
+<details open={state !== "done"} className="tool-call">
+  <summary>
+    <StatusGlyph state={state} />
+    <span className="tool-name">{label(tool.name)}</span>
+    <span className="tool-args">{summarise(tool.args)}</span>
+    {state === "done" && <time>{formatDuration(ms)}</time>}
+  </summary>
+  <ArgsList args={tool.args} />
+  <ToolResult result={result} />
+</details>
+```
+
+A native `<details>` keeps the content in the page for find-in-page and copy (layout law 11).
+
+## Inline approvals
+
+A step that changes something outside the conversation — sends a message, edits records, spends money — waits for approval under its own card:
+
+```
+┌ ◌ Send email · to 3 members ─────────────────────┐
+│ Subject   Site walk moved to Thursday             │
+│ To        Sam, Priya, Jo                          │
+└───────────────────────────────────────────────────┘
+  [Send email]  [Don't send]
+```
+
+- **The approve button names the action** and takes the brand action colour; reject is a muted ghost button. Not "Approve" and "Reject": the reader should be able to read the button alone.
+- **Never a modal.** The card above it, and the turns above that, are the evidence for the decision; a modal covers them.
+- **Never focused by default**, and never on Enter from the composer: an approval is a decision, not a keystroke the reader was already making.
+- **After the answer**, the buttons give way to a line saying what was decided ("Sent", "Not sent"), so the record stays readable.
+- **Several pending steps** each keep their own buttons; an "Approve all" may sit above them only when every step is the same kind of action.
+
+## Conversation layout
+
+- **No avatar per message.** Two speakers don't need faces to be told apart.
+- **The reader's turns** sit right-aligned, on a light tint, at most about two-thirds of the panel's width.
+- **The agent's turns** run full width with no fill — they are the content, and they hold tables, cards and code that need the width.
+- **AI-made content elsewhere** in the product — a summary on a record, a suggested title — carries one small mark in brand beside it, not a robot face or a coloured block (the colour guide).
+- **The panel is non-modal**: a side panel or sheet the reader can work beside, keyboard-reachable, closed by Escape when focus is inside it.
+- **The composer**: Enter sends, Shift+Enter adds a line; the send button is disabled while empty and becomes Stop while the agent is working.
+
+## Live text
+
+A live transcript or a streaming answer has two kinds of text, and they must look different:
+
+| Part | Treatment |
+|---|---|
+| Committed segments | Ink, final; never rewritten |
+| The phrase still forming | Muted, with a brand caret at its end |
+| Speaker or time markers | Meta tier, at each change, not on every line |
+
+**Following the bottom.** Follow while the reader is at the bottom; stop the moment they scroll up; show "Jump to latest" until they return:
+
+```ts
+function useFollowBottom(el: HTMLElement | null, deps: unknown[]) {
+  const atBottom = useRef(true);
+  useEffect(() => {
+    if (!el) return;
+    const onScroll = () => {
+      atBottom.current = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+    };
+    el.addEventListener("scroll", onScroll, { passive: true });
+    return () => el.removeEventListener("scroll", onScroll);
+  }, [el]);
+  useLayoutEffect(() => {
+    if (el && atBottom.current) el.scrollTop = el.scrollHeight;
+  }, deps); // eslint-disable-line react-hooks/exhaustive-deps
+  return atBottom;
+}
+```
+
+**The top fade** says more is above, and costs nothing to layout:
+
+```css
+.live-scroll {
+  mask-image: linear-gradient(to bottom, transparent 0, #000 32px);
+}
+```
+
+**Announcing.** Put committed segments in a polite live region, one segment at a time; keep the forming phrase out of it, or a screen reader re-reads every word as it changes. A visually hidden region beside the visible text is often simpler than making the visible list live.
+
+## Paused, stopped, failed
+
+| State | Shows | Offers |
+|---|---|---|
+| Live | Moving level bars or the one "working" signal | Pause; on hover and focus the live control becomes Stop |
+| Paused | Everything still; the forming phrase committed or dropped | View (the text so far), Copy, Resume |
+| Stopped | The full text, final | Copy, and whatever the product does next with it |
+| Failed | What was captured, kept | Retry, and the captured text never lost |
+
+What moves while live and stops while paused is motion law 1; what colour a live state takes is the colour guide's *Live is not danger*.