@ericrisco/rsc 1.0.27 → 1.0.28

package/skills/review-animations/evals/cases.yaml

@@ -0,0 +1,34 @@
+skill: review-animations
+
+should_trigger:
+  - prompt: "Review the animations in this pull request and tell me what's wrong with them."
+    why: "Reviewing motion in a diff: the skill's core object."
+  - prompt: "Is the easing and duration on this modal transition right?"
+    why: "A judgement call against the easing and duration standards."
+  - prompt: "Check this component's motion against a strict craft bar before I merge it."
+    why: "The bar and the merge gate are what this skill provides."
+  - prompt: "Critique the transitions I just wrote — be harsh."
+    why: "Default-to-flagging posture; approval is earned."
+  - prompt: "Did I get the transform-origin and the reduced-motion handling right on this popover?"
+    why: "Two of the ten non-negotiable standards, named directly."
+
+should_not_trigger:
+  - prompt: "Audit the animations across the whole app and give me a prioritized roadmap of fixes."
+    route_to: "improve-animations"
+    why: "Whole-codebase audit producing plans, not a verdict on one diff."
+  - prompt: "Animate this dropdown for me with the right curve and duration."
+    route_to: "animate"
+    why: "Building the animation, not reviewing one."
+  - prompt: "Review this pull request for SQL injection and missing authorization checks."
+    route_to: "code-review"
+    why: "Non-motion code review; this skill declines and points there."
+  - prompt: "What could be animated in this settings page that isn't animated today?"
+    route_to: "find-animation-opportunities"
+    why: "Looking for absent motion, not judging present motion."
+  - prompt: "Pick a library for the command palette instead of the div-based one we have."
+    route_to: "pick-ui-library"
+    why: "A dependency choice, not a motion review."
+
+capability:
+  - scenario: "A diff adds `transition: all 400ms ease-in` and a `transform: scale(0)` entrance to a popover with `transform-origin: center`, and no reduced-motion handling anywhere in the project."
+    expect: "Runs scripts/verify.sh first so the countable findings come from the checker (transition-all, ease-in-ui, scale-zero-entrance, origin-center-popover, reduced-motion-missing) and spends judgement on frequency, purpose and cohesion. Blocks rather than approves, and every finding carries the exact replacement value."

package/skills/review-animations/references/standards.md

