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로 플랫폼 태그가 붙어 있어 관련 없는 플랫폼 행은 건너뜁니다.

상호보완 관계:

• ui-ux-designer (에이전트): 디자인 조언 — "이렇게 만들어라" (개발 중)
• ui-ux-auditor (이 스킬): UI/UX 점검 + 수정 — "이게 문제니까 고쳐라" (개발 후)

적용 시점

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

---

Step 1: 프로젝트 스캔

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

검사 대상	경로 패턴
페이지 라우트	src/app/, pages/, src/routes/
컴포넌트	src/components/, components/
스타일 시스템	globals.css, tailwind.config.*, *.module.css
UI 의존성	package.json → DaisyUI, shadcn, Radix, MUI, Chakra 등

프레임워크 자동 감지:

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

검사 항목	기준
하드코딩 색상	text-white, bg-black 등 → 시맨틱 토큰으로 변환 필요
CSS 변수 충돌	:root vs [data-theme] 우선순위 충돌
테마 전환	next-themes, data-theme 속성 적용 여부
이미지/아이콘	다크모드에서 안 보이는 요소 (흰 배경 위 흰 아이콘 등)
select/option	<select>의 <option>이 OS 기본색으로 렌더 → 다크에서 깨짐. 루트 color-scheme: light dark + option 배경/글자색 명시 필요
컨테이너 div 배경	섹션/카드 div 배경색이 테마 토큰을 따르는지 (하드코딩 흰/검정 금지)
텍스트 반전	배경 반전 시 텍스트 색도 함께 반전되는지 (다크에서 검은 글자 잔존 금지)

2-2. 반응형 디자인

Grep 탐지 패턴:

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

검사 항목	기준
브레이크포인트 누락	sm:, md:, lg: 없이 고정 레이아웃
터치 타겟 크기	클릭 영역 최소 44×44px (WCAG 2.5.5)
가로 스크롤	모바일에서 가로 스크롤 발생하는 요소
텍스트 오버플로우	truncate, line-clamp 누락으로 텍스트가 넘침
고정 너비	w-[500px] 같은 고정값 → 반응형 단위로 변환

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

검사 항목	기준
이미지 alt	모든 <img>에 의미 있는 alt 텍스트 필수
색상 대비	WCAG AA 기준 4.5:1 (본문), 3:1 (대형 텍스트)
aria 속성	아이콘 버튼에 aria-label, 모달에 aria-modal
키보드 네비게이션	Tab 순서, Enter/Space 동작, Esc 닫기
시맨틱 HTML	<nav>, <main>, <article>, <section> 사용
포커스 표시	outline-none 제거 → focus-visible:ring 대체

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

검사 항목	기준
페이지 loading.tsx	Next.js 라우트마다 loading.tsx 또는 Suspense 경계
Skeleton UI	데이터 페칭 구간에 Skeleton 표시
버튼 피드백	클릭 후 로딩 상태 (spinner, disabled)
이미지 레이지 로딩	뷰포트 밖 이미지에 loading="lazy"
빈 상태	데이터 없을 때 빈 상태 UI (Empty State)
이미지 최적화	next/image 등 최적화 컴포넌트 사용, 원본 대용량 이미지 직접 서빙 금지
폰트 로딩	렌더 블로킹 <link rel=stylesheet> → preload+swap 또는 font-display: swap(gotcha: Google Fonts CSS는 그 자체가 렌더 블로킹 — technique-recipes 폰트 preload 패턴 참조)
렌더 블로킹 리소스	head의 동기 <script>(defer/async 없음), 대형 인라인 <style>
번들/코드 스플리팅	라우트 단위 dynamic()/React.lazy 분리 여부

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

검사 항목	기준
유효성 검사 피드백	에러 메시지 위치 (필드 바로 아래), 색상 (빨강 계열)
포커스 스타일	입력 필드 포커스 시 시각적 구분
자동완성	autocomplete 속성 (이메일, 비밀번호, 주소 등)
자동 포커스	첫 입력 필드에 autoFocus
제출 버튼	비활성화 상태, 로딩 상태, 중복 제출 방지

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

검사 항목	기준
활성 페이지 표시	현재 페이지 하이라이트 (active state)
뒤로가기 동작	브라우저 뒤로가기 정상 동작 확인
브레드크럼	3단계 이상 깊이에서 경로 표시
일관된 위치	네비게이션이 모든 페이지에서 동일 위치

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

검사 항목	기준
제목 크기 계층	h1 > h2 > h3 순서로 크기 감소 (시각적 계층)
줄 간격	본문 leading-relaxed (1.625) 이상
섹션 간격	일관된 간격 패턴 (예: 섹션 간 py-12, 카드 간 gap-6)
폰트 일관성	같은 용도에 같은 크기/굵기 사용
폰트 실제 로드	font-family에 쓴 폰트가 @import/<link>로 실제 로드됐는지 — 누락 시 시스템 폴백 (document.fonts.check('700 16px "X"')로 확인 — 한글 등 서브셋 폰트는 로드돼도 check() false 가능, face status로 확인·gotcha 045)
한글 웹폰트	한글 포함 UI에 한글 웹폰트(Pretendard 등) 로드 여부 — 라틴 폰트엔 한글 글리프 없어 한글이 시스템 폴백

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

