애플리케이션 안에서 독립적으로 떠 있는 UI 만들기
작성일:2026.10.24|수정일:2026.11.03|조회수:4

<ilokesto-form-devtools>라는 이름을 얻었다고 해서 그 안의 UI까지 독립되는 것은 아니다. 애플리케이션에 button { border: 0 } 같은 전역 스타일이 있다면 런처 버튼이 뜻밖의 모습으로 바뀔 수 있고, 반대로 Devtools가 쓰는 .panel 규칙이 애플리케이션의 패널을 건드릴 수도 있다. 클래스 이름 앞에 긴 접두사를 붙이고 !important를 늘려도 충돌 확률만 낮출 뿐, 어디까지가 누구의 DOM과 CSS인지 정해 주지는 못한다.
Form Devtools는 이 경계를 Shadow DOM으로 만든다. 다만 처음에는 나도 Shadow DOM을 “컴포넌트 안을 완전히 봉인하는 기능”에 가깝게 생각했는데, 그렇게 이해하면 절반만 맞는다. DOM 질의와 CSS 선택자는 경계에서 멈추지만, 상속되는 CSS 값과 이벤트처럼 의도해서 통과시킬 수 있는 것들도 있다. 중요한 것은 전부 막는 일이 아니라 무엇을 막고 무엇을 공개할지 정하는 일이다.
화면 한 덩어리 안에 두 트리가 있다
Shadow DOM을 이해하려면 먼저 위치를 나눠야 한다. 문서에 놓인 <ilokesto-form-devtools>는 shadow host이고, host에 연결된 별도의 루트는 **shadow root**, 그 아래 런처와 패널은 shadow tree에 속한다. host의 일반 자식은 light DOM에 남는다. 둘은 화면에서 함께 보일 수 있지만 같은 DOM 트리는 아니다.
브라우저 API만으로 이 구조를 풀어 쓰면 다음과 같은 모양이다. Form Devtools의 실제 소스를 옮긴 코드는 아니고, attachShadow()가 host에 별도 루트를 연결한다는 점만 보여 주기 위한 예시다.
const host = document.createElement('ilokesto-form-devtools');const shadowRoot = host.attachShadow({ mode: 'open' });shadowRoot.innerHTML = ` <section class="panel">...</section> <button class="launcher" type="button">iF</button>`;브라우저 개발자 도구에서는 이 관계가 대략 다음처럼 보인다. 현재 Form Devtools는 light DOM 자식을 받지 않으므로 host 아래의 화면 구성은 열린 Shadow Root 안에 있다.
<ilokesto-form-devtools position="bottom-right"> #shadow-root (open) <section class="panel">...</section> <button class="launcher">iF</button></ilokesto-form-devtools>트리가 나뉘면 DOM 질의의 출발점도 나뉜다. document.querySelector('.launcher')는 문서의 light DOM만 찾기 때문에 위 버튼을 반환하지 않는다. 먼저 host를 찾고, 그 host에 연결된 Shadow Root에서 다시 질의해야 한다.
const host = document.querySelector('ilokesto-form-devtools');const launcher = host?.shadowRoot?.querySelector('.launcher');현재 구현의 Shadow Root는 open이다. 그래서 host.shadowRoot로 루트 참조를 얻을 수 있고, 실제 테스트도 element.shadowRoot?.querySelectorAll('.tab')처럼 내부 탭을 찾는다. 여기서 open은 Shadow DOM 경계가 사라진다는 뜻이 아니다. 바깥 자바스크립트가 그 경계를 명시적으로 건너 질의할 수 있다는 뜻이다. mode: 'closed'였다면 host.shadowRoot가 null을 반환했겠지만, 그 차이를 보안 기능으로 받아들이면 곤란하다. 같은 페이지에서 실행되는 코드를 서로 신뢰할 수 없는 영역으로 분리해 주는 장치는 아니기 때문이다.
CSS 선택자는 멈추지만 상속은 멈추지 않는다
DOM 질의와 마찬가지로 CSS 선택자에도 범위가 생긴다. 애플리케이션의 button, .tab, table 선택자는 shadow tree 안의 노드를 고르지 못한다. Shadow Root 안에서 선언한 .panel이나 table도 바깥 문서의 같은 이름을 가진 노드까지 퍼지지 않는다. Form Devtools가 .header, .content, .section처럼 다른 애플리케이션에서도 흔히 나올 법한 클래스 이름을 쓸 수 있는 이유다.
하지만 CSS 선택자가 멈춘다고 해서 계산된 스타일 값이 전부 초기화되지는 않는다. color, font-family, direction처럼 원래 상속되는 속성은 host를 거쳐 내부로 흐를 수 있다. 바깥의 button 선택자가 런처를 직접 고르는 것과, 런처가 host의 글꼴이나 색상을 상속받는 것은 다른 동작이다.
이때 안쪽 스타일에서 host를 가리키는 선택자가 :host다. Form Devtools의 경계 관련 스타일을 일반 CSS 형태로 옮겨 보면, host에서 도구 전체의 위치와 글꼴을 정하고 내부 버튼은 그 값을 상속받는다.
:host { position: fixed; display: flex; flex-direction: column; z-index: 2147483647; color: var(--ilokesto-devtools-text); font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;}button { color: inherit; font: inherit;}:host([position='bottom-right']) { right: 16px; bottom: 16px;}:host는 Shadow Root 안의 규칙이 바깥 문서 전체를 탐색하도록 허용하는 예외가 아니다. 자신을 품고 있는 host라는 한 접점만 선택한다. 바깥 CSS도 ilokesto-form-devtools를 선택해 같은 접점을 다룰 수 있으므로, Shadow DOM은 host까지 감추는 기능이 아니라 host 안쪽의 소유권을 나누는 기능에 가깝다.
CSS Custom Properties로 테마 통로를 남긴다
상속이 경계를 통과한다는 성질은 피해야 할 누수만은 아니다. CSS Custom Properties를 host에 선언하면 내부 DOM 구조와 클래스 이름을 공개하지 않고도 바깥에서 테마 값을 전달할 수 있다. Form Devtools는 여섯 개의 색상 값을 이 통로로 받는다.
:host { --ilokesto-devtools-accent: #7c3aed; --ilokesto-devtools-bg: #111318; --ilokesto-devtools-panel: #191c23; --ilokesto-devtools-border: #303541; --ilokesto-devtools-muted: #99a1b3; --ilokesto-devtools-text: #f5f7fb;}.launcher { background: var(--ilokesto-devtools-accent);}.panel { border: 1px solid var(--ilokesto-devtools-border); background: var(--ilokesto-devtools-bg);}애플리케이션은 .launcher가 버튼인지, 패널 안에 어떤 요소가 더 있는지 알 필요가 없다. host에서 지원하는 변수만 바꾸면 값이 shadow tree 안으로 상속된다.
ilokesto-form-devtools { --ilokesto-devtools-accent: #0ea5e9;}이 차이는 꽤 중요하다. 바깥 코드가 .launcher라는 내부 클래스에 의존하면 마크업을 바꾸는 순간 깨지지만, --ilokesto-devtools-accent를 공개된 조절점으로 유지하는 동안에는 내부 버튼 구조를 바꿀 수 있다. 물론 Custom Property라고 해서 전부 공개 API가 되는 것은 아니다. 현재 Form Devtools가 실제로 소비하는 값은 위 여섯 개이며, 어떤 이름을 계속 지원할지는 컴포넌트가 약속해야 한다.
slot과 ::part는 필요한 만큼만 여는 통로다
Shadow DOM에는 Custom Properties 말고도 경계를 선택적으로 잇는 방법이 있다. slot은 light DOM의 노드를 shadow tree 안의 지정된 위치에 보이게 한다. 예를 들어 내부에 <slot name="header">가 있고 host의 자식으로 <strong slot="header">Form state</strong>를 넣으면, strong은 화면상 내부 헤더 자리에 배치된다. 그렇다고 노드가 shadow tree로 복사되거나 소유권이 넘어가지는 않는다. 그 노드는 계속 light DOM에 있으며 바깥 문서의 스타일 대상이다.
::part()는 반대 방향의 스타일 통로다. 내부 노드가 part="launcher"라는 이름을 공개했다면 바깥에서는 ilokesto-form-devtools::part(launcher)로 그 부분을 선택할 수 있다. 내부 클래스와 전체 트리를 드러내지 않고, 작성자가 이름 붙인 노드만 외부 스타일 표면으로 내보내는 방식이다.
현재 Form Devtools에는 <slot>도 part Attribute도 없다. 호출자가 자식 마크업을 패널 안에 합성하는 계약이 없고, 바깥 CSS가 런처나 패널을 ::part()로 직접 꾸미는 계약도 없다. 지금 열어 둔 스타일 통로는 여섯 개의 CSS Custom Properties뿐이다. slot과 part를 쓸 수 없어서 빠진 것이 아니라, 첫 공개 표면에 포함하지 않은 것이다. 나중에 part="launcher"를 추가한다면 그 이름도 소비자가 의존하는 API가 되므로 내부 클래스명보다 신중하게 수명을 정해야 한다.
이벤트는 경계를 통과하며 target을 바꾼다
스타일 경계만 생각하면 내부 버튼의 클릭을 바깥에서 어떻게 알 수 있는지가 남는다. 브라우저의 click 같은 UI 이벤트는 보통 Shadow DOM 경계를 통과할 수 있다. 다만 바깥 리스너가 보는 event.target은 내부 버튼이 아니라 host로 재지정된다. 이것을 event retargeting이라고 한다. 바깥 코드가 Shadow Root의 구체적인 버튼 구조에 매달리지 않도록 경계에 맞춰 발신자를 보정하는 셈이다.
직접 만든 이벤트에서는 bubbles와 composed를 따로 봐야 한다. bubbles는 이벤트가 현재 트리의 조상 방향으로 전파되는지를 정하고, composed는 Shadow DOM 경계를 넘어갈 수 있는지를 정한다. 예를 들어 shadow tree 안의 버튼이 자체 사용자 정의 이벤트를 보낸다면 다음처럼 두 옵션을 모두 켤 수 있다.
const toggleButton = shadowRoot.querySelector<HTMLButtonElement>('.toggle');toggleButton?.dispatchEvent( new CustomEvent('panel-toggle', { detail: { open: true }, bubbles: true, composed: true, }),);실제 Form Devtools의 open-change는 이 예시와 발신 위치가 다르다. 내부 버튼의 핸들러가 host 메서드인 toggleOpen()을 호출하고, 그 메서드는 host 자신에게서 이벤트를 보낸다.
private readonly toggleOpen = (): void => { this.open = !this.open; this.dispatchEvent(new CustomEvent('open-change', { bubbles: true, composed: true, detail: { open: this.open }, }));};바깥으로 내보내는 값은 어느 버튼을 눌렀는지가 아니라 변경된 open 값이다. 소비자는 내부 .launcher나 .close를 찾지 않고 host에서 상태 변화만 구독한다.
const devtools = document.querySelector('ilokesto-form-devtools');devtools?.addEventListener('open-change', event => { const { open } = (event as CustomEvent<{ open: boolean }>).detail; console.log('Form Devtools open:', open);});host는 이미 Shadow DOM 바깥과 만나는 접점이므로, 현재 open-change의 전파 경로는 Shadow Root를 통과하지 않는다. 따라서 지금 코드에서 composed: true는 전파 결과를 바꾸지 않는다. 같은 이벤트를 shadow tree 내부 노드에서 발신한다면 경계를 넘길지 정하는 옵션이 되겠지만, 현재 구현에서 실제로 경계를 건너 나오는 것은 내부 버튼의 click이고 open-change는 host가 새로 발신하는 별개의 이벤트다.
Shadow DOM은 보안이나 마스킹이 아니다
여기까지 보면 Shadow DOM이 내부를 감춘다고 말하고 싶어진다. 하지만 감춘다는 표현도 범위를 붙이지 않으면 오해를 만든다. Shadow DOM이 가리는 것은 기본 DOM 질의와 CSS 선택자의 탐색 범위다. 현재처럼 열린 Shadow Root라면 바깥 자바스크립트가 shadowRoot를 얻어 내부 노드를 읽을 수 있고, 닫힌 루트 역시 비밀 저장소나 권한 경계가 되지는 않는다.
따라서 비밀번호를 shadow tree 안에 출력했다고 해서 보호되는 것은 아니다. 민감한 값을 렌더링하지 않는 일과 애플리케이션 CSS가 내부 패널을 망가뜨리지 못하게 하는 일은 서로 다른 책임이며, Shadow DOM은 후자를 돕지만 전자를 대신하지 않는다. 어떤 값을 화면에 내보내기 전에 가릴지는 FormState를 진단 정보로 바꾸는 책임에서 따로 다룬다.
경계를 만들었지만 화면은 저절로 갱신되지 않는다
이제 Form Devtools의 UI가 애플리케이션과 한 문서에 있으면서도 어디까지 분리되는지는 설명할 수 있다. 내부 DOM과 기본 스타일은 shadow tree가 소유하고, host는 바깥과 만나는 접점이 되며, CSS Custom Properties와 이벤트는 이름을 붙여 남겨 둔 통로다. 현재는 slot과 part를 열지 않았고, 열린 Shadow Root는 검사 가능성을 남겨 두었다.
하지만 Shadow DOM이 해 주는 일은 여기까지다. open이 바뀌거나 폼 상태가 새로 들어왔을 때 어떤 노드를 다시 만들고 어느 값만 고칠지는 Shadow DOM이 결정하지 않는다. 경계 안의 화면을 상태 변화에 맞춰 계속 갱신하려면, 이제 브라우저 경계와 별개로 렌더링 구현을 정해야 한다.
댓글
댓글을 불러오는 중...