@@ -0,0 +1,187 @@
+# Animation Standards Reference
+
+The precise values, curves, and rules behind the review. Cite these in findings instead of approximating. Distilled from Emil Kowalski's design engineering philosophy.
+
+## Should it animate? (frequency table)
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day (keyboard shortcuts, command palette toggle) | No animation. Ever. |
+| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare / first-time (onboarding, feedback, celebrations) | Can add delight |
+
+**Never animate keyboard-initiated actions** — they repeat hundreds of times daily; animation makes them feel slow and disconnected. (Raycast has no open/close animation — correct for something used hundreds of times a day.)
+
+Valid purposes for motion: spatial consistency, state indication, explanation, feedback, preventing jarring change. "It looks cool" on a frequently-seen element is not valid.
+
+## Easing
+
+Decision order:
+- Entering or exiting → **`ease-out`** (starts fast, feels responsive)
+- 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 strong custom curves:
+
+```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) */
+```
+
+Find curves at [easing.dev](https://easing.dev/) or [easings.co](https://easings.co/) — don't hand-roll from scratch.
+
+## 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 |
+
+**Rule: UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one. Faster spinners make load feel faster (same actual time). Instant tooltips after the first (skip delay + animation) make a toolbar feel faster.
+
+## Physicality
+
+- **Never `scale(0)`.** Start from `scale(0.9–0.97)` + `opacity: 0`. Nothing in the real world appears from nothing.
+- **Origin-aware popovers.** Scale from the trigger, not center:
+  ```css
+  .popover { transform-origin: var(--transform-origin); } /* Base UI */
+  ```
+  **Modals are exempt** — they appear centered in the viewport, keep `transform-origin: center`.
+- **Button press feedback.** `transform: scale(0.97)` on `:active`, `transition: transform 160ms ease-out`. Subtle (0.95–0.98). Applies to any pressable element.
+
+## Springs
+
+Feel natural because they simulate physics; no fixed duration — they settle on parameters. Use for: drag with momentum, "alive" elements (Dynamic Island), interruptible gestures, decorative mouse-tracking.
+
+```js
+// Apple-style (easier to reason about) — recommended
+{ type: "spring", duration: 0.5, bounce: 0.2 }
+
+// Traditional physics (more control)
+{ type: "spring", mass: 1, stiffness: 100, damping: 10 }
+```
+
+Keep bounce subtle (0.1–0.3); avoid bounce in most UI — reserve for drag-to-dismiss and playful interactions. Springs maintain velocity when interrupted (keyframes restart from zero), so they're ideal for gestures users may reverse mid-motion.
+
+Mouse interactions: interpolate with `useSpring` rather than tying value directly to mouse position (direct = artificial, no momentum). Only do this when the motion is decorative.
+
+## Interruptibility
+
+CSS **transitions** can be interrupted and retargeted mid-animation; **keyframes** restart from zero. For anything triggered rapidly (toasts being added, toggles), transitions are smoother.
+
+```css
+/* Interruptible — good for dynamic UI */
+.toast { transition: transform 400ms ease; }
+
+/* Not interruptible — avoid for dynamic UI */
+@keyframes slideIn { from { transform: translateY(100%); } to { transform: translateY(0); } }
+```
+
+Use `@starting-style` for entry without JS:
+
+```css
+.toast {
+  opacity: 1; transform: translateY(0);
+  transition: opacity 400ms ease, transform 400ms ease;
+  @starting-style { opacity: 0; transform: translateY(100%); }
+}
+```
+
+Legacy fallback: `useEffect(() => setMounted(true), [])` + `data-mounted` attribute.
+
+## Asymmetric timing
+
+Slow where the user is deciding, fast where the system responds.
+
+```css
+.overlay { transition: clip-path 200ms ease-out; }            /* release: fast */
+.button:active .overlay { transition: clip-path 2s linear; }  /* press: slow, deliberate */
+```
+
+## Performance
+
+- **Only animate `transform` and `opacity`** — they skip layout/paint and run on the GPU. `padding`/`margin`/`height`/`width`/`top`/`left` trigger all three rendering steps.
+- **Don't drive child transforms via a CSS variable on the parent** — it recalcs styles for all children. Set `transform` directly on the element.
+  ```js
+  element.style.setProperty('--swipe-amount', `${d}px`); // bad: recalc on all children
+  element.style.transform = `translateY(${d}px)`;        // good: only this element
+  ```
+- **Framer Motion shorthands are NOT hardware-accelerated.** `x`/`y`/`scale` run on the main thread via rAF and drop frames under load. Use the full transform string:
+  ```jsx
+  <motion.div animate={{ x: 100 }} />                          // drops frames under load
+  <motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
+  ```
+- **CSS animations beat JS under load** — they run off the main thread; rAF-based animations stutter while the browser loads/scripts/paints. Use CSS for predetermined motion, JS for dynamic/interruptible.
+- **WAAPI** gives JS control with CSS performance (hardware-accelerated, interruptible, no library):
+  ```js
+  element.animate([{ clipPath: 'inset(0 0 100% 0)' }, { clipPath: 'inset(0 0 0 0)' }],
+    { duration: 1000, fill: 'forwards', easing: 'cubic-bezier(0.77, 0, 0.175, 1)' });
+  ```
+
+## Transforms & clip-path
+
+- **`translate` percentages** are relative to the element's own size — `translateY(100%)` moves by the element's height regardless of dimensions (how Sonner/Vaul position toasts/drawers). Prefer over hardcoded px.
+- **`scale()` scales children too** (font, icons, content) — a feature for press feedback.
+- **3D**: `rotateX/Y` + `transform-style: preserve-3d` for depth/orbit/flip without JS.
+- **`clip-path: inset(t r b l)`** is a powerful animation tool: each value eats in from that side. Uses: reveal-on-scroll (`inset(0 0 100% 0)` → `inset(0 0 0 0)`), hold-to-delete overlay, seamless tab color transitions (duplicate + clip the active copy), comparison sliders.
+
+## Gestures & drag
+
+- **Momentum dismissal**: don't require crossing a distance threshold — compute velocity (`Math.abs(distance)/elapsedMs`); dismiss if `> ~0.11`. A flick should be enough.
+- **Damping at boundaries**: dragging past a natural edge moves less the further you go (real things slow before stopping).
+- **Pointer capture** once dragging starts, so it continues when the pointer leaves bounds.
+- **Multi-touch protection**: ignore extra touch points after the drag begins (`if (isDragging) return`) — prevents jumps.
+- **Friction over hard stops** — allow over-drag with rising resistance rather than an invisible wall.
+
+## Masking imperfect crossfades
+
+When a crossfade shows two overlapping states despite tuning easing/duration, add subtle `filter: blur(2px)` during the transition to blend them into one perceived transformation. Keep blur < 20px (heavy blur is expensive, especially Safari).
+
+## Stagger
+
+Stagger group entrances; 30–80ms between items. Longer delays feel slow. Stagger is decorative — never block interaction while it plays.
+
+```css
+.item { opacity: 0; transform: translateY(8px); animation: fadeIn 300ms ease-out forwards; }
+.item:nth-child(2) { animation-delay: 50ms; }
+.item:nth-child(3) { animation-delay: 100ms; }
+@keyframes fadeIn { to { opacity: 1; transform: translateY(0); } }
+```
+
+## Accessibility
+
+```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); } /* gate hover motion — 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/position changes.
+
+## Debugging (recommend in reviews when feel is uncertain)
+
+- **Slow motion**: bump duration 2–5× or use DevTools animation inspector. Check colors crossfade cleanly, easing doesn't stop abruptly, `transform-origin` is right, coordinated properties stay in sync.
+- **Frame-by-frame**: Chrome DevTools Animations panel reveals timing drift between coordinated properties.
+- **Real devices** for gestures (drawers, swipe) — connect a phone, hit the dev server by IP, use Safari remote devtools.
+- **Fresh eyes next day** — imperfections invisible during development surface later.
+
+## Cohesion
+
+Match motion to the component's personality: playful can be bouncier; a professional dashboard should be crisp and fast. Sonner feels right partly because easing, duration, design, and even the name are in harmony — slightly slower, `ease` rather than `ease-out`, to feel elegant. Opacity + height in entering/exiting lists is trial and error; there's no formula — adjust until it feels right.

package/skills/review-animations/scripts/verify.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+#
+# verify.sh — the checkable half of the motion craft bar.
+#
+# WHAT THIS IS
+#   The source material for these skills (emilkowalski/skills, MIT) ships its "Never Ship" bar as
+#   a markdown table: prose an agent may or may not honor. Part of that bar is a plain pattern in
+#   the code — `transition: all`, an entrance from `scale(0)`, `ease-in` on a UI transition — and
+#   anything that is a pattern belongs in a binary, not in a paragraph (constitution P1).
+#
+#   So this script owns the countable half, and the SKILL.md bodies own the half that needs
+#   judgement (is the frequency tier right? does the motion have a purpose? does it feel right?).
+#   Nothing here can tell you whether an animation feels good. It tells you when it is definitely
+#   wrong.
+#
+# WHAT IT CHECKS
+#   - the tell registry: one row per checkable motion defect, iterated generically — see
+#     motion_tell_table(). Every row has a fixture in tests/fixtures/motion-tells/ and is driven
+#     from tests/motion-tells.test.js; a row without a fixture fails the suite.
+#   - one counter that cannot be a row: motion present with no prefers-reduced-motion guard
+#     anywhere. Absence of a guard is not a pattern match, so it gets its own check and its own
+#     named test.
+#
+# HOW TO RUN (inside YOUR project, not the skills repo)
+#   bash verify.sh              # fail-severity rows break the build; warns are advisory
+#   bash verify.sh --strict     # treat warnings as failures too
+#
+# EXIT CODES
+#   0  no fail-severity finding (and no warning, under --strict)
+#   1  a fail-severity finding, or --strict with any warning
+#   2  bad usage
+#
+# Missing tools are SKIPPED with a notice, never failed.
+
+set -euo pipefail
+
+# --- portability: runs on stock macOS bash 3.2 ------------------------------
+# No mapfile, no associative arrays, no `${arr[@]}` under set -u — same constraint as design's
+# verify.sh, for the same reason: the default /bin/bash on macOS is 3.2.
+if [ -z "${BASH_VERSION:-}" ]; then
+  printf 'This script requires bash (any version >= 3.2). Run: bash %s\n' "$0" >&2
+  exit 2
+fi
+
+STRICT=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --strict) STRICT=1; shift ;;
+    -h|--help) sed -n '2,32p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) printf 'unknown argument: %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+SELF_NAME="$(basename "$0")"
+
+ok()   { printf '%s  ok %s  %s\n'   "$GREEN" "$NC" "$1"; ok_count=$((ok_count + 1)); }
+skip() { printf '%sskip %s  %s\n'   "$YELLOW" "$NC" "$1"; skip_count=$((skip_count + 1)); }
+warn() { printf '%swarn %s  %s\n'   "$YELLOW" "$NC" "$1"; warn_count=$((warn_count + 1)); }
+fail() { printf '%sfail %s  %s\n'   "$RED" "$NC" "$1"; fail_count=$((fail_count + 1)); }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+search() {
+  [ "$#" -gt 0 ] || return 1
+  # VERIFY_FORCE_GREP=1 pins the grep branch so the suite can prove both engines agree, instead
+  # of only exercising whichever one happens to be installed.
+  if have rg && [ -z "${VERIFY_FORCE_GREP:-}" ]; then
+    rg -n --no-heading --glob "!$SELF_NAME" "$@"
+  else
+    local pattern="${*: -1}"
+    grep -rnE \
+      --exclude="$SELF_NAME" \
+      --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next \
+      --exclude-dir=dist --exclude-dir=build \
+      "$pattern" . 2>/dev/null
+  fi
+}
+
+# --- the tell registry ------------------------------------------------------
+# Columns, delimited by %% (the pattern column needs `|` for ERE alternation):
+#   id %% sev %% extensions %% POSIX-ERE pattern %% what to do instead / the legit exception
+#
+# Patterns are POSIX ERE: no lookahead, no \b, no \s — they must behave identically under rg and
+# under grep -E. The bar they encode is adapted from emilkowalski/skills (MIT).
+#
+# Severity is load-bearing, not decoration. `fail` is for a defect with no legitimate reading;
+# `warn` is for a pattern whose exception is real and cannot be seen from one line (a centered
+# modal, an accordion animating height). A table where everything fails gets switched off (P7).
+motion_tell_table() {
+  cat <<'TELLS'
+transition-all%%fail%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%transition:[[:space:]]*all|transition-all%%transition: all animates every property that ever changes, including layout ones, and janks. Name the exact properties instead: transition-property: transform, opacity
+scale-zero-entrance%%fail%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%scale\(0\)|scale3d\(0,|scale:[[:space:]]*0[,;}[:space:]]%%nothing in the real world appears from nothing, so an entrance from zero scale reads as broken. Start from scale(0.9)-scale(0.97) plus opacity: 0
+ease-in-ui%%fail%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%(^|[^a-zA-Z])ease-in([^-]|$)%%ease-in starts slow, delaying the exact moment the user is watching, so the interface feels sluggish. Use ease-out, or the stronger cubic-bezier(0.23, 1, 0.32, 1). Legitimate exception: an exit that must accelerate off-screen
+origin-center-popover%%warn%%tsx,jsx,ts,js,css,scss,html,vue,svelte%%transform-origin:[[:space:]]*center%%a popover, dropdown, menu or tooltip should grow out of the trigger that opened it, not out of its own middle. Use transform-origin: var(--transform-origin). Legitimate exception: a modal, which is not anchored to a trigger and stays centered
+layout-property-animation%%warn%%css,scss%%transition-property:[[:space:]]*(width|height|margin|padding|top|left)|transition:[[:space:]]*(width|height|margin|padding|top|left)[[:space:]]%%animating a layout property triggers layout, paint and composite every frame. Animate transform and opacity instead. Legitimate exception: an accordion height, which has no transform equivalent
+motion-shorthand-under-load%%warn%%tsx,jsx,ts,js%%animate=\{\{[[:space:]]*(x|y|scale):%%the Motion x/y/scale shorthands are not hardware-accelerated: they run on the main thread and drop frames while the page is busy. Use the full transform string: animate={{ transform: "translateX(100px)" }}
+TELLS
+}
+
+run_motion_tell_table() {
+  local line id sev globs pat msg hits exts rest
+  # NOT `IFS='%%'`: IFS is a set of characters, so it would split on a single `%`. Parameter
+  # expansion splits on the two-character delimiter exactly, which the pattern column needs to
+  # keep its ERE `|`.
+  while IFS= read -r line; do
+    case "$line" in ''|'#'*) continue ;; esac
+    id="${line%%"%%"*}";    rest="${line#*"%%"}"
+    sev="${rest%%"%%"*}";   rest="${rest#*"%%"}"
+    globs="${rest%%"%%"*}"; rest="${rest#*"%%"}"
+    pat="${rest%%"%%"*}";   msg="${rest#*"%%"}"
+    exts="${globs//,/|}"
+    # Two post-filters, both taken from design/scripts/verify.sh where they were learned from a
+    # real run: keep only the extensions the row declares (anchored before the first colon, so it
+    # behaves the same under rg and grep and never matches content that merely names a file), and
+    # drop matches that sit inside a code comment. `ease-in` in `/* not ease-in */` is not code,
+    # and flagging it trains the reader to ignore the tool.
+    hits="$(search "$pat" 2>/dev/null \
+      | grep -E "^[^:]*\.($exts):" \
+      | grep -vE "^[^:]*:[0-9]+:[[:space:]]*(//|/\*|\*[^a-zA-Z]|#|<!--|\{/\*)" || true)"
+    if [ -n "$hits" ]; then
+      case "$sev" in
+        warn) warn "$id: $msg" ;;
+        *)    fail "$id: $msg" ;;
+      esac
+      printf '%s\n' "$hits" | head -n 5
+    fi
+  done <<EOF
+$(motion_tell_table)
+EOF
+}
+
+# --- the counter that cannot be a row ---------------------------------------
+# Absence of a guard has no line to match, so it cannot ride the generic mechanism. It carries its
+# own named test instead of pretending to be a row.
+reduced_motion_counter() {
+  # Only meaningful where motion actually exists: telling a backend repo to add a reduced-motion
+  # guard is the noise that gets a checker switched off.
+  if search 'transition:|transition-property|@keyframes|animation:|animate=\{|useSpring|animate-\[' >/dev/null 2>&1; then
+    if search 'prefers-reduced-motion|useReducedMotion|motion-safe:|motion-reduce:' >/dev/null 2>&1; then
+      ok "reduced-motion-missing: motion is present and a reduced-motion guard was found"
+    else
+      fail "reduced-motion-missing: this project animates but no prefers-reduced-motion guard was found anywhere. Reduced motion means fewer and gentler animations, not zero: keep opacity and color transitions that aid comprehension, drop movement and position changes"
+    fi
+  else
+    skip "reduced-motion-missing: no motion found in this project, nothing to guard"
+  fi
+}
+
+# --- run --------------------------------------------------------------------
+run_motion_tell_table
+reduced_motion_counter
+
+printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+
+if [ "$fail_count" -gt 0 ]; then exit 1; fi
+if [ "$STRICT" -eq 1 ] && [ "$warn_count" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/swift-ios/SKILL.md

@@ -9,6 +9,13 @@ origin: risco
 
 # swift-ios
 
+**Hand-off — the language vs the platform.** This skill owns the **platform**: SwiftUI/UIKit views,
+app lifecycle, Xcode, iOS APIs, App Store shipping. Language-level Swift — Swift 6 data-race safety
+and approachable concurrency, actors and task groups, `some` vs `any`, ARC and performance, Swift
+Testing, macros — is `../write-swift/SKILL.md`'s. A concurrency error, a hang, a data race or a
+retain cycle goes there, not here. Interface feel, springs and materials: `../apple-design/SKILL.md`.
+
+
 Native Apple-platform apps: the code is `.swift`, the UI is SwiftUI, and the compiler enforces actor isolation. If the answer is a `@MainActor`, `@Observable`, `async let`, `#expect`, `NavigationStack`, or `@Model`, you are in the right place.
 
 ## First move: match the project before you write a line