UI 일관성 리뷰

UI 일관성 리뷰 是做什么的？

디자이너가 없으면 "기존 화면"이 디자인 기준이다. 에이전트는 화면마다 Tailwind 클래스를 새로 조합하기 때문에, 같은 역할의 UI가 화면마다 조금씩 달라진다. 이 리뷰는 그 어긋남을 잡는다. 예쁜지는 판단하지 않는다.

0. 모드

모드	대상	blocking 대상
셀프 체크	내가 바꾼 화면	고친다
변경 리뷰	PR이 바꾼 화면 파일과 스타일	이번 변경이 만든 어긋남만
점검	화면 전체	전부

1. 기준 읽기

1. docs/review/design.md를 찾는다. 없으면 CLAUDE.md·AGENTS.md가 가리키는 디자인 문서를 쓴다.

2. 기준 문서에서 가져올 것: 원칙, 토큰(색 역할, 간격, 폭, 글꼴), 공용 컴포넌트, 상태 표현(로딩, 빈 목록, 오류, 권한 없음, 성공), 문구 말투와 용어.

3. 기준 문서가 없으면 기존 화면에서 뽑는다.

   # 역할별로 실제 쓰인 값과 빈도
   git grep -hoE "text-(red|amber|green|zinc|gray|slate)-[0-9]+" -- 'src/**/*.tsx' | sort | uniq -c | sort -rn
   git grep -hoE "max-w-[a-z0-9]+|gap-[0-9]+|px-[0-9]+|py-[0-9]+" -- 'src/**/*.tsx' | sort | uniq -c | sort -rn
   

   가장 많이 쓰인 값을 기준으로 삼고, 보고 첫 줄에 "기준 문서 없음 → 기존 화면에서 추출"이라고 적는다. 기준 문서가 없으면 내부 불일치만 blocking으로 올린다.

2. 볼 것

• 토큰: 같은 역할에 다른 값을 쓰나 (오류 색 red-600과 red-500, 페이지 폭 max-w-2xl과 max-w-3xl). 기준에 없는 새 값을 들였나.
• 컴포넌트: 같은 역할의 UI(주 버튼, 링크, 오류 문구, 빈 상태, 로딩 표시)를 공용 컴포넌트 대신 클래스 문자열을 복사해 새로 그렸나.
• 레이아웃 셸: 페이지 폭, 여백, 제목 위치, 뒤로 가기 위치가 다른 화면과 같은가.
• 상태 표현: 로딩, 빈 목록, 오류, 권한 없음, 저장 성공을 기존 화면과 같은 방식(위치, 색, 문장 구조)으로 보여 주나.
• 문구: 말투(해라체, 해요체 등)가 같은가. 같은 대상을 다른 단어로 부르지 않나. 오류 문구가 "무엇이 안 됐는지 + 무엇을 하면 되는지" 구조인가.
• 개발용 정보: 측정값, 내부 id, 해시가 사용자 화면에 나오나. 기준 문서가 허용하지 않으면 지적한다.
• 최소 접근성: 입력에 label이 있나, 상태를 색으로만 구분하지 않나, 버튼이 키보드로 닿나, 문서 언어(lang)가 화면 언어와 맞나.

3. 화면으로 확인

실행할 수 있으면 변경 전후 화면을 같은 데이터로 찍어 비교한다 (compare-output 스킬). 로그인이나 외부 자격증명이 필요해 실행할 수 없으면 코드로 판단했다고 쓴다. 실행하지 않은 화면을 본 것처럼 쓰지 않는다.

4. 판정

blocking

• 기준 문서의 규칙을 어겼다.
• 같은 역할의 UI에 기존과 다른 표현(값, 문구 구조, 위치)을 새로 들였다.
• 공용 컴포넌트가 있는데 클래스 문자열을 복사해 새로 그렸다.

suggestion

• 기준 문서가 없는 영역의 새 패턴. 기준에 추가할지 사람이 정하도록 "기준 제안"으로 적는다.
• 원래 있던 불일치.

적지 않는 것: 취향(이 색이 더 예쁘다), 기준과 상관없는 새 디자인 제안.

5. 보고

첫 줄: 본 범위, 기준 문서 유무, 화면을 실제로 봤는지, 건수.

항목마다:

• 제목: 어긋남을 결과로 쓴다. ("글 화면만 페이지 폭이 넓어 화면을 오갈 때 본문 위치가 바뀐다")
• 위치: 파일:줄과 비교 대상 파일:줄.
• 기준: 어느 규칙이나 어느 기존 화면과 어긋나는지.
• 방향: 어떤 값이나 컴포넌트로 맞출지.
• 등급. "기준 제안"이면 무엇을 기준 문서에 더할지 한 줄.