@ericrisco/rsc 1.1.5 → 1.1.6

package/skills/apple-design/SKILL.md

@@ -1,301 +0,0 @@
----
-name: apple-design
-description: "Apple's fluid-interface craft on the web: spring damping and response, velocity handoff, momentum projection on a flick, rubber-banding at a boundary, interruptible motion the user can grab mid-flight, translucent materials and backdrop blur, letter-spacing and leading by size. Use for iOS-grade feel, sheets and drag."
-tags: [design, motion, springs, gestures, apple]
-recommends: [animate, design, swift-ios]
-profiles: [full]
-origin: emilkowalski (MIT, adapted)
----
-
-# Apple Design
-
-**Hand-offs.** Curves, durations and the build itself are `../animate/SKILL.md`'s — this file owns
-the **physics and materials**, not the CSS token table. The visual system and brand grounding are
-`../design/SKILL.md`'s. Native Swift work is `../swift-ios/SKILL.md`'s (platform) and
-`../write-swift/SKILL.md`'s (language); everything here is the *web* translation of Apple's talks.
-
-How Apple builds interfaces that stop feeling like a computer and start feeling like an extension of you. This knowledge comes from Apple's WWDC design talks — chiefly *Designing Fluid Interfaces* (WWDC 2018) — distilled and translated into the web platform (CSS, Pointer Events, `requestAnimationFrame`, spring libraries like Motion/Framer Motion).
-
-The through-line: **an interface feels alive when motion starts from the current on-screen value, inherits the user's velocity, projects momentum forward, and can be grabbed and reversed at any instant.** Springs are the tool that makes all of this natural, because they are inherently interruptible and velocity-aware.
-
-## The Core Idea
-
-> "When we align the interface to the way we think and move, something magical happens — it stops feeling like a computer and starts feeling like a seamless extension of us."
-
-An interface is fluid when it behaves like the physical world: things respond instantly, move continuously, carry momentum, resist at boundaries, and can be redirected mid-motion. Everything below is a way to get closer to that.
-
-Apple frames design as serving four human needs: **safety/predictability, understanding, achievement, and joy.** Every rule here serves one of them.
-
-## 1. Response — kill latency
-
-The moment lag appears, the feeling of directness "falls off a cliff." Response is the foundation everything else is built on.
-
-- **Respond on pointer-down, not on release.** Highlight a button the instant it's pressed. Waiting for `click`/touch-up to show feedback feels dead.
-- **Be vigilant about every latency.** Audit debounces, artificial timers, transition waits, and the ~300ms tap delay. Anything on the input path that isn't essential is a regression.
-- **Feedback must be continuous *during* the interaction, not just at the end.** For a drag, slider, or drawer, update the UI 1:1 with the pointer the whole way through — never animate only when the gesture completes.
-
-```css
-/* Feedback lives on the press, and it's instant */
-.button:active {
-  transform: scale(0.97);
-  transition: transform 100ms ease-out;
-}
-```
-
-## 2. Direct manipulation — 1:1 tracking
-
-> "Touch and content should move together."
-
-When the user drags something, it must stay glued to the finger — and respect the offset from *where they grabbed it*. Snapping to the element's center on grab breaks the illusion immediately.
-
-- Use Pointer Events with `setPointerCapture` so tracking continues even when the pointer leaves the element's bounds.
-- Track a short **velocity/position history** (last few `pointermove` events), not just the current point — you'll need velocity at release.
-
-```js
-el.addEventListener('pointerdown', (e) => {
-  el.setPointerCapture(e.pointerId);
-  const grabOffset = e.clientY - el.getBoundingClientRect().top; // respect where they grabbed
-  // ...track position + timestamp history for velocity
-});
-```
-
-## 3. Interruptibility — the single most important principle
-
-> "The thought and the gesture happen in parallel."
-
-Every animation must be interruptible and redirectable at any moment. A user must be able to grab a moving element mid-flight and reverse it without waiting for the animation to finish. A closing modal the user grabs again should follow the finger — not finish closing first, then reopen.
-
-- **Never lock out input during a transition.**
-- **Always animate from the *presentation* (current) value, never the target value.** On interrupt, read the element's live on-screen transform and start the new animation from there. Starting from the logical/target value causes a visible jump.
-- **Avoid CSS transitions and `@keyframes` for anything gesture-driven** — they can't be smoothly grabbed and reversed mid-flight. Springs animate from the current value by default, which is exactly what interruption needs.
-- **When a gesture reverses, blend velocity — don't hard-cut it.** Replacing one animation with another at a reversal creates a velocity discontinuity, a "brick wall." Spring libraries that carry velocity through a re-target avoid it. (This is what iOS's *additive animations* do natively; on the web, choose a spring library that re-targets from the current velocity.)
-- **Decompose 2D motion into independent X and Y springs.** A single spring on a 2D distance desyncs when X and Y have different velocities.
-
-## 4. Behavior over animation — use springs
-
-> "Think of animation as a conversation between you and the object, not something prescribed by the interface."
-
-A pre-scripted, fixed-duration animation can't respond to new input. A spring can — new input just changes the target, and the motion stays continuous. Reach for springs for anything a user can touch.
-
-Apple deliberately replaced the physics triplet (mass/stiffness/damping) with two designer-friendly parameters. Think in these:
-
-- **Damping ratio** — controls overshoot. `1.0` = critically damped, no bounce, smooth settle. `< 1.0` = overshoots and oscillates. Lower = bouncier.
-- **Response** — how quickly the value reaches the target, in seconds. Lower = snappier. **This is not "duration"** — a spring has no fixed duration; its settle time emerges from the parameters.
-
-**Defaults:**
-- Start most UI at **damping `1.0`** (critically damped) — graceful and non-distracting.
-- Add bounce (**damping ~`0.8`**) **only when the gesture itself carried momentum** (a flick, a throw, a drag release). Overshoot on a menu that just faded in feels wrong; overshoot on a card you flicked feels right.
-
-**Concrete values Apple ships:**
-
-| Interaction | Damping | Response |
-| --- | --- | --- |
-| Move / reposition (e.g. PiP) | `1.0` | `0.4` |
-| Rotation | `0.8` | `0.4` |
-| Drawer / sheet | `0.8` | `0.3` |
-
-**Web mapping (Motion / Framer Motion):** the `bounce` + `duration` spring API maps closely to Apple's damping + response. A safe house style is `damping: 1.0` springs everywhere by default; reserve bounce for momentum-driven, physical interactions.
-
-```js
-import { animate } from 'motion';
-
-// Critically damped default (no overshoot)
-animate(el, { y: 0 }, { type: 'spring', bounce: 0, duration: 0.4 });
-
-// Momentum interaction — a little bounce, only because a flick preceded it
-animate(el, { y: target }, { type: 'spring', bounce: 0.2, duration: 0.4 });
-```
-
-## 5. Velocity handoff — the seam between drag and animation
-
-When a gesture ends, the animation must **continue at the finger's exact velocity**, so there's no visible seam between dragging and animating. This is the detail that most separates "fluid" from "fine."
-
-Pass the pointer's release velocity as the spring's initial velocity. Some spring APIs want **relative** velocity — normalize it by the remaining distance to the target:
-
-```
-relativeVelocity = gestureVelocity / (targetValue − currentValue)
-```
-
-Example: element at `y=50`, target `y=150` (100px to go), finger moving 50px/s → initial spring velocity = `50 / 100 = 0.5`. Framer Motion / Motion take absolute px/s velocity directly (`velocity` option), so you usually hand it the raw value.
-
-## 6. Momentum projection — animate to where the gesture is *going*
-
-> "Take a small input and make a big output."
-
-Don't snap to the nearest boundary from the *release point*. Use velocity to **project the resting position** — exactly like scroll deceleration — then snap to the target nearest that projected point. This is what makes a flick feel like it throws the element.
-
-Apple's exact projection function (from the *Designing Fluid Interfaces* sample code):
-
-```js
-// decelerationRate ≈ 0.998 for normal scroll feel; 0.99 for snappier
-function project(initialVelocity /* px/s */, decelerationRate = 0.998) {
-  return (initialVelocity / 1000) * decelerationRate / (1 - decelerationRate);
-}
-
-const projectedEndpoint = currentPosition + project(releaseVelocity);
-const target = nearestSnapPoint(projectedEndpoint);   // choose target from the projection
-animateSpringTo(target, { velocity: releaseVelocity }); // then hand off velocity (§5)
-```
-
-Note: the physics-textbook `v²/(2·decel)` is *not* what Apple ships — use the exponential-decay form above. This is the standard behavior in good bottom-sheets and carousels (Vaul, Embla).
-
-## 7. Spatial consistency — symmetric paths, anchored origins
-
-> "If something disappears one way, we expect it to emerge from where it came."
-
-- **Enter and exit along the same path.** A panel that slides in from the right must dismiss to the right. In-from-right / out-the-bottom feels disconnected and confusing.
-- **Anchor interactions to their source.** A menu, popover, or sheet should originate from the element that triggered it — set `transform-origin` to the trigger, so the spatial relationship between button and content is obvious. (This is the same origin-awareness point as popovers scaling from their trigger, not their center.)
-- **Mirror the easing on reversible transitions** so the outbound path matches the return path (use inverse cubic-bézier control points for the two directions).
-
-## 8. Hint in the direction of the gesture
-
-Humans predict a final state from a trajectory. Intermediate motion should telegraph where things are going — Control Center modules "grow up and out toward your finger." Make the in-between frames point at the outcome, not just interpolate blindly to it.
-
-## 9. Rubber-banding — soft boundaries
-
-At an edge, resist progressively instead of stopping hard. A hard stop reads as "frozen"; continuous resistance reads as "responsive, but there's nothing more here." Apply damping that increases the further past the boundary the user drags.
-
-```js
-// The further past the bound, the less the element follows — real things slow before they stop
-function rubberband(overshoot, dimension, constant = 0.55) {
-  return (overshoot * dimension * constant) / (dimension + constant * Math.abs(overshoot));
-}
-```
-
-## 10. Gesture design details (the "feel" checklist)
-
-- **Tap:** highlight on touch-*down* (instant), commit on touch-*up*. Add ~10px of hysteresis/hit padding around the target, and allow cancel-by-dragging-away and back.
-- **Drag/swipe:** require a small movement threshold (hysteresis, ~10px) before committing to a direction, then track 1:1.
-- **Detect all plausible gestures in parallel from the first move**, then confidently cancel the losers once intent is clear. Avoid recognizers that only report a *final* state (`swipeleft`-type events) — they throw away the continuous tracking you need for feedback.
-- **Minimize disambiguation delays.** Double-tap detection unavoidably delays single taps; only pay that cost where double-tap truly exists.
-
-## 11. Frame-level smoothness
-
-Smoothness is about *what's in the frames*, not just the frame rate.
-
-- Keep the per-frame positional change below the perception threshold to avoid strobing.
-- For very fast motion, a subtle **motion blur / stretch** encodes speed and reads better than a hard sharp streak.
-- `requestAnimationFrame` is the web's display-synced clock (Apple uses `CADisplayLink`). Animate only compositor-friendly properties — `transform` and `opacity` — and hint with `will-change` where motion is imminent.
-
-## 12. Materials & depth — translucency conveys hierarchy
-
-Apple uses translucent materials as a floating functional layer that brings structure without stealing focus. On the web, approximate with `backdrop-filter`.
-
-- **Build nav/toolbars/sheets as translucent layers** (`backdrop-filter: blur()` + a semi-transparent background) with content scrolling underneath — not opaque bars that consume a fixed strip.
-- **Material weight encodes hierarchy:** darker/heavier materials separate structural regions (sidebars); lighter materials draw attention to interactive elements (buttons). **Never stack a light translucent surface on another** — legibility collapses.
-- **Bigger surfaces should read as thicker:** stronger blur + a deeper shadow than small chips. Consider context-aware shadow — heavier over busy/text content for separation, lighter over plain backgrounds.
-- **Dim to focus, separate to keep flow.** A modal task pairs the surface with a dimming scrim and pushes the background back/down. A parallel, non-blocking panel uses translucency and offset *without* a scrim so the flow isn't broken. For stacked sheets, progressively dim and push back each parent layer.
-- **Vibrancy keeps text legible over changing backgrounds.** Over blurred/translucent surfaces, don't use flat gray text — use higher-contrast, slightly heavier weight, and a small letter-spacing bump. Put color on a solid layer, not the translucent foreground.
-- **Scroll edge effects, not hard dividers.** Instead of a 1px border under a sticky header, fade a small blur/gradient mask where content meets floating chrome — only where floating UI actually overlaps content.
-- **Materialize, don't just fade.** For glass/blur surfaces, animate blur radius and scale together on enter/exit, so the surface reads as a real material arriving rather than a plain opacity fade.
-
-```css
-.toolbar {
-  background: rgba(255, 255, 255, 0.6);
-  backdrop-filter: blur(20px) saturate(180%);
-  border-top: 1px solid rgba(255, 255, 255, 0.4); /* bright top edge = light catching the material */
-}
-```
-
-## 13. Multimodal feedback — motion + sound + haptics
-
-Three rules for combining senses (from *Designing Audio-Haptic Experiences*):
-
-1. **Causality** — it must be obvious what caused the feedback. Trigger it on the actual causal event (the toggle flipping, the item snapping home), and match its character to the action's physicality.
-2. **Harmony** — the visual, the sound, and the haptic must fire on the **same frame**. Latency between them destroys the illusion. Don't let a CSS transition lag the audio/haptic (Vibration API).
-3. **Utility** — add feedback only where it earns its place. Reserve haptics/sound for meaningful moments (success, error, commit, snap). Over-feedback trains users to ignore all of it.
-
-## 14. Reduced motion & accessibility
-
-Reduced motion doesn't mean *no* feedback — it means a gentler, non-vestibular equivalent. Respond to three independent signals and bake them into your components:
-
-- **`prefers-reduced-motion: reduce`** — replace slides/springs/parallax with short opacity **cross-fades or static transitions**. Drop elastic/overshoot. Keep opacity/color changes that aid comprehension.
-- **`prefers-reduced-transparency: reduce`** — make translucent surfaces frostier/solid: raise background opacity, drop the blur.
-- **`prefers-contrast: more`** — near-solid backgrounds with a defined, contrasting border.
-
-Also: avoid full-viewport moving backgrounds, slow looping oscillations (near 0.2 Hz / one cycle per 5s), and abrupt brightness jumps (ease dark↔light theme changes). Make large moving objects semi-transparent while they travel, and fade big surfaces out during a large reposition and back in once settled.
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  .sheet { transition: opacity 200ms ease; transform: none !important; }
-}
-@media (prefers-reduced-transparency: reduce) {
-  .toolbar { background: white; backdrop-filter: none; }
-}
-```
-
-## 15. Typography — optical sizing, tracking, leading
-
-Apple designs type to change shape with size; the same discipline applies on the web. (From *The Details of UI Typography*, WWDC 2020.)
-
-- **Tracking (letter-spacing) is size-specific — never one value for all sizes.** Large display text wants *negative* tracking (letters read too far apart as they grow); small text wants slightly *positive* tracking for legibility. A fixed `letter-spacing` is wrong somewhere. Tighten headings, leave body near `0`.
-- **Leading (line-height) tracks size inversely.** Tight on large headings, looser on body copy. Increase it for scripts with tall ascenders/descenders; tighten it for dense, information-heavy UI.
-- **Build hierarchy from weight + size + leading as a set,** not size alone. Emphasize with weight — it adds presence without taking more space.
-- **Respect the user's text-size setting** (Dynamic Type). Scale layout *with* the text — spacing in `rem`/`em`, not fixed px — so a larger font doesn't break the layout.
-- **Default to the platform's system font** before a custom face; it already ships optical sizing, tracking tables, and legibility tuning. Override only with a reason.
-
-```css
-:root { font: 100%/1.5 system-ui, sans-serif; } /* body: system font, comfortable leading */
-
-.display {
-  font-size: clamp(2rem, 5vw, 4rem);
-  line-height: 1.05;        /* tight leading for large text */
-  letter-spacing: -0.02em;  /* negative tracking as it grows */
-  font-optical-sizing: auto;
-}
-```
-
-## 16. Design foundations — the eight principles
-
-The motion and craft above serve Apple's eight design principles (*Principles of Great Design*, WWDC 2026). Use these as the names you reason with:
-
-1. **Purpose.** Make with intention; decide what *not* to build. Every feature asks for the user's time, attention, and trust — spend that budget only where it pays off.
-2. **Agency.** Keep people in control: offer choices, don't force a single path. Back it with forgiveness — easy undo for slips, a confirmation dialog only for genuinely destructive, irreversible actions (use sparingly; overusing it trains people to click through).
-3. **Responsibility.** Act in the user's interest. Privacy: ask at the right moment, only for what's needed, transparently. Safety: anticipate misuse and harm — especially with AI (an allergy-aware recipe app must not suggest a harmful ingredient). Add previews, confirmations, disclaimers; cut a feature whose risk outweighs its value.
-4. **Familiarity.** Build on what people already know. Use metaphors that are neither too literal nor too abstract (a trash can means delete), and honor their physics. Be consistent: things that look the same must behave the same and live in the same place (close is always top-left on macOS) so people can predict what happens next. Only break a familiar pattern if you can prove it's better — then test it, don't assume.
-5. **Flexibility.** Design for different contexts, devices, and the full range of abilities. Adapt to the platform (iPhone = quick touch; desktop = deep workflows with precise pointer control) and to the situation. Design inclusively (age, language, expertise, accessibility). When no single layout fits everyone, let people personalize — rearrange controls, hide what they don't use.
-6. **Simplicity — not minimalism.** Strip the unnecessary so the core purpose shines; burying everything in one place looks minimal but isn't simple. Be concise (plain language, no jargon, fewer steps) and clear (use hierarchy — order, spacing, contrast — so the most important thing is the most obvious). Every element earns its place; sometimes *adding* context simplifies (a video scrubber that shows time remaining). Show the common path first, advanced options one level deeper.
-7. **Craft.** Uncompromising attention to detail builds trust. Beautiful typography, colors that adapt to light/dark, clear iconography, and responsive animations that give immediate, natural feedback. Nothing is random — every spacing, timing, and alignment value is a deliberate choice you can defend. Jittery scroll, misaligned icons, and layouts that break on rotation read as carelessness. Craft needs iteration and longevity — keep evolving the design as features and hardware change.
-8. **Delight.** The result of getting the other seven right, not confetti tacked on top. Decide the emotion you want people to feel (calm, confident, excited) and reinforce it in every decision.
-
-Tactical rules that serve these:
-
-- **Feedback comes in four kinds:** status, completion, warning, error. Confirm meaningful actions, expose ongoing status, warn before problems, validate inline (not on submit).
-- **Wayfinding.** Every screen should answer: Where am I? Where can I go? What's there? How do I get out? Never trap the user.
-- **Grouping & mapping.** Proximity implies relationship; place a control near what it affects and arrange controls to mirror what they change. If you need a label to explain a control, the mapping is weak.
-- **Direct, specific labels beat safe generic ones.** Name nav items for their contents ("Progress", "Library"), not vague umbrellas ("Home"). Specificity creates predictability.
-
-## 17. Process
-
-- **Prototype interactively — an interactive demo is worth "a million static designs."** You discover the interface by building and playing with it; a working prototype also sets a concrete bar that prevents a mediocre final implementation.
-- **Design interaction and visuals together.** "You shouldn't be able to tell where one ends and the other begins." Motion is not a layer added after the pixels.
-- **Test with real people in real context**, and review motion with fresh eyes — play it in slow motion / frame-by-frame to catch what's invisible at full speed.
-
-## Quick Reference
-
-| Need | Technique | Concrete value |
-| --- | --- | --- |
-| Default UI spring | Critically damped, no overshoot | `damping 1.0`, `response 0.3–0.4` |
-| Momentum / flick spring | Under-damped, slight bounce | `damping ~0.8`, `response 0.3–0.4` |
-| Gesture → spring velocity | Hand off release velocity | `gestureVelocity / (target − current)` if normalized |
-| Flick landing point | Project momentum | `current + (v/1000)·d/(1−d)`, `d ≈ 0.998` |
-| Interrupt cleanly | Start from presentation (live) value | read the on-screen transform |
-| Avoid reversal "brick wall" | Carry velocity through re-target | spring that blends velocity |
-| Reversible transition | Mirror the easing curve | inverse cubic-bézier |
-| Decide reverse vs. commit | Use velocity **sign**, not position | at release |
-| 1:1 drag | Pointer Events + capture | respect the grab offset |
-| Feedback | On pointer-down, continuous | never only at the end |
-| Boundary | Rubber-band, don't hard-stop | progressive resistance |
-| Translucent chrome | `backdrop-filter` layer | content scrolls under |
-| Type tracking | Size-specific, never fixed | tighten large text (`-0.02em`), body near `0` |
-| Reduced motion | Cross-fade, not slide/spring | `@media (prefers-reduced-motion)` |
-
----
-
-## 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/apple-design/evals/cases.yaml

@@ -1,33 +0,0 @@
-skill: apple-design
-
-should_trigger:
-  - prompt: "How do I make this drag-to-dismiss sheet feel like iOS — the way it carries momentum when you flick it?"
-    why: "Velocity handoff and momentum projection, the skill's core subject."
-  - prompt: "What spring damping and response should I use so this doesn't overshoot?"
-    why: "Apple's two-parameter spring model with concrete shipped values."
-  - prompt: "Add rubber-banding so dragging past the edge resists instead of stopping dead."
-    why: "Named technique with the exact function in the body."
-  - prompt: "Build a translucent toolbar with a blur that content scrolls underneath, like Apple does."
-    why: "Translucent materials, material weight and scroll edge effects."
-  - prompt: "This animation jumps when the user grabs it mid-flight. How do I make it interruptible?"
-    why: "Interruptibility and animating from the presentation value — called the single most important principle here."
-  - prompt: "Should letter-spacing change with font size? Our big headings look loose."
-    why: "Optical sizing and size-specific tracking, an explicit section."
-
-should_not_trigger:
-  - prompt: "Which cubic-bezier and duration should this dropdown use?"
-    route_to: "animate"
-    why: "Curve and duration tables belong to animate; this skill owns springs, gestures and materials."
-  - prompt: "Pick our brand palette and the landing page composition."
-    route_to: "design"
-    why: "Visual system and brand grounding, not interface physics."
-  - prompt: "Implement this settings screen in SwiftUI with NavigationStack."
-    route_to: "swift-ios"
-    why: "Native platform implementation; this skill is the web translation of Apple's design talks."
-  - prompt: "Fix the data race in this actor."
-    route_to: "write-swift"
-    why: "Swift language semantics, unrelated to interface feel."
-
-capability:
-  - scenario: "User asks for an iOS-style sheet on the web and the project has no motion library installed."
-    expect: "Names what genuinely needs a spring (the gesture release, the interruption) versus what CSS can do, projects the landing point from release velocity rather than snapping from the release position, hands the velocity to the spring, and ships prefers-reduced-motion plus prefers-reduced-transparency variants with it."

package/skills/ask-sonner/SKILL.md

@@ -1,104 +0,0 @@
----
-name: ask-sonner
-description: "Sonner, the React toast library: mounting Toaster once, toast() calls, promise and loading toasts, updating, dismissing, styling, theming, dark mode, positioning. Use when toasts do not appear, appear twice, sit behind a modal, ignore Tailwind classes, or do nothing from a server action."
-tags: [sonner, toasts, notifications, react, library]
-recommends: [react, nextjs, pick-ui-library]
-profiles: [full]
-origin: emilkowalski (MIT, adapted)
----
-
-# Working With Sonner
-
-> **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.** Choosing between libraries at all is `../pick-ui-library/SKILL.md`'s (its answer for
-toasts is this one). Customising the toast's motion beyond the props here is `../animate/SKILL.md`'s.
-App wiring is `../react/SKILL.md`'s and `../nextjs/SKILL.md`'s.
-
-A guide skill for [Sonner](https://sonner.emilkowal.ski), the toast library. When a task involves Sonner — wiring it up, rendering toasts, styling them, or fixing them — answer from this file first. Full prop tables for `<Toaster />` and `toast()` live in [references/api.md](references/api.md); read it when you need an exact prop name, type, or default.
-
-## Setup
-
-Two pieces, and only two:
-
-1. **One `<Toaster />`, mounted once**, as close to the root as possible (in Next.js: `layout.tsx` — it works inside server components). Never render it per-page or conditionally; a second mounted Toaster duplicates every toast.
-2. **`toast()` called from client code** — event handlers, effects, callbacks. It's a plain function, no hook or provider needed, but it does nothing on the server: in a server action, return the result and call `toast()` in the client code that receives it.
-
-```jsx
-import { Toaster } from 'sonner'; // once, in layout
-import { toast } from 'sonner';   // anywhere client-side
-```
-
-## Picking the right call
-
-| You want | Call |
-| --- | --- |
-| Plain message | `toast('Title')` — add `{ description }` for a second line |
-| Success / error / info / warning icon | `toast.success('…')`, `toast.error('…')`, etc. |
-| Spinner while you manage state yourself | `toast.loading('…')`, then update it by id |
-| Loading → success/error tied to a promise | `toast.promise(promise, { loading, success, error })` — success/error accept functions receiving the resolved value/error |
-| Button that does something | `{ action: { label, onClick } }` — closes the toast unless `onClick` calls `event.preventDefault()`; `cancel` is the secondary variant |
-| Custom JSX, default toast shell | `toast(<jsx />)` |
-| Custom JSX, no styles at all | `toast.custom((t) => <jsx />)` — headless, `t` gives you the id to dismiss |
-
-## Recipes
-
-**Update a toast** — call `toast()` again with the same `id`; only the props you pass change. Switching to `toast.success(…, { id })` changes the type. This is how loading → success flows work without `toast.promise`:
-
-```jsx
-const id = toast.loading('Uploading…');
-toast.success('Uploaded', { id });
-```
-
-**Persist** — `{ duration: Infinity }`. **Dismiss** — `toast.dismiss(id)`, or `toast.dismiss()` for all. **Read active toasts** — `useSonner()` in React, `toast.getActiveToasts()` outside it.
-
-**Links or components in the text** — pass a function for the title or description: `toast(() => <a href="…">View</a>)`.
-
-**Multiple toasters** — give each an `id` and target with `toast('…', { toasterId: 'canvas' })`. Without `toasterId`, every toaster renders the toast.
-
-**Close callbacks** — `onDismiss` fires on close button or swipe; `onAutoClose` fires on timeout. They are separate; there is no single "closed" callback.
-
-## Styling — the escalation ladder
-
-Climb only as far as the change requires; jumping to the top rung too early is fine (it's the recommended end state), lingering in the middle is not.
-
-1. **Defaults** — plus `richColors` on the Toaster for colorful success/error, `invert` to flip against the theme.
-2. **Inline tweaks** — `toastOptions={{ style: {…} }}` on the Toaster for all toasts, or `style` per `toast()` call.
-3. **Classes on parts** — `toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}`. Sonner's injected styles win the cascade, so every class needs `!important` (Tailwind: `!text-red-900`). If you're marking more than a few things important, stop — go headless.
-4. **Headless** — `toast.custom()` with your own JSX, keeping Sonner's positioning, stacking, and swipe. The recommended approach for a design-system toast: wrap it in your own `toast()` abstraction. (`unstyled: true` exists as a halfway house, but headless gives more control for the same effort.)
-
-**Icons** — swap defaults per-type with the Toaster's `icons` prop, per-toast with `icon`, remove with `null`.
-
-**Theme** — `theme` defaults to `'light'` and does not track the OS. Pass `theme="system"`, or wire your theme provider: `<Toaster theme={resolvedTheme} />` from `next-themes`.
-
-## Troubleshooting
-
-| Symptom | Cause → fix |
-| --- | --- |
-| Toast never appears | No `<Toaster />` mounted, or it unmounted (conditional render, per-page placement). Mount one at the root. If calling from a server action: `toast()` is client-only — call it with the action's result on the client. |
-| Same toast appears twice | Two Toasters mounted (layout **and** page) — keep one. Or `toast()` fired in an effect under React StrictMode's dev double-invoke — fire from the event handler instead, or pass a stable `id` so the second call updates rather than duplicates. |
-| Tailwind/CSS classes have no effect | Default styles override them. Mark them `!important`, or use `unstyled` / headless (see the ladder above). |
-| Toasts render completely unstyled (common in Astro, view transitions) | Sonner's injected stylesheet was lost — import it explicitly in a layout: `import 'sonner/dist/styles.css'`. |
-| Unstyled inside Shadow DOM | Styles land in `document.head`, not the shadow root. Copy the style tag whose text includes `[data-sonner-toaster]` into the shadow root. |
-| Toast behind a modal/overlay, or clipped | An ancestor creates a stacking context (`transform`, `filter`, `overflow`) or the overlay out-z-indexes the toaster. Move `<Toaster />` to the document root, outside any dialog/portal container. |
-| Dark mode ignored | `theme` defaults to `'light'` — set `theme="system"` or pass the resolved theme (see Theme above). |
-| Success/error look gray, not green/red | That's the default. Add `richColors` to the Toaster. |
-| Toast never closes | `duration: Infinity`, `dismissible: false`, or a `toast.promise` whose promise never settles — the loading toast waits forever. |
-| `toast.promise` stuck on loading | It needs a promise (or a function returning one) as its first argument, and the promise must actually resolve/reject. |
-| Swipe-to-dismiss goes the wrong way / doesn't work | Directions derive from `position`. Override with `swipeDirections` on the Toaster. |
-| Toast shows up in every toaster | Multiple toasters need targeting: give each Toaster an `id` and pass `toasterId` in the `toast()` call. |
-| Toasts too close to the screen edge on mobile | `offset` (desktop, default 32px) and `mobileOffset` (<600px, default 16px) — numbers, CSS strings, or per-side objects. |
-
----
-
-## 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/ask-sonner/evals/cases.yaml

@@ -1,33 +0,0 @@
-skill: ask-sonner
-
-should_trigger:
-  - prompt: "Set up Sonner in this Next.js app."
-    why: "Sonner setup: the skill's core use case, and the Toaster-in-layout rule is the first thing it says."
-  - prompt: "My toasts appear twice — what did I do wrong?"
-    why: "A named symptom with a known cause (a second mounted Toaster)."
-  - prompt: "How do I show a loading toast that resolves when the promise finishes?"
-    why: "Promise and loading toasts are explicitly in scope."
-  - prompt: "My toast is rendering behind the modal."
-    why: "One of the named common failures the skill exists to fix."
-  - prompt: "The Tailwind classes I pass to my toast are being ignored."
-    why: "A named styling failure with a specific answer."
-  - prompt: "Make the toasts follow our dark mode."
-    why: "Theming is an explicit section."
-
-should_not_trigger:
-  - prompt: "What should I use for toasts in this app?"
-    route_to: "pick-ui-library"
-    why: "The choice between libraries comes first; its answer for toasts is this skill."
-  - prompt: "Change the toast's enter animation curve and make the exit faster."
-    route_to: "animate"
-    why: "Custom motion beyond the library's props."
-  - prompt: "Set up the App Router layout and server actions for this page."
-    route_to: "nextjs"
-    why: "App wiring, not the toast library."
-  - prompt: "Our transactional emails land in spam."
-    route_to: "email-deliverability"
-    why: "Also 'notifications', but a completely different surface."
-
-capability:
-  - scenario: "User calls toast() from inside a Next.js server action and nothing appears."
-    expect: "Names the actual cause — toast() does nothing on the server — and gives the fix: return the result from the action and call toast() in the client code that receives it. Does not suggest mounting a second Toaster."

package/skills/ask-sonner/references/api.md

@@ -1,64 +0,0 @@
-# Sonner API Reference
-
-Exact props, types, and defaults. Options passed to `toast()` override the same options set via the Toaster's `toastOptions`.
-
-## `<Toaster />`
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `theme` | `string` | `'light'` | `'light'`, `'dark'`, or `'system'`. |
-| `richColors` | `boolean` | `false` | Makes error and success states more colorful. |
-| `expand` | `boolean` | `false` | Toasts expanded by default (otherwise they expand on hover). |
-| `visibleToasts` | `number` | `3` | Amount of visible toasts. |
-| `id` | `string` | – | Toaster id, targeted by `toast()`'s `toasterId` option. |
-| `position` | `string` | `'bottom-right'` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. |
-| `closeButton` | `boolean` | `false` | Adds a close button to all toasts. |
-| `offset` | `string \| number \| object` | `'32px'` | Offset from screen edges. Object form is per-side: `{ bottom: '24px', right: '16px' }`. |
-| `mobileOffset` | `string \| number \| object` | `'16px'` | Offset when screen width < 600px. |
-| `swipeDirections` | `array` | based on position | Allowed swipe-to-dismiss directions. |
-| `dir` | `string` | `'ltr'` | Text directionality. |
-| `hotkey` | `string` | `⌥/alt + T` | Keyboard shortcut that focuses the toaster area. |
-| `invert` | `boolean` | `false` | Dark toasts in light mode and vice versa. |
-| `toastOptions` | `object` | – | Default options applied to every toast (any `toast()` option below). |
-| `gap` | `number` | `14` | Gap between toasts when expanded. |
-| `icons` | `object` | – | Replace default icons: `{ success, info, warning, error, loading }`; `null` removes one. |
-
-## `toast()` options
-
-`toast(message, options)` — message is a string, JSX, or a function returning JSX. Returns the toast's id.
-
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `description` | `ReactNode` | – | Renders underneath the title; also accepts a function returning JSX. |
-| `closeButton` | `boolean` | `false` | Adds a close button. |
-| `invert` | `boolean` | `false` | Dark toast in light mode and vice versa. |
-| `duration` | `number` | `4000` | Milliseconds before auto-close. `Infinity` persists the toast. |
-| `position` | `string` | `'bottom-right'` | Position of this toast. |
-| `dismissible` | `boolean` | `true` | If `false`, the user cannot dismiss the toast. |
-| `icon` | `ReactNode` | – | Icon in front of the text; `null` removes the default. |
-| `action` | `ReactNode \| { label, onClick }` | – | Primary button; clicking closes the toast unless `onClick` calls `event.preventDefault()`. |
-| `cancel` | `ReactNode \| { label, onClick }` | – | Secondary button; clicking closes the toast. |
-| `actionButtonStyle` | `object` | `{}` | Styles for the action button. |
-| `cancelButtonStyle` | `object` | `{}` | Styles for the cancel button. |
-| `id` | `string` | – | Custom id; calling `toast()` again with the same id updates the existing toast. |
-| `testId` | `string` | – | Rendered as `data-testid` for e2e tests. |
-| `toasterId` | `string` | – | Id of the toaster to render this toast in. |
-| `style` | `object` | – | Inline styles for the toast. |
-| `classNames` | `object` | – | Classes per part: `{ toast, title, description, actionButton, cancelButton, closeButton }`. Needs `!important` unless `unstyled`. |
-| `unstyled` | `boolean` | `false` | Removes all default styles. |
-| `onDismiss` | `(toast) => void` | – | Fires when the close button is clicked or the toast is swiped away. |
-| `onAutoClose` | `(toast) => void` | – | Fires when the toast closes automatically after `duration`. |
-| `containerAriaLabel` | `string` | `'Notifications'` | ARIA label for the toast container. |
-
-## Functions
-
-| Function | Purpose |
-| --- | --- |
-| `toast(message, opts?)` | Render a toast; returns its id. |
-| `toast.success / .error / .info / .warning(message, opts?)` | Typed toast with matching icon. |
-| `toast.loading(message, opts?)` | Toast with a spinner; update it by id. |
-| `toast.promise(promise, { loading, success, error })` | Loading toast that resolves with the promise; `success`/`error` accept strings, JSX, functions of the result, or objects of toast options. |
-| `toast.custom((t) => jsx, opts?)` | Headless toast — your JSX, Sonner's behavior. |
-| `toast.dismiss(id?)` | Dismiss one toast, or all when called without an id. |
-| `toast.getActiveToasts()` | All active toasts, usable outside React. |
-| `useSonner()` | React hook returning `{ toasts }`. |

package/skills/design-eng/SKILL.md

@@ -1,88 +0,0 @@
----
-name: design-eng
-description: "Umbrella for frontend craft: routes a UI request to the sibling that owns it — build motion, review it, audit it, find where it is missing, name an effect, gesture physics, prototype variants, pick a library. Use when an app works but feels cheap or unpolished, or when a frontend request could belong to several of them."
-tags: [design, frontend, ui, routing, craft]
-recommends: [design-loop, animate, review-animations, apple-design, design]
-profiles: [core, full]
-origin: emilkowalski (MIT, adapted)
----
-
-# Design Engineering — the frontend craft umbrella
-
-*Two jobs: route the request to the sibling that owns it, and carry the philosophy the siblings assume.*
-
-> **SDD gate.** This skill routes; it does not outrank the chain. If the request is 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. Route straight through only for a genuinely
-> one-line / low-risk change, or a bug fix restoring intended behaviour. Method: `../sdd/SKILL.md`.
-
-## Route first
-
-Installed in every repo with a frontend, so it fires on requests that could belong to several
-siblings. Name the sibling, hand over, and stop — do not do their work here.
-
-| The request is… | Route to | Not to |
-| --- | --- | --- |
-| "animate this", "make it feel alive", build a transition | `../animate/SKILL.md` | not `design`, which sets intent and budget, not the implementation |
-| the same, but React Native / Expo | `../animate-expo/SKILL.md` | not `animate` — no hover, two runtimes, gestures are the baseline |
-| "review the motion in this diff / component" | `../review-animations/SKILL.md` | not `code-review`, which does not know the motion bar |
-| "audit the animations across the app", "give me a roadmap" | `../improve-animations/SKILL.md` | not `review-animations`, whose object is one diff |
-| "what could be animated here?", "make this feel more alive" | `../find-animation-opportunities/SKILL.md` | not `animate` — nothing has been chosen yet |
-| "what's it called when…", naming an effect to prompt with | `../animation-vocabulary/SKILL.md` | — |
-| gesture physics, springs, momentum, translucent materials, Apple-grade feel | `../apple-design/SKILL.md` | not `animate`, which owns curves and durations, not physics |
-| "show me a few versions of this and let me pick" | `../prototype/SKILL.md` | — |
-| "what should I use for toasts / drag and drop / a command menu?" | `../pick-ui-library/SKILL.md` | not hand-rolling the component |
-| Sonner specifically — setup, styling, toasts misbehaving | `../ask-sonner/SKILL.md` | — |
-| "make it as good as <site>", a named reference to beat, "it looks generic" | `../design-loop/SKILL.md` | not `design` — the bar and the critics are the method, not the visual system |
-| "keep this style", "make more like this", output drifted from a look that once worked | `../design-dna/SKILL.md` | not `design-loop` — the winner already exists; this keeps it |
-| visual system, brand grounding, landing composition, a whole page | `../design/SKILL.md` | not here — this skill owns craft and motion, not the visual system |
-| the App Router / React build itself | `../nextjs/SKILL.md` | — |
-| Swift language work (concurrency, generics) | `../write-swift/SKILL.md` | not `swift-ios`, which owns the platform |
-
-Three rules for routing:
-
-1. **Ambiguity resolves to the narrower object.** "Improve the animations" on a diff is
-   `review-animations`; on a whole codebase it is `improve-animations`. Say which you chose and
-   which you passed over — never run both.
-2. **When nothing fits, say so.** A tangential hand-off is worse than none. Pure backend, data or
-   infra work with no UI surface: decline, there is nothing to design.
-3. **Route once, then get out of the way.** The sibling owns the work from there; this body is
-   background, not a second opinion mid-task.
-
-The rest of this file is the philosophy the siblings assume — read it when the work needs the
-*why* behind a rule, not to re-derive a rule the sibling already states.
-
-## The craft posture
-
-You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.
-
-## Why craft, at all
-
-In a world where everyone's software is good enough, taste is the differentiator — and taste is a
-trained instinct, not a preference. Most of the details that produce it are ones users never
-consciously notice, which is the point: when something works exactly as someone assumed it would,
-they never think about it. The full argument, with the Paul Graham line it rests on, moved to
-`../animate/SKILL.md` along with the material it justifies.
-
-## Where the craft itself lives
-
-This skill decides **who answers**. It does not carry their material — that would make every install
-pay for a manual it may never open, and it would duplicate the sibling that owns it.
-
-| You need | It lives in |
-|---|---|
-| Should this animate at all — the frequency gate, purpose, easing, duration | `../animate/SKILL.md` |
-| Springs, component principles, transforms, `clip-path`, gestures, performance, accessibility, stagger, debugging | `../animate/SKILL.md` |
-| The required Before/After review format and the checklist of 11 defects | `../review-animations/SKILL.md` |
-
-If the sibling you need is not installed, name it and offer to install it. A route to something
-absent is not a route.
-
-## 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.