@ericrisco/rsc 1.0.26 → 1.0.28

package/scripts/lib/spec-gate.js

@@ -0,0 +1,122 @@
+// The exit gate of the `specify` phase, as a binary instead of a feeling.
+//
+// "Stop when the WHAT and WHY are complete enough to plan against" cannot tell done from not-done,
+// so the phase closed whenever the agent felt closed — with the write/review/approve steps visible
+// the whole time, pulling attention toward being finished. This checks the artifact instead: every
+// template section carries content or an explicit open point.
+//
+// What it does NOT check is returned in `unchecked`, on purpose. Detecting an unmarked assumption is
+// the problem `specify` exists to solve, not something a parser can do, and a gate that implies
+// otherwise is worse than one that admits its edge.
+
+// The four states a point can be in. Order is the table's order in the skill body.
+export const OPEN_POINT_TYPES = [
+  'pregunta abierta', // formulable now, unanswered → clarify asks it
+  'suposición tomada', // we decided, with the basis written → clarify validates it
+  'decisión diferida', // sharp, out of this cycle on purpose → clarify leaves it
+  'área no formulable', // known to be coming, not yet sharp → clarify notes it
+];
+
+// The corpus is Spanish, the template is English, and both carry drifting parentheticals
+// ("Objetivos (resultado)", "Criterios de aceptación (binarios)"). Matching literal strings would
+// be useless, so each family is a set of normalised prefixes.
+const FAMILIES = {
+  problem: ['problema & por que', 'problema y por que', 'problem & why'],
+  goals: ['objetivos', 'goals'],
+  nongoals: ['no-objetivos', 'no objetivos', 'non-goals'],
+  users: ['usuarios & contexto', 'usuarios y contexto', 'users & context'],
+  behaviour: ['comportamiento', 'behaviour', 'behavior'],
+  acceptance: ['criterios de aceptacion', 'acceptance criteria'],
+  open: ['puntos a clarificar', 'puntos de clarify', 'puntos que siguen abiertos', 'points to clarify'],
+};
+
+const UNCHECKED = [
+  'que ninguna sección contenga una suposición sin marcar (no es detectable por máquina; es el juicio que la fase existe para ejercer)',
+  'que el contenido de cada sección sea correcto, y no sólo presente',
+  'que los criterios de aceptación sean de verdad binarios',
+];
+
+function fold(s) {
+  return s
+    .normalize('NFD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .trim();
+}
+
+function familyOf(heading) {
+  const h = fold(heading);
+  for (const [family, prefixes] of Object.entries(FAMILIES)) {
+    if (prefixes.some((p) => h.startsWith(p))) return family;
+  }
+  return null;
+}
+
+// A heading with nothing under it is not a filled section. Neither is one holding only the
+// template's own italic/angle-bracket guidance, which is what a hurried pass leaves behind.
+function isSubstantive(line) {
+  const t = line.trim();
+  if (!t) return false;
+  if (/^<.*>$/.test(t)) return false; // <guidance from the template>
+  if (/^\*[^*].*\*$/.test(t) && t.length < 200) return false; // *italic guidance*
+  if (/^(-|\*)\s*$/.test(t)) return false; // an empty bullet
+  return true;
+}
+
+function parseOpenPoints(lines) {
+  const points = [];
+  for (const line of lines) {
+    const m = line.match(/^\s*[-*]\s+(?:\[[ x]\]\s*)?(.*)$/);
+    if (!m || !m[1].trim()) continue;
+    const body = m[1];
+    const declared = OPEN_POINT_TYPES.find((t) => {
+      const re = new RegExp(`^\\*\\*\\s*${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\*\\*`, 'i');
+      return re.test(fold(body)) || re.test(body);
+    });
+    points.push({
+      type: declared || OPEN_POINT_TYPES[0], // the costliest default: treat it as a real question
+      typed: Boolean(declared),
+      text: body.trim(),
+    });
+  }
+  return points;
+}
+
+/**
+ * @param {string} markdown a written spec file
+ * @returns {{ok: boolean, missing: string[], empty: string[],
+ *            openPoints: Array<{type: string, typed: boolean, text: string}>,
+ *            untyped: string[], unchecked: string[]}}
+ */
+export function specCompleteness(markdown) {
+  const lines = String(markdown ?? '').split('\n');
+  const sections = new Map(); // family -> body lines
+
+  let current = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+(.*)$/);
+    if (h) {
+      const fam = familyOf(h[1]);
+      current = fam;
+      if (fam && !sections.has(fam)) sections.set(fam, []);
+      continue;
+    }
+    if (current && sections.has(current)) sections.get(current).push(line);
+  }
+
+  const families = Object.keys(FAMILIES);
+  const missing = families.filter((f) => !sections.has(f));
+  const empty = families.filter((f) => sections.has(f) && !sections.get(f).some(isSubstantive));
+
+  const openPoints = sections.has('open') ? parseOpenPoints(sections.get('open')) : [];
+  const untyped = openPoints.filter((p) => !p.typed).map((p) => p.text);
+
+  return {
+    ok: missing.length === 0 && empty.length === 0,
+    missing,
+    empty,
+    openPoints,
+    untyped,
+    unchecked: UNCHECKED,
+  };
+}

