design-interactions

name	design-interactions
description	Design the interactive UX micro-patterns of a full-stack Rails 8.1 Hotwire app — modals/dialogs, drawers, dropdowns, tabs, toast/flash notifications, inline editing, loading/skeleton states, empty states, and infinite scroll — built with Turbo Frames/Streams and Stimulus. Menu-driven with a Recommended default per menu (native <dialog> + Turbo Frame + Stimulus for overlays, Stimulus auto-dismiss + Turbo Stream for toasts, Turbo loading states + skeletons for feedback). Owns the visual/UX shape of these patterns and the accessibility contract each must meet (the canonical a11y rules live in design-accessibility); the Turbo/Stimulus plumbing is rails-hotwire. Detects the installed UI kit and Hotwire wiring first, then verifies the interaction works and is keyboard/screen-reader accessible. Apply when building any of these patterns. Web apps only.
metadata	{"owner":"rails-design","status":"stable"}
user-invocable	true
argument-hint	[pattern]

design-interactions

Purpose

Owns the interactive UX micro-patterns that make a Hotwire app feel responsive: modals/dialogs, drawers, dropdowns, tabs, toast/flash notifications, inline editing, loading/skeleton states, empty states, and infinite scroll. It owns the visual and UX shape of each pattern — what it looks like, how it behaves, and the accessibility it must meet — built on Turbo Frames/Streams and Stimulus. The plumbing (how Turbo Streams render, how Stimulus controllers wire up, broadcasting) belongs to ../rails-hotwire/; this skill is the design layer on top, and it defers every a11y rule to ../design-accessibility/.

When to Apply

Use this skill when the task is:

• A modal / dialog, drawer/off-canvas, dropdown menu, or tabs
• Toast / flash notifications (transient feedback)
• Inline editing (click-to-edit a field/row in place)
• Loading / skeleton states and optimistic feedback
• Empty states (zero-data, no-results, first-run)
• Infinite scroll / load-more for feeds and long lists

Do not use this skill when the task is:

