Style Gallery.
Design Engineering가이드실험적 가이드

Dialog와 Popover의 동작 정하기

Native Interaction Contracts

컴포넌트 선택부터 키보드, 포커스 복귀, 닫기 동작까지 연결합니다.

이 자료로 구현하기

원문 주소와 버전이 포함된 요청문입니다. 복사한 뒤 만들 화면과 요구사항을 채워 에이전트에게 전달하세요.

화면을 여는 동작부터 닫은 뒤의 포커스까지 하나의 계약으로 정합니다.

FROM PRINCIPLE TO PRACTICE

이 원리로 만든 예제 48

예제를 열어 동작을 살펴보고, 코드와 함께 이 문서의 원리를 확인해 보세요.

  • 탐색

    File Tree

    • 파일 모양과 실제 위젯 모델

      File Tree는 중첩 Radix Accordion으로 폴더를 열고 파일 button을 선택합니다. 기본 정렬은 폴더 우선·영어 숫자 비교이며 초기 button ID의 상위 경로를 펼칩니다. tree 역할과 그에 따른 전체 키보드 탐색을 구현했다고 이름만으로 추정해서는 안 됩니다.

    예제·코드 보기
  • 카드

    Hero Video Dialog

    • 영상 오버레이의 모달 계약

      HeroVideoDialog는 button으로 열지만 열린 표면은 role=button인 motion.div입니다. 바깥 클릭과 그 요소의 키 입력으로 닫으며 닫기 아이콘 버튼의 별도 이름·초점 이동·트랩·복귀는 선언되지 않습니다. iframe 플레이어가 이 계약을 대신하지 않습니다.

    예제·코드 보기
  • 버튼

    Rainbow Button

    • asChild가 바꾸는 제어의 의미

      RainbowButton은 기본 button 대신 asChild일 때 Radix Slot에 클래스를 넘깁니다. 기본 스타일에는 disabled 포인터 차단과 focus-visible이 있지만 링크 자식의 비활성 행동까지 정하지는 않습니다. 데모는 기본 버튼·문구만 제공합니다.

    예제·코드 보기
연결된 예제 45개 더 보기
원문 가이드 ENGLISH

Primary role: product component selection and behavior guide.

Repository Boundary

This guide extends the Component Contract with source-backed decisions for native HTML and custom composites. It owns product behavior, not reusable Layout CSS. The shared accessibility evidence contract remains the authority for evidence claims.

Reusable Method

Write the user's task, the information being exposed, whether background interaction remains available, and what closes the surface. Choose semantics before appearance. Then assign keyboard, focus, pointer, and state ownership. A floating rectangle is insufficient information to choose a component.

Mechanisms And Obligations

Source Bounded finding Consumer responsibility
HTML interactive elements details is a disclosure; dialog supports distinct modal and nonmodal presentation. showModal() participates in the modal/inert model. Choose the right behavior, accessible name, initial focus, and close policy.
HTML popover The attribute adds presentation behavior to elements with their own semantics; custom menu keyboard behavior still needs implementation. Select a semantic element or role and implement its interaction contract.
APG modal dialog The pattern describes contained keyboard navigation, focus placement, and return. Initial focus depends on content and task. Test focus with long content and a missing invocation control.
APG menu button A menu button opens a menu of actions or functions with the menu keyboard model. Do not assign menu roles solely because links appear in a dropdown.
APG combobox A combobox has a value and a popup with defined keyboard/state relationships. Specify text editing, suggestion navigation, selection, and escape separately.
APG disclosure The disclosure control exposes expanded/collapsed state and toggles associated content. Keep the control name, state, and controlled content consistent.
WAI-ARIA 1.2 aria-disabled communicates disabled semantics. It does not implement event suppression. Prevent disallowed activation in the application's actual event paths.

HTML is a Living Standard; WAI-ARIA 1.2 is a Recommendation; APG is informative implementation guidance. Sources were inspected 2026-09-21. Pattern examples do not establish support for an unspecified browser and assistive-technology combination.

Selection Questions

User need Starting point Question that can change the choice
Reveal optional explanatory content Native disclosure Does this actually switch mutually exclusive views or choose a value?
Complete a bounded task while background interaction is unavailable Modal dialog Must the user compare or interact with the background during this task?
Temporarily expose nonmodal related content Semantically appropriate element with popover behavior Is the content a menu, a list of links, a form, or plain information?
Invoke commands from a compact control Menu button and menu behavior Are these ordinary navigation links better served by ordinary link navigation?
Edit a value with selectable suggestions Combobox Is an ordinary input, select, or separate search-result list sufficient?

These are local selection heuristics. Similar visuals can correctly produce different DOM, focus, and keyboard behavior.

Worked Contract: Edit A Record

The user opens an editor from a list row. The consumer chooses a modal because this task intentionally suspends interaction with the list. Save commits a submitted snapshot; Close requests dismissal; an unsaved-change decision belongs to the state owner.

Stage Decision to record Adversarial case
Open Accessible name and initial focus target Long introduction would be scrolled out of view by focusing the first input.
Edit Draft lifetime and field-error relationship Background data refresh replaces the edited row.
Save Request identity and pending activation rule Enter and a pointer click arrive before the request settles.
Dismiss Which paths request close and which discard changes Escape, an outside interaction, and an explicit Cancel have different intended meanings.
Return Valid focus destination after closing The original row was deleted or filtered out.

Compose submitted snapshot, single flight, and unsaved navigation as needed. Animation completion cannot authorize a write or decide whether a draft is disposable.

Preserve Editing Inside Composites

An editable combobox has at least two responsibilities: editing text and navigating candidate options. Specify when Arrow keys move a candidate, when Enter accepts it, and when Escape dismisses suggestions while retaining the typed text. During IME composition, those keys may belong to the input method; follow Text Input And Internationalization.

A disabled-looking control needs a deliberate discoverability policy. Native disabled and aria-disabled have different behavior; choose which focus and activation behavior the task requires, and explain why an action is unavailable without relying only on color.

Opinionated Guidance

Prefer native semantics when they fit the task, and build the smallest custom behavior that remains necessary. Name the semantic reason for every role override. Treat multiple open surfaces as an ownership question: which surface receives Escape, where focus stays, and which state survives dismissal.

Platform-Specific Guidance

Native HTML behavior, browser support, and accessibility mappings are separate from framework component names. Record the browser, framework adapter, and assistive technology used in verification. A native platform's “popover” does not settle the web contract; compare Interaction Semantics and Platform Adaptation.

Unsupported Absolutes

Top-layer presentation does not imply modality. A role does not supply keyboard handlers. Native HTML does not remove the need for an accessible name or target verification. Escape does not intrinsically mean “discard all work.”

Verification Contract

The proposed matrix includes keyboard-only opening and closing, forward/backward Tab, active popup navigation, IME input, a removed opener, nested surface dismissal, long content, zoom, and reduced motion. Check visible behavior, DOM state, accessibility semantics, and the actual announcement path separately.

Record the selected widget model and expected key behavior before testing. Passing a self-written handler test establishes that handler's behavior, not conformance with APG or the platform. Compare observed behavior with the cited contract. No browser or screen-reader execution is claimed by this guide. Re-review when the widget model, browser, or focus owner changes.

Source, License, And Attribution

Locally authored synthesis of the official sources linked above, inspected 2026-09-21. No upstream examples or implementation are reproduced. consumer_reference: not_applicable because this guide selects no consumer component record.

IA Navigation

Parent: Design Engineering. Next: Text Input And Internationalization.

Design Engineering 전체 ↗