@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/animation-performance/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: animation-performance
+description: Keep web animations inside the frame budget — animate composite-only properties, keep motion off the main thread when the page is busy, and find the cause when an animation drops frames. Covers the layout/paint/composite pipeline, cheaper property swaps, CSS vs WAAPI vs requestAnimationFrame, Framer Motion's hardware-accelerated path, React re-rendering per frame, inherited CSS variable recalculation, blur cost, and when `will-change` actually helps. Use when an animation is janky, choppy, stutters, or drops frames; when choosing which property to animate; when deciding between CSS and JS animation on performance grounds; or when reaching for `will-change` or GPU layers. For choosing easing, duration, or whether to animate at all use animate; for reviewing motion as a whole use review-animations.
+disable-model-invocation: true
+---
+
+# Animation Performance
+
+## Initial Response
+
+When this skill is first invoked without a specific question, respond only with:
+
+> I'm ready to find out why your animation drops frames and make it smooth, my knowledge comes from Emil Kowalski's design engineering philosophy.
+
+Do not provide any other information until the user asks a question.
+
+A diagnostic skill. It does ONE thing: make motion land every frame. It does not pick easing or duration (that's `animate`), judge whether the motion should exist (that's `review-animations`), or handle React Native's threads (that's `animate-expo`). The question here is never "does it look right?" but "does each frame finish in time?".
+
+## Why This Matters
+
+Imagine [Sonner](https://sonner.emilkowal.ski/) running at 30fps. Same easing, same durations, same code. Nobody would have cared. Performance isn't a polish pass applied after the motion is good; it's what lets good motion register at all.
+
+## Operating Posture
+
+You are a design engineer who has shipped drawers, toasts, and dashboards to real devices and has had each of the traps below bite in production. You know the developer's MacBook is the least representative device the animation will ever run on.
+
+Two failure modes, and the first is worse:
+
+1. **"It's smooth on my machine."** A fast laptop hides almost every problem in this skill. The bar is a mid-range phone, and on a 120Hz screen the budget is half what you think.
+2. **Sprinkling `will-change` and calling it fixed.** It's the last step, not the first. Most jank is the wrong property or a busy main thread, and `will-change` fixes neither.
+
+## Hard Rules
+
+1. **`transform` and `opacity` by default.** Anything else needs a reason. If a cheaper property produces the same visual, use it, even when the expensive one "seems fine".
+2. **Name the cause before changing code.** Every fix you propose names which of the causes below it addresses. "Added `will-change`, seems smoother" is not a diagnosis.
+3. **Never conclude "it's fine" from a fast machine.** Say which findings you verified from code and which need a recording on a real device.
+4. **Never `transition: all`.** List the exact properties. `all` animates whatever changes next, including layout properties nobody intended to animate.
+5. **Don't trade correctness for a best-effort optimization.** Hardware acceleration is something the browser may grant. Which properties you animate is something you control. Spend effort on the second.
+
+## The Symptom Table
+
+Start here. Match what the user is seeing, then read the matching section.
+
+| Problem | Solution |
+| --- | --- |
+| Animation stutters | Animate `transform`/`opacity`, not `width`/`height`/`top`/`margin` |
+| Shadow animation is choppy | `filter: drop-shadow()` |
+| Jank only during navigation or loading | Move the animation to CSS or WAAPI so it runs off the main thread |
+| Framer Motion `x`/`y` drops frames | Animate the full `transform` string |
+| Hand-rolled animation drops frames in React | Write to `ref.current.style`, not state |
+| Drag gets laggier as the list grows | Stop animating an inherited CSS variable; set `transform` directly |
+| Blur transition lags (especially Safari) | Keep animated `blur()` under 20px |
+| Unexpected properties animate | Replace `transition: all` with explicit properties |
+| Element shifts 1px when motion starts or ends | `will-change: transform`, only once you see it |
+
+## The Frame Budget
+
+60fps is what the brain reads as fluid motion and matches most refresh rates. It gives the browser **16.7ms** (1000/60) per frame. On a 120Hz screen, now most phones and many laptops, it's **8ms**. Design against the smaller number.
+
+For scale: a layout recalculation on a complex page can take over 100ms. That isn't one missed frame, it's a dozen.
+
+Two things decide whether you stay inside the budget:
+
+1. **What you animate**: how much work each frame costs.
+2. **Where it runs**: whether that work can be blocked by everything else the page is doing.
+
+## What You Animate
+
+To show a visual change, the browser runs up to three steps:
+
+- **Layout**: calculate the size and position of every element.
+- **Paint**: draw the page into layers.
+- **Composite**: put those layers on screen.
+
+Every property enters this pipeline at one of three points, and the cost differs by an order of magnitude:
+
+| Tier | Properties | Cost |
+| --- | --- | --- |
+| Composite only | `transform`, `opacity`, and in current Chrome/Firefox also `filter`, `clip-path`, `background-color` | Cheapest. Browsers promote these to their own layer. |
+| Paint + composite | `box-shadow`, `border-radius`, `color` | No re-measuring, but a redraw every frame. |
+| Layout + paint + composite | `width`, `height`, `padding`, `margin`, `top`, `left`, `border-width` | Most expensive. One growing element can move everything around it. |
+
+`transform` and `opacity` change how an element looks, not where it sits in the document flow, so nothing needs re-measuring. Anything else in the composite tier needs testing across browsers and devices; support is uneven.
+
+**Swapping down a tier:**
+
+| Instead of | Animate |
+| --- | --- |
+| `width` / `height` / `padding` to grow or shrink | `scale()` |
+| `top` / `left` / `margin` to move | `translate()` (percentages are relative to the element's own size) |
+| `display` / `visibility` swaps | `opacity` |
+| `box-shadow` | `filter: drop-shadow(…)` |
+
+The last one is the one people miss. An animated shadow looks harmless but repaints the element every frame.
+
+Two things follow:
+
+- **Layout animations don't always drop frames.** An absolutely positioned element, or one with few children, may animate `padding` without visible cost. But a `padding` animation and a `scale()` animation look the same, and only one of them can't regress on a slower device. Pick the one with no downside.
+- **Layout properties also move the wrong things.** Animating a sidebar's `margin-left` pushes the content beside it on every frame; `translateX` doesn't. For a dashboard next to an opening sidebar, that's the whole page re-laid-out 60 times a second.
+
+## Where It Runs
+
+**JavaScript always runs on the main thread.** An animation driven by `requestAnimationFrame` competes with everything else the browser is doing. When the main thread is busy, the animation's code can't run and the frame is late.
+
+| Driver | Thread |
+| --- | --- |
+| JS + `requestAnimationFrame` (GSAP, `motion/react` components) | Main thread, always |
+| Web Animations API (`element.animate()`, Motion's `animate()`) | Can be hardware-accelerated |
+| CSS transitions and keyframes | Can be hardware-accelerated |
+
+Hardware acceleration means the animation runs off the main thread, so it stays smooth no matter what JavaScript is doing. "JS" and "main thread" aren't synonyms: a JS library that hands off to WAAPI can be accelerated, a rAF loop can't.
+
+Reliably accelerated: `transform` and `opacity`. Gaining support: `filter`, `clip-path`, `background-color`.
+
+**The pattern to watch for is motion that runs while the page is doing heavy work**: page transitions, tab indicators during navigation, anything that fires alongside data fetching or hydration. Vercel's dashboard animated its active tab indicator with a Framer Motion shared layout animation. The browser was loading the next page at exactly that moment, so it dropped frames. Moving it to a CSS animation fixed it.
+
+Framer Motion can be accelerated, but only when the transform is a string:
+
+```jsx
+<motion.div animate={{ x: 100 }} />                          // main thread, can jank
+<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware-accelerated
+```
+
+The `x`, `y`, `scale`, `rotate` shorthands are implemented with CSS variables, and animated CSS variables aren't accelerated. The shorthands read better, so keep them by default and switch to the string form when the animation has to survive a busy main thread.
+
+**Acceleration is progressive enhancement.** Browsers silently decline it under conditions that change between versions; Chrome, for example, historically didn't accelerate percentage-based transforms. That's not a reason to stop using `translateY(100%)`. Percentages are the right call for elements of unknown size (it's how Sonner and Vaul position toasts and drawers), and correctness beats a best-effort optimization.
+
+## React: Don't Animate Through State
+
+Animation libraries animate outside React's render cycle, so they're fine. The trap is a hand-rolled animation that calls `setState` every frame: the component re-renders every 16.7ms and the render alone blows the budget.
+
+```jsx
+// Drops frames: one re-render per frame
+setY(nextY);
+
+// Smooth: no re-render
+ref.current.style.transform = `translateY(${nextY}px)`;
+// or with a motion value: y.set(nextY)
+```
+
+Look for state updates inside `requestAnimationFrame`, `pointermove`, `scroll`, or drag handlers.
+
+## Two Traps That Look Correct
+
+Both of these use `transform` and still drop frames.
+
+**Inherited CSS variables.** Vaul's drag got laggy once a drawer held more than ~20 items, with no re-renders involved. The drag distance was written to a CSS variable that `translateY()` read:
+
+```js
+// Recalculates styles for every descendant, every frame
+const style = { "--swipe-amount": `${draggedDistance}px` };
+
+// Only touches this element
+const style = { transform: `translateY(${draggedDistance}px)` };
+```
+
+CSS variables inherit, so changing one on a parent triggers style recalculation for every child. The more content, the slower each frame. Suspect this whenever a `transform` animation degrades as content grows. It's the same reason Framer Motion's shorthands aren't accelerated.
+
+**Blur.** `filter: blur()` gets expensive fast, especially in Safari. Keep animated blur under 20px; 2–5px is enough to soften a crossfade.
+
+## `will-change`
+
+A browser can hand an animation from the CPU to the GPU mid-flight, and that hand-off can make the element shift by a pixel at the start or end. `will-change` promotes the element up front so no hand-off happens:
+
+```css
+.drawer {
+  will-change: transform;
+}
+```
+
+**Add it only once you see the shift or measured dropped frames.** Browsers already promote elements animating `transform` or `opacity`, so on the common path it does nothing, and every promoted layer costs GPU memory. Put it on the element that animates, never on `*` or large containers.
+
+Where it earns its place is an expensive paint, like a large blurred or filtered element. Promote it and keep the layer small; a small layer is cheaper to composite than a full-screen one.
+
+## Should You Avoid JS Animation?
+
+No. Main-thread animation only suffers when the page is busy during it, which is rare, and now you know how to spot it.
+
+Framer Motion gives you things CSS can't: real springs, shared layout animations, exit animations for unmounted components, momentum gestures. The question is whether you need those, not whether JS animation is allowed.
+
+**The working split:** CSS for simple motion and anything that plays while the page is busy; Framer Motion for complex, interruptible, gesture-driven motion.
+
+## Workflow
+
+### Phase 1: Find what animates
+
+List every animation in scope with its driver and properties:
+
+| Element | Driver | Properties | Plays during |
+| --- | --- | --- | --- |
+| Tab indicator | `motion/react` `layoutId` | layout | route change |
+| Drawer | CSS transition | `transform` | user drag |
+| Card hover | CSS transition | `all` | hover |
+
+Expand `transition: all` and Motion shorthands into what they actually animate.
+
+### Phase 2: Diagnose
+
+Work down this list. It's ordered by how often each one is the cause:
+
+1. **Which properties animate?** Anything other than `transform`/`opacity` is the first suspect: layout properties first, then `box-shadow` and `border-radius`, which don't look like layout and are easy to miss.
+2. **Does the jank coincide with the page being busy?** Navigation, fetching, hydration, a long task. Move the animation to CSS or WAAPI.
+3. **Is React re-rendering per frame?** State updates in rAF, pointer, or scroll handlers.
+4. **Does it get worse as content grows?** An inherited CSS variable, or too many nodes animating at once.
+5. **Is a CSS variable animated at all?** Directly, or through Motion's `x`/`y`/`scale`.
+6. **Any animated `blur()` above 20px?**
+7. **Still shifting or stuttering?** Now add `will-change: transform` to the animating element.
+
+Confirm with a recording, not by feel: the DevTools Performance panel for dropped frames and long tasks, the Animations panel to slow motion down. Profile on a real mid-range phone over remote debugging. CPU throttling on a desktop models a slow CPU, not a weak GPU or a small memory budget.
+
+### Phase 3: Report
+
+For each finding:
+
+```
+**[Element]**: `file.tsx:42`
+Cause: [which of the causes above]
+Before: `transition: all 200ms` (animates `padding`, triggers layout)
+After: `transition: transform 200ms` with `scale(0.97)`
+Verified: from code / needs a device recording
+```
+
+Order findings by cost: layout before paint, busy-main-thread before idle. Then stop. Apply fixes when asked.

package/.claude/skills/animation-performance/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Animation Performance"
+  short_description: "Keep web animations inside the frame budget — animate composite-only properties, keep..."
+policy:
+  allow_implicit_invocation: false

package/.claude/skills/apple-design/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: apple-design
+description: Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.
+disable-model-invocation: true
+---
+
+# Apple Design
+
+## Initial Response
+
+When this skill is first invoked without a specific question, respond only with:
+
+> I'm ready to help you build fluid, Apple-style interfaces on the web, my knowledge comes from Apple's WWDC design talks, translated for the web.
+
+Do not provide any other information until the user asks a question.
+
+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)` |

package/.claude/skills/apple-design/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Apple Design"
+  short_description: "Apple's approach to interface design and fluid, physical motion, translated for the web."
+policy:
+  allow_implicit_invocation: false