UI 일관성 리뷰
디자이너가 없으면 "기존 화면"이 디자인 기준이다. 에이전트는 화면마다 Tailwind 클래스를 새로 조합하기 때문에, 같은 역할의 UI가 화면마다 조금씩 달라진다. 이 리뷰는 그 어긋남을 잡는다. 예쁜지는 판단하지 않는다.
0. 모드
| 모드 | 대상 | blocking 대상 |
|---|---|---|
| 셀프 체크 | 내가 바꾼 화면 | 고친다 |
| 변경 리뷰 | PR이 바꾼 화면 파일과 스타일 | 이번 변경이 만든 어긋남만 |
| 점검 | 화면 전체 | 전부 |
1. 기준 읽기
-
docs/review/design.md를 찾는다. 없으면 CLAUDE.md·AGENTS.md가 가리키는 디자인 문서를 쓴다. -
기준 문서에서 가져올 것: 원칙, 토큰(색 역할, 간격, 폭, 글꼴), 공용 컴포넌트, 상태 표현(로딩, 빈 목록, 오류, 권한 없음, 성공), 문구 말투와 용어.
-
기준 문서가 없으면 기존 화면에서 뽑는다.
# 역할별로 실제 쓰인 값과 빈도 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. 보고
첫 줄: 본 범위, 기준 문서 유무, 화면을 실제로 봤는지, 건수.
항목마다:
- 제목: 어긋남을 결과로 쓴다. ("글 화면만 페이지 폭이 넓어 화면을 오갈 때 본문 위치가 바뀐다")
- 위치:
파일:줄과 비교 대상파일:줄. - 기준: 어느 규칙이나 어느 기존 화면과 어긋나는지.
- 방향: 어떤 값이나 컴포넌트로 맞출지.
- 등급. "기준 제안"이면 무엇을 기준 문서에 더할지 한 줄.