implement-ui-interaction

UI Interaction Implementer

상호작용의 시각 효과보다 입력, widget 상태, 포커스, 피드백과 복구 계약을 먼저 구현한다. pointer에서만 작동하는 데모가 아니라 keyboard, touch와 보조기술에서도 같은 과업을 완료할 수 있게 한다.

시작 절차

1. 저장소 지침과 현재 diff를 확인하고 framework, 렌더링 방식, package manager, browser 범위, 기존 primitive·상태 관리·테스트 도구를 읽는다.

2. 대상 UI를 실행하거나 코드로 확인한다. 관찰하지 않은 keyboard, focus, touch와 보조기술 동작을 사실처럼 단정하지 않는다.

3. 상호작용의 주 결과를 분류한다.

   • composite-widget: Dialog, Menu, Tabs, Combobox, Tooltip, Popover
   • collection-navigation: Carousel, list navigation, reorder
   • direct-manipulation: drag, swipe, pinch, pan, resize
   • floating-surface: anchor positioning과 collision 처리

4. 구현 전에 다음 계약을 짧게 고정한다.

   사용자 과업과 완료 상태:
   trigger·entry·exit:
   상태의 진실 원본:
   keyboard·focus·screen reader:
   pointer·touch·gesture와 동등한 대안:
   disabled·invalid·empty 상태:
   dismiss·cancel·recovery:
   responsive·zoom·reduced-motion:
   fallback과 성공·반증 기준:
   

5. ../uiux-advisor/scripts/search_toolkits.py --capability <capability> --surface <surface> --ecosystem <ecosystem>으로 후보를 찾는다.

6. 도구 선택은 references/interaction-toolkit-selection.md, widget 계약과 QA는 references/interaction-contract-and-qa.md를 읽어 적용한다.

도구 선택 규칙

• 먼저 semantic HTML과 현재 프로젝트의 component·primitive로 해결한다.
• focus management와 keyboard pattern이 복잡한 widget은 기존 Base UI, Radix, React Aria, Ark UI 또는 같은 역할의 검증된 primitive를 우선한다.
• Floating UI는 anchor 좌표와 collision 문제를 해결하는 positioning engine으로 사용한다. 그것만으로 Dialog, Menu, Tooltip의 semantics가 완성된다고 가정하지 않는다.
• Carousel은 scroll snap이나 기존 component가 충분한지 먼저 확인하고, 세밀한 headless 제어가 필요하면 Embla, 다수의 내장 효과가 실제 요구면 Swiper를 검토한다.
• drag·swipe·pinch 인식이 복잡하면 @use-gesture를 검토하고, 물리 반응이 핵심이면 React Spring 또는 기존 Motion 도구와 결합한다.
• 목록 추가·삭제·재정렬의 작은 layout 변화는 AutoAnimate를 검토하되 focus, 읽기 순서와 완료 상태를 animation에 맡기지 않는다.
• 이미 설치된 적합한 도구가 있으면 새 의존성을 추가하지 않는다. 도입 전 현재 공식 API, 설치 버전, license, bundle, SSR·hydration과 제거 비용을 확인한다.

구현 규칙

입력과 포커스

• native element로 가능한 동작을 div와 임의 ARIA로 다시 만들지 않는다.
• 보이는 label, accessible name, role, value와 state를 실제 동작과 동기화한다.
• trigger에서 surface로 들어가는 focus, 내부 탐색, Escape·외부 dismiss, 닫힌 뒤 focus 복귀를 명시한다.
• hover에만 정보나 행동을 숨기지 않는다. focus, click 또는 touch에서 동등하게 발견 가능하게 한다.
• drag·swipe·pinch가 유일한 조작이 되지 않게 button, keyboard, direct input 같은 동등한 경로를 제공한다.
• screen width로 입력 장치를 추정하지 않는다. coarse pointer, keyboard와 touch가 섞인 환경을 처리한다.