UI 감사 — 인터페이스 및 상호작용 검토은(는) 무엇을 하나요?
디자인 기준: 극소주의 + 애니메이션 스토리텔링 + 최소한의 텍스트.
핵심 원칙: 시각적으로 해결할 수 있으면 텍스트를 사용하지 않고, 애니메이션으로 프롬프트를 대체할 수 있으면 애니메이션을 사용하며, 텍스트가 반드시 필요할 때는 최소한의 단어만 사용합니다.
동반 스크립트
scripts/scan-ui.sh [DIRECTORY]: 텍스트 기호, 지나치게 긴 버튼 텍스트, 하드코딩된 중국어, 정적 로딩, 정의되지 않은 CSS 클래스 등 일반적인 UI 문제를 읽기 전용으로 자동 스캔합니다.
0단계: UI 베이스라인 검사 (모든 검토 전에 반드시 수행)
네비게이션 베이스라인
□ 사용자가 모든 페이지에서 홈/메인 페이지로 돌아갈 수 있음
□ 사용자가 상세 페이지에서 목록 페이지로 돌아갈 수 있음
□ 사용자가 목록 페이지에서 생성/새로 만들기 플로우로 이동할 수 있음
□ 페이지 새로고침 후에도 현재 위치가 유지됨
상태 처리 베이스라인
□ 모든 데이터 로드에 로딩 상태 존재 (skeleton/spinner)
□ 모든 API 호출에 오류 상태 존재 (사용자가 볼 수 있는 오류 메시지)
□ 모든 목록에 빈 상태 존재 (데이터가 없을 때 친숙한 안내 + 액션 가이드)
□ 양식 제출에 비활성화 상태 존재 (중복 제출 방지)
인증 베이스라인
□ 로그인 페이지에 '회원가입' 진입점 있음
□ 회원가입 페이지에 '로그인' 진입점 있음
□ 로그인 후 의미 있는 페이지로 이동 (빈 화면이 아님)
□ 로그아웃 시 상태가 정리됨
□ 토큰 만료 시 자동으로 로그인 페이지로 이동
베이스라인을 통과하지 못하면 먼저 베이스라인을 수정하고 다른 UI 검토를 수행하지 않습니다.
디자인 철학
극소주의
□ 각 페이지에는 하나의 시각적 초점만 있음
□ 여백은 디자인의 일부임
□ 색상은 2개의 주 색상 + 1개의 강조 색상을 초과하지 않음
□ 글꼴은 1종류를 초과하지 않음
□ 그림자, 그라데이션, 4px 초과 둥근 모서리 없음
□ 간격은 8px/16px/24px/32px의 배수 사용
애니메이션 스토리텔링
□ 모든 상태 변화에 전환 애니메이션 있음 (150-300ms)
□ 목록 항목 진입에 지연 애니메이션 있음 (간격 30-50ms)
□ 버튼 클릭에 누름 피드백 있음 (scale: 0.98)
□ 로딩은 정적 플레이스홀더가 아닌 Skeleton 사용
□ 오류는 팝업이 아닌 떨림 애니메이션 또는 색상 변화 사용
□ 성공은 토스트가 아닌 짧은 하이라이트 애니메이션 사용
최소한의 텍스트
□ 버튼 텍스트는 4자를 초과하지 않음
□ 아이콘 버튼에는 텍스트 없음 (tooltip으로 대체)
□ '확인', '취소' 등 모호한 텍스트 없음 ('저장', '취소'로 대체)
□ 오류 메시지는 10자를 초과하지 않음
□ 네비게이션 항목은 2자 + 아이콘을 초과하지 않음
텍스트 기호 금지
□ → ← ↑ ↓ 없음 (화살표 아이콘 사용)
□ × 없음 (닫기 아이콘 사용)
□ + - 없음 (추가/빼기 아이콘 사용)
□ > < 없음 (Chevron 아이콘 사용)
□ ✓ ! 없음 (Check/Alert 아이콘 사용)
□ ~ 없음 (시각적 구분선 사용)
□ % 없음 (진행 표시줄 또는 원형 사용)
검토 체크리스트
1. 텍스트 기호 검사 (최우선 순위)
scripts/scan-ui.sh를 실행하여 자동 스캔한 후, 각 일치 항목을 아이콘으로 교체해야 하는지 수동으로 확인합니다.
2. 아이콘 시스템 검사
□ 자주 사용하는 작업 아이콘이 완비됨: save / trash / edit / arrow-left / x (close)
□ 네비게이션 아이콘이 완비됨: search / plus / download / upload / external-link
□ 모든 아이콘이 통일된 스타일 (윤곽선 또는 채우기 중 하나 선택)
□ 아이콘 크기가 통일됨 (16px 작업, 24px 네비게이션, 32px 빈 상태)
□ 아이콘이 동일한 아이콘 라이브러리에서 가져옴 (예: Lucide / Heroicons / Phosphor), 혼용 금지
3. 애니메이션 검사
□ 페이지 전환에 전환 애니메이션 있음 (fade/slide)
□ 목록 항목 진입에 지연 애니메이션 있음
□ 버튼 클릭에 누름 피드백 있음
□ 로딩에 Skeleton 애니메이션 사용
□ 모달/드롭다운 메뉴에 확장 애니메이션 있음
□ 장시간 작업에 진행 애니메이션 있음
금지: 2초 이상 회전하는 스피너, 깜빡이는 레이블, 무한 루프 애니메이션, 성능에 영향을 주는 복잡한 애니메이션.
4. i18n 완전성
□ 모든 사용자에게 보이는 텍스트가 t() 함수를 사용함
□ translations 파일 외에 하드코딩된 중국어 문자열 없음
□ 오류 메시지가 i18n key를 사용함
□ aria-label이 i18n을 사용함
5. CSS 일관성
□ JSX에서 참조하는 CSS 클래스가 모두 정의됨
□ 사용되지 않는 CSS 클래스 없음
□ z-index 계층이 일관됨 (modal: 200, drawer: 100, backdrop: 99, toast: 300)
□ 색상은 CSS 변수 또는 테마 색상을 사용하고 하드코딩된 hex 없음
□ !important 없음 (명확한 이유가 있는 경우 제외)
6. 데드 코드 검사
□ 모든 컴포넌트 파일이 다른 파일에 의해 최소 1회 import됨
□ 동일한 이름의 파일 없음 (다른 디렉토리의 중복 컴포넌트)
□ 사용되지 않는 import 없음
7. 상태 처리
□ 모든 데이터 로드에 로딩 상태 있음
□ 모든 API 호출에 오류 상태 있음
□ 모든 목록에 빈 상태 있음
□ 양식 제출에 비활성화 상태 있음
□ 장시간 작업에 취소/중단 지원 있음
8. 네비게이션 플로우
□ 모든 경로에 해당 페이지 컴포넌트가 있음
□ 보호된 경로에 인증 가드가 있음
□ 404에 친숙한 fallback 페이지가 있음
□ 빵 부스러기/뒤로 가기 버튼이 올바르게 탐색됨
□ 외부 링크가 새 탭에서 열림
9. 반응형 및 접근성
□ 모바일 레이아웃이 오버플로되지 않음
□ 모든 상호작용 요소에 aria-label 있음
□ 키보드로 작동 가능 (Tab 탐색, Escape 닫기, Enter 확인)
□ 모달/패널에 focus trap 있음
□ 색상 대비가 WCAG AA를 준수함
작업 흐름
Phase 1: 자동화 스캔
scripts/scan-ui.sh를 실행하고 결과를 수집합니다. 다음에 중점을 둡니다: 텍스트 기호, 지나치게 긴 버튼 텍스트, 애니메이션 부족, 하드코딩된 중국어, 정의되지 않은 CSS 클래스.
Phase 2: 수동 검증
디자인 철학과 검토 체크리스트를 기준으로 페이지별로 검증합니다. Playwright를 사용해 각 페이지의 스크린샷을 찍어 대조 확인합니다.
Phase 3: 수정
우선순위에 따라 수정합니다:
- 텍스트 기호를 아이콘으로 교체
- 텍스트 단순화
- 애니메이션 보완
- CSS 클래스 보완
- i18n 보완
- 데드 코드 제거
- 상태 처리
- 네비게이션 플로우
Phase 4: 회귀 검증
수정 후 자동화 스캔을 다시 실행하여 새로운 문제가 없음을 확인합니다.
polish-loop-v2와의 관계
- polish-loop-v2: 일반 코드 검토 (로직, 보안, 성능, 런타임)
- ui-audit: 프론트엔드 UI 및 사용자 경험에 집중
병렬 실행, 베이스라인 검사는 공유합니다. ui-audit의 문제는 polish-loop-v2보다 우선순위가 높습니다.