package/scripts/spec-gate.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Runs the `specify` exit gate over written specs. Report-only: it never edits a spec.
+//
+// Not wired into `prepublishOnly`, and that is deliberate: specs live under 02-DOCS, which is never
+// tracked (principle 9), so a publish gate depending on them would fail in any clean clone. This is
+// the phase's own instrument, and the author's.
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { specCompleteness } from './lib/spec-gate.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_DIR = join(ROOT, '02-DOCS', 'wiki', 'sdd', 'specs');
+
+function defaultTargets() {
+  try {
+    return readdirSync(DEFAULT_DIR)
+      .filter((f) => f.endsWith('.md') && !f.endsWith('.plan.md'))
+      .map((f) => join(DEFAULT_DIR, f));
+  } catch {
+    return [];
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const targets = args.length ? args : defaultTargets();
+  if (!targets.length) {
+    console.log('no specs found — pass a path, or write one to 02-DOCS/wiki/sdd/specs/');
+    return;
+  }
+
+  let failed = 0;
+  for (const path of targets) {
+    const r = specCompleteness(readFileSync(path, 'utf8'));
+    const name = basename(path);
+    if (r.ok) {
+      const typed = r.openPoints.length - r.untyped.length;
+      console.log(`PASS  ${name} — ${r.openPoints.length} open point(s), ${typed} typed`);
+      if (r.untyped.length) {
+        console.log(`      untyped (treated as open questions): ${r.untyped.length}`);
+      }
+    } else {
+      failed += 1;
+      console.log(`FAIL  ${name}`);
+      if (r.missing.length) console.log(`      missing section(s): ${r.missing.join(', ')}`);
+      if (r.empty.length) console.log(`      section(s) with no content: ${r.empty.join(', ')}`);
+    }
+  }
+
+  // A green here is narrower than the rule it enforces, so it says so every run rather than
+  // letting the reader assume the gate covered more than it did.
+  console.log(`\n${targets.length - failed}/${targets.length} pass. Not checked by this gate:`);
+  for (const u of specCompleteness('').unchecked) console.log(`  - ${u}`);
+  if (failed) process.exit(1);
+}
+
+main();

package/skills/animate/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: animate
+description: "Build a web animation: whether it should animate at all, the purpose, the tool, the properties, the easing curve, the duration, interruption and exit. Writes the CSS or Motion code for dropdowns, modals, toasts, tooltips, accordions, press feedback, stagger and scroll reveals. Use to animate something or make a component feel alive."
+tags: [motion, animation, css, transitions, ui]
+recommends: [review-animations, pick-ui-library, apple-design]
+profiles: [full]
+origin: emilkowalski (MIT, adapted)
+---
+
+# Building Animations
+
+> **SDD gate.** If this fired on a **new, non-trivial feature or behaviour change** and there is
+> **no approved spec + plan** under `02-DOCS/wiki/sdd/`, hand off to `../specify/SKILL.md` first —
+> it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is
+> approved. Build straight from here only for a genuinely one-line / low-risk change, or a bug fix
+> restoring intended behaviour. Method: `../sdd/SKILL.md`.
+
+**Hand-offs.** The **visual system** — palette, type scale, spacing, brand grounding, landing
+composition — is `../design/SKILL.md`'s; this skill only sets motion. **React Native / Expo** motion
+is `../animate-expo/SKILL.md`'s: no hover, two runtimes, gestures as the baseline. **Gesture physics**
+— velocity handoff, momentum projection, rubber-banding, translucent materials — is
+`../apple-design/SKILL.md`'s. Reviewing motion someone else wrote is `../review-animations/SKILL.md`'s.
+The countable half of the bar below is executable: `../review-animations/scripts/verify.sh` flags
+`transition: all`, a `scale(0)` entrance, `ease-in` on UI, a centered popover origin, and motion with
+no reduced-motion guard. Run it before you claim the animation is done.
+
+A construction skill. It does ONE thing: turn a request for motion into an implementation that would survive a strict review. It does not audit a codebase (that's `improve-animations`), critique a diff (that's `review-animations`), hunt for places that could animate (that's `find-animation-opportunities`), or build for React Native (that's `animate-expo`).
+
+## Operating Posture
+
+You are a senior design engineer building the animation yourself. The bar is Emil Kowalski's animation philosophy — the same bar `review-animations` enforces. Write it so it passes that review the first time.
+
+Two failure modes, and the first is worse:
+
+1. **Animating something that shouldn't animate.** The gate below exists to produce zero lines of code sometimes. That's a success, not a dodge.
+2. **Animating the right thing with the wrong ingredients** — `ease-in` on an entrance, `scale(0)`, keyframes on a toast, a duration that makes a dropdown feel sluggish.
+
+Never present motion options as a menu. Make the call, state the reasoning in one line, write the code.
+
+## Hard Rules
+
+1. **Run the sequence in order.** Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
+2. **No approximated values.** Every curve, duration, and spring config comes from the tables below. Never invent `cubic-bezier(0.4, 0, 0.2, 1)` because it looks familiar.
+3. **Extend the codebase's tokens, don't fork them.** If `--ease-out` or a duration scale already exists, use it. Adding a parallel system is a defect.
+4. **Reduced motion and hover gating ship with the animation**, not as a follow-up.
+5. **Cheapest tool that works.** Don't install a motion library for a fade.
+
+## The Build Sequence
+
+### 1. Should this animate at all?
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day (keyboard shortcuts, command palette toggle) | **No animation. Ever.** Stop here. |
+| Tens of times/day (hover effects, list navigation) | Near-imperceptible only — fast and subtle, or nothing |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare / first-time (onboarding, success, celebration) | The delight budget lives here |
+
+**Keyboard-initiated actions are a disqualifier, not a judgment call.** Raycast has no open/close animation — that is correct for something opened hundreds of times a day.
+
+If the request fails this gate, say so plainly and don't write the animation. Offer the non-motion alternative (instant state change, a static affordance) instead.
+
+### 2. What is the purpose?
+
+Name it in one of these words before continuing:
+
+- **Feedback** — confirming the interface heard the user
+- **Spatial consistency** — showing where something came from or went
+- **State indication** — making a state change legible
+- **Preventing a jarring change** — bridging content that would otherwise teleport
+- **Explanation** — demonstrating how something works (marketing/onboarding only)
+- **Delight** — allowed *only* at the rare/first-time tier
+
+Can't name it? Don't build it. "It looks cool" on a frequently-seen element is a reason to stop.
+
+Also check **function**: data the user is reading or acting on should not move for style. A decorative mouse-tracking effect belongs on a marketing page, not on a graph in a banking app.
+
+### 3. Pick the tool — cheapest that works
+
+Walk down; stop at the first that fits.
+
+| Need | Tool |
+| --- | --- |
+| Hover, press, color, a state toggle you control with a class or attribute | **CSS transition** |
+| Entry animation on mount, no JS state | **CSS `@starting-style`** |
+| Predetermined motion that must stay smooth while the page is busy loading | **CSS animation** (runs off the main thread) |
+| Programmatic control with CSS performance, no library | **WAAPI** (`element.animate()`) |
+| Springs, layout animations, exit animations, gesture-driven values | **Motion** (`motion.dev`) |
+
+CSS animations beat JS under load — they run off the main thread, while `requestAnimationFrame`-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.
+
+If the task needs a *component* rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and invoke `pick-ui-library`. Hand-rolling those is how you end up with a `<div>` dropdown and no focus management.
+
+### 4. Pick the properties
+
+- **`transform` and `opacity` only.** They skip layout and paint and run on the GPU. `width`/`height`/`margin`/`padding`/`top`/`left` trigger all three. (`clip-path` is the sanctioned fourth — see [references/recipes.md](references/recipes.md). `height` is tolerated only for accordions, where there's no transform equivalent.)
+- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
+- **`transform-origin` at the trigger** for popovers, dropdowns, menus, tooltips — `var(--transform-origin)` in Base UI. **Modals are exempt**; they're not anchored to a trigger, so they stay centered.
+- **Percentages in `translate()`** are relative to the element's own size — `translateY(100%)` moves by its own height whatever the content. Prefer over hardcoded pixels.
+- **In Motion, use the full transform string.** `x`/`y`/`scale` shorthands are not hardware-accelerated and drop frames under load:
+
+```jsx
+<motion.div animate={{ x: 100 }} />                          // drops frames under load
+<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
+```
+
+- **Never drive a child's transform from a CSS variable on the parent** — it recalculates styles for every child. Set `transform` on the element directly.
+
+### 5. Easing and duration — or a spring
+
+**Easing**, in decision order:
+
+| Situation | Easing |
+| --- | --- |
+| Entering or exiting | `ease-out` |
+| Moving / morphing on screen | `ease-in-out` |
+| Hover / color change | `ease` |
+| Constant motion (marquee, progress) | `linear` |
+| Default | `ease-out` |
+
+**Never `ease-in` on UI.** It starts slow, delaying the exact moment the user is watching. `ease-out` at 200ms *feels* faster than `ease-in` at 200ms.
+
+Built-in CSS easings are too weak. Use these:
+
+```css
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
+--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
+```
+
+Need a curve that isn't here? Take it from [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/). Don't hand-roll one.
+
+**Duration:**
+
+| Element | Duration |
+| --- | --- |
+| Button press feedback | 100–160ms |
+| Tooltips, small popovers | 125–200ms |
+| Dropdowns, selects | 150–250ms |
+| Modals, drawers | 200–500ms |
+| Marketing / explanatory | Can be longer |
+
+**UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one.
+
+**Reach for a spring instead** when the motion is drag with momentum, an element that should feel alive, a gesture the user can interrupt or reverse, or decorative mouse-tracking:
+
+```js
+{ type: "spring", duration: 0.5, bounce: 0.2 }        // Apple-style — easier to reason about
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // traditional physics — more control
+```
+
+Keep bounce at 0.1–0.3, and avoid bounce in most UI — reserve it for drag-to-dismiss and playful interactions.
+
+### 6. Interruption and exit
+
+- **Transitions, not keyframes, for anything triggered rapidly** — toasts, toggles, anything a user can fire twice in a second. Transitions retarget from the current value; keyframes restart from zero.
+- **Springs for gestures**, because they carry velocity through an interruption.
+- **Exit the way it entered.** A toast that slides in from the bottom leaves through the bottom. Symmetric paths are what make swipe-to-dismiss feel obvious.
+- **Asymmetric timing where the user is deciding.** Slow on the deliberate phase (a hold-to-confirm press: 2s linear), snappy on the system response (release: 200ms ease-out).
+
+### 7. Reduced motion and pointer gating
+
+Ships with the animation, every time.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
+}
+```
+
+```jsx
+const reduce = useReducedMotion();
+const closedX = reduce ? 0 : '-100%';
+```
+
+Reduced motion means **fewer and gentler** animations, not zero — keep transitions that aid comprehension, remove movement and position changes.
+
+## Recipes
+
+For ready-to-build implementations of the common cases — button press, dropdown, tooltip, modal, drawer, toast, accordion, stagger, hold-to-confirm, tab indicator, scroll reveal, drag-to-dismiss — see [references/recipes.md](references/recipes.md). Load it whenever the request matches one of those components; start from the recipe rather than from a blank file.
+
+## Never Ship
+
+Self-check before you finish. Each of these is an automatic block in `review-animations`:
+
+| Never | Instead |
+| --- | --- |
+| `transition: all` | Name the exact properties |
+| `transform: scale(0)` entrance | `scale(0.95)` + `opacity: 0` |
+| `ease-in` on a UI element | `ease-out` or a strong custom curve |
+| Built-in `ease-out` on a deliberate animation | `cubic-bezier(0.23, 1, 0.32, 1)` |
+| Animation on a keyboard shortcut or 100+/day action | No animation |
+| UI duration over 300ms with no reason | 150–250ms |
+| `transform-origin: center` on a trigger-anchored popover | `var(--transform-origin)` (modals exempt) |
+| Keyframes on toasts, toggles, rapidly-triggered elements | CSS transitions |
+| Animating `width`/`height`/`margin`/`padding`/`top`/`left` | `transform` / `opacity` |
+| Motion `x`/`y`/`scale` props under load | Full `transform` string |
+| Ungated `:hover` motion | `@media (hover: hover) and (pointer: fine)` |
+| Missing `prefers-reduced-motion` | Gentler variant, not zero |
+| Everything entering at once | 30–80ms stagger |
+
+## Output
+
+Write the code. Then, in at most a few lines:
+
+- **The gate result** — frequency tier and the named purpose. If something in the request was rejected, say which and why.
+- **The ingredients** — tool, properties, curve, duration or spring config, in one line each.
+- **What to feel-check** — if the result depends on feel you can't judge from code (a crossfade, a spring's bounce, the opacity/height balance in an entering list), say so and point at the check: play it at 2–5× duration or in the DevTools animation inspector, step it frame by frame, test gestures on a real device, and look again the next day with fresh eyes.
+
+Don't pad this into a report. The code is the deliverable.
+
+## Tone
+
+Opinionated and brief. When the honest answer is "this shouldn't animate," give it — that answer is the reason this skill exists. When feel genuinely can't be settled from code, say so instead of guessing at a value.
+
+---
+
+## Credit
+
+Adapted for the rsc catalog from **[emilkowalski/skills](https://github.com/emilkowalski/skills)**
+(MIT, commit `d23d7f8`) by Emil Kowalski — the design-engineering and animation philosophy behind
+[Sonner](https://sonner.emilkowal.ski), [Vaul](https://vaul.emilkowal.ski) and
+[animations.dev](https://animations.dev). The craft bar here is his; the routing, gates and evals
+that make it an rsc skill are not. Nothing in this body is a substitute for his course.

package/skills/animate/evals/cases.yaml

@@ -0,0 +1,36 @@
+skill: animate
+
+should_trigger:
+  - prompt: "Animate this dropdown so it opens smoothly — pick the right easing and duration."
+    why: "A build request for a named component's motion: the skill's core use case."
+  - prompt: "Add a transition when the modal opens and closes so it doesn't just pop in."
+    why: "Building an enter/exit animation, including the exit path the skill insists is symmetric."
+  - prompt: "Make this button feel responsive when you press it."
+    why: "Press feedback is a recipe in this skill; 'feel responsive' is its vocabulary."
+  - prompt: "I want a hold-to-delete button where the fill animates while you hold it."
+    why: "Hold-to-confirm is an explicit recipe (clip-path, 2s linear press, snappy release)."
+  - prompt: "Add motion to this toast so it slides in from the bottom and can be swiped away."
+    why: "Toast motion with a gesture: transitions over keyframes, symmetric exit, velocity dismissal."
+  - prompt: "Make this list of cards feel alive when the page loads."
+    why: "'Feel alive' is named in the description; the answer is a stagger, or a refusal if the frequency tier is wrong."
+
+should_not_trigger:
+  - prompt: "Review the animations in this pull request and tell me what's wrong with them."
+    route_to: "review-animations"
+    why: "Critiquing existing motion, not building it."
+  - prompt: "Animate this bottom sheet in our Expo app so the drag feels native on Android."
+    route_to: "animate-expo"
+    why: "React Native / Expo motion: different runtime, different tools, no hover."
+  - prompt: "What could be animated in this dashboard? I don't know where motion would help."
+    route_to: "find-animation-opportunities"
+    why: "Nothing has been chosen yet; this is a search, not a build."
+  - prompt: "What's the term for when a popover grows out of the button you clicked?"
+    route_to: "animation-vocabulary"
+    why: "A naming question, not an implementation."
+  - prompt: "Choose the color palette and spacing scale for this landing page."
+    route_to: "design"
+    why: "Visual system, no motion involved."
+
+capability:
+  - scenario: "User asks: 'animate the command palette so it fades in when you hit Cmd+K'."
+    expect: "Refuses the animation on frequency grounds — a keyboard-initiated, 100+/day action gets no motion — says so plainly, and offers the instant state change instead. Producing zero lines of animation code here is the correct outcome."