• The Turbo/Stimulus mechanics themselves (frame targets, stream actions, controller lifecycle) → read ../rails-hotwire/SKILL.md
• The component primitives (button, menu, card markup) → read ../design-components/SKILL.md
• Form layout and validation/error UX → read ../design-forms/SKILL.md (inline editing here links there for the field UX)
• Navigation layout (the navbar/drawer placement) → read ../design-layout-navigation/SKILL.md (this skill owns the drawer's open/close behavior)
• Tokens / theming → read ../design-foundations/SKILL.md
• The full ARIA / focus / keyboard spec → read ../design-accessibility/SKILL.md
• An API-only app — no interactions to design

Detect Before You Generate

grep -nE "api_only" config/application.rb               # api_only=true → stop
bundle list 2>/dev/null | grep -E "turbo-rails|stimulus-rails"      # Hotwire present (required)
ls app/javascript/controllers/ 2>/dev/null              # existing Stimulus controllers to reuse
grep -E "daisyui|flowbite" Gemfile.lock package.json 2>/dev/null    # UI kit may supply modal/drawer/tabs
grep -rlnE "turbo_stream|turbo-frame|<dialog|data-controller" app/views 2>/dev/null | head
grep -rnE "flash\[|render.*flash|toast" app/views app/controllers 2>/dev/null | head  # existing flash pattern

• Hotwire is required — these patterns assume turbo-rails + stimulus-rails. If missing, set them up via ../rails-hotwire/ first.
• Reuse existing Stimulus controllers instead of duplicating (a generic dialog/dismiss/toggle controller usually already covers several patterns).
• If a UI kit ships the pattern (daisyUI modal/drawer/dropdown/tabs, Flowbite JS), prefer its markup — but keep the a11y requirements from ../design-accessibility/.

Menu

Three menus via AskUserQuestion; defaults marked Recommended. Ask unless detected.

Overlay mechanism (modals / drawers)

Option	One-line trade-off	Deep dive
Native <dialog> + Turbo Frame + Stimulus (Recommended)	Browser-native focus trap, Esc, backdrop + inert; server-rendered content lazy-loaded into a frame. Least JS, best a11y.	modals-dialogs.md
UI-kit JS (daisyUI/Flowbite)	Prebuilt modal/drawer with its own toggle JS; fast, ties you to the kit's behavior/markup.	drawers-dropdowns-tabs.md
Custom Stimulus overlay	Hand-built role="dialog" overlay; full control, you own focus trap + Esc + scroll lock.	modals-dialogs.md

Toast / flash notifications

Option	One-line trade-off	Deep dive
Stimulus auto-dismiss + Turbo Stream (Recommended)	Flash renders into a live region, a Stimulus controller auto-dismisses; Turbo Stream can push toasts after actions/broadcasts.	toasts-flash.md
Static flash (no JS)	Server-rendered flash banner, dismissed on next navigation; simplest, no transient/stacked toasts.	toasts-flash.md

Loading / feedback

Option	One-line trade-off	Deep dive
Turbo loading states + skeletons (Recommended)	Drive aria-busy/[data-turbo-...] styling + skeleton placeholders that match final layout; no layout shift.	loading-skeleton-states.md
Spinners	A single spinner during requests; simple, but jumpier and less informative than skeletons.	loading-skeleton-states.md

Decision Flow

• Overlays: prefer native <dialog> — it gives focus trap, Esc, and backdrop inert for free, which is most of the a11y work. Load contents lazily via a Turbo Frame. Use the UI kit's modal/drawer when you're already all-in on it; reach for a custom Stimulus overlay only when neither fits. Whatever you pick, the a11y contract (focus on open, trap, return focus on close) comes from ../design-accessibility/.
• Toasts: Stimulus auto-dismiss + Turbo Stream is the flexible default — transient, stackable, and pushable from server actions or broadcasts; render them into a persistent live region so screen readers hear them. Use the static flash when you don't need transient/stacked feedback.
• Loading: skeletons that mirror the final layout beat spinners — they prevent layout shift and feel faster. Drive them off Turbo's aria-busy. Use a spinner for small, in-place actions.
• Inline editing swaps a display partial for a form via a Turbo Frame, and must manage focus on enter/save/cancel (inline-editing.md); the field UX itself is ../design-forms/.
• Empty states are a design surface, not an afterthought — every list/search/dashboard needs a designed zero-state with a clear next action (empty-states.md).
• Infinite scroll suits feeds; keep a paginated fallback for findability/SEO and announce appended content. Pagination choice is ../design-layout-navigation/.

Problem → Reference

Task	Read
Modal / dialog (native <dialog> or custom), lazy-loaded via Turbo Frame	references/modals-dialogs.md
Drawer/off-canvas, dropdown menu, tabs (kit or Stimulus)	references/drawers-dropdowns-tabs.md
Toast / flash notifications, auto-dismiss, live regions, Turbo Stream push	references/toasts-flash.md
Inline / click-to-edit a field or row in place	references/inline-editing.md
Loading, skeleton placeholders, optimistic/busy states	references/loading-skeleton-states.md
Empty states: zero-data, no-results, first-run	references/empty-states.md
Infinite scroll / load-more with Turbo Streams	references/infinite-scroll.md

Verify

An interaction is "done" when it works, is keyboard-operable, and announces itself:

bin/rails server -d && sleep 3
curl -fsS localhost:3000/ -o /tmp/p.html
grep -qE "<dialog|role=\"dialog\"|data-controller" /tmp/p.html && echo "✓ interactive markup present"
grep -qE "aria-live|role=\"status\"|role=\"alert\"" /tmp/p.html && echo "✓ live region for toasts/updates"
kill "$(cat tmp/pids/server.pid)"
# System test exercises the behavior + focus (Turbo needs a JS driver — ../rails-testing/):
bin/rails test test/system 2>/dev/null || bundle exec rspec spec/system

Manually: open the overlay with the keyboard (focus moves in, Esc closes, focus returns), fire a toast (it announces and auto-dismisses), and confirm skeletons don't shift layout. Then route to ../design-accessibility/ for the focus/ARIA audit and ../design-visual-qa/ to lock the behavior with tests.