UI UX Auditor

UI/UX Auditor — 9영역 감사 + 0-10 채점 + 자동 수정

프로젝트의 UI/UX를 9개 카테고리로 스캔하고, 영역별 0-10 점수를 매긴 뒤, 발견된 문제를 우선순위별로 분류한 뒤 코드를 직접 수정합니다.

세부 규칙 DB: references/ux-guidelines.csv — nextlevelbuilder/ui-ux-pro-max-skill(MIT)에서 흡수한 UX 이슈 99종(No/Category/Issue/Platform/Description/Do/Don't/Code Example Good/Code Example Bad/Severity). 아래 9영역 각각에 Category 컬럼으로 매핑돼 있으니, 채점 시 해당 영역 Category로 grep해 Do/Don't·코드 예시를 인용하세요. Web/Mobile/All/VisionOS로 플랫폼 태그가 붙어 있어 관련 없는 플랫폼 행은 건너뜁니다.

상호보완 관계:

• design-plan의 네이티브 렌더 비평: 디자인 방향·계약 — "어떤 경험을 만들 것인가" (개발 전·중)
• ui-ux-auditor (이 스킬): UI/UX 점검 + 수정 — "이게 문제니까 고쳐라" (개발 후)

적용 시점

• /ui-ux-auditor 명시적 실행
• "UI 점검해줘", "UX 감사해줘", "접근성 검사", "반응형 확인" 요청 시

Step 1: 프로젝트 스캔

프로젝트 구조를 파악합니다:

프레임워크 자동 감지:

package.json → "next" → Next.js
package.json → "nuxt" → Nuxt
package.json → "@sveltejs/kit" → SvelteKit
package.json → "@remix-run" → Remix
package.json → "astro" → Astro
index.html + vite → Vite SPA

Step 2: 9영역 정적 스캔 (Grep — 1차 신호)

이 단계의 Grep 결과는 1차 신호입니다. 최종 채점은 Step 2.5의 시각 검증(렌더링 관찰)이 우선합니다.

2-1. 다크/라이트 모드 호환성

Grep 탐지 패턴:

# 하드코딩 색상 (다크모드에서 깨지는 패턴)
text-white|text-black|bg-white|bg-black
bg-zinc-[0-9]|bg-gray-[0-9]|bg-slate-[0-9]
text-zinc-[0-9]|text-gray-[0-9]|text-slate-[0-9]
border-zinc-|border-gray-|border-slate-
# 네이티브 폼 컨트롤 (다크모드 자주 깨짐 — color-scheme 누락)
<select|<option|color-scheme|::placeholder|appearance-none

2-2. 반응형 디자인

Grep 탐지 패턴:

# 브레이크포인트 사용 여부
sm:|md:|lg:|xl:|2xl:
# 고정 너비 (반응형 깨지는 패턴)
w-\[[\d]+px\]|width:\s*[\d]+px
# 가로 스크롤 유발
overflow-x-auto|overflow-x-scroll

ux-guidelines.csv Category=Responsive(8) + Touch(6, 모바일 프로젝트만) — 터치 타겟 스페이싱, 제스처 충돌, 탭 딜레이, 테이블 처리 등 세부 Do/Don't.

2-3. 접근성 (a11y)

Grep 탐지 패턴:

# alt 속성 누락
<img(?![^>]*alt=)
# aria-label 없는 인터랙티브 요소
<button(?![^>]*aria-label)(?![^>]*>[\w가-힣])
# 포커스 아웃라인 제거 (접근성 위반)
outline-none|outline-0|focus:outline-none

ux-guidelines.csv Category=Accessibility(11) — Severity High가 8/11. 색상 단독 정보 전달 금지, 폼 라벨/에러 announce, skip link 등. Category=Animation의 Motion Sensitivity(#99, parallax/scroll-jacking 멀미) 행도 여기서 함께 확인.

2-4. 로딩 상태 & 성능

Grep 탐지 패턴:

# loading 컴포넌트 존재 여부
loading\.tsx|loading\.jsx|Skeleton|skeleton
# 레이지 로딩
loading="lazy"|lazy\(\)|React\.lazy|dynamic\(
# 버튼 로딩 상태
isLoading|isPending|disabled.*loading
# 성능 — 렌더 블로킹/번들/폰트 (ux-guidelines.csv Category=Performance)
<link.*stylesheet(?!.*preload)|<script(?!.*defer)(?!.*async)
next/image|next/font|font-display

ux-guidelines.csv Category=Performance(8, Severity 대부분 Medium) — 이미지 최적화, 캐싱, 3rd party 스크립트, 번들 사이즈 세부 기준.

2-5. 폼 UX

Grep 탐지 패턴:

# 폼 관련 패턴
<form|useForm|handleSubmit|onSubmit
# 유효성 검사
required|pattern=|minLength|maxLength
# 에러 메시지 표시
error|formState\.errors|fieldState

ux-guidelines.csv Category=Forms(10) + Data Entry(1, 반복 편집엔 일괄 작업 제공) — 입력 타입, 비밀번호 표시, 모바일 키보드 타입 등.

2-6. 네비게이션 일관성

Grep 탐지 패턴:

# 네비게이션 컴포넌트
<nav|<Nav|Navbar|Sidebar|Breadcrumb
# 활성 상태
active|isActive|pathname|usePathname|useRouter
# 링크 컴포넌트
<Link|<a\s

ux-guidelines.csv Category=Navigation(6) + Search(2, 자동완성·No Results 데드엔드) + Onboarding(1, 튜토리얼 건너뛰기 자유).

2-7. 타이포그래피 & 간격

Grep 탐지 패턴:

# 타이포그래피 계층
text-xs|text-sm|text-base|text-lg|text-xl|text-2xl|text-3xl|text-4xl
# 간격 패턴
gap-|space-|p-|px-|py-|m-|mx-|my-
# 줄 간격
leading-|line-height
# 폰트 실제 로드 (이름만 쓰고 @import/link 누락 → 시스템 폴백)
font-family|@import.*fonts|<link.*fonts|Pretendard|noonnu

ux-guidelines.csv Category=Typography(6) + Layout(7, z-index/stacking context/viewport unit/컨테이너 폭) + Content(4, 말줄임/날짜·숫자 포맷/플레이스홀더).

2-8. 애니메이션 & 전환

Grep 탐지 패턴:

# 애니메이션 라이브러리
framer-motion|motion\.|animate-|transition-
# 호버 상태
hover:|group-hover:|focus:
# 페이지 전환
AnimatePresence|pageTransition|layout

ux-guidelines.csv Category=Interaction(8, focus/hover/active/disabled/에러·성공 피드백/확인 다이얼로그) + Feedback(6, 로딩 인디케이터/빈 상태/에러 복구/진행률/토스트) — 상태 전환·피드백 디테일.

2-9. AI Slop 탐지

See ai-slop-blacklist.md — 공유 블랙리스트.

시각 확인 항목 (코드 + 렌더링):

판정: AI Slop 항목이 3개 이상 → P1, Hard Rejection 항목 발견 → P0

ux-guidelines.csv Category=AI Interaction(3, AI와 대화 중임을 고지·스트리밍 응답·피드백 루프) — 챗봇/AI 기능이 있는 프로젝트만 해당.

범위 밖(참고만): ux-guidelines.csv의 Sustainability(2, 자동재생 영상·에셋 무게)와 Spatial UI(2, VisionOS 전용)는 이 9영역 어디에도 깔끔히 안 들어가고 해당 프로젝트가 드물어 정식 항목화하지 않음 — VisionOS/친환경 웹 프로젝트면 CSV에서 직접 grep.

Step 2.5: 시각 검증 — 스크린샷 관찰 (Visual Pass)

디자인의 진실은 코드가 아니라 렌더링된 화면에 있습니다. Grep은 후보를 찾고, 점수는 화면을 직접 보고 매깁니다.

2.5-1. 서버 준비

1. 이미 실행 중인 dev server가 있으면 재사용 (헬스체크: curl -s -o /dev/null -w "%{http_code}" http://localhost:{port})
2. 없으면 minos Step 3의 감지 순서 재사용: docker-compose → Dev Server (npm run dev 등) → 정적 빌드 프리뷰
3. 서버 구동 불가 시: 시각 검증을 건너뛰되, 스코어카드에 "정적 스캔만 수행 — 관찰 미반영" 명시 + 등급에 * 표기 (신뢰도 제한)

2.5-2. 캡처 매트릭스

주요 페이지(라우트 상위 5개 이내)에 대해 캡처:

캡처 방법 (우선순위):

1. 로컬 Playwright CLI — MCP 불필요, 3-CLI 공통:

   npx playwright screenshot --viewport-size="1440,900" --color-scheme=light \
     --wait-for-timeout=3000 --full-page \
     "http://localhost:3000/" docs/ui-audit/screenshots/home-desktop-light.png
   npx playwright screenshot --viewport-size="390,844" --color-scheme=dark \
     --wait-for-timeout=3000 --full-page \
     "http://localhost:3000/" docs/ui-audit/screenshots/home-mobile-dark.png
   

2. Playwright MCP / chrome-devtools MCP가 연결돼 있으면 browser_navigate + browser_take_screenshot 사용 가능

저장 규칙: docs/ui-audit/screenshots/{page}-{viewport}-{scheme}.png

2.5-3. 관찰 채점

각 스크린샷 파일을 현재 런타임이 제공하는 이미지 보기 기능으로 직접 관찰합니다:

충돌 규칙: Grep 결과와 관찰이 다르면 관찰이 이깁니다. 예: 코드에 dark: 클래스가 있어도 화면에서 텍스트가 안 보이면 실패. 코드에 고정폭이 있어도 화면에서 안 깨지면 P3로 강등.

Step 2.7: 영역별 0-10 채점

8+1개 영역을 각각 0-10으로 채점합니다. 시각 검증을 수행한 경우 관찰 결과가 최종 점수이고, Grep 결과는 보조 근거입니다.

채점 기준:

• 0-3: 심각한 문제 다수 — 즉시 수정 필요
• 4-6: 기본은 되지만 개선 필요
• 7-8: 양호 — 마이너 이슈만 있음
• 9-10: 우수 — 업계 수준 이상

가중 총점:

총점 → 등급:

출력 형식:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UI/UX 감사 스코어카드

| 영역 | 점수 | 주요 이슈 |
|------|------|----------|
| 다크/라이트 모드 | 7/10 | 하드코딩 2건 |
| 반응형 | 5/10 | 브레이크포인트 누락 |
| 접근성 | 6/10 | alt 미작성 4건 |
| 로딩 상태 & 성능 | 3/10 | Skeleton 없음, 폰트 렌더 블로킹 |
| 폼 UX | 8/10 | — |
| 네비게이션 | 9/10 | — |
| 타이포/간격 | 7/10 | 간격 불일관 |
| 애니메이션 | 6/10 | reduced-motion 미대응 |
| AI Slop | 8/10 | 3열 그리드 1건 |

시각 검증: {수행 — 스크린샷 N장 (docs/ui-audit/screenshots/) | 미수행 (서버 구동 불가)}
총점: 6.4/10 (등급: C)      ← 시각 검증 미수행 시 등급에 * 표기 (예: C*)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 3: 문제 분류 (P0~P3)

Step 4: 사용자 확인 후 수정

감사 결과를 보고하고 수정 범위를 확인합니다:

UI/UX 감사 완료

발견된 문제: {N}건
- P0 (긴급): {x}건
- P1 (높음): {y}건
- P2 (보통): {z}건
- P3 (낮음): {w}건

어떤 범위까지 수정할까요?
1. P0만 — 긴급한 것만 빠르게
2. P0 + P1 — 중요한 것까지 (권장)
3. 전부 — 모든 문제 수정

수정 규칙:

• 기존 코드 스타일/프레임워크에 맞춰 수정
• 관련 없는 코드는 건드리지 않음
• 한 파일씩 순차적으로 수정 (변경 추적 용이)

공통 수정 패턴:

Step 5: 수정 리포트

UI/UX 개선 완료

수정한 파일: {N}개
- P0: {x}건 수정
- P1: {y}건 수정
- P2: {z}건 수정

주요 변경:
| 파일 | 영역 | 변경 내용 |
|------|------|-----------|
| src/components/Header.tsx | 반응형 | 모바일 브레이크포인트 추가 |
| src/app/page.tsx | 접근성 | 이미지 alt 텍스트 추가 |
| ... | ... | ... |

남은 작업 (수동 확인 필요):
- ...

주의사항

• 수정 전 반드시 사용자 확인을 받습니다
• UI 라이브러리(DaisyUI, shadcn, MUI 등)에 맞는 수정 방법을 선택합니다
• 디자인 방향성 결정이 필요하면 design-plan의 렌더 비평 계약으로 돌아갑니다
• 한 번에 너무 많이 바꾸지 않고 단계적으로 수정합니다

연관 리소스