UX 품질 검사은(는) 무엇을 하나요?
변경 사항이 적용된 UI 표면들을 references/rules.md의 규칙에 대해 점검합니다. 각 규칙에는 이유, 코드 내 확인 방법, 브라우저 내 확인 방법, 수정 방법이 있습니다. 해당 파일 상단의 표는 각 규칙이 어떤 종류의 변경에 적용되는지 보여줍니다.
1. 변경 사항 찾기
- 요청된 diff를 가져옵니다: PR, 브랜치, 커밋 또는 커밋되지 않은 변경 사항. 이름이 없으면 커밋되지 않은 변경 사항을 사용합니다. 커밋되지 않은 변경 사항이 없으면 브랜치와 기본 브랜치의 병합 기준점 간 diff를 사용합니다 (
git diff $(git merge-base HEAD origin/HEAD)...HEAD). 브랜치가 기본 브랜치라면 마지막 커밋을 사용합니다. 보고서에 어떤 diff를 확인했는지 명시합니다. - 변경된 UI 파일을 나열합니다: 컴포넌트, 템플릿, 스타일, 그리고 이들이 렌더링하는 문자열과 props. 공유 컴포넌트나 토큰에 대한 변경도 UI 변경에 해당합니다.
- diff에 UI를 렌더링하는 파일이 하나도 없다면 (서버 코드, 테스트, 설정, 문서만 있다면), 한두 문장으로 그렇게 명시하고 중단합니다. 발견된 사항이 없다고 보고합니다.
2. 저장소 고유 UI 규칙 읽기 및 표면 매핑
저장소의 규칙이 카탈로그 기본값보다 우선합니다.
- 저장소의 에이전트 문서(
AGENTS.md,CLAUDE.md, 디자인 시스템 README)에서 'UI 규칙' 또는 유사한 섹션을 읽습니다. 규칙에 대해 명명된 각 컨트롤, 토큰 또는 컴포넌트를 기록합니다 (예: 다이얼로그 헬퍼, 비동기 버튼, 타입 토큰, AI 표시). 수정 방법은 해당 컴포넌트를 명명합니다. - 저장소 자체 UX 검사 방법을 찾습니다:
make ux-check또는ux:check타겟, 레이아웃 또는 접근성 스크립트, 린트 규칙, 또는 UI 규칙을 위해 소스를 스캔하는 테스트. 변경 사항을 다루는 각각을 실행하고 그 출력을 증거로 사용합니다.
그런 다음 변경된 각 파일을 사용자가 보는 표면(라우트, 뷰, 컨트롤)에 매핑합니다. 공유 컴포넌트는 이를 사용하는 각 표면에 매핑됩니다. 사용자가 찾는 방식으로 표면 이름을 지정합니다 ("리뷰 페이지, 댓글 추가 폼"). 각 표면에 대해 다음을 기록합니다:
- 종류. diff가 추가하거나 편집한
references/rules.md의 범례에 있는 각 종류로 표면에 태그를 지정합니다:write,data,form,list,control,overlay,layout,route,copy,chart,style. 새로운 호버 스타일은control및list입니다. 저장 버튼은write입니다. - 상태. 빈(empty), 로딩(loading), 보류(pending), 오류(error), 호버(hover), 포커스(focus), 선택(selected), 비활성(disabled). 대부분의 발견 사항은 작성자가 열어보지 않은 상태에 있습니다.
3. 검사 실행
각 표면에 대해, '적용 대상(Applies to)'이 표면과 종류를 공유하는 각 규칙을 실행합니다. 확인하기 전에 규칙의 섹션을 읽습니다. 건너뛴 각 규칙과 그 이유를 기록합니다.
먼저 코드를 읽습니다. 각 규칙의 '코드 내 확인' 항목은 무엇을 찾아야 하는지 알려줍니다. 이 방법으로 대부분의 결함을 잡을 수 있으며 브라우저가 필요 없습니다. 누락된 상태를 보고하기 전에 코드가 호출하는 컴포넌트(래퍼, 비동기 버튼, 폼 훅, pending을 전달하는 부모)가 이를 처리하는지 확인합니다.
그런 다음 가능할 때 브라우저에서 측정합니다. 정적 HTML 페이지는 디스크에서 file:// URL로 열립니다. 앱의 경우 실행 중인 개발 서버를 찾거나 저장소의 문서화된 명령어로 시작합니다. 호스트가 제공하는 브라우저 도구(내장 브라우저 창, Playwright 스크립트, 헤드리스 Chrome)를 사용합니다. 페이지에 로그인이 필요하면 사용자에게 해당 브라우저에서 로그인하도록 요청합니다. 자격 증명을 직접 입력하지 마십시오.
scripts/measure.js를 페이지에 로드합니다. 이 스크립트는 각 규칙의 '브라우저 내 확인' 항목이 명명하는 헬퍼 함수를 정의하며, references/rules.md에는 각 함수가 반환하는 내용이 나열되어 있습니다. 페이지를 로드할 때마다 다시 붙여넣습니다. 앱이 제공하는 각 테마와 색상 구성표, 그리고 최소한 휴대폰 너비와 데스크톱 너비에서 확인합니다.
변경된 각 행, 카드 및 컨트롤을 상호작용 상태에서도 측정합니다. 호버, 포커스 또는 선택된 상태는 종종 채우기, 테두리, 그림자 또는 컨트롤을 추가합니다. 그러면 두 개의 박스형 항목이 서로 닿거나, 항목이 커져서 이웃을 밀어내거나, 호버 시에만 나타나는 동작이 개수를 줄 밖으로 밀어냅니다. 표면의 각 목록, 카드 그룹 또는 컨트롤 그룹에 대해:
- 항목이 기본 상태일 때
snapshot(sel, "rest")및gaps(sel)을 실행합니다. - 브라우저 도구로 항목 하나를 호버한 다음,
snapshot(sel, "hover")및gaps(sel)을 다시 실행합니다. 키보드 포커스(Tab 키)로도 동일하게 수행하고, 선택된 항목 옆에 호버된 항목이 있을 때도 동일하게 수행합니다. moved("rest", "hover")를 실행합니다. 두 박스형 항목 사이의 간격이 0px이거나, 다른 항목이 호버되었을 때 항목이 이동한 경우 발견 사항입니다.
메뉴, 팝오버 또는 패널을 여는 각 작업 주변에서도 동일하게 수행합니다: 주요 블록의 스냅샷을 찍고, 열고, 다시 스냅샷을 찍어 비교합니다. 코드에서는 각 :hover, :focus-visible 및 선택된 클래스 규칙에서 상자(박스)를 추가하거나 크기를 변경하는 속성(background, border, box-shadow, padding, margin, width, display)을 읽습니다.
브라우저가 없거나 열 페이지가 없으면 코드 발견 사항을 보고하고 실행되지 않은 브라우저 검사 목록을 나열합니다.
4. 각 발견 사항 확인
발견 사항을 보고하기 전에 한 번 더 확인합니다:
- 코드 발견 사항. 사용자가 해당 상태에 도달할 수 있는지 확인합니다: 브랜치가 실행되고, prop이 전달되며, 래퍼나 부모가 이를 처리하지 않습니다.
- 브라우저 발견 사항. 새로고침 후, 발견 사항이 명명하는 상태에서 두 번째 측정합니다. 반복되지 않는 값은 제외합니다.
- 변경 사항 내부인지 이전인지. diff가 추가하거나 변경한 줄의 결함은 변경 사항에 속합니다. diff가 대응하는 상태 없이 추가한 상태(예:
:focus-visible규칙 없이 새:hover규칙, 또는 보류 상태 없이 새 쓰기 작업)도 해당 변경 사항에 속하며, 누락된 줄이 다른 곳에 있어야 하는 경우에도 마찬가지입니다. diff가 건드리지 않은 줄의 결함은 변경 이전부터 존재했던 것입니다. '기존 결함' 섹션에 변경 사항의 발견 사항과 별도로 보고하며, 변경된 표면에 있는 경우에만 보고합니다.
확인에 실패한 발견 사항은 제외합니다. 확인할 수 없었던 발견 사항은 '확인되지 않음'으로 보고하고 이유를 기재합니다.
5. 발견 사항 보고
확인한 diff와 표면을 명명하는 한 줄로 시작합니다. 그런 다음 결함당 하나의 발견 사항을 심각도가 높은 순서대로 나열합니다. 심각도:
- 높음: 사용자가 데이터나 입력을 잃거나, 중복 쓰기를 보내거나, 컨트롤에 접근할 수 없거나, 텍스트를 읽을 수 없습니다.
- 중간: 컨트롤이 오해를 불러일으키거나(잘못된 아이콘, 색상만으로 상태 표현, AI 표시 누락), 레이아웃이 눈에 띄게 깨졌습니다.
- 낮음: 저장소 시스템과의 불일치(원시 타입 값, 혼합된 선택 컨트롤, 채우기).
각 발견 사항은 네 부분으로 구성됩니다:
| 부분 | 내용 |
|---|---|
| 표면 | 뷰와 컨트롤, 파일 및 줄 (ReviewForm.tsx:42) |
| 규칙 | 카탈로그의 규칙 ID 또는 위반한 저장소 규칙 |
| 증거 | 읽거나 측정한 내용: 코드 줄, 측정값, 상태, 테마 및 너비 |
| 수정 | 한두 문장으로 된 변경 사항, 명명된 저장소의 컴포넌트 또는 토큰 포함 |
예시:
표면: 스택 사이드바, 작성자 필터 목록 (
AuthorList.tsx:58) 규칙:no-cramped-controls증거:gaps(".author-row")at 1440px, 2행 호버 시: 1행(선택됨)과 2행 사이y: 0. 기본 상태에서도 간격은 0이지만 선택된 행만 상자를 그립니다. 수정: 목록에gap: 2px를 추가하거나 호버 채우기를 2px 안쪽으로 설정합니다.
그런 다음 다음 섹션을 추가합니다:
- 기존 결함: 4단계에서 변경 사항이 도입하지 않은 결함, 각각 한 줄씩.
- 확인되지 않음: 건너뛴 규칙과 그 이유, 실행되지 않은 브라우저 검사.
사용자가 수정을 요청하면 수정한 후 동일한 표면에서 동일한 검사를 다시 실행합니다.