LLM Wiki는 LLM이 특정 분야의 자료를 찾고 사용하는 방법을 정리한 Wiki입니다. 질문에 따라 무엇을 먼저 읽어야 하는지 안내하고, 자료끼리 내용이 다르면 어떤 출처를 우선할지 알려 줍니다.
아직 확인되지 않은 내용도 따로 남깁니다. 작업 중 새로 확인한 내용은 다시 Wiki에 반영하므로, 다음 작업은 이미 정리된 기준과 남은 질문에서 시작합니다.
LLM Wiki의 필요성
문서가 한곳에 많이 모여 있다고 해서 곧바로 지식이 되지는 않습니다. 필요한 자료가 어디에 있는지, 어느 내용이 최신인지, 서로 다른 기록이 충돌할 때 무엇을 따라야 하는지 알 수 없다면 LLM은 많은 문서를 읽고도 엉뚱한 답을 낼 수 있습니다.
도서관이 책만 쌓아 둔 창고와 다른 이유는 분류와 목록이 있기 때문입니다. VUI LLM Wiki도 같은 방식으로 자료를 정리합니다. 작업 종류에 따라 읽을 문서를 좁히고, 각 자료의 위치와 우선순위를 알려 줍니다.
답을 찾지 못한 경우도 기록합니다. 임시로 처리한 내용과 아직 확인할 질문을 남겨 두면 LLM이 빈칸을 추측으로 채우지 않고, 다음 작업에서는 그 지점부터 다시 검토합니다.
VUI LLM Wiki의 제작 배경
저에게는 장기적으로 VUI Design System을 만드는 업무가 주어졌습니다. 문제는 제가 시각 디자인을 체계적으로 훈련받지 않았다는 점이었습니다. 화면을 보고 곧바로 ‘VUI답다’거나 ‘VUI답지 않다’고 판단하기 어려웠습니다.
개인적인 감각만으로는 오래 유지할 Design System을 만들기 어렵다고 생각했습니다. 그래서 VUI 디자인을 판단할 때 무엇을 확인해야 하는지, 같은 문제를 다시 만났을 때 그 판단을 어떻게 재현할지부터 정리해야 했습니다.
VUI LLM Wiki의 구성 원리
VUI를 판단할 자료는 Figma 디자인, VUI 소스 코드와 테마, 생성 토큰과 컴포넌트 스펙, Storybook과 QA 기록 등 여러 곳에 있었습니다. Wiki는 이 자료를 복사하지 않고, 질문에 맞는 자료로 가는 길과 우선순위를 정리합니다.
1. 기준 자료
Figma는 디자이너가 의도한 모습을 보여 줍니다. packages/vui-ui와 packages/vui-theme에는 현재 동작하는 코드가 있고, 생성 토큰과 컴포넌트 스펙에는 사용할 수 있는 이름과 기능이 정리돼 있습니다. Storybook과 Figma Sync 보고서, QA 기록은 구현 결과를 비교할 때 사용합니다.
2. 판단 기준
자료가 서로 다르면 authority.md에 정리된 순서를 따릅니다. 새 디자인을 옮길 때는 Figma를 목표로 삼고, 현재 동작을 설명할 때는 소스 코드와 테마를 확인합니다. 컴포넌트, 토큰, 화면 패턴은 각 목록에 나누고, 아직 확정하지 못한 내용은 gap-index.md에 따로 기록합니다.
3. 읽기 경로
wiki.md는 작업에 맞는 시작점을 알려 줍니다. 그 다음에는 관련 컴포넌트 카드나 토큰 문서, 화면 패턴만 읽습니다. DESIGN.md는 자주 반복되는 작업에 필요한 문서를 한 번 더 좁혀 놓은 읽기 목록이며, 판단이 필요할 때는 링크를 따라 원래 자료로 돌아갑니다.
디렉터리 구조
docs/design에서는 이 원칙을 네 문서 그룹으로 나눕니다. wiki.md가 작업에 맞는 문서로 안내하므로 파일 이름을 모두 외울 필요는 없습니다.
입구와 규칙 docs/design/wiki.md, authority.md, validation.md
wiki.md는 작업별 시작점을 안내합니다. authority.md는 자료가 다를 때 무엇을 따를지 정하고, validation.md는 Wiki를 갱신한 뒤 확인할 항목을 모아 둡니다.
목록 docs/design/profiles/company/*-index.md
컴포넌트, 토큰, 화면 패턴, 미확정 항목을 각각 나눠 둔 목록입니다. 현재 질문과 관련된 문서만 골라 줍니다.
세부 문서 components/*.card.md, patterns/*.md, tokens/*.md
컴포넌트별 사용법, 화면을 구성하는 방식, 토큰 사용 원칙을 필요한 단위로 설명합니다.
작업별 읽기 목록 DESIGN.md, exports/*.DESIGN.md
CRUD 목록 화면이나 Form처럼 반복되는 작업에 필요한 문서만 모아 둡니다. LLM은 전체 Wiki를 읽지 않고 여기서 시작하며, 판단이 필요하면 원래 자료를 확인합니다.
Figma Sync 활용과 갱신
디자이너가 승인한 Figma 디자인을 VUI 컴포넌트와 Storybook으로 옮기는 작업을 Figma Sync라고 부릅니다. 화면만 비슷하게 만드는 작업은 아닙니다. 컴포넌트 상태를 기존 API에 연결하고, VUI 토큰과 Storybook 전용 장식을 구분해야 합니다.
저는 Figma Sync를 시작할 때 Wiki에서 해당 컴포넌트 카드와 토큰 문서를 먼저 확인했습니다. 작업 중 새로 확인한 내용은 관련 문서에 반영하고, 아직 답이 없는 부분은 미확정 항목(gap)으로 남겼습니다. 작업이 끝날 때마다 Wiki도 함께 갱신했습니다.
Tooltip 검증 사례
Tooltip의 첫 화면은 얼핏 완성된 것처럼 보였습니다. 하지만 화살표 방향과 위치가 Figma와 달랐고, Storybook 설명용 점선 프레임도 결과 화면에 들어가 있었습니다.
화면만 보고 수정했다면 화살표 크기와 위치를 임의의 숫자로 맞췄을 수 있습니다. Wiki를 따라 Figma의 방향 정의, 기존 VuiTooltip API, Storybook 장식의 범위, 사용할 수 있는 토큰을 순서대로 확인했습니다.
그림 1. 수정 전 Tooltip. Storybook 장식과 방향별 화살표 문제가 한 화면에 섞인 상태.
그림 2. 수정 후 Tooltip. 기존 VuiTooltip의 direction을 사용하고 Storybook 전용 장식을 분리한 상태.
확인 결과, 방향은 기존 VuiTooltip의 direction으로 처리할 수 있었습니다. Storybook 전용 장식은 구현에서 분리했습니다. 반면 화살표 모양에는 확인된 토큰이 없었기 때문에 임의로 규칙을 만들지 않고 미확정 항목으로 남겼습니다.
MenuItem 상태 구분 사례
MenuItem에서는 disabled와 disabled + selected를 같은 상태로 처리한 것이 문제였습니다. 초기 구현은 disabled 상태 전체에 selected 배경색을 적용했고, 선택되지 않은 항목에도 회색 배경이 남았습니다.
저는 Wiki에서 VuiMenuItem 카드와 Figma의 상태별 화면, VUI의 text와 action token을 함께 확인했습니다. Figma에서는 disabled 항목의 배경이 투명했고, disabled + selected에만 selected 배경이 남아 있었습니다. 따라서 disabled 텍스트에는 text.disabled를 적용하되 배경은 투명하게 두고, selected 상태가 함께 있을 때만 action.selected를 적용했습니다.
그림 3. 수정 전 MenuItem. 선택되지 않은 disabled 항목에도 selected 배경이 적용된 상태.
그림 4. 수정 후 MenuItem. disabled는 투명하게 두고 disabled + selected에만 selected 배경을 적용한 상태.
Kanban 디자인 생성 사례
지난 Sprint에서는 짧은 시간 안에 실제로 사용할 수 있는 Kanban 템플릿이 필요했습니다. VUI LLM Wiki가 기존 컴포넌트를 고치는 데만 도움이 되는지, 새로운 화면을 설계할 때도 쓸 수 있는지 확인해 볼 좋은 기회였습니다.
먼저 Wiki에서 CRUD/List 화면과 Dialog 흐름을 확인했습니다. 보드와 lane, 카드, 등록·수정·삭제 동작은 기존 VUI 컴포넌트로 구성했고, 상태 색상과 카드 표면에는 semantic token을 사용했습니다. 처음 만드는 Kanban이었지만 다른 VUI 화면과 어울리는 형태를 빠르게 만들 수 있었습니다.
그림 5. VUI LLM Wiki의 패턴, 컴포넌트, 토큰 경로를 따라 생성한 Kanban backlog 화면.
VUI LLM Wiki가 완성되면 작업을 맡은 LLM이 바뀌어도 같은 설계 기준을 찾을 수 있을 것입니다. 새로운 컴포넌트와 화면도 매번 처음부터 추측하지 않고, 이미 정리된 판단에서 시작해 VUI다운 방향으로 확장할 수 있습니다.
Joseph