ux-audit

name	ux-audit
description	UI/UX 품질을 다관점·적대적으로 검증할 때. — MUST TRIGGER: UI/UX 변경 후 /review 전, 새 기능 론칭 전, 프론트엔드 리팩토링 후, 접근성(WCAG) 점검이 필요할 때.
description_en	Use when UI/UX quality must be validated adversarially from multiple perspectives. — MUST TRIGGER: after UI/UX changes before /review, before launching a new feature, after frontend refactoring, or when accessibility (WCAG) review is needed.
user-invocable	false

Nova UX Audit

5인 적대적 평가자(Adversarial Jury)로 UI/UX를 다관점 심층 평가한다. 각 평가자는 서로 다른 페르소나로 독립 분석하며, 결과를 종합하여 우선순위 개선 목록을 도출한다.

"사용자는 코드를 보지 않는다. 사용자가 보는 것만이 진실이다."

핵심 원칙

• 독립 평가: 5인 전원 독립 서브에이전트로 실행 (상호 영향 금지)
• 코드 기반: 실제 컴포넌트/i18n/스타일 코드를 읽고 분석 (추측 금지)
• 분석 전용: 평가자는 코드를 수정하지 않는다
• 최신 기준: WCAG 2.2, Core Web Vitals (INP), EU DSA 2024 기준 적용

옵션

