「유스케이스별 대응표」의 함정 — 예비 지식이 없는 AI가 잘못 유도된 6가지 패턴 - Insights | Molayo

자작 디자인 시스템

@gunjo/ui (군죠/gunjo.jp)를, 군죠를 한 번도 본 적 없는 AI에게 170개 화면을 구성하게 했던 연재의 정리 제1탄입니다. 이번에는 유스케이스별 대응표 (by-use-case) (gunjo.jp의 docs에 있는, 하고 싶은 일로부터 컴포넌트를 찾는 목록) 설계에서 발견된 6가지 함정을 실제 round(라운드)와 함께 나열합니다.

왜 「대응표의 함정」을 이야기하는가

「AI가 사용할 수 있는 디자인 시스템」을 내세운다면, 이 대응표는 피할 수 없습니다. docs를 읽어도 목적하는 컴포넌트에 도달할 수 없다면, 그 컴포넌트는 없는 것과 마찬가지이기 때문입니다.

그래서 군죠는 처음부터 유스케이스별 대응표를 준비했습니다. 「경로 검색 결과 카드를 만들고 싶다」 → ListCard,
「청구서의 금액 내역을 표시하고 싶다」 → AmountBreakdown,
하는 식으로, 하고 싶은 일로부터 컴포넌트를 찾을 수 있는 목록입니다.

하지만 이 대응표는 잘못 유도하면, 애초에 「싣지 않는 것」보다 위험합니다. 실려 있지 않으면 사용하는 사람은 직접 구현(hand-build)하려 하겠지만, 「있다고 생각하고 사용하다가 막히는 것」이 성공이라고 착각되어 발견이 늦어지기 때문입니다. 170개 화면의 콜드 테스트(Cold Test)를 통해 그 함정을 6가지 패턴으로 정리할 수 있었습니다.

패턴 ①: 의미 키워드는 맞지만, UI 형태가 반대

예시: 대응표에서 「경로 (route)」를 찾으면 Itinerary (여정용·세로로 단계를 쌓는 컴포넌트)로 유도됩니다. 하지만 정말로 원했던 것은 가로로 나열된 A→B 구간 헤더인 OriginDestination이었습니다.

#166 국제 물류 (발송→도착)에서 직접 구현
#169 철도 노선별 실적 (기점→종점)에서 직접 구현
#170 철도 특급 예약 (도쿄→신오사카)에서 직접 구현

이 3개 화면에 대해 예비 지식이 없는 AI가 「Itinerary는 세로로 쌓는 형태이므로 가로 A→B를 구성할 수 없다」고 작성했고, 3번의 확인을 거쳐 OriginDestination을 구현했습니다. 의미 키워드는 맞지만 UI 형태가 반대인 함정입니다.

대응표의 시정: tracking timeline → RouteStops가 HH:MM에서 멈췄던 오유도를 「여러 날짜는 dateLabel이라고 명시」함으로써 방어하고, A→B 헤더는 OriginDestination으로 다시 유도하도록 수정했습니다.

패턴 ②: 외형은 비슷하지만, 의미가 반대 (다루는 대상의 착오)

예시: 대응표에서 「2명을 나란히 배치하기」를 찾으면 RelationshipRow (상사↔부하)가 나옵니다. 하지만 RelationshipRow의 from / to 타입은 PersonCellProps로 고정되어 있어, 회사×제도와 같은 조직 간의 쌍에는 타입이 통하지 않습니다.

#160 화물/차량 매칭 (화물×공차의 양자 간 마켓)
#172 M&A (매수자×매도자·회사×회사)
#173 보조금 매칭 (자사×제도·회사×제도라는 종류가 다른 쌍)

3번째인 #173에서, 예비 지식이 없는 AI는 「아바타+재석 도트(presence dot)를 가진 사람 모델을 조직에 강제하고 있다. 재무 데이터 슬롯도, 스코어 및 요인 내역 영역도 없다. 추가해야 할 것은 사람을 전제로 하지 않는 MatchCard와 PersonCell의 조직 버전인 CompanyCell이다」라고 정확하게 구분해냈습니다. → 2개의 컴포넌트를 동시에 구현.