검사 항목	기준
호버 상태	클릭 가능 요소에 호버 효과 (커서, 색상 변화)
페이지 전환	화면 전환 시 부드러운 효과 (선택사항)
과도한 애니메이션	prefers-reduced-motion 미대응 시 경고
성능 영향	레이아웃 트리거 애니메이션 (width, height) 지양 → transform, opacity 사용

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

2-9. AI Slop 탐지

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

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

#	탐지 대상	Grep 힌트
1	보라/인디고 그라데이션	from-purple, from-indigo, bg-gradient, linear-gradient.*purple
2	3열 대칭 피처 그리드	grid-cols-3 + 내부 아이콘+제목+설명 반복
3	원형 배경 아이콘	rounded-full.*bg- + <svg 또는 아이콘 컴포넌트
4	전부 가운데 정렬	text-center가 3개 이상 연속 컨테이너에 적용
5	균일 둥근 모서리	같은 rounded-* 값이 카드/버튼/입력 모두에 적용
6	장식용 블롭/웨이브 SVG	blob, wave, circle.*absolute, 장식 목적 SVG
7	과사용 폰트	font-family.*Inter, font-family.*Roboto (프라이머리로 사용 시)

판정: 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개 이내)에 대해 캡처:

축	값
Viewport	데스크톱 1440,900 / 모바일 390,844
컬러 스킴	light / dark (다크모드 지원 프로젝트만)

캡처 방법 (우선순위):

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. 관찰 채점

각 스크린샷 파일을 이미지로 직접 읽어(Read 도구 — Claude/Codex/Gemini 모두 이미지 입력 지원) 관찰합니다:

영역	화면에서 보는 것 (코드로 못 잡는 것)
다크모드	안 보이는 텍스트/아이콘, 조합으로만 발생하는 대비 붕괴
반응형	모바일 캡처의 가로 스크롤, 요소 겹침/잘림, 터치 타겟 밀집
타이포/간격	시각 계층이 실제로 느껴지는지, 간격 리듬의 일관성
네비게이션	활성 상태가 눈에 보이는지, 위치 일관성
AI Slop	보라 그라데이션, 3열 대칭, 천편일률적 인상 — 화면에서 한눈에 판별
전체 인상	"돈 주고 쓰고 싶은 화면인가" — 한 줄 총평 (ui-ux-designer 에이전트 관점)

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

---

Step 2.7: 영역별 0-10 채점

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

채점 기준:

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

가중 총점:

영역	가중치
2-1. 다크/라이트 모드	10%
2-2. 반응형	15%
2-3. 접근성	15%
2-4. 로딩 상태 & 성능	10%
2-5. 폼 UX	10%
2-6. 네비게이션	10%
2-7. 타이포그래피 & 간격	15%
2-8. 애니메이션	10%
2-9. AI Slop	5%

총점 → 등급:

등급	점수	의미
A	9.0+	출시 가능, 업계 최고 수준
B	7.0-8.9	출시 가능, 소소한 개선 권장
C	5.0-6.9	출시 전 개선 필요
D	3.0-4.9	심각한 문제 — 대폭 수정 필요
F	0-2.9	출시 불가

출력 형식:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
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)

우선순위	기준	예시
P0 (긴급)	사용 불가 또는 심각한 UX 결함	다크모드에서 글자 안 보임, 모바일에서 터치 안 됨
P1 (높음)	사용자 이탈에 영향	로딩 상태 없음, CTA 잘 안 보임, 폼 에러 피드백 없음
P2 (보통)	불편하지만 사용 가능	간격 불일관, 호버 상태 없음, 접근성 미흡
P3 (낮음)	있으면 좋은 개선	애니메이션 추가, 마이크로 인터랙션

---

Step 4: 사용자 확인 후 수정

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

UI/UX 감사 완료

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

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

수정 규칙:

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

공통 수정 패턴:

문제 유형	수정 방법
하드코딩 색상	CSS 변수 또는 시맨틱 토큰으로 변환
반응형 누락	모바일 퍼스트 브레이크포인트 추가
alt 누락	컨텍스트에 맞는 alt 텍스트 작성
로딩 상태 없음	Skeleton / Spinner / 로딩 UI 추가
포커스 아웃라인 제거	focus-visible:ring 계열로 대체
터치 타겟 부족	min-h-[44px] min-w-[44px] 적용

---

Step 5: 수정 리포트

UI/UX 개선 완료

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

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

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

---

주의사항

• 수정 전 반드시 사용자 확인을 받습니다
• UI 라이브러리(DaisyUI, shadcn, MUI 등)에 맞는 수정 방법을 선택합니다
• 디자인 방향성 결정이 필요하면 ui-ux-designer 에이전트와 연계합니다
• 한 번에 너무 많이 바꾸지 않고 단계적으로 수정합니다

---

연관 리소스

리소스	역할	관계
ui-ux-designer (에이전트)	디자인 조언, 피드백	설계 방향 → auditor가 점검
seo-audit (스킬)	SEO 점검	릴리즈 전 SEO + UX 함께 점검
web-design-guidelines (스킬)	웹 디자인 원칙	감사 기준의 근거
references/ux-guidelines.csv	UX 이슈 99종 Do/Don't + 코드 예시	9영역 채점의 세부 근거 (Credits: nextlevelbuilder/ui-ux-pro-max-skill, MIT)