문제: 옮긴 기록은 지금 동작을 설명하는지, 상태가 무엇인지, 지금 정본이 어디인지 알 길이 없다. 설계서·계획서 27개와 docs/architecture 목표 설계 16개에는 상태 칸이 없고, VD는 「상태: Accepted」 같은 영어 값을 쓴다. 고른 방법: docs-system.md 4절 형식으로 맨 위에 머리 블록을 달고 본문은 한 글자도 고치지 않는다. 상태는 기계 변환이다. - 설계서: Accepted·확정·정본·설계 완료 → 채택, 상태 줄이 없으면 확인 안 함 (채택 4, 확인 안 함 21) - 계획서: 체크 상자가 모두 표시됐으면 끝남, 아니면 확인 안 함. SPEC.md는 같은 폴더 plan.md와 같은 근거(0.2.0으로 끝난 라운드)로 끝남 (끝남 5, 확인 안 함 14. 이미 블록이 있던 5개는 그대로) - 결정 기록: Accepted → 채택, 날짜가 붙은 뒤늦은 보완 메모가 본문에 있으면 채택(보완) (채택 14, 채택(보완) 9). 프론트 VD는 처음부터 한국어로 썼고 번역하지 않으므로 둘째 줄은 「원문이다」 문구다. - 작성일: 파일 이름 날짜 → 본문 날짜 줄(VD는 `결정일:`) → git 첫 추가일. 위험: VD-09·11·13은 git으로 보면 결정 뒤 본문이 그 자리에서 고쳐졌지만 본문에 날짜 표시가 없어 기계 규칙대로 채택으로 두었다. 보완으로 올릴지는 사람이 정한다. 「현재 정본」은 지금 있는 살아 있는 문서나 코드 경로만 쓴다. 검증: 블록과 그 뒤 빈 줄 하나를 빼면 72개 모두 `git show HEAD:`와 바이트가 같다. 뒤 커밋의 문서 검사 head 규칙으로 돌려 문제 0건.
4.4 KiB
4.4 KiB
결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택(보완)
- 작성일: 2026-07-26
- 요약: 아이콘은
lucide-react를 한 파일 facade 뒤에 두고 의미 이름만 노출하며, 복합 control은 headless 라이브러리 없이 native 요소로 만든다는 결정이다. - 현재 정본:
src/presentation/design-system/,docs/styling/design-tokens.md
VD-05: Semantic icon facade와 native-first interaction
- 상태: Accepted
- 결정일: 2026-07-26
- 적용 브랜치:
feature-frontend-design-system-platform - 재검토: native 계약으로 충족할 수 없는 widget 요구가 확인될 때
배경
앱 셸과 공통 UI는 문자 glyph, raw button/select와 페이지별 focus 처리를 사용했다. 아이콘 공급자와 복합 interaction을 제품 코드에 직접 노출하면 번들, 접근성, vendor type과 교체 비용이 모든 feature로 전파된다. 반대로 실제 요구가 없는 두 개의 headless vendor를 기본 설치하면 skeleton 소비자가 제거해야 할 의존성과 중복 interaction 모델이 생긴다.
결정
- 아이콘 공급자는 lockfile 최소 게시 유예를 통과한
lucide-react@1.25.0으로 고정한다. lucide-react의 static named import는design-system/icons/vendors/lucide.tsx한 파일에서만 허용한다.- public API는
MenuIcon,CloseIcon,WarningIcon같은 의미 이름만 노출한다. vendor component type, icon name, stroke API와 dynamic icon registry는 노출하지 않는다. - 장식 아이콘은 accessibility tree에서 제외한다. 정보를 단독 전달하는
아이콘은
label, icon-only action은 필수accessibleName을 사용한다. - 현재 복합 control은 native
dialog, form control,details와 local TypeScript state model로 구현한다. Menu는 roving focus/typeahead/Escape, Tabs는 manual/automatic activation, Drawer는 modal/background 비활성화/focus restore 계약을 가진다. - React Aria와 Radix는 기본 dependency로 추가하지 않는다. native platform이 collision, nested overlay, virtualized collection 또는 복합 select 요구를 충족하지 못한다는 재현 가능한 요구가 생길 때 prototype과 ADR로 다시 평가한다.
- Storybook과 pinned visual baseline은 VD-08/RP-10에서 도입한다. RP-07의 runtime gallery와 browser interaction test는 해당 workshop을 대체한다고 주장하지 않는다.
경계와 검증
- 제품 코드는
presentation/design-system/index만 import한다. 예외는 규칙에 이름으로 적는다.presentation/components/ui/*.ts는 아래 Rollback의 재수출 facade이고,presentation/templates/page-templates.tsx는 index가 내보내지 않는PaginationLandmarkContext를 읽는다. - deep import와 direct icon import는
check:architecture그래프 규칙design-system-is-reached-through-its-index,icon-vendor-is-facade-only(.dependency-cruiser.json)가 거절한다. 경로 해석이 끝난 간선을 보므로 presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는tests/fixtures/architecture/dependency-graph/import-boundaries다. - design-system 검사기(
scripts/check-design-system.ts)는 headless vendor import, raw palette, undefined token과 tooltip-only required information fixture를 거절한다. - type negative fixture는 accessible name 없는
IconButton을 거절한다. - component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를 검증한다.
- Chromium/Firefox E2E는 compact Drawer의 native modal 상태, Escape, focus restore, gallery keyboard interaction과 axe를 검증한다.
- 로컬 WebKit 실행은 host
libevent-2.1.so.7부재로 환경 검증이 남아 있으며 공급자 선택이나 product behavior의 PASS로 숨기지 않는다.
Rollback
기존 presentation/components/ui/* 경로는 canonical TypeScript primitive를
재수출하므로 소비 코드를 즉시 되돌릴 수 있다. Lucide 제거 시 vendor facade와
semantic icon 구현만 교체하고 제품 API는 유지한다. headless vendor를 나중에
도입해도 public props와 interaction test를 유지한다.