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 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:

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

Selection and form controls

Navigation and wayfinding

Overlays and surfaces

Content, data, and gestures

Ambience and scroll

4. Mechanics rules

These sharpen the shared axioms for interaction work; none of them replace the style skill.

• Motion serves meaning. Every animation maps to a real interaction, state change, or affordance. A hover that changes nothing is slop — beui.dev patterns all animate state, never decoration.
• Reduced motion is part of the component, not an afterthought. Every beui.dev component ships a reduced-motion path; match that bar. Web: prefers-reduced-motion: reduce disables or replaces every transform-based animation (the loader pattern's opacity-pulse swap is the model). React Native: respect the system reduce-motion setting.
• GPU-composited properties only — transform, opacity, filter. Never animate layout properties; morph layout through shared-layout (layoutId) or measured height primitives instead.
• Springs move things; easings tint things. Spatial movement (position, scale, layout morphs) wants spring physics so it stays interruptible and retargetable. Color, opacity, and blur want short duration + easing. Do not put a fixed-duration tween on a gesture-driven surface.
• Interruptibility is non-negotiable. A press, hover-out, or route change mid-animation must retarget smoothly, never queue or block input. This is the practical reason beui.dev uses springs — copy that property, not just the bounce.
• Motion never regresses input latency or stream rendering. Measure with the perfection ruleset when in doubt; a virtualized list's measurement contract beats a pretty reveal.
• Library choice is a project decision, not a default. beui.dev assumes Motion (motion.dev) + Tailwind. If the project already has a motion stack, adapt the mechanism to it. If it has none: CSS transitions/WAAPI cover micro-interactions; adding a library is justified by shared-layout or spring-physics needs and gets recorded (with bundle cost) in DESIGN.md. Check package.json before importing anything.

5. DESIGN.md integration

design-system-architecture.md defines a Motion & Interaction section in every DESIGN.md. This file feeds it:

• Extracted spring configs, durations, and easings land there as named tokens before components use them.
• Each shipped interaction traces to a catalog pattern (or a recorded novel mechanism) plus its reduced-motion behavior.
• New reusable interaction patterns (used 2+ times) get documented back into DESIGN.md Section 5 with their states, like any other primitive.

6. Verification

Interaction work is verified through /visual-qa with motion actually driven and inspected — hover, press, open/close, swipe, and theme transitions exercised on the rendered surface, plus a reduced-motion pass (emulate prefers-reduced-motion: reduce) proving the fallback exists. Timing-sensitive changes record a short screen capture, not just stills.