플래그	동작
(없음)	5인 평가 + 종합 보고
--target <경로>	평가 범위 지정 (기본: 프론트엔드 전체 자동 탐색)
--screenshot	Puppeteer로 실제 화면 캡처 후 평가 (dev 서버 실행 필요)
--live <URL>	Computer Use로 실제 브라우저에서 앱을 조작하며 평가 (예: --live http://localhost:3000)
--sprint	결과를 스프린트로 자동 분할
--fix	Critical/High 자동 수정 제안 (사용자 승인 필요)
--a11y	접근성 평가자를 Full 모드로 강제 (WCAG 전 항목 검사)

실행 플로우

Phase 1: 환경 분석

1. 프론트엔드 기술 스택 감지 (React/Vue/Svelte/Angular/etc.)
2. --target 지정 시 해당 경로, 미지정 시 프론트엔드 루트 자동 탐색
3. i18n 파일, 테마/디자인 토큰, 라우트 구조, 컴포넌트 디렉토리 파악
4. --screenshot 시: dev 서버 기동 확인 → Puppeteer MCP로 주요 화면 캡처 (미설치 시 경고 후 코드 분석만 수행)
5. --live <URL> 시: Computer Use로 실제 브라우저에서 앱을 열고 인터랙션하며 평가 (아래 상세 참조)
6. 디자인 시스템 자동 감지 (평가자 3 Cognitive Load 디자인 항목 평가용):
   • 스캔 우선순위 5단계:
     1. tailwind.config.{ts,js,mjs,cjs} (Tailwind preset 추출)
     2. theme.{ts,tsx,js} 파일 (root, src/, app/) — export 객체 파싱
     3. *.css 파일의 :root { --token-name: ... } CSS 변수
     4. design-tokens/*.{json,ts,js} 직접 토큰 정의
     5. packages/*/tokens/, packages/design-system/ (monorepo 케이스)
   • 결과 구조 (tokenCatalog):

     {
       "detected": true,
       "sources": [{"type": "tailwind", "path": "..."}],
       "tokenCount": { "color": 7, "spacing": 6, "fontSize": 5 },
       "tokens": { "color": [...], "spacing": [...] },
       "components": ["Button", "Input", "Card"]
     }
     

   • 미감지 시: { "detected": false }
   • 평가자 3 (Cognitive Load) 컨텍스트 주입은 요약 형태: tokenCount + 카테고리별 첫 5개 토큰만 (전체 토큰 카탈로그 주입 금지 — 평가자 토큰 부담 최소화)

환경 분석 결과를 요약하여 표시한다:

[Nova UX Audit] 스택: {React 18 + TypeScript} | 대상: {src/components/} | 모드: {코드 분석 / 스크린샷 포함} | 디자인 시스템: {Tailwind + 토큰 18개 / 미정의}

Phase 2: 5인 평가자 병렬 실행

5개 평가자 에이전트를 독립 서브에이전트로 병렬 실행한다 (Agent tool, run_in_background: true).

각 평가자에게 전달할 공통 컨텍스트:

프로젝트 경로: {절대 경로}
기술 스택: {감지된 스택}
평가 대상 파일: {파일/디렉토리 목록}
i18n 파일 경로: {있으면 명시}
라우트 구조: {파악된 라우트 요약}
역할: 분석만 수행한다. 코드를 수정하지 않는다.
출력 형식: 문제 목록 (심각도 Critical/High/Medium/Low + 파일:라인 + 개선안). 최대 8건. 200단어 이내.

--screenshot 시 캡처된 스크린샷 경로도 컨텍스트에 포함한다.

Phase 3: 종합 (5인 전원 완료 후)

1. 5인 결과 수집
2. 중복 제거 (아래 규칙 적용)
3. 우선순위 정렬 (Critical → High → Medium → Low)
4. 종합 보고서 출력
5. NOVA-STATE.md 갱신

Phase 4: 후속 조치 (선택)

• --sprint 시: 스프린트 분할 제안 (아래 형식)
• --fix 시: Critical/High 수정안 생성 → 사용자 승인 → 적용 → 해당 평가자 관점 재검증 (Lite)

5인 평가자 구성

평가자 1: Newcomer — 신규 사용자 온보딩

너는 이 도구를 처음 접하는 신규 사용자다.
"이게 뭔지, 어떻게 시작하는지" 전혀 모르는 상태에서 평가한다.
JTBD(Jobs to be Done) 관점으로 "사용자가 무엇을 완료했다고 느끼는지"를 중심에 놓는다.

평가 기준:
1. 첫 화면에서 도구의 목적이 즉시 파악 가능한가? (5초 테스트 — 제목/부제/히어로만으로 판단)
2. 빈 상태(Empty State)에 "다음에 뭘 해야 하는지" 안내가 있는가?
3. 핵심 개념 간 관계가 UI에서 시각적으로 설명되는가?
4. 기능 첫 사용 시 "무슨 일이 일어나는지" 사전 안내가 있는가?
5. 에러 메시지가 해결책을 포함하는가? (단순 "오류 발생" = High)
6. 온보딩 진입점이 발견 가능한가? (Hidden Help = 없는 것과 같다)
7. CTA 버튼 라벨이 행동 동사로 시작하는가? ("확인" 대신 "프로젝트 생성")
8. 완료 신호(Success State)가 명확한가? (사용자가 "끝났다"를 인지하는 순간)

분석 대상: 빈 상태 컴포넌트, 온보딩 플로우, 에러 바운더리, CTA 버튼 라벨, 성공/완료 화면.
출력: 문제 목록 (심각도 Critical/High/Medium/Low + 파일:라인 + 개선안). 최대 8건. 200단어 이내.

평가자 2: Accessibility Guardian — 접근성 감시자

너는 WCAG 2.2 AA 기준을 엄격히 적용하는 접근성 전문가다.
키보드만으로, 스크린 리더만으로, 저시력 상태로 이 도구를 사용할 수 있는지 평가한다.

평가 기준 (WCAG 2.2 기반):
1. 모든 인터랙티브 요소에 키보드 접근이 가능한가? (tabIndex, onKeyDown, role="button"에 Enter/Space 핸들러)
2. 포커스 순서가 시각적 순서와 일치하는가? (tabIndex > 0 사용 = 경고)
3. 색상 대비율이 AA 기준을 충족하는가? (일반 텍스트 4.5:1, 대형 텍스트/UI 컴포넌트 3:1)
4. 이미지/아이콘에 대체 텍스트(alt, aria-label)가 있는가? 장식용이면 aria-hidden="true"?
5. 동적 콘텐츠 변경 시 aria-live 영역으로 스크린 리더에 알리는가?
6. 터치 타겟이 최소 24×24px인가? (WCAG 2.5.8 Target Size Minimum)
7. 드래그 전용 동작에 클릭/키보드 대체 입력이 있는가? (WCAG 2.5.7 Dragging Movements)
8. 도움말/헬프 메커니즘 위치가 페이지 간 일관적인가? (WCAG 3.2.6 Consistent Help)
9. 폼 에러 시 에러 위치로 포커스 이동 + 해결 방법을 텍스트로 제공하는가?
10. 모션 애니메이션에 prefers-reduced-motion 미디어 쿼리 대응이 있는가?

분석 대상: JSX/TSX의 HTML 속성, aria-* 속성, CSS 색상값/크기, 이벤트 핸들러, 애니메이션.
출력: 문제 목록 (심각도 + 파일:라인 + WCAG 기준 번호 + 개선안). 최대 8건. 200단어 이내.

평가자 3: Cognitive Load Analyst — 인지 부하 분석가

너는 인지심리학 기반으로 UI의 정신적 부담을 측정하는 분석가다.
개발 경험이 없는 PM/파운더가 이 도구를 사용한다고 가정한다.
기술 용어, 정보 과부하, 의사결정 피로를 핵심으로 찾는다.

평가 기준:
1. 단일 화면의 동시 선택지가 7±2개를 초과하는가? (Miller's Law — 메뉴, 탭, 버튼 수 합산)
2. 온보딩/위자드 단계당 신규 개념이 3개를 초과하는가?
3. "지금 무엇이 진행 중인지" 한눈에 파악 가능한가? (상태 가시성 — 로딩/진행률/완료)
4. "이번 작업이 언제쯤 끝나는지" 예측 가능한 정보가 있는가? (진행률 바, 예상 시간)
5. 기술 용어가 비개발자에게 직접 노출되는가? (i18n 파일 키/값 점검)
6. 활동 로그/알림이 비전문가가 읽을 수 있는 자연어 문장인가?
7. 핵심 기능까지 네비게이션 깊이가 3단계를 초과하는가? (3-Click Rule)
8. 정보 계층(Visual Hierarchy)이 중요도 순으로 정렬되어 있는가? (CSS font-size/weight/color 분석)
9. "왜 진행이 안 되는지" 사용자가 스스로 진단 가능한가? (에러 상태 + 해결 경로)
10. 되돌리기(Undo) 또는 실수 복구가 가능한가? (파괴적 행동 전 확인 다이얼로그)

[디자인 시스템 정합 — 인지 부하 관점]
11. 같은 의미의 UI(에러/성공/경고/로딩)가 화면마다 다른 색·폰트로 표시되는가?
    → 사용자가 학습한 시각 패턴을 깨면 매번 의미를 재해석해야 함 (인지 부하 ↑)

12. 디자인 토큰을 거치지 않은 하드코딩(색상·spacing·font-size)이 인지 일관성을 깨는가?
    → 같은 의미인데 미세하게 다른 값 = 사용자가 "다른 것"으로 인식 → 학습 비용 증가
    → ★ 디자인 시스템이 정의되지 않은 프로젝트에서는 이 항목을 건너뜁니다.

[디자인 항목 출력 제한]
- 위 11~12 항목에서 발견한 이슈는 최대 3건까지만 보고하세요.
- 전체 출력 8건 제한은 그대로 유지합니다.

분석 대상: 라우팅 구조(깊이), 컴포넌트 props/state 복잡도, i18n 문자열, CSS 시각 계층, 모달/다이얼로그, 디자인 토큰 파일(tokenCatalog), 컴포넌트 라이브러리(components/ui/, design-system/), CSS 변수 사용 패턴.
출력: 문제 목록 (심각도 + 파일:라인 + 개선안). 최대 8건. 200단어 이내.

Context Override (디자인 시스템 미정의 시)

tokenCatalog.detected == false인 경우, 평가자 3 프롬프트에 다음 문장을 prepend한다:

[Context Override] 이 프로젝트에는 디자인 시스템 정의가 없습니다. 항목 12는 평가에서 제외하고, 보고서 끝에 "디자인 시스템 정의 없음 — 토큰 검증 스킵" 1줄을 표기하세요.

이는 false positive 폭주를 방지한다. 항목 11(의미별 일관성)은 디자인 시스템 부재와 무관하게 평가한다.

평가자 4: Performance Critic — 성능 비평가

너는 매일 대규모 데이터를 다루는 파워 유저이자 프론트엔드 성능 전문가다.
Core Web Vitals 지표를 코드 레벨에서 진단하고, 대규모 데이터 시 UX 열화 패턴을 찾는다.

평가 기준:

[렌더링 성능 — INP/CLS/LCP 관련]
1. 이벤트 핸들러(onClick, onChange 등)에 무거운 동기 연산이 있는가? (INP 악화: 200ms 초과 위험)
2. 이미지/미디어에 width/height 또는 aspect-ratio가 명시되어 있는가? (CLS 방지)
3. 동적 콘텐츠 삽입(토스트, 배너, 무한스크롤)이 기존 레이아웃을 밀어내는가? (CLS 유발)
4. 최대 콘텐츠(히어로 이미지, 주요 텍스트 블록)에 loading="eager" 또는 preload가 적용되어 있는가? (LCP)
5. React: useMemo/useCallback/React.memo가 고비용 연산/빈번 리렌더에 적절히 사용되는가?

[대규모 데이터 UX]
6. 100+ 항목 리스트에 가상화(react-window, tanstack-virtual 등)가 적용되어 있는가?
7. API 호출에 적절한 LIMIT/커서 기반 페이지네이션이 있는가? (무한 fetch 방지)
8. 검색/필터링이 대규모 데이터에서 실용적인가? (디바운스, 서버사이드 필터)

[효율성]
9. 번들 사이즈 — 대형 의존성에 dynamic import/코드 스플리팅이 적용되어 있는가?
10. 키보드 단축키/벌크 작업이 지원되는가? (반복 작업 N회 → 1회로 줄이는 경로)

분석 대상: 컴포넌트 렌더링 로직, API 호출 패턴, 리스트 컴포넌트, 번들 설정(webpack/vite/next.config).
출력: 문제 목록 (심각도 + 파일:라인 + 개선안). 최대 8건. 200단어 이내.

평가자 5: Dark Pattern Detective — 다크 패턴 탐정

너는 EU Digital Services Act(2024)와 사용자 권리를 기준으로 조작적 UI 패턴을 탐지하는 감사자다.
의도적이든 비의도적이든, 사용자를 기만하거나 불리하게 유도하는 모든 패턴을 찾는다.

평가 기준 (EU DSA 2024 + FTC 가이드라인):
1. 확인/동의 버튼이 거부/취소보다 시각적으로 과도하게 강조되는가? (Visual Interference — 크기, 색상, 위치 비교)
2. 구독 취소/계정 삭제/데이터 삭제 경로가 가입/생성보다 복잡한가? (Roach Motel — 경로 단계 수 비교)
3. 거절 옵션에 감정적 조작 문구가 있는가? (Confirmshaming — "아니요, 좋은 기회를 포기합니다")
4. 근거 없는 카운트다운, "한정", "남은 N개" 표시가 있는가? (Fake Urgency/Scarcity)
5. 체크박스/토글 기본값이 사용자에게 불리하게(opt-in으로) 설정되어 있는가? (Pre-selection)
6. 설정 해제가 설정만큼 쉬운가? (Asymmetric Choice — 같은 단계 수로 역행 가능 여부)
7. 에러 메시지가 특정 유료/업그레이드 행동으로 유도하는가? (Misdirection)
8. 개인정보 수집 범위와 목적이 수집 시점에 투명하게 고지되는가?
9. 가격/비용 정보가 결제 직전에야 공개되는가? (Hidden Cost)
10. "무료" 표시가 실제로는 기간 한정/조건부인데 이를 명시하지 않는가?

분석 대상: CSS(버튼 스타일·크기·색상 비교), 폼 defaultChecked/defaultValue, 라우팅(경로 깊이 비대칭), i18n 문자열(감정 조작 어휘).
출력: 문제 목록 (심각도 + 파일:라인 + 위반 패턴명 + 개선안). 최대 8건. 200단어 이내.

중복 제거 규칙

5인의 결과를 종합할 때:

1. 같은 파일:라인을 지적한 평가자가 2인 이상이면 하나로 병합, 출처 열에 "평가자 1,3" 표기
2. 심각도가 다르면 높은 쪽 채택
3. 개선안이 다르면 더 구체적인(파일:라인 + 코드 수준) 쪽 채택
4. 같은 근본 원인의 파생 이슈들은 근본 원인 하나로 통합, 파생을 하위 목록에 기록

종합 보고서 형식

━━━ Nova UX Audit — 5인 적대적 평가 종합 보고서 ━━━━━━━

  대상: {평가 경로}
  스택: {감지된 기술 스택}
  모드: {코드 분석 / 스크린샷 포함}

  ## 평가자별 핵심 발견
  | # | 관점 | Critical | High | 핵심 발견 |
  |---|------|----------|------|----------|
  | 1 | Newcomer | {N} | {N} | {한 줄 요약} |
  | 2 | Accessibility | {N} | {N} | {한 줄 요약} |
  | 3 | Cognitive Load | {N} | {N} | {한 줄 요약} |
  | 4 | Performance | {N} | {N} | {한 줄 요약} |
  | 5 | Dark Pattern | {N} | {N} | {한 줄 요약} |

  ## 우선순위 정렬 — Top N 개선 항목
  | 순위 | 심각도 | 출처 | 문제 | 파일:라인 | 개선안 |
  |------|--------|------|------|----------|--------|

  ## 잘 되어 있는 점 (Strengths)
  1. ...
  2. ...
  3. ...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Critical/High가 0건인 평가자는 "이슈 없음"으로 표기
• 잘 되어 있는 점은 5인의 분석에서 긍정적으로 언급된 항목을 3건 이상 추출
• 디자인 시스템 미감지 시 보고서 끝에 "디자인 시스템 정의 없음 — 토큰 검증 스킵 (평가자 3 항목 12)" 1줄 표기

--sprint 스프린트 분할

--sprint 지정 시 종합 보고서 뒤에 추가:

  ## 스프린트 분할 제안
  | 스프린트 | 항목 수 | 예상 파일 수 | 초점 |
  |---------|---------|-------------|------|
  | S1 | {N} | {N} | Critical + 접근성 필수 항목 |
  | S2 | {N} | {N} | High + 성능 최적화 |
  | S3 | {N} | {N} | Medium + 인지 부하 개선 |

스프린트 분할 기준:

• S1: Critical + WCAG AA 위반 (법적 리스크) → 즉시 수정
• S2: High + 성능 (사용자 이탈 위험) → 다음 릴리스
• S3: Medium + Low (품질 향상) → 백로그

--fix 수정 모드

/nova:review --fix와 동일한 워크플로우:

1. 종합 보고서 완료
2. Critical/High 이슈에 대해 수정 코드 제안 (Before/After + 영향 범위)
3. 사용자에게 수정안 표시 + 승인 요청
4. 승인된 수정만 적용
5. 적용 후 해당 평가 관점으로 재검증 (Lite)
6. 재검증에서 새로운 Critical 발견 시 → 추가 자동 수정 없이 사용자 보고

수정 제안 형식:

━━━ UX Fix Proposal ━━━━━━━━━━━━━━━━━━━━━━━━
  이슈 #{N}: {이슈 제목}
  심각도: {Critical / High}
  출처: 평가자 {N} ({관점})
  파일: {파일:라인}

  ── 문제 ──
  {문제 설명 1~2줄}

  ── 수정안 ──
  {Before/After 코드 diff}

  ── 영향 범위 ──
  {수정으로 영향받는 파일/모듈}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

--live Computer Use 모드

Claude Code의 Computer Use 기능으로 실제 브라우저에서 앱을 열고 인터랙션하며 평가한다.

실행 절차

1. 지정된 URL로 브라우저를 연다 (Computer Use)
2. 주요 사용자 시나리오를 자동으로 실행한다:
   • 메인 페이지 탐색 + 네비게이션 클릭
   • 폼 입력 + 제출
   • 에러 유발 (빈 제출, 잘못된 입력)
   • 뒤로가기/되돌리기 동작
3. 각 단계에서 스크린샷을 캡처하여 평가자 컨텍스트에 포함한다
4. 코드 분석 결과 + 실제 렌더링/인터랙션 결과를 종합하여 평가한다

평가자별 활용

평가자	--live에서 추가 확인 사항
Newcomer	실제 첫 화면 인상, 온보딩 흐름 클릭 경로
Accessibility	실제 탭 키 순서, 포커스 표시 가시성, 스크린 리더 영역
Cognitive Load	실제 화면에서의 시각적 복잡도, 네비게이션 깊이 체감
Performance	실제 로딩 시간, 인터랙션 반응 속도
Dark Pattern	실제 버튼 크기/색상 비교, 해지 경로 클릭 수

폴백 체인

--live (Computer Use)
  │ 미지원 환경
  ▼
--screenshot (Puppeteer MCP)
  │ 미설치/미연결
  ▼
코드 분석만 수행

각 폴백 시 경고를 출력한다:

[Nova UX Audit] Computer Use 미지원 — --screenshot 모드로 폴백합니다.
[Nova UX Audit] Puppeteer MCP 미연결 — 코드 분석만 수행합니다.

주의: Computer Use는 Research Preview 기능입니다. 프로덕션 환경이 아닌 로컬 개발 서버에서만 사용하세요.

--screenshot 스크린샷 모드

Puppeteer MCP 도구로 실제 화면을 캡처한다.

캡처 대상 화면 (자동 선정)

1. 메인/랜딩 페이지 (첫 화면)
2. 빈 상태 (데이터 없을 때)
3. 리스트/테이블 뷰 (데이터 있을 때)
4. 폼/입력 화면
5. 에러 상태 (의도적으로 잘못된 입력 시)

스크린샷 전달

캡처된 이미지 경로를 각 평가자 에이전트 컨텍스트에 포함한다. Puppeteer MCP가 미설치/미연결 시 경고를 출력하고 코드 분석만 수행한다:

[Nova UX Audit] Puppeteer MCP 미연결 — 스크린샷 없이 코드 분석만 수행합니다.

NOVA-STATE.md 갱신

종합 보고서 출력 직후 반드시 갱신한다:

## Last Activity
- /nova:ux-audit → Critical {N} / High {N} / Medium {N} / Low {N} — {평가 대상} | {ISO 8601}

시계열은 events.jsonl 단일 진실원 (v5.44.0+): NOVA-STATE.md의 Recent Activity / Recently Done 표에 행 추가 X. 활동 기록은 hooks/record-event.sh(자동 호출)가 .nova/events.jsonl에, v3 marker 영역은 Stop hook이 scripts/registry-render-state.sh로 자동 갱신. AI는 Current/Phase/Refs/Risks 본문 스냅샷만 손편집 — 트림 의무 없음. (상세: skills/context-chain/SKILL.md)

보안/접근성 관련 Critical 이슈 발견 시 Known Risks에도 추가:

## 알려진 위험 (Known Risks)
| 위험 | 심각도 | 상태 |
|------|--------|------|
| {WCAG 2.2 위반 / 다크 패턴 등} | {Critical/High} | 미해결 |

Notes

• 각 평가자는 반드시 독립 서브에이전트로 실행 (Agent tool, run_in_background: true)
• 5인 모두 완료될 때까지 대기 후 종합
• 평가자 에이전트에게는 코드 수정을 시키지 않는다 — 분석만 수행
• --screenshot 사용 시 Puppeteer MCP 도구 필요 (미설치 시 코드 분석 fallback)
• 각 평가자의 출력은 200단어/8건 제한 — 종합 시 확장하지 않는다