transitions-refine 0.1.0

package/.agents/skills/refine-live/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: refine-live
+description: Become the live "Refine" agent for the Timeline Inspector. Use when the user runs `/refine live`, asks to "refine live", "go live", "answer refine jobs", or wants the timeline panel's Refine button (LLM mode) to be backed by a real agent. Long-polls the local refine relay, reasons about each CSS transition with the transitions-dev skill, and posts suggestions back to the browser panel.
+---
+
+# Refine Live
+
+Turn yourself into the LLM behind the Timeline Inspector's **Refine** button. While
+this loop runs, the panel's **LLM** tab is "available": each click sends one
+transition here, you reason about it, and your suggestions appear in the panel.
+
+You are the poller. Nothing is installed — you just talk to a small local relay
+(default `http://localhost:7331`) that the `npx` injector already started.
+
+## How it works
+
+```
+Browser (Refine, LLM tab) ──POST /jobs──► relay ──GET /jobs/next──► YOU
+                          ◄──GET /jobs/:id── relay ◄──POST /jobs/:id/result── YOU
+```
+
+## The loop — stay live for the whole session
+
+**Keep polling continuously until the user explicitly stops you.** This is the
+only thing that keeps the panel's LLM tab "available", so do not give up on idle.
+A long stretch of `204` responses is *normal and expected* — it just means no one
+has clicked Refine yet. Re-poll immediately every time; never treat repeated
+`204`s as a reason to stop. The relay reports the agent as "available" for ~120s
+after your last poll, so as long as you keep looping you stay live and the user
+never has to re-run `/refine live`.
+
+1. **Claim the next job (long-poll).** This call blocks up to ~25s, then returns.
+
+   ```bash
+   curl -s http://localhost:7331/jobs/next
+   ```
+
+   - HTTP `204` / empty body → no work yet. Immediately call it again.
+   - HTTP `200` with JSON → a job. Shape:
+
+     ```json
+     {
+       "id": "uuid",
+       "request": {
+         "label": "Resize + Color",
+         "selector": ".box-resize",
+         "mode": "llm",
+         "refineType": "small",
+         "timings": [
+           { "property": "width", "durationMs": 400, "delayMs": 0, "easing": "ease-out" },
+           { "property": "background", "durationMs": 400, "delayMs": 0, "easing": "ease-out" }
+         ]
+       }
+     }
+     ```
+
+   - `refineType` chooses what kinds of suggestions to make (it mirrors the
+     panel's two tabs):
+     - `"small"` (or missing) → **Small refinements**: nudge the existing
+       declarations toward the motion tokens (step 3a) **and**, when it's possible
+       and sensible, *also* suggest swapping the whole transition for a
+       transitions.dev recipe (step 3b).
+     - `"replace"` → **Replace transition**: suggest a whole-transition recipe
+       swap **only** (step 3b). Do **not** propose motion-token tweaks — skip
+       step 3a entirely.
+
+2. **(Optional) post progress** so the panel shows what you're doing:
+
+   ```bash
+   curl -s -X POST http://localhost:7331/jobs/<id>/status \
+     -H 'Content-Type: application/json' \
+     -d '{"message":"Matching to transitions.dev motion tokens…"}'
+   ```
+
+3. **Reason about the transition.** Read `transitions-dev` and apply its
+   `transitions refine` behaviour. Which steps you run depends on `refineType`:
+   - `refineType === "small"` → do step 3a **and** step 3b.
+   - `refineType === "replace"` → do step 3b **only** (skip 3a — no token tweaks).
+
+   First, infer each declaration's **usage** from `label` + `selector` (modal
+   close, dropdown open, tooltip, badge, resize, color/theme change…). Every
+   decision below keys off that usage — match on **intent, not the nearest
+   number**.
+
+   **3a. Motion-token tweaks (only for `refineType === "small"`).** Using
+   `## Motion tokens`:
+   - Pick the motion token that fits the usage — a modal close wants a fast exit;
+     a color/theme change can be slower; spring/back easings suit playful slides,
+     not opacity.
+   - Only propose a change where the current value actually differs.
+
+   **3b. Replace the whole transition (for `small` when sensible, always
+   considered for `replace`).** Judge whether this transition would be better off
+   re-built as one of the twenty-one transitions.dev recipes:
+   - The `transitions-dev` skill stays in the loop — run its `## Decision rules`
+     against the inferred usage to pick the **single** best-fit recipe, then open
+     that recipe's reference file (e.g. `06-modal.md`, `05-menu-dropdown.md`) to
+     read its real timings, easing, distance, scale, and blur.
+   - Only propose a replacement when it is **possible and sensible**: the current
+     declarations are clearly a hand-rolled version of a catalogued recipe, or are
+     missing the structure the usage calls for (e.g. an opacity-only "modal" that
+     should scale, a width tween that should be the card-resize recipe). If the
+     transition already *is* the right recipe, or no recipe genuinely fits, **do
+     not** force one.
+     - For `refineType === "small"`: skip the replace suggestion and let the 3a
+       token tweaks stand alone.
+     - For `refineType === "replace"`: there are no token tweaks to fall back on,
+       so return an **empty** `suggestions` array with a short `summary` saying the
+       transition already fits / no recipe applies.
+   - Emit at most **one** `kind: "replace"` suggestion per job. For `small` it sits
+     alongside the token tweaks (don't drop those); for `replace` it is the only
+     suggestion.
+   - Make its `patch` apply what the panel *can* apply live — the recipe's
+     recommended duration/easing for the property that already transitions (or
+     `"all"`). Name the recipe and its reference file in `title` + `reason` so the
+     user knows the structural parts (keyframes, extra properties, JS hooks) come
+     from running `transitions apply <recipe>` / pasting that reference file. Never
+     invent timings — quote the ones from the reference file.
+
+4. **Post the result** (this completes the job and renders cards in the panel):
+
+   ```bash
+   curl -s -X POST http://localhost:7331/jobs/<id>/result \
+     -H 'Content-Type: application/json' \
+     -d '{
+       "summary": "Tightened the resize and softened the color fade.",
+       "suggestions": [
+         {
+           "id": "width-duration",
+           "kind": "duration",
+           "property": "width",
+           "title": "Duration → Snappy (250ms)",
+           "from": "400ms",
+           "to": "250ms",
+           "patch": { "property": "width", "durationMs": 250 },
+           "reason": "A size change reads as direct manipulation — snappy is more responsive than 400ms."
+         }
+       ]
+     }'
+   ```
+
+   The example above is a `small` job (token tweaks). When a recipe genuinely
+   fits, include a `kind: "replace"` card — alongside the token tweaks for
+   `small`, or as the **only** suggestion for `replace`:
+
+   ```json
+   {
+     "id": "replace-card-resize",
+     "kind": "replace",
+     "property": "width",
+     "title": "Replace with Card resize",
+     "from": "hand-rolled width tween",
+     "to": "transitions.dev · Card resize",
+     "patch": { "property": "width", "durationMs": 250, "easing": "cubic-bezier(0.22, 1, 0.36, 1)" },
+     "reference": "transitions-dev/01-card-resize.md",
+     "reason": "This is a width tween on layout change — the Card resize recipe handles it properly. Apply nudges the live timing; paste 01-card-resize.md (run `transitions apply card-resize`) for the full recipe."
+   }
+   ```
+
+   If nothing should change, post `"suggestions": []` with a short `summary`.
+   If something goes wrong, report it instead:
+
+   ```bash
+   curl -s -X POST http://localhost:7331/jobs/<id>/error \
+     -H 'Content-Type: application/json' -d '{"message":"…"}'
+   ```
+
+5. **Go back to step 1.** Keep looping indefinitely. **Only stop when the user
+   explicitly tells you to** (e.g. "stop refine", "exit live"). Do not stop just
+   because it's been quiet — idle is the normal state between clicks. If you do
+   stop, tell them the LLM tab will go unavailable and how to restart
+   (`/refine live`).
+
+## Suggestion shape (must match the panel)
+
+Each suggestion object:
+
+| field | meaning |
+| --- | --- |
+| `id` | unique within the job (e.g. `"width-duration"`) — used to track "Applied" |
+| `kind` | `"duration"` \| `"delay"` \| `"easing"` for token tweaks, or `"replace"` for a whole-transition swap (drives the card label) |
+| `property` | the CSS property this targets, or `"all"` |
+| `title` | short label shown on the card |
+| `from` / `to` | human-readable before → after |
+| `patch` | **what actually gets applied** — `{ "property", "durationMs"?, "delayMs"?, "easing"? }`. Include only changed fields; `property` must match an input property (or `"all"`). For a `replace`, use the chosen recipe's recommended timing here so Apply still does something live. |
+| `reference` | *(replace only, optional)* the transitions.dev reference file the user should paste for the full recipe, e.g. `"transitions-dev/06-modal.md"`. |
+| `reason` | one sentence of *why*, in usage terms |
+
+The panel applies `patch` live in the browser via the property override. Values
+are not written to source files — the user copies the ones they keep.
+
+## Notes
+
+- Relay port: `http://localhost:7331` unless `REFINE_RELAY_PORT` was changed.
+- Only **LLM**-mode jobs reach you; **Deterministic**-mode jobs are answered by
+  the relay itself (nearest-token snapping) and never appear here. Whole-transition
+  **replace** suggestions are therefore LLM-only — the deterministic path can't
+  infer usage well enough to pick a recipe, so a Deterministic + "Replace
+  transition" job just returns an empty result pointing the user back to the Agent
+  tab.
+- A `replace` card's Apply only changes the live timing in the patch. The recipe's
+  structural parts (keyframes, extra properties, JS hooks) aren't applied in the
+  browser — that's why the card points the user at the reference file to paste.
+- The relay errors a waiting job after ~120s, so answer promptly once you claim
+  one. The long-poll itself returning `204` is normal — just poll again.

package/.agents/skills/transitions-dev/01-card-resize.md

@@ -0,0 +1,53 @@
+# Card resize
+
+## When to use
+
+Tweening a container's width or height when its layout state changes (compact ↔ expanded card, collapsing panel, list row toggling extra detail). Pure CSS — no JS required beyond the class toggle that drives the size change.
+
+## HTML usage
+
+```html
+<div class="t-resize">…</div>
+```
+
+Put `.t-resize` on any element and change its width/height
+(directly, or via a state class such as `.is-small`). The
+transition will tween the two sizes.
+
+## Tunable variables
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `--resize-dur` | `300ms` | sourced from `--p4-dur` |
+| `--resize-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` | sourced from `--p4-ease` |
+
+The `:root` defaults below match the live tuning on [transitions.dev](https://transitions.dev). Drop them into your global stylesheet once — every transition in this skill reads from semantic names like these, so multiple transitions can share a single `:root` block.
+
+```css
+:root {
+  --resize-dur: 300ms;
+  --resize-ease: cubic-bezier(0.22, 1, 0.36, 1);
+}
+```
+
+## CSS
+
+```css
+.t-resize {
+  transition:
+    width  var(--resize-dur) var(--resize-ease),
+    height var(--resize-dur) var(--resize-ease);
+  will-change: width, height;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-resize { transition: none !important; }
+}
+```
+
+The `@media (prefers-reduced-motion: reduce)` guard at the bottom of the snippet is required — keep it. It zeroes the transition for users who have asked for less motion at the OS level.
+
+## JavaScript orchestration
+
+None — pure CSS. Toggle the documented HTML attributes or class names from whatever already drives state in your app.
+

package/.agents/skills/transitions-dev/02-number-pop-in.md

@@ -0,0 +1,119 @@
+# Number pop-in
+
+## When to use
+
+Counters, prices, balances, or any number that updates and should re-enter from a direction with blur. Each character animates independently and the last two digits stagger so decimals feel alive without looking chaotic.
+
+## HTML usage
+
+```html
+<span class="t-digit-group is-animating">
+  <span class="t-digit">1</span>
+  <span class="t-digit">2</span>
+  <span class="t-digit" data-stagger="1">.</span>
+  <span class="t-digit" data-stagger="2">3</span>
+</span>
+```
+
+Replay:
+  - Remove `.is-animating`, re-render digits (or swap text),
+    force a reflow, then re-add `.is-animating`.
+  - Use data-stagger="1", "2", … to delay individual
+    digits by `n * var(--digit-stagger)`.
+
+Direction:
+  --digit-dir-x / --digit-dir-y are unit-less multipliers
+  (e.g. 1, -1, 0) applied to --digit-distance.
+
+## Tunable variables
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `--digit-dur` | `500ms` | sourced from `--p9-dur` |
+| `--digit-distance` | `8px` | sourced from `--p9-distance` |
+| `--digit-stagger` | `70ms` | sourced from `--p9-stagger` |
+| `--digit-blur` | `2px` | sourced from `--p9-blur` |
+| `--digit-ease` | `cubic-bezier(0.34, 1.45, 0.64, 1)` | sourced from `--p9-ease` |
+| `--digit-dir-x` | `0` | sourced from `--p9-dir-x` |
+| `--digit-dir-y` | `1` | sourced from `--p9-dir-y` |
+
+The `:root` defaults below match the live tuning on [transitions.dev](https://transitions.dev). Drop them into your global stylesheet once — every transition in this skill reads from semantic names like these, so multiple transitions can share a single `:root` block.
+
+```css
+:root {
+  --digit-dur: 500ms;
+  --digit-distance: 8px;
+  --digit-stagger: 70ms;
+  --digit-blur: 2px;
+  --digit-ease: cubic-bezier(0.34, 1.45, 0.64, 1);
+  --digit-dir-x: 0;
+  --digit-dir-y: 1;
+}
+```
+
+## CSS
+
+```css
+@keyframes t-digit-pop-in {
+  0%   {
+    transform: translate(
+      calc(var(--digit-distance) * var(--digit-dir-x)),
+      calc(var(--digit-distance) * var(--digit-dir-y))
+    );
+    opacity: 0;
+    filter: blur(var(--digit-blur));
+  }
+  100% { transform: translate(0, 0); opacity: 1; filter: blur(0); }
+}
+
+.t-digit-group {
+  display: inline-flex;
+  align-items: baseline;
+}
+.t-digit {
+  display: inline-block;
+  will-change: transform, opacity, filter;
+}
+.t-digit-group.is-animating .t-digit {
+  animation: t-digit-pop-in var(--digit-dur) var(--digit-ease) both;
+}
+.t-digit-group.is-animating .t-digit[data-stagger="1"] {
+  animation-delay: var(--digit-stagger);
+}
+.t-digit-group.is-animating .t-digit[data-stagger="2"] {
+  animation-delay: calc(var(--digit-stagger) * 2);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-digit-group .t-digit { animation: none !important; }
+}
+```
+
+The `@media (prefers-reduced-motion: reduce)` guard at the bottom of the snippet is required — keep it. It zeroes the transition for users who have asked for less motion at the OS level.
+
+## JavaScript orchestration
+
+```js
+// Replay the digit pop-in: remove .is-animating, swap the digit spans,
+// force a reflow, then re-add .is-animating. Mark the last two digits
+// with data-stagger="1" / "2" so they ride in 1× / 2× --digit-stagger
+// behind the leading digits.
+const group = document.querySelector(".t-digit-group");
+
+function setDigits(str) {
+  group.classList.remove("is-animating");
+  group.replaceChildren();
+  const chars = str.split("");
+  chars.forEach((ch, i) => {
+    const span = document.createElement("span");
+    span.className = "t-digit";
+    span.textContent = ch;
+    if (i === chars.length - 2) span.dataset.stagger = "1";
+    else if (i === chars.length - 1) span.dataset.stagger = "2";
+    group.appendChild(span);
+  });
+  void group.offsetHeight; // force reflow
+  group.classList.add("is-animating");
+}
+```
+

package/.agents/skills/transitions-dev/03-notification-badge.md

@@ -0,0 +1,110 @@
+# Notification badge
+
+## When to use
+
+A small badge appearing on top of a trigger (bell, inbox, button). Slides in diagonally and pops the dot independently of the trigger so the trigger itself never moves.
+
+## HTML usage
+
+```html
+<!-- Place .t-badge inside your trigger (bell icon, button, etc.). -->
+<!-- The trigger must be position: relative so .t-badge can anchor to it. -->
+<button class="your-trigger" style="position: relative">
+  <!-- your icon / trigger contents -->
+  <span class="t-badge" data-open="false">
+    <span class="t-badge-dot">1</span>
+  </span>
+</button>
+```
+
+State: toggle data-open="true" / "false" on .t-badge.
+Only the badge slides + pops — the trigger itself stays put.
+
+## Tunable variables
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `--badge-slide-dur` | `260ms` | sourced from `--p1-pos-open-dur` |
+| `--badge-pop-dur` | `500ms` | sourced from `--p1-scale-open-dur` |
+| `--badge-pop-close-dur` | `180ms` | sourced from `--p1-scale-close-dur` |
+| `--badge-fade-dur` | `400ms` | sourced from `--p1-opacity-open-dur` |
+| `--badge-fade-close-dur` | `180ms` | sourced from `--p1-opacity-close-dur` |
+| `--badge-blur` | `2px` | sourced from `--p1-blur` |
+| `--badge-offset-x` | `-8.2px` | sourced from `--p1-distance-x` |
+| `--badge-offset-y` | `12.4px` | sourced from `--p1-distance-y` |
+| `--badge-slide-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` | sourced from `--p1-ease-pos-open` |
+| `--badge-pop-ease` | `cubic-bezier(0.34, 1.36, 0.64, 1)` | sourced from `--p1-ease-scale-open` |
+| `--badge-close-ease` | `cubic-bezier(0.4, 0, 0.2, 1)` | sourced from `--p1-ease-close` |
+
+The `:root` defaults below match the live tuning on [transitions.dev](https://transitions.dev). Drop them into your global stylesheet once — every transition in this skill reads from semantic names like these, so multiple transitions can share a single `:root` block.
+
+```css
+:root {
+  --badge-slide-dur: 260ms;
+  --badge-pop-dur: 500ms;
+  --badge-pop-close-dur: 180ms;
+  --badge-fade-dur: 400ms;
+  --badge-fade-close-dur: 180ms;
+  --badge-blur: 2px;
+  --badge-offset-x: -8.2px;
+  --badge-offset-y: 12.4px;
+  --badge-slide-ease: cubic-bezier(0.22, 1, 0.36, 1);
+  --badge-pop-ease: cubic-bezier(0.34, 1.36, 0.64, 1);
+  --badge-close-ease: cubic-bezier(0.4, 0, 0.2, 1);
+}
+```
+
+## CSS
+
+```css
+@keyframes t-badge-slide-in {
+  from { transform: translate(var(--badge-offset-x), var(--badge-offset-y)); }
+  to   { transform: translate(0, 0); }
+}
+
+/* .t-badge is the absolutely-positioned wrapper for the dot.
+   Adjust top/right (or left/bottom) to anchor it on your trigger. */
+.t-badge {
+  position: absolute;
+  top: -6px;
+  right: -8px;
+  pointer-events: none;
+  will-change: transform;
+}
+.t-badge[data-open="true"] {
+  animation: t-badge-slide-in var(--badge-slide-dur) var(--badge-slide-ease);
+}
+
+.t-badge-dot {
+  display: block;
+  transform-origin: center;
+  transform: scale(1);
+  opacity: 1;
+  filter: blur(0);
+  transition:
+    transform var(--badge-pop-dur)  var(--badge-pop-ease),
+    opacity   var(--badge-fade-dur) var(--badge-pop-ease),
+    filter    var(--badge-pop-dur)  var(--badge-pop-ease);
+  will-change: transform, opacity, filter;
+}
+.t-badge[data-open="false"] .t-badge-dot {
+  transform: scale(0);
+  opacity: 0;
+  filter: blur(var(--badge-blur));
+  transition:
+    transform var(--badge-pop-close-dur)  var(--badge-close-ease),
+    opacity   var(--badge-fade-close-dur) var(--badge-close-ease),
+    filter    var(--badge-pop-close-dur)  var(--badge-close-ease);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-badge, .t-badge-dot { animation: none !important; transition: none !important; }
+}
+```
+
+The `@media (prefers-reduced-motion: reduce)` guard at the bottom of the snippet is required — keep it. It zeroes the transition for users who have asked for less motion at the OS level.
+
+## JavaScript orchestration
+
+None — pure CSS. Toggle the documented HTML attributes or class names from whatever already drives state in your app.
+

package/.agents/skills/transitions-dev/04-text-states-swap.md

@@ -0,0 +1,97 @@
+# Text states swap
+
+## When to use
+
+Swapping the text of a status indicator in place — "Processing…" → "Done", "Save" → "Saved". The old text exits up with blur, the new text enters from below.
+
+## HTML usage
+
+```html
+<span class="t-text-swap">Processing…</span>
+```
+
+Driven by JS (three-phase sequence):
+  1. Add `.is-exit`  -> old text slides up + blurs + fades.
+  2. After --text-swap-dur: change textContent, then add
+     `.is-enter-start` (jumps to below, no transition).
+  3. Force reflow, remove `.is-enter-start` so the new text
+     animates back to 0 with the default transition.
+
+## Tunable variables
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `--text-swap-dur` | `150ms` | sourced from `--p6-dur` |
+| `--text-swap-translate-y` | `4px` | sourced from `--p6-translate-y` |
+| `--text-swap-blur` | `2px` | sourced from `--p6-blur` |
+| `--text-swap-ease` | `ease-in-out` | sourced from `--p6-ease` |
+
+The `:root` defaults below match the live tuning on [transitions.dev](https://transitions.dev). Drop them into your global stylesheet once — every transition in this skill reads from semantic names like these, so multiple transitions can share a single `:root` block.
+
+```css
+:root {
+  --text-swap-dur: 150ms;
+  --text-swap-translate-y: 4px;
+  --text-swap-blur: 2px;
+  --text-swap-ease: ease-in-out;
+}
+```
+
+## CSS
+
+```css
+.t-text-swap {
+  display: inline-block;
+  transform: translateY(0);
+  filter: blur(0);
+  opacity: 1;
+  transition:
+    transform var(--text-swap-dur) var(--text-swap-ease),
+    filter    var(--text-swap-dur) var(--text-swap-ease),
+    opacity   var(--text-swap-dur) var(--text-swap-ease);
+  will-change: transform, filter, opacity;
+}
+.t-text-swap.is-exit {
+  transform: translateY(calc(var(--text-swap-translate-y) * -1));
+  filter: blur(var(--text-swap-blur));
+  opacity: 0;
+}
+.t-text-swap.is-enter-start {
+  transform: translateY(var(--text-swap-translate-y));
+  filter: blur(var(--text-swap-blur));
+  opacity: 0;
+  transition: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-text-swap { transition: none !important; }
+}
+```
+
+The `@media (prefers-reduced-motion: reduce)` guard at the bottom of the snippet is required — keep it. It zeroes the transition for users who have asked for less motion at the OS level.
+
+## JavaScript orchestration
+
+```js
+// Three-phase text swap:
+//   1. Add .is-exit              — old text exits up with blur.
+//   2. After --text-swap-dur, swap textContent and add .is-enter-start
+//      (jumps to "below, no transition"), force a reflow.
+//   3. Remove .is-enter-start    — new text animates back to rest.
+const el = document.querySelector(".t-text-swap");
+const dur = parseFloat(
+  getComputedStyle(document.documentElement).getPropertyValue("--text-swap-dur")
+) || 200;
+
+function swapText(next) {
+  el.classList.add("is-exit");
+  setTimeout(() => {
+    el.textContent = next;
+    el.classList.remove("is-exit");
+    el.classList.add("is-enter-start");
+    void el.offsetHeight; // force reflow so the next change transitions
+    el.classList.remove("is-enter-start");
+  }, dur);
+}
+```
+

package/.agents/skills/transitions-dev/05-menu-dropdown.md

@@ -0,0 +1,105 @@
+# Menu dropdown
+
+## When to use
+
+Contextual menus, dropdowns, popovers — anything that opens from a trigger and should visually grow from that trigger's position. Origin-aware via `data-origin` (top-left, top-center, top-right, bottom-*).
+
+## HTML usage
+
+```html
+<div class="t-dropdown" data-origin="top-center">
+  <!-- your menu contents -->
+</div>
+```
+
+State:
+  - Add `.is-open` to show.
+  - On close, swap `.is-open` for `.is-closing`, then remove
+    `.is-closing` after --dropdown-close-dur.
+
+data-origin values: top-left | top-center | top-right |
+                    bottom-left | bottom-center | bottom-right.
+
+## Tunable variables
+
+| Variable | Default | Notes |
+| --- | --- | --- |
+| `--dropdown-open-dur` | `250ms` | sourced from `--p2-open-dur` |
+| `--dropdown-close-dur` | `150ms` | sourced from `--p2-close-dur` |
+| `--dropdown-pre-scale` | `0.97` | sourced from `--p2-pre-scale` |
+| `--dropdown-closing-scale` | `0.99` | sourced from `--p2-closing-scale` |
+| `--dropdown-ease` | `cubic-bezier(0.22, 1, 0.36, 1)` | sourced from `--p2-ease` |
+
+The `:root` defaults below match the live tuning on [transitions.dev](https://transitions.dev). Drop them into your global stylesheet once — every transition in this skill reads from semantic names like these, so multiple transitions can share a single `:root` block.
+
+```css
+:root {
+  --dropdown-open-dur: 250ms;
+  --dropdown-close-dur: 150ms;
+  --dropdown-pre-scale: 0.97;
+  --dropdown-closing-scale: 0.99;
+  --dropdown-ease: cubic-bezier(0.22, 1, 0.36, 1);
+}
+```
+
+## CSS
+
+```css
+.t-dropdown {
+  transform-origin: top left;
+  transform: scale(var(--dropdown-pre-scale));
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    transform var(--dropdown-open-dur) var(--dropdown-ease),
+    opacity   var(--dropdown-open-dur) var(--dropdown-ease);
+  will-change: transform, opacity;
+}
+.t-dropdown[data-origin="top-right"]     { transform-origin: top right; }
+.t-dropdown[data-origin="top-center"]    { transform-origin: top center; }
+.t-dropdown[data-origin="bottom-left"]   { transform-origin: bottom left; }
+.t-dropdown[data-origin="bottom-center"] { transform-origin: bottom center; }
+.t-dropdown[data-origin="bottom-right"]  { transform-origin: bottom right; }
+
+.t-dropdown.is-open {
+  transform: scale(1);
+  opacity: 1;
+  pointer-events: auto;
+}
+.t-dropdown.is-closing {
+  transform: scale(var(--dropdown-closing-scale));
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    transform var(--dropdown-close-dur) var(--dropdown-ease),
+    opacity   var(--dropdown-close-dur) var(--dropdown-ease);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-dropdown { transition: none !important; }
+}
+```
+
+The `@media (prefers-reduced-motion: reduce)` guard at the bottom of the snippet is required — keep it. It zeroes the transition for users who have asked for less motion at the OS level.
+
+## JavaScript orchestration
+
+```js
+// Toggle .is-open / .is-closing with a setTimeout cleanup so the closing
+// scale animates before the element resets to its pre-open rest state.
+const dropdown = document.querySelector(".t-dropdown");
+const closeMs = parseFloat(
+  getComputedStyle(document.documentElement).getPropertyValue("--dropdown-close-dur")
+) || 150;
+
+function openDropdown() {
+  dropdown.classList.remove("is-closing");
+  dropdown.classList.add("is-open");
+}
+function closeDropdown() {
+  dropdown.classList.remove("is-open");
+  dropdown.classList.add("is-closing");
+  setTimeout(() => dropdown.classList.remove("is-closing"), closeMs);
+}
+```
+