interaction-skill

# Interaction Mechanics — beui.dev-Anchored

Style skills decide how a surface looks. This file decides how it *moves and responds* — spring physics, layout morphs, enter/exit orchestration, gesture feel, and reduced-motion discipline. It stacks on top of any Layer A style skill and any Layer B brand, exactly like `layout-skill.md`, and adds ZERO visual direction: color, type, and material still come from the style skill and `DESIGN.md`.

Load this whenever the deliverable includes interaction feel: micro-interactions, animated components, transitions, hover/press/focus/state feedback, gestures, loading/success/error morphs, animated tabs/menus/modals/drawers/toasts — or the user says "make it feel alive", "polish the interactions", "add micro-interactions".

## 1. The reference contract — never design an interaction from memory

[beui.dev](https://beui.dev) is the interaction benchmark: free, open-source animated React components (Motion + Tailwind CSS) where every component ships reduced-motion support and the full TypeScript source is one `curl` away. Improvised interaction design produces slop motion the same way freestyled styling produces generic SaaS slop, and the fix is the same: consult the reference before designing.

The contract, in order:

1. **Find the nearest pattern** in the catalog (section 3). The live catalog is `https://beui.dev/llms.txt`; refresh from it when a pattern seems missing from the tables below.
2. **Read its real source** through the recipe (section 2). Never guess spring values, exit orchestration, or gesture thresholds from a preview description.
3. **Extract the mechanism**, not the pixels: the spring config, the layout strategy (`layoutId` shared layout vs height morph vs clip-path), what animates in what order on enter/exit, where blur crossfades sit, and what the reduced-motion path swaps to.
4. **Adapt to the project.** Concrete durations, easings, and spring params come from the project `DESIGN.md` Motion & Interaction section. Where beui.dev and `DESIGN.md` disagree, `DESIGN.md` wins. A value that is not in `DESIGN.md` gets added there first, then used.
5. **No matching pattern?** Compose from the nearest two, or state explicitly that the interaction is novel and record its mechanism in `DESIGN.md` before building it.

## 2. Consultation recipe (curl-only, verified 2026-07)

All endpoints are public, no auth, no browser:

```bash
curl -s https://beui.dev/llms.txt                          # full catalog: every component + one-line feel
curl -s https://beui.dev/r                                 # registry index (JSON): slugs, categories, endpoints
curl -s https://beui.dev/r/{slug}                          # component detail (JSON): files, dependencies, dates
curl -s https://beui.dev/r/{slug}/raw                      # component source (TypeScript) — the thing to read
curl -s https://beui.dev/components/{category}/{slug}.md   # component doc page as markdown
```

Categories are `motion` (primitives) and `blocks` (composed patterns). When the user wants the component itself rather than the mechanism, a shadcn-style item registry exists at `https://beui.dev/r/{slug}.json`. Read source to learn; do not vendor beui.dev files into reference docs, and do not paste whole components into a project when only the mechanism is needed.

## 3. Catalog — pattern routing map

### Buttons, state feedback, and progress

| Pattern (slug) | Mechanism | Reach for it when |
|---|---|---|
| `button` | Spring press; StatefulButton idle → loading → success/error with blur-swap slots and morphing width; MagneticButton cursor pull | Any submit/CTA that has async states — never leave a button state-less |
| `action-swap` | Text/icon swap with blur motion | Copy → check, send → stop, any label that changes meaning in place |
| `expanding-arrow-button` | Expanding, hold-to-confirm, and slide CTA interactions | Expressive marketing CTAs, destructive hold-to-confirm |
| `animated-badge` | Animated state icons, pulse feedback | Connection/status dots, live activity indicators |
| `loader` | 17 variants incl. terminal-ascii; reduced motion swaps every transform for an opacity pulse | Any loading state; copy its reduced-motion contract even when hand-rolling |
| `otp-input` | Gliding focus ring, per-slot digit roll, error shake, success check draw | Code entry, verification flows |
| `file-upload` | Progress rows, retry/remove, reduced-motion-safe state changes | Upload queues, long-running item lists |
| `feedback-widget` | Trigger morphs into a popup with sending/success/retry states | Corner feedback affordances, inline report flows |

### Selection and form controls

| Pattern (slug) | Mechanism | Reach for it when |
|---|---|---|
| `switch` | Spring-driven thumb with press feedback | Boolean toggles |
| `checkbox` | Draw-on checkmark, indeterminate support | Multi-select, tree selection |
| `radio` | Gliding `layoutId` indicator dot | Single-select groups |
| `input` | Label, icons, error shake, success check draw | Validated text entry |
| `select` | Panel bouncily unfolds from the trigger; Morph variant grows the trigger into the panel | Dropdown selection with spatial continuity |
| `range-slider` | Bouncy vertical-bar thumb gliding between snapped steps | Stepped value entry |
| `wheel-picker` | iOS-style 3D drum on native momentum scroll with notch snap | Date/time or option drums, mobile-feel pickers |
| `availability-scheduler` | Per-day spring toggles, blur-slide range add/remove | Schedule/slot editors |

### Navigation and wayfinding

| Pattern (slug) | Mechanism | Reach for it when |
|---|---|---|
| `tabs` | Pill/segment/underline with a spring `layoutId` indicator | Tab bars, view-mode selectors |
| `expandable-tabs` | Active icon tab expands to a labelled pill; panel morphs height, slides direction-aware | Compact tab bars with rich panels |
| `shared-layout-bg` | Pill glides between hovered items via shared layout, blur enter/exit | Sidebar/menu hover and active s