라이브러리 개발기 (4) — 스토리보드

devtools.ts까지 뜯어보고 나니, 이제 진짜 뭘 만들지는 머릿속에 대충 그려졌다.

이번 글에서는 무턱대고 기능 구현이 아니라, Z-UI를 설치한 사용자가 실제로 어떤 순서로 화면을 마주치는지 그 시나리오를 정리하고자 한다.

물론 아직 구상 단계인 목업이라, 실제 구현에서 이 화면 그대로 가지는 않을 수 있다.

컨셉 구현에 가까운 설계도에 지나지 않는다.

만들다 보면 여기 없던 화면이 새로 추가될 수도 있고, 색상이 바뀌거나 레이아웃이 바뀔 수도, 또 반대로 여기서 그린 것 중 일부는 빠지거나 합쳐질 수도 있다.

디자인 톤

화면을 하나씩 그리기 전에, 공통 톤부터 간단히 정했다.

다크 테마에 모노스페이스 폰트를 포인트로 썼다.

개발자 도구에 알맞게 색상을 골랐고 추후 다크/라이트 테마 토글도 고려할 생각이다.

메인 UI 색상은 다크 네이비 배경 위에 앰버(#FF9F43)를 메인 강조색으로, 테라코타(#E67E22)를 보조 강조색으로 쓰기로 했다. 비활성 상태나 서브 텍스트에는 톤을 낮춘 뮤트 샌드(#D4A373)를 쓴다.

버튼, 활성 상태 뱃지, 포커스 테두리 같은 공통 UI 요소는 전부 이 앰버로 통일할 계획이다.

스토어별 색은 이름별로 미리 고정해두는 대신, 스토어를 만들 때 개발자가 정해진 팔레트 중에서 직접 고르는 방식 혹은 색상코드 방식으로 하려 한다(코드 작성 시에는 객체로 color 키-밸류 전달).

따로 지정 안 하면 메인 컬러와 같은 앰버가 기본값으로 잡히게 할 것이다.

1. GUI 실행 직후 — 연결 대기 화면

사용자가 별도 터미널에서 npx z-ui를 실행하면 브라우저가 자동으로 열리며 화면이 뜬다.

아직 WS 연결(ws://localhost:3274 - 개발 중인 앱 실행시 함께 실행)이 확립되기 전이거나, 앱 쪽에 zuiPlugin()이 아직 안 켜져 있는 상태를 위한 화면이다.

화면 중앙엔 연결 상태 텍스트("Z-UI 서버에 연결 중...")와 스피너만 있고, 캔버스는 비어있다.

3초 재시도 로직이 뒤에서 계속 돌고 있다는 걸 하단에 작은 텍스트로 안내한다("3초마다 재연결 시도 중").

vite.config.ts에 zuiPlugin()을 추가했는지 확인하라는 문구도 같이 보여줘야했다.

이 화면에서 막히는 사용자가 가장 먼저 보게 될 안내이기 때문에, 원인(플러그인 미설치, 혹은 앱 미실행)을 여기서 명확히 짚어줘야 한다고 생각했다.

2. 연결 성공 — 메인 캔버스

WS 연결이 열리고 REQUEST_STORES → STORE_INIT 응답을 받으면 이 화면으로 전환된다.

상단 Header에 연결 상태 뱃지("● 연결됨")와 스토어 개수를 표시하고, 그 아래 전체 화면을 채우는 Canvas(React Flow) 위에 등록된 스토어들이 카드형 노드로 나란히 배치된다.

각 노드는 스토어 이름, state의 비함수 필드 최대 3개 미리보기, 하단의 "액션 N개" 뱃지로 구성했다.

현재 구현은 스토어 상호참조 기획 이전이라 노드 사이 연결선(엣지)은 없다.

노드들은 서로 독립적으로 캔버스 위에 흩어져 있고, 사용자가 자유롭게 드래그해서 보기 쉽게 재배치할 수 있다.

우측 상단엔 "+ 새 스토어" 버튼을 띄워 클릭하면 스토어를 생성할 수 있도록 했다.

3. 노드 클릭 → Inspector 패널

캔버스에서 스토어 노드 하나를 클릭하면 화면 우측에 Inspector 패널이 슬라이드인 된다.

Inspector 상단엔 스토어 이름과 색상 뱃지가 있고, 그 아래 state 전체가 JSON 트리 형태로 펼쳐진다.

편집 버튼을 누르면 모달이 뜨고, 그 안에서 state 전체를 한 번에 고쳐서 저장하면 STATE_PATCH가 전송된다. 스토어 삭제 버튼도 추가할 예정이다.

함수 필드(액션)는 JSON에 그대로 노출하면 이상해서, 패널 맨 아래 "액션" 섹션에 실행 가능한 버튼 목록으로 따로 뺐다.

패널 하단엔 "초기화" 버튼이 있다.

스토어를 STORE_INIT 수신 시점 state로 되돌리는 버튼이다.

4. 실시간 양방향 동기화 시연

이 화면은 기능 스크린샷이라기보다는 "이 도구가 하는 일"을 한 장으로 설명하는 컨셉 다이어그램에 가깝다.

브라우저 창 두 개를 나란히 띄운 구도인데, 왼쪽은 앱에서 사용자가 "+1" 버튼을 눌러 state를 업데이트하는 모습이고, 오른쪽은 방금 3번 화면에서 열어둔 Z-UI GUI이다.

왼쪽에서 버튼을 누르는 순간 오른쪽 Inspector의 count 값이 실시간으로 갱신되고, 값이 바뀐 필드에 짧은 하이라이트 펄스 애니메이션(테두리가 스토어 색상으로 잠깐 빛나는 효과)이 들어간다.

5. 새 스토어 생성 — 모달 폼

캔버스의 "+ 새 스토어" 버튼을 누르면 뜨는 모달이다.

구성 요소는 스토어 이름 입력, 필드 입력 영역이 있고, "+ 필드 추가" 버튼으로 행을 늘림, 색상 선택 라디오 버튼, 그리고 하단에 "Z-UI에 등록" 체크박스(기본 체크됨)로 잡았다.

또한 프로젝트 구조를 생각해, 기본 스토어 구조를 바꿀 수 있는 입력 필드를 추가할 예정이다.

생성을 누르면 지정된 경로에 스토어 명으로 스토어와 파일이 생성되며 zustand 스토어 보일러플레이트가 생성된다.

6. 생성 결과 & 삭제 확인

한 화면에 두 상태를 나란히 보여주는 비교 컷으로 그렸다.

왼쪽은 방금 생성한 productStore 노드가 캔버스에 새로 나타난 순간이다. 다른 노드와 구분되게 테두리에 잠깐 "new" 글로우 효과가 있고, 상단에 토스트 메시지("productStore 생성 및 등록 완료")가 뜬다.

오른쪽은 노드 삭제 확인 다이얼로그이다.

편집창 내부나 Inspector 패널에서 삭제할 수 있게끔 할 것이며, 삭제는 소프트로 할지 즉시 삭제로 할 지 정하지 않았다.

즉시 삭제가 사용자 경험에 더 좋을 듯하여 즉시 삭제로 고려 중이다.

7. 액션 로그 & 스냅샷

Inspector 패널 안에, state JSON 아래쪽으로 탭으로 전환되는 두 번째 영역을 뒀다.

액션 로그 탭은 최신 항목이 위로 오는 타임라인 리스트다. 각 행에 [storeName] actionName · 12:03:41 형태의 라벨과 함께, 값이 바뀐 필드는 count 2 → 3처럼 메인 컬러인 앰버로 강조해서 보여준다. 항목을 클릭하면 그 시점 state로 즉시 복구된다(복구 버튼도 row에 추가해서 ui를 구성할까 고려 중이다).

스냅샷 탭은 사용자가 저장해둔 커스텀 지점들이 카드 목록으로 표시된다(예: "로그인 전 · 12:01", "초기 설정 · 12:01"). 각 카드 우측엔 북마크 아이콘을 둬서 저장된 스냅샷이라는 걸 시각적으로 표시했다. 카드를 클릭하면 전체 앱 state가 그 시점으로 복구된다.

(원래는 우측 상단 스냅샷 탭 활성화 돼야함)

두 탭 모두 시간여행 디버깅이라는 공통 주제를 다루기에, 탭 UI로 하나의 패널 안에 묶어서 구성하였다.

정리하며

7장을 순서대로 그려보니, Z-UI가 하려는 일이 결국 devtools.ts에서 봤던 그 구조와 유사하다는 게 다시 한번 보였다.

앱 → GUI 방향은 2, 4번 화면(조회, 동기화)이고, GUI → 앱 방향은 3, 5, 6, 7번 화면(편집, 생성, 삭제, 시간여행)이다.

이건 어디까지나 지금 시점에서 그린 초안이다.

실제로 구현에 들어가면 이대로 안 될 부분도 분명 나올 것이고, 지금은 생각도 못한 화면이 새로 필요해질 수도 있다.

그때그때 이 문서를 기준점 삼아 고치고 덧붙여가면서 만들 생각이다.

다음 포스팅부터는 이 스토리보드를 기준으로, AI 에이전트가 제시한 로드맵 스텝과 던져준 과제 단위로 zui() 미들웨어와 GUI 캔버스 앱을 실제로 구현하려한다.