MatchCard는 left/right를 일부러 ReactNode로 만들었기에 (타입을 CompanyCellProps로 고정하지 않았기에), 회사×제도와 같이 종류가 다른 쌍에서도 사용할 수 있습니다. 외형이 비슷하다는 것이 의미가 올바르다는 것과 같지는 않다는 함정이었습니다.

패턴 ③: 표시 전용 컴포넌트를 입력용으로 착각 (치환 함정)

예시: 대응표에서 「별점 평가를 입력하게 하고 싶다」를 찾으면 Rating이 나옵니다. 하지만 Rating은 role="img"인 표시 전용이며, onChange도, 포커스할 수 있는 별도 가지고 있지 않습니다. 예비 지식이 없는 AI가 선의로 onChange를 연결하더라도, 반응이 없어 막히게 됩니다.

#150 택시 승차 후 평가 (5단계 별점 + 좋았던 점 태그)
사용하는 사람이 움직이는 UI라고 믿고 구현 → 무반응 → 발견이 늦어짐 (가장 위험한 함정)

이것은 예비 지식이 없는 AI 자신이 "움직이는 컴포넌트처럼 보이지만 움직이지 않는다"라고 표현한, 치환 함정(substitution trap)의 전형적인 사례입니다. 부족한 컴포넌트라면 사용자는 "없으니까 직접 구현(hand-build)"하는 방향으로 갈 수 있지만, "있다고 생각해서 사용했다가 막히는" 함정은 성공이라고 착각되어 발견이 늦어집니다. 이러한 깨달음은 입력용 RatingInput을 과제로 기록하는 것과, 대응표 측에 "Rating은 표시 전용"이라고 명시하는 것으로 이어졌습니다.

패턴 ④: 시간의 정밀도가 다른데 이름이 비슷함 (시각 vs 시간대)

예시: 대응표에서 "집하 시간대를 선택"을 검색하면 TimePicker가 후보로 나옵니다. 하지만 TimePicker는 HH:MM 형식의 "정확한 시각"을 선택하는 컴포넌트로, "오전 / 12-14시 / 16-18시"와 같은 이산적인(discrete) 시간대는 선택할 수 없습니다.

#164 화주 포털 집하 의뢰 (물류 업계의 "시간대" 발주)
#165 택배 개인용 재배송 (수령 시간대)

예비 지식이 없는 AI는 #164에서 TimePicker를 직접 구현하여 피했고, #165에서는 처음부터 SegmentedControl을 선택했습니다 (대응표도 수정 완료). "시간대 → SegmentedControl / RadioGroup"으로 유도하고, TimePicker는 "정확한 시각"에만 한정함으로써, 시간 정밀도의 축 함정을 차단했습니다.

패턴 ⑤: 단일 선택과 다중 선택을 같은 이름으로 유도

예시: 대응표에서 "카드 행을 나열"을 검색하면 ListCard가 나옵니다. 하지만 ListCard.onSelect는 카드 전체를 하나의 <button>으로 만들어 버리기 때문에 (aria-pressed 토글), 단일 선택의 의미를 갖게 됩니다. 모바일 경비 내역 등에서 다중 선택 + 일괄 조작을 위한 BottomActionBar를 추가하고 싶을 때 이 함정에 빠지면, 카드 안에 버튼을 중첩(nesting)하게 되어 잘못된 HTML 구조와 포커스 순서의 붕괴로 인해 막히게 됩니다.

#149 택시 탑승 내역 (월별 내역 + 경비 다중 선택 + 일괄 다운로드)
"모바일 다중 선택" → ListCard + Checkbox + BottomActionBar로 수정 완료

이 함정은, 서류 다운로드 행(DocumentRow)은 ListCard로는 구조적으로 불가능하다는 점과 연결되며, 이는 다음 정리 글인 「'만들어야 하는 이유'에는 강도의 단계가 있다」의 주제로 이어집니다.

패턴 ⑥: 입도(Granularity) 차이 (부모와 자식 중 한쪽만 기재됨)

예시: 대응표에서 "안건 목록 + 일괄 할당"을 검색하면 DataTable은 나오지만, ActionDataTable(다중 선택 + 행 액션)은 기재되어 있지 않습니다. 예비 지식이 없는 AI는 DataTable을 선택하고 다중 선택을 직접 구현한 뒤에야 "사실 ActionDataTable이 이미 존재했다"는 것을 깨닫습니다.

#159 트럭 운송 배차 관리 (안건 목록의 일괄 할당)
대응표를 수정하여 "안건 목록 + 일괄 할당 → ActionDataTable"이라고 명시

"기재하지 않는 것"은 없다는 것을 알면 직접 구현하면 그만입니다. 하지만 부모만 기재하고 자식을 숨기면, 사용자는 부모만으로 충분하다고 생각하여 자식의 존재를 알아차리지 못합니다. 입도의 축에서 부모와 자식 모두를 대응표에 기재해 두어야 합니다.

같은 함정이 Meter 계열에서도 나타났습니다. ExpiryBadge(만료) / ReferenceValue(범위) / Meter(용량) / LimitMonitor(이름 있는 상한)라는 4형제가 모두 갖춰지기 전까지, 예비 지식이 없는 AI는 매번 Meter target으로 잘못 유도되어 구속 시간이나 운임 비교 작업에서 막히곤 했습니다.

대응표의 질은 4가지 축으로 평가해야 한다

170개의 화면을 통해 발견된 함정들을 모아보니, 이 대응표의 질은 4가지 축으로 평가해야 한다는 것을 알게 되었습니다.

형태 (Type) — 해당 컴포넌트의 Props에 의도한 인수가 들어가는가 (RelationshipRow는 CompanyCellProps를 받아들이지 않음)
접근성 (a11y) — 의미가 올바른가 (ListCard.onSelect의 aria-pressed는 "단일 선택 토글"이므로 다중 선택에는 사용할 수 없음)
모양 (Shape) — 가로 방향 A→B인가, 세로 방향의 시퀀스인가 (OriginDestination vs Itinerary)

） -
다루는 대상 (Domain) — 사람 모델인가 조직 모델인가 (PersonCell/RelationshipRow vs CompanyCell/MatchCard)

이 4가지 축 중 하나라도 뒤바뀐 대응표는, 사용하는 사람을 "있다고 생각하며 사용하다가 막히게" 만듭니다. 없다는 사실을 올바르게 전달하는 정직한 대응표 또한 하나의 정답입니다.

요약

대응표는 "뒤바꾸는 것"이 "싣지 않는 것"보다 위험합니다 (발견이 늦어짐)
170개 화면의 콜드 테스트 (Cold Test) 결과, 뒤바뀜의 함정에는 6가지 패턴이 있었습니다:
- 모양 (Shape)의 축 (세로 vs 가로)
- 다루는 대상 (Domain) (사람 vs 조직)
- 모드 (Mode) (표시 vs 입력)
- 시간의 정밀도 (Precision) (시각 vs 시간대)
- 선택의 범위 (Scope) (단일 vs 복수)
- 입도 (Granularity) (부모와 자식)
대응표의 질은 **형식 (Type) / 접근성 (Accessibility) / 모양 (Shape) / 다루는 대상 (Domain)**의 4가지 축으로 결정됩니다.
정직한 대응표 (Rating은 표시 전용이라고 명시하는 것 등)는, 숨기는 대응표보다 안전합니다.

"AI가 사용할 수 있는 디자인 시스템"을 만든다면, 대응표의 설계는 "서식"이 아니라 "설계 판단"입니다. 예비 지식이 없는 AI가 잘못 유도되는 횟수를 "찾을 수 없음"이 아니라 "있다고 생각하며 사용하다가 막힘"으로 측정하면, 수정해야 할 우선순위가 다르게 보일 것입니다.

Insights

「유스케이스별 대응표」의 함정 — 예비 지식이 없는 AI가 잘못 유도된 6가지 패턴

요약

핵